REG_CREATE_KEY_EX, DISPLAY_REG_CREATE_KEY_EX

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.
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_CREATE_KEY_EX when you want the action to be performed 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_CREATE_KEY_EX when you want the action to be performed 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_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 (defined in acugui.def):

    Value Meaning
    REG_OPTION_VOLATILE The value of this key varies depending on the Windows operating system used:

    Windows 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 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.

Compatibility Issues

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