Information Catalog Manager Programming Guide and Reference

The Information Catalog Manager API output structure

Figure 24 shows the general format of the Information Catalog Manager API output structure. The output structure consists of three contiguous areas: the header area, the definition area, and the object area. Some Information Catalog Manager API calls (for example, FLGGetType) produce only the first two areas.

When your program calls an API call that produces an output structure, it passes a pointer to a null pointer as a parameter. The API call then assigns the address of the output structure to the null pointer.

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 FLGFreeMem, see FLGFreeMem.

Figure 24. API output structure

The following API calls produce output structures to return data:

FLGDeleteTree: Returns a list of deleted object instances
FLGFoundIn: Returns a list of instances or object types in which a specified instance is found
FLGGetInst: Gets information about an object instance
FLGGetReg: Gets the information for an object type registration
FLGGetType: Gets information about an object type
FLGInit: Allocates required resources and initializes the Information Catalog Manager client
FLGListAnchors: Returns a list of the instances of the Grouping objects that are not contained by other objects; these top-level Grouping objects are referred to as anchors.
FLGListAssociates: Returns a list of the associate instances for a specified instance or object type
FLGListContacts: Returns a list of all Contact object instances for a specified instance
FLGListObjTypes: Returns a list of all object types
FLGListOrphans: Returns a list of instances for a specified object type that are not currently associated with any other instances
FLGListPrograms: Returns a list of all Program objects
FLGManageCommentStatus: Updates the list of available status choices for comments
FLGManageUsers: Updates the administrators and users for an information catalog and identifies extent of each user's authority
FLGNavigate: Returns a list of the Grouping or Elemental objects that the specified Grouping object contains
FLGSearch: Returns a list of the instances of a specific object type that meet the selection criteria
FLGSearchAll: Returns a list of the instances of any object type that meet the selection criteria
FLGWhereUsed: Returns a list of the Grouping objects that contain the specified object

Header area -- always present

The header area describes the information in the definition and object areas. The byte-offset positions of the header area are shown in Figure 25 and described in Table 12.

Figure 25. Output structure header area

Table 12. The output structure header area and its fields

Section from Figure 25 Byte offset Present? Description
FLG-HEAD 0-7 Always Structure identifier.
definition length 8-15 Always Length of the definition area.
Value is a multiple of 160 (number of properties times the length of each definition record).
object length 16-23 Always Length of the object area.
If no data is returned, then the length of the object area is zero (00000000).
obj area entry count 24-31 Always Number of individual property values entered in the object area.
Value is the number of properties in the definition area times the number of sets of values described in the object area.
If no data is returned, then the length of the object area is zero (00000000).
cat 32 Present with:

FLGGetInst
FLGGetReg
FLGGetType
Category of the object type or object.
Valid values are:

G
Grouping
E
Elemental
C
Contact
P
Program
D
Dictionary
S
Support
A
Attachment

object type id 33-38 Present with:

FLGGetInst
FLGGetReg
FLGGetType
System-generated identifier for an object type.

39-159 Always Should be left blank.

Section from Figure 25	Byte offset	Present?	Description
FLG-HEAD	0-7	Always	Structure identifier.
definition length	8-15	Always	Length of the definition area. Value is a multiple of 160 (number of properties times the length of each definition record).
object length	16-23	Always	Length of the object area. If no data is returned, then the length of the object area is zero (00000000).
obj area entry count	24-31	Always	Number of individual property values entered in the object area. Value is the number of properties in the definition area times the number of sets of values described in the object area. If no data is returned, then the length of the object area is zero (00000000).
cat	32	Present with: FLGGetInst FLGGetReg FLGGetType	Category of the object type or object. Valid values are: G Grouping E Elemental C Contact P Program D Dictionary S Support A Attachment
object type id	33-38	Present with: FLGGetInst FLGGetReg FLGGetType	System-generated identifier for an object type.
	39-159	Always	Should be left blank.

Definition area -- always present

The definition area contains a set of property definitions produced as output values by a particular Information Catalog Manager API function.

Table 13 shows the meaning of the definition area for the API calls that produce output structures.

Table 13. The meaning of the definition area for different API calls

API calls Information in the definition area

FLGGetInst
FLGGetReg
FLGGetType
FLGDeleteTree

Definition of the set of properties that define the object registration, object type, or object instance
FLGInit Information about the Information Catalog Manager environment

FLGFoundIn
FLGListAnchors
FLGListAssociates
FLGListContacts
FLGListObjTypes
FLGListOrphans
FLGListPrograms
FLGManage-
CommentStatus
FLGManageUsers
FLGNavigate
FLGSearch
FLGSearchAll
FLGWhereUsed

