You must follow certain rules and guidelines when you write C language programs that contain the Information Catalog Manager API calls. These guidelines are explained in this section.
When you write a program that issues the Information Catalog Manager API calls, you must issue an FLGInit call before you can issue any other Information Catalog Manager API calls.
FLGInit initializes the Information Catalog Manager, returns the names of properties required for the Information Catalog Manager object types and registrations, and returns environmental information.
Save the information returned by FLGInit. You might need this information for other Information Catalog Manager API calls. If you are using a national language version of the Information Catalog Manager, FLGInit returns the translated names of the properties required for the Information Catalog Manager object types and registrations. You need to use these translated names in the definition area of your input structure when you create or maintain object types and registrations.
See FLGInit for information about the contents of the FLGInit output structure.
Your program must issue an FLGTerm call after it finishes using the Information Catalog Manager functions. FLGTerm ends the Information Catalog Manager session and releases resources used by the Information Catalog Manager. See FLGTerm for more information about this API call.
Certain Information Catalog Manager errors indicate that some of the metadata in the database on which your information catalog resides might be inconsistent. Therefore, you should write your program to roll back the information catalog database when your program encounters errors. By issuing FLGCommit calls when your API calls succeed and FLGRollback calls when they fail, you protect your information catalog database from becoming inconsistent.
Attention: When your information catalog database is on DB2 you must issue an FLGRollback call if you encounter an error. Otherwise, your information catalog database may be damaged when your program issues FLGTerm.
To start a program that works with your data from an Information Catalog Manager application, create a Programs object instance that is associated with the object type that represents that kind of data.
You must define values for three properties in the Programs object instance
that identify the program and associate the Programs object instance with an
object type, as shown in Table 5.
Table 5. Properties of a Programs object instance that start the program
| Property name | Property short name | Value |
|---|---|---|
| Start by invoking | STARTCMD | Path and file name of the program to be started, as well as the start options. |
| Object type this program handles | HANDLES | 8-character short name of the object type |
| Parameter list is | PARMLIST | List of properties in the associated object type the values of which you want to pass to the program as command-line parameters. Each property is delimited by two percent signs (%%) |
The value of the Start by invoking (STARTCMD) property has different recommended formats, depending on the program's interface type. Enter the file name of the program and the recommended starting parameters. For Windows NT(R), Windows 95, and Windows 98, the recommended starting parameter is START filename.exe. The PATH statement must contain the directory where the program is located.
If the file name of the program is in high-performance file system (HPFS) format and contains blanks, then you must surround the path and file name of the program with double quotes, as shown below:
""D:\PROGPATH\My Program.EXE""
If your program name contains blanks, then you cannot specify any other start options in the STARTCMD property value.
To start a program, issue an FLGOpen call with the Programs object FLGID and object instance FLGID as parameters. For more information about the FLGOpen call, see FLGOpen.
The registration, object type, object instances, and relationships build upon one another; therefore, you can only create a set of these entities in a certain order. When creating new object types, object instances, and relationships, you must issue the Information Catalog Manager API calls in the following order:
You can, however, delete registration, object type, object instances, and relationships in two manners: conservative (this method is slower), or potentially destructive (yet quicker).
When deleting object types and object instances in a conservative manner, issue the following the Information Catalog Manager API calls for related object instances and object types in the following order:
You must delete all relationships where the particular object instances are containers of other objects before you can delete these object instances. FLGDeleteInst automatically deletes relationships where object instances are contained or have associated Contact, Attachment, or linked objects.
You must delete all object instances of a particular object type before you can delete the object type using FLGDeleteType.
You can delete object instances and object types more quickly using the following APIs, but if you are not completely certain of your information catalog's contents, the results can be destructive.
Simultaneously delete a Grouping object instance and, optionally, all object instances it contains as well as all relationships in which the contained object instances participate.
Simultaneously delete the object type, object type registration, and all instances of the object type. You must delete individual branches containing objects of other object types before you can delete the object type using FLGDeleteTypeExt.
The Information Catalog Manager stores the metadata for an object's properties using four data types, which are defined in Table 6.
Your program may need to make some data conversions to ensure that your
metadata is in a valid format.
Table 6. Valid data types for information catalog metadata
| Data type | How represented | How an omitted value is represented in input and output structures |
|---|---|---|
| CHAR | Occupies its defined length. The value is padded on the right with trailing blanks if the value is shorter than its defined length. | Blanks fill up the value's defined length. |
| TIMESTAMP | Occupies its full length (26) using the following format: yyyy-mm-dd-hh.mm.ss.nnnnnn | Represented by 26 blanks. |
| LONG VARCHAR | Preceded by an 8-character length field that specifies the actual length of the following value. | Length field is set to zeros that specifies that no value follows. Example: 00000000 |
| VARCHAR | Preceded by an 8-character length field that specifies the actual length of the following value. | Length field set to zeros that specifies that no value follows. Example: 00000000 |
With input structures, the Information Catalog Manager automatically removes trailing blanks from variable-length values and adjusts their lengths accordingly before validating and accepting the request. Therefore, if only blanks are specified for a required value, the request is rejected with a reason code indicating that a required value was not specified. When a value is required, but not available, you can use the not-applicable symbol to avoid errors.