Retrieves the type and data for a specified value name associated with an open registry key. This library routine works with 32-bit Windows only.
Usage
Call "REG_QUERY_VALUE_EX"
USING OPEN-KEY-HANDLE,
VALUE-NAME,
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
VALUE-NAME PIC X(n)
Name of the value to be queried.
DATA-TYPE Usage signed-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):
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 NT and Windows 95.
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 recieve 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-BINARY redefines 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.
STATUS-CODE Numeric data item
Receives the return status of call to Microsoft's "RegQueryValueEx" function. A return status of zero indicates success; non-zero indicates that an error occurred. A return status of '234' indicates that the size of the data to be returned in VALUE-DATA exceeds the buffer size specified by the DATA-SIZE parameter.
Comments
The key identified by OPEN-KEY-HANDLE must have been opened with KEY_QUERY_VALUE access. This function does not expand the environment-variable names in the value data when the value type is REG_EXPAND_SZ.
When calling the REG_QUERY_VALUE_EX function with OPEN-KEY-HANDLE set to the HKEY_PERFORMANCE_DATA handle and a value string of a specified object, the returned data structure sometimes has unrequested objects. Don't be surprised; this is normal behavior.
When calling the REG_QUERY_VALUE_EX function, you should always expect to 'walk' the returned data structure to look for the requested object.