Definition of the set of properties that describe each item returned by one of these API calls

API calls	Information in the definition area
FLGGetInst FLGGetReg FLGGetType FLGDeleteTree	Definition of the set of properties that define the object registration, object type, or object instance
FLGInit	Information about the Information Catalog Manager environment
FLGFoundIn FLGListAnchors FLGListAssociates FLGListContacts FLGListObjTypes FLGListOrphans FLGListPrograms FLGManage- CommentStatus FLGManageUsers FLGNavigate FLGSearch FLGSearchAll FLGWhereUsed	Definition of the set of properties that describe each item returned by one of these API calls

Figure 26 shows the byte-offset positions for a record in the definition area.

Figure 26. A record in the definition area

Each property in the set is defined by a set of formatted specifications, as described in Table 14.

Table 14. The output structure definition area and its fields

Section from Figure 26 Byte offset Present? Description
property name 0-79 Always External name
datatype 80-109 Always The data type of the property.
Valid values are:

CHAR
Fixed-length character data. Maximum length is 254.
VARCHAR
Variable-length character data. Maximum length is 4000.
LONG VARCHAR
Variable-length character data. Maximum length is 32700.
TIMESTAMP
Time stamp in the form of: yyyy-mm-dd-hh.mm.ss.nnnnnn Timestamp length is 26.

length 110-117 Always Maximum length of the property value in the object area.
ppn 118-125 Present with:

FLGGetInst
FLGGetReg
FLGGetType
FLGManage- CommentStatus
For other API calls, this field is unused and left blank Property short name
vf 126 Present with:

FLGGetInst
FLGGetReg
FLGGetType
For other API calls, this field is unused and left blank Value flag specifying whether a property is required, optional, or system-generated.
Valid values are:

R
Required
O
Optional
S
System-generated

us 127 Present for the following API calls:

FLGGetInst
FLGGetType
For other API calls, this field is unused and left blank Universal Unique Identifier (UUI) sequence number that specifies that a property is part of the UUI.
Valid values are:

1
UUI Part 1
2
UUI Part 2
3
UUI Part 3
4
UUI Part 4
5
UUI Part 5
(blank)
Not part of the UUI

See the Information Catalog Manager Administration Guide for more information about UUI parts.

128-159 Always Reserved section.
Is left blank.

Section from Figure 26	Byte offset	Present?	Description
property name	0-79	Always	External name
datatype	80-109	Always	The data type of the property. Valid values are: CHAR Fixed-length character data. Maximum length is 254. VARCHAR Variable-length character data. Maximum length is 4000. LONG VARCHAR Variable-length character data. Maximum length is 32700. TIMESTAMP Time stamp in the form of: `yyyy-mm-dd-hh.mm.ss.nnnnnn` Timestamp length is 26.
length	110-117	Always	Maximum length of the property value in the object area.
ppn	118-125	Present with: FLGGetInst FLGGetReg FLGGetType FLGManage- CommentStatus For other API calls, this field is unused and left blank	Property short name
vf	126	Present with: FLGGetInst FLGGetReg FLGGetType For other API calls, this field is unused and left blank	Value flag specifying whether a property is required, optional, or system-generated. Valid values are: R Required O Optional S System-generated
us	127	Present for the following API calls: FLGGetInst FLGGetType For other API calls, this field is unused and left blank	Universal Unique Identifier (UUI) sequence number that specifies that a property is part of the UUI. Valid values are: 1 UUI Part 1 2 UUI Part 2 3 UUI Part 3 4 UUI Part 4 5 UUI Part 5 (blank) Not part of the UUI See the Information Catalog Manager Administration Guide for more information about UUI parts.
	128-159	Always	Reserved section. Is left blank.

Object area -- Present when retrieving information

The object area contains the values for the properties defined in the definition area. The values appear in the order defined in the definition area.

The object area is included in the output structure for the following API calls:

FLGDeleteTree

FLGFoundIn

FLGGetInst

FLGGetReg

FLGInit

FLGListAnchors

FLGListAssociates

FLGListContacts

FLGListObjTypes

FLGListOrphans

FLGListPrograms

FLGManageCommentStatus

FLGManageUsers

FLGNavigate

FLGSearch

FLGSearchAll

FLGWhereUsed

You can determine the size of each value using the following rules:

Data type: Rules for value size
VARCHAR: Value is preceded by an 8-character length field that specifies the actual length of the value.
LONG VARCHAR: Value is preceded by an 8-character length field that specifies the actual length of the value.
CHAR: Value occupies the number of bytes defined by the property's length field in the definition area and is padded on the right with blanks to fill the defined length.
TIMESTAMP: 26 bytes.

[ Top of Page | Previous Page | Next Page ]