Information Catalog Manager Programming Guide and Reference

FLGUpdateReg

Modifies registration information in the information catalog for a specific object type.

This action does not update the object type itself; it updates the registration information for the object type.

Authorization

Administrator

Syntax

APIRET APIENTRY FLGUpdateReg( PFLGHEADERAREA pObjRegStruct, PSZ pszIconFileID, PFLGEXTCODE pExtCode );

Parameters

pObjRegStruct (PFLGHEADERAREA) -- input

Points to the input structure that contains the property specifications and values of the object type registration being updated.

pszIconFileID (PSZ) -- input

Contains the drive, directory path, and file name of the file that contains the OS/2 ICON for the object type registration being updated. If this parameter is NULL, then no change is made to the ICON. If specified, the OS/2 ICON is added to the object type registration if an ICON does not currently exist or replaces any existing ICON for the registration.

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.

Input structure

To use FLGUpdateReg, you must define the input structure shown in Figure 157. This structure contains only the header area and the definition area.

Figure 157. FLGUpdateReg input structure

Usage

Restrictions

• The registration information stored in the information catalog by FLGCreateReg consists of registration values, such as DP NAME, Physical Type Name, External Name, and Icon, which describe the object type. FLGUpdateReg can only update the External Name and Icon information.
• You can only update an OS/2 icon using FLGUpdateReg. To update a Windows icon, use FLGManageIcons (see FLGManageIcons).
• After you define the object type using FLGCreateReg, you can issue FLGUpdateReg or FLGManageIcons calls to change the icon that is associated with the object type, or add an icon association if one was not defined originally. You can also use FLGManageIcons to remove an icon from an object type.

Prerequisites

Before issuing an FLGUpdateReg call, you must obtain the current values of the registration information. You can either save this information from the original FLGCreateReg call, or issue an FLGGetReg call for the object type registration being modified.

Input requirements

Header area

All of the information shown in the header record is required.

Definition area

• The definition area must contain definitions for each of the six registration properties. The definitions for each of these registration properties are fixed, and all specifications other than those for the property name must be exactly as shown in Figure 157. The property name is also fixed, but might be translated from the English property name illustrated in the example into any one of the supported languages.
• The properties (as identified by their property short names) must be specified in the following order in the definition and object area:
  1. NAME
  2. PTNAME
  3. DPNAME
  4. CREATOR
  5. UPDATEBY
  6. UPDATIME

  These properties are explained in FLGCreateReg.

Object area

Only the value for NAME (EXTERNAL NAME OF OBJ TYPE) can be updated. The NAME value must be unique within the local information catalog.

The remaining property values cannot be modified. CREATOR, UPDATEBY, and UPDATIME are system-generated values. DPNAME and PTNAME are the unique identifiers of the object type, and cannot be updated. Values for system-generated properties are generated when the object type itself is created or appended.

The value for DPNAME must be specified and match the DPNAME of the current object registration associated with the object type ID in the header area.

Controlling updates to your information catalog

To keep your program as synchronized as possible with your information catalog, you should include a call to FLGCommit (see FLGCommit) after FLGUpdateReg completes successfully. If FLGUpdateReg does not complete successfully, you should include a call to FLGRollback (see FLGRollback).

Examples

Figure 158 shows the C language code required to invoke the FLGUpdateReg API call. This sample code updates the object type registration for the MYIMAGE object type. The update modifies the value for the external name property, NAME.

Figure 158. Sample C language call to FLGUpdateReg

APIRET rc; // Declare reason code PFLGHEADERAREA pObjRegStruct; // Pointer to the input structure UCHAR pszIconFileID[FLG_ICON_FILE_ID_MAXLEN+1]; // Path/File name of ICON FLGEXTCODE ExtCode=0; // Declare extended code . . /* updating pObjRegStruct object type */ /* registration by providing an updated input structure */ . strcpy (pszIconFileID,"Y:\\FLGICON2.ICO"); rc = FLGUpdateReg (pObjRegStruct, // Pointer to updated Input Structure pszIconFileID, // Path/File name of file containing the ICON &ExtCode); // Pass pointer to extended code

Figure 159 shows the input structure (pointed to by the pObjRegStruct pointer in the C code) that carries the property and value information for the object type registration information to be updated.

Figure 159. Sample input structure for FLGUpdateReg

In this example, the values in the object areas corresponding to system-generated properties (CREATOR, LAST CHANGED BY, and LAST CHANGED DATE AND TIME) cannot be updated and are ignored by FLGUpdateReg. One way of generating the input structure is to issue FLGGetReg to get the current definition and values and use the output structure from that API call as a template for this FLGUpdateReg input structure.

Bytes 33 through 38 of the header area contain the object type ID (000044) of the object type for which registration information is being updated.