Information catalog API calls receive input and provide output using two mechanisms: parameters and input structures and output structures.
You can use parameters to provide single input values and pointers to output values and data structures.
All API call parameters that are character strings must be passed as strings terminated by a null character, or null-terminated strings. Under the Syntax section for each API call in Chapter 5, The Information Catalog Manager API call syntax, the descriptions for such parameters specify the maximum length of the actual data without the null terminator. For example, the length of an object type identifier, ObjTypeID, is specified as 6, not 7.
However, the C declarations for such parameters in the examples include the extra byte for the null terminator. For example, if you use the #define constants in the DG2API.H file, a possible declaration for the ObjTypeID parameter is:
uchar objtypid[FLG_OBJTYPID_LEN+1]
(See Appendix B, The Information Catalog Manager API header file--DG2APIH for a list of the constants in the DG2API.H file.)
To provide multiple values of input and receive multiple values of output from the Information Catalog Manager API calls, you need to use input structures and output structures.
Input structures and output structures are self-defining data structures; each structure defines the format and meaning of the data that it is passing.
Each self-defining structure must be a contiguous area of storage. Input structures and output structures contain only character data, and cannot contain nulls.
Each input structure and output structure must contain these two areas:
Structures that define or receive values for the properties defined in the definition area must also contain an object area, which specifies values for the properties defined in the definition area. Figure 3 shows how these three areas are put together.
Figure 3. An input or output structure
|
To pass an input structure to an API call, build the input structure and pass a pointer to the beginning of the input structure as an input parameter for the API call.
To retrieve information from an output structure, pass the address of a null pointer as an input parameter so that the Information Catalog Manager can assign that pointer the address of the beginning of the output structure.
For example, when you pass the API call a pointer named ppListStruct, which contains the address of a null pointer named pOutStruct, the API call then assigns pOutStruct the address of the output structure, as shown in Figure 4.
Figure 4. A pointer to an output structure
 |
To avoid running out of memory after several API calls, your program can deallocate the memory allocated for this output structure using the Information Catalog Manager API call FLGFreeMem. For more information about using FLGFreeMem, see FLGFreeMem.