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.

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.

 

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.

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.