ContentsIndexPreviousNext

REG_CREATE_KEY_EX Routine

Creates a specified registry key by providing access to the Windows registry routine RegCreateKeyEx. If the key already exists, this function opens it (same functionality as REG_OPEN_KEY_EX). If the key does not exist, it is created and then opened. This library routine works with 32-bit Windows only.

Usage

Call "REG_CREATE_KEY_EX"
   USING OPEN-KEY-HANDLE,
       SUBKEY-TO-BE-CREATED,
       CLASS-NAME,
       OPTIONS,
       SAM-DESIRED,
       SUBKEY-HANDLE,
       DISPOSITION
   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 key created or opened by REG_CREATE_KEY_EX is a subkey of the key identified by OPEN-KEY-HANDLE.

SUBKEY-TO-BE-CREATED PIC X(n)

Name of the subkey to create or open.

CLASS-NAME PIC X(n)

Specifies the class (object type) of the key to be created. This parameter is ignored if the key already exists.

OPTIONS Usage unsigned-long

Specifies special options for the key. This parameter must be one of the following values values (defined in acugui.def):

Value
Meaning
REG_OPTION_VOLATILE
The value of this key varies depending on the Windows operating system used:
Windows 95/98: This value is ignored . That is, even if REG_OPTION_VOLATILE is specified, the RegCreateKeyEx function creates a nonvolatile key and returns ERROR_SUCCESS.
Windows NT 3.5/4.0, Windows 2000: This key is volatile; the information is stored in memory and is not preserved when the system is restarted.
REG_OPTION_NON_VOLATILE
This key is not volatile; the information is stored in a file and is preserved when the system is restarted.

By default, keys are not volatile. This option is ignored if the key already exists.

SAM-DESIRED Usage unsigned-long

Specifies a security access mask (SAM) that describes the desired security access for the new key. This parameter can be a combination of the following values (defined in acugui.def):

Value
Meaning
KEY_ALL_ACCESS
Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, EY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access.
KEY_CREATE_LINK
Permission to create a symbolic link.
KEY_CREATE_SUB_KEY
Permission to create subkeys.
KEY_ENUMERATE_SUB_KEYS
Permission to enumerate subkeys.
KEY_EXECUTE
Permission for read access.
KEY_NOTIFY
Permission for change notification.
KEY_QUERY_VALUE
Permission to query subkey data.
KEY_READ
Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access.
KEY_SET_VALUE
Permission to set subkey data.
KEY_WRITE
Combination of KEY_SET_VALUE and KEY_CREATE_SUB_KEY access.

The above values may be combined in COBOL applications by using the "CBL_OR" library routine.

SUBKEY-HANDLE Usage unsigned-long

Data item to receive the handle of the newly created or opened key.

DISPOSITION Usage unsigned-long

Points to a variable that receives one of the following disposition values (defined in acugui.def):

Value
Meaning
REG_CREATED_NEW_KEY
The key did not exist and was created.
REG_OPENED_EXISTING_KEY
The key existed and was simply opened without being changed.

STATUS-CODE Numeric data item

Receives the return status of the call to Microsoft's "RegCreateKeyEx" function. A return status of zero indicates success; non-zero indicates that an error occurred.