REG_QUERY_VALUE, DISPLAY_REG_QUERY_VALUE

Retrieves the value associated with a specified registry key by accessing the Windows registry routine RegQueryValue.
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_QUERY_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_QUERY_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_QUERY_VALUE" 
    USING OPEN-KEY-HANDLE, RETURN-VALUE, RETURN-SIZE,
    GIVING STATUS-CODE

or

CALL "REG_QUERY_VALUE" 
    USING OPEN-KEY-HANDLE, RETURN-VALUE, RETURN-SIZE,
       SUBKEY-NAME, 
    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
RETURN-VALUE PIC X(n) Receives the value associated with the specified key.
RETURN-SIZE usage unsigned-long Specifies the size, in characters, of the RETURN-VALUE buffer. When the function returns, RETURN-SIZE contains the size of the string copied to RETURN-VALUE.
SUBKEY-NAME PIC X(n) (optional) Name of a subkey of OPEN-KEY-HANDLE for which a value is to be retrieved. If SUBKEY-NAME is omitted or contains an empty string, REG_QUERY_VALUE retrieves the value associated with the key identified by OPEN-KEY-HANDLE.
STATUS-CODE Numeric data item. Receives the return status of the call to Microsoft's RegQueryValue function. A return status of zero indicates success; non-zero indicates that an error occurred.

Comments

When REG_QUERY_VALUE is called repeatedly in a loop, be sure to reset the value of RETURN-SIZE between calls.

If the length of the value string exceeds the size of the RETURN-VALUE buffer (the buffer size is indicated in the input value of RETURN-SIZE), then the behavior of the routine depends on the operating system. On 32-bit Windows systems, a value string that exceeds the size of the RETURN-VALUE buffer causes RETURN-SIZE to be set to the full length of the value string. In this case, the value string is not copied into RETURN-VALUE, and STATUS-CODE is set to 234.

Compatibility Issues

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