Information Catalog Manager Programming Guide and Reference

FLGFoundIn

Retrieves a list of object instances or object types in which a specified instance is found. FLGFoundIn can retrieve any of the following:

• Grouping object instances that contain the specified object instance
• Object instances for which the specified object instance is a Contact
• Object instances to which the specified object instance is attached as a Comments object
• Object types with which the specified Programs object instance is associated

Authorization

Administrator or user

Syntax

APIRET APIENTRY FLGFoundIn( PSZ pszFLGID, FLGOPTIONS Options, PFLGHEADERAREA * ppListStruct, PFLGEXTCODE pExtCode );

Parameters

pszFLGID (PSZ) -- input

Points to the 16-character object instance ID (FLGID) of the object instance for which a list of parents 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.

The FLGID you specify depends on what you want to list:

Attachments

FLGID of an Attachment category object instance (retrieves object instances to which the specified object instance is attached as a Comments object).

Contacts

FLGID of a Contact category object instance (retrieves object instances for which the specified object instance is a Contact).

Containees

FLGID of an Elemental or Grouping category object instance (retrieves Grouping object instances that contain the specified object instance)

Programs

FLGID of a Program category object instance (retrieves object types with which the specified Programs object instance is associated)

Options (FLGOPTIONS) -- input

Choose one of the following options:

FLG_LIST_ATTACHMENT

Retrieves object instances to which the specified object instance is attached as a Comments object

FLG_LIST_CONTACT

Retrieves object instances for which the specified object instance is a Contact

FLG_LIST_CONTAIN

Retrieves Grouping object instances that contain the specified object instance

FLG_LIST_PROGRAM

Retrieves object types with which the specified Programs object instance is associated

ppListStruct (PFLGHEADERAREA) -- output

Points to the address of the pointer to the output structure containing a list of object instances or object types in which a specified instance is found. If there is no output structure, then the pointer to the output structure is set to NULL.

For each Contain, Contact, or Attachment relationship, the output structure contains the following information about the "found-in" object instances:

• FLGID (16 characters)
• Name (80 characters)

All instances are sorted by object type name first, then object instance name, in ascending order according to collating order of the underlying database management system.

For each Program association, the output structure contains the following information about the "found-in" object types:

• Object type ID (6 characters)
• 80-character external name of object type (EXTERNAL NAME OF OBJ TYPE)

All object types are sorted by the 80-character external name of object type (EXTERNAL NAME OF OBJ TYPE) in ascending order according to collating order of the underlying database management system.

The maximum number of object instances or object types that can be returned by FLGFoundInis 5000.

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.

Usage

Freeing memory allocated for an output structure

If FLGFoundIn 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

This sample code retrieves a list of object instances in which the specified Contact object is found. Figure 68 shows the C language code required to issue the FLGFoundIn call.

Figure 68. Sample C language call to FLGFoundIn

APIRET rc; // reason code from FLGFoundIn UCHAR pszInstID[FLG_ID_LEN + 1]; FLGOPTIONS Option=0; // association type PFLGHEADERAREA * ppReturnObjList; // pointer to output structure ptr FLGEXTCODE xc=0; // extended code . . /* provide values for input parameters */ . Option = Option | FLG_LIST_CONTACT; rc = FLGFoundIn (pszInstID, Option, ppReturnObjList, &xc);

Figure 69 shows the output structure for the FLGFoundIn call.

Figure 69. Sample output structure for FLGFoundIn

This sample code retrieves a list of object types handled by the specified Programs object instance. Figure 70 shows the C language code required to issue the FLGFoundIn call.

Figure 70. Sample C language call to FLGFoundIn

APIRET rc; // reason code from FLGFoundIn UCHAR pszInstID[FLG_ID_LEN + 1]; FLGOPTIONS Option=0; // association type PFLGHEADERAREA * ppReturnObjList; // pointer to output structure ptr FLGEXTCODE xc=0; // extended code . . /* provide values for input parameters */ . Option = Option | FLG_LIST_PROGRAM; rc = FLGFoundIn (pszInstID, Option, ppReturnObjList, &xc);

Figure 71 shows the output structure for the FLGFoundIn call.

Figure 71. Sample output structure for FLGFoundIn