Open topic with navigation

TIBCO® Patterns 6.1.2

# Building the Input: lpars

An lpar is a value and an integer code, called the lpar ID, that identifies the value's data type. Lpar ID's are predefined in the header file `devkit.h`. Here is a partial listing of that file:

    enum lparid_en {
            /* ... */
            LPAR_STR_DBDESCRIPTOR,     /* Database name */
            LPAR_STR_LAYOUT,           /* Layout name - deprecated*/
            /* ... */
            LPAR_INTARR_SELECTFLDS,     /* Indexes of fields to search */
            LPAR_INT_ALIGNFIELD,        /* Initial alignment field IN FIELDSET */
            LPAR_BLK_SEARCHQUERY,       /* Search query */
            LPAR_LST_MULTIQUERY,        /* Multi-query */
            /* ... */
    };

In this example, you created a string lpar, a Boolean lpar, a signed integer lpar, a list lpar, and a byte block lpar. Lpar creator functions always have the form `lpar_create_<``` `>`, where <`type`> is the value type of the lpar. See the header file listing in Table of DevKit Error Codes and Strings for prototypes of the creator functions for the lpar types.

Each of the enum identifiers shown above is an lpar ID. The second component of the identifier part between the two underscores represents the type of the value. For example, the ID LPAR_INT_ALIGNFIELD takes an integer value; the ID LPAR_STR_DBDESCRIPTOR takes a null-terminated character string as a value. Creating an lpar with a value that does not agree with its lpar id is a programming error.

Here is a list of all lpar value types used in the DevKit, with the corresponding enum prefixes (additional types used internally that are not used in the interface):

LPAR value types used in the DevKit

Lpar value type | Id macro prefix
Boolean (true/false) | LPAR_BOOL_`<name>`
signed integer | LPAR_INT_`<name>`
array of signed integers | LPAR_INTARR_`<name>`
double-precision oat | LPAR_DBL_`<name>`
array of double-precision oats | LPAR_DBLARR_`<name>`
Null-terminated character string | LPAR_STR_`<name>`
array of null-terminated character strings | LPAR_STRARR_`<name>`
byte block | LPAR_BLK_`<name>`
array of byte blocks | LPAR_BLKARR_`<name>`
list of more lpars | LPAR_LST_`<name>`

You assign a value to an lpar when you create it. Call the lpar creator function for the value type, passing it the lpar id and the value.

Note: The null-terminated string values of LPAR_STR_ and LPAR_STRARR must never contain a new-line character. A byte block however might contain any character, including new-line characters.
Note: You cannot initialize the value of a list type lpar. It is created empty and must be filled later.

The creator function returns a new lpar containing the value you specified. The following is an example of this:

    typedef unsigned char UCHAR;
    /* ... */
    {
        int        querylen, nfields;
        UCHAR      *query;
        lpar_t     lpar1, lpar2, lpar3, lpar4;
        /* ... */
        query = malloc(querylen);
        /* ... initialize the query here ... */
        lpar1 = lpar_create_str(LPAR_STR_DBDESCRIPTOR, (UCHAR *)"My Database");
        lpar2 = lpar_create_int(LPAR_INT_DBNUMFIELDS, nfields);
        lpar3 = lpar_create_lst(LPAR_LST_QUERYLET);
        lpar4 = lpar_create_blk(LPAR_BLK_SEARCHQUERY,query,querylen);
        /* ... pass lpars as input to a command function ... */
    lpar_destroy(lpar1);
    lpar_destroy(lpar2);
    lpar_destroy(lpar3);
    lpar_destroy(lpar4);
        free(query);
    }

In this example, you created a string lpar, a Boolean lpar, a signed integer lpar, a list lpar, and a byte block lpar. Lpar creator functions always have the form `lpar_create_<``type``>`, where <type> is the value type of the lpar. See the devkit.h file in TIBCO Patterns installation for prototypes of the creator functions for the lpar types.

After creating an lpar, you can access its integer id with the function lpar_id. See examples of this in the section on DevKit output. The function lpar_value_type returns the value type of an lpar:

        lpar_t         lpar;
        lpar_type_t    type;
        /* ... */
        type = lpar_value_type(lpar);

The type returned by `lpar_value_type` can be any one of the following:

| • | LPAR_TYPE_BOOL (boolean)

| • | LPAR_TYPE_INT (32-bit, integer)

| • | LPAR_TYPE_INTARR (array of integers)

| • | LPAR_TYPE_LONG (64-bit, integer)

| • | LPAR_TYPE_DBL (double)

| • | LPAR_TYPE_DBLARR (array of doubles)

| • | LPAR_TYPE_STR (nul-terminated, string)

| • | LPAR_TYPE_STRARR (array of strings)

| • | LPAR_TYPE_LST (list of lpars)

| • | LPAR_TYPE_BLK (byte block)

| • | LPAR_TYPE_BLKARR (byte block array)

| • | LPAR_TYPE_RN

Since lpar objects are allocated by the DevKit dynamically, their storage must be released after use. The function `lpar_destroy` releases an lpar of any value type. When you create`lpar4`, it is initialized with a copy of the byte block query.

Note: The same holds for lpars containing integer arrays, double-precision arrays, and strings.

Using `lpar_destroy` to destroy `lpar4` does not remove the need to free query.

Most DevKit commands expect list type lpars as parameters. Non-list lpars are usually created to be attached to one or more lists, which are then passed to DevKit commands.

Typically, create a list lpar first, and then the member lpars, appending each lpar to the list. The following is an example of this:

    typedef unsigned char UCHAR;
    * ... */
    {
        int        querylen;
        UCHAR      *query;
        lpar_t     lpar, lpar2;
        lpar_t    list1, list2;
        /* ... */
        list1 = lpar_create_lst(LPAR_LST_GENERIC);
        lpar = lpar_create_str(LPAR_STR_DBDESCRIPTOR, (UCHAR *)"My Database");
    lpar_append_lst(list1, lpar);
        lpar = lpar_create_int(LPAR_INT_DBNUMFIELDS, 4);
    lpar_append_lst(list1, lpar);
        list2 = lpar_create_lst(LPAR_LST_GENERIC);
        lpar = lpar_create_lst(LPAR_LST_QUERYLET);
        lpar2 = lpar_create_blk(LPAR_BLK_SEARCHQUERY,query);
    lpar_append_lst(lpar, lpar2); /* Put the query in the querylet */
    lpar_append_lst(list2, lpar);
        /* ... Pass the lists to a command function ... */
    lpar_destroy(list1);
    lpar_destroy(list2);
        free(query);
                                        }

In this realistic example, the code is compact and simpler. Rather than declaring lpar variables one by one, declare two temporary lpars and reuse them after adding each lpar to a list. Then pass the lists to a command function.

Note: If an lpar is appended to a list that already contains one or more lpars with the same lpar ID, and only one lpar of that ID is expected, the value of the most recently added lpar supersedes that of previous instances of that lpar ID.

To clean up, destroy the lists and free query, if it was dynamically allocated. Destroying a list destroys all lpars in that list. When you `lpar_destroy` a list, all its elements are destroyed recursively. Do not add an lpar to more than one list, or destroy it while it is a member of a list. When you need to add an lpar to more than one list, copy it with the function `lpar_copy`(lpar) and add the copy.

Did you find this helpful?

Yes No
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO® Patterns

Copyright © 2010-2025. Cloud Software Group, Inc. All Rights Reserved.