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, ...);
1 – 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.
To view the item code diagrams and descriptor fields tables, see
the VSI OpenVMS System Services Reference Manual.
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.
To view the diagram, see the VSI OpenVMS System Services Reference
Manual.
When $REGISTRY begins execution, it clears the quadword I/O
status block if you specify the iosb argument.
Although the iosb argument is optional, VSI strongly recommends
that you specify it for the following reasons:
o 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.
o 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.