REG_ENUM_VALUE, DISPLAY_REG_ENUM_VALUE

Enumerates the values of a specified registry key. REG_ENUM_VALUE retrieves the name of one value 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_VALUE 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_VALUE 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_VALUE"
    USING OPEN-KEY-HANDLE, NDX, VALUE-NAME, NAME-SIZE,
        DATA-TYPE, VALUE-DATA, DATA-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
  • NDX Numeric data item

    Specifies the index of the value to retrieve. NDX should be set to 1 for the first call to REG_ENUM_VALUE and then incremented for subsequent calls. The values are not returned in any particular order.

  • VALUE-NAME PIC X(n)

    Receives the name of the value.

  • NAME-SIZE Usage unsigned-long

    Specifies the size, in characters, of the VALUE-NAME buffer. When the function returns, NAME-SIZE contains the size of the string copied to VALUE-NAME.

  • DATA-TYPE Usage unsigned-long

    Points to a variable that receives the type code for the value entry. The type code can be one of the following values (defined in acugui.def):

    Value Meaning
    REG_BINARY Binary data in any form.
    REG_DWORD A 32-bit number.
    REG_DWORD_LITTLE_ENDIAN A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order word. This is the most common format for computers running Windows and Windows NT.
    REG_DWORD_BIG_ENDIAN A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order word.
    REG_EXPAND_SZ A null-terminated string that contains unexpanded references to environment variables (for example, "%PATH%"). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
    REG_LINK A Unicode symbolic link.
    REG_MULTI_SZ An array of null-terminated strings, terminated by two null characters.
    REG_NONE No defined value type.
    REG_RESOURCE_LIST A device-driver resource list.
    REG_SZ A null-terminated string. It will be a Unicode or ANSI string, depending on whether you use the Unicode or ANSI functions.
  • VALUE-DATA Variable parameter
    Buffer to receive the data for the value entry. If you know what type of data is being returned, you may specify this parameter accordingly. If the type of data returned is unknown, you may specify a group item structured as follows:
    01 VALUE-DATA
       02 VALUE-DATA-ORIG                                PIC X (n).
       02 VALUE-DWORD redefines VALUE-DATA-ORIG          Usage signed-long.
       02 VALUE-LIT-ENDIAN redefines VALUE-DATA-ORIG     Usage signed-long.
       02 VALUE-BIG-ENDIAN redefines VALUE-DATA-ORIG     S9 (9) COMP-4.
       02 VALUE-EXPAND-SZ redefines VALUE-DATA-ORIG      PIC X (n).
       02 VALUE-LINK redefines VALUE-DATA-ORIG           PIC X (n).
       02 VALUE-MULTI-SZ redefines VALUE-DATA-ORIG       PIC X (n).
       02 VALUE-NONE redefines VALUE-DATA-ORIG           PIC X (n).
       02 VALUE-RESOURCE-LIST redefines VALUE-DATA-ORIG  PIC X (n).
       02 VALUE-SZ redefines VALUE-DATA-ORIG             PIC X (n).
  • DATA-SIZE Usage unsigned-long

    Specifies the size, in bytes, of the VALUE-DATA buffer. When the function returns, DATA-SIZE contains the number of bytes copied to VALUE-DATA. This parameter can be NULL only if VALUE-DATA is NULL.

  • STATUS-CODE Numeric data item

    Receives the return status of call to Microsoft's RegEnumValue function. A return status of zero indicates success; non-zero indicates that an error occurred. A value of 259 indicates that there are no more values for the specified key.

Comments

To enumerate values, an application should initialize the NDX parameter to 1 and call REG_ENUM_VALUE repeatedly, incrementing NDX each time, until there are no more values (that is, until the function returns with STATUS-CODE set to 259).

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

The key identified by the OPEN-KEY-HANDLE parameter must have been opened with KEY_QUERY_VALUE access.

Compatibility Issues

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