Information Catalog Manager Programming Guide and Reference

FLGListContacts

Retrieves a list of Contact objects for an Elemental or Grouping object.

Authorization

Administrator or user

Syntax

APIRET APIENTRY FLGListContacts( PSZ pszFLGID, PFLGHEADERAREA * ppListStruct, PFLGEXTCODE pExtCode );

Parameters

pszFLGID (PSZ) -- input

Points to the 16-character FLGID of the object instance for which Contacts will be retrieved.

Characters 1-6 of this ID identify the object type of this instance.

Characters 7-16 of this ID are the system-generated unique instance identifier.

ppListStruct (PFLGHEADERAREA) -- output

Points to the address of the pointer to the output structure listing the Contacts. When there is no output structure, the pointer to the structure is set to NULL.

This output structure contains the 16-character FLGID of each Contact object and its 80-character name.

Entries in the list are first sorted by object type name, then by the value of the Name property for each instance, according to the collating sequence used by the database management system used by your information catalog.

The maximum number of Contact object instances that can be returned by FLGListContacts is approximately 5000, depending on the storage available on your machine.

pExtCode (PFLGEXTCODE) -- output

Points to an extended code associated with the reason code. See Appendix D, Information Catalog Manager reason codes to see if a meaningful extended code is associated with the returned reason code.

Reason code (APIRET)

Represents the execution result of this API call.

See Appendix D, Information Catalog Manager reason codes for an explanation of the returned reason codes.

Output structure

FLGListContacts produces an output structure containing a list of Contacts, as shown in Figure 101.

The object area of the output structure contains a list of Contact object instances associated with the specified object instance. These Contact objects are identified by the value of the FLGID and the external name for each object instance.

Figure 101. FLGListContacts output structure

Usage

Freeing memory allocated for an output structure

If FLGListContacts returned data in the output structure, you must save the data returned in the output structure and then call FLGFreeMem (see FLGFreeMem). Do not use other methods, for example, C language instructions, to free memory.

Examples

Figure 102 shows the C language code required to invoke the FLGListContacts API call. This sample code retrieves a list of the Contacts for Elemental object MYREPORT.

Figure 102. Sample C language call to FLGListContacts

APIRET rc; // reason code from FLGListContacts UCHAR pszFLGID[FLG_ID_LEN + 1]; PFLGHEADERarea * ppListStruct; // pointer to output structure pointer FLGEXTCODE ExtCode=0; // extended code . . /* allocate storage for input parms */ . /* set objid to FLGID of 'MYREPORT' */ . rc = FLGListContacts (pszFLGID, ppListStruct, // address of output structure pointer &ExtCode);

Figure 103 shows the output structure for this API call.

Figure 103. Sample output structure for FLGListContacts