/sys$common/syshlp/helplib.hlb System Services, $REGISTRY (Alpha Only)  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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

    VMS 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

    VMS 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

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

    Refer to the OpenVMS System Services Reference Manual to view the
    item code diagrams and descriptor fields tables.

 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.
    Refer to the OpenVMS System Services Reference Manual to view the
    diagram.

    When $REGISTRY begins execution, it clears the quadword I/O
    status block if you specify the iosb argument.

    Although the iosb argument is optional, Compaq 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

    VMS 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

    VMS 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-F-NORESPONSE.