Information Catalog Manager Programming Guide and Reference

FLGGetInst

Retrieves a single object instance for a specified object type.

Authorization

Administrator or user

Syntax

APIRET APIENTRY FLGGetInst( PSZ pszFLGID, PFLGHEADERAREA * ppObjInstStruct, PFLGEXTCODE pExtCode );

Parameters

pszFLGID (PSZ) -- input

Points to the 16-character, system-generated unique identifier of the object instance to 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.

ppObjInstStruct (PFLGHEADERAREA) -- output

Points to the address of the pointer to the output structure. This pointer is set to NULL if FLGGetInst fails.

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

FLGGetInst produces an output structure containing the property specifications and values of the requested object instance, as shown in Figure 73.

The object area of the output structure contains the values of the properties of the requested object instance.

Figure 73. FLGGetInst output structure

For an explanation of the meanings of the byte offsets, see The Information Catalog Manager API output structure.

Usage

Prerequisites

The value in the pszFLGID input parameter must refer to an existing object instance.

Freeing memory allocated for an output structure

If FLGGetInst 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.

Controlling updates to your information catalog

FLGGetInst commits changes to the database. Your program should issue FLGCommit or FLGRollback before issuing FLGGetInst to ensure that the Information Catalog Manager does not also commit unexpected changes that occurred before the FLGGetInst call.

Examples

Figure 74 shows the C language code required to invoke the FLGGetInst API call. This sample code retrieves information about the Quality Group object instance.

Figure 74. Sample C language call to FLGGetInst

APIRET rc; // Declare reason code UCHAR pszFLGID[FLG_ID_LEN+1]; // Unique ID for "Quality Group" PFLGHEADERAREA * ppObjInstStruct; // Pointer to the output structure FLGEXTCODE ExtCode = 0; // Declare extended code . . /* Retrieving an object Instance */ . strcpy (pszFLGID,"0000330000001234"); rc = FLGGetInst (pszFLGID, // Instance ID ppObjInstStruct, // Structure pointer where output will be returned &ExtCode); // Pass pointer to extended code

Figure 75 shows the output structure that contains the property and value information for the object instance.

Figure 75. Sample output structure for FLGGetInst