HP OpenVMS System Services Reference Manual
$REGISTRY (Alpha and Integrity servers)
On Alpha and Integrity server systems, interface to the OpenVMS
Registry database server.
The $REGISTRY service allows you to query, update, and set keys,
subkeys, and values in the OpenVMS Registry database.
The $REGISTRY service supports both asynchronous and synchronous
operations. For asynchronous completion, use the Registry ($REGISTRY)
system service.
For synchronous completion, use the Registry and Wait ($REGISTRYW)
system service. The $REGISTRYW system service is identical to the
$REGISTRY system service, except that $REGISTRYW returns to the caller
after the system completes the requested operation. For additional
information about system service completion, see the Synchronize
($SYNCH) system service.
This system service is 64-bit compatible.
Format
SYS$REGISTRY [efn] ,func ,0 ,itmlst ,[iosb or iosa_64] [,astadr or
astadr_64] [,astprm or astprm_64] [,timeout]
C Prototype
int sys$registry (unsigned int efn, unsigned int func, void *, void
*itmlst, struct _iosb *iosb, ...);
Arguments
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the event flag to be used by $REGISTRY. If you do not specify
the event flag, the system defaults to event flag 0. The event flag is
initially cleared by $REGISTRY and then set when the operation
completes.
func
| OpenVMS usage: |
function_code |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Function code specifying the action that $REGISTRY is to perform. The
func argument is a longword containing this function
code. The function code can contain function modifiers. For more
information on function modifiers, see the Function
Modifiers section.
A single call to $REGISTRY can specify only one function code. All
function codes require additional information to be passed in the call
with the itmlst argument.
itmlst
| OpenVMS usage: |
32-bit item_list_3 or 64-bit item_list_64b |
| type: |
longword (unsigned) for 32-bit; quadword (unsigned) for
64-bit |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Item list supplying information that the system will use to perform the
function specified by the func argument.
The itmlst argument is the address of the item list.
The item list consists of one or more sets of item descriptors. Each
descriptor is either an item_list_3 or item_list_64b format.
Some function codes allow you to specify multiple operations in a
single call. In this case, you must place the REG$_SEPARATOR item code
between each set of item codes. Each request, separated by a
REG$_SEPARATOR item code, can contain the item codes in any order.
You can specify item codes as either input or output parameters. Input
parameters modify functions, set context, or describe the information
to be returned. Output parameters return the requested information.
For item_list_3 lists, you must terminate the list with a longword of
0. For item_list_64b lists, you must terminate the list with a quadword
of 0.
The following diagram shows the structure of an
item_list_3 descriptor:
The following diagram shows the structure of an
item_list_64b descriptor:
The following table defines the item descriptor fields:
| Descriptor Field |
Definition |
|
Buffer length
|
A word that specifies the length of the buffer. The buffer either
supplies information to be used by $REGISTRY, or receives information
from $REGISTRY. The required length of the buffer varies, depending on
the item code specified. Each item code description specifies the
required length.
|
|
Item code
|
A word containing a symbolic code that describes the type of
information currently in the buffer or that is returned in the buffer.
The buffer address field points to the location of the buffer.
|
|
Buffer address
|
A longword that contains the address of the buffer that specifies or
receives the information.
|
|
Return length address
|
A longword that contains the address of a word that specifies the
actual length in bytes of the information returned by $REGISTRY. The
information resides in a buffer identified by the buffer address field.
The field applies to output item list entries only, and must be 0
(zero) for input entries. If the return length address is 0, it is
ignored.
|
iosb or iosa_64
| OpenVMS usage: |
status_block |
| type: |
buffer |
| access: |
write only |
| mechanism: |
by reference |
Status block to receive the final completion status and information of
the $REGISTRY operation.
If multiple operations are requested for a function code, the value
returned in iosb is either SS$_NORMAL or SS$_REGERROR.
A more specific return status for each operation is returned in the
REG$_RETURNSTATUS item code (if specified).
The iosb argument is the address of the $REGISTRY
status block:
When $REGISTRY begins execution, it clears the quadword I/O status
block if you specify the iosb argument.
Although the iosb argument is optional, HP strongly
recommends that you specify it for the following reasons:
- If you are using an event flag to signal the completion of the
service, you can test the I/O status block for a condition value to be
sure that the event flag was not set by an event other than service
completion.
- If you are using the $SYNCH system service to synchronize
completion of the service, the I/O status block is a required argument
for $SYNCH.
The condition value returned in R0 and the condition value returned in
the I/O status block provide information about different aspects of the
call to the $REGISTRY service. The condition value returned in R0
provides information about the success or failure of the service call
itself; the condition value returned in the I/O status block provides
information about the success or failure of the service operation.
To assess the success or failure of the call to $REGISTRY accurately,
you must first check the condition value returned in R0. If R0 contains
a successful value, you must check the condition value in the I/O
status block.
The following table defines the item descriptor fields:
| Descriptor Field |
Definition |
|
Status
|
A longword specifying the final status of the $REGISTRY service. If you
request multiple operations for a function code, the system returns
either SS$_NORMAL or SS$_REGERROR to
iosb. This field is set to 0 (zero) when the operation
begins.
|
|
Reserved
|
A reserved longword.
|
astadr or astadr_64
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by reference |
AST service routine to be executed when $REGISTRY completes. The
astadr argument is the address of this routine. If you
specify astadr, the AST routine executes at the same
access mode as the caller of the $REGISTRY service.
If the $REGISTRY service is not called successfully (that is, if it
returns an error immediately), the AST routine is not executed.
astprm or astprm_64
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
AST parameter to be passed to the AST service routine specified by the
astadr argument. The astprm argument
specifies this longword parameter.
timeout
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Timeout value specifies the number of seconds allotted to $REGISTRY to
perform the request. If the Registry server does not complete the
request within the time you allot, $REGISTRY returns REG$_NORESPONSE.
Function Codes Table SYS-49 provides a summary of valid function
codes, a brief description of their function, and the OpenVMS Registry
rights identifier required to perform the function.
You can find a detailed description of each item code in the
Item Codes section.
The OpenVMS Registry identifier is required only if you do not provide a
valid NT access token and you do not have the SYSPRV privilege. If you
have a granted REG$UPDATE identifier, you can perform all the functions
in Table SYS-49.
Table SYS-49 Valid Function Codes
| Function Code |
Identifier |
Description |
|
REG$FC_CLOSE_KEY
|
REG$LOOKUP
|
Closes an open key or subkey.
|
|
REG$FC_CREATE_KEY
|
REG$UPDATE
|
Creates (and opens) a subkey.
|
|
REG$FC_DELETE_KEY
|
REG$UPDATE
|
Removes a subkey from a key.
|
|
REG$FC_DELETE_VALUE
|
REG$UPDATE
|
Removes a value from a key.
|
|
REG$FC_ENUM_KEY
|
REG$LOOKUP
|
Lists (enumerates) the subkeys of a key.
|
|
REG$FC_ENUM_VALUE
|
REG$LOOKUP
|
Lists (enumerates) the values of a key.
|
|
REG$FC_FLUSH_KEY
|
REG$UPDATE
|
Ensures that all information for the key is backed to disk.
|
|
REG$FC_MODIFY_KEY
|
REG$UPDATE
|
Modifies a key.
|
|
REG$FC_MODIFY_TREE_KEY
|
REG$UPDATE
|
Modifies a key and all its subkeys.
|
|
REG$FC_NOTIFY_CHANGE_KEY_VALUE
|
REG$UPDATE
|
Notifies when a key or value has changed.
|
|
REG$FC_OPEN_KEY
|
REG$LOOKUP
|
Opens a key or subkey.
|
|
REG$FC_QUERY_KEY
|
REG$LOOKUP
|
Fetches information about a key.
|
|
REG$FC_QUERY_VALUE
|
REG$LOOKUP
|
Fetches information about a value.
|
|
REG$FC_SEARCH_TREE_DATA
|
REG$LOOKUP
|
Searches the value data of key and its subkeys.
|
|
REG$FC_SEARCH_TREE_KEY
|
REG$LOOKUP
|
Searches the names of a key and its subkeys.
|
|
REG$FC_SEARCH_TREE_VALUE
|
REG$LOOKUP
|
Searches the values of a key and its subkeys.
|
|
REG$FC_SET_VALUE
|
REG$UPDATE
|
Changes the data associated with a value name.
|
REG$FC_CLOSE_KEY
This request releases the open resources of the specified key. If
REG$_KEYID indicates a predefined key, the system ignores the action
and returns success.
Specify the item codes as follows:
| Item Code |
Required |
Parameter Type |
|
REG$_KEYID
|
Yes
|
Input
|
|
REG$_RETURNSTATUS
|
No
|
Output
|
REG$FC_CREATE_KEY
If the key does not exist, this request creates a new subkey under the
key specified by REG$_KEYID. If the key does exist, the system does not
modify it.
If you specify the REG$_KEYRESULT item code, the system opens the
specified subkey.
The system returns the result in the REG$_DISPOSITION item code buffer.
Using this function code, you can group multiple requests into a single
call to the $REGISTRY service. To use the multiple-request feature, you
must 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.
To set a value for a key, call the $REGISTRY service with the
REG$FC_SET_VALUE function code.
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$_DISPOSITION
|
No
|
Output
|
|
REG$_KEYID
|
Yes
|
Input
|
|
REG$_KEYRESULT
|
No
|
Output
|
|
REG$_LINKPATH
|
No
|
Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
|
|
REG$_LINKTYPE
|
No
|
Input
|
|
REG$_RETURNSTATUS
|
No
|
Output
|
|
REG$_SECACCESS
|
No
|
Input
|
|
REG$_SECURITYPOLICY
|
No
|
Input
|
|
REG$_SEPARATOR
|
No
|
n/a
|
|
REG$_SUBKEYNAME
|
Yes
|
Input (Pointer to Unicode string. Unicode character is 4 bytes long.)
|
|
REG$_VOLATILE
|
No
|
Input
|
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$_VALUEDATASIZE
|
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.
| 
