REG_ENUM_KEY, DISPLAY_REG_ENUM_KEY

Enumerates subkeys of a specified open registry key. REG_ENUM_KEY retrieves the name of one subkey each time it is called.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.

Use DISPLAY_REG_ENUM_KEY to perform the action on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_ENUM_KEY to perform the action on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_ENUM_KEY" 
    USING OPEN-KEY-HANDLE, NDX, SUBKEY-NAME, NAME-SIZE,
    GIVING STATUS-CODE

Parameters

OPEN-KEY-HANDLE Usage unsigned-long Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

The keys enumerated by REG_ENUM_KEY are subkeys of the key identified by OPEN-KEY-HANDLE.

NDX Numeric data item Specifies the index of the subkey to retrieve. NDX should be set to '1' for the first call to REG_ENUM_KEY and then incremented for subsequent calls. The subkeys are not returned in any particular order.
SUBKEY-NAME PIC X(n) Receives the name of the subkey. REG_ENUM_KEY copies only the name of the subkey, not the full key hierarchy, to the SUBKEY-NAME buffer.
NAME-SIZE Numeric data item Specifies the size, in characters, of the SUBKEY-NAME buffer.
STATUS-CODE Numeric data item. Receives the return status of the call to Microsoft's RegEnumKey function. A return status of zero indicates success; non-zero indicates that an error occurred.

Comments

To enumerate subkeys, your application should initialize the NDX parameter to 1 and call REG_ENUM_KEY repeatedly, incrementing NDX each time, until there are no more subkeys. You can tell that there are no more subkeys when the function returns a non-zero STATUS-CODE (259 for 32-bit Windows).

While an application is using REG_ENUM_KEY, it should not make calls to any registry routines that might change the key being queried.

If the subkey name exceeds the size of the SUBKEY-NAME buffer (as specified by the NAME-SIZE parameter), the result depends on the operating system. Under 32-bit Windows, a STATUS-CODE of 234 is returned.

Compatibility Issues

  • REG_ENUM_KEY is a Windows-only routine.
  • DISPLAY_REG_ENUM_KEY is not supported.
  • acugui.def is not supplied in this COBOL system.
  • Thin client technology is not supported in this COBOL system.