Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

If you specify the REG$_LINKPATH item code, it must point to a key path already defined in the OpenVMS Registry; otherwise the system returns the REG$_INVALIDPATH error.

Note If you do not specify the REG$_CACHEACTION item code, the new key is created with the same cache action value as the parent key. The same rule applies to the REG$_VOLATILE and REG$_SECURITYPOLICY item codes.

#### REG$FC_DELETE_KEY

This request removes the specified subkey and its values from the OpenVMS Registry database. If the specified key has subkeys, the key is not deleted. You must delete the subkeys first.

Using this function code, you can group multiple requests into a single call to the $REGISTRY service. If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_RETURNSTATUS | No | Output
REG$_SEPARATOR | No | n/a
REG$_SUBKEYNAME | Yes | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)

#### REG$FC_DELETE_VALUE

This request deletes the specified value from the key.

Using this function code, you can group multiple requests into a single call to the $REGISTRY service. If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_RETURNSTATUS | No | Output
REG$_SEPARATOR | No | n/a
REG$_VALUENAME | Yes | Input

#### REG$FC_ENUM_KEY

This request retrieves information about one subkey of the key. You identify the subkey in the REG$_SUBKEYINDEX item code.

To enumerate all the key's subkeys, the application must call the $REGISTRY service repeatedly using the REG$FC_ENUM_KEY function code. Begin with a REG$_SUBKEYINDEX of zero, then increment the count until the request returns a REG$_NOMOREITEMS error.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_CACHEACTION | No | Output
REG$_CLASSNAME | No | Output (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LASTWRITE | No | Output
REG$_LINKCOUNT | No | Output
REG$_LINKPATH | No | Output (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LINKTYPE | No | Output
REG$_RETURNSTATUS | No | Output
REG$_SECURITYPOLICY | No | Output
REG$_SUBKEYINDEX | Yes | Input
REG$_SUBKEYNAME | No | Output (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_VOLATILE | No | Output

#### REG$FC_ENUM_VALUE

This request retrieves information about a value of the specified key identifier. The value to retrieve is identified in the REG$_VALUEINDEX item code.

To enumerate all a key's values, the application must call the $REGISTRY service repeatedly using the REG$FC_ENUM_VALUE function code. Begin with a REG$_VALUEINDEX of zero, then increment the count until the request returns a REG$_NOMOREITEMS error.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_DATAFLAGS | No | Output
REG$_DATATYPE | No | Output
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_RETURNSTATUS | No | Output
REG$_VALUEDATA | No | Output
REG$_VALUEINDEX | Yes | Input
REG$_VALUENAME | No | Output
REG$_VOLATILE | No | Output

#### REG$FC_FLUSH_KEY

This request writes all the information about a specified key to disk.

This request returns only after the operation is complete and all attributes of the key have been written to the OpenVMS Registry database.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_RETURNSTATUS | No | Output

#### REG$FC_MODIFY_KEY

This request modifies a specified key's attributes.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_CACHEACTION | No | Input
REG$_CLASSNAME | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LINKPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LINKTYPE | No | Input
REG$_NEWNAME | No | Input
REG$_RETURNSTATUS | No | Output
REG$_SECURITYPOLICY | No | Input

To remove the link from the specified key, enter a REG$_LINKPATH item code with an address of zero. You cannot add a link to a key that has either values or subkeys (or both).

#### REG$FC_MODIFY_TREE_KEY

This request modifies a specified key and all its subkey attributes. No link will be followed or modified.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_CACHEACTION | No | Input
REG$_CLASSNAME | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_RETURNSTATUS | No | Output
REG$_SECURITYPOLICY | No | Input

#### REG$FC_NOTIFY_CHANGE_KEY_VALUE

This request notifies the calling process when a specified key or any of its subkeys has changed. That is, the requested function waits for the specified condition before returning.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_FLAGSUBKEY | Yes | Input
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_NOTIFYFILTER | Yes | Input
REG$_RETURNSTATUS | No | Output

#### REG$FC_OPEN_KEY

This request opens the specified key. If you do not specify a subkey, the system opens the key specified in REG$_KEYID.

If REG$_KEYID specifies a key other than a predefined key, the system opens the key again (duplicates the key).

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_KEYID | Yes | Input
REG$_KEYRESULT | Yes | Output
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_RETURNSTATUS | No | Output
REG$_SECACCESS | Yes | Input
REG$_SUBKEYNAME | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)

#### REG$FC_QUERY_KEY

This request retrieves attributes about a specified key.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_CACHEACTION | No | Output
REG$_CLASSNAME | No | Output (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_CLASSNAMEMAX | No | Output
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LASTWRITE | No | Output
REG$_LINKCOUNT | No | Output
REG$_LINKPATH | No | Output (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LINKTYPE | No | Output
REG$_RETURNSTATUS | No | Output
REG$_SECURITYPOLICY | No | Output
REG$_SUBKEYNAMEMAX | No | Output
REG$_SUBKEYSNUMBER | Yes | Output
REG$_VALUEDATAMAX | No | Output
REG$_VALUENAMEMAX | No | Output
REG$_VALUENUMBER | No | Output
REG$_VOLATILE | No | Output

#### REG$FC_QUERY_VALUE

This request retrieves the type, data flags, and data for the specified value name.

Using this function code, you can group multiple requests into a single call to the $REGISTRY service.

If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_DATAFLAGS | No | Output
REG$_DATATYPE | No | Output
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_KEYID | Yes | Input
REG$_LINKCOUNT | No | Output
REG$_LINKPATH | No | Output (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LINKTYPE | No | Output
REG$_RETURNSTATUS | No | Output
REG$_SEPARATOR | No | n/a
REG$_VALUEDATA | No | Output
REG$_VALUENAME | Yes | Input
REG$_VOLATILE | No | Output

#### REG$FC_SEARCH_TREE_DATA

This request scans a specified key and all its descendants for a match with a specified set of data information.

The set of data information can be either the REG$_DATAFLAGS item code, or the pair REG$_DATATYPE and REG$_VALUEDATA item codes, or all three item codes.

The REG$_FLAGOPCODE item code specifies how the REG$_DATAFLAGS item code should be matched against the database. (See the item codes description for more information about the REG$_FLAGOPCODE item code.)

Every time the system finds a match, it appends the path name relative to the specified key to the REG$_PATHBUFFER item code. A Unicode null character is used to separate the value path names.

If the buffer supplied by the application is not big enough to hold all the value path names found, the system returns the SS$_BUFFEROVF error message in the iosb argument, and the length required to complete the operation successfully is returned in the REG$_REQLENGTH item (if specified).

Use the ellipsis (...) wildcard to match zero or more subkeys in the REG$_KEYPATH item code.

(For example, `Hardware\...\disks` finds all the paths that start with the `Hardware` subkey and end with the `disk` subkey, with zero or more subkeys in between.)

Use the asterisk (*) wildcard to match an entire subkey or a portion of a subkey in the REG$_KEYPATH item code.

Use the percent (%) wildcard to match one character in a key name in the REG$_KEYPATH item code.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_DATAFLAGS | No | Input
REG$_DATATYPE | No | Input
REG$_FLAGOPCODE | No | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_KEYID | Yes | Input
REG$_PATHBUFFER | Yes | Output
REG$_REQLENGTH | No | Output
REG$_RETURNSTATUS | No | Output
REG$_VALUEDATA | No | Input

#### REG$FC_SEARCH_TREE_KEY

This request scans a specified key and all its descendants for a specified key path.

For this function code, a valid key path is a Unicode string that can include the ellipsis (...), asterisk (*), or percent (%) wildcard character, but that cannot start with the backslash character (\).

Use the ellipsis (...) wildcard to match zero or more subkeys in the REG$_KEYPATH item code. (For example, `Hardware\...\disks` finds all the paths that start with the `Hardware` subkey and end with the `disk` subkey, with zero or more subkeys in between.)

Use the asterisk (*) wildcard to match an entire subkey or a portion of a subkey in the REG$_KEYPATH item code.

Use the percent (%) wildcard to match one character in a key name in the REG$_KEYPATH item code.

An example of a valid key path is as follows:

      hardware\system\*\disk%%

Every time the system finds a match, the system appends its path name relative to the specified key identifier to the REG$_PATHBUFFER item code. A Unicode null character (4 bytes) separates the subkey path names.

If the buffer supplied by the application is not big enough to contain all the subkey path names found, the system returns the SS$_BUFFEROVF error message in the iosb argument, and the system returns the required length to complete the operation successfully in the REG$_REQLENGTH item (if specified).

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_PATHBUFFER | Yes | Output
REG$_REQLENGTH | No | Output
REG$_RETURNSTATUS | No | Output

#### REG$FC_SEARCH_TREE_VALUE

This request scans a specified key and all its descendants for a specified value name.

For this function code a valid key name is a Unicode string that can include the ellipsis (...), asterisk (*), or percent (%) wildcard character, but cannot start with the backslash character (\).

Use the ellipsis (...) wildcard to match zero or more subkeys in the REG$_KEYPATH item code. (For example, `Hardware\...\disks` finds all the paths that start with the `Hardware` subkey and end with the `disk` subkey, with zero or more subkeys in between.)

Use the asterisk (*) wildcard to match an entire subkey or a portion of a subkey in the REG$_KEYPATH item code.

Use the percent (%) wildcard to match one character in a key name in the REG$_KEYPATH item code.

An example of a valid key path is as follows:

      hardware\system\...

For this function code, a valid name is a Unicode string that can include the asterisk (*) and percent (%) wildcard characters.

Every time the system finds a match, the system appends its path name relative to the specified key identifier to the REG$_PATHBUFFER item code. A Unicode null character (4 bytes) separates the subkey path names.

If the buffer supplied by the application is not big enough to contain all the subkey path names found, the system returns the SS$_BUFFEROVF error message in the iosb argument, and the system returns the required length to complete the operation successfully in the REG$_REQLENGTH item (if specified).

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_KEYID | Yes | Input
REG$_PATHBUFFER | Yes | Output
REG$_REQLENGTH | No | Output
REG$_RETURNSTATUS | No | Output
REG$_VALUENAME | Yes | Input

#### REG$FC_SET_VALUE

This request sets value and type information for a specified key.

Using this function code, you can group multiple requests into a single call to the $REGISTRY service.

If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.

When a value is set to a link, the system validates the link unless you specify the REG$M_IGNORE_LINKS function code modifier.

Specify the item codes as follows:

Item Code | Required | Parameter Type
--- | --- | ---
REG$_DATAFLAGS | No | Input
REG$_DATATYPE | No | Input
REG$_KEYID | Yes | Input
REG$_KEYPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LINKPATH | No | Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
REG$_LINKTYPE | No | Input
REG$_RETURNSTATUS | No | Output
REG$_SEPARATOR | No | n/a
REG$_VALUEDATA | No | Input
REG$_VALUENAME | No | Input

Item Codes Table SYS-18 provides a summary of item codes that are valid as an item descriptor in the itmlst argument. The table lists the item codes, input/output usage, and data types.

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_080.HTML