VMS Help  —  System Services
    This help category provides an overview and the format of each of
    the system services. The C function prototypes are available only
    on OpenVMS Alpha and Integrity server systems.

    System services provide basic operating system functions,
    interprocess communication, and various control resources.

1  –  $ABORT TRANS

    Ends a transaction by aborting it.

    Format

      SYS$ABORT_TRANS  [efn] ,[flags] ,iosb [,[astadr] ,[astprm]

                       ,[tid] ,[reason] ,[bid]]

    C Prototype

      int sys$abort_trans  (unsigned int efn, unsigned int flags,

                           struct _iosb *iosb,...);

1.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for these option
    flags, described in $ABORT_TRANS Option Flags. All undefined bits
    must be 0. If this argument is omitted, no flags are used.

    Table SYS-1 $ABORT_TRANS Option Flags

    Flag           Description

    DDTM$M_        Set this flag to indicate that the service should
    NOWAIT         return to the caller without waiting for final
                   cleanup. Note that $ABORT_TRANSW with the DDTM$M_
                   NOWAIT flag set is not equivalent to $ABORT_TRANS.
                   $ABORT_TRANS returns when the operation has been
                   queued. The former does not return until the
                   operation has been initiated. The latter returns
                   as soon as the operation has been queued. The
                   full range of status values may be returned from a
                   nowait call.
    DDTM$M_SYNC    Set this flag to specify that successful
                   synchronous completion is to be indicated by
                   returning SS$_SYNCH. When SS$_SYNCH is returned,
                   the AST routine is not called, the event flag is
                   not set, and the I/O status block is not filled
                   in.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block in which the following information is returned:

    o  The completion status of the service, returned as a condition
       value.

    o  An abort reason code that gives one reason why the transaction
       aborted, if the completion status of the service is SS$_
       NORMAL.

       Note that, if there are multiple reasons why the transaction
       aborted, the abort reason code returned in the I/O status
       block might not be the same as the abort reason code passed
       in the reason argument. The DECdtm transaction manager returns
       one of the reasons in the I/O status block. It may return
       different reasons to different branches of the transaction.

       For example, if the call to $ABORT_TRANS gives DDTM$_ABORTED
       as the reason and the transaction timeout expires at about the
       same time as the call to $ABORT_TRANS, then either the DDTM$_
       TIMEOUT or DDTM$_ABORTED reason code can be returned in the
       I/O status block.

    The $DDTMMSGDEF macro defines symbolic names for abort reason
    codes, which are defined in Abort Reason Codes:

    Table SYS-2 Abort Reason Codes

    Symbolic Name       Description

    DDTM$_ABORTED       The application aborted the transaction
                        without giving a reason.
    DDTM$_COMM_FAIL     A communications link failed.
    DDTM$_INTEGRITY     A resource manager integrity constraint check
                        failed.
    DDTM$_LOG_FAIL      A write operation to the transaction log
                        failed.
    DDTM$_ORPHAN_       An unauthorized branch caused failure.
    BRANCH
    DDTM$_PART_SERIAL   A resource manager serialization check
                        failed.
    DDTM$_PART_TIMEOUT  The timeout specified by a resource manager
                        expired.
    DDTM$_SEG_FAIL      A process or image terminated.
    DDTM$_              A DECdtm transaction manager serialization
    SERIALIZATION       check failed.
    DDTM$_SYNC_FAIL     The transaction was not globally
                        synchronized; an authorized branch was not
                        added to the transaction.
    DDTM$_TIMEOUT       The timeout specified on $START_TRANS
                        expired.
    DDTM$_UNKNOWN       The reason is unknown.
    DDTM$_VETOED        A resource manager was unable to commit the
                        transaction.

    To view the I/O status block structure diagram, see the VSI
    OpenVMS System Services Reference Manual.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    AST routine that is executed when the service completes, if SS$_
    NORMAL is returned in R0. The astadr argument is the address of
    the entry mask of this routine. The routine is executed in the
    access mode of the caller.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    AST parameter that is passed to the AST routine specified by the
    astadr argument.

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    Identifier of the transaction to be aborted.

    If this argument is omitted, $ABORT_TRANS aborts the default
    transaction of the calling process.

 reason

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Code that gives the reason why the application is aborting the
    transaction. The $DDTMMSGDEF macro defines symbolic names for
    abort reason codes. See the iosb item code for a list of abort
    reason codes.

    The default value for this argument is DDTM$_ABORTED.

 bid

    OpenVMS usage:branch_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (BID) of the branch that is aborting the
    transaction.

    The default value of this argument is zero, which is the BID of
    the branch that started the transaction.

2  –  $ABORT TRANSW

    Ends a transaction by aborting it.

    $ABORT_TRANSW always waits for the request to complete before
    returning to the caller. Other than this, it is identical to
    $ABORT_TRANS.

    Format

      SYS$ABORT_TRANSW  [efn] ,[flags] ,iosb [,[astadr] ,[astprm]

                        ,[tid] ,[reason] ,[bid]]

    C Prototype

      int sys$abort_transw  (unsigned int efn, unsigned int flags,

                            struct _iosb *iosb,...);

3  –  $ACK EVENT

    Acknowledges an event reported to a Resource Manager (RM)
    participant or Resource Manager instance (RMI).

    Format

      SYS$ACK_EVENT  [flags] ,report_id ,report_reply [,[reason]

                     ,[beftime] ,[afttime] ,[part_name]

                     ,[rm_context], [timout]]

    C Prototype

      int sys$ack_event  (unsigned int flags, unsigned int report_id,

                         int report_reply,...);

3.1  –  Arguments

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Reserved to VSI. This argument must be zero.

 report_id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The identifier of the event report being acknowledged by this
    call to $ACK_EVENT.

 report_reply

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Acknowledgment code appropriate to the event being acknowledged
    by this call to $ACK_EVENT. The following tables give the valid
    acknowledgment codes for the various events. The title of each
    table gives the event, and in brackets, its event code. The event
    code is passed in the event report block (see $DECLARE_RM).

    Acknowledgment of prepare or one-phase commit events gives a
    vote on the outcome of the transaction-either to commit or to
    abort. The tables for these events have a column labeled "Vote".
    A "yes" vote means that the RM participant wants to commit the
    transaction, while a "no" vote means that the RM participant
    cannot commit. The transaction will be committed only if all
    participants vote "yes".

    Table SYS-3 Replies to an Abort Event Report (DDTM$K_ABORT)

    report_
    reply       Description

    SS$_FORGET  RM participant guarantees that the effects of its
                transaction operations will never be detected by any
                transaction that commits.

                Side effects:

                On successful completion of the call to $ACK_EVENT,
                the RM participant is removed from the transaction,
                and the ASTLM quota consumed by the call to $JOIN_RM
                or $ACK_EVENT that added it to the transaction is
                returned.

                DECdtm also releases any application threads that are
                waiting for the transaction to end (necessary but not
                sufficient condition). Any call to $END_TRANS, $END_
                BRANCH, or $ABORT_TRANS on a node for a transaction
                whose outcome is abort is not allowed to complete
                until after all abort event reports delivered to RM
                participants on that node have been acknowledged.

    Table SYS-4 Replies to a Commit Event Report (DDTM$K_COMMIT)

    report_
    reply       Description

    SS$_FORGET  Allows the DECdtm transaction manager to forget the
                RM participant.

                The RM participant must not give this reply until it
                has either:

                o  Completed the commit processing for its
                   transaction operations.

                o  Safely stored enough information to ensure that
                   this commit processing will inevitably complete
                   (for example, logged that the transaction has
                   committed in a private log).

                If the RM participant is associated with a
                nonvolatile RMI, then at some point after receiving
                this reply, the DECdtm transaction manager will
                delete the name of the RM participant from the
                transaction database. After SS$_FORGET replies
                have been given for all the RM participants in
                a transaction, that transaction ceases to be
                recoverable (some time after all these replies
                are given, the transaction is deleted from the
                transaction database). A subsequent call to $GETDTI
                can lead the resource manager to wrongly assume that
                the transaction had aborted.

                If there is a failure after this reply is sent, a
                recoverable resource manager must be able to rely
                on its own safely stored information to determine if
                any of the commit processing associated with the RM
                participant needs to be restarted.

                Side effects:

                On successful completion of the call to $ACK_EVENT,
                the RM participant is removed from the transaction,
                and the ASTLM quota consumed by the call to $JOIN_RM
                or $ACK_EVENT that added it to the transaction is
                returned.

                DECdtm also releases any application threads that
                are waiting for the transaction to end (necessary but
                not sufficient condition). Any call to $END_TRANS or
                $END_BRANCH on a node for a transaction whose outcome
                is commit cannot complete successfully until all
                commit event reports delivered to RM participants on
                that node have been acknowledged.
    SS$_        The RM participant requires that the DECdtm
    REMEMBER    transaction manager stores its name and the outcome
                of the transaction (commit) in the transaction
                database. Note that for an RM participant associated
                with a volatile RMI, SS$_REMEMBER is treated in the
                same way as SS$_FORGET.

                Side effects:

                On successful completion of the call to $ACK_EVENT,
                the RM participant is removed from the transaction,
                and the ASTLM quota consumed by the call to $JOIN_RM
                or $ACK_EVENT that added it to the transaction is
                returned.

                DECdtm also releases any application threads that
                are waiting for the transaction to end (necessary but
                not sufficient condition). Any call to $END_TRANS or
                $END_BRANCH on a node for a transaction whose outcome
                is commit cannot complete successfully until all
                commit event reports delivered to RM participants on
                that node have been acknowledged.

    Table SYS-5 Replies to a One-phase Commit Event Report (DDTM$K_
                ONE_PHASE_COMMIT)

    report_
    reply       Vote  Meaning

    SS$_NORMAL  Yes   The RM participant decided to commit the
                      transaction, and has safely stored enough
                      information to be able to keep this guarantee
                      even if there is a recoverable failure, caused,
                      for example, by a node crash.

                      The DECdtm transaction manager does not log any
                      information about the transaction.

                      Side effects:

                      On successful completion of the call to $ACK_
                      EVENT, the RM participant is removed from the
                      transaction, the transaction is ended, and the
                      ASTLM quota consumed by the call to $JOIN_RM or
                      $ACK_EVENT that added the RM participant to the
                      transaction is returned.

                      DECdtm also allows the call to $END_TRANS to
                      complete (necessary and sufficient condition).
    SS$_        Yes   RM participant decided not to accept the
    PREPARED          opportunity to decide the outcome of the
                      transaction. It has performed only prepare
                      processing for the transaction and requires
                      full two-phase commit processing. This is
                      equivalent to voting SS$_PREPARED on a prepare
                      event.

                      The RM participant can either commit or
                      abort the operations of the transaction, and
                      guarantees that it will abide by the DECdtm
                      transaction manager's decision on whether the
                      transaction (and therefore these operations)
                      are committed or aborted.

                      A recoverable resource manager must not give
                      this vote until it has safely stored enough
                      information to be able to keep this guarantee
                      even if there is a recoverable failure, caused,
                      for example, by a node crash.

                      The DECdtm transaction manager will decide
                      the outcome of the transaction, then inform
                      the resource manager of the decision with
                      a commit or abort event report delivered
                      to the RM participant (assuming that it is
                      associated with an RMI that requested these
                      event reports).

                      Note that an application or other failure can
                      cause the DECdtm transaction manager to decide
                      to abort the transaction.
    SS$_VETO    No    RM participant requires that the transaction
                      be aborted and guarantees that the effects of
                      that transaction on its resources will never
                      be detected by any transaction that commits.
                      The reason argument gives the reason why the RM
                      participant is aborting the transaction.

                      The DECdtm transaction manager does not log any
                      information about the transaction.

                      Side effects:

                      On successful completion of the call to $ACK_
                      EVENT, the RM participant is removed from the
                      transaction, the transaction is ended, and the
                      ASTLM quota consumed by the call to $JOIN_RM or
                      $ACK_EVENT that added the RM participant to the
                      transaction is returned.

                      DECdtm also allows the call to $END_TRANS to
                      complete (necessary and sufficient condition).

    Table SYS-6 Replies to a Prepare Event Report (DDTM$K_PREPARE)

    report_
    reply       Vote  Meaning

    SS$_FORGET  Yes   This is called a read-only vote. It is an
                      optimization that allows an RM participant
                      to vote "yes" and not receive a commit or abort
                      event report.

                      Side effects:

                      On successful completion of the call to $ACK_
                      EVENT, the RM participant is removed from the
                      transaction, and the ASTLM quota consumed by
                      the call to $JOIN_RM or $ACK_EVENT that added
                      it to the transaction is returned.
    SS$_        Yes   The RM participant can either commit or
    PREPARED          abort the operations of the transaction, and
                      guarantees that it will abide by the DECdtm
                      transaction manager's decision on whether the
                      transaction (and therefore these operations)
                      are committed or aborted. In other words, the
                      RM participant guarantees that the behavior
                      of its resources will never be inconsistent
                      with that decision, insofar as that behavior is
                      detected by any transactions that commit.

                      A recoverable resource manager must not give
                      this vote until it has safely stored enough
                      information to be able to keep this guarantee
                      even if there is a recoverable failure, caused,
                      for example, by a node crash.

                      The DECdtm transaction manager will decide
                      the outcome of the transaction, then inform
                      the resource manager of the decision with a
                      commit or abort event report delivered to the
                      RM participant (assuming that it is associated
                      with an RMI that requested these event reports)
                      or, in the event of a failure, using the
                      resource manager's recovery mechanism.
    SS$_VETO    No    RM participant requires that the transaction
                      be aborted. The reason argument gives the
                      reason why the RM participant is aborting the
                      transaction.

                      The RM participant guarantees that the effects
                      of its transaction operations will never be
                      detected by any transaction that commits.

                      Side effects:

                      The DECdtm transaction manager will deliver an
                      abort event report for the transaction to the
                      RM participant.

    Table SYS-7 Replies to a Default Transaction Started Event Report
                (DDTM$K_STARTED_DEFAULT)

    report_
    reply       Description

    SS$_NORMAL  Adds a new RM participant running in the calling
                process to the transaction to which a new branch is
                being added. The new RM participant is associated
                with the RMI to which the default transaction started
                event was reported. The part_name and rm_context
                arguments specify the name of the new RM participant
                and its context.

                Side effects:

                The postconditions on successful completion of the
                call to $ACK_EVENT are the same as those for $JOIN_
                RM.

                DECdtm also allows the call to $START_TRANS or
                $START_BRANCH that is adding the new branch to
                complete (necessary but not sufficient condition).
                That call cannot complete successfully until all
                default transaction-started event reports delivered
                to RMIs in that process have been acknowledged.
    SS$_FORGET  Acknowledgment of the event report.

                Side effects:

                DECdtm allows the call to $START_TRANS or $START_
                BRANCH that is adding the new branch to complete
                (necessary but not sufficient condition).

                That call cannot complete successfully until all
                default transaction-started event reports delivered
                to RMIs in that process have been acknowledged.

    Table SYS-8 Replies to a Nondefault Transaction Started Event
                Report (DDTM$K_STARTED_NONDEFAULT)

    report_
    reply       Description

    SS$_NORMAL  Adds a new RM participant running in the calling
                process to the transaction to which a new branch is
                being added. The new RM participant is associated
                with the RMI to which the nondefault transaction
                started event was reported. The part_name and rm_
                context arguments specify the name of the new RM
                participant and its context.

                Side effects:

                The postconditions on successful completion of the
                call to $ACK_EVENT are the same as those for $JOIN_
                RM.

                DECdtm also allows the call to $START_TRANS or
                $START_BRANCH that is adding the new branch to
                complete (necessary but not sufficient condition).
                That call cannot complete successfully until all
                default transaction-started event reports delivered
                to RMIs in that process have been acknowledged.
    SS$_FORGET  Acknowledgment of the event report.

                Side effects:

                DECdtm allows the call to $START_TRANS or $START_
                BRANCH that is adding the new branch to complete
                (necessary but not sufficient condition).

                That call cannot complete successfully until all
                default transaction-started event reports delivered
                to RMIs in that process have been acknowledged.

 reason

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    A code that gives the reason why the RM participant is aborting
    the transaction.

    This argument is ignored unless the value in the report_reply
    argument is SS$_VETO and the event being acknowledged is a
    prepare or one-phase commit event.

    The $DDTMMSGDEF macro defines symbolic names for abort reason
    codes described in Abort Reason Codes. The default value for this
    argument is DDTM$_VETOED.

    Table SYS-9 Abort Reason Codes

    Symbolic Name      Description

    DDTM$_ABORTED      Application aborted the transaction without
                       giving a reason.
    DDTM$_COMM_FAIL    Transaction aborted because a communications
                       link failed.
    DDTM$_INTEGRITY    Transaction aborted because a resource manager
                       integrity constraint check failed.
    DDTM$_LOG_FAIL     Transaction aborted because an attempt to
                       write to the transaction log failed.
    DDTM$_ORPHAN_      Transaction aborted because it had an
    BRANCH             unauthorized branch.
    DDTM$_PART_SERIAL  Transaction aborted because a resource manager
                       serialization check failed.
    DDTM$_PART_        Transaction aborted because a resource manager
    TIMEOUT            timeout expired.
    DDTM$_SEG_FAIL     Transaction aborted because a process or image
                       terminated.
    DDTM$_             Transaction aborted because a serialization
    SERIALIZATION      check failed.
    DDTM$_SYNC_FAIL    Transaction aborted because a branch had been
                       authorized for it but had not been added to
                       it.
    DDTM$_TIMEOUT      Transaction aborted because its timeout
                       expired.
    DDTM$_UNKNOWN      Transaction aborted; reason unknown.
    DDTM$_VETOED       Transaction aborted because a resource manager
                       was unable to commit it.

 beftime

    OpenVMS usage:utc_date_time
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    Reserved to VSI.

 afttime

    OpenVMS usage:utc_date_time
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    Reserved to VSI.

 part_name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    The name of the new RM participant that is added to the
    transaction by this call to $ACK_EVENT. This argument is ignored
    unless the event being acknowledged is of type Transaction
    Started and the value of the report_reply argument is SS$_NORMAL.

    If this argument is omitted (the default) or its value is zero,
    the name of the new RM participant is the same of that of the RMI
    with which it is associated.

    The string passed in this argument must be no longer than 32
    characters.

    To ensure smooth operation in a mixed-network environment,
    refer to the chapter entitled Managing DECdtm Services in the
    VSI OpenVMS System Manager's Manual, for information on defining
    node names.

 rm_context

    OpenVMS usage:userarg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The context associated with the new RM participant. This argument
    is ignored unless the value of the report_reply argument is SS$_
    NORMAL, and the event being acknowledged is of type Transaction
    Started.

    The context of the new RM participant is passed in the event
    reports subsequently delivered to that RM participant.

    The context is used to pass information specific to the new
    RM participant from the main line code into the event handler
    specified in the call to $DECLARE_RM that created the RMI with
    which the new RM participant is associated.

    If this argument is omitted (the default) or is zero, the context
    associated with the new RM participant is the same of that of the
    RMI with which it is associated.

 timout

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Reserved to VSI.

4  –  $ACM

    The $ACM service provides a common interface to all functions
    supported by the Authentication and Credential Management (ACM)
    authority.

    The caller must specify the function code and any applicable
    function modifiers and item codes for the requested operation.

    The $ACM service completes asynchronously; for synchronous
    completion, use the $ACMW form of the service.

    Format

      SYS$ACM  [efn], func, [context], itmlst, acmsb, [astadr],

               [astprm]

    C Prototype

      int sys$acm  (unsigned int efn, unsigned int func, struct

                   _acmecb **context, void *itmlst, struct _acmesb

                   *acmsb, void (*astadr)(__unknown_params), int

                   astprm);

4.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the $ACM request
    completes. The efn argument is a longword containing this number;
    however, $ACM uses only the low-order byte.

    When the request is queued, $ACM clears the specified event flag.
    Then, when the request completes, the specified event flag is
    set.

 func

    OpenVMS usage:function_code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Function code and modifiers specifying the operation that $ACM
    is to perform. The func argument is a longword containing the
    function code, logically 'OR'ed together with the modifiers.
    For some programming languages this may be defined as a record
    structure.

    Function codes have symbolic names of the following format:

       ACME$_FC_code

    Function modifiers have symbolic names of the following format:

       ACME$M_modifier

    The language support mechanisms specific to each programming
    language define the names of each function code and modifier.
    Only one function code can be specified across a dialogue
    sequence of related calls to $ACM.

    Most function codes require or allow additional information to
    be passed in the call. This information is passed using the
    itmlst argument, which specifies a list of one or more item
    descriptors. Each item descriptor in turn specifies an item code,
    which either controls the action to be performed, or requests
    specific information to be returned.

 context

    OpenVMS usage:context
    type:         longword pointer (signed)
    access:       modify
    mechanism:    by 32- or 64-bit reference
    Address of a longword to receive the 32-bit address of an ACM
    communications buffer.

    $ACM uses the ACM communications buffer for dialogue functions
    (ACME$_FC_AUTHENTICATE_PRINCIPAL and ACME$_FC_CHANGE_PASSWORD)
    to request that the caller provide additional information in a
    subsequent call.

    The context argument on a continuation call must contain the
    same ACM communications buffer address returned by $ACM on the
    previous call. The itmlst provided on a continuation call must
    contain entries to fulfill each of the input item set entries in
    the ACM communications buffer returned by $ACM on the previous
    call.

    The longword specified must contain a -1 on the first call in a
    dialogue sequence of related calls. If additional information is
    required to complete the request, $ACM returns a pointer in the
    context argument to an ACM communications buffer that describes
    the information. To continue with the particular operation call,
    $ACM again specifying the function argument previously provided.

    The ACM communications buffer is user readable, but not user
    writable. It consists of a structure header, an item set, and
    a string buffer segment. The item set is an array of item set
    entries, each describing an item of information that is needed
    to complete the request or information that can be reported to a
    human user.

    $ACM presents the item set entries in the logical presentation
    order for a sequential interface, so calling programs that
    give a sequential view to the user should process the item set
    entries in that $ACM order. More advanced GUI programs may use
    simultaneous presentation with distinctive placement for various
    message types.

    To view the diagram of the overall format of an ACM
    communications buffer, see the VSI OpenVMS System Services
    Reference Manual.

    To view the format of an item set entry and descriptor table, see
    the VSI OpenVMS System Services Reference Manual.

 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 specifying information to be used in performing
    the function and requesting information to be returned. The
    itmlst argument is the 32- or 64-bit address of a list of item
    descriptors, describing an item of information. An item list in
    32-bit format is terminated by a longword of 0; an item list in
    64-bit format is terminated by a quadword of 0.

    The item list can be composed of up to 32 segments, connected by
    a chain item (using item code ACME$_CHAIN) at the end of all but
    the last segment pointing to the start of the next segment. All
    item descriptors in a single segment must be of the same format
    (32-bit or 64-bit), but a single item list can contain a mixture
    of segments composed of 32-bit item descriptors and segments
    composed of 64-bit item descriptors.

    To view the 32-bit and 64-bit item code diagrams and descriptor
    fields tables, see the VSI OpenVMS System Services Reference
    Manual.

    In an item list, no ACME-specific item codes can be included in
    an item list until the ACME Context has been set with one of the
    following codes:

       ACME$_CONTEXT_ACME_ID
       ACME$_CONTEXT_ACME_NAME

    You can also implicitly set the ACME Context with one of the
    following codes:

       ACME$_TARGET_DOI_ID
       ACME$_TARGET_DOI_NAME

    These codes are described in the VSI OpenVMS Programming Concepts
    Manual.

 acmsb

    OpenVMS usage:acm_status_block
    type:         octaword array of 4 longwords
    access:       write only
    mechanism:    by 32- or 64-bit reference
    ACM status block that is to receive the final completion status.
    The acmsb argument is the 32- or 64-bit address of the ACM status
    block.

    To view the structure of an ACM status block and descriptor field
    definitions, see the VSI OpenVMS System Services Reference Manual.

    Upon request initiation, $ACM sets the value of all fields
    within the ACM status block to 0. When the requested operation
    completes. The $ACM service writes condition values into the
    ACMESB$L_STATUS and ACMESB$L_SECONDARY_STATUS fields.

    If the status in the ACMESB$L_STATUS field is ACME$_AUTHFAILURE,
    that is the only result that should be displayed or otherwise
    made known to a user. The status in ACMESB$L_SECONDARY_STATUS
    (when the caller has the SECURITY privilege, or is calling from
    kernel or executive mode) contains the detailed reason for the
    failure, which may be used for purposes that do not disclose the
    code to the user, such as the process termination code supplied
    to $DELPRC (but not the image exit code supplied to $EXIT).

    Otherwise, the status in ACMESB$L_SECONDARY_STATUS should be
    considered as subsidiary to that in ACMESB$L_STATUS and used to
    form a chained message, unless the two cells contain identical
    values.

    In either case, the caller of $ACM[W] can rely on the success bit
    (bit 0) of the ACMESB$L_STATUS and the ACMESB$L_SECONDARY_STATUS
    field having the same setting. Either both low-order bits will be
    set (success) or both will be clear (failure).

    The ACMESB$L_ACME_STATUS field is valid only when the contents
    of the ACMESB$L_ACME_ID field are nonzero, indicating which ACME
    agent supplied the (possibly zero) value in ACMESB$L_ACME_STATUS.

    There is one special format for such data in ACMESB$L_ACME_
    STATUS. If $ACM rejects the request because of a bad entry in
    the item list, then ACMESB$L_STATUS contains one of the following
    codes:

    SS$_BADPARAM  Incorrect contents for the item code
    SS$_          Incorrect item code for the function
    BADITMCOD
    SS$_          Incorrect length for the item code
    BADBUFLEN

    If ACMESB$L_STATUS contains one of the listed returns, then
    ACME$L_ACME_STATUS contains the item code from the incorrect
    item, which is an aid to debugging.

    In all other cases, the value delivered in ACME$L_ACME_STATUS is
    specific to the ACME agent that failed the request. An ACME agent
    can return a longword value that indicates additional information
    about the operation. $ACM writes this value in the ACMESB$L_ACME_
    STATUS field of the ACM status block.

    In these cases, you can expect the success of a valid value (one
    where ACMESB$L_ACME_ID is not zero) in field ACMESB$L_ACME_STATUS
    to match the "success" bits (bit 0) in fields ACMESB$L_STATUS and
    ACMESB$L_SECONDARY_STATUS, although what constitutes a "success"
    value in ACMESB$L_ACME_STATUS is subject to that interpretation
    specified for the ACME agent that set the value. In particular,
    the values in the ACMESB$L_ACME_STATUS field from certain ACME
    Agents might not be a VMS-style message code.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference
    AST service routine to be executed when $ACM completes. The
    astadr argument is the 32- or 64-bit address of this routine.
    The AST routine executes at the same access mode as the caller of
    the $ACM service.

 astprm

    OpenVMS usage:user_arg
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    AST parameter to be passed to the AST service routine specified
    by the astprm argument. The astprm argument is the longword
    parameter.

5  –  $ACMW

    The $ACM service provides a common interface to all functions
    supported by the Authentication and Credentials Management (ACM)
    authority. The caller must specify the function code and any
    applicable function modifiers and item codes for the requested
    operation.

    The $ACM service completes asynchronously; for synchronous
    completion, use the $ACMW form of the service.

    Format

      SYS$ACMW  [efn], func, [context], itmlst, acmsb, [astadr],

                [astprm]

    C Prototype

      int sys$acmw  (unsigned int efn, unsigned int func, struct

                    _acmecb *context, void *itmlst, struct _acmesb

                    *acmsb, void (*astadr)(__unknown_params), int

                    astprm);

5.1  –  Description

    Beginning in OpenVMS Version 7.3-2, a number of functional
    changes were made to SYS$ACM[W]. In the following descriptions
    of these changes, nonprivileged processes refer to processes
    running in user mode that do not have SECURITY privilege.

    These changes are the following:

    o  Timeout processing

       Timeout processing is now enforced for nonprivileged
       processes. Othe processes can request time processing by
       specifying the ACME$M_TIMEOUT function modifier.

    o  Dialogue mode iteration limit

       Nonprivileged processes are now limited in the number of
       iterative requests they can make in a dialogue sequence of
       calls.

6  –  $ACQUIRE GALAXY LOCK (Alpha Only)

    Acquires ownership of an OpenVMS Galaxy lock.

    Note that this system service is supported only in an OpenVMS
    Alpha Galaxy environment.

    For more information about programming with OpenVMS Galaxy system
    services, see the VSI OpenVMS Alpha Partitioning and Galaxy Guide.

    Format

      SYS$ACQUIRE_GALAXY_LOCK  handle ,timeout ,flags

    C Prototype

      int sys$acquire_galaxy_lock  (unsigned __int64 lock_handle,

                                   unsigned int timeout, unsigned int

                                   flags);

6.1  –  Arguments

 handle

    OpenVMS usage:galaxy lock handle
    type:         quadword (unsigned)
    access:       read
    mechanism:    input by value
    The 64-bit lock handle that identifies the lock to be acquired.
    This value is returned by SYS$CREATE_GALAXY_LOCK.

 timeout

    OpenVMS usage:wait timeout
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    The 32-bit wait or spin timeout specified in 10 microsecond
    units. If not specified, defaults to 10 microseconds.

 flags

    OpenVMS usage:bit mask
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    Control flags defined by the GLOCKDEF macro: GLOCK$C_NOBREAK,
    GLOCK$C_NOSPIN, and GLOCK$C_NOWAIT.

7  –  $ADD BRANCH

    Authorizes a new branch to be added to a transaction.

    Format

      SYS$ADD_BRANCH  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid

                      ,tm_name ,bid

    C Prototype

      int sys$add_branch  (unsigned int efn, unsigned int

                          flags, struct _iosb *iosb, void

                          (*astadr)(__unknown_params), int astprm,

                          unsigned int tid [4], void *tmname,

                          unsigned int bid [4]);

7.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument
    is a longword bit mask in which each bit corresponds to an
    option flag. The $DDTMDEF macro defines symbolic names for the
    option flag, which is described in $ADD_BRANCH Option Flag. All
    undefined bits must be 0. If this argument is omitted, no flags
    are used.

    Table SYS-10 $ADD_BRANCH Option Flag

    Flag Name   Description

    DDTM$M_     Specifies successful synchronous completion by
    SYNC        returning SS$_SYNCH. When SS$_SYNCH is returned,
                the AST routine is not called, the event flag is not
                set, and the I/O status block is not filled in.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the completion status of the
    service is returned as a condition value.

    To view the I/O status block diagram, see the VSI OpenVMS System
    Services Reference Manual.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine executed when the service completes, if SS$_
    NORMAL is returned in R0. The astadr argument is the address
    of the entry mask of this routine. The routine is executed in
    the same access mode as that of the caller of the $ADD_BRANCH
    service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter that is passed to the AST routine specified by
    the astadr argument.

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (TID) of the transaction for which a new branch is
    to be authorized.

 tm_name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    The name of the node on which the new branch is running. Note
    that this cannot be a cluster alias.

    To ensure smooth operation in a mixed-network environment,
    refer to the chapter entitled Managing DECdtm Services in the
    VSI OpenVMS System Manager's Manual, for information on defining
    node names.

 bid

    OpenVMS usage:branch_id
    type:         octaword (unsigned)
    access:       write only
    mechanism:    by reference
    An octaword in which the identifier (BID) of the new branch is
    returned. No other call to $ADD_BRANCH on any node ever returns
    the same BID value.

8  –  $ADD BRANCHW

    Authorizes a new branch to be added to a transaction. $ADD_
    BRANCHW always waits for the request to complete before returning
    to the caller. Other than this, it is identical to $ADD_BRANCH.

    Format

      SYS$ADD_BRANCHW  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid

                       ,tm_name ,bid

    C Prototype

      int sys$add_branchw  (unsigned int efn, unsigned int

                           flags, struct _iosb *iosb, void

                           (*astadr)(__unknown_params), int astprm,

                           unsigned int tid [4], void *tmname,

                           unsigned int bid [4]);

9  –  $ADD HOLDER

    Adds a specified holder record to a target identifier.

    Format

      SYS$ADD_HOLDER  id ,holder ,[attrib]

    C Prototype

      int sys$add_holder  (unsigned int id, struct _generic_64

                          *holder, unsigned int attrib);

9.1  –  Arguments

 id

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Target identifier granted to the specified holder when $ADD_
    HOLDER completes execution. The id argument is a longword
    containing the binary value of the target identifier.

 holder

    OpenVMS usage:rights_holder
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Holder identifier that is granted access to the target identifier
    when $ADD_HOLDER completes execution. The holder argument is the
    address of a quadword data structure that consists of a longword
    containing the holder's UIC identifier followed by a longword
    containing a value of 0.

 attrib

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Attributes to be placed in the holder record when $ADD_HOLDER
    completes execution. The attrib argument is a longword containing
    a bit mask specifying the attributes. A holder is granted a
    specified attribute only if the target identifier has the
    attribute.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The symbols are defined
    in the system macro library ($KGBDEF). The symbolic name for each
    bit position is listed in the following table:

    Bit Position           Meaning When Set

    KGB$V_DYNAMIC          Allows holders of the identifier to remove
                           it from or add it to the process rights
                           database by using the DCL command SET
                           RIGHTS_LIST.
    KGB$V_HOLDER_HIDDEN    Prevents someone from getting a list of
                           users who hold an identifier, unless they
                           own the identifier themselves.
    KGB$V_NAME_HIDDEN      Allows holders of an identifier to have it
                           translated-either from binary to ASCII or
                           vice versa-but prevents unauthorized users
                           from translating the identifier.
    KGB$V_NOACCESS         Makes any access rights of the identifier
                           null and void. This attribute is intended
                           as a modifier for a resource identifier or
                           the Subsystem attribute.
    KGB$V_RESOURCE         Allows holders of an identifier to charge
                           disk space to the identifier. It is used
                           only for file objects.
    KGB$V_SUBSYSTEM        Allows holders of the identifier to
                           create and maintain protected subsystems
                           by assigning the Subsystem ACE to the
                           application images in the subsystem.

10  –  $ADD IDENT

    Adds the specified identifier to the rights database.

    Format

      SYS$ADD_IDENT  name ,[id] ,[attrib] ,[resid]

    C Prototype

      int sys$add_ident  (void *name, unsigned int id, unsigned int

                         attrib, unsigned int *resid);

10.1  –  Arguments

 name

    OpenVMS usage:char-string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Identifier name to be added to the rights database when $ADD_
    IDENT completes execution. The name argument is the address of
    a character-string descriptor pointing to the identifier name
    string.

    An identifier name consists of 1 to 31 alphanumeric characters,
    including dollar signs ($)  and underscores (_), and must contain
    at least one nonnumeric character. Any lowercase characters
    specified are automatically converted to uppercase.

 id

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Identifier to be created when $ADD_IDENT completes execution.
    The id argument is a longword containing the binary value of the
    identifier to be created.

    If the id argument is omitted, $ADD_IDENT selects a unique
    available value from the general identifier space and returns
    it in resid, if it is specified.

 attrib

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Attributes placed in the identifier's record when $ADD_IDENT
    completes execution. The attrib argument is a longword containing
    a bit mask that specifies the attributes.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The symbols are defined
    in the system macro library ($KGBDEF). The symbolic name for each
    bit position is listed in the following table:

    Bit Position           Meaning When Set

    KGB$V_DYNAMIC          Allows holders of the identifier to remove
                           it from or add it to the process rights
                           database by using the DCL command SET
                           RIGHTS_LIST.
    KGB$V_HOLDER_HIDDEN    Prevents someone from getting a list of
                           users who hold an identifier, unless they
                           own the identifier themselves.
    KGB$V_NAME_HIDDEN      Allows holders of an identifier to have it
                           translated-either from binary to ASCII or
                           vice versa-but prevents unauthorized users
                           from translating the identifier.
    KGB$V_NOACCESS         Makes any access rights of the identifier
                           null and void. This attribute is intended
                           as a modifier for a resource identifier or
                           the Subsystem attribute.
    KGB$V_RESOURCE         Allows holders of an identifier to charge
                           disk space to the identifier. It is used
                           only for file objects.
    KGB$V_SUBSYSTEM        Allows holders of the identifier to
                           create and maintain protected subsystems
                           by assigning the Subsystem ACE to the
                           application images in the subsystem.

 resid

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Identifier value assigned by the system when $ADD_IDENT completes
    execution. The resid argument is the address of a longword in
    which the system-assigned identifier value is written.

11  –  $ADD PROXY

    Adds a new proxy to, or modifies an existing proxy in, the proxy
    database.

    Format

      SYS$ADD_PROXY  rem_node ,rem_user ,local_user ,[flags]

    C Prototype

      int sys$add_proxy  (void *rem_node, void *rem_user, void

                         *local_user, unsigned int flags);

11.1  –  Arguments

 rem_node

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Remote node name of the proxy to be added to or modified in
    the proxy database. The rem_node argument is the address of a
    character-string descriptor pointing to the remote node name
    string.

    A remote node name consists of 1 to 1024 characters. No specific
    characters, format, or case are required for a remote node name
    string. Node names are converted to their DECnet for OpenVMS full
    name unless the PRX$M_BYPASS_EXPAND flag is set with the flags
    argument.

    If you specify a single asterisk (*)  for the rem_node argument,
    the user name specified by the rem_user argument on all nodes is
    served by the proxy.

 rem_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Remote user name of the proxy to be added to or modified in
    the proxy database. The rem_user argument is the address of a
    character-string descriptor pointing to the user name string.

    A remote user name consists of 1 to 32 alphanumeric characters,
    including dollar signs ($),  underscores (_), and brackets
    ([ ]).  Any lowercase characters specified are automatically
    converted to uppercase.

    The rem_user argument can be specified in user identification
    code (UIC) format ([group, member]).  Brackets are allowed only
    if the remote user name string specifies a UIC. Group and member
    are character-string representations of octal numbers with no
    leading zeros.

    If you specify a single asterisk (*)  for the rem_user argument,
    all users from the node specified by the rem_node argument
    are served by the same user names specified by the local_user
    argument.

 local_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Local user name to add to the proxy record specified by the rem_
    node and rem_user arguments in the proxy database as either
    the default user or local user. The local_user argument is the
    address of a character-string descriptor pointing to the local
    user name.

    A local user name consists of 1 to 32 alphanumeric characters,
    including dollar signs ($)  and underscores (_). Any lowercase
    characters specified are automatically converted to uppercase.

    The user name specified by the local_user argument must be a user
    name known to the local system.

    If the PRX$M_DEFAULT flag is specified in the flags argument, the
    user name specified by the local_user argument will be added to
    the proxy record in the proxy database as the default user. If a
    default user already exists for the specified proxy record, the
    default user is placed into the proxy's local user list and is
    replaced by the user name specified by the local_user argument.

    Proxy records can contain no more than 16 local users and 1
    default user. To add multiple users to a single proxy, you must
    call this service once for each local user.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Functional specification for the service and type of user the
    local_user argument represents. The flags argument is a longword
    bit mask wherein each bit corresponds to an option.

    Each flag option has a symbolic name. The $PRXDEF macro defines
    the following symbolic names:

    Symbolic Name      Description

    PRX$M_BYPASS_      The service should not convert the node name
    EXPAND             specified in the rem_node argument to its
                       corresponding DECnet for OpenVMS full name.
                       If this flag is set, it is the caller's
                       responsibility to ensure that the fully
                       expanded node name is passed into the service.

    PRX$M_DEFAULT      The user name specified by the local_user
                       argument is the default user for the proxy.
                       If this flag is not specified, the user name
                       specified by the local_user argument is added
                       to the proxy record's local user list.

    PRX$M_IGNORE_      The service should not wait for a return
    RETURN             status from the security server. No return
                       status from the server's function will be
                       returned to the caller.

12  –  $ADJSTK

    Modifies the stack pointer for a less privileged access mode.
    The operating system uses this service to modify a stack pointer
    for a less privileged access mode after placing arguments on the
    stack.

    Format

      SYS$ADJSTK  [acmode] ,[adjust] ,newadr

    C Prototype

      int sys$adjstk  (unsigned int acmode, short int adjust, void

                      *(*(newadr)));

12.1  –  Arguments

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode for which the stack pointer is to be adjusted. The
    acmode argument is this longword value. If not specified, the
    default value 0 (kernel access mode) is used.

 adjust

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by value
    Signed adjustment value used to modify the value specified by the
    newadr argument. The adjust argument is a signed longword, which
    is the adjustment value.

    Only the low-order word of this argument is used. The value
    specified by the low-order word is added to or subtracted
    from (depending on the sign) the value specified by the newadr
    argument. The result is loaded into the stack pointer for the
    specified access mode.

    If the adjust argument is not specified or is specified as 0, the
    stack pointer is loaded with the value specified by the newadr
    argument.

 newadr

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value that adjust is to adjust. The newadr argument is the
    address of this longword value.

    The value specified by this argument is both read and written
    by $ADJSTK. The $ADJSTK service reads the value specified and
    adjusts it by the value of the adjust argument (if specified).
    After this adjustment is made, $ADJSTK writes the adjusted value
    back into the longword specified by newadr and then loads the
    stack pointer with the adjusted value.

    If the value specified by newadr is 0, the current value of the
    stack pointer is adjusted by the value specified by adjust. This
    new value is then written back into newadr, and the stack pointer
    is modified.

13  –  $ADJWSL

    Adjusts a process's current working set limit by the specified
    number of pagelets (on Alpha or Integrity server systems) and
    returns the new value to the caller. The working set limit
    specifies the maximum number of process pagelets that can be
    resident in physical memory.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ADJWSL  [pagcnt] ,[wsetlm]

    C Prototype

      int sys$adjwsl  (int pagcnt, unsigned int *wsetlm);

13.1  –  Arguments

 pagcnt

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by value
    Signed adjustment value specifying the number of pagelets to
    add to (if positive) or subtract from (if negative) the current
    working set limit. The pagcnt argument is this signed longword
    value.

    Note that, on Alpha and Integrity server systems, the specified
    value is rounded up to an even multiple of the CPU-specific page
    size.

    If pagcnt is not specified or is specified as 0, no adjustment
    is made and the current working set limit is returned in the
    longword specified by the wsetlm argument (if this argument is
    specified).

 wsetlm

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Value of the working set limit, in pagelets , returned by
    $ADJWSL. The wsetlm argument is the 32- or 64-bit address of
    this longword value. The wsetlm argument receives the newly
    adjusted value if pagcnt is specified, and it receives the prior,
    unadjusted value if pagcnt is not specified.

14  –  $ALLOC

    Allocates a device for exclusive use by a process and its
    subprocesses. No other process can allocate the device or assign
    channels to it until the image that called $ALLOC exits or
    explicitly deallocates the device with the Deallocate Device
    ($DALLOC) service.

    Format

      SYS$ALLOC  devnam ,[phylen] ,[phybuf] ,[acmode] ,[flags]

    C Prototype

      int sys$alloc  (void *devnam, unsigned short int *phylen, void

                     *phybuf, unsigned int acmode, unsigned int

                     flags);

14.1  –  Arguments

 devnam

    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Device name of the device to be allocated. The devnam argument
    is the address of a character string descriptor pointing to the
    device name string.

    The string can be either a physical device name or a logical
    name. If it is a logical name, it must translate to a physical
    device name.

 phylen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Word into which $ALLOC writes the length of the device name
    string for the device it has allocated. The phylen argument is
    the address of this word.

 phybuf

    OpenVMS usage:device_name
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Buffer into which $ALLOC writes the device name string for the
    device it has allocated. The phybuf argument is the address of a
    character string descriptor pointing to this buffer.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be associated with the allocated device. The
    acmode argument is a longword containing the access mode.

    The most privileged access mode used is the access mode of the
    caller. Only equal or more privileged access modes can deallocate
    the device.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Longword of status flags indicating whether to interpret the
    devnam argument as the type of device to be allocated. Only one
    flag exists, bit 0. When it is set, the $ALLOC service allocates
    the first available device that has the type specified in the
    devnam argument.

    This feature is available for the following mass storage devices:

    RA60    RA80    RA81    RC25
    RCF25   RK06    RK07    RL01
    RL02    RM03    RM05    RM80
    RP04    RP05    RP06    RP07
    RX01    RX02    TA78    TA81
    TS11    TU16    TU58    TU77
    TU78    TU80    TU81

15  –  $ASCEFC

    Associates a named common event flag cluster with a process
    to execute the current image and to be assigned a process-
    local cluster number for use with other event flag services.
    If the named cluster does not exist but the process has suitable
    privilege, the service creates the cluster.

    Format

      SYS$ASCEFC  efn ,name ,[prot] ,[perm]

    C Prototype

      int sys$ascefc  (unsigned int efn, void *name, char prot, char

                      perm);

15.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of any event flag contained within the desired common
    event flag cluster. The efn argument is a longword value
    specifying this number; however, $ASCEFC uses only the low-order
    byte.

    There are two common event flag clusters: cluster 2 and cluster
    3. Cluster 2 contains event flag numbers 64 to 95, and cluster
    3 contains event flag numbers 96 to 127. (Clusters 0 and 1 are
    process-local event flag clusters.)

    To associate with common event flag cluster 2, specify any flag
    number in the cluster (64 to 95); to associate with common event
    flag cluster 3, specify any event flag number in the cluster (96
    to 127).

 name

    OpenVMS usage:ef_cluster_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the common event flag cluster with which to associate.
    The name argument is the address of a character string descriptor
    pointing to this name string.

    The character string descriptor can be 1 to 15 bytes in length,
    and each byte can be any 8-bit value.

    Common event flag clusters are accessible only to processes
    having the same UIC group number, and each such process must
    associate with the cluster using the same name (specified in the
    name argument). The operating system implicitly associates the
    group UIC number with the name, making the name unique to a UIC
    group.

    You can specify any name from 1 to 43 characters. All processes
    mapping to the same global section must specify the same name.
    Note that the name is case sensitive.

    Use of characters valid in logical names is strongly encouraged.
    Valid values include alphanumeric characters, the dollar sign
    ($), and the underscore (_). If the name string begins with an
    underscore (_), the underscore is stripped and the resultant
    string is considered to be the actual name. Use of the colon (:)
    is not permitted.

    Names are first subject to a logical name translation, after
    the application of the prefix GBL$ to the name. If the result
    translates, it is used as the name of the section. If the
    resulting name does not translate, the name specified by the
    caller is used as the name of the section.

    Additional information on logical name translations and
    on section name processing is available in the VSI OpenVMS
    Programming Concepts Manual.

 prot

    OpenVMS usage:Boolean
    type:         byte (unsigned)
    access:       read only
    mechanism:    by value
    Protection specifier that allows or disallows access to the
    common event flag cluster for processes with the same UIC group
    number as the creating process. The prot argument is a longword
    value, which is interpreted as Boolean.

    The default value 0 specifies that any process with the same UIC
    group number as the creating process can access the event flag
    cluster. The value 1 specifies that only processes having the UIC
    of the creating process can access the event flag cluster.

    When the prot argument is 1, all access to the Group category is
    denied.

    The process must have associate access to access an existing
    common event flag cluster.

 perm

    OpenVMS usage:Boolean
    type:         byte (unsigned)
    access:       read only
    mechanism:    by value
    Permanent specifier that marks a common event flag cluster as
    either permanent or temporary. The perm argument is a longword
    value, which is interpreted as Boolean.

    The default value 0 specifies that the cluster is temporary. The
    value 1 specifies that the cluster is permanent.

16  –  $ASCTIM

    Converts an absolute or delta time from 64-bit system time format
    to an ASCII string.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ASCTIM  [timlen] ,timbuf ,[timadr] ,[cvtflg]

    C Prototype

      int sys$asctim  (unsigned short int *timlen, void *timbuf,

                      struct _generic_64 *timadr, char cvtflg);

16.1  –  Arguments

 timlen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Length (in bytes) of the ASCII string returned by $ASCTIM.
    The timlen argument is the the 32- or 64-bit address of a word
    containing this length.

 timbuf

    OpenVMS usage:time_name
    type:         character-coded text string
    access:       write only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Buffer into which $ASCTIM writes the ASCII string. The timbuf
    argument is the 32- or 64-bit address of a character string
    descriptor pointing to the buffer.

    The buffer length specified in the timbuf argument, together with
    the cvtflg argument, controls what information is returned.

 timadr

    OpenVMS usage:date_time
    type:         quadword
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Time value that $ASCTIM is to convert. The timadr argument is
    the 32- or 64-bit address of this 64-bit time value. A positive
    time value represents an absolute time. A negative time value
    represents a delta time. If you specify a delta time, it must be
    less than 10,000 days.

    If timadr is not specified or is specified as 0 (the default),
    $ASCTIM returns the current date and time.

 cvtflg

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Conversion indicator specifying which date and time fields
    $ASCTIM should return. The cvtflg argument is a longword
    value, which is interpreted as Boolean. The value 1 specifies
    that $ASCTIM should return only the hour, minute, second, and
    hundredths-of-second fields. The default value 0 specifies that
    $ASCTIM should return the full date and time.

17  –  $ASCTOID

    Translates the specified identifier name into its binary
    identifier value.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ASCTOID  name ,[id] ,[attrib]

    C Prototype

      int sys$asctoid  (void *name, unsigned int *id, unsigned int

                       *attrib);

17.1  –  Arguments

 name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Identifier name translated when $ASCTOID completes execution. The
    name argument is the 32- or 64-bit address of a character-string
    descriptor pointing to the identifier name.

 id

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Identifier value resulting when $ASCTOID completes execution. The
    id argument is the 32- or 64-bit address of a longword in which
    the identifier value is written.

 attrib

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Attributes associated with the identifier returned in id when
    $ASCTOID completes execution. The attrib argument is the 32- or
    64-bit address of a longword containing a bit mask specifying the
    attributes.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The symbols are defined
    in the system macro $KGBDEF library. The symbolic names for each
    bit position are listed in the following table:

    Bit Position           Meaning When Set

    KGB$V_DYNAMIC          Allows holders of the identifier to remove
                           it from or add it to the process rights
                           database by using the DCL command SET
                           RIGHTS_LIST.
    KGB$V_HOLDER_HIDDEN    Prevents someone from getting a list of
                           users who hold an identifier, unless they
                           own the identifier themselves. Special
                           privilege is required to translate hidden
                           names.
    KGB$V_NAME_HIDDEN      Allows holders of an identifier to have it
                           translated-either from binary to ASCII or
                           vice versa-but prevents unauthorized users
                           from translating the identifier. Special
                           privilege is required to translate hidden
                           names.
    KGB$V_NOACCESS         Makes any access rights of the identifier
                           null and void. This attribute is intended
                           as a modifier for a resource identifier or
                           the Subsystem attribute.
    KGB$V_RESOURCE         Allows the holder to charge resources,
                           such as disk blocks, to the identifier.
    KGB$V_SUBSYSTEM        Allows holders of the identifier to create
                           and maintain protected subsystems by
                           assigning the Subsystem access control
                           entry (ACE) to the application images in
                           the subsystem.

18  –  $ASCUTC

    Converts an absolute time from 128-bit UTC format to an ASCII
    string.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ASCUTC  [timlen] ,timbuf ,[utcadr] ,[cvtflg]

    C Prototype

      int sys$ascutc  (unsigned short int *timlen, void *timbuf,

                      unsigned int *utcadr [4], char cvtflg);

18.1  –  Arguments

 timlen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Length (in bytes) of the ASCII string returned by $ASCUTC. The
    timlen argument is the 32- or 64-bit address of a word containing
    this length.

 timbuf

    OpenVMS usage:time_name
    type:         character-coded string text
    access:       write only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Buffer into which $ASCUTC writes the ASCII string. The timbuf
    argument is the 32- or 64-bit address of a character string
    descriptor pointing to the buffer. The buffer length specified in
    the timbuf argument, together with the cvtflg argument, controls
    what information is returned.

 utcadr

    OpenVMS usage:coordinated universal time
    type:         utc_date_time
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Time value that $ASCUTC is to convert. The timadr argument is the
    32- or 64-bit address of this 128-bit time value. Relative times
    are not permitted. If the timadr argument is not specified, it
    defaults to 0 and $ASCUTC returns the current date and time.

 cvtflg

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Conversion indicator specifying which date and time fields
    $ASCUTC should return. The cvtflg argument is a longword value
    that is interpreted as Boolean. The value 1 specifies that
    $ASCUTC should return only the time, including hour, minute,
    second, and hundredths-of-second fields. The default value 0
    specifies that $ASCUTC should return the full date and time.

19  –  $ASSIGN

    Provides a process with an I/O channel so input/output operations
    can be performed on a device, or establishes a logical link with
    a remote node on a network.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ASSIGN  devnam ,chan ,[acmode] ,[mbxnam] ,[flags]

    C Prototype

      int sys$assign  (void *devnam, unsigned short int *chan,

                      unsigned int acmode, void *mbxnam,...);

19.1  –  Arguments

 devnam

    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the device to which $ASSIGN is to assign a channel.
    The devnam argument is the 32- or 64-bit address of a character
    string descriptor pointing to the device name string.

    If the device name contains a double colon (::),  the system
    assigns a channel to the first available network device (NET:)
    and performs an access function on the network.

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Number of the channel that is assigned. The chan argument is the
    32- or 64-bit address of a word into which $ASSIGN writes the
    channel number.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be associated with the channel. The acmode
    argument specifies the access mode. The $PSLDEF macro defines
    the following symbols for the four access modes:

    Symbol        Access Mode   Numeric Value

    PSL$C_KERNEL  Kernel        0
    PSL$C_EXEC    Executive     1
    PSL$C_SUPER   Supervisor    2
    PSL$C_USER    User          3

    The specified access mode and the access mode of the caller are
    compared. The less privileged (but the higher numeric valued) of
    the two access modes becomes the access mode associated with the
    assigned channel. I/O operations on the channel can be performed
    only from equal and more privileged access modes. For more
    information, see the section on access modes in the VSI OpenVMS
    Programming Concepts Manual.

 mbxnam

    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Logical name of the mailbox to be associated with the device.
    The mbxnam argument is the 32- or 64-bit address of a character
    string descriptor pointing to the logical name string.

    If you specify mbxnam as 0, no mailbox is associated with the
    device. This is the default.

    You must specify the mbxnam argument when performing a
    nontransparent, task-to-task, network operation.

    Only the owner of a device can associate a mailbox with the
    device; the owner of a device is the process that has allocated
    the device, whether implicitly or explicitly. Only one mailbox
    can be associated with a device at any one time.

    For unshareable, nonspooled devices, an implicit $ALLOCATE is
    done. This requires read, write, or control access to the device.

    A mailbox cannot be associated with a device if the device has
    foreign (DEV$M_FOR) or shareable (DEV$M_SHR) characteristics.

    A mailbox is disassociated from a device when the channel that
    associated it is deassigned.

    If a mailbox is associated with a device, the device driver can
    send status information to the mailbox. For example, if the
    device is a terminal, this information might indicate dialup,
    hangup, or the reception of unsolicited input; if the device is a
    network device, it might indicate that the network is connected
    or perhaps that the line is down.

    For details on the nature and format of the information returned
    to the mailbox, see the VSI OpenVMS I/O User's Reference Manual.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    An optional device-specific argument. The flags argument is a
    longword bit mask.

    For more information on the applicability of the flags argument
    for a particular device, see the VSI OpenVMS I/O User's Reference
    Manual.

20  –  $AUDIT EVENT

    Appends an event message to the system security audit log file or
    sends an alarm to a security operator terminal.

    Format

      SYS$AUDIT_EVENT  [efn] ,[flags] ,itmlst ,[audsts] ,[astadr]

                       ,[astprm]

    C Prototype

      int sys$audit_event  (unsigned int efn, unsigned int flags,

                           void *itmlst, unsigned int *audsts, void

                           (*astadr)(__unknown_params), int astprm);

20.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when the audit completes. The
    efn argument is a longword containing the number of the event
    flag; however, $AUDIT_EVENT uses only the low-order byte. If efn
    is not specified, event flag 0 is used.

    Upon request initiation, $AUDIT_EVENT clears the specified event
    flag.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the $AUDIT_EVENT system operation.
    The flags argument is a longword bit mask, where each bit
    corresponds to an option.

    Each flag option has a symbolic name. The $NSADEF macro defines
    the following symbolic names:

    Symbolic Name      Description

    NSA$M_ACL          Specifies an event generated by an Alarm ACE
                       or Audit ACE. This flag is Reserved to VSI.

    NSA$M_FLUSH        Specifies that all messages in the audit
                       server buffer be written to the audit log
                       file.

    NSA$M_INTERNAL     Specifies that the $AUDIT_EVENT call
                       originates in the context of a trusted
                       computing base (TCB) component. The auditing
                       components use this flag to indicate that
                       internal auditing failures should result in a
                       SECAUDTCB bugcheck. This flag is reserved to
                       VSI.

    NSA$M_MANDATORY    Specifies that an audit is to be performed,
                       regardless of system alarm and audit settings.

    NSA$M_NOEVTCHECK   Specifies that an audit is to be performed,
                       regardless of the system alarm or audit
                       settings. This flag is similar to the NSA$M_
                       MANDATORY bit but, unlike the NSA$M_MANDATORY
                       bit, this flag is not reflected in the NSA$W_
                       FLAGS field in the resulting audit record on
                       disk.

    NSA$M_SERVER       Indicates that the call originates in a TCB
                       server process and that the event should be
                       audited regardless of the state of a process-
                       specific, no-audit bit.

                       Trusted servers use this flag to override
                       the no-audit bit when they want to perform
                       explicit auditing on behalf of a client
                       process. This flag is Reserved to VSI.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying information to include in the audit record.
    The itmlst argument is the address of a list of item descriptors.
    The list of item descriptors is terminated by a longword of 0.

    The item list for all calls to $AUDIT_EVENT must include the
    following item codes:

    o  NSA$_EVENT_TYPE

    o  NSA$_EVENT_SUBTYPE

    o  At least one of the NSA$_ALARM_NAME item code or the NSA$_
       AUDIT_NAME item code.

    o  If the event being reported is an object access (NSA$C_MSG_
       OBJ_ACCESS) or an object delete (NSA$C_MSG_OBJ_DELETE), the
       NSA$_FINAL_STATUS, NSA$_ACCESS_DESIRED, and NSA$_OBJECT_CLASS
       item codes must be specified.

    o  If the event being reported is an object create (NSA$C_MSG_
       OBJ_CREATE), the NSA$_FINAL_STATUS and NSA$_OBJECT_CLASS item
       codes must be specified.

    o  If the event being reported is a privilege audit (NSA$C_MSG_
       PRVAUD), the NSA$_PRIVS_USED or the NSA$_PRIVS_MISSING item
       code must be specified.

    o  If the audit event being reported is a deaccess event (NSA$C_
       MSG_OBJ_DEACCESS), the NSA$_OBJECT_CLASS item code must be
       specified.

    The item list is a standard format item list.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

 audsts

    OpenVMS usage:cond_value_type
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Longword condition value that receives the final completion
    status from the operation. If a security audit is required,
    the final completion status represents either the successful
    completion of the resulting security audit or any failing status
    that occurred while the security audit was performed within the
    audit server process.

    The audsts argument is valid only when the service returns
    success and the status is not SS$_EVTNOTENAB. In addition, the
    caller must either make use of the astadr argument or use the
    $AUDIT_EVENTW service before attempting to access audsts.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    Asynchronous system trap (AST) routine to be executed after the
    audsts is updated. The astadr argument, which is the address of a
    longword value, is the procedure value of the AST routine.

    The AST routine executes in the access mode of the caller of
    $AUDIT_EVENT.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Asynchronous system trap (AST) parameter passed to the AST
    service routine. The astprm argument is a longword value
    containing the AST parameter.

21  –  $AUDIT EVENTW

    Determines whether a security-related event should be reported.
    If the event should be reported, the service sends the event
    report to the audit server.

    The $AUDIT_EVENTW service completes synchronously; that is, it
    returns only after receiving an explicit confirmation from the
    audit server that the associated audit, if enabled, has been
    performed.

    For asynchronous completion, use the Audit Event ($AUDIT_EVENT)
    service. In all other respects, $AUDIT_EVENTW is identical to
    $AUDIT_EVENT. For additional information about $AUDIT_EVENTW, see
    the $AUDIT_EVENT service.

    Format

      SYS$AUDIT_EVENTW  efn ,[flags] ,itmlst ,audsts ,[astadr]

                        ,[astprm]

    C Prototype

      int sys$audit_eventw  (unsigned int efn, unsigned int flags,

                            void *itmlst, unsigned int *audsts, void

                            (*astadr)(__unknown_params), int astprm);

22  –  $AVOID PREEMPT

    Requests that the EXEC avoid preempting the calling process or
    thread.

    Format

      SYS$AVOID_PREEMPT  enable

    C Prototype

      int sys$avoid_preempt  (int enable);

22.1  –  Arguments

 enable

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Enables or disables preemption avoidance. If the enable argument
    is set to 1, preemption avoidance is enabled; if 0, preemption
    avoidance is disabled.

23  –  $BINTIM

    Converts an ASCII string to an absolute or delta time value in
    the system 64-bit time format suitable for input to the Set Timer
    ($SETIMR) or Schedule Wakeup ($SCHDWK) service.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$BINTIM  timbuf ,timadr

    C Prototype

      int sys$bintim  (void *timbuf, struct _generic_64 *timadr);

23.1  –  Arguments

 timbuf

    OpenVMS usage:time_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Buffer that holds the ASCII time to be converted. The timbuf
    argument specifies the 32- or 64-bit address of a character
    string descriptor pointing to the time string. The time string
    specifies the absolute or delta time to be converted by $BINTIM.

 timadr

    OpenVMS usage:date_time
    type:         quadword
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Time value that $BINTIM has converted. The timadr argument is the
    32- or 64-bit address of the quadword system time, which receives
    the converted time.

24  –  $BINUTC

    Converts an ASCII string to an absolute time value in the 128-bit
    UTC format.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$BINUTC  timbuf ,utcadr

    C Prototype

      int sys$binutc  (void *timbuf, unsigned int *utcadr [4]);

24.1  –  Arguments

 timbuf

    OpenVMS usage:time_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Buffer that holds the ASCII time to be converted. The timbuf
    argument specifies the 32- or 64-bit address of a character
    string descriptor pointing to a local time string. The time
    string specifies the absolute time to be converted by $BINUTC.

 utcadr

    OpenVMS usage:coordinated universal time
    type:         utc_date_time
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Time value that $BINUTC has converted. The utcadr argument is
    the 32- or 64-bit address of a 16-byte location to receive the
    converted time.

25  –  $BRKTHRU

    Sends a message to one or more terminals. The $BRKTHRU service
    completes asynchronously; that is, it returns to the caller after
    queuing the message request, without waiting for the message to
    be written to the specified terminals.

    For synchronous completion, use the Breakthrough and Wait
    ($BRKTHRUW) service. The $BRKTHRUW service is identical to the
    $BRKTHRU service in every way except that $BRKTHRUW returns
    to the caller after the message is written to the specified
    terminals.

    The $BRKTHRU service supersedes the Broadcast ($BRDCST) service.
    When writing new programs, you should use $BRKTHRU instead of
    $BRDCST. When updating old programs, you should change all uses
    of $BRDCST to $BRKTHRU.

    Format

      SYS$BRKTHRU  [efn] ,msgbuf [,sendto] [,sndtyp] [,iosb]

                   [,carcon] [,flags] [,reqid] [,timout] [,astadr]

                   [,astprm]

    C Prototype

      int sys$brkthru  (unsigned int efn, void *msgbuf, void *sendto,

                       unsigned int sndtyp, struct _iosb *iosb,

                       unsigned int carcon, unsigned int flags,

                       unsigned int reqid, unsigned int timout, void

                       (*astadr)(__unknown_params), int astprm);

25.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when the message has been
    written to the specified terminals. The efn argument is a
    longword containing this number; however, $BRKTHRU uses only
    the low-order byte.

    When the message request is queued, $BRKTHRU clears the specified
    event flag (or event flag 0 if efn is not specified). Then, after
    the message is sent, $BRKTHRU sets the specified event flag (or
    event flag 0).

 msgbuf

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Message text to be sent to the specified terminals. The msgbuf
    argument is the address of a descriptor pointing to this message
    text.

    The $BRKTHRU service allows the message text to be as long as
    16,350 bytes; however, both the system parameter MAXBUF and the
    caller's available process space can affect the maximum length of
    the message text.

 sendto

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of a single device (terminal) or single user name to which
    the message is to be sent. The sendto argument is the address of
    a descriptor pointing to this name.

    The sendto argument is used in conjunction with the sndtyp
    argument. When sndtyp specifies BRK$C_DEVICE or BRK$C_USERNAME,
    the sendto argument is required.

    If you do not specify sndtyp or if sndtyp does not specify BRK$C_
    DEVICE or BRK$C_USERNAME, you should not specify sendto; if
    sendto is specified, $BRKTHRU ignores it.

 sndtyp

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Terminal type to which $BRKTHRU is to send the message. The
    sndtyp argument is a longword value specifying the terminal type.

    Each terminal type has a symbolic name, which is defined by the
    $BRKDEF macro. The following table describes each terminal type:

    Terminal Type   Description

    BRK$C_          When specified, $BRKTHRU sends the message to all
    ALLTERMS        terminals at which users are logged in and to all
                    other terminals that are connected to the system
                    except those with the AUTOBAUD characteristic
                    set.

    BRK$C_          When specified, $BRKTHRU sends the message to all
    ALLUSERS        users who are currently logged in to the system.

    BRK$C_DEVICE    When specified, $BRKTHRU sends the message to a
                    single terminal; you must specify the name of the
                    terminal by using the sendto argument.

    BRK$C_          When specified, $BRKTHRU sends the message to a
    USERNAME        user with a specified user name; you must specify
                    the user name by using the sendto argument.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block that is to receive the final completion status.
    The iosb argument is the address of this quadword block.

    When the iosb argument is specified, $BRKTHRU sets the quadword
    to 0 when it queues the message request. Then, after the message
    is sent to the specified terminals, $BRKTHRU returns four
    informational items, one item per word, in the quadword I/O
    status block.

    These informational items indicate the status of the messages
    sent only to terminals and mailboxes on the local node; these
    items do not include the status of messages sent to terminals and
    mailboxes on other nodes in an OpenVMS Cluster system.

    The following table shows each word of the quadword block and the
    informational item it contains:

    Word Informational Item

    1    A condition value describing the final completion status.
    2    A decimal number indicating the number of terminals and
         mailboxes to which $BRKTHRU successfully sent the message.
    3    A decimal number indicating the number of terminals to which
         $BRKTHRU failed to send the message because the write to the
         terminals timed out.
    4    A decimal number indicating the number of terminals to which
         $BRKTHRU failed to send the message because the terminals
         were set to the NOBROADCAST characteristic (by using the DCL
         command SET TERMINAL/NOBROADCAST).

 carcon

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Carriage control specifier indicating the carriage control
    sequence to follow the message that $BRKTHRU sends to the
    terminals. The carcon argument is a longword containing the
    carriage control specifier.

    For a list of the carriage control specifiers that you can use
    in the carcon argument, see the VSI OpenVMS I/O User's Reference
    Manual.

    If you do not specify the carcon argument, $BRKTHRU uses a
    default value of 32, which represents a space in the ASCII
    character set. The message format resulting from this default
    value is a line feed, the message text, and a carriage return.

    The carcon argument has no effect on message formatting
    specified by the BRK$M_SCREEN flag in the flags argument. See
    the description of the flags argument.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag bit mask specifying options for the $BRKTHRU operation. The
    flags argument is a longword value that is the logical OR of each
    desired flag option.

    Each flag option has a symbolic name. The $BRKDEF macro defines
    the following symbolic names:

    Symbolic Name    Description

    BRK$V_ERASE_     When specified with the BRK$M_SCREEN flag,
    LINES            BRK$V_ERASE_LINES causes a specified number of
                     lines to be cleared from the screen before the
                     message is displayed. When BRK$M_SCREEN is not
                     also specified, BRK$V_ERASE_LINES is ignored.

                     Unlike the other Boolean flags, BRK$V_ERASE_
                     LINES specifies a 1-byte integer in the range
                     0 to 24. It occupies the first byte in the
                     longword flag mask. In coding the call to
                     $BRKTHRU, specify the desired integer value in
                     the OR operation with any other desired flags.

    BRK$M_SCREEN     When specified, $BRKTHRU sends screen-formatted
                     messages as well as messages formatted through
                     the use of the carcon argument. $BRKTHRU sends
                     screen-formatted messages to terminals with
                     the DEC_CRT characteristic, and it sends
                     messages formatted by carcon to those without
                     the DEC_CRT characteristic. You set the DEC_CRT
                     characteristic for the terminal by using the DCL
                     command SET TERMINAL/DEC_CRT.

                     A screen-formatted message is displayed at the
                     top of the terminal screen, and the cursor is
                     repositioned at the point it was prior to the
                     broadcast message. However, the BRK$V_ERASE_
                     LINES and BRK$M_BOTTOM flags also affect the
                     display.

    BRK$M_BOTTOM     When BRK$M_BOTTOM is specified and BRK$M_SCREEN
                     is also specified, $BRKTHRU writes the message
                     to the bottom of the terminal screen instead of
                     the top. BRK$M_BOTTOM is ignored if the BRK$M_
                     SCREEN flag is not set.

    BRK$M_           When BRK$M_NOREFRESH is specified, $BRKTHRU,
    NOREFRESH        after writing the message to the screen, does
                     not redisplay the last line of a read operation
                     that was interrupted by the broadcast message.
                     This flag is useful only when the BRK$M_SCREEN
                     flag is not specified, because BRK$M_NOREFRESH
                     is the default for screen-formatted messages.

    BRK$M_CLUSTER    Specifying BRK$M_CLUSTER enables $BRKTHRU to
                     send the message to terminals or mailboxes on
                     other nodes in an OpenVMS Cluster system. If
                     BRK$M_CLUSTER is not specified, $BRKTHRU sends
                     messages only to terminals or mailboxes on the
                     local node.

 reqid

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Class requester identification, which identifies to $BRKTHRU
    the application (or image) that is calling $BRKTHRU. The reqid
    argument is this longword identification value.

    The reqid argument is used by several images that send messages
    to terminals and can be used by as many as 16 different user
    images as well.

    When such an image calls $BRKTHRU, specifying reqid, $BRKTHRU
    notifies the terminal that this image wants to write to the
    terminal. This makes it possible for you to allow the image to
    write or prevent it from writing to the terminal.

    To prevent a particular image from writing to your
    terminal, you use the image's name in the DCL command SET
    TERMINAL/NOBROADCAST=image-name. Note that image-name in this
    DCL command is the same as the value of the reqid argument that
    the image passed to $BRKTHRU.

    For example, you can prevent the Mail utility (which is an image)
    from writing to the terminal by entering the DCL command SET
    BROADCAST=NOMAIL.

    The $BRKDEF macro defines class names that are used by several
    OpenVMS components. These components specify their class names by
    using the reqid argument in calls to $BRKTHRU. The $BRKDEF macro
    also defines 16 class names (BRK$C_USER1 through BRK$C_USER16)
    for the use of user images that call $BRKTHRU. The class names
    and the components to which they correspond are as follows:

    Class Name       Component

    BRK$C_GENERAL    This class name is used by the image invoked
                     by the DCL command REPLY and the callers of the
                     $BRKTHRU service. This is the default if the
                     reqid argument is not specified.
    BRK$C_PHONE      This class name is used by the OpenVMS Phone
                     utility.
    BRK$C_MAIL       This class name is used by the OpenVMS Mail
                     utility.
    BRK$C_DCL        This class name is used by the DIGITAL Command
                     Language (DCL) interpreter for the Ctrl/T
                     command, which displays the process status.
    BRK$C_QUEUE      This class name is used by the queue manager,
                     which manages print and batch jobs.
    BRK$C_SHUTDOWN   This class name is used by the system shutdown
                     image, which is invoked by the DCL command
                     REPLY/ID=SHUTDOWN.
    BRK$C_URGENT     This class name is used by the image invoked by
                     the DCL command REPLY/ID=URGENT.
    BRK$C_USER1      These class names can be used by user-written
    through BRK$C_   images.
    USER16

 timout

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Timeout value, which is the number of seconds that must elapse
    before an attempted write by $BRKTHRU to a terminal is considered
    to have failed. The timout argument is this longword value (in
    seconds).

    Because $BRKTHRU calls the $QIO service to perform write
    operations to the terminal, the timeout value specifies the
    number of seconds allotted to $QIO to perform a single write
    operation to the terminal.

    If you do not specify the timout argument, $BRKTHRU uses a
    default value of 0 seconds, which specifies infinite time (no
    timeout occurs).

    The value specified by timout can be 0 or any number greater than
    4; the numbers 1, 2, 3, and 4 are illegal.

    When you press Ctrl/S or the No Scroll key, $BRKTHRU cannot send
    a message to the terminal. In such a case, the value of timout is
    usually exceeded and the attempted write to the terminal fails.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    AST service routine to be executed after $BRKTHRU has sent the
    message to the specified terminals. 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 $BRKTHRU.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    AST parameter to be passed to the AST routine specified by the
    astadr argument. The astprm argument specifies this longword
    parameter.

26  –  $BRKTHRUW

    Sends a message to one or more terminals. The $BRKTHRUW service
    operates synchronously; that is, it returns to the caller after
    the message has been sent to the specified terminals.

    For asynchronous operations, use the Breakthrough ($BRKTHRU)
    service; $BRKTHRU returns to the caller after queuing the message
    request, without waiting for the message to be delivered.

    Aside from the preceding, $BRKTHRUW is identical to $BRKTHRU.
    For all other information about the $BRKTHRUW service, see the
    description of $BRKTHRU.

    The $BRKTHRU and $BRKTHRUW services supersede the Broadcast
    ($BRDCST) service. When writing new programs, you should use
    $BRKTHRU or $BRKTHRUW instead of $BRDCST. When updating old
    programs, you should change all uses of $BRDCST to $BRKTHRU or
    $BRKTHRUW. $BRDCST is now an obsolete system service and is no
    longer being enhanced.

    Format

      SYS$BRKTHRUW  [efn] ,msgbuf [,sendto] [,sndtyp] [,iosb]

                    [,carcon] [,flags] [,reqid] [,timout] [,astadr]

                    [,astprm]

    C Prototype

      int sys$brkthruw  (unsigned int efn, void *msgbuf, void

                        *sendto, unsigned int sndtyp, struct _iosb

                        *iosb, unsigned int carcon, unsigned int

                        flags, unsigned int reqid, unsigned int

                        timout, void (*astadr)(__unknown_params),int

                        astprm);

27  –  $CANCEL

    Cancels all pending I/O requests on a specified channel. In
    general, this includes all I/O requests that are queued, as well
    as the request currently in progress.

    Format

      SYS$CANCEL  chan

    C Prototype

      int sys$cancel  (unsigned short int chan);

27.1  –  Argument

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    I/O channel on which I/O is to be canceled. The chan argument is
    a word containing the channel number.

28  –  $CANEXH

    Deletes an exit control block from the list of control blocks for
    the calling access mode. Exit control blocks are declared by the
    Declare Exit Handler ($DCLEXH) service and are queued according
    to access mode in a last-in first-out order.

    Format

      SYS$CANEXH  [desblk]

    C Prototype

      int sys$canexh  (void *desblk);

28.1  –  Argument

 desblk

    OpenVMS usage:exit_handler_block
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Control block describing the exit handler to be canceled. If you
    do not specify the desblk argument or specify it as 0, all exit
    control blocks are canceled for the current access mode. The
    desblk argument is the address of this control block.

29  –  $CANTIM

    Cancels all or a selected subset of the Set Timer requests
    previously issued by the current image executing in a process.
    Cancellation is based on the request identification specified
    in the Set Timer ($SETIMR) service. If you give the same request
    identification to more than one timer request, all requests with
    that request identification are canceled.

    Format

      SYS$CANTIM  [reqidt] ,[acmode]

    C Prototype

      int sys$cantim  (unsigned __int64 reqidt, unsigned int acmode);

29.1  –  Arguments

 reqidt

    OpenVMS usage:user_arg
    type:         quadword
    access:       read only
    mechanism:    by value
    Request identification of the timer requests to be canceled.
    If you specify it as 0 (the default), all timer requests are
    canceled. The reqidt argument is a quadword containing this
    identification.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode of the requests to be canceled. The acmode argument
    is a longword containing the access mode.

    The $PSLDEF macro defines the following symbols for the four
    access modes:

    Symbol         Access Mode

    PSL$C_KERNEL   Kernel
    PSL$C_EXEC     Executive
    PSL$C_SUPER    Supervisor
    PSL$C_USER     User

    The most privileged access mode used is the access mode of the
    caller.

30  –  $CANWAK

    Removes all scheduled wakeup requests for a process from the
    timer queue, including those made by the caller or by other
    processes. The Schedule Wakeup ($SCHDWK) service makes scheduled
    wakeup requests.

    Format

      SYS$CANWAK  [pidadr] ,[prcnam]

    C Prototype

      int sys$canwak  (unsigned int *pidadr, void *prcnam);

30.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) of the process for which wakeups are
    to be canceled. The pidadr argument is the address of a longword
    specifying the PID. The pidadr argument can refer to a process
    running on the local node or a process running on another node in
    the OpenVMS Cluster system.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the process for which wakeups are to be canceled. The
    prcnam argument is the address of a character string descriptor
    pointing to the process name string.

    A process running on the local node can be identified with a 1-
    to 15-character string. To identify a process on a specific node
    in a cluster, specify the full process name, which includes the
    node name as well as the process name. The full process name can
    contain up to 23 characters.

    The operating system interprets the UIC group number of the
    calling process as part of the process name; the names of
    processes are unique to UIC groups. Because of this, you can
    use the prcnam argument only on behalf of processes in the same
    group as the calling process.

31  –  $CHECK ACCESS

    Determines on behalf of a third-party user whether a named user
    can access the object specified.

    Format

      SYS$CHECK_ACCESS  [objtyp], [objnam], [usrnam], itmlst,

                        [contxt], [clsnam], [objpro], [usrpro]

    C Prototype

      int sys$check_access  (unsigned int *objtyp, void *objnam,

                            void *usrnam, void *itmlst, unsigned int

                            *contxt, void *clsnam, void *objpro, void

                            *usrpro);

31.1  –  Arguments

 objtyp

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Type of object being accessed. The objtyp argument is the address
    of a longword containing a value specifying the type of object.

    The appropriate symbols are listed in the following table and are
    defined in the system macro $ACLDEF library:

    Symbol                   Meaning

    ACL$C_CAPABILITY         Object is a restricted resource; use the
                             reserved name VECTOR.
    ACL$C_DEVICE             Object is a device.
    ACL$C_FILE               Object is a Files-11 On-Disk Structure
                             Level 2 file.
    ACL$C_GROUP_GLOBAL_      Object is a group global section.
    SECTION
    ACL$C_JOBCTL_QUEUE       Object is a batch, print, or server
                             queue.
    ACL$C_LOGICAL_NAME_      Object is a logical name table.
    TABLE
    ACL$C_SYSTEM_GLOBAL_     Object is a system global section.
    SECTION

    For further information about these symbols, see the description
    of the clsnam argument.

 objnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the object being accessed. The objnam argument is the
    address of a character-string descriptor pointing to the object
    name.

 usrnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the user attempting access. The usrnam argument is the
    address of a descriptor that points to a character string that
    contains the name of the user attempting to gain access to the
    specified object. The user name string can contain a maximum of
    12 alphanumeric characters.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Attributes describing how the object is to be accessed and
    information returned after $CHECK_ACCESS performs the protection
    check (for instance, security alarm information).

    For each item code, you must include a set of four elements and
    end the list with a longword containing the value 0 (CHP$_END).

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

 contxt

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read-write
    mechanism:    by reference
    Longword used to maintain the user authorization file (UAF)
    context. The contxt argument is the address of a longword
    to receive a UAI context longword. On the initial call, this
    longword should contain the value -1. On subsequent calls, the
    value of the contxt argument from the previous call should be
    passed back in.

    Using the contxt argument keeps the UAF open across all calls,
    thereby improving the performance of the system on subsequent
    calls. To close the UAF, you must run down the image.

    The resulting contxt value from a $CHECK_ACCESS call can also be
    used as the input contxt argument to the $GETUAI system service,
    and vice versa.

 clsnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Object class name associated with the protected object. The
    clsnam argument is the address of a descriptor pointing to the
    name of the object class associated with the object specified by
    either the objnam or the objpro argument. The clsnam and objtyp
    arguments are mutually exclusive. The clsnam argument is the
    preferred argument to $CHECK_ACCESS. The following object class
    names are valid:

    CAPABILITY                  QUEUE
    COMMON_EVENT_CLUSTER        RESOURCE_DOMAIN
    DEVICE                      SECURITY_CLASS
    FILE                        SYSTEM_GLOBAL_SECTION
    GROUP_GLOBAL_SECTION        VOLUME
    LOGICAL_NAME_TABLE

 objpro

    OpenVMS usage:char_string
    type:         opaque byte stream or object handle
    access:       read only
    mechanism:    by descriptor
    Buffer containing an object security profile or object handle.
    The objpro argument is the address of a descriptor pointing to
    a buffer that contains an encoded object security profile or the
    address of a descriptor pointing to an object handle.

    Object handles vary according to the associated security object
    class. Currently, the only supported object handles are for the
    file and device class objects where the object handle is a word
    or longword channel.

    The objpro and objnam arguments are mutually exclusive unless the
    objpro argument is a simple object handle. The objpro and usrpro
    arguments are also mutually exclusive unless the objpro argument
    is an object handle.

 usrpro

    OpenVMS usage:char_string
    type:         opaque byte stream
    access:       read only
    mechanism:    by descriptor
    Buffer containing a user security profile. The usrpro argument is
    the address of a descriptor pointing to a buffer that contains an
    encoded user security profile.

    The $CREATE_USER_PROFILE service can be used to construct a user
    security profile. The usrpro and usrnam arguments are mutually
    exclusive. The objpro and usrpro arguments are also mutually
    exclusive unless the objpro argument is an object handle.

32  –  $CHECK FEN (Alpha and Integrity servers)

    On Alpha and Integrity server systems, indicates whether floating
    point is enabled for the current image.

    Format

      SYS$CHECK_FEN  [flags]

    C Prototype

      int sys$check_fen  (unsigned int *flags);

32.1  –  Arguments

 flags

    OpenVMS usage:mask longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    For architectures that have multiple floating-point resources
    that can be enabled separately, this longword is returned with a
    bitmask indicating which resources are enabled. On Alpha systems,
    no separate resources exist; nothing is returned. On Integrity
    server systems, the bitmask has two bits: bit 0 for the low
    floating-point bank and bit 1 for the high floating-point bank.

33  –  $CHECK PRIVILEGE

    Determines whether the caller has the specified privileges
    or identifier. In addition to checking for a privilege or an
    identifier, $CHECK_PRIVILEGE determines if the caller's use of
    privilege needs to be audited.

    Format

      SYS$CHECK_PRIVILEGE  [efn] ,prvadr ,[altprv] ,[flags] ,[itmlst]

                           ,[audsts] ,[astadr] ,[astprm]

    C Prototype

      int sys$check_privilege  (unsigned int efn, struct _generic_64

                               *prvadr, struct _generic_64

                               *altprv, unsigned int flags, void

                               *itmlst, unsigned int *audsts, void

                               (*astadr)(__unknown_params), int

                               astprm);

33.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when the audit completes. The
    efn argument is a longword containing the number of the event
    flag; however, $CHECK_PRIVILEGE uses only the low-order byte. If
    efn is not specified, event flag 0 is used.

    Upon request initiation, $CHECK_PRIVILEGE clears the specified
    event flag.

 prvadr

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    The privilege, privileges, or identifier that the calling process
    must possess.

    The prvadr argument is either the address of a quadword bit
    array, where each bit corresponds to a privilege, or the address
    of a quadword identifier.

    When the array lists privileges, each bit has a symbolic name.
    The $PRVDEF macro defines these names. You form the bit array
    by specifying the symbolic name of each desired privilege in a
    logical OR operation. See the $SETPRV system service for the
    symbolic name and description of each privilege.

    If the caller passes an identifier, the caller must set the
    NSA$M_IDENTIFIER bit in the flags longword. The identifier
    structure is defined by the $KGBDEF macro. The identifier
    attributes (KGB$) are reserved for future use and should be set
    to 0.

 altprv

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Alternate privilege mask to check against. The altprv argument
    is the address of a quadword privilege mask, where each bit
    corresponds to a privilege. This argument and the flags NSA$M_
    AUTHPRIV, NSA$M_IDENTIFIER, and NSA$M_PROCPRIV are mutually
    exclusive.

    With this argument, $CHECK_PRIVILEGE uses the supplied set of
    privileges instead of the current, active privileges. Each bit
    in the mask has a symbolic name, defined by the $PRVDEF macro.
    You form the bit array by specifying the symbolic name of each
    desired privilege in a logical OR operation. See the $SETPRV
    system service for the symbolic name and description of each
    privilege.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags that specify options for the $CHECK_PRIVILEGE operation.
    The flags argument is a longword bit mask, where each bit
    corresponds to an option.

    Each flag option has a symbolic name. The $NSADEF macro defines
    the following symbolic names. Be aware that the flags NSA$M_
    AUTHPRIV, NSA$M_IDENTIFIER, and NSA$M_PROCPRIV are mutually
    exclusive; therefore, you can specify only one of these flag
    options.

    Symbolic Name      Description

    NSA$M_AUTHPRIV     Checks the authorized privileges of the
                       process instead of the current (active)
                       privileges.
    NSA$M_FLUSH        Specifies that all messages in the audit
                       server buffer be written to the audit log
                       file.
    NSA$M_IDENTIFIER   Interprets the prvadr argument as the address
                       of an identifier instead of a privilege mask.
    NSA$M_INTERNAL     Specifies that the $CHECK_PRIVILEGE call
                       originates in the context of a trusted
                       computing base (TCB) component. The auditing
                       components use this flag to indicate that
                       internal auditing failures should result in a
                       SECAUDTCB bugcheck. This flag is reserved to
                       VSI.
    NSA$M_MANDATORY    Specifies that an audit is to be performed,
                       regardless of system alarm and audit settings.
    NSA$M_PROCPRIV     Checks the permanent privileges of the
                       process, instead of the privileges in the
                       current (active) mask.
    NSA$M_SERVER       Indicates that the call originates in a TCB
                       server process and that the event should be
                       audited regardless of the state of a process-
                       specific no-audit bit.

                       Trusted servers use this flag to override
                       the no-audit bit when they want to perform
                       explicit auditing on behalf of a client
                       process. This flag is Reserved to VSI.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying additional security auditing information
    to be included in any security audit that is generated by the
    service. The itmlst argument is the address of a list of item
    descriptors, each of which describes an item of information. The
    list of item descriptors is terminated by a longword of 0.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

 audsts

    OpenVMS usage:cond_value_type
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Longword condition value that receives a final completion status
    from the operation. If a security audit is required, the final
    completion status represents either the successful completion of
    the resulting security audit or any failing status that occurred
    while the security audit was performed within the AUDIT_SERVER
    process.

    The audsts argument is valid only when the service returns
    success and the status is not SS$_EVTNOTENAB. In addition, the
    caller must either make use of the astadr argument or use the
    $CHECK_PRIVILEGEW service before attempting to access audsts.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    Asynchronous system trap (AST) routine to be executed after the
    audsts argument is written. The astadr argument, which is the
    address of a longword value, is the procedure value of the AST
    routine.

    The AST routine executes in the access mode of the caller of
    $CHECK_PRIVILEGE.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Asynchronous system trap (AST) parameter passed to the AST
    service routine. The astprm argument is a longword value
    containing the AST parameter.

34  –  $CHECK PRIVILEGEW

    Determines whether the caller has the specified privileges
    or identifier. In addition to checking for a privilege or an
    identifier, the Check Privilege and Wait service determines if
    the caller's use of privilege needs to be audited.

    $CHECK_PRIVILEGEW completes synchronously; that is, it returns
    the final status to the caller only after receiving an explicit
    confirmation from the audit server that the associated audit, if
    enabled, has been performed.

    Format

      SYS$CHECK_PRIVILEGEW  efn ,prvadr ,[altprv] ,[flags] ,[itmlst]

                            ,audsts ,[astadr] ,[astprm]

    C Prototype

      int sys$check_privilegew  (unsigned int efn, struct _generic_64

                                *prvadr, struct _generic_64

                                *altprv, unsigned int flags, void

                                *itmlst, unsigned int *audsts, void

                                (*astadr)(__unknown_params), int

                                astprm);

35  –  $CHKPRO

    Determines whether an accessor with the specified rights and
    privileges can access an object with the specified attributes.

    Format

      SYS$CHKPRO  itmlst ,[objpro] ,[usrpro]

    C Prototype

      int sys$chkpro  (void *itmlst, void *objpro, void *usrpro);

35.1  –  Argument

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Protection attributes of the object and the rights and privileges
    of the accessor. The itmlst argument is the address of an item
    list of descriptors used to specify the protection attributes of
    the object and the rights and privileges of the accessor.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

    Specifying any specific protection attribute causes that
    protection check to be made; any protection attribute not
    specified is not checked. Rights and privileges specified are
    used as needed. If a protection check requires any right or
    privilege not specified in the item list, the right or privilege
    of the caller's process is used.

 objpro

    OpenVMS usage:char_string
    type:         opaque byte stream
    access:       read only
    mechanism:    by descriptor
    Buffer containing an object security profile. The objpro
    argument is the address of a descriptor pointing to a buffer
    that contains an encoded object security profile. The objpro
    argument eliminates the need to supply all of the component
    object protection attributes with the $CHKPRO item list. The
    objpro argument is currently Reserved to VSI.

 usrpro

    OpenVMS usage:char_string
    type:         opaque byte stream
    access:       read only
    mechanism:    by descriptor
    Buffer containing a user security profile. The usrpro argument is
    the address of a descriptor pointing to a buffer that contains an
    encoded user security profile. The usrpro argument eliminates the
    need to supply all of the component user security attributes with
    the $CHKPRO item list.

    The $CREATE_USER_PROFILE service can be used to construct a user
    security profile. When the usrpro argument is specified, any
    component user profile attributes specified in the $CHKPRO item
    list replace those contained in the user security profile.

36  –  $CLEAR SYSTEM EVENT (Alpha and Integrity servers)

    Removes one or more notification requests previously established
    by a call to $SET_SYSTEM_EVENT.

    This service does not allow you to specify a handle and an
    event. You must pass a zero as one of these parameters. You can
    either clear by handle or request that all events for the user be
    cleared.

    Format

      SYS$CLEAR_SYSTEM_EVENT  [handle] ,[acmode] ,event

    C Prototype

      int sys$clear_system_event  (struct _generic_64 * handle,

                                  unsigned int acmode, unsigned int

                                  event);

36.1  –  Arguments

 handle

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Identification of the AST request to be cleared. The handle
    argument uniquely identifies the request and is returned when
    the $SET_SYSTEM_EVENT service is called. The handle argument may
    be omitted by specifying a zero address.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode of the system event to be cleared. The acmode
    argument is a longword containing the access mode. The value of
    the access mode is maximized with the access mode of the caller.

 event

    OpenVMS usage:event_code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The event argument is a value indicating the type of system event
    to be cleared. SYSEVT$C_ALL_EVENTS may be specified to clear all
    event types.

37  –  $CLEAR UNWIND TABLE (Integrity servers Only)

    Clears unwind table (UT) information.

    Format

      SYS$CLEAR_UNWIND_TABLE  code_base_va

    C Prototype

      int SYS$CLEAR_UNWIND_TABLE  (unsigned __int64 code_base_va);

37.1  –  Arguments

 code_base_va

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        read only
    mechanism:     by value
    Input by value. Must be the process virtual address of the start
    of a registered code range.

38  –  $CLOSE

    The Close service terminates file processing and closes the file.
    This service performs an implicit Disconnect service for all
    record streams associated with the file.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

39  –  $CLRAST

    Clears the "AST active" status.

    This enables delivery of asynchronous system traps (ASTs) for the
    access mode from which the service call was issued, while an AST
    routine is active.

                                   NOTE

       The explicit use of $CLRAST is strongly discouraged, as
       it complicates synchronization issues and may lead to the
       unbounded consumption of stack space.

    Normally, AST delivery for a particular access mode is deferred
    while an AST routine is executing in that access mode. When the
    AST routine returns, an implicit call is made to $CLRAST to re-
    enable AST delivery.

    Explicitly calling $CLRAST within an AST routine allows the
    delivery of ASTs for the access mode from which the service call
    was issued, prior to completion of the active AST routine.

    Format

      SYS$CLRAST

39.1  –  Arguments

    None.

40  –  $CLRCLUEVT

    Removes one or more notification requests previously established
    by a call to SYS$SETCLUEVT.

    Format

      SYS$CLRCLUEVT  [handle] ,[acmode] ,[event]

    C Prototype

      int sys$clrcluevt  (struct _cluevthndl *handle, unsigned int

                         acmode, unsigned int event);

40.1  –  Arguments

 handle

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Identification of the AST request to be canceled. The handle
    argument uniquely identifies the request and is returned when the
    $SETCLUEVT service is called.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode of the cluster configuration event to be canceled.
    The acmode argument is a longword containing the access mode.

    Each access mode has a symbolic name. The $PSLDEF macro defines
    the following symbols for the four access types:

    Symbol         Access Mode

    PSL$C_KERNEL   Kernel
    PSL$C_EXEC     Executive
    PSL$C_SUPER    Supervisor
    PSL$C_USER     User

 event

    OpenVMS usage:event_code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Event code indicating the type of cluster configuration event for
    which an AST is no longer to be delivered. The event argument is
    a value indicating which type of event is no longer of interest.

    Each event type has a symbolic name. The $CLUEVTDEF macro defines
    the following symbolic names:

    Symbolic Name      Description

    CLUEVT$C_ADD       One or more OpenVMS nodes have been added to
                       the OpenVMS Cluster system.
    CLUEVT$C_REMOVE    One or more OpenVMS nodes have been removed
                       from the OpenVMS Cluster system.

41  –  $CLREF

    Clears (sets to 0) an event flag in a local or common event flag
    cluster.

    Format

      SYS$CLREF  efn

    C Prototype

      int sys$clref  (unsigned int efn);

41.1  –  Argument

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be cleared. The efn argument is a
    longword containing this number; however, $CLREF uses only the
    low-order byte.

42  –  $CMEXEC

    Changes the access mode of the calling process to executive mode.

    Format

      SYS$CMEXEC  routin ,[arglst]

    C Prototype

      int sys$cmexec  (int (*routin)(__unknown_params), unsigned int

                      *arglst);

42.1  –  Arguments

 routin

    OpenVMS usage:procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    Routine to be executed while the process is in executive mode.
    The routin argument is the address of this routine.

 arglst

    OpenVMS usage:arg_list
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Argument list to be passed to the routine specified by the routin
    argument. The arglst argument is the address of this argument
    list.

    If the arglst value is nonzero and is not accessible as an
    address or if the routine is inaccessible, the service returns
    SS$_ACCVIO.

    Alpha and Integrity server systems require a pointer to a valid
    argument list or a value of 0 in the arglst argument. This means
    that the arglst argument must contain an accessible virtual
    address for an argument list, the first longword of which must
    be a valid list size.

43  –  $CMEXEC 64

    On Alpha and Integrity server systems, changes the access mode of
    the calling process to executive mode.

    This service accepts 64-bit addresses.

    Format

      SYS$CMEXEC_64  routin_64 ,arglst_64

    C Prototype

      int sys$cmexec_64  (int (*routin_64)(__unknown_params),

                         unsigned __int64 *arglst_64);

43.1  –  Arguments

 routin_64

    OpenVMS usage:procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference
    Routine to be executed while the process is in executive mode.
    The routin_64 argument is the 32- or 64-bit address of this
    routine.

 arglst_64

    OpenVMS usage:arg_list
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Argument list to be passed to the routine specified by the
    routin_64 argument. The arglst_64 argument is the 32- or 64-bit
    address of this argument list.

    If the arglst value is nonzero and is not accessible as an
    address or if the routine is inaccessible, the service returns
    SS$_ACCVIO.

    Alpha and Integrity server systems require a pointer to a valid
    argument list or a value of 0 in the arglst_64 argument. This
    means that the arglst_64 argument, if nonzero, must contain
    an accessible virtual address for an argument list, the first
    quadword of which must be a number between 0 and 255 specifying
    the number of quadwords that follow it on the list.

44  –  $CMKRNL

    Changes the access mode of the calling process to kernel mode.
    This service allows a process to change its access mode to
    kernel, execute a specified routine, and then return to the
    access mode in effect before the call was issued.

    Format

      SYS$CMKRNL  routin ,[arglst]

    C Prototype

      int sys$cmkrnl  (int (*routin)(__unknown_params), unsigned int

                      *arglst);

44.1  –  Arguments

 routin

    OpenVMS usage:procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    Routine to be executed while the process is in kernel mode. The
    routin argument is the address of this routine.

 arglst

    OpenVMS usage:arg_list
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Argument list to be passed to the routine specified by the routin
    argument. The arglst argument is the address of this argument
    list.

    If the arglst value is nonzero and is not accessible as an
    address or if the routine is inaccessible, the service returns
    SS$_ACCVIO.

    Alpha systems require a pointer to a valid argument list or a
    value of 0 in the arglst argument. This means that the arglst
    argument must contain an accessible virtual address for an
    argument list, the first longword of which must be a valid list
    size.

45  –  $CMKRNL 64

    On Alpha and Integrity server systems, changes the access mode of
    the calling process to kernel mode. This service allows a process
    to change its access mode to kernel, execute a specified routine,
    and then return to the access mode in effect before the call was
    issued.

    This service accepts 64-bit addresses.

    Format

      SYS$CMKRNL_64  routin_64 ,arglst_64

    C Prototype

      int sys$cmkrnl_64  (int (*routin_64)(__unknown_params),

                         unsigned __int64 *arglst_64);

45.1  –  Arguments

 routin_64

    OpenVMS usage:procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference
    Routine to be executed while the process is in kernel mode. The
    routin_64 argument is the 32- or 64-bit address of this routine.

 arglst_64

    OpenVMS usage:arg_list
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Quadword argument list to be passed to the routine specified
    by the routin_64 argument. The routin_64 argument is the 32- or
    64-bit address of this routine.

    If the arglst value is nonzero and is not accessible as an
    address or if the routine is inaccessible, the service returns
    SS$_ACCVIO.

    Alpha and Integrity server systems require a pointer to a valid
    argument list or a value of 0 in the arglst_64 argument. This
    means that the arglst_64 argument, if nonzero, must contain
    an accessible virtual address for an argument list, the first
    quadword of which must be a number between 0 and 255 specifying
    the number of quadwords that follow it on the list.

46  –  $CONNECT

    The Connect service establishes a record stream by associating
    and connecting a RAB with a FAB. You can invoke the Connect
    service only for files that are already open.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

47  –  $CPU CAPABILITIES

    On Alpha and Integrity server systems, allows modification of the
    user capability set for a specified CPU, or for the global user
    capability CPU default.

    This service accepts 64-bit addresses.

    Format

      SYS$CPU_CAPABILITIES  cpu_id [,select_mask] [,modify_mask]

                            [,prev_mask] [,flags]

    C Prototype

      int sys$cpu_capabilities  (int cpu_id, struct _generic_64

                                *select_mask, struct _generic_64

                                *modify_mask, struct _generic_64

                                *prev_mask, struct _generic_64

                                *flags);

47.1  –  Arguments

 cpu_id

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Identifier of the CPU whose user capability mask is to be
    modified or returned. The cpu_id argument is a longword
    containing this number, which is in the supported range of
    individual CPUs from 0 to SYI$_MAX_CPUS -1.

    Specifying the constant CAP$K_ALL_ACTIVE_CPUS applies the current
    modification operation to all CPUs currently in the active set,
    and to the default CPU initialization context in SCH$GL_DEFAULT_
    CPU_CAP. If the prev_mask argument is also supplied, the previous
    default CPU initialization context in SCH$GL_DEFAULT_CPU_CAP will
    be returned rather than any specific CPU state.

    To modify only the user capabilities in SCH$GL_DEFAULT_CPU_CAP,
    the flags argument has a bit constant CAP$M_FLAG_DEFAULT_ONLY.
    When this bit is set, all service operations are performed on
    the global cell rather than on an individual CPU specified in
    the cpu_id argument. This bit does not supersede the CAP$K_
    ALL_ACTIVE_CPUS constant, however. If both constants are
    specified, CAP$K_ALL_ACTIVE_CPUS take precedence; nevertheless,
    the operations to SCH$GL_DEFAULT_CPU are identical because that
    function is a direct subset of the other.

 select_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Mask specifying which bits of the specified CPU's user capability
    mask are to be modified. The select_mask argument is the 32-
    or 64-bit address of a quadword bit vector wherein a bit, when
    set, specifies that the corresponding user capability is to be
    modified.

    The individual user capability bits in select_mask can be
    referenced by their symbolic constant names, CAP$M_USER1 through
    CAP$M_USER16. These constants (not zero-relative) specify the
    position in the mask quadword that corresponds to the bit
    name. Multiple capabilities can be selected by connecting the
    appropriate bits with a logical OR operation.

    The constant CAP$K_ALL_USER, when specified in the select_mask
    argument, selects all user capability bits.

 modify_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Mask specifying the settings for those capabilities selected in
    the select_mask argument. The modify_mask argument is the 32-
    or 64-bit address of a quadword bit vector wherein a bit, when
    set, specifies that the corresponding user capability is to be
    added to the specified CPU; when clear, the corresponding user
    capability is to be removed from the specified CPU.

    The bit constants CAP$M_USER1 through CAP$M_USER16 can be used
    to modify the appropriate bit position in modify_mask. Multiple
    capabilities can be modified by connecting the appropriate bits
    with OR.

    To add a specific user capability to the specified CPU, that
    bit position must be set in both select_mask and modify_mask. To
    remove a specific user capability from the specified CPU, that
    bit position must be set in select_mask and cleared in modify_
    mask.

    The symbolic constant CAP$K_ALL_USER_ADD, when specified in
    modify_mask, indicates that all capabilities specified in select_
    mask are to be added to the current user capability set. The
    constant CAP$K_ALL_USER_REMOVE indicates that all capabilities
    specified are to be cleared from the set.

 prev_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Previous user capability mask for the specified CPU before
    execution of this call to $CPU_CAPABILITIES. The prev_mask
    argument is the 32- or 64-bit address of a quadword into which
    $CPU_CAPABILITIES writes a quadword bit mask specifying the
    previous user capabilities.

    If this argument is specified in conjunction with CAP$K_ALL_
    ACTIVE_CPUS as the cpu_id selection constant or with CAP$M_
    FLAG_DEFAULT_ONLY, the user capability portion of the default
    boot initialization state context SCH$GL_DEFAULT_CPU_CAP will be
    returned.

 flags

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Options selected for the user capability modification. The flags
    argument is a quadword bit vector wherein a bit corresponds to an
    option. Only the bits specified in the following table are used;
    the remainder of the quadword bits are reserved and must be 0.

    Each option (bit) has a symbolic name, defined by the $CAPDEF
    macro. The flags argument is constructed by performing a logical
    OR operation using the symbolic names of each desired option.

    The following table describes the symbolic name of each option:

    Symbolic Name          Description

    CAP$M_FLAG_DEFAULT_    Indicates that the specified operations
    ONLY                   are to be performed on the global context
                           cell instead of on a specific CPU.
                           This bit supersedes any individual CPU
                           specified in cpu_id but does not override
                           the all active set behavior (CAP$K_ALL_
                           ACTIVE_CPUS). Specifying this bit constant
                           applies this operation to the default
                           startup capabilities for all CPUs booted
                           for the first time.

    CAP$M_FLAG_CHECK_CPU   Determines whether the kernel thread can
                           be left in a nonrunnable state under
                           some circumstances. No operation of
                           this service allows a transition from a
                           runnable to blocked state; however, if
                           the kernel thread is already at a blocked
                           state, this bit determines whether the
                           result of the operation must leave it
                           runnable. If CAP$M_FLAG_CHECK_CPU is set
                           or flags is not specified, the kernel
                           thread is checked to ensure that it can
                           safely run on one of the CPUs in the
                           active set. If CAP$M_FLAG_CHECK_CPU is
                           not set, any state operations on kernel
                           threads already in a blocked state are
                           allowed.

48  –  $CPU TRANSITION (Alpha and Integrity servers)

    On Alpha and Integrity server systems, changes the current
    processing state of a CPU in the configure set of the current
    system or an unassigned CPU in an OpenVMS Galaxy configuration.
    This service completes asynchronously. For synchronous
    completion, use the $CPU_TRANSITIONW service.

    This service accepts 64-bit addresses. Parameter and bit
    definitions are resolved in $CSTDEF in the appropriate STARLET
    library.

    For more information, see the VSI OpenVMS Alpha Partitioning and
    Galaxy Guide.

    Format

      SYS$CPU_TRANSITION  tran_code ,cpu_id ,nodename ,node_id ,flags

                          ,efn ,iosb ,astadr_64 ,astprm_64

    C Prototype

      int sys$cpu_transition  (int tran_code, int cpu_id,

                              dsc64$descriptor_s_pq nodename, int

                              node_id, uint32 flags, int efn, IOSB

                              *iosb, VOID_PQ astadr, uint64 astprm,

                              uint32 timout);

48.1  –  Arguments

 tran_code

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Identifier specifying the type of state change to be initiated on
    the target CPU. The tran_code argument is a longword containing
    one of the following values:

    Symbolic Name      Description

    CST$K_CPU_STOP     The target CPU is to be removed from the
                       active set and halted into console mode. It
                       remains in the configure set of the current
                       partition.

    CST$K_CPU_MIGRATE  The target CPU is removed from the configure
                       set of the local partition and the console
                       is requested to add it to the configure set
                       of the partition specified in node_id. If
                       the CPU is currently in the active set, it is
                       automatically brought to console mode through
                       the CST$K_CPU_STOP function first.

    CST$K_CPU_START    The target CPU is requested to exit console
                       mode and join the active set of the current
                       partition. The CPU must already be part of the
                       configure set.

    CST$K_CPU_         The CPU is assigned a default target partition
    FAILOVER           where it will automatically migrate on system
                       failure. This assignment persists until it
                       is superseded. To remove an assignment or
                       partition name, the current partition ID
                       should be specified.

    CST$K_CPU_POWER_   The requested operation is initiated on the
    OFF                target CPU to bring the electrical power to
                       the OFF state. If the CPU is currently in
                       the active set, it is automatically brought
                       to console mode through the CST$K_CPU_STOP
                       function first.

    CST$K_CPU_POWER_   The requested operation is initiated on the
    ON                 target CPU to bring the electrical power to
                       the ON state.

    Each $K code represents an end state operation, each of which
    has a specific start state that the CPU must be in, in order to
    initiate the transition.

    This service may automatically initiate a successful completion
    of the requested operation by initiating one or more transparent
    transitions. This operation takes place if the CPU is not in that
    specific start state, and there are an obvious and unique set
    of transitions that can be initiated prior to the specified end
    state.

    Multiple transitions can also be initiated simultaneously through
    the system service tran_code parameter. Each transition code has
    a $M form as shown in the following list, that can be or'd with a
    specific end state $K code:

    o  CST$M_CPU_STOP

    o  CST$M_CPU_MIGRATE

    o  CST$M_CPU_START

    o  CST$M_CPU_FAILOVER

    o  CST$M_CPU_POWER_OFF

    o  CST$M_CPU_POWER_ON

    Any legal combination of transitions can be specified with the $M
    form, however no more than one $K code is allowed.

 cpu_id

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Identifier of the CPU whose state is to be modified. The cpu_
    id argument is a longword number in the supported range of
    individual CPUs from 0 to SYI$_MAX_CPUS - 1.

    Generic identifiers can also be used to allow OpenVMS to select
    the most appropriate resource. The following table lists these
    codes:

    Code                Description

    CST$K_ANY_OWNED_    Any CPU in the configure set, regardless of
    CPU                 the active set state
    CST$K_ANY_ACTIVE_   Any CPU in the active set
    CPU
    CST$K_ANY_STOPPED_  Any CPU in the configure set, but not the
    CPU                 active set

 node_id

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Identifier of the target Galaxy partition in CST$K_CPU_ASSIGN,
    CST$K_CPU_FAILOVER, or CST$K_CPU_MIGRATE transition. The node_id
    argument is a longword containing a number in the supported range
    of IDs provided by the console for the current hardware platform.
    If the nodename parameter is specified, node_id is ignored.

 flags

    OpenVMS usage:longword_mask
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Options selected for the CPU state transition. The flags argument
    is a longword bit vector wherein a bit corresponds to an option.
    Only the bits specified below are used; the remainder of the
    longword bits are reserved and must be 0.

    Each option (bit) has a symbolic name. The flags argument is
    constructed by performing a logical OR operation using the
    symbolic names of the following options:

    Symbolic Name      Description

    CST$V_CPU_         At the completion of the transition, the CPU's
    DEFAULT_           user capabilities are set back to the default
    CAPABILITIES       system value. If this option is not specified,
                       modified user capabilities are maintained
                       across STOP and START transitions as long
                       as the CPU remains in the local partition
                       configure set.

    CST$V_CPU_ALLOW_   The transition is to be allowed even though it
    ORPHANS            will leave at least one thread in the system
                       unable to execute on any CPU in the active
                       set.

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The event flag to be set when the state transition attempt has
    completed. The efn argument is a longword specifying the number
    of the event flag; however, this service only uses the low-order
    byte.

    When you invoke $CPU_TRANSITION, the specified event flag is
    cleared; when the operation is complete, the event flag is set.

 iosb

    OpenVMS usage:io_status_area
    type:         IOSB structure
    access:       write only
    mechanism:    by 32-bit or 64-bit reference
    The I/O status area to receive the final completion status of
    the transition operation. The iosb argument is the 32-bit or 64-
    bit virtual address of the I/O status area. The I/O status area
    structure is 32 bytes in length; its definition can be found in
    $IOSBDEF in STARLET.MLB for macro and in the file IOSBDEF.H in
    SYS$STARLET_C.TLB for C.

    When you call $CPU_TRANSITION, the I/O status area is cleared.
    After the transition operation is complete, the block is modified
    as follows:

    Symbolic
    Name        Description

    iosb$w_     The first word contains the condition value return,
    status      indicating the final completion status of the
                operation.

                The first bit in the second word of the IOSB is set
                only if an error occurred during the operation; the
                remaining bits are zeroes.

 astadr_64

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit reference
    The AST routine to be executed when the requested transition
    attempt has completed. The astadr_64 argument is the 32-bit
    or 64-bit virtual address of this routine. If you specify the
    astadr_64 argument, the AST routine executes at the access mode
    from which the state transition was requested.

 astprm_64

    OpenVMS usage:user_arg
    type:         quadword
    access:       read only
    mechanism:    by value
    The quadword AST parameter to be passed to the AST routine.

49  –  $CPU TRANSITIONW (Alpha and Integrity servers)

    On Alpha and Integrity server systems, changes the current
    processing state of a CPU in the configure set or an unassigned
    CPU in a Galaxy configuration. This service completes
    synchronously; that is, it returns to the caller only after the
    final completion status of the operation is known.

    In all other respects, $CPU_TRANSITIONW is identical to $CPU_
    TRANSITION. For all other information about the $CPU_TRANSITIONW
    service, see the description of $CPU_TRANSITION in this manual.

    This service accepts 64-bit addresses.

    For more information, see the VSI OpenVMS Alpha Partitioning and
    Galaxy Guide.

    Format

      SYS$CPU_TRANSITIONW  tran_id ,cpu_id ,nodename ,node_id ,flags

                           ,efn ,iosb ,astadr_64 ,astprm_64

    C Prototype

      int sys$cpu_transitionw  (int tran_code, int cpu_id,

                               dsc64$descriptor_s_pq nodename,

                               int node_id, uint32 flags, int efn,

                               IOSB *iosb, UINT64_PQ astadr, uint64

                               astprm, uint32 timout);

50  –  $CREATE

    The Create service constructs a new file according to the
    attributes you specify in the FAB. If any XABs are chained to the
    FAB, then the characteristics described in the XABs are applied
    to the file. This service performs implicit Open and Display
    services.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

51  –  $CREATE BUFOBJ 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, creates a buffer object
    out of a range of pages.

    This service accepts 64-bit addresses.

    Format

      SYS$CREATE_BUFOBJ_64  start_va_64 ,length_64 ,acmode ,flags

                            ,return_va_64 ,return_length_64

                            ,buffer_handle_64

    C Prototype

      int sys$create_bufobj_64  (void *start_va_64, unsigned

                                __int64 length_64, unsigned int

                                acmode, unsigned int flags, void

                                *(*(return_va_64)), unsigned __int64

                                *return_length_64, struct _generic_64

                                *buffer_handle_64);

51.1  –  Arguments

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    Starting virtual address of the pages to be included in the
    buffer object. The specified virtual address will be rounded
    down to a CPU-specific page boundary.

    The virtual address space must already exist.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space to be included in the buffer
    object. The specified length will be rounded up to a CPU-specific
    page boundary such that it includes all CPU-specific pages in the
    requested range.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode on behalf of which the request is being made. The
    acmode argument is a longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of
    the caller. For the $CREATE_BUFOBJ_64 service to complete
    successfully, the resultant access mode must be equal to or more
    privileged than the access mode already associated with the pages
    in the specified input range.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the request options. The flags argument is a
    longword bit vector in which each bit corresponds to a flag. The
    $CBODEF macro in STARLET.MLB and CBODEF.H file in SYS$STARLET_
    C.TLB define a symbolic name for each flag.

    The following table describes each flag that is valid for the
    $CREATE_BUFOBJ_64 service:

    Flag          Value  Description

    CBO$M_RETSVA  1      If set, returns the system virtual address
                         in the return_va_64 argument instead of the
                         process virtual address range. (Valid for
                         inner mode callers only.)
    CBO$M_SVA_32  4      If set, creates the buffer object window
                         in 32-bit S0/S1 space. (By default, this
                         service creates the window in 64-bit S2
                         space.)

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of the pages in the buffer
    object. The return_va_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword into which the service
    returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the virtual address range in the buffer object. The
    return_length_64 argument is the 32- or 64-bit virtual address of
    a naturally aligned quadword into which the service returns the
    length of the virtual address range in bytes.

 buffer_handle_64

    OpenVMS usage:handle
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned
    quadword into which a buffer handle is returned to be used when
    referencing the created buffer object.

52  –  $CREATE GALAXY LOCK (Alpha Only)

    Allocates an OpenVMS Galaxy lock block from a lock table created
    with the $CREATE_GALAXY_LOCK_TABLE service.

    Note that this system service is supported only in an OpenVMS
    Alpha Galaxy environment.

    For more information about programming with OpenVMS Galaxy system
    services, see the VSI OpenVMS Alpha Partitioning and Galaxy Guide.

    Format

      SYS$CREATE_GALAXY_LOCK  lcktbl_handle ,name ,size ,timeout ,ipl

                              ,rank ,handle

    C Prototype

      int sys$create_galaxy_lock  (unsigned int lcktbl_handle, void

                                  *name, unsigned int size, unsigned

                                  int timeout, unsigned int ipl,

                                  unsigned int rank, unsigned __int64

                                  *lock_handle);

52.1  –  Arguments

 lcktbl_handle

    OpenVMS usage:lock table handle
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    The 32-bit lock table handle that identifies the lock table in
    which to create the lock. This value is returned by SYS$CREATE_
    GALAXY_LOCK_TABLE.

 name

    OpenVMS usage:address
    type:         ASCID string
    access:       read
    mechanism:    input by reference
    The name parameter is a pointer to an ASCID string (passed by
    descriptor). The name can be a maximum of 15 characters. Lock
    names are not checked for uniqueness; therefore, multiple locks
    can be created with the same name.

 timeout

    OpenVMS usage:wait timeout
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    The 32-bit wait or spin timeout specified in 10 microsecond
    units. If not specified, the timeout defaults to 10 microseconds.

 size

    OpenVMS usage:byte count
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    The size of the galaxy lock in bytes. Galaxy locks have two legal
    sizes. These values are returned by SYS$GET_GALAXY_LOCK_SIZE. The
    value passed to SYS$CREATE_GALAXY_LOCK must be equal to the value
    passed to the call to SYS$CREATE_GALAXY_LOCK_TABLE.

 ipl

    OpenVMS usage:IPL of lock
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    For galaxy locks acquired in kernel mode, the IPL to raise to
    while the lock is held. This parameter is ignored for all other
    access mode.

 rank

    OpenVMS usage:rank of lock
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    Rank applied to a galaxy lock. Ranking is used to detect
    potential deadlocks. This parameter is currently ignored.

 handle

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write
    mechanism:    output by reference
    The handle parameter is a pointer to a quadword. The value
    returned is a 64-bit handle that uniquely identifies the lock
    galaxy-wide.

53  –  $CREATE GALAXY LOCK TABLE (Alpha Only)

    Allocates an OpenVMS Galaxy lock table.

    Note that this system service is supported only in an OpenVMS
    Alpha Galaxy environment.

    For more information about programming with OpenVMS Galaxy system
    services, see the VSI OpenVMS Alpha Partitioning and Galaxy Guide.

    Format

      SYS$CREATE_GALAXY_LOCK_TABLE  name ,accmode ,section_size

                                    ,section_type ,prot ,lock_size

                                    ,lcktbl_handle

    C Prototype

      int sys$create_galaxy_lock_table  (void *name, unsigned int

                                        accmode, unsigned __int64

                                        section_size, unsigned int

                                        section_type, unsigned int

                                        prot, unsigned int lock_size,

                                        unsigned int *lcktbl_handle);

53.1  –  Arguments

 name

    OpenVMS usage:address
    type:         ASCID string
    access:       read
    mechanism:    input by reference
    The name parameter is a pointer to an ASCID string (passed by
    descriptor). The name is given to the global section that is
    created to contain the galaxy locks.

 accmode

    OpenVMS usage:access mode
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    Access mode that is to be the owner of the pages created during
    the mapping. The accmode argument is a longword containing the
    access mode.

 section_size

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read
    mechanism:    input by value
    Length of the global section to be created, in bytes. The size
    must be specified as a multiple of the CPU-specific page size. A
    size of zero is illegal.

 section_type

    OpenVMS usage:bit mask
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    Used to control where in virtual memory the global section
    is created. If GLCKTBL$C_PROCESS is specified, the section is
    created in P2 (process) space. If GLCKTBL$C_SYSTEM is specified,
    the section is created in S0/S1 (system) space. These constants
    are defined in the GLOCKDEF macro.

 prot

    OpenVMS usage:protection
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    Protection to be applied to the global section.

 lock_size

    OpenVMS usage:byte count
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    The size of the galaxy lock in bytes. Galaxy locks have two
    sizes. The legal values are returned by SYS$GET_GALAXY_LOCK_SIZE.

 lcktbl_handle

    OpenVMS usage:address
    type:         longword
    access:       write
    mechanism:    output by reference
    Pointer to a longword. The value returned is a 32-bit handle that
    uniquely identifies the lock table galaxy-wide.

54  –  $CREATE GDZRO

    On Alpha and Integrity server systems, creates a permanent,
    memory-resident, global demand-zero section to which processes
    can map. Shared page table sections can also be created.

    This service accepts 64-bit addresses.

    Format

      SYS$CREATE_GDZRO  gs_name_64 ,ident_64 ,prot ,length_64 ,acmode

                        ,flags [,reserved_length_64] [,rad_mask]

    C Prototype

      int sys$create_gdzro  (void *gs_name_64, struct _secid

                            *ident_64, unsigned int prot, unsigned

                            __int64 length_64, unsigned int acmode,

                            unsigned int flags,...);

54.1  –  Arguments

 gs_name_64

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section. The gs_name_64 argument is the 32-
    or 64-bit virtual address of a naturally aligned 32- or 64-bit
    string descriptor pointing to this name string.

 ident_64

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of the global
    section. The ident_64 argument is a quadword containing three
    fields. The ident_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword that contains the
    identification value.

    The first longword specifies the matching criteria in its low-
    order 2 bits. Their meanings are as follows:

           Symbolic
    Value  Name           Match Criteria

    0      SEC$K_MATALL   Match all versions of the section.
    1      SEC$K_MATEQU   Match only if major and minor
                          identifications match.
    2      SEC$K_MATLEQ   Match if the major identifications are
                          equal and the minor identification of the
                          mapper is less than or equal to the minor
                          identification of the global section.

    If you specify the ident_64 argument as 0, the version number and
    match control fields default to 0.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. You
    can assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

 prot

    OpenVMS usage:file_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Protection to be applied to the global demand-zero section. The
    mask contains four 4-bit fields. Bits are read from right to left
    in each field.

    To view the diagram depicting the mask, see the VSI OpenVMS System
    Services Reference Manual.

    Cleared bits indicate that read, write, execute, and delete
    access, in that order, are granted to the particular category
    of user. Only read, write, and execute access are meaningful for
    section protection. Delete access bits are ignored. Read access
    also grants execute access for those situations where execute
    access applies. If 0 is specified, read access and write access
    are granted to all users.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length, in bytes, of the global demand-zero section to be
    created. The length_64 argument must be specified as a multiple
    of the CPU-specific page size. A length of 0 cannot be specified.

                                   NOTE

       Creating a memory-resident global section with shared page
       tables does not imply that the global section must have
       a length that is an even multiple of CPU-specific page
       table pages. The global section might not fully use the
       last shared page table page.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. The acmode argument is a longword containing the
    access mode.

    If the memory-resident global section is created with shared
    page tables, this is the access mode that is stored in the owner,
    read, and write fields of the corresponding shared page table
    entries (PTEs).

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the type of global section to be created as
    well as its characteristics. The flags argument is a longword bit
    vector in which each bit corresponds to a flag. The $SECDEF macro
    and the SECDEF.H file define a symbolic name for each flag. You
    construct the flags argument by performing a logical OR operation
    on the symbol names for all desired flags.

    The following table describes the flags that are valid for the
    $CREATE_GDZRO service:

    Flag          Description

    SEC$M_DZRO    Pages are demand-zero pages. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_GBL     Pages form a global section. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_MRES    Pages form a memory-resident section. By default,
                  this flag is always present in this service and
                  cannot be disabled.
    SEC$M_PERM    Global section is permanent. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_RAD_    When set, the argument rad_mask is used as a mask
    HINT          of RADs from which to allocate memory. See the rad_
                  mask argument description for more information.
    SEC$M_READ_   Create shared table pages for the section that
    ONLY_SHPT     allow read access only.
    SEC$M_SHMGS   Create a shared-memory global section.
    SEC$M_SYSGBL  Pages form a system global section. By default,
                  pages form a group global section.
    SEC$M_WRT     Pages form a read/write section. By default, this
                  flag is always present in this service and cannot
                  be disabled.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set.

 reserved_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    32- or 64-bit reference
    Length, in bytes, of the global section as currently registered
    in the Reserved Memory Registry. The reserved_length_64 argument
    is the 32- or 64-bit virtual address of a naturally aligned
    quadword into which the service returns the reserved length.

    If reserved_length_64 is not specified or is specified as 0, no
    reserved length is returned to the caller.

    If the memory-resident global section is not registered,
    reserved_length_64 is written with the value 0.

 rad_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Use the rad_mask argument to specify from which RADs to allocate
    memory. Currently only one bit may be set. The specified RAD
    must contain memory. This argument is only a hint. Memory may be
    obtained from other RADs if no free memory is available at the
    time of allocation.

    The rad_mask argument is considered only if the SEC$M_RAD_HINT
    flag is specified. Otherwise, this argument is ignored.

    On a system that does not support resource affinity domains
    (RADs), specifying 1 for the rad_mask argument is allowed.

    RAD is supported on AlphaServer GS series systems and starting
    from OpenVMS Version 8.4, support is extended to NUMA capable
    Integrity servers.

55  –  $CREATE GFILE (Alpha and Integrity servers)

    On Alpha and Integrity server systems, creates a permanent global
    disk file section to which processes can map.

    This service accepts 64-bit addresses.

    Format

      SYS$CREATE_GFILE  gs_name_64 ,ident_64 ,file_offset_64

                        ,length_64 ,chan ,acmode ,flags

                        ,return_length_64 [,fault_cluster]

    C Prototype

      int sys$create_gfile  (void *gs_nam_64, struct _secid

                            *ident_64, unsigned __int64

                            file_offset_64, unsigned __int64

                            length_64, unsigned short int chan,

                            unsigned int acmode, unsigned int flags,

                            unsigned __int64 *return_length_64,...);

55.1  –  Arguments

 gs_name_64

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section. The gs_name_64 argument is the 64-
    bit virtual address of a naturally aligned 32- or 64-bit string
    descriptor pointing to this name string.

 ident_64

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of a global
    section. The ident_64 argument is a quadword containing three
    fields. The ident_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword that contains the
    identification value.

    The first longword specifies the matching criteria in its low-
    order two bits. The valid values, symbolic names by which they
    can be specified, and their meanings are as follows:

           Symbolic
    Value  Name           Match Criteria

    0      SEC$K_MATALL   Match all versions of the section.
    1      SEC$K_MATEQU   Match only if major and minor
                          identifications match.
    2      SEC$K_MATLEQ   Match if the major identifications are
                          equal and the minor identification of the
                          mapper is less than or equal to the minor
                          identification of the global section.

    If you specify the ident_64 argument as 0, the version number and
    match control fields default to 0.

    The version number is in the second longword and contains
    two fields: a minor identification in the low-order 24 bits
    and a major identification in the high-order 8 bits. You can
    assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

 file_offset_64

    OpenVMS usage:byte offset
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Byte offset into the file that marks the beginning of the
    section. The file_offset_64 argument is a quadword containing
    this number. If you do not specify the file_offset_64 argument or
    specify it as 0, the section is created beginning with the first
    byte in the file.

    The file_offset_64 argument must be a multiple of virtual disk
    blocks.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length, in bytes, of the global disk file section to be created.
    The length specified must be 0 or a multiple of virtual disk
    blocks. If the length specified is 0 or extends beyond end-of-
    file (EOF), the global disk file section is created up to and
    including the virtual block number that contains EOF.

 chan

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the channel on which the file has been accessed. The
    chan argument is a longword containing this number. The access
    mode at which the channel was opened must be equal to or less
    privileged than the access mode of the caller.

    You can use the OpenVMS Record Management Services (RMS) macro
    $OPEN to access a file; the file options parameter in the file
    access block must indicate a user file open (UFO keyword).

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. The acmode argument is a longword containing the
    access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the type of global section to be created as
    well as its characteristics. The flags argument is a longword bit
    vector in which each bit corresponds to a flag. The $SECDEF macro
    and the SECDEF.H file define a symbolic name for each flag. You
    construct the flags argument by performing a logical OR operation
    on the symbol names for all desired flags.

    The following table describes each flag that is valid for the
    $CREATE_GFILE service:

    Flag          Description

    SEC$M_CRF     Pages are copy-on-reference. By default, pages are
                  shared.
    SEC$M_DZRO    Pages are demand-zero pages. By default, they are
                  not zeroed when copied.

                  Note that SEC$M_DZRO and SEC$M_CRF cannot both be
                  set and that SEC$M_DZRO set and SEC$M_WRT clear is
                  an invalid combination.
    SEC$M_GBL     Pages form a global section. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_PERM    Global section is permanent. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_SYSGBL  Pages form a system global section. By default,
                  pages form a group global section.
    SEC$M_WRT     Pages form a read/write section. By default, pages
                  form a read-only section.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set or if
    an illegal combination of flags is set.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the global section created. The return_length_64
    argument is the 32- or 64-bit virtual address of a naturally
    aligned quadword into which the service returns the length of the
    global section in bytes.

 fault_cluster

    OpenVMS usage:byte count
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Page fault cluster in byte units indicating how many pages are
    to be brought into memory when a page fault occurs for a single
    page. The fault cluster specified is rounded up to a multiple of
    CPU-specific pages.

    If this argument is specified as 0, the system default page fault
    cluster is used. If this argument is specified as more than
    the maximum allowed for the system, no error is returned. The
    systemwide maximum is used.

56  –  $CREATE GPFILE (Alpha and Integrity servers)

    On Alpha and Integrity server systems, creates a permanent global
    page file section to which processes can map.

    This service accepts 64-bit addresses.

    Format

      SYS$CREATE_GPFILE  gs_name_64 ,ident_64 ,prot ,length_64

                         ,acmode ,flags

    C Prototype

      int sys$create_gpfile  (void *gs_name_64, struct _secid

                             *ident_64, unsigned int prot, unsigned

                             __int64 length_64, unsigned int acmode,

                             unsigned int flags);

56.1  –  Arguments

 gs_name_64

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section. The gs_name_64 argument is the 32-
    or 64-bit virtual address of a naturally aligned 32- or 64-bit
    string descriptor pointing to this name string.

 ident_64

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of a global
    section. The ident_64 argument is a quadword containing three
    fields. The ident_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword that contains the
    identification value.

    The first longword specifies the matching criteria in its low-
    order 2 bits. Their meanings are as follows:

           Symbolic
    Value  Name           Match Criteria

    0      SEC$K_MATALL   Match all versions of the section.
    1      SEC$K_MATEQU   Match only if major and minor
                          identifications match.
    2      SEC$K_MATLEQ   Match if the major identifications are
                          equal and the minor identification of the
                          mapper is less than or equal to the minor
                          identification of the global section.

    If you specify the ident_64 argument as 0, the version number and
    match control fields default to 0.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. You
    can assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

 prot

    OpenVMS usage:file_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Protection to be applied to the global page file section. The
    mask contains four 4-bit fields. Bits are read from right to left
    in each field.

    To view the diagram depicting the mask, see the VSI OpenVMS System
    Services Reference Manual.

    Cleared bits indicate that read, write, execute, and delete
    access, in that order, are granted to the particular category
    of user. Only read, write, and execute access are meaningful for
    section protection. Delete access bits are ignored. Read access
    also grants execute access for those situations where execute
    access applies. If 0 is specified, read access and write access
    are granted to all users.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length, in bytes, of the global page file section to be created.
    The length_64 argument must be specified as a multiple of the
    CPU-specific page size. A length of 0 cannot be specified.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. The acmode argument is a longword containing the
    access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the type of global section to be created as
    well as its characteristics. The flags argument is a longword bit
    vector in which each bit corresponds to a flag. The $SECDEF macro
    and the SECDEF.H file define a symbolic name for each flag. You
    construct the flags argument by performing a logical OR operation
    on the symbol names for all desired flags.

    The following table describes the flags that are valid for the
    $CREATE_GPFILE service:

    Flag          Description

    SEC$M_DZRO    Pages are demand-zero pages.
    SEC$M_GBL     Pages form a global section. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_PAGFIL  Pages form a global page-file section. SEC$M_PAGFIL
                  also implies SEC$M_WRT and SEC$M_DZRO. By default,
                  this flag is always present in this service and
                  cannot be disabled.
    SEC$M_PERM    Global section is permanent. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_SYSGBL  Pages form a system global section. By default,
                  pages form a group global section.
    SEC$M_WRT     Pages form a read/write section. By default, this
                  flag is always present in this service and cannot
                  be disabled.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set.

57  –  $CREATE GPFN (Alpha and Integrity servers)

    On Alpha and Integrity server systems, creates a permanent page
    frame section to which processes can map.

    This service accepts 64-bit addresses.

    Format

      SYS$CREATE_GPFN  gs_name_64 ,ident_64 ,prot ,start_pfn

                       ,page_count ,acmode ,flags

    C Prototype

      int sys$create_gpfn  (void *gs_name_64, struct _secid

                           *ident_64, unsigned int prot, unsigned

                           int start_pfn, unsigned int page_count,

                           unsigned int acmode, unsigned int flags);

57.1  –  Arguments

 gs_name_64

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section. The gs_name_64 argument is the 32-
    or 64-bit virtual address of a naturally aligned 32- or 64-bit
    string descriptor pointing to this name string.

 ident_64

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of a global
    section. The ident_64 argument is a quadword containing three
    fields. The ident_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword that contains the
    identification value.

    The first longword specifies the matching criteria in its low-
    order two bits.

    The valid values, symbolic names by which they can be specified,
    and their meanings are as follows:

           Symbolic
    Value  Name           Match Criteria

    0      SEC$K_MATALL   Match all versions of the section.
    1      SEC$K_MATEQU   Match only if major and minor
                          identifications match.
    2      SEC$K_MATLEQ   Match if the major identifications are
                          equal and the minor identification of the
                          mapper is less than or equal to the minor
                          identification of the global section.

    If you specify the ident_64 argument as 0, the version number and
    match control fields default to 0.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. You
    can assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

 prot

    OpenVMS usage:file_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Protection to be applied to the global page frame section. The
    mask contains four 4-bit fields. Bits are read from right to left
    in each field.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the diagram depicting the mask.

    Cleared bits indicate that read, write, execute, and delete
    access, in that order, are granted to the particular category
    of user. Only read, write, and execute access are meaningful
    for section protection. Delete access bits are ignored. Read
    access also grants execute access for those situations where
    execute access applies. If zero is specified, read access and
    write access are granted to all users.

 start_pfn

    OpenVMS usage:page frame number
    type:         longword (unsigned) on Alpha, quadword (unsigned)
                  on Integrity servers
    access:       read only
    mechanism:    by value
    The CPU-specific page frame number where the section begins in
    memory.

 page_count

    OpenVMS usage:CPU-specific page count
    type:         longword (unsigned) on Alpha, quadword (unsigned)
                  on Integrity servers
    access:       read only
    mechanism:    by value
    Length of the page frame section in CPU-specific pages.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. The acmode argument is a longword containing the
    access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the characteristics of the page frame
    section to be created. The flags argument is a longword bit
    vector in which each bit corresponds to a flag. The $SECDEF macro
    and the SECDEF.H file define a symbolic name for each flag. You
    construct the flags argument by performing a logical OR operation
    on the symbol names for all desired flags.

    The following table describes the flags that are valid for the
    $CREATE_GPFN service:

    Flag          Description

    SEC$M_ARGS64  Indicates that all parameters, specifically start_
                  pfn and page_count, are passed as 64-bit numbers.
                  This flag is ignored on OpenVMS Alpha but must be
                  set on Integrity server systems. If the flag is
                  not set on Integrity servers, the error code SS$_
                  IVSECFLG is returned.
    SEC$M_GBL     Pages form a global section. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_PERM    Global section is permanent. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_PFNMAP  Pages form a page frame section. By default, this
                  flag is always present in this service and cannot
                  be disabled.
    SEC$M_SYSGBL  Pages form a system global page frame section.
                  By default, pages form a group global page frame
                  section.
    SEC$M_        Flag that must be set when a PFN-mapped section
    UNCACHED      is created if this section must be treated as
                  uncached memory. Flag is ignored on Alpha systems;
                  it applies only to Integrity server systems.
    SEC$M_WRT     Pages form a read/write section. By default, pages
                  form a read-only section.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set or if
    an illegal combination of flags is set.

58  –  $CREATE RDB

    Initializes a rights database.

    Format

      SYS$CREATE_RDB  [sysid]

    C Prototype

      int sys$create_rdb  (struct _generic_64 *sysid);

58.1  –  Argument

 sysid

    OpenVMS usage:system_access_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    System identification value associated with the rights database
    when $CREATE_RDB completes execution. The sysid argument is the
    address of a quadword containing the system identification value.
    If you omit sysid, the current system time in 64-bit format is
    used.

59  –  $CREATE REGION 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, creates a virtual region
    within the process's private address space.

    This service accepts 64-bit addresses.

    Format

      SYS$CREATE_REGION_64  length_64 ,region_prot ,flags

                            ,return_region_id_64 ,return_va_64

                            ,return_length_64 [,start_va_64]

    C Prototype

      int sys$create_region_64  ( unsigned __int64 length_64,

                                unsigned int region_prot,

                                unsigned int flags, struct

                                _generic_64 *return_region_id, void

                                *(*(return_va_64)), unsigned __int64

                                *return_length_64,...);

59.1  –  Arguments

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual region to be created. The length specified
    must be a multiple of CPU-specific pages. This length is fixed at
    the time the region is created.

    If you want to map multiple memory-resident sections to this
    region, specify a length large enough not only to accommodate
    all of the sections, but also to fill the space necessary to
    align the next section for a maximum of effective page sizes
    (granularity hints). You can satisfy this requirement by simply
    allocating a region that is twice as large as the sum of all
    sections you want to map.

    If the flag VA$M_SHARED_PTS is set, this length is rounded up to
    include an even multiple of CPU-specific pages mapped by a page
    table page.

 region_prot

    OpenVMS usage:region_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Region protection to be associated with the region to be created.
    The region_prot argument is a longword containing the create and
    owner mode.

    The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in
    STARLET.MLB define the following symbols for valid combinations
    of create and owner modes:

    Symbol                 Create and Owner Modes

    VA$C_REGION_UCREATE_   User create mode and user owner mode
    UOWN
    VA$C_REGION_UCREATE_   User create mode and supervisor owner mode
    SOWN
    VA$C_REGION_UCREATE_   User create mode and executive owner mode
    EOWN
    VA$C_REGION_UCREATE_   User create mode and kernel owner mode
    KOWN
    VA$C_REGION_SCREATE_   Supervisor create mode and supervisor
    SOWN                   owner mode
    VA$C_REGION_SCREATE_   Supervisor create mode and executive owner
    EOWN                   mode
    VA$C_REGION_SCREATE_   Supervisor create mode and kernel owner
    KOWN                   mode
    VA$C_REGION_ECREATE_   Executive create mode and executive owner
    EOWN                   mode
    VA$C_REGION_ECREATE_   Executive create mode and kernel owner
    KOWN                   mode
    VA$C_REGION_KCREATE_   Kernel create mode and kernel owner mode
    KOWN

    For both create and owner mode, the $CREATE_REGION_64 service
    uses whichever of the following two access modes is least
    privileged:

    o  Access mode specified by the acmode argument

    o  Access mode of the caller

    A subsequent call to any system service that created address
    space within a region must be made from an access mode that is
    the same or more privileged than the create mode associated with
    the region.

    A subsequent call to $DELETE_REGION_64 to delete the region must
    be made from an access mode that is the same or more privileged
    than the owner mode associated with the region.

    All regions created by $CREATE_REGION_64 are automatically
    deleted when the image is run down on image exit.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the characteristics of the region to
    be created. The flags argument is a longword bit vector in
    which each bit corresponds to a flag. The file VADEF.H in
    SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLB define a
    symbolic name for each flag. You construct the flags argument
    by performing a logical OR operation on the symbol names for all
    desired flags.

    The following table describes the flags that are valid for the
    $CREATE_REGION_64 service:

    Flag             Description

    VA$M_DESCEND     Created region is a descending region; that
                     is, allocation occurs toward decreasing virtual
                     addresses. If VA$M_DESCEND is not specified,
                     the region allocation occurs toward increasing
                     virtual addresses.
    VA$M_SHARED_PTS  Created region requires the virtual address
                     space created within it to be capable of
                     using shared page tables. If this flag is not
                     specified, the virtual address space created
                     within the region is mapped by process-private
                     page tables only. By default, the region does
                     not allow the use of shared page tables.
    VA$M_P0_SPACE    Create region in P0 space. This flag cannot be
                     set if VA$M_P1_SPACE is set.
    VA$M_P1_SPACE    Create region in P1 space. This flag cannot be
                     set if VA$M_P0_SPACE is set.

    All other bits in the flags argument are reserved for future
    use by VSI. The condition value SS$_IVREGFLG is returned if any
    undefined bits are set.

 return_region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the created region. The
    return_region_id_64 argument is the 32- or 64-bit virtual address
    of a naturally aligned quadword into which the service returns
    the region ID.

 return_va_64

    OpenVMS usage:return address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of the region. The
    return_va_64 argument is the 32- or 64-bit virtual address of
    a naturally aligned quadword into which the service returns the
    lowest virtual address of the region.

    If the flag VA$M_SHARED_PTS is set, the returned virtual address
    is aligned to a CPU-specific page table page boundary. If the
    global section mapped by this shared page table region is large
    enough that multiple page table pages are required to map the
    global section, the page tables themselves can be mapped with
    granularity hints; therefore, the alignment of the returned
    virtual address can be even greater than that of a single CPU-
    specific page table page boundary.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the region actually created. The return_length_64
    argument is the 32- or 64-bit virtual address of a naturally
    aligned quadword into which the service returns the length of the
    region in bytes.

    If the flag VA$M_SHARED_PTS is set, the returned length is the
    input length rounded up to an even multiple of bytes mapped by a
    single CPU-specific page table page.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting address for the created virtual region. The
    specified virtual address must be a CPU-specific page aligned
    address.

    If the start_va_64 argument is not specified or is specified
    as 0, the region can be created anywhere within the following
    address spaces:

    o  P2 space (if the flags VA$M_P0_SPACE and VA$M_P1_SPACE are
       clear)

    o  P0 space (if the flag VA$M_P0_SPACE is set and VA$M_P1_SPACE
       is clear)

    o  P1 space (if the flag VA$M_P1_SPACE is set and VA$M_P0_SPACE
       is clear)

    If the flag VA$M_SHARED_PTS is set and this argument is
    specified, the specified starting address must be aligned to the
    larger of a natural page table boundary or the largest possible
    page size used to map the section. If the alignment is less than
    a page table boundary, the $CREATE_REGION_64 service returns an
    error. If the alignment is less than the largest page size used
    in the section, an error might be returned when you attempt to
    map the section.

    If you do not specify a starting address, OpenVMS automatically
    ensures correct alignment.

60  –  $CREATE UID

    Generates a universally unique identifier (UID).

    Format

      SYS$CREATE_UID  uid

    C Prototype

      int sys$create_uid  (unsigned int uid [4]);

60.1  –  Arguments

 uid

    OpenVMS usage:uid
    type:         octaword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of an octaword in which the unique identifier is returned
    to the calling process.

61  –  $CREATE USER PROFILE

    Returns an encoded security profile for the specified user.

    Format

      SYS$CREATE_USER_PROFILE  usrnam ,[itmlst] ,[flags] ,usrpro

                               ,usrprolen ,[contxt]

    C Prototype

      int sys$create_user_profile  (void *usrnam, void *itmlst,

                                   unsigned int flags, void *usrpro,

                                   unsigned int *usrprolen, unsigned

                                   int *contxt);

61.1  –  Arguments

 usrnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Name of the user whose security profile is to be returned. The
    usrnam argument is the address of a descriptor pointing to a text
    string containing the user name. The user name string can contain
    a maximum of 12 alphanumeric characters.

    For more information about user names, see the VSI OpenVMS Guide
    to System Security.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying the portions of the user's security profile
    to be replaced or augmented.

    To view the general format of an item descriptor and the fields
    description, see the VSI OpenVMS System Services Reference Manual.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The flags argument is used to control the behavior of the
    $CREATE_USER_PROFILE service. This argument does not accept ISS$
    mask values; therefore, continue to use the CHP$ mask values for
    this argument.

    The following table describes each flag:

    Symbol          Description

    CHP$M_          By default, $CREATE_USER_PROFILE initializes
    DEFCLASS        the security profile with the user's maximum
                    authorized classification. When this flag is set,
                    the service initializes the security profile from
                    the user's default classification instead. This
                    flag is Reserved to VSI.

    CHP$M_DEFPRIV   By default, $CREATE_USER_PROFILE initializes
                    the security profile with the user's authorized
                    privilege mask. When this flag is set, the
                    service initializes the security profile from
                    the user's default privilege mask instead.

    CHP$M_          Instructs the service not to access the user
    NOACCESS        authorization file (SYSUAF.DAT) or rights
                    database (RIGHTSLIST.DAT) to build the security
                    profile. This flag can be used as an optimization
                    when all the information necessary to build the
                    security profile is known to the caller.

 usrpro

    OpenVMS usage:char_string
    type:         opaque byte stream
    access:       write only
    mechanism:    by reference
    Buffer to receive the security profile. The usrpro argument is
    the address of a buffer to receive the encoded security profile.
    If an address of 0 is specified, $CREATE_USER_PROFILE returns the
    size of the buffer needed in the usrprolen argument.

 usrprolen

    OpenVMS usage:word
    type:         word (unsigned)
    access:       read/write
    mechanism:    by reference
    Word to receive the full size of the security profile. On input,
    the usrprolen argument specifies the length of the buffer pointed
    to by the usrpro argument. The usrprolen argument is the address
    of a word to which $CREATE_USER_PROFILE writes the actual length
    of the security profile. If the caller specifies a usrpro address
    of 0, $CREATE_USER_PROFILE returns the anticipated size, in
    bytes, of the buffer needed to hold the user's security profile
    in the usrprolen argument.

 contxt

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Longword used to maintain authorization file context. The contxt
    argument is the address of a longword to receive a $GETUAI
    context value. On the initial call, this longword should contain
    the value -1. On subsequent calls, the value of the contxt
    argument from the previous call should be passed back in.

    Using the contxt argument keeps the UAF open across all calls,
    thereby improving the performance of the system on subsequent
    calls. To close the UAF, you must run down the image.

    The resulting context value from a $CREATE_USER_PROFILE call can
    also be used as the input contxt argument to the $GETUAI system
    service, and vice versa.

62  –  $CRELNM

    Creates a logical name and specifies its equivalence names.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$CRELNM  [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]

    C Prototype

      int sys$crelnm  (unsigned int *attr, void *tabnam, void

                      *lognam, unsigned char *acmode, void *itmlst);

62.1  –  Arguments

 attr

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Attributes to be associated with the logical name. The attr
    argument is the 32- or 64-bit address of a longword bit mask
    specifying these attributes.

    Each bit in the longword corresponds to an attribute and has a
    symbolic name. These symbolic names are defined by the $LNMDEF
    macro. To specify an attribute, specify its symbolic name or set
    its corresponding bit. The longword bit mask is the logical OR of
    all desired attributes. All undefined bits in the longword must
    be 0.

    If you do not specify this argument or specify it as 0 (no bits
    set), no attributes are associated with the logical name.

    The attributes are as follows:

    Attribute      Description

    LNM$M_         If set, the logical name is not copied from the
    CONFINE        process to its spawned subprocesses. You create
                   a subprocess with the DCL command SPAWN or the
                   LIB$SPAWN Run-Time Library routine. If the logical
                   name is placed into a process-private table that
                   has the CONFINE attribute, the CONFINE attribute
                   is automatically associated with the logical
                   name. This applies only to process-private logical
                   names.

    LNM$M_NO_      If set, the logical name cannot be duplicated in
    ALIAS          this table at an outer access mode. If another
                   logical name with the same name already exists in
                   the table at an outer access mode, it is deleted.

 tabnam

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the table in which to create the logical name. The tabnam
    argument is the 32- or 64-bit address of a descriptor that points
    to the name of this table. This argument is required and must be
    specified in uppercase.

    The name must be entered in uppercase letters. (This requirement
    differs from the $CRELNT system service, which automatically
    changes tabnam to uppercase.)

    If tabnam is not the name of a logical name table, it is assumed
    to be a logical name and is translated iteratively until either
    the name of a logical name table is found or the number of
    translations allowed by the system has been performed. If tabnam
    translates to a list of logical name tables, the logical name is
    entered into the first table in the list.

 lognam

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the logical name to be created. The lognam argument is
    the 32- or 64-bit address of a descriptor that points to the
    logical name string.

    Logical name strings of logical names created within either the
    system or process directory table must consist of uppercase
    alphanumeric characters, dollar signs ($),  hyphens (-), and
    underscores (_);  the maximum length is 31 characters. The
    maximum length of logical name strings created within other
    tables is 255 characters with no restrictions on the types of
    characters that can be used. This argument is required.

 acmode

    OpenVMS usage:access_mode
    type:         byte (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Access mode to be associated with the logical name. The acmode
    argument is the 32- or 64-bit address of a byte that specifies
    the access mode.

    The access mode associated with the logical name is determined
    by maximizing the access mode of the caller with the access
    mode specified by the acmode argument, which means that the less
    privileged of the two is used. Symbols for the four access modes
    are defined by the $PSLDEF macro.

    You cannot specify an access mode more privileged than that
    of the containing table. However, if the caller has SYSNAM
    privilege, then the specified access mode is associated with
    the logical name regardless of the access mode of the caller.

    If you omit this argument or specify it as 0, the access mode of
    the caller is associated with the logical name.

 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 describing the equivalence names to be defined for
    the logical name and information to be returned to the caller.
    The itmlst argument is the 32- or 64-bit address of a list of
    item descriptors, each of which specifies information about an
    equivalence name. An item list in 32-bit format is terminated by
    a longword of 0; an item list in 64-bit format is terminated by
    a quadword of 0. All items in an item list must be of the same
    format-either 32-bit or 64-bit.

    Note that it is possible to create a logical that has no
    equivalence names. This is done by either omitting the itmlst
    argument to $CRELNM, or by not including the LNM$_STRING item
    code to the itmlst data structure that is passed into $CRELNM. It
    is not possible to create this kind of logical using DCL.

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

63  –  $CRELNT

    Creates a process-private or shareable logical name table.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$CRELNT  [attr] ,[resnam] ,[reslen] ,[quota]

                  ,[promsk] ,[tabnam] ,partab ,[acmode]

    C Prototype

      int sys$crelnt  (unsigned int *attr, void *resnam, unsigned

                      short int *reslen, unsigned int *quota,

                      unsigned short int *promsk, void *tabnam, void

                      *partab, unsigned char *acmode);

63.1  –  Arguments

 attr

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Attributes to affect the creation of the logical name table and
    to be associated with the newly created logical name table. The
    attr argument is the 32- or 64-bit address of a longword bit mask
    specifying these attributes.

    Each bit in the longword corresponds to an attribute and has a
    symbolic name. These symbolic names are defined by the $LNMDEF
    macro. To specify an attribute, specify its symbolic name or set
    its corresponding bit. The longword bit mask is the logical OR of
    all desired attributes. All unused bits in the longword must be
    0.

    If you do not specify this argument or specify it as 0 (no bits
    set), no attributes are associated with the logical name table or
    affect the creation of the new table.

    The following table describes each attribute:

    Attribute       Description

    LNM$M_CONFINE   If set, the logical name table is not copied
                    from the process to its spawned subprocesses. You
                    create a subprocess with the DCL command SPAWN or
                    the Run-Time Library LIB$SPAWN routine. You can
                    specify this attribute only for process-private
                    logical name tables; it is ignored for shareable
                    tables.

                    The state of this bit is also propagated from
                    the parent table to the newly created table
                    and can be overridden only if the parent table
                    does not have the bit set. Thus, if the parent
                    table has the LNM$M_CONFINE attribute, the newly
                    created table will also have it, no matter what
                    is specified in the attr argument. On the other
                    hand, if the parent table does not have the
                    LNM$M_CONFINE attribute, the newly created table
                    can be given this attribute through the attr
                    argument.

                    The process-private directory table LNM$PROCESS_
                    DIRECTORY does not have the LNM$M_CONFINE
                    attribute.

    LNM$M_CREATE_   This attribute applies to all types of logical
    IF              name tables except clusterwide logical name
                    tables. If set, a new logical name table is
                    created only if the specified table name is not
                    already entered at the specified access mode in
                    the appropriate directory table. If the table
                    name exists, a new table is not created and no
                    modification is made to the existing table name.
                    This holds true even if the existing name has
                    differing attributes or quota values, or even if
                    it is not the name of a logical name table.

                    If LNM$M_CREATE_IF is not set, the new logical
                    name table will supersede any existing table name
                    with the same access mode within the appropriate
                    directory table. Setting this attribute is useful
                    when two or more users want to create and use
                    the same table but do not want to synchronize its
                    creation.

                    Regardless of the setting of LNM$M_CREATE_IF:

                    o  You cannot create a new clusterwide logical
                       name table with the same name and the same
                       mode as an existing clusterwide logical name
                       table until you delete the existing one.

                    o  If you specify a new clusterwide logical name
                       table with the same name and access mode as
                       an existing local logical name table, the new
                       clusterwide logical name table is created,
                       and the local table and its logical names are
                       deleted.

    LNM$M_NO_       If set, the name of the logical name table cannot
    ALIAS           be duplicated at an outer access mode within
                    the appropriate directory table. If this name
                    already exists at an outer access mode, it is
                    deleted. Note that this attribute does not apply
                    to clusterwide logical name tables.

 resnam

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       write only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the newly created logical name table, returned by
    $CRELNT. The resnam argument is the 32- or 64-bit address of a
    descriptor pointing to this name. The name is a character string
    whose maximum length is 31 characters.

 reslen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Length in bytes of the name of the newly created logical name
    table, returned by $CRELNT. The reslen argument is the 32- or
    64-bit address of a word to receive this length.

 quota

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Maximum number of bytes of memory to be allocated for logical
    names contained in this logical name table. The quota argument is
    the 32- or 64-bit address of a longword specifying this value.

    If you specify no quota value, the logical name table has an
    infinite quota. Note that a shareable table created with infinite
    quota permits users with write access to that table to consume
    system dynamic memory without limit.

 promsk

    OpenVMS usage:file_protection
    type:         word (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Protection mask to be associated with the newly created shareable
    logical name table. The promsk argument is the 32- or 64-bit
    address of a word that contains a value that represents four
    4-bit fields. Each field grants or denies the type of access,
    either delete, create, write, or read, allowed for system, owner,
    group, and world users.

    The following diagram depicts these protection bits:

            |------------|------------|------------|------------|
            |   World    |    Group   |   Owner    |   System   |
            |------------|------------|------------|------------|
            | D  C  W  R | D  C  W  R | D  C  W  R | D  C  W  R |
            |------------|------------|------------|------------|
             15 14 13 12  11 10  9  8   7  6  5  4   3  2  1  0

    Create access is required to create a shareable table within
    another shareable table.

    Each field consists of 4 bits specifying protection for the
    logical name table. The remaining bits in the protection mask
    are as follows:

    o  Read privileges allow access to names in the logical name
       table.

    o  Write privileges allow creation and deletion of names within
       the logical name table.

    o  Delete privileges allow deletion of the logical name table.

    If a bit is clear, access is granted.

    The initial security profile for any shared logical name table is
    taken from the logical name table template. The owner is then set
    to the process UIC and, if the promsk argument is nonzero, that
    value replaces the protection mask.

 tabnam

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    The name of the new logical name table. The tabnam argument
    is the 32- or 64-bit address of a character-string descriptor
    pointing to this name string. Table names are contained in either
    the process or system directory table (LNM$PROCESS_DIRECTORY or
    LNM$SYSTEM_DIRECTORY); therefore, table names must consist of
    alphanumeric characters, dollar signs ($),  and underscores (_);
    the maximum length is 31 characters. Names of logical name tables
    must be in uppercase letters. If you specify a lowercase name,
    the $CRELNT service automatically changes it to uppercase.

    This argument is required for clusterwide logical name tables.
    For all other logical name tables, if you do not specify this
    argument, a default name in the format LNM$xxxx is used, where
    xxxx is a unique hexadecimal number.

    You need SYSPRV privilege or write access to LNM$SYSTEM_DIRECTORY
    to specify the name of a shareable logical name table.

 partab

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name string for the parent table name. The partab argument is the
    32- or 64-bit address of a character string descriptor pointing
    to this name string.

    If the parent table is shareable, then the newly created table
    is shareable and is entered into the system directory LNM$SYSTEM_
    DIRECTORY. If the parent table is process-private, then the newly
    created table is process-private and is entered in the process
    directory LNM$PROCESS_DIRECTORY.

    You need SYSPRV privilege or write access to the system directory
    table to create a named shareable table. This argument is
    required.

 acmode

    OpenVMS usage:access_mode
    type:         byte (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Access mode to be associated with the newly created logical name
    table. The acmode argument is the 32- or 64-bit address of a byte
    containing this access mode. The $PSLDEF macro defines symbolic
    names for the four access modes.

    If you do not specify the acmode argument or specify it as 0, the
    access mode of the caller is associated with the newly created
    logical name table.

    The access mode associated with the logical name table is
    determined by maximizing the access mode of the caller with the
    access mode specified by the acmode. The less privileged of the
    two access modes is used.

    However, if the caller has SYSNAM privilege, then the specified
    access mode is associated with the logical name table, regardless
    of the access mode of the caller.

    Access modes associated with logical name tables govern logical
    name table processing and provide a protection mechanism that
    prevents the deletion of inner access mode logical name tables
    by nonprivileged users. You cannot specify an access mode more
    privileged than that of the parent table.

    A logical name table with supervisor mode access can contain
    supervisor mode and user mode logical names and can be a parent
    to supervisor mode and user mode logical name tables, but cannot
    contain executive or kernel mode logical names or be a parent to
    executive or kernel mode logical name tables.

    You need SYSNAM privilege to specify executive or kernel mode
    access for a logical name table.

64  –  $CREMBX

    Creates a virtual mailbox device named MBAn and assigns an I/O
    channel to it. The system provides the unit number n when it
    creates the mailbox. If a logical name is specified and a mailbox
    with the specified name already exists, the $CREMBX service
    assigns a channel to the existing mailbox.

    Format

      SYS$CREMBX  [prmflg] ,chan ,[maxmsg] ,[bufquo] ,[promsk]

                  ,[acmode] ,[lognam] ,[flags] ,[nullarg]

    C Prototype

      int sys$crembx  (char prmflg, unsigned short int *chan,

                      unsigned int maxmsg, unsigned int bufquo,

                      unsigned int promsk, unsigned int acmode, void

                      *lognam,...);

64.1  –  Arguments

 prmflg

    OpenVMS usage:boolean
    type:         byte (unsigned)
    access:       read only
    mechanism:    by value
    Indicator specifying whether the created mailbox is to be
    permanent or temporary. The prmflg argument is a byte value.
    The first bit specifies a permanent mailbox; the value 0, which
    is the default, specifies a temporary mailbox. Any other values
    result in an error.

 chan

    OpenVMS usage:channel
    type:         word
    access:       write only
    mechanism:    by reference
    Channel number assigned by $CREMBX to the mailbox. The chan
    argument is the address of a word into which $CREMBX writes the
    channel number.

 maxmsg

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Maximum size (in bytes) of a message that can be sent to the
    mailbox. The maxmsg argument is a longword value containing this
    size.

    The maximum value you can specify for the maxmsg argument is
    65535. If you do not specify a value or specify the value
    as 0, the operating system provides a default value from the
    DEFMBXBUFQUO system parameter.

 bufquo

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of bytes of system dynamic memory that can be used to
    buffer messages sent to the mailbox. The bufquo argument is a
    value containing this number. If you do not specify the bufquo
    argument or specify it as 0, the operating system provides a
    default value from the DEFMBXBUFQUO system parameter.

    For a temporary mailbox, this value must be less than or equal to
    the process buffer quota.

    Note that as of Version 7.3-1, the maximum value limit for the
    bufquo argument is the amount of available non-paged pool.

 promsk

    OpenVMS usage:file_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Protection mask to be associated with the created mailbox. The
    promsk argument is a longword value that is the combined value
    of the bits set in the protection mask. Cleared bits grant access
    and set bits deny access to each of the four classes of user:
    world, group, owner, and system. The following diagram depicts
    these protection bits:

            |------------|------------|------------|------------|
            |   World    |    Group   |   Owner    |   System   |
            |------------|------------|------------|------------|
            | L  P  W  R | L  P  W  R | L  P  W  R | L  P  W  R |
            |------------|------------|------------|------------|
             15 14 13 12  11 10  9  8   7  6  5  4   3  2  1  0

    If you do not specify the promsk argument or specify it as 0, the
    mailbox template is used.

    The logical access bit must be clear for the class of user
    requiring access to the mailbox. The access bit must be clear
    for all categories of user because logical access is required to
    read or write to a mailbox; thus, setting or clearing the read
    and write access bits is meaningless unless the logical access
    bit is also cleared.

    The physical access bit is ignored for all categories of user.

    Logical access also allows you to queue read or write attention
    ASTs.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be associated with the channel to which the
    mailbox is assigned. The acmode argument is a longword containing
    the access mode.

    The $PSLDEF macro defines the following symbols for the four
    access modes:

    Symbol         Access Mode    Numeric Value

    PSL$C_KERNEL   Kernel         0
    PSL$C_EXEC     Executive      1
    PSL$C_SUPER    Supervisor     2
    PSL$C_USER     User           3

    The most privileged access mode used is the access mode of
    the caller. The specified access mode and the access mode of
    the caller are compared. The less privileged (but the higher
    numeric valued) of the two access modes becomes the access
    mode associated with the assigned channel. I/O operations on
    the channel can be performed only from equal or more privileged
    access modes.

 lognam

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Logical name to be assigned to the mailbox. The lognam argument
    is the address of a character string descriptor pointing to the
    logical name string.

    The equivalence name for the mailbox is MBAn. The equivalence
    name is marked with the terminal attribute. Processes can use the
    logical name to assign other I/O channels to the mailbox.

    For permanent mailboxes, the $CREMBX service enters the specified
    logical name, if any, in the LNM$PERMANENT_MAILBOX logical name
    table and, for temporary mailboxes, into the LNM$TEMPORARY_
    MAILBOX logical name table.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The flags argument is used for specifying options for the
    assign operation that occurs in $CREMBX. The flags argument
    is a longword bit mask that enables the user to specify that
    the channel assigned to the mailbox is a READ ONLY or WRITE
    ONLY channel. If the flags argument is not specified, then the
    default channel behavior is READ/WRITE. The $CMBDEF macro defines
    a symbolic name for each flag bit.

    The following table describes each flag:

    Flag            Description

    CMB$M_          When this flag is specified, $CREMBX assigns
    READONLY        a read-only channel to the mailbox device.
                    An attempt to issue a QIO WRITE operation on
                    the mailbox channel results in an illegal I/O
                    operation error.
    CMB$M_          When this flag is specified, $CREMBX assigns
    WRITEONLY       a write-only channel to the mailbox device.
                    An attempt to issue a QIO READ operation on
                    the mailbox channel results in an illegal I/O
                    operation error.

    For more information about the flags argument, see the VSI OpenVMS
    I/O User's Reference Manual.

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument reserved by VSI.

65  –  $CREPRC

    Creates, on behalf of the calling process, a subprocess or
    detached process on the current node, or a detached process on
    another OpenVMS Cluster node.

    Format

      SYS$CREPRC  [pidadr] ,[image] ,[input] ,[output] ,[error]

                  ,[prvadr] ,[quota] ,[prcnam] ,[baspri] ,[uic]

                  ,[mbxunt] ,[stsflg] ,[itmlst] ,[node] ,[home_rad]

    C Prototype

      int sys$creprc  (unsigned int *pidadr, void *image, void

                      *input, void *output, void *error, struct

                      _generic_64 *prvadr, unsigned int *quota, void

                      *prcnam, unsigned int baspri, unsigned int

                      uic, unsigned short int mbxunt, unsigned int

                      stsflg,...);

65.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Process identification (PID) of the newly created process. The
    pidadr argument is the address of a longword into which $CREPRC
    writes the PID.

 image

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the image to be activated in the newly created process.
    The image argument is the address of a character string
    descriptor pointing to the file specification of the image.

    The image name can have a maximum of 63 characters. If the image
    name contains a logical name, the logical name is translated in
    the created process and must therefore be in a logical name table
    that it can access.

    To create a process that will run under the control of a command
    language interpreter (CLI), specify SYS$SYSTEM:LOGINOUT.EXE as
    the image name.

 input

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Equivalence name to be associated with the logical name SYS$INPUT
    in the logical name table of the created process. The input
    argument is the address of a character string descriptor pointing
    to the equivalence name string.

 output

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Equivalence name to be associated with the logical name
    SYS$OUTPUT in the logical name table of the created process. The
    output argument is the address of a character string descriptor
    pointing to the equivalence name string.

 error

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Equivalence name to be associated with the logical name SYS$ERROR
    in the logical name table of the created process. The error
    argument is the address of a character string descriptor pointing
    to the equivalence name string.

    Note that the error argument is ignored if the image argument
    specifies SYS$SYSTEM:LOGINOUT.EXE; in this case, SYS$ERROR has
    the same equivalence name as SYS$OUTPUT.

 prvadr

    OpenVMS usage:mask_privileges
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Privileges to be given to the created process. The prvadr
    argument is the address of a quadword bit mask wherein each bit
    corresponds to a privilege; setting a bit gives the privilege. If
    the prvadr argument is not specified, the current privileges are
    used.

    Each bit has a symbolic name; the $PRVDEF macro defines these
    names. You form the bit mask by specifying the symbolic name of
    each desired privilege in a logical OR operation.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the table containing the symbolic name and description of each
    privilege.

    You need the user privilege SETPRV to grant a process any
    privileges other than your own. If the caller does not have this
    privilege, the mask is minimized with the current privileges of
    the creating process; any privileges the creating process does
    not have are not granted, but no error status code is returned.

 quota

    OpenVMS usage:item_quota_list
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Process quotas to be established for the created process. These
    quotas limit the created process's use of system resources. The
    quota argument is the address of a list of quota descriptors,
    where each quota descriptor consists of a 1-byte quota name
    followed by a longword that specifies the desired value for
    that quota. The list of quota descriptors is terminated by the
    symbolic name PQL$_LISTEND.

    If you do not specify the quota argument or specify it as 0, the
    operating system supplies a default value for each quota.

    Refer to the VSI OpenVMS System Services Reference Manual to
    view MACRO and C examples, individual quota descriptions, and
    instructions for use of the quota list.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Process name to be assigned to the created process. The prcnam
    argument is the address of a character string descriptor pointing
    to a process name string.

    If a subprocess is being created, the process name is implicitly
    qualified by the UIC group number of the creating process. If a
    detached process is being created, the process name is qualified
    by the group number specified in the uic argument.

 baspri

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Base priority to be assigned to the created process. The baspri
    argument is a longword value.

    The OpenVMS Alpha and Integrity servers range is 0 to 63, with
    real-time priorities in the range 32 to 63.

    If you want a created process to have a higher priority than its
    creating process, you must have ALTPRI privilege to raise the
    priority level. If the caller does not have this privilege, the
    specified base priority is compared with the caller's priority
    and the lower of the two values is used.

    A process with ALTPRI privilege running on a VAX node can
    create a process with a priority greater than 31 on an Alpha
    or Integrity servers node.

    If the baspri argument is not specified, the priority defaults to
    2 for VAX MACRO, VAX BLISS-32, and Pascal; it defaults to 0 for
    all other languages.

 uic

    OpenVMS usage:uic
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    User identification code (UIC) to be assigned to the created
    process. The uic argument is a longword value containing the UIC.

    If you do not specify the uic argument or specify it as 0 (the
    default), $CREPRC creates a process and assigns it the UIC of the
    creating process.

    If you specify a nonzero value for the uic argument, $CREPRC
    creates a detached process. This value is interpreted as a 32-bit
    octal number, with two 16-bit fields:

       bits 0-15-member number
       bits 16-31-group number

    You need IMPERSONATE or CMKRNL privilege to create a detached
    process with a UIC that is different from the UIC of the creating
    process.

    If the image argument specifies the SYS$SYSTEM:LOGINOUT.EXE,
    the UIC of the created process will be the UIC of the caller of
    $CREPRC, and the UIC parameter is ignored.

 mbxunt

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Unit number of a mailbox to receive a termination message when
    the created process is deleted. The mbxunt argument is a word
    containing this number.

    If you do not specify the mbxunt argument or specify it as 0 (the
    default), the operating system sends no termination message when
    it deletes the process.

    The Get Device/Volume Information ($GETDVI) service can be used
    to obtain the unit number of the mailbox.

    If you specify the mbxunt argument, the mailbox is used when
    the created process actually terminates. At that time, the
    $ASSIGN service is issued for the mailbox in the context of the
    terminating process and an accounting message is sent to the
    mailbox. If the mailbox no longer exists, cannot be assigned,
    or is full, the error is treated as if no mailbox had been
    specified.

    If you specify this argument when you create a process on another
    node, an accounting message will be written to the mailbox when
    the process terminates. If the node is removed from the cluster
    before the created process terminates, an accounting message
    will be simulated. The simulated message will contain the created
    process's PID and name and a final status of SS$_NODELEAVE, but
    will lack execution statistics.

    Note that two processes on different nodes cannot use the
    termination mailbox for general interprocess communication.

    The accounting message is sent before process rundown is
    initiated but after the process name has been set to null. Thus,
    a significant interval of time can occur between the sending of
    the accounting message and the final deletion of the process.

    To receive the accounting message, the caller must issue a read
    to the mailbox. When the I/O completes, the second longword of
    the I/O status block, if one is specified, contains the process
    identification of the deleted process.

    The $ACCDEF macro defines symbolic names for offsets of fields
    within the accounting message.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the table describing the offsets, their symbolic names, and the
    contents of each field.

 stsflg

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Options selected for the created process. The stsflg argument
    is a longword bit vector wherein a bit corresponds to an option.
    Only bits 0 to 22 are used; the others are reserved and must be
    0.

    Each option (bit) has a symbolic name, which the $PRCDEF macro
    defines. You construct the stsflg argument by performing a
    logical OR operation using the symbolic names of each desired
    option.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the table describing the symbolic name of each option.

 itmlst

    OpenVMS usage:reserved
    type:         longword (unsigned)
    access:
    mechanism:    0
    The itmlst argument is reserved by VSI.

 node

    OpenVMS usage:SCS_nodename
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the OpenVMS Cluster node on which the process is to be
    created. The node argument is the address of a character string
    descriptor pointing to a 1- to 6-character SCS node name string.
    If the argument is present but zero or if the string is zero
    length, the process is created on the current node.

 home_rad

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Sets the home resource affinity domain (RAD) of a process.

    The home RAD is determined by the operating system, unless you
    explicitly request one. If bit PRC$M_HOME_RAD in the stsflg is
    set, home_rad is the RAD on which the process is to start. Note
    that you may set this bit to 0 on non-RAD systems.

    RAD is supported on AlphaServer GS series systems and starting
    from OpenVMS Version 8.4, support is extended to NUMA capable
    Integrity servers. For more information about using RADs, see the
    VSI OpenVMS Alpha Partitioning and Galaxy Guide.

 kt_limit

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by value
    Sets the limit of the number of kernel threads that can be
    created in the process. If the value is greater than the SYSGEN
    MULTITHREAD parameter, an error message is returned.

    The number of kernel threads that can be created in a process,
    is by default controlled by the MULTITHREAD SYSGEN parameter. The
    kt_limit argument is used to further limit the number of possible
    kernel threads for the process.

66  –  $CRETVA

    Adds a range of demand-zero allocation pagelets to a process's
    virtual address space for the execution of the current image.

    Format

      SYS$CRETVA  inadr ,[retadr] ,[acmode]

    C Prototype

      int sys$cretva  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode);

66.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a 2-longword array containing the starting and ending
    virtual addresses of the pages to be created. If the starting and
    ending virtual addresses are the same, a single page is created.
    The addresses are adjusted up or down to fall on CPU-specific
    page boundaries. Only the virtual page number portion of the
    virtual address is used; the low order byte-within-page bits are
    ignored.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference-array reference or descriptor
    Address of a 2-longword array to receive the starting and ending
    virtual addresses of the pages created.

    On Alpha and Integrity server systems, the retadr argument should
    be checked by programs for actual allocation. Because the Alpha
    and Integrity servers architectures define more than one page
    size, more space might be created than was specified in the inadr
    argument.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode and protection for the new pages. The acmode argument
    is a longword containing the access mode.

    The $PSLDEF macro defines the following symbols for the four
    access modes:

    Symbol         Access Mode

    PSL$C_KERNEL   Kernel
    PSL$C_EXEC     Executive
    PSL$C_SUPER    Supervisor
    PSL$C_USER     User

    The most privileged access mode used is the access mode of
    the caller. The protection of the pages is read/write for the
    resultant access mode and those more privileged.

67  –  $CRETVA 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, adds a range of demand-
    zero allocation pages to a process's virtual address space for
    the execution of the current image. The new pages are added at
    the virtual address specified by the caller.

    This service accepts 64-bit addresses.

    Format

      SYS$CRETVA_64  region_id_64 ,start_va_64 ,length_64 ,acmode

                     ,flags ,return_va_64 ,return_length_64

    C Prototype

      int sys$cretva_64  (struct _generic_64 *region_id_64, void

                         *start_va_64, unsigned __int64 length_64,

                         unsigned int acmode, unsigned int flags,

                         void *(*(return_va_64)), unsigned __int64

                         *return_length_64);

67.1  –  Arguments

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region to create the virtual
    address range. The file VADEF.H in SYS$STARLET_C.TLB and the
    $VADEF macro in STARLET.MLB define a symbolic name for each of
    the three default regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified. Also, given a particular virtual address, the
    region ID for the region it is in can be obtained by calling the
    $GET_REGION_INFO system service specifying the VA$_REGSUM_BY_VA
    function.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting address for the created virtual address range. The
    specified virtual address must be a CPU-specific page aligned
    address.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space to be created. The length
    specified must be a multiple of CPU-specific pages.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode associated with the call to $CRETVA_64. The access
    mode determines the owner mode of the pages as well as the read
    and write protection on the pages. The acmode argument is a
    longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The $CRETVA_64 service uses whichever of the following access
    modes is least privileged:

    o  Access mode specified by the acmode argument

    o  Access mode of the caller

    The protection of the pages is read/write for the resultant
    access mode and those more privileged.

    Address space cannot be created within a region that has a create
    mode associated with it that is more privileged than the caller's
    mode. The condition value SS$_IVACMODE is returned if the caller
    is less privileged than the create mode for the region.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask controlling the characteristics of the demand-zero
    pages created. The flags argument is a longword bit vector in
    which each bit corresponds to a flag. The $VADEF macro and the
    VADEF.H file define a symbolic name for each flag. You construct
    the flags argument by performing a logical OR operation on the
    symbol names for all desired flags.

    The following table describes the flag that is valid for the
    $CRETVA_64 service:

    Flag               Description

    VA$M_NO_OVERMAP    Pages cannot overmap existing address space.
                       By default, pages can overmap existing address
                       space.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVVAFLG is returned if any undefined bits are set.

 return_va_64

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of the created virtual address
    range. The return_va_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword into which the service
    returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the virtual address range created. The
    return_length_64 argument is the 32- or 64-bit virtual address
    of a naturally aligned quadword into which the service returns
    the length of the virtual address range in bytes.

68  –  $CRMPSC

    Allows a process to associate (map) a section of its address
    space with either a specified section of a file (a disk file
    section) or specified physical addresses represented by page
    frame numbers (a page frame section). This service also allows
    the process to create either type of section and to specify that
    the section be available only to the creating process (private
    section) or to all processes that map to it (global section).

    Format

      SYS$CRMPSC  [inadr] ,[retadr] ,[acmode] ,[flags] ,[gsdnam]

                  ,[ident] ,[relpag] ,[chan] ,[pagcnt] ,[vbn] ,[prot]

                  ,[pfc]

    C Prototype

      int sys$crmpsc  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode, unsigned int

                      flags, void *gsdnam, unsigned int relpag,

                      unsigned short int chan, unsigned int pagcnt,

                      unsigned int vbn, unsigned int prot,unsigned

                      int pfc);

68.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Starting and ending virtual addresses into which the section is
    to be mapped. The inadr argument is the address of a 2-longword
    array containing, in order, the starting and ending process
    virtual addresses. Only the virtual page number portion of each
    virtual address is used to specify which pages are to be mapped;
    the low-order byte-within-page bits are ignored for this purpose.

    The interpretation of the inadr argument depends on the setting
    of SEC$M_EXPREG in the flags argument and whether you are
    using an Alpha or an Integrity server system. For a complete
    description of these differences, see the VSI OpenVMS System
    Services Reference Manual.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference-array reference
    Starting and ending process virtual addresses into which the
    section was actually mapped by $CRMPSC. The retadr argument
    is the address of a 2-longword array containing, in order, the
    starting and ending process virtual addresses.

    On Alpha and Integrity server systems, the retadr argument
    returns starting and ending addresses of the usable range of
    addresses. This might differ from the total amount mapped.
    The retadr argument is required when the relpag argument is
    specified. If the section being mapped does not completely
    fill the last page used to map the section, the retadr argument
    indicates the highest address that actually maps the section.
    If the relpag argument is used to specify an offset into the
    section, the retadr argument reflects the offset.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. The acmode argument is a longword containing the
    access mode.

    The $PSLDEF macro defines the following symbols for the four
    access modes:

    Symbol         Access Mode

    PSL$C_KERNEL   Kernel
    PSL$C_EXEC     Executive
    PSL$C_SUPER    Supervisor
    PSL$C_USER     User

    The most privileged access mode used is the access mode of the
    caller.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the type of section to be created or mapped
    to, as well as its characteristics. The flags argument is a
    longword bit vector wherein each bit corresponds to a flag.
    The $SECDEF macro defines a symbolic name for each flag. You
    construct the flags argument by performing a logical OR operation
    on the symbol names for all desired flags.

    The following table describes each flag and the default value
    that it supersedes:

    Flag             Description

    SEC$M_CRF        Pages are copy-on-reference. By default, pages
                     are shared.
    SEC$M_DZRO       Pages are demand-zero pages. By default, they
                     are not zeroed when copied.
    SEC$M_EXECUTE    Pages are mapped if the caller has execute
                     access. This flag takes effect only (1)  when
                     specified from executive or kernel mode, (2)
                     when the SEC$M_GBL flag is also specified, and
                     (3)  when SEC$M_WRT is not specified. By default
                     $CRMPSC performs a read access check against the
                     section.
    SEC$M_EXPREG     Pages are mapped into the first available space.
                     By default, pages are mapped into the range
                     specified by the inadr argument.

                     See the inadr argument description for a
                     complete explanation of how to set the SEC$M_
                     EXPREG flag.
    SEC$M_GBL        Pages form a global section. The default is
                     private section.
    SEC$M_NO_        Pages cannot overmap existing address space.
    OVERMAP          Note that, by default, pages can overmap
                     existing address space.
    SEC$M_PAGFIL     Pages form a global page file section. By
                     default, pages form a disk file section. SEC$M_
                     PAGFIL also implies SEC$M_WRT and SEC$M_DZRO.
    SEC$M_PERM       Global section is permanent. By default, global
                     sections are temporary.
    SEC$M_PFNMAP     Pages form a page frame section. By default,
                     pages form a disk file section. Pages mapped
                     by SEC$M_PFNMAP are not included in or charged
                     against the process's working set; they are
                     always valid. Do not lock these pages in the
                     working set by using $LKWSET; this can result in
                     a machine check if they are in I/O space.

                     On Alpha and Integrity server systems, when the
                     SEC$M_PFNMAP flag is set, the pagcnt and relpag
                     arguments are interpreted in CPU-specific pages,
                     not as pagelets.
    SEC$M_SYSGBL     Pages form a system global section. By default,
                     pages form a group global section.
    SEC$M_UNCACHED   Flag that must be set when a PFN-mapped section
                     is created if this section is to be treated
                     as uncached memory. Flag is ignored on Alpha
                     systems; it applies only to Integrity server
                     systems.
    SEC$M_WRT        Pages form a read/write section. By default,
                     pages form a read-only section.

 gsdnam

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the global section. The gsdnam argument is the address of
    a character string descriptor pointing to this name string.

    For group global sections, the operating system interprets the
    UIC group as part of the global section name; thus, the names of
    global sections are unique to UIC groups.

    You can specify any name from 1 to 43 characters. All processes
    mapping to the same global section must specify the same name.
    Note that the name is case sensitive.

    Use of characters valid in logical names is strongly encouraged.
    Valid values include alphanumeric characters, the dollar sign
    ($), and the underscore (_). If the name string begins with an
    underscore (_), the underscore is stripped and the resultant
    string is considered to be the actual name. Use of the colon (:)
    is not permitted.

    Names are first subject to a logical name translation, after
    the application of the prefix GBL$ to the name. If the result
    translates, it is used as the name of the section. If the
    resulting name does not translate, the name specified by the
    caller is used as the name of the section.

    Additional information on logical name translations and
    on section name processing is available in the VSI OpenVMS
    Programming Concepts Manual.

 ident

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Identification value specifying the version number of a global
    section and, for processes mapping to an existing global section,
    the criteria for matching the identification. The ident argument
    is the address of a quadword structure containing three fields.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. You
    can assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

    The first longword specifies, in its low-order two bits, the
    matching criteria. The valid values, symbolic names by which they
    can be specified, and their meanings are as follows:

    Value/Name       Match Criteria

    0 SEC$K_MATALL   Match all versions of the section.
    1 SEC$K_MATEQU   Match only if major and minor identifications
                     match.
    2 SEC$K_MATLEQ   Match if the major identifications are equal and
                     the minor identification of the mapper is less
                     than or equal to the minor identification of the
                     global section.

    When a section is mapped at creation time, the match control
    field is ignored.

    If you do not specify the ident argument or specify it as 0 (the
    default), the version number and match control fields default to
    0.

 relpag

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Relative page number within the global section of the first page
    in the section to be mapped. The relpag argument is a longword
    containing this page number.

    On Alpha and Integrity server systems, the relpag argument
    is interpreted as an index into the section file, measured in
    pagelets for a file-backed section or in CPU-specific pages for a
    PFN-mapped section.

    On Alpha or Integrity servers, you use this argument only for
    global sections. If you do not specify the relpag argument or
    specify it as 0 (the default), the global section is mapped
    beginning with the first virtual block in the file.

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Number of the channel on which the file has been accessed. The
    chan argument is a word containing this number.

    The file must have been accessed with the OpenVMS RMS macro
    $OPEN; the file options parameter (FOP) in the FAB must indicate
    a user file open (UFO keyword). The access mode at which the
    channel was opened must be equal to or less privileged than the
    access mode of the caller.

 pagcnt

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of pagelets in the section. The pagcnt argument is a
    longword containing this number.

    On Alpha and Integrity server systems, the smallest allocation
    is an Alpha or Integrity servers page, which is 8192 bytes. When
    requesting pagelets, the size requested is a multiple of 512
    bytes, but the actual allocation is rounded to 8192. For example,
    when requesting 17 pagelets, the allocation is for two Alpha or
    Integrity servers pages, 16384 bytes.

    On Alpha and Integrity server systems, if the SEC$M_PFNMAP flag
    bit is set, the pagcnt argument is interpreted as CPU-specific
    pages, not as pagelets.

    On Alpha or Integrity server systems , the specified page count
    is compared with the number of blocks in the section file;
    if they are different, the lower value is used. If you do not
    specify the page count or specify it as 0 (the default), the size
    of the section file is used. However, for physical page frame
    sections, this argument must not be 0.

 vbn

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Virtual block number in the file that marks the beginning of the
    section. The vbn argument is a longword containing this number.
    If you do not specify the vbn argument or specify it as 0 (the
    default), the section is created beginning with the first virtual
    block in the file.

    If you specified page frame number mapping (by setting the SEC$M_
    PFNMAP flag), the vbn argument specifies the CPU-specific page
    frame number where the section begins in memory.

    To view which arguments are required and which are optional for
    three different uses of the $CRMPSC service, see the VSI OpenVMS
    System Services Reference Manual.

 prot

    OpenVMS usage:file_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Protection to be applied to the global page file and PFN
    sections. For file-backed sections, the protection is taken from
    the backing file and the prot argument is ignored.

    The mask contains four 4-bit fields. Bits are read from right to
    left in each field.

    To view the diagram depicting the mask, see the VSI OpenVMS System
    Services Reference Manual.

    Cleared bits indicate that read, write, execute, and delete
    access, in that order, are granted to the particular category
    of user.

    Only read, write, and execute access are meaningful for section
    protection. Delete access bits are ignored. Read access also
    grants execute access for those situations where execute access
    applies.

    Protection is taken from the system or group global section
    template for page file or PFN global sections if the prot
    argument is not specified.

 pfc

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Page fault cluster size indicating how many pagelets are to be
    brought into memory when a page fault occurs for a single page.

    On Alpha and Integrity server systems, this argument is not used
    for page file sections or physical page frame sections. The pfc
    argument is rounded up to CPU-specific pages. That is, at least
    16 pagelets (on an Alpha or Integrity servers system with an
    8KB page size) will be mapped for each physical page. The system
    cannot map less than one physical page.

69  –  $CRMPSC FILE 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows a process to map
    a section of its address space to a specified portion of a file.
    This service creates and maps a private disk file section.

    This service accepts 64-bit addresses.

    Format

      SYS$CRMPSC_FILE_64  region_id_64 ,file_offset_64 ,length_64

                          ,chan ,acmode ,flags ,return_va_64

                          ,return_length_64 [,fault_cluster

                          [,start_va_64]]

    C Prototype

      int sys$crmpsc_file_64  (struct _generic_64 *region_id_64,

                              unsigned __int64 file_offset_64,

                              unsigned __int64 length_64, unsigned

                              short int chan, unsigned int

                              acmode, unsigned int flags, void

                              *(*(return_va_64)), unsigned __int64

                              *return_length_64,...);

69.1  –  Arguments

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region to map the private disk
    file section. The file VADEF.H in SYS$STARLET_C.TLB and the
    $VADEF macro in STARLET.MLB define a symbolic name for each of
    the three default regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified.

 file_offset_64

    OpenVMS usage:byte offset
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Byte offset into the file that marks the beginning of the
    section. The file_offset_64 argument is a quadword containing
    this number. If you specify the file_offset_64 argument as 0, the
    section is created beginning with the first byte in the file.

    The file_offset_64 argument must be a multiple of virtual disk
    blocks.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    value
    Length, in bytes, of the private disk file section to be created
    and mapped to. The length specified must be 0 or a multiple of
    virtual disk blocks. If the length specified is 0 or extends
    beyond end-of-file (EOF), the disk file is mapped up to and
    including the virtual block number that contains EOF.

 chan

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the channel on which the file has been accessed. The
    chan argument is a longword containing this number. The access
    mode at which the channel was opened must be equal to or less
    privileged than the access mode of the caller.

    Use the OpenVMS Record Management Services (RMS) macro $OPEN
    to access a file; the file options parameter in the file access
    block must indicate a user file open (UFO) keyword.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. The acmode argument is a longword containing the
    access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. The calling process can delete pages only if those pages
    are owned by an access mode equal to or less privileged than the
    access mode of the calling process.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the characteristics of the private section
    to be created. The flags argument is a longword bit vector in
    which each bit corresponds to a flag. The $SECDEF macro and the
    SECDEF.H file define a symbolic name for each flag. You construct
    the flags argument by performing a logical OR operation on the
    symbol names for all desired flags.

    The following table describes each flag that is valid for the
    $CRMPSC_FILE_64 service:

    Flag          Description

    SEC$M_CRF     Pages are copy-on-reference.
    SEC$M_DZRO    Pages are demand-zero pages. By default, they are
                  not zeroed when copied.

                  Note that SEC$M_DZRO and SEC$M_CRF cannot both be
                  set and that SEC$M_DZRO set and SEC$M_WRT clear is
                  an invalid combination.
    SEC$M_EXPREG  Pages are mapped into the first available space at
                  the current end of the specified region.
    SEC$M_NO_     Pages cannot overmap existing address space. By
    OVERMAP       default, pages can overmap existing address space.
    SEC$M_WRT     Pages form a read/write section. By default, pages
                  form a read-only section.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set or if
    an illegal combination of flags is set.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address into which the private disk
    file section was mapped. The return_va_64 argument is the 32- or
    64-bit virtual address of a naturally aligned quadword into which
    the service returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned quadword
    into which the service returns the length of the usable virtual
    address range mapped in bytes. This length might differ from
    the total amount mapped. If the section being mapped does not
    completely fill the last page used to map the section, the
    return_va_64 and return_length_64 arguments indicate the highest
    address that actually maps the section.

 fault_cluster

    OpenVMS usage:byte count
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Page fault cluster in byte units indicating how many pages
    are to be brought into memory when a page fault occurs for a
    single page. The fault cluster specified will be rounded up to a
    multiple of CPU-specific pages.

    If this argument is specified as 0, the process default page
    fault cluster will be used. If this argument is specified as more
    than the maximum allowed for the system, no condition value will
    be returned. The systemwide maximum will be used.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address to map the private disk file
    section. The specified virtual address must be a CPU-specific
    page aligned address. If the flag SEC$M_EXPREG is specified, the
    start_va_64 argument must not be specified or must be specified
    as 0. If SEC$M_EXPREG is set and the start_va_64 argument is
    nonzero, the condition value SS$_IVSECFLG is returned.

70  –  $CRMPSC GDZRO 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows a process to create
    a memory-resident global demand-zero section and to map a section
    of its address space to the global section. Shared page table
    sections can also be created.

    This service accepts 64-bit addresses.

    Format

      SYS$CRMPSC_GDZRO_64  gs_name_64 ,ident_64 ,prot ,length_64

                           ,region_id_64 ,section_offset_64 ,acmode

                           ,flags ,return_va_64 ,return_length_64

                           [[[[,start_va_64] ,map_length_64]

                           ,reserved_length_64] ,rad_mask]

    C Prototype

      int sys$crmpsc_gdzro_64  (void *gs_nam_64, struct _secid

                               *ident_64, unsigned int prot, unsigned

                               __int64 length_64, struct _generic_64

                               *region_id_64, unsigned __int64

                               section_offset_64, unsigned int

                               acmode, unsigned int flags, void

                               *(*(return_va_64)), unsigned __int64

                               *return_length_64,...);

70.1  –  Arguments

 gs_name_64

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section. The gs_name_64 argument is the 32-
    or 64-bit virtual address of a naturally aligned 32- or 64-bit
    string descriptor pointing to this name string.

 ident_64

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of a global
    section. The ident_64 argument is a quadword containing three
    fields. The ident_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword that contains the
    identification value.

    The first longword specifies the matching criteria in its low-
    order 2 bits. The valid values, symbolic names by which they can
    be specified, and their meanings are as follows:

           Symbolic
    Value  Name           Match Criteria

    0      SEC$K_MATALL   Match all versions of the section.
    1      SEC$K_MATEQU   Match only if major and minor
                          identifications match.
    2      SEC$K_MATLEQ   Match if the major identifications are
                          equal and the minor identification of the
                          mapper is less than or equal to the minor
                          identification of the global section.

    When a section is mapped at creation time, the match control
    field is ignored. If you specify the ident_64 argument as 0, the
    version number and match control fields default to 0.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. You
    can assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

 prot

    OpenVMS usage:file_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Protection to be applied to the global demand-zero section. The
    mask contains four 4-bit fields. Bits are read from right to left
    in each field.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the diagram depicting the mask.

    Cleared bits indicate that read, write, execute, and delete
    access, in that order, are granted to the particular category
    of user. Only read, write, and execute access are meaningful
    for section protection. Delete access bits are ignored. Read
    access also grants execute access for those situations where
    execute access applies. If zero is specified, read access and
    write access are granted to all users.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length, in bytes, of the global demand-zero section to be
    created. The length_64 must be specified as a multiple of the
    CPU-specific page size. A length of 0 cannot be specified.

                                   NOTE

       Creating a memory-resident global section with shared page
       table does not imply that the global section must have an
       even multiple of CPU-specific page table pages. The global
       section might not fully use the last page table page.

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region to map the global page
    file section.

    The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in
    STARLET.MLB define a symbolic name for each of the three default
    regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified.

 section_offset_64

    OpenVMS usage:byte offset
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Offset into the global section to start mapping into the
    process's virtual address space. The offset specified must be
    a multiple of a CPU-specific page size.

    If a shared page table region is specified by the region_id_
    64 argument, section_offset_64 must be an even multiple of
    the larger of the number of bytes that can be mapped by a CPU-
    specific page. For Integrity server systems, the alignment of
    section offsets must also be an integer multiple of the page size
    used to map VA space at this offset.

    VSI recommends that you avoid any partial mapping of memory-
    resident sections when you use shared page tables on Integrity
    server systems. If you cannot avoid this, set bit 4 in the system
    parameter MMG_CTLFLAGS to limit the effective page size to the
    number of bytes that can be mapped by a page.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. This access mode is also the read access mode
    and the write access mode. The acmode argument is a longword
    containing the access mode.

    If the memory-resident global section is created with shared
    page tables, this is the access mode that is stored in the owner,
    read, and write fields of the corresponding shared page table
    entries (PTEs).

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. The calling process can delete pages only if those pages
    are owned by an access mode equal to or less privileged than the
    access mode of the calling process.

    Address space cannot be created within a region that has a create
    mode associated with it that is more privileged than the caller's
    mode. The condition value SS$_IVACMODE is returned if the caller
    is less privileged than the create mode for the region.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the type of the global section to be created
    as well as its characteristics. The flags argument is a longword
    bit vector in which each bit corresponds to a flag. The $SECDEF
    macro and the SECDEF.H file define a symbolic name for each
    flag. You construct the flags argument by performing a logical
    OR operation on the symbol names for all desired flags.

    The following table describes each flag that is valid for the
    $CRMPSC_GDZRO_64 service:

    Flag          Description

    SEC$M_DZRO    Pages are demand-zero pages. By default, this flag
                  is always present in this service and cannot be
                  disabled.

    SEC$M_EXPREG  Pages are mapped into the first available space at
                  the current end of the specified region.

                  If the /ALLOCATE qualifier was specified when the
                  global section was registered in the Reserved
                  Memory Registry, virtually aligned addresses
                  after the first available space are chosen for
                  the mapping.

    SEC$M_GBL     Pages form a global section. By default, this flag
                  is always present in this service and cannot be
                  disabled.

    SEC$M_NO_     Pages cannot overmap existing address space.
    OVERMAP

    SEC$M_PERM    Global section is permanent.

    SEC$M_RAD_    When set, the argument rad_mask is used as a mask
    HINT          of RADs from which to allocate memory. See the rad_
                  mask argument description for more information.

    SEC$M_READ_   Create shared table pages for the section that
    ONLY_SHPT     allow read access only.

    SEC$M_SHMGS   Create a shared-memory global section.

    SEC$M_SYSGBL  Pages form a system global section. By default,
                  pages form a group global section.

    SEC$M_MRES    Pages form a memory-resident section. By default,
                  this page is always present in this service and
                  cannot be disabled.

    SEC$M_WRT     Pages form a read/write section. By default, this
                  flag is always present in this service and cannot
                  be disabled.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set or if
    an invalid combination of flags is set.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address into which the global demand-
    zero section was mapped. The return_va_64 argument is the 32- or
    64-bit virtual address of a naturally aligned quadword into which
    the service returns the virtual address.

    If a shared page table region is specified by the region_id_64
    argument and the SEC$M_EXPREG flag is set, the returned virtual
    address is aligned to a CPU-specific page table page boundary.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned quadword
    into which the service returns the length of the virtual address
    range mapped in bytes.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address to map the memory-resident global
    section. The specified virtual address must be a CPU-specific
    page aligned address. If the flag SEC$M_EXPREG is specified, the
    start_va_64 argument must not be specified or must be specified
    as 0. If SEC$M_EXPREG is set and the start_va_64 argument is
    nonzero, the condition value SS$_IVSECFLG is returned.

    If SEC$M_EXPREG is clear, start_va_64 is nonzero, and a shared
    page table region is specified, the specified starting address
    must be aligned to a natural page table page boundary; otherwise,
    the condition value SS$_VA_NOTPAGALGN is returned.

    If the /ALLOCATE qualifier was specified when the memory-resident
    global section was registered in the Reserved Memory Registry
    and start_va_64 is aligned to a multiple of CPU-specific pages
    appropriate for taking advantage of granularity hints then
    granularity hints are used to map to the global section:

    o  On Alpha systems, granularity hints mean multiples of pages,
       regardless of page size. The multiples 8, 64, and 512 pages
       are architected.

    o  On Integrity server systems, OpenVMS initially supports page
       sizes of 64KB, 256KB, and 4MB instead of granularity hints.
       Additional pages sizes will be supported in the future.

    If the flag VA$M_SHARED_PTS is set and this argument is
    specified, the specified starting address must be aligned to
    the larger of a natural page table boundary or to the largest
    possible page size used to map the section. If the alignment is
    less than a page table boundary, the $CREATE_REGION_64 service
    returns an error. If the alignment is less than the largest page
    size used in the section, an error might be returned when you
    attempt to map the section.

    If you do not specify a starting address, OpenVMS automatically
    ensures correct alignment.

 map_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the memory-resident global section to be mapped. The
    length specified must be a multiple of CPU-specific pages. If
    this argument is not specified or is specified as zero, the
    global file section is mapped up to and including the last page
    in that section.

    If a shared page table region is specified by the region_id_64
    argument, map_length_64 must be an even multiple of the number
    of bytes that can be mapped by a CPU-specific page table page or
    must include the last page within the global section.

 reserved_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    32- or 64-bit reference
    Length, in bytes, of the global section as currently registered
    in the Reserved Memory Registry. The reserved_length_64 argument
    is the 32- or 64-bit virtual address of a naturally aligned
    quadword into which the service returns the reserved length.

    If reserved_length_64 is not specified or is specified as 0, no
    reserved length is returned to the caller.

    If the memory-resident global section is not registered,
    reserved_length_64 is written with the value 0.

 rad_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Use the rad_mask argument to specify from which RADs to allocate
    memory. Currently only one bit may be set. The specified RAD
    must contain memory. This argument is only a hint. Memory may be
    obtained from other RADs if no free memory is available at the
    time of allocation.

    The rad_mask argument is considered only if the SEC$M_RAD_HINT
    flag is specified. Otherwise, this argument is ignored.

    On a system that does not support resource affinity domains
    (RADs), specifying 1 for the rad_mask argument is allowed.

    RAD is supported on AlphaServer GS series systems and starting
    from OpenVMS Version 8.4, support is extended to NUMA capable
    Integrity servers.

71  –  $CRMPSC GFILE 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows a process to create
    a global disk file section and to map a section of its address
    space to the global section.

    This service accepts 64-bit addresses.

    Format

      SYS$CRMPSC_GFILE_64  gs_name_64 ,ident_64 ,file_offset_64

                           ,length_64 ,chan ,region_id_64

                           ,section_offset_64 ,acmode ,flags

                           ,return_va_64 ,return_length_64

                           [,fault_cluster

                           [,start_va_64 [,map_length_64]]]

    C Prototype

      int sys$crmpsc_gfile_64  (void *gs_nam_64, struct _secid

                               *ident_64, unsigned __int64

                               file_offset_64, unsigned __int64

                               length_64, unsigned short

                               int chan, struct _generic_64

                               *region_id_64, unsigned __int64

                               section_offset_64, unsigned int

                               acmode, unsigned int flags, void

                               *(*(return_va_64)), unsigned __int64

                               *return_length_64,...);

71.1  –  Arguments

 gs_name_64

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section. The gs_name_64 argument is the 32-
    or 64-bit virtual address of a naturally aligned 32- or 64-bit
    string descriptor pointing to this name string.

 ident_64

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of a global
    section. The ident_64 argument is a quadword containing three
    fields. The ident_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword that contains the
    identification value.

    The first longword specifies the matching criteria in its low-
    order 2 bits. The valid values, symbolic names by which they can
    be specified, and their meanings are as follows:

           Symbolic
    Value  Name           Match Criteria

    0      SEC$K_MATALL   Match all versions of the section.
    1      SEC$K_MATEQU   Match only if major and minor
                          identifications match.
    2      SEC$K_MATLEQ   Match if the major identifications are
                          equal and the minor identification of the
                          mapper is less than or equal to the minor
                          identification of the global section.

    When a section is mapped at creation time, the match control
    field is ignored. If you specify the ident_64 argument as 0, the
    version number and match control fields default to 0.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. You
    can assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

 file_offset_64

    OpenVMS usage:byte offset
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Byte offset into the file that marks the beginning of the
    section. The file_offset_64 argument is a quadword containing
    this number. If you specify the file_offset_64 argument as 0, the
    section is created beginning with the first byte in the file.

    The file offset specified must be a multiple of virtual disk
    blocks.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length, in bytes, of the global disk file section to be created.
    The length specified must be 0 or a multiple of virtual disk
    blocks. If the length specified is 0 or extends beyond the end-
    of-file (EOF), the global disk file section is created up to and
    including the virtual block number that contains EOF.

 chan

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the channel on which the file has been accessed. The
    chan argument is a longword containing this number. The access
    mode at which the channel was opened must be equal to or less
    privileged than the access mode of the caller.

    You can use the OpenVMS Record Management Services (RMS) macro
    $OPEN to access a file; the file options parameter in the file
    access block must indicate a user file open (UFO) keyword.

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 64 bit reference
    The region ID associated with the region in which to map the
    global disk file section. The file VADEF.H in SYS$STARLET_C.TLB
    and the $VADEF macro in STARLET.MLB define a symbolic name for
    each of the three default regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified.

 section_offset_64

    OpenVMS usage:byte offset
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Offset into the global section to start mapping into the
    process's virtual address space. The offset specified must be
    a multiple of virtual disk blocks.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. The acmode argument is a longword containing the
    access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller.

    Address space cannot be created within a region that has a create
    mode associated with it that is more privileged than the caller's
    mode. The condition value SS$_IVACMODE is returned if the caller
    is less privileged than the create mode for the region.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the characteristics of the global section
    to be created. The flags argument is a longword bit vector in
    which each bit corresponds to a flag. The $SECDEF macro and the
    SECDEF.H file define a symbolic name for each flag. You construct
    the flags argument by performing a logical OR operation on the
    symbol names for all desired flags.

    The following table describes each flag that is valid for the
    $CRMPSC_GFILE_64 service:

    Flag          Description

    SEC$M_CRF     Pages are copy-on-reference.
    SEC$M_GBL     Pages form a global section. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_WRT     Pages form a read/write section. By default, pages
                  form a read-only section.
    SEC$M_DZRO    Pages are demand-zero pages. By default, they are
                  not zeroed when copied.

                  Note that SEC$M_DZRO and SEC$M_CRF cannot both be
                  set and that SEC$M_DZRO set and SEC$M_WRT clear is
                  an invalid combination.
    SEC$M_EXPREG  Pages are mapped into the first available space at
                  the current end of the specified region.
    SEC$M_NO_     Pages cannot overmap existing address space. By
    OVERMAP       default, pages can overmap existing address space.
    SEC$M_PERM    Global section is permanent. By default, global
                  sections are temporary.
    SEC$M_SYSGBL  Pages form a system global section. By default,
                  pages form a group global section.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set or if
    an illegal combination of flags is set.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address into which the global disk
    file section was mapped. The return_va_64 argument is the 32- or
    64-bit virtual address of a naturally aligned quadword into which
    the service returns the virtual address.

    Upon successful completion of this service, if the
    section_offset_64 argument was specified, the virtual address
    returned in return_va_64 reflects the offset into the global
    section mapped such that the virtual address returned cannot
    be aligned on a CPU-specific page boundary. The virtual address
    returned will always be on an even virtual disk block boundary.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned quadword
    into which the service returns the length of the virtual address
    range mapped in bytes.

    Upon successful completion of this service, the value in the
    return_length_64 argument indicates the amount of created address
    space backed by the section file.

    If the number of disk blocks mapped does not represent an exact
    multiple of CPU-specific pages, the last page in the mapped
    address space will not be completely mapped by the section file.
    In this case, modifying memory beyond the amount indicated by
    return_length_64 can result in the loss of this data.

    Unlike the return_length_64 argument for the $CREATE_GFILE
    service, upon successful completion of this service, the
    return_length_64 argument does not represent the total length
    of the global section created if the section_offset_64 argument
    was specified as nonzero. The value in the section_offset_64
    argument plus the value in the return_length_64 argument is the
    total length of the global disk file section created.

 fault_cluster

    OpenVMS usage:byte count
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Page fault cluster in byte units indicating how many pages
    are to be brought into memory when a page fault occurs for a
    single page. The fault cluster specified will be rounded up to a
    multiple of CPU-specific pages.

    If this argument is specified as 0, the system default page fault
    cluster will be used. If this argument is specified as more than
    the maximum allowed for the system, no error will be returned.
    The systemwide maximum will be used.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address to map the global disk file section.
    The specified virtual address must be a CPU-specific page aligned
    address. If the flag SEC$M_EXPREG is specified, this argument
    will not be used. If SEC$M_EXPREG is clear and the start_va_64
    argument is not specified or is specified as 0, the condition
    value SS$_IVSECFLG will be returned.

    Always refer to the return_va_64 and return_length_64 arguments
    to determine the usable range of virtual addresses mapped.

 map_length_64

    OpenVMS usage:byte count
    type:         quadword unsigned
    access:       read only
    mechanism:    by value
    Length of the global disk file section to be mapped. The length
    specified must be a multiple of virtual disk blocks. If this
    argument is not specified as zero, the global disk section is
    mapped up to and including the last disk block in the section.

72  –  $CRMPSC GPFILE 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows a process to create
    a global page file section and to map a section of its address
    space to the global section.

    This service accepts 64-bit addresses.

    Format

      SYS$CRMPSC_GPFILE_64  gs_name_64 ,ident_64 ,prot ,length_64

                            ,region_id_64 ,section_offset_64 ,acmode

                            ,flags ,return_va_64 ,return_length_64

                            [,start_va_64 [,map_length_64]]

    C Prototype

      int sys$crmpsc_gpfile_64  (void *gs_nam_64, struct _secid

                                *ident_64, unsigned int prot,

                                unsigned __int64 length_64, struct

                                _generic_64 *region_id_64, unsigned

                                __int64 section_offset_64, unsigned

                                int acmode, unsigned int flags, void

                                *(*(return_va_64)), unsigned __int64

                                *return_length_64,...);

72.1  –  Arguments

 gs_name_64

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section. The gs_name_64 argument is the 32-
    or 64-bit virtual address of a naturally aligned 32- or 64-bit
    string descriptor pointing to this name string.

 ident_64

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of a global
    section. The ident_64 argument is a quadword containing three
    fields. The ident_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword that contains the
    identification value.

    The first longword specifies the matching criteria in its low-
    order 2 bits. The valid values, symbolic names by which they can
    be specified, and their meanings are as follows:

           Symbolic
    Value  Name           Match Criteria

    0      SEC$K_MATALL   Match all versions of the section.
    1      SEC$K_MATEQU   Match only if major and minor
                          identifications match.
    2      SEC$K_MATLEQ   Match if the major identifications are
                          equal and the minor identification of the
                          mapper is less than or equal to the minor
                          identification of the global section.

    When a section is mapped at creation time, the match control
    field is ignored. If you specify the ident_64 argument as 0, the
    version number and match control fields default to 0.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. You
    can assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

 prot

    OpenVMS usage:file_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Protection to be applied to the global page file section. The
    mask contains four 4-bit fields. Bits are read from right to left
    in each field.

    To view the mask diagram, see the VSI OpenVMS System Services
    Reference Manual.

    Cleared bits indicate that read, write, execute, and delete
    access, in that order, are granted to the particular category
    of user. Only read, write, and execute access are meaningful
    for section protection. Delete access bits are ignored. Read
    access also grants execute access for those situations where
    execute access applies. If zero is specified, read access and
    write access are granted to all users.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length, in bytes, of the global page file section to be created.
    The length specified must be a multiple of CPU-specific pages. A
    length of 0 cannot be specified.

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region to map the global page
    file section.

    The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in
    STARLET.MLB define a symbolic name for each of the three default
    regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified.

 section_offset_64

    OpenVMS usage:byte offset
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Offset into the global section to start mapping into the
    process's virtual address space. The offset specified must be
    a multiple of virtual disk blocks.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. The acmode argument is a longword containing the
    access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. The calling process can delete pages only if those pages
    are owned by an access mode equal to or less privileged than the
    access mode of the calling process.

    Address space cannot be created within a region that has a create
    mode associated with it that is more privileged than the caller's
    mode. The condition value SS$_IVACMODE is returned if the caller
    is less privileged than the create mode for the region.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the characteristics of the global section
    to be created. The flags argument is a longword bit vector in
    which each bit corresponds to a flag. The $SECDEF macro and the
    SECDEF.H file define a symbolic name for each flag. You construct
    the flags argument by performing a logical OR operation on the
    symbol names for all desired flags.

    The following table describes each flag that is valid for the
    $CRMPSC_GPFILE_64 service:

    Flag          Description

    SEC$M_DZRO    Pages are demand-zero pages. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_EXPREG  Pages are mapped into the first available space
                  at the current end of the specified region.
                  SEC$M_EXPREG cannot be specified with the
                  SEC$M_NO_OVERMAP flag.
    SEC$M_GBL     Pages form a global section. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_NO_     Pages cannot overmap existing address space. By
    OVERMAP       default, pages can overmap existing address space.
                  SEC$M_NO_OVERMAP cannot be specified with the
                  SEC$M_EXPREG flag.
    SEC$M_PAGFIL  Pages form a global page file section. By default,
                  this flag is always present in this service and
                  cannot be disabled.
    SEC$M_PERM    Global section is permanent. By default, global
                  sections are temporary.
    SEC$M_SYSGBL  Pages form a system global section. By default,
                  pages form a group global section.
    SEC$M_WRT     Pages form a read/write section. By default, this
                  flag is always present in this service and cannot
                  be disabled.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set or if
    an invalid combination of flags is set.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address into which the global page
    file section was mapped. The return_va_64 argument is the 32- or
    64-bit virtual address of a naturally aligned quadword into which
    the service returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned quadword
    into which the service returns the length of the virtual address
    range mapped in bytes.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address to map the global page file section.
    The specified virtual address must be a CPU-specific page aligned
    address. If the flag SEC$M_EXPREG is specified, the start_va_64
    argument must not be specified or must be specified as 0. If
    SEC$M_EXPREG is set and the start_va_64 argument is nonzero, the
    condition value SS$_IVSECFLG is returned.

    Always refer to the return_va_64 and return_length_64 arguments
    to determine the range of virtual addresses mapped.

 map_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the global page file section to be mapped. The length
    specified must be a multiple of CPU-specific pages. If this
    argument is not specified or is specified as zero, the global
    file section is mapped up to and including the last page in that
    section.

73  –  $CRMPSC GPFN 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows a process to create
    a permanent global page frame section and to map a section of its
    address space to the global page frame section.

    This service accepts 64-bit addresses.

    Format

      SYS$CRMPSC_GPFN_64  gs_name_64 ,ident_64 ,prot ,start_pfn

                          ,page_count ,region_id_64 ,relative_page

                          ,acmode ,flags ,return_va_64

                          ,return_length_64 [,start_va_64

                          [,map_page_count]]

    C Prototype

      int sys$crmpsc_gpfn_64  (void *gs_nam_64, struct _secid

                              *ident_64, unsigned int prot, unsigned

                              int start_pfn, unsigned int page_count,

                              struct _generic_64 *region_id_64,

                              unsigned int relative_page, unsigned

                              int acmode, unsigned int flags, void

                              *(*(return_va_64)), unsigned __int64

                              *return_length_64,...);

73.1  –  Arguments

 gs_name_64

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section. The gs_name_64 argument is the 32-
    or 64-bit virtual address of a naturally aligned 32- or 64-bit
    string descriptor pointing to this name string.

 ident_64

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of a global
    section. The ident_64 argument is a quadword containing three
    fields. The ident_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword that contains the
    identification value.

    The first longword specifies the matching criteria in its low-
    order 2 bits. The valid values, symbolic names by which they can
    be specified, and their meanings are as follows:

           Symbolic
    Value  Name           Match Criteria

    0      SEC$K_MATALL   Match all versions of the section.
    1      SEC$K_MATEQU   Match only if major and minor
                          identifications match.
    2      SEC$K_MATLEQ   Match if the major identifications are
                          equal and the minor identification of the
                          mapper is less than or equal to the minor
                          identification of the global section.

    When a section is mapped at creation time, the match control
    field is ignored. If you specify the ident_64 argument as 0, the
    version number and match control fields default to 0.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. You
    can assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

 prot

    OpenVMS usage:file_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Protection to be applied to the global page file section.

    The mask contains four 4-bit fields. Bits are read from right to
    left in each field.

    To view the mask diagram, see the VSI OpenVMS System Services
    Reference Manual.

    Cleared bits indicate that read, write, execute, and delete
    access, in that order, are granted to the particular category
    of user. Only read, write, and execute access are meaningful
    for section protection. Delete access bits are ignored. Read
    access also grants execute access for those situations where
    execute access applies. If zero is specified, read access and
    write access are granted to all users.

 start_pfn

    OpenVMS usage:page frame number
    type:         longword (unsigned) on Alpha, quadword (unsigned)
                  on Integrity servers
    access:       read only
    mechanism:    by value
    The CPU-specific page frame number where the section begins.

 page_count

    OpenVMS usage:CPU-specific page count
    type:         longword (unsigned) on Alpha, quadword (unsigned)
                  on Integrity servers
    access:       read only
    mechanism:    by value
    Length of the page frame section in CPU-specific pages.

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region to map the global page
    frame section. The file VADEF.H in SYS$STARLET_C.TLB and the
    $VADEF macro in STARLET.MLB define a symbolic name for each of
    the three default regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified.

 relative_page

    OpenVMS usage:CPU-specific page number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Relative CPU-specific page number within the global section to
    start mapping.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. The acmode argument is a longword containing the
    access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller.

    Address space cannot be created within a region that has a create
    mode associated with it that is more privileged than the caller's
    mode. The condition value SS$_IVACMODE is returned if the caller
    is less privileged than the create mode for the region.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the characteristics of the global section
    to be created. The flags argument is a longword bit vector in
    which each bit corresponds to a flag. The $SECDEF macro and the
    SECDEF.H file define a symbolic name for each flag. You construct
    the flags argument by performing a logical OR operation on the
    symbol names for all desired flags.

    The following table describes each flag that is valid for
    $CRMPSC_GPFN_64:

    Flag          Description

    SEC$M_ARGS64  Indicates that all parameters, specifically start_
                  pfn and page_count, are passed as 64-bit numbers.
                  This flag is ignored on OpenVMS Alpha but must be
                  set on Integrity server systems. If the flag is
                  not set on Integrity servers, the error code SS$_
                  IVSECFLG is returned.
    SEC$M_EXPREG  Pages are mapped into the first available space at
                  the current end of the specified region.
    SEC$M_GBL     Pages form a global section. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_PERM    Global section is permanent. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_PFNMAP  Pages form a page frame section. By default, this
                  flag is always present in this service and cannot
                  be disabled.
    SEC$M_NO_     Pages cannot overmap existing address space. By
    OVERMAP       default, pages can overmap existing address space.
    SEC$M_SYSGBL  Pages form a system global section. By default,
                  pages form a group global section.
    SEC$M_        Flag that must be set when a PFN-mapped section
    UNCACHED      is created if this section must be treated as
                  uncached memory. Flag is ignored on Alpha systems;
                  it applies only to Integrity server systems.
    SEC$M_WRT     Pages form a read/write section. By default, pages
                  form a read-only section.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set or if
    an illegal combination of flags is set.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address into which the global page
    frame section was mapped. The return_va_64 argument is the 32-
    or 64-bit address of a naturally aligned quadword into which the
    service returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned quadword
    into which the service returns the length of the virtual address
    range mapped in bytes.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address to map the global page frame
    section. The specified virtual address must be a CPU-specific
    page-aligned address. If the flag SEC$M_EXPREG is specified, the
    start_va_64 argument must not be specified or must be specified
    as 0. If SEC$M_EXPREG is set and the start_va_64 argument is
    nonzero, the condition value SS$_IVSECFLG is returned.

    Always refer to the return_va_64 and return_length_64 arguments
    to determine the range of virtual addresses mapped.

 map_page_count

    OpenVMS usage:CPU-specific page count
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the global page frame section to be mapped in CPU-
    specific pages.

74  –  $CRMPSC PFN 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows a process to map
    a section of its address space to a specified physical address
    range represented by page frame numbers. This service creates and
    maps a private page frame section.

    This service accepts 64-bit addresses.

    Format

      SYS$CRMPSC_PFN_64  region_id_64 ,start_pfn ,page_count ,acmode

                         ,flags ,return_va_64 ,return_length_64

                         [,start_va_64]

    C Prototype

      int sys$crmpsc_pfn_64  (struct _generic_64 *region_id_64,

                             unsigned int start_pfn, unsigned

                             int page_count, unsigned int

                             acmode, unsigned int flags, void

                             *(*(return_va_64)), unsigned __int64

                             *return_length_64,...);

74.1  –  Arguments

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region to map the private page
    frame section. The file VADEF.H in SYS$STARLET_C.TLB and the
    $VADEF macro in STARLET.MLB define a symbolic name for each of
    the three default regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified.

 start_pfn

    OpenVMS usage:page frame number
    type:         longword (unsigned)on Alpha, quadword (unsigned) on
                  Integrity servers
    access:       read only
    mechanism:    by value
    The CPU-specific page frame number where the section begins in
    memory.

 page_count

    OpenVMS usage:CPU-specific page count
    type:         longword (unsigned) on Alpha, quadword (unsigned)
                  on Integrity servers
    access:       read only
    mechanism:    by value
    Length of the page frame section in CPU-specific pages.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. The acmode argument is a longword containing the
    access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. The calling process can delete pages only if those pages
    are owned by an access mode equal to or less privileged than the
    access mode of the calling process.

    Address space cannot be created within a region that has a create
    mode associated with it that is more privileged than the caller's
    mode. The condition value SS$_IVACMODE is returned if the caller
    is less privileged than the create mode for the region.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the characteristics of the private section
    to be created. The flags argument is a longword bit vector in
    which each bit corresponds to a flag. The $SECDEF macro and the
    SECDEF.H file define a symbolic name for each flag. You construct
    the flags argument by performing a logical OR operation on the
    symbol names for all desired flags.

    The following table describes each flag that is valid for the
    $CRMPSC_PFN_64 service:

    Flag            Description

    SEC$M_ARGS64    Indicates that all parameters, specifically
                    start_pfn and page_count, are passed as 64-bit
                    numbers. This flag is ignored on OpenVMS Alpha
                    but must be set on Integrity server systems. If
                    the flag is not set on Integrity servers, the
                    error code SS$_IVSECFLG is returned.
    SEC$M_EXPREG    Pages are mapped into the first available space
                    at the current end of the specified region.
    SEC$M_NO_       Pages cannot overmap existing address space.
    OVERMAP         By default, pages can overmap existing address
                    space.
    SEC$M_PFNMAP    Pages form a page frame section. By default, this
                    flag is always present in this service and cannot
                    be disabled.
    SEC$M_          Flag that must be set when a PFN-mapped section
    UNCACHED        is created if this section must be treated
                    as uncached memory. Flag is ignored on Alpha
                    systems; it applies only to Integrity server
                    systems.
    SEC$M_WRT       Pages form a read/write section. By default,
                    pages form a read-only section.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set or if
    an invalid combination of flags is set.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address into which the private page
    frame section was mapped. The return_va_64 argument is the 32- or
    64-bit virtual address of a naturally aligned quadword into which
    the service returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the virtual address range mapped. The
    return_length_64 argument is the 32- or 64-bit virtual address
    of a naturally aligned quadword into which the service returns
    the length of the virtual address range in bytes.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address to map the private page frame
    section. The specified virtual address must be a CPU-specific
    page aligned address. If the flag SEC$M_EXPREG is specified, the
    start_va_64 argument must not be specified or must be specified
    as 0. If SEC$M_EXPREG is set and the start_va_64 argument is
    nonzero, the condition value SS$_IVESCFLG is returned.

75  –  $CVT FILENAME (Alpha and Integrity servers)

    Converts a string from RMS format to file-system (ACP-QIO) format
    or from file-system (ACP-QIO) format to RMS format.

    Format

      SYS$CVT_FILENAME  cvttyp ,srcstr ,inflags ,outbuf ,outlen

                        ,outflags

    C Prototype

      int sys$cvt_filename  (unsigned int cvttyp, void *srcstr,

                            unsigned int inflags, void *outbuf,

                            unsigned short int *outlen, unsigned int

                            *outflags);

75.1  –  Arguments

 cvttyp

    OpenVMS usage:unsigned_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Longword value that indicates whether the conversion is from RMS
    format to ACP-QIO format or vice versa.

    There are two legal values for this parameter, represented by the
    symbols CVTFNM$C_ACPQIO_TO_RMS and CVTFNM$C_RMS_TO_ACPQIO, that
    are defined by the $CVTFNMDEF macro.

 srcstr

    OpenVMS usage:string of bytes or words
    type:         string of bytes or words
    access:       read only
    mechanism:    by 32-bit descriptor-fixed-length string descriptor
    String to be converted by the service.

    If the conversion is from RMS format to ACP-QIO format, srcstr
    is an ISO-Latin-1 or VTF-7-encoded character string. If the
    conversion is from ACP-QIO format to RMS format, srcstr is a
    string of byte-width or word-width characters.

    The descriptor length field indicates the length of the input
    string in bytes, whether the characters are byte-width or word-
    width.

    The srcstr argument is the 32-bit address of a descriptor that
    points to this string.

 inflags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Longword flag mask indicating the characteristics of the input
    string.

    For conversion from RMS format to ACP-QIO format, only the
    CVTFNM$V_NO_DELIMITERS flag is valid.

    For conversion from ACP-QIO format to RMS format, legal flags are
    CVTFNM$V_WORD_CHARS and CVTFNM$V_NO_DELIMITERS (defined by the
    $CVTFNMDEF macro).

    Flag                 Description

    CVTFNM$V_WORD_       Input source string contains word-width
    CHARS                UCS-2 characters (ACPQIO_TO_RMS conversion
                         only).
    CVTFNM$V_NO_         Input source string should be treated as an
    DELIMITERS           arbitrary string (such as a subdirectory
                         name) rather than as a file name that
                         contains (or should contain) dots or
                         semicolons as type and version delimiters.
    CVTFNM$V_FORCE_      Causes this system service to convert each
    UPCASE               character to uppercase. (ACPQIO_TO_RMS
                         conversion only).

 outbuf

    OpenVMS usage:string of bytes or words
    type:         string of bytes or words
    access:       write only
    mechanism:    by 32-bit descriptor-fixed-length string descriptor
    The buffer into which the converted string is to be written.

    If the conversion is from RMS format to ACP-QIO format, the
    string may consist of byte-width ISO Latin-1 characters or
    word-width UCS-2 characters, depending on the characters in the
    source string. (If any character in the source string must be
    converted to UCS-2, then all characters in the output buffer will
    be converted to UCS-2.)

    If the conversion is from ACP-QIO format to RMS format, then the
    output string will consist of ISO Latin-1 and VTF-7 characters in
    RMS canonical form. (See the Guide to OpenVMS File Applications.)

    For ACPQIO_TO_RMS conversion, if the output string contains word-
    width characters, the CVTFNM$V_WORD_CHARS flag in the outflags
    flag mask will be set.

    The outbuf argument is the 32-bit address of a descriptor
    pointing to a buffer writable in the access mode of the caller.

 outlen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32-bit reference
    The outlen argument is the 32-bit address of a (16-bit) word
    writable in the access mode of the caller.

 outflags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32-bit reference
    Longword flag mask in which the service sets or clears flags to
    indicate characteristics of the output string.

    For an RMS_TO_ACPQIO conversion, SYS$CVT_FILENAME sets the bit
    corresponding to CVTFNM$V_WORD_CHARS (defined by the $CVTFNMDEF
    macro) if the characters of the converted string are one-
    word wide rather than one-byte wide. If the characters of the
    converted string are one-byte wide, the service clears the
    CVTFNM$V_WORD_CHARS bit. All other bits are cleared by an RMS_
    TO_ACPQIO conversion.

    The outflags argument is the 32-bit address of a 32-bit flag mask
    writable in the access mode of the caller.

76  –  $DACEFC

    Releases the calling process's association with a common event
    flag cluster.

    Format

      SYS$DACEFC  efn

    C Prototype

      int sys$dacefc  (unsigned int efn);

76.1  –  Argument

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of any event flag in the common cluster to be
    disassociated. The efn argument is a longword containing this
    number; however, $DACEFC uses only the low-order byte. The number
    must be in the range of 64 through 95 for cluster 2, and 96
    through 127 for cluster 3.

77  –  $DALLOC

    Deallocates a previously allocated device.

    Format

      SYS$DALLOC  [devnam] ,[acmode]

    C Prototype

      int sys$dalloc  (void *devnam, unsigned int acmode);

77.1  –  Arguments

 devnam

    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the device to be deallocated. The devnam argument is the
    address of a character string descriptor pointing to the device
    name string. The string might be either a physical device name or
    a logical name. If it is a logical name, it must translate to a
    physical device name.

    If you do not specify a device name, all devices allocated by the
    process from access modes equal to or less privileged than that
    specified are deallocated.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode from which the deallocation is to be performed. The
    acmode argument is a longword containing the access mode.

    The $PSLDEF macro defines the following symbols for the four
    access modes:

    Symbol         Access Mode

    PSL$C_KERNEL   Kernel
    PSL$C_EXEC     Executive
    PSL$C_SUPER    Supervisor
    PSL$C_USER     User

    The most privileged access mode used is the access mode of the
    caller.

78  –  $DASSGN

    Deassigns (releases) an I/O channel previously acquired using the
    Assign I/O Channel ($ASSIGN) service.

    Format

      SYS$DASSGN  chan

    C Prototype

      int sys$dassgn  (unsigned short int chan);

78.1  –  Argument

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Number of the I/O channel to be deassigned. The chan argument is
    a word containing this number.

79  –  $DCLAST

    Queues an asynchronous system trap (AST) for the calling access
    mode or for a less privileged access mode.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$DCLAST  astadr ,[astprm] ,[acmode]

    C Prototype

      int sys$dclast  (void (*astadr)(__unknown_params), unsigned

                      __int64 astprm, unsigned int acmode);

79.1  –  Arguments

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference
    AST service routine to be executed. On Alpha and Integrity server
    systems, the astadr argument is the 32- or 64-bit address of this
    routine.

 astprm

    OpenVMS usage:user_arg
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 64-bit value
    AST parameter to be passed to the AST routine specified by the
    astadr argument. On Alpha and Integrity server systems, the
    astprm argument is a quadword value containing this parameter.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode for which the AST is to be declared. The most
    privileged access mode used is the access mode of the caller. The
    resultant mode is the access mode for which the AST is declared.

80  –  $DCLCMH

    Specifies the address of a routine to receive control when a
    Change Mode to User or Change Mode to Supervisor instruction trap
    occurs.

    Format

      SYS$DCLCMH  addres ,[prvhnd] ,[type]

    C Prototype

      int sys$dclcmh  (int (*addres)(__unknown_params), void

                      *(*(prvhnd)), char type);

80.1  –  Arguments

 addres

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Routine to receive control when a change mode trap or a
    compatibility mode fault occurs. The addres argument is the
    exception handling code in the address space of the calling
    process.

    If you specify the addres argument as 0, $DCLCMH clears the
    previously declared handler.

 prvhnd

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of a previously declared handler. The prvhnd argument
    is the address of a longword containing the address of the
    previously declared handler.

 type

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Handler type indicator. The type argument is a longword value.
    The value 0 (the default) indicates that a change mode handler
    is to be declared for the access mode at which the request is
    issued; the value 1 specifies that a compatibility mode handler
    is to be declared.

81  –  $DCLEXH

    Declares an exit handling routine that receives control when an
    image exits.

    Format

      SYS$DCLEXH  desblk

    C Prototype

      int sys$dclexh  (void *desblk);

81.1  –  Argument

 desblk

    OpenVMS usage:exit_handler_block
    type:         longword (unsigned)
    access:       write
    mechanism:    by reference
    Exit handler control block. The desblk argument is the address of
    this control block.

    To view the control block diagram, see the VSI OpenVMS System
    Services Reference Manual.

82  –  $DECLARE RM

    Creates a new Resource Manager instance (RMI) in the calling
    process.

    Format

      SYS$DECLARE_RM  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id

                      ,event_handler ,[part_name] [,[rm_context]

                      ,[acmode] ,[tm_log_id] ,[event_mask]]

    C Prototype

      int sys$declare_rm  unsigned int efn, unsigned int

                          flags, struct _iosb *iosb, void

                          (*astadr)(__unknown_params), int

                          astprm, unsigned int *rm_id, void

                          (*event_handler)(__unknown_params),... ;

82.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for these option
    flags, described in $DECLARE_RM Option Flags. All undefined bits
    must be 0. If this argument is omitted, no flags are used.

    Table SYS-11 $DECLARE_RM Option Flags

    Flag Name      Description

    DDTM$M_SYNC    Specifies successful synchronous completion by
                   returning SS$_SYNCH. When SS$_SYNCH is returned,
                   the AST routine is not called, the event flag is
                   not set, and the I/O status block is not filled
                   in.
    DDTM$M_        Set this flag for the new RMI to be volatile.
    VOLATILE       With this flag set, the DECdtm transaction manager
                   will not log information about any RM participants
                   associated with the new RMI. Resource managers
                   that never perform recovery should set this flag.

                   If this flag is clear, the new RMI is not
                   volatile. The DECdtm transaction manager will
                   log the following information about each RM
                   participant associated with the new RMI:

                   o  The name of the RM participant.

                   o  The identifier (TID) of the transaction in
                      which it is participating.

                   If this flag is clear and a recoverable failure
                   occurs, such as a system crash, the resource
                   manager can use the $GETDTI system service to
                   query the transaction log to determine the outcome
                   of the transactions in which it was participating
                   before the failure occurred.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the completion status of the
    service is returned as a condition value.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the I/O status block diagram.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine that is executed when the service completes, if
    SS$_NORMAL is returned in R0. The astadr argument is the address
    of the entry mask of this routine. The routine is executed in
    the same access mode as that of the caller of the $DECLARE_RM
    service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter that is passed to the AST routine specified by
    the astadr argument.

 rm_id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Longword in which the identifier (RM_ID) of the new RMI is
    returned. This identifier is unique within the calling process
    at any time.

 event_handler

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The new RMI's event handler. This routine is called to report
    an event to the new RMI or one of its RM participants. The
    event_handler argument is the address of the entry mask of this
    routine. An event handler must be specified.

    This routine is called as an AST delivered by the DECdtm
    transaction manager.

    The AST is executed in the access mode specified by the acmode
    argument. The AST parameter is the address of a DECdtm event
    report block that contains an event report.

    The DECdtm transaction manager reports events to an RMI and the
    RM participants associated with it using ASTs executed in the
    access mode specified in the call to $DECLARE_RM that created
    that RMI.

    The DECdtm transaction manager creates an event report block,
    and passes its address to the AST routine in the parameter of the
    AST. Each event report block contains:

    o  The identifier of the event report.

    o  A code that describes the event.

    o  The identifier (TID) of the transaction.

    o  The name of the RM participant or RMI.

    o  The context of the RM participant or RMI.

    o  Other data that depend on the type of the event.

    Fields in an Event Report Block describes the fields in an event
    report block, in alphabetical order:

    Table SYS-12 Fields in an Event Report Block

    Symbol             Description

    DDTM$A_TID_PTR     Address of the identifier (TID) of the
                       transaction.
    DDTM$L_ABORT_      Abort reason code (longword).
    REASON
                       See the $ACK_EVENT service for a list of
                       possible values. Present only in abort event
                       reports.
    DDTM$L_EVENT_TYPE  A code that identifies the event (longword).
                       The following table lists the possible values:
                       Symbol             Event

                       DDTM$K_ABORT       Abort
                       DDTM$K_COMMIT      Commit
                       DDTM$K_PREPARE     Prepare
                       DDTM$K_ONE_PHASE_  One-phase commit
                       COMMIT
                       DDTM$K_STARTED_    Default transaction started
                       DEFAULT
                       DDTM$K_STARTED_    Nondefault transaction
                       NONDEFAULT         started

    DDTM$L_REPORT_ID   Event report identifier (unsigned longword).
    DDTM$L_RM_CONTEXT  The context of the RM participant or RMI to
                       which the event report is being delivered
                       (unsigned longword).
    DDTM$Q_PART_NAME   The name of the RM participant or RMI to
                       which the event report is being delivered
                       (descriptor).
    DDTM$Q_TX_CLASS    The transaction class of the transaction
                       (descriptor).

    Each event report must be acknowledged by calling $ACK_EVENT,
    specifying the identifier of the report. This acknowledgment need
    not come from AST context.

    The DECdtm transaction manager delivers only one event report
    at a time to each RM participant. For example, if a prepare
    event report has been delivered to an RM participant, and the
    transaction is aborted while the RM participant is doing its
    prepare processing, then the DECdtm transaction manager does not
    deliver an abort event report to that RM participant until it has
    acknowledged the prepare event report by a call to $ACK_EVENT.
    Note that the DECdtm transaction manager may deliver multiple
    reports to an RMI.

    After acknowledging the event report, the RMI or RM participant
    should no longer access the event report block.

 part_name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    The name of the new RMI. This is:

    o  The default name of its RM participants, used when a call to
       $JOIN_RM or $ACK_EVENT that adds one of these RM participants
       to a transaction does not specify the name of the new RM
       participant.

       When an RM participant associated with the new RMI is added to
       a transaction by a call to $JOIN_RM or $ACK_EVENT that has a
       zero part_name argument, then that RM participant inherits its
       name from the RMI. The name of that RM participant is the same
       as the name of the RMI.

    o  The string passed in the participant name field of Transaction
       Started event reports delivered to the new RMI.

    This string must be no longer than 32 characters.

    If this argument is omitted, the name of the new RMI is the null
    string.

    To ensure smooth operation in a mixed-network environment,
    refer to the chapter entitled Managing DECdtm Services in the
    VSI OpenVMS System Manager's Manual, for information on defining
    node names.

 rm_context

    OpenVMS usage:userarg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The context of the new RMI. This is:

    o  The default context of its RM participants, used when a
       call to $JOIN_RM or $ACK_EVENT that adds one of these RM
       participants to a transaction does not specify the context
       of the new RM participant.

       When an RM participant associated with the new RMI is added
       to a transaction by a call to $JOIN_RM or $ACK_EVENT that has
       a zero rm_context argument, then that RM participant inherits
       its context from the RMI. The context of that RM participant
       is the same as the context of the RMI.

    o  The string passed in the context field of Transaction Started
       event reports delivered to the new RMI.

    If this argument is omitted, the context of the new RMI is 0.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The access mode of the new RMI. This is:

    o  The access mode at which the ASTs delivered to its event
       handler are to be executed.

    o  The least privileged access mode that the caller must be in
       to call $ACK_EVENT to acknowledge an event report delivered to
       the new RMI or to its RM participants.

    o  The least privileged access mode that the caller must be in to
       delete the new RMI by calling $FORGET_RM.

    o  The least privileged access mode that the caller must be in to
       call $JOIN_RM to add a new RM participant associated with the
       new RMI.

    o  The most privileged access mode of new branches that this RMI
       is interested in, if the event_mask argument requests events
       of type Transaction Started.

       The call to $START_TRANS or $START_BRANCH that adds a new
       branch to a transaction specifies the access mode of that
       transaction within this process. The DECdtm transaction
       manager reports a Transaction Started event to the new RMI
       only if the access mode of the transaction is the same as or
       less privileged than the access mode of the new RMI.

       For example, if the access mode of the new RMI is supervisor,
       it will receive a Transaction Started event when a branch
       of the calling process is added to a transaction only if the
       access mode of that transaction is user or supervisor.

    The access mode of the new RMI is the least privileged of:

    o  The access mode of the caller.

    o  The access mode specified by the acmode argument.

    If this argument is omitted, the access mode of the new RMI is
    the same as the access mode of the caller.

 tm_log_id

    OpenVMS usage:DECnet_uid
    type:         octaword (unsigned)
    access:       write only
    mechanism:    by reference
    The globally unique identifier of the transaction log for the
    local node. This identifier is used during resource manager
    recovery to check that the correct DECdtm transaction manager
    log is used. See $GETDTI for more information.

    To ensure smooth operation in a mixed-network environment,
    refer to the chapter entitled Managing DECdtm Services in the
    VSI OpenVMS System Manager's Manual, for information on defining
    node names.

 event_mask

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Requests the types of event to be reported to the new RMI and to
    its RM participants. The only type of event that can be reported
    to the new RMI is a Transaction Started event (a default or non-
    default transaction started event). The following types of event
    can be reported to its RM participants:

    o  Abort events

    o  Commit events

    o  One-phase commit events

    o  Prepare events

    The event_mask argument is a longword bit mask that is the
    logical OR of each bit set, where each bit corresponds to an
    event. The $DDTMDEF module defines a symbolic name for each flag
    bit. $DECLARE_RM Event Selection Flags describes the flags. All
    undefined bits must be 0.

    If this argument is omitted, the following events are requested:

    o  Abort events

    o  Commit events

    o  One-phase commit events

    o  Prepare events

    Table SYS-13 $DECLARE_RM Event Selection Flags

    Flag Name      Description

    DDTM$M_EV_     Specifies that abort events are to be reported
    ABORT          to the RM participants associated with the new
                   RMI. If this flag is set, when an abort event
                   occurs for a transaction, the DECdtm transaction
                   manager delivers an abort event report to each RM
                   participant in the transaction that is associated
                   with the new RMI.
    DDTM$M_EV_     Specifies that commit events are to be reported to
    COMMIT         the RM participants associated with the new RMI.

                   If this flag is set, when the DECdtm transaction
                   manager decides that the outcome of a transaction
                   is commit, it delivers a commit event report to
                   each RM participant in the transaction that is
                   associated with the new RMI.
    DDTM$M_EV_     Specifies that prepare events are to be reported
    PREPARE        to the RM participants associated with the new
                   RMI.

                   If this flag is set, when the DECdtm transaction
                   manager initiates the commit protocol (in response
                   to a call to $END_TRANS) to determine the outcome
                   of a transaction, it reports a prepare event to
                   each RM participant in the transaction that is
                   associated with the new RMI.

                   The acknowledgment of a prepare event is a vote on
                   the outcome of the transaction. See $ACK_EVENT for
                   more information.
    DDTM$M_EV_     Specifies that events of type Transaction Started
    TRANS_START    are to be reported to the new RMI. Events of type
                   Transaction Started are:

                   o  Default transaction started events.

                   o  Non-default transaction-started events.

                   If this flag is set, the DECdtm transaction
                   manager will report one of these events to the
                   new RMI whenever a new branch in the calling
                   process is added to a transaction, provided that
                   the access mode of the new branch is not more
                   privileged than the access mode of the new RMI.
                   The acknowledgment of that event report may add
                   a new RM participant associated with the new RMI
                   to that transaction. See the description of the
                   acmode argument for a discussion of access modes.

83  –  $DECLARE RMW

    Creates a new Resource Manager instance (RMI) in the calling
    process. $DECLARE_RMW always waits for the request to complete
    before returning to the caller. Other than this, it is identical
    to $DECLARE_RM.

    Format

      SYS$DECLARE_RMW  [efn] ,[flags] ,iosb ,[astadr] ,[astprm]

                       ,rm_id ,event_handler ,[part_name]

                       [,[rm_context] ,[acmode] ,[tm_log_id]

                       ,[event_mask]]

    C Prototype

      int sys$declare_rmw  (unsigned int efn, unsigned int

                           flags, struct _iosb *iosb, void

                           (*astadr)(__unknown_params), int

                           astprm, unsigned int *rm_id, void

                           (*event_handler)(__unknown_params),...);

84  –  $DELETE

    The Delete service removes an existing record from a relative
    or indexed file. You cannot use this service when processing
    sequential files.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

85  –  $DELETE BUFOBJ (Alpha and Integrity servers)

    On Alpha and Integrity server systems, deletes a buffer object
    previously created by the $CREATE_BUFOBJ_64 system service.

    This service accepts 64-bit addresses.

    Format

      SYS$DELETE_BUFOBJ  buffer_handle_64

    C Prototype

      int sys$delete_bufobj  (struct _generic_64 *buffer_handle_64);

85.1  –  Arguments

 buffer_handle_64

    OpenVMS usage:handle
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The buffer object to be deleted. The buffer_handle_64 argument
    is the 32- or 64-bit address of a 2-longword array previously
    returned by a $CREATE_BUFOBJ_64 call.

86  –  $DELETE GALAXY LOCK (Alpha Only)

    Invalidates an OpenVMS Galaxy lock and deletes it.

    Note that this system service is supported only in an OpenVMS
    Alpha Galaxy environment.

    For more information about programming with OpenVMS Galaxy system
    services, see the VSI OpenVMS Alpha Partitioning and Galaxy Guide.

    Format

      SYS$DELETE_GALAXY_LOCK  handle

    C Prototype

      int sys$delete_galaxy_lock  (unsigned __int64 lock_handle);

86.1  –  Arguments

 handle

    OpenVMS usage:galaxy lock handle
    type:         quadword (unsigned)
    access:       read
    mechanism:    input by value
    The 64-bit lock handle that identifies the lock to be deleted.
    This value is returned by SYS$CREATE_GALAXY_LOCK.

87  –  $DELETE GALAXY LOCK TABLE (Alpha Only)

    Deletes an OpenVMS Galaxy locktable.

    Note that this system service is supported only in an OpenVMS
    Alpha Galaxy environment. For more information about programming
    with OpenVMS Galaxy system services, see the VSI OpenVMS Alpha
    Partitioning and Galaxy Guide.

    Format

      SYS$DELETE_GALAXY_LOCK_TABLE  handle

    C Prototype

      int sys$delete_galaxy_lock_table  (unsigned int

                                        *lcktbl_handle);

87.1  –  Arguments

 lcktbl_handle

    OpenVMS usage:lock table handle
    type:         longword (unsigned)
    access:       read
    mechanism:    input by value
    The 32-bit lock table handle that identifies the table to be
    deleted. This value is returned by SYS$CREATE_GALAXY_LOCK_TABLE.

88  –  $DELETE INTRUSION

    Searches for and deletes all records in the intrusion database
    matching the caller's specifications.

    Format

      SYS$DELETE_INTRUSION  user_criteria ,[flags]

    C Prototype

      int sys$delete_intrusion  (void *user_criteria, unsigned int

                                flags);

88.1  –  Arguments

 user_criteria

    OpenVMS usage:char_string or item_list_3
    type:         character-coded text string or longword (unsigned)
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor or by
                  reference
    If the CIA$M_ITEMLIST flag is FALSE:

    The user_criteria argument is the description of intruder or
    suspect. This argument is the address of a character-string
    descriptor pointing to a buffer containing the user criteria to
    match an intrusion record's user specification in the intrusion
    database.

    The user_criteria argument is a character string of 1 to 1058
    bytes containing characters to match the user specification on
    records in the intrusion database.

    A user specification is any combination of the suspect's or
    intruder's source node name, source user name, source DECnet-
    Plus address, local failed user name, or local terminal. The user
    specification for an intrusion record is based on the input to
    the $SCAN_INTRUSION service and the settings of the LGI system
    parameter. For more information, see the VSI OpenVMS Guide to
    System Security.

    Wildcards are allowed for the user_criteria argument. For
    example, if you specify an asterisk (*)  for the user_criteria
    argument, the service deletes all records in the intrusion
    database.

    If the CIA$M_ITEMLIST flag is TRUE:

    The user_criteria argument is now the address of a 32-bit item
    list. If the item list is used, one item, the CIA$_USER_CRITERIAL
    item, must be present in the item list. The ITM$L_BUFADR should
    point to a buffer containing the specified user criteria.

    The following table lists the valid item descriptions for the
    user_criteria argument:

    Item               Description

    CIA$_SCSNODE_LIST  Address of a list of 8-character null-padded
                       SCS nodenames for which intrusions are to be
                       deleted.
    CIA$_USER_         Address of a buffer, 1-1058 bytes long,
    CRITERIAL          containing the intruder or suspect.

    If the CIA$_SCSNODE_LIST item is present, it is the address
    of a list of 8-character null-padded SCS nodenames for which
    intrusions are to be deleted. If this item is absent, the service
    deletes the specified intrusion records for all nodes in the
    cluster. Multiple CIA$_SCSNODE_LIST items are permitted.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Functional specification for the service. The flags argument is a
    longword bit mask wherein each bit corresponds to an option.

    Each flag option has a symbolic name. The $CIADEF macro defines
    the following valid names for the $DELETE_INTRUSION service:

    Symbolic Name      Description

    CIA$M_IGNORE_      The service should not wait for the return
    RETURN             status from the security server. No return
                       status from the server's function will be
                       returned to the caller.
    CIA$M_ITEMLIST     If FALSE, the user_criteria argument is a
                       character string. If TRUE, this argument is a
                       32-bit item list.

89  –  $DELETE PROXY

    Deletes an existing proxy or removes the default user or a local
    user from an existing proxy in the proxy database.

    Format

      SYS$DELETE_PROXY  rem_node ,rem_user ,[local_user] ,[flags]

    D Prototype

      int sys$delete_proxy  (void *rem_node, void *rem_user, void

                            *local_user, unsigned int flags);

89.1  –  Arguments

 rem_node

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Remote node name of the proxy to be deleted from or modified
    in the proxy database. The rem_node argument is the address of
    a character-string descriptor pointing to the remote node name
    string.

    A remote node name consists of 1 to 1024 characters. No specific
    characters, format, or case are required for a remote node name
    string. All node names are converted to their DECnet for OpenVMS
    full name unless the PRX$M_BYPASS_EXPAND flag is set with the
    flags argument.

    Asterisk (*)  and percent sign (%) wildcards are allowed for the
    remote node specification. If you specify wildcards for the rem_
    node argument, the security server searches for an exact match
    to the specified remote node first. If it does not find an exact
    match, the server performs the requested operations on all of the
    matching proxies in the proxy database.

 rem_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Remote user name of the proxy to be deleted from or modified in
    the proxy database. The rem_user argument is the address of a
    character-string descriptor pointing to the user name string.

    A remote user name consists of 1 to 32 alphanumeric characters,
    including dollar signs ($),  underscores (_), and brackets
    ([ ]).  Any lowercase characters specified are automatically
    converted to uppercase.

    The rem_user argument can be specified in user identification
    code (UIC) format ([group, member]).  Brackets are allowed only
    if the remote user name string specifies a UIC. Group and member
    are character-string representations of octal numbers with no
    leading zeros.

    Asterisk (*)  and percent sign (%) wildcards are allowed for
    the remote user specification. If you specify wildcards for the
    rem_user argument, the server searches for an exact match to
    the specified remote user first. If it does not find an exact
    match, the server performs the requested operations on all of the
    matching proxies in the proxy database.

 local_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Local user name to delete from the proxy record specified by the
    rem_node and rem_user arguments in the proxy database. The local_
    user argument is the address of a character-string descriptor
    pointing to the local user name.

    A local user name consists of 0 to 32 alphanumeric characters,
    including dollar signs ($)  and underscores (_). If the local_
    user argument is not specified or has a length of 0, the server
    will delete the entire record or records specified by the rem_
    node and rem_user arguments from the proxy database.

    If the local_user argument is specified, the server will delete
    only the user name specified by the local_user argument from
    the record specified by the rem_node and rem_user arguments. The
    local_user argument can specify either the proxy's default user
    or a user name in the proxy's local users list.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Functional specification for the service and type of user the
    local_user argument represents. The flags argument is a longword
    bit mask wherein each bit corresponds to an option.

    Each flag option has a symbolic name. The $PRXDEF macro defines
    the following symbolic names:

    Symbolic Name      Description

    PRX$M_BYPASS_      The service should not convert the node name
    EXPAND             specified in the rem_node argument to its
                       corresponding DECnet full name. If this flag
                       is set, it is the caller's responsibility to
                       ensure that the fully expanded node name is
                       passed into the service.

    PRX$M_IGNORE_      The service should not wait for a return
    RETURN             status from the security server. No return
                       status from the server's function will be
                       returned to the caller.
    PRX$M_EXACT        The service should match exactly the remote
                       node and remote user and ignore wildcards.

90  –  $DELETE REGION 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, deletes a virtual region
    within the process's address space, including all created virtual
    addresses within the region.

    This service accepts 64-bit addresses.

    Format

      SYS$DELETE_REGION_64  region_id_64 ,acmode ,return_va_64

                            ,return_length_64

    C Prototype

      nt sys$delete_region_64  (struct _generic_64 *region_id_64,

                               unsigned int acmode, void

                               *(*(return_va_64)), unsigned __int64

                               *return_length_64);

90.1  –  Arguments

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region to be deleted. The
    region ID specified must be one returned by the $CREATE_REGION_64
    service. You cannot specify VA$C_P0, VA$C_P1, or VA$C_P2.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode associated with the call to $DELETE_REGION_64. The
    acmode argument is a longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. The caller can delete pages only if those pages are owned
    by an access mode equal to or less privileged than the access
    mode of the caller.

    Once all pages are deleted within the region, the region can be
    deleted only if the region is owned by an access mode equal to or
    less privileged than the access mode of the caller.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of the pages that
    $DELETE_REGION_64 has successfully deleted. The return_va_64
    argument is the 32- or 64-bit virtual address of a naturally
    aligned quadword into which the service returns the virtual
    address of the first page deleted. Virtual addresses are deleted
    from low address to high address, regardless of the direction in
    which virtual addresses expand for that region.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the virtual address range that $DELETE_REGION_64
    has successfully deleted. The return_length_64 argument is the
    32- or 64-bit virtual address of a naturally aligned quadword
    into which the service returns the length of the deleted virtual
    address range in bytes.

91  –  $DELLNM

    Deletes all logical names with the specified name at the
    specified access mode or outer access mode, or it deletes all
    the logical names with the specified access mode or outer access
    mode in a specified table.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$DELLNM  tabnam ,[lognam] ,[acmode]

    C Prototype

      int sys$dellnm  (void *tabnam, void *lognam, unsigned char

                      *acmode);

91.1  –  Arguments

 tabnam

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of a logical name table or a list of tables to be searched
    for the logical name to be deleted. The tabnam argument is the
    32- or 64-bit address of a descriptor that points to the table
    name. This argument is required.

    If tabnam is not the name of a logical name table, it is assumed
    to be a logical name and is translated iteratively until either
    the name of a logical name table is found or the number of
    translations allowed by the system has been performed.

    If tabnam translates to the name of a list of tables, $DELLNM
    does the following:

    o  If you specify the lognam argument, $DELLNM searches (in
       order) each table in the list until it finds the first table
       that contains the specified logical name. If the logical
       name is at the specified access mode, $DELLNM then deletes
       occurrences of the logical name at the specified access mode
       and at outer access modes within the table.

    o  If you do not specify the lognam argument, $DELLNM deletes all
       of the logical names at the specified access mode or at outer
       access modes from the first table in the list whose access
       mode is equal to or less privileged than the caller's access
       mode.

 lognam

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Logical name to be deleted. The lognam argument is the 32- or
    64-bit address of a descriptor that points to the logical name
    string.

 acmode

    OpenVMS usage:access_mode
    type:         byte (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Access mode to be used in the delete operation. The acmode
    argument is the 32- or 64-bit address of a byte containing this
    access mode. The $PSLDEF macro defines symbolic names for the
    four access modes.

    You determine the access mode actually used in the delete
    operation by maximizing the access mode of the caller with the
    access mode specified by the acmode argument; that is, the less
    privileged of the two is used.

    However, if you have SYSNAM privilege, the delete operation is
    executed at the specified access mode regardless of the caller's
    access mode.

    If you omit this argument or specify it as 0, the access mode
    of the caller is used in the delete operation. The access mode
    used in the delete operation determines which tables are used and
    which names are deleted.

92  –  $DELMBX

    Marks a permanent mailbox for deletion.

    Format

      SYS$DELMBX  chan

    C Prototype

      int sys$delmbx  (unsigned short int chan);

92.1  –  Argument

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Number of the channel assigned to the mailbox that is to be
    deleted. The chan argument is a word containing this number.

93  –  $DELPRC

    Allows a process to delete itself or another process.

    Format

      SYS$DELPRC  [pidadr] ,[prcnam] ,[flags]

    C Prototype

      int sys$delprc  (unsigned int *pidadr, void *prcnam);

93.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) of the process to be deleted. The
    pidadr argument is the address of a longword that contains the
    PID. The pidadr argument can refer to a process running on the
    local node or a process running on another node in the OpenVMS
    Cluster system.

    You must specify the pidadr argument to delete processes in other
    UIC groups.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Process name of the process to be deleted. The prcnam is the
    address of a character string descriptor pointing to the
    process name string. A process running on the local node can
    be identified with a 1- to 15-character string. To identify
    a process on a particular node on a cluster, specify the full
    process name, which includes the node name as well as the process
    name. The full process name can contain up to 23 characters.

    You use the prcnam argument to delete only processes in the
    same UIC group as the calling process, because process names
    are unique to UIC groups, and the operating system uses the UIC
    group number of the calling process to interpret the process name
    specified by the prcnam argument.

    You must use the pidadr argument to delete processes in other
    groups.

 flags

    OpenVMS usage:mask
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The flags argument can be used to control whether exit handlers
    are called by $DELPRC. If the flags argument is not specified
    or is specified with a zero, the system parameter DELPRC_EXIT
    controls what exit handlers, if any, are called by $DELPRC.

    The $DELPRCSYMDEF macro defines a symbolic name for EXIT and
    NOEXIT. The EXIT flag should be or'd with the access mode defined
    by the $PSLDEF macro for the initial exit handler.

    The following table describes each flag:

    Flag           Description

    DELPRC$M_      When set, exit handlers as specified by DELPRC$M_
    EXIT           MODE are called. This flag is ignored for a hard
                   suspended process.
    DELPRC$M_      2 bit field: values psl$c_kernel, psl$c_exec,
    MODE           psl$c_super, psl$c_user (from the $PSLDEF macro)
    DELPRC$M_      Set to disable any exit handler execution
    NOEXIT

                                   NOTE

       Deleting the current process:

       When $DELPRC is used to delete the current process,
       execution cannot continue in the mode from which $DELPRC
       was called. The first exit handlers that are called will be
       in the next more privileged mode relative to the mode from
       which $DELPRC was called (subject to options defined). For
       example:

       o  $DELPRC called from user mode can call supervisor mode
          exit handlers.

       o  $DELPRC called from exec mode can only execute kernel
          mode exit handlers.

       o  $DELPRC called from kernel mode cannot call exit
          handlers.

94  –  $DELTVA

    Deletes a range of addresses from a process's virtual address
    space. Upon successful completion of the service, the deleted
    pages are inaccessible, and references to them cause access
    violations.

    Format

      SYS$DELTVA  inadr ,[retadr] ,[acmode]

    C Prototype

      int sys$deltva  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode);

94.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Starting and ending virtual addresses of the pages to be
    deleted. The inadr argument is the address of a 2-longword array
    containing, in order, the starting and ending process virtual
    addresses. If the starting and ending virtual addresses are the
    same, a single page is deleted. The addresses are adjusted up or
    down to fall on CPU-specific page boundaries. Only the virtual
    page number portion of each virtual address is used; the low-
    order byte-within-page bits are ignored.

    The $DELTVA service deletes pages starting at the address
    contained in the second longword of the inadr argument and ending
    at the address in the first longword. Thus, if you use the same
    address array for both the Create Virtual Address Space ($CRETVA)
    and the $DELTVA services, the pages are deleted in the reverse
    order from which they were created.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Starting and ending process virtual addresses of the pages that
    $DELTVA has deleted. The retadr argument is the address of a
    2-longword array containing, in order, the starting and ending
    process virtual addresses.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode on behalf of which the service is to be performed.
    The acmode argument is a longword containing the access mode.

    The most privileged access mode used is the access mode of the
    caller. The calling process can delete pages only if those pages
    are owned by an access mode equal to or less privileged than the
    access mode of the calling process.

95  –  $DELTVA 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, deletes a range of virtual
    addresses from a process's virtual address space. Upon successful
    completion of the service, the deleted pages are inaccessible,
    and references to them cause access violations.

    This service accepts 64-bit addresses.

    Format

      SYS$DELTVA_64  region_id_64 ,start_va_64 ,length_64 ,acmode

                     ,return_va_64 ,return_length_64

    C Prototype

      int sys$deltva_64  (struct _generic_64 *region_id_64,

                         void *start_va_64, unsigned __int64

                         length_64, unsigned int acmode, void

                         *(*(return_va_64)), unsigned __int64

                         *return_length_64);

95.1  –  Arguments

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region from which to address
    the VA space.

    The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in
    STARLET.MLB define a symbolic name for each of the three default
    regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified. Also, the region ID that a virtual address
    is in can be obtained by calling the $GET_REGION_INFO service,
    specifying the VA$_REGSUM_BY_VA function.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address of the pages to be deleted. The
    specified address must be a CPU-specific page aligned address.
    If the region_id_64 argument specifies a shared page table region
    or if the start_va_64 argument lies within a shared page table
    region, the specified address must be a CPU-specific page table
    page aligned address.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space to be deleted. The length
    specified must be a multiple of CPU-specific pages. If the
    virtual address space is being deleted from a shared page table
    region, the specified length must be page table page aligned or
    include the last page in a memory-resident section.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode associated with the call to $DELTVA_64. The acmode
    argument is a longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. The calling process can delete pages only if those pages
    are owned by an access mode equal to or less privileged than the
    access mode of the calling process.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of the deleted virtual address
    range. The return_va_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword into which the $DELTVA_64
    service returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned quadword
    into which the $DELTVA_64 service returns the length in bytes of
    the virtual address range deleted.

96  –  $DEQ

    Dequeues (unlocks) granted locks; dequeues the sublocks of a
    lock; or cancels an ungranted lock request. The calling process
    must have previously acquired the lock or queued the lock request
    by calling the Enqueue Lock Request ($ENQ) service.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$DEQ  [lkid] ,[valblk] ,[acmode] ,[flags]

    C Prototype

      int sys$deq  (unsigned int lkid, void *valblk, unsigned int

                   acmode, unsigned int flags);

96.1  –  Arguments

 lkid

    OpenVMS usage:lock_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Lock identification of the lock to be dequeued. The lkid argument
    specifies this lock identification.

    Note that if you do not specify the lkid argument, you must
    specify the LCK$M_DEQALL flag in the flags argument.

    When you specify the LCK$M_DEQALL flag in the flags argument,
    different values (or no value) for the lkid argument produce
    varying behavior:

    o  When you do not specify the lkid argument (or specify it as
       0) and you do specify the LCK$M_DEQALL flag, $DEQ dequeues all
       locks held by the process, at access modes equal to or less
       privileged than the effective access mode, on all resources.
       The effective access mode is the least privileged of the
       caller's access mode and the access mode specified in the
       acmode argument.

    o  When you specify the lkid argument as a nonzero value together
       with the LCK$M_DEQALL flag, $DEQ dequeues all sublocks of
       the lock identified by lkid; it does not dequeue the lock
       identified by lkid. For this operation, $DEQ ignores the
       LCK$M_CANCEL flag if it is set. A sublock of a lock is a lock
       that was created when the parid argument in the call to $ENQ
       was specified, where parid is the lock ID of the parent lock.

    If you omit the lkid argument (or specify it as 0) and the LCK$M_
    DEQALL flag is not set, the $DEQ service returns the invalid lock
    ID condition value (SS$_IVLOCKID).

 valblk

    OpenVMS usage:lock_value_block
    type:         longword (unsigned)
    access:       modify
    mechanism:    by 32- or 64-bit reference
    Lock value block for the resource associated with the lock to
    be dequeued. The valblk argument is the 32- or 64-bit address of
    the 16-byte lock value block, or, if LCK$M_XVALBLK is specified
    (on Alpha or Integrity server systems), of the 64-byte lock value
    block. When you specify the LCK$M_DEQALL flag, you cannot use
    this argument.

    When a protected write (PW) or exclusive (EX) mode lock is
    being dequeued and you specify a lock value block in the valblk
    argument, the contents of that lock value block are written to
    the lock value block in the lock database. Further, if the lock
    value block in the lock database was marked as invalid, that
    condition is cleared; the block becomes valid.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode of the lock to be dequeued. The acmode argument is a
    longword containing the access mode.

    The acmode argument is valid only if the LCK$M_DEQALL flag of the
    flags argument is set. The $PSLDEF macro defines the following
    symbols for the four access modes:

    Symbol         Access Mode

    PSL$C_KERNEL   Kernel
    PSL$C_EXEC     Executive
    PSL$C_SUPER    Supervisor
    PSL$C_USER     User

    When dequeuing locks, $DEQ maximizes the access mode of the
    caller and the specified acmode argument. The maximized access
    mode is the less privileged of the caller's access mode and the
    acmode argument. If you do not specify the acmode argument, $DEQ
    uses the caller's access mode. Only those locks with an access
    mode that is equal to or less than the maximized access mode are
    dequeued.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the $DEQ operation. The flags
    argument is a longword bit mask that is the logical OR of each
    bit set, where each bit corresponds to an option.

    Note that if you do not specify the lkid argument, you must
    specify the LCK$M_DEQALL flag in the flags argument.

    A symbolic name for each flag bit is defined by the $LCKDEF
    macro. The following table describes each flag:

    Flag           Description

    LCK$M_DEQALL   When you specify this flag, $DEQ dequeues
                   multiple locks, depending on the value of the lkid
                   argument. For details, see the description of the
                   lkid argument. The acmode argument is ignored if
                   the LCK$M_DEQALL flag is not set. If you specify
                   LCK$M_DEQALL, the LCK$M_CANCEL flag, if set, is
                   ignored.

    LCK$M_CANCEL   When you specify this flag, $DEQ attempts to
                   cancel a lock request that was queued by $ENQ.
                   You can cancel only a waiting request. When the
                   request is canceled, $DEQ returns the condition
                   value SS$_NORMAL.

                   If you attempt to cancel a granted lock, the
                   request fails and $DEQ returns the condition value
                   SS$_CANCELGRANT. There are two types of waiting
                   requests that can be canceled:

                   o  A request for a new lock

                   o  A request to convert an existing lock

                   When canceling a new lock request, the following
                   action is taken:

                   o  If a completion asynchronous system trap (AST)
                      was requested, the AST is queued for delivery
                      and SS$_ABORT is stored in the lock status
                      block.

                   When canceling a request to convert an existing
                   lock, the conversion request is canceled. The
                   existing granted lock remains unchanged. The
                   following specific actions are taken:

                   o  The blocking AST address specified for the
                      existing granted lock is queued for delivery
                      if the granted mode of the existing lock is
                      blocking other waiting requests.

                   o  If a completion AST was specified by the
                      conversion request, the completion AST is
                      queued for delivery with SS$_CANCEL status
                      stored in the lock status block that was
                      specified by the conversion request.

                   If you specify the LCK$M_DEQALL flag, the LCK$M_
                   CANCEL flag is ignored.

    LCK$M_         When you specify this flag, $DEQ marks the lock
    INVVALBLK      value block, which is maintained for the resource
                   in the lock database, as invalid. The lock value
                   block remains marked as invalid until it is again
                   written to. The Description section of the $ENQ
                   service provides additional information about lock
                   value block invalidation.

                   This flag is ignored if (1)  the lock mode of the
                   lock being dequeued is not protected write or
                   exclusive, or (2)  you specify the LCK$M_CANCEL
                   flag.
    LCK$M_         When you specify this flag, you must provide a
    XVALBLK        64-byte lock value block as the valblk argument.
                   If you do not specify this flag, only the first
                   16 bytes of the buffer specified in the valblk
                   argument will be written.

                   If the value block is written without this flag,
                   the value block will be flagged so that a future
                   reader who specifies the LCK$M_XVALBLK flag in the
                   $ENQ system service call will receive the warning
                   status SS$_XVALNOTVALID until a future writer
                   writes to the value block specifying this flag.

                   This flag is valid only on Alpha and Integrity
                   server systems.

97  –  $DEVICE PATH SCAN (Alpha and Integrity servers)

    On Alpha and Integrity server systems, returns the displayable
    pathname for a given I/O channel or device name. Can be used to
    return all displayable paths to an I/O device.

    Format

      SYS$DEVICE_PATH_SCAN  [chan] [,devnam] ,itmlst [,contxt]

                            [,nullarg]

    C Prototype

      int sys$device_path_scan  (unsigned short int chan, void

                                *devnam, void *itmlst, unsigned int

                                *contxt, struct_generic_64 *nullarg);

97.1  –  Arguments

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Number of the I/O channel assigned to the device about which
    information is desired. The chan argument is a word containing
    this number.

    To identify a device to $DEVICE_PATH_SCAN, you can specify either
    the chan or devnam parameters, but you should not specify both.
    If you specify both arguments, the chan argument is used.

    If you specify neither chan nor devnam, $DEVICE_PATH_SCAN uses a
    default value of 0 for chan.

 devnam

    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    The name of the device about which $DEVICE_PATH_SCAN is to
    return path information. The devnam argument is the address of
    a character string descriptor pointing to this name string.

    The device name string can be either a physical device name
    or a logical name. If the first character in the string is an
    underscore (_),  the string is considered a physical device name;
    otherwise, the string is considered a logical name and logical
    name translation is performed until either a physical device name
    is found or the system default number of translations has been
    performed.

    If the device name string contains a colon (:),  the colon and
    the characters that follow it are ignored.

    To identify a device to $DEVICE_PATH_SCAN, you can specify either
    the chan or devnam argument, but you should not specify both. If
    both arguments are specified, the chan argument is used.

    If you specify neither chan nor devnam, $DEVICE_PATH_SCAN uses a
    default value of 0 for chan.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying which information about the device is to be
    returned. The itmlst argument is the address of a list of item
    descriptors, each of which describes an item of information. The
    list of item descriptors is terminated by a longword of 0.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

 contxt

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value used to indicate the current position of a $DEVICE_PATH_
    SCAN search. The contxt argument is the address of the longword
    that receives this information. On the initial call, the longword
    should contain 0.

 nullarg

    OpenVMS usage:null_arg
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Placeholding argument Reserved to VSI.

98  –  $DEVICE SCAN

    Returns the names of all devices that match a specified set of
    search criteria.

    Format

      SYS$DEVICE_SCAN  return_devnam ,retlen ,[search_devnam]

                       ,[itmlst] ,[contxt]

    C Prototype

      int sys$device_scan  (void *return_devnam, unsigned short

                           int *retlen, void *search_devnam, void

                           *itmlst, struct _generic_64 *contxt);

98.1  –  Arguments

 return_devnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Buffer to receive the device name. The return_devnam argument is
    the address of a character string descriptor pointing to a buffer
    into which $DEVICE_SCAN writes the name of the first or next
    device that matches the specified search criteria. The maximum
    size of any device name is 64 bytes.

 retlen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Length of the device name string returned by $DEVICE_SCAN. The
    retlen argument is the address of a word into which $DEVICE_SCAN
    writes the length of the device name string.

 search_devnam

    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the device for which $DEVICE_SCAN is to search. The
    search_devnam argument accepts the standard wildcard characters,
    the asterisk (*), which matches any sequence of characters, and
    the percent sign (%), which matches any one character. If the
    search_devnam argument does not include a wildcard character,
    an exact match is used for comparison. For example, to match all
    unit 0 DU devices on any controller, specify *DU%0. This string
    is compared to the most complete device name (DVI$_ALLDEVNAM).
    Only uppercase characters are accepted.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword_unsigned
    access:       read only
    mechanism:    by reference
    Item list specifying search criteria used to identify the device
    names for return by $DEVICE_SCAN. The itmlst argument is the
    address of a list of item descriptors, each of which describes
    one search criterion. The list of item descriptors is terminated
    by a longword of 0.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

 contxt

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference
    Value used to indicate the current position of a $DEVICE_SCAN
    search. The contxt argument is the address of the quadword that
    receives this information. On the initial call, the quadword
    should contain 0.

99  –  $DGBLSC

    Marks an existing permanent global section for deletion. The
    actual deletion of the global section takes place when all
    processes that have mapped the global section have deleted the
    mapped pages.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$DGBLSC  [flags] ,gsdnam ,[ident]

    C Prototype

      int sys$dgblsc  (unsigned int flags, void *gsdnam, struct

                      _secid *ident);

99.1  –  Arguments

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Mask indicating global section characteristics. The flags
    argument is a longword value. A value of 0 (the default)
    specifies a group global section; a value of SEC$M_SYSGBL
    specifies a system global section; a value of SEC$M_SHMGS on
    an OpenVMS Galaxy system creates a shared-memory global section.

 gsdnam

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section to be deleted. The gsdnam argument
    is the address of a character string descriptor pointing to this
    name string.

    For group global sections, the operating system interprets the
    group UIC as part of the global section name; thus, the names of
    global sections are unique to UIC groups.

    You can specify any name from 1 to 43 characters. All processes
    mapping to the same global section must specify the same name.
    Note that the name is case sensitive.

    Use of characters valid in logical names is strongly encouraged.
    Valid values include alphanumeric characters, the dollar sign
    ($), and the underscore (_). If the name string begins with an
    underscore (_), the underscore is stripped and the resultant
    string is considered to be the actual name. Use of the colon (:)
    is not permitted.

    Names are first subject to a logical name translation, after
    the application of the prefix GBL$ to the name. If the result
    translates, it is used as the name of the section. If the
    resulting name does not translate, the name specified by the
    caller is used as the name of the section.

    Additional information on logical name translations and
    on section name processing is available in the VSI OpenVMS
    Programming Concepts Manual.

 ident

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of the global
    section to be deleted and the matching criteria to be applied.
    The ident argument is the 32- or 64-bit address of a quadword
    structure containing three fields.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. Values
    for these fields can be assigned by installation convention to
    differentiate versions of global sections. If you specify no
    version number when creating a section, processes that specify a
    version number when mapping cannot access the global section.

    The first longword specifies, in its low-order 3 bits, the
    matching criteria. The valid values, the symbolic names by
    which they can be specified, and their meanings are listed in
    the following table:

    Value Name          Match Criteria

    0     SEC$K_MATALL  Match all versions of the section.
    1     SEC$K_MATEQU  Match only if major and minor identifications
                        match.
    2     SEC$K_MATLEQ  Match if the major identifications are
                        equal and the minor identification of the
                        mapper is less than or equal to the minor
                        identification of the global section.

    If you specify no address or specify it as 0 (the default), the
    version number and match control fields default to 0.

100  –  $DISCONNECT

    The Disconnect service breaks the connection between a RAB and a
    FAB, thereby terminating a record stream. All system resources,
    such as I/O buffers and data structure space, are deallocated.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

101  –  $DISMOU

    Dismounts a mounted volume or volume sets.

    Format

      SYS$DISMOU  devnam ,[flags]

    C Prototype

      int sys$dismou  (void *devnam, unsigned int flags);

101.1  –  Arguments

 devnam

    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Device name of the device to be dismounted. The devnam argument
    is the address of a character string descriptor pointing to
    the device name string. The string can be either a physical
    device name or a logical name. If it is a logical name, it must
    translate to a physical device name.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    A longword bit vector specifying options for the dismount
    operation. The flags argument is a longword bit vector wherein
    a bit, when set, selects the corresponding option. Each bit has a
    symbolic name; these names are defined by the $DMTDEF macro.

    The flags and their meanings are listed in the following table:

    Flag                Meaning

    DMT$M_ABORT         The volume is to be dismounted even if
                        the caller did not mount the volume. If
                        the volume was mounted with MNT$M_SHARE
                        specified, $DISMOU dismounts the volume for
                        all of the users who mounted it.

                        To specify DMT$M_ABORT, the caller must: (1)
                        have GRPNAM privilege for a group volume,
                        (2)  have SYSNAM privilege for a system
                        volume, or (3)  either own the volume or have
                        VOLPRO privilege.

    DMT$M_CLUSTER       The volume is to be dismounted clusterwide,
                        that is, from all nodes in the OpenVMS
                        Cluster system. $DISMOU dismounts the volume
                        from the caller's node first and then from
                        every other node in the existing cluster.

                        DMT$M_CLUSTER dismounts only system or
                        group volumes. To dismount a group volume
                        clusterwide, the caller must have GRPNAM
                        privilege. To dismount a system volume
                        clusterwide, the caller must have SYSNAM
                        privilege.

                        DMT$M_CLUSTER has no effect if the system
                        is not a member of a cluster. DMT$M_CLUSTER
                        applies only to disks.

    DMT$M_FORCE         If connectivity to a device has been lost and
                        the shadow set is in mount verification, this
                        flag causes a named shadow set member to be
                        immediately expelled from the shadow set.

    DMT$M_MINICOPY_     $DISMOU takes place, regardless of whether
    OPTIONAL            minicopy is enabled on the disk.

    DMT$M_MINICOPY_     $DISMOU fails if minicopy has not been
    REQUIRED            enabled on the disk.

    DMT$M_NOUNLOAD      Specifies that the volume is not to be
                        physically unloaded after the dismount. If
                        both the DMT$M_UNLOAD and DMT$M_NOUNLOAD
                        flags are specified, the DMT$M_NOUNLOAD flag
                        is ignored. If neither flag is specified,
                        the volume is physically unloaded, unless
                        the DMT$M_NOUNLOAD flag was specified on
                        the $MOUNT system service or the /NOUNLOAD
                        qualifier was specified on the MOUNT command
                        when the volume was mounted.

    DMT$M_OVR_CHECKS    Specifies that the volume should be
                        dismounted without checking for open files,
                        spooled devices, installed images, or
                        installed swap and page files.

    DMT$M_UNIT          The specified device, rather than the entire
                        volume set, is dismounted.

    DMT$M_UNLOAD        Specifies that the volume is to be physically
                        unloaded after the dismount. If both the
                        DMT$M_UNLOAD and DMT$M_NOUNLOAD flags
                        are specified, the DMT$M_NOUNLOAD flag
                        is ignored. If neither flag is specified,
                        the volume is physically unloaded, unless
                        the DMT$M_NOUNLOAD flag was specified on
                        the $MOUNT system service or the /NOUNLOAD
                        qualifier was specified on the MOUNT command
                        when the volume was mounted.

102  –  $DISPLAY

    The Display service retrieves file attribute information about
    a file and places this information in fields in the FAB, in XABs
    chained to the FAB, and in a NAM block (if one is requested).

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

103  –  $DISPLAY PROXY

    Returns information about one or more existing proxies.

    Format

      SYS$DISPLAY_PROXY  rem_node ,rem_user ,buffer_sizes ,proxy_node

                         ,proxy_user ,default_user ,local_users

                         ,flags ,[context]

    C Prototype

      int sys$display_proxy  (void *rem_node, void *rem_user,

                             unsigned short int buffer_sizes [4],

                             void *proxy_node, void *proxy_user,

                             void *default_user, unsigned int

                             *local_users, unsigned int flags,

                             unsigned int *context);

103.1  –  Arguments

 rem_node

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Remote node name of the proxy about which information is being
    requested. The rem_node argument is the address of a character-
    string descriptor pointing to the remote node name string.

    A remote node name consists of 1 to 1024 characters. No specific
    characters, format, or case are required for a remote node
    name string. All node names are converted to their DECnet full
    name unless the PRX$M_BYPASS_EXPAND flag is set with the flags
    argument.

    Asterisk (*)  and percent sign (%) wildcards are allowed for the
    remote node specification. If you specify wildcards for the rem_
    node argument, the server searches the entire proxy database for
    matches to the remote node and remote user you specified. If a
    match is found, information about the matched proxy is returned.

    For additional details on retrieving information about multiple
    proxies, see the VSI OpenVMS System Services Reference Manual.

 rem_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Remote user name of the proxy about which information is being
    requested. The rem_user argument is the address of a character-
    string descriptor pointing to the user name string.

    A remote user name consists of 1 to 32 alphanumeric characters,
    including dollar signs ($),  underscores (_), and brackets
    ([ ]).  Any lowercase characters specified are automatically
    converted to uppercase.

    The rem_user argument can be specified in user identification
    code (UIC) format ([group, member]).  Brackets are allowed only
    if the remote user name string specifies a UIC. Group and member
    are character-string representations of octal numbers with no
    leading zeros.

    Asterisk (*)  and percent sign (%) wildcards are allowed for the
    remote user specification. If you specify wildcards for the rem_
    user argument, the server searches the entire proxy database for
    matches to the remote node and remote user you specified. If a
    match is found, information about the matched proxy is returned.
    See the Description section for information about retrieving
    information about multiple proxies.

 buffer_sizes

    OpenVMS usage:return length block
    type:         array of 4 words (unsigned)
    access:       write only
    mechanism:    by reference
    Array of return lengths for various input buffers.

    To view the array diagram and buffer_sizes fields table, see the
    VSI OpenVMS System Services Reference Manual.

 proxy_node

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Node name of a proxy matching the remote node name specified by
    the rem_node argument and the remote user name specified by the
    rem_user argument. The proxy_node argument is the address of a
    character-string descriptor pointing to a buffer to receive the
    proxy node name.

    The descriptor's buffer must be 1024 bytes long to receive a node
    name. The length of the returned node name is specified by the
    proxy node length field returned in the buffer specified by the
    buffer_sizes argument.

 proxy_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    User name of a proxy matching the remote node name specified by
    the rem_node argument and the remote user name specified by the
    rem_user argument. The proxy_user argument is a character-string
    descriptor pointing to a buffer to receive the remote user name
    of a proxy.

    The descriptor's buffer must be 32 bytes long to receive a user
    name. The length of the returned user name is specified by the
    proxy user length field returned in the buffer specified by the
    buffer_sizes argument.

 default_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Default user of a proxy matching the node name specified by the
    rem_node argument and the remote user name specified by the rem_
    user argument. The default_user argument is the address of a
    character-string descriptor pointing to a buffer to receive the
    default user name.

    The descriptor's buffer must be 32 bytes long to receive a user
    name. The length of the returned user name is specified in the
    default user length field in the buffer specified by the buffer_
    sizes argument.

 local_users

    OpenVMS usage:buffer
    type:         array of 0 to 16 user name buffers
    access:       write only
    mechanism:    by reference
    Array of local user names associated with a proxy matching the
    remote node name specified by the rem_node argument and the
    remote user name specified by the rem_user argument. The local_
    users argument is the address of a buffer to receive an array of
    local user names.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the array diagram and local_users fields table.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Functional specification for the service and type of user the
    local_user argument represents. The flags argument is a longword
    bit mask wherein each bit corresponds to an option.

    Each flag option has a symbolic name. The $PRXDEF macro defines
    the following symbolic names:

    Symbolic Name      Description

    PRX$M_BYPASS_      The service should not convert the node name
    EXPAND             specified in the rem_node argument to its
                       corresponding DECnet full name. If this flag
                       is set, it is the caller's responsibility to
                       ensure that the fully expanded node name is
                       passed into the service.

    PRX$M_EXACT        The service should match exactly the remote
                       node and remote user and ignore wildcards.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Context information to keep between related calls to the
    $DISPLAY_PROXY service. The context argument is the address of
    a longword to receive a context from the $DISPLAY_PROXY service.

    The initial value contained in the longword pointed to by the
    context argument must be 0. The contents of the unsigned longword
    must not be changed after the service has set its value. If the
    contents of the buffer pointed to by the context argument are
    changed between calls to the $DISPLAY_PROXY service, the service
    will return SS$_BADCONTEXT. If the contents of the context
    argument are changed between calls to the $DISPLAY_PROXY service,
    you can change the value of the context argument back to 0 to
    start the search over again.

    Contexts become invalid after one-half hour of non-use. This
    means that if you call the $DISPLAY_PROXY service with a wildcard
    rem_node or rem_user, and do not call the service to get the
    next matching record within one-half hour, the context becomes
    invalid. If the context has become invalid, you must start your
    search of the proxy database over from its beginning by resetting
    the context to 0.

104  –  $DLCEFC

    Marks a permanent common event flag cluster for deletion.

    Format

      SYS$DLCEFC  name

    C Prototype

      int sys$dlcefc  (void *name);

104.1  –  Argument

 name

    OpenVMS usage:ef_cluster_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the common event flag cluster to be deleted. The name
    argument is the address of a character string descriptor pointing
    to the name of the cluster.

    The names of event flag clusters are unique to UIC groups, and
    the UIC group number of the calling process is part of the name.

105  –  $END BRANCH

    Removes a branch from a transaction and returns the outcome of
    the transaction.

    Format

      SYS$END_BRANCH  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid

                      ,bid

    C Prototype

      int sys$end_branch  (unsigned int efn, unsigned int

                          flags, struct _iosb *iosb, void

                          (*astadr)(__unknown_params), int astprm,

                          unsigned int tid [4], unsigned int bid

                          [4]);

105.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag set when the service completes. If this
    argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for these option
    flags, described in $END_BRANCH Option Flags. All undefined bits
    must be 0. If this argument is omitted, no flags are used.

    Table SYS-14 $END_BRANCH Option Flags

    Flag Name      Description

    DDTM$M_SYNC    Specifies successful synchronous completion by
                   returning SS$_SYNCH. When SS$_SYNCH is returned,
                   the AST routine is not called, the event flag is
                   not set, and the I/O status block is not filled
                   in.
    DDTM$M_        Indicates that the service should return to the
    NOWAIT         caller without waiting for final cleanup. Note
                   that $END_BRANCHW with the DDTM$M_NOWAIT flag
                   set is not equivalent to $END_BRANCH. The latter
                   returns when the operation has been queued. The
                   former does not return until the operation has
                   been initiated. The full range of status values
                   may be returned from a nowait call.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the following information is
    returned:

    o  The completion status of the service. This is returned as a
       condition value. See the Condition Values Returned section for
       more information.

    o  The outcome of the transaction. If the service completes
       successfully, the outcome of the transaction is commit. If
       it returns SS$_ABORT, the outcome of the transaction is abort.

    o  An abort reason code that gives one reason why the transaction
       aborted, if the completion status of the service is SS$_ABORT.
       The $DDTMMSGDEF macro defines symbolic names for these abort
       reason codes. See $ACK_EVENT for a list of the codes that are
       currently defined.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the I/O status block diagram.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine executed when the service completes, if SS$_
    NORMAL is returned in R0. The astadr argument is the address
    of the entry mask of this routine. The routine is executed in
    the same access mode as that of the caller of the $END_BRANCH
    service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter passed to the AST routine specified by the
    astadr argument.

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (TID) of the transaction from which the branch is
    to be removed.

 bid

    OpenVMS usage:branch_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (BID) of the branch to be removed from the
    transaction.

106  –  $END BRANCHW

    Removes a branch from a transaction and returns the outcome of
    the transaction. $END_BRANCHW always waits for the request to
    complete before returning to the caller. Other than this, it is
    identical to $END_BRANCH.

    Format

      SYS$END_BRANCHW  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid

                       ,bid

    C Prototype

      int sys$end_branchw  (unsigned int efn, unsigned int

                           flags, struct _iosb *iosb, void

                           (*astadr)(__unknown_params), int astprm,

                           unsigned int tid [4], unsigned int bid

                           [4]);

107  –  $END TRANS

    Ends a transaction by attempting to commit it, and returns the
    outcome of the transaction.

    Format

      SYS$END_TRANS  [efn] ,[flags] ,iosb [,[astadr] ,[astprm]

                     ,[tid]]

    C Prototype

      int sys$end_trans  (unsigned int efn, unsigned int flags,

                         struct _iosb *iosb,...);

107.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for these option
    flags, which are defined in $END_TRANS Option Flags.

    All undefined bits must be 0. If this argument is omitted, no
    flag is set.

    Table SYS-15 $END_TRANS Option Flags

    Flag           Description

    DDTM$M_SYNC    Set this flag to specify that successful
                   synchronous completion is to be indicated by
                   returning SS$_SYNCH. When SS$_SYNCH is returned,
                   the asynchronous system trap (AST) routine is not
                   called, the event flag is not set, and the I/O
                   status block is not filled in.
    DDTM$M_        Indicates that the service should return to the
    NOWAIT         caller without waiting for final cleanup. Note
                   that $END_TRANSW with the DDTM$M_NOWAIT flag set
                   is not equivalent to $END_TRANS. The former does
                   not return until the operation has been initiated,
                   while $END_TRANS returns when the operation has
                   been queued.

                   The full range of status values may be returned
                   from a nowait call.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block in which the following information is returned
    contains:

    o  The completion status of the service. This is returned as a
       condition value.

    o  The outcome of the transaction. If the service returns SS$_
       NORMAL, the outcome of the transaction is commit. If the
       service returns SS$_ABORT, the outcome of the transaction
       is abort.

    o  An abort reason code that gives one reason why the transaction
       aborted, if the completion status of the service is SS$_ABORT.

    The $DDTMMSGDEF macro defines symbolic names for these abort
    reason codes, which are described in Abort Reason Codes:

    Table SYS-16 Abort Reason Codes

    Symbolic Name        Description

    DDTM$_ABORTED        The application aborted the transaction.
    DDTM$_COMM_FAIL      A communications link failed.
    DDTM$_INTEGRITY      A resource manager integrity constraint
                         check failed.
    DDTM$_LOG_FAIL       A write operation to the transaction log
                         failed.
    DDTM$_ORPHAN_        Unauthorized branch caused failure.
    BRANCH
    DDTM$_PART_SERIAL    A resource manager serialization check
                         failed.
    DDTM$_PART_TIMEOUT   The timeout specified by a resource manager
                         expired.
    DDTM$_SEG_FAIL       A process or image terminated.
    DDTM$_               A DECdtm transaction manager serialization
    SERIALIZATION        check failed.
    DDTM$_SYNC_FAIL      The transaction was not globally
                         synchronized (an authorized branch had not
                         been added).
    DDTM$_TIMEOUT        The timeout specified on $START_TRANS
                         expired.
    DDTM$_UNKNOWN        The reason is unknown.
    DDTM$_VETOED         A resource manager was unable to commit the
                         transaction.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the structure of the I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    AST routine that is executed when the service completes if SS$_
    NORMAL is returned in R0. The astadr argument is the address of
    this routine. The routine is executed in the access mode of the
    caller.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    AST parameter that is passed to the AST routine specified by the
    astadr argument.

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    Identifier (TID) of the transaction to be ended.

    If this argument is omitted, $END_TRANS ends the default
    transaction of the calling process.

108  –  $END TRANSW

    Ends a transaction by attempting to commit it, and returns the
    outcome of the transaction.

    $END_TRANSW always waits for the request to complete before
    returning to the caller. Other than this, it is identical to
    $END_TRANS.

    Format

      SYS$END_TRANSW  [efn] ,[flags] ,iosb [,[astadr] ,[astprm]

                      ,[tid]]

    C Prototype

      int sys$end_transw  (unsigned int efn, unsigned int flags,

                          struct _iosb *iosb,...);

109  –  $ENQ

    Queues a new lock or lock conversion on a resource.

    The $ENQ, $ENQW, $DEQ (Dequeue Lock Request), and $GETLKI (Get
    Lock Information) services together provide the user interface to
    the Lock Management facility.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    For additional information about system service completion, see
    the Synchronize ($SYNCH) service.

    Format

      SYS$ENQ  [efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid]

               ,[astadr] ,[astprm] ,[blkast] ,[acmode] ,[rsdm_id]

               ,[nullarg]

    C Prototype

      int sys$enq  (unsigned int efn, unsigned int lkmode,

                   struct _lksb *lksb, unsigned int flags,

                   void *resnam, unsigned int parid, void

                   (*astadr)(__unknown_params), unsigned int acmode,

                   unsigned int rsdm_id,...);

109.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when the request has been
    granted or canceled. Cancellation occurs if you use $DEQ with the
    cancel modifier or if the waiting request is chosen to break a
    deadlock. The efn argument is a longword containing this number;
    however, $ENQ uses only the low-order byte.

    Upon request initiation, $ENQ clears the specified event flag
    (or event flag 0 if efn was not specified). Then, when the lock
    request is granted, the specified event flag (or event flag 0)
    is set unless you specified the LCK$M_SYNCSTS flag in the flags
    argument.

 lkmode

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Lock mode requested. The lkmode argument is a longword specifying
    this lock mode.

    Each lock mode has a symbolic name. The $LCKDEF macro defines
    these symbolic names. The following table gives the symbolic name
    and description for each lock mode:

    Lock Mode     Description

    LCK$K_NLMODE  Null mode. This mode grants no access to the
                  resource but serves as a placeholder and indicator
                  of future interest in the resource. The null mode
                  does not inhibit locking at other lock modes;
                  further, it prevents the deletion of the resource
                  and lock value block, which would otherwise occur
                  if the locks held at the other lock modes were
                  dequeued.

    LCK$K_CRMODE  Concurrent read. This mode grants the caller read
                  access to the resource while permitting write
                  access to the resource by other users. This mode is
                  used to read data from a resource in an unprotected
                  manner, because other users can modify that data as
                  it is being read. This mode is typically used when
                  additional locking is being performed at a finer
                  granularity with sublocks.

    LCK$K_CWMODE  Concurrent write. This mode grants the caller
                  write access to the resource while permitting write
                  access to the resource by other users. This mode is
                  used to write data to a resource in an unprotected
                  fashion, because other users can simultaneously
                  write data to the resource. This mode is typically
                  used when additional locking is being performed at
                  a finer granularity with sublocks.

    LCK$K_PRMODE  Protected read. This mode grants the caller read
                  access to the resource while permitting only read
                  access to the resource by other users. Write access
                  is not allowed. This is the traditional share lock.

    LCK$K_PWMODE  Protected write. This mode grants the caller write
                  access to the resource while permitting only read
                  access to the resource by other users; the other
                  users must have specified concurrent read mode
                  access. No other writers are allowed access to the
                  resource. This is the traditional update lock.

    LCK$K_EXMODE  Exclusive. The exclusive mode grants the caller
                  write access to the resource and allows no access
                  to the resource by other users. This is the
                  traditional exclusive lock.

    The following table shows the compatibility of lock modes:

    Table SYS-17 Compatibility of Lock Modes

    Mode of                Mode of Currently Granted Locks

    Requested

    Lock       NL    CR    CW    PR     PW    EX

    NL         Yes   Yes   Yes   Yes    Yes   Yes
    CR         Yes   Yes   Yes   Yes    Yes   No
    CW         Yes   Yes   Yes   No     No    No
    PR         Yes   Yes   No    Yes    No    No
    PW         Yes   Yes   No    No     No    No
    EX         Yes   No    No    No     No    No
    __________________________________________________________________
    Key to Lock Modes:

     NL-Null
     CR-Concurrent read
     CW-Concurrent write
     PR-Protected read
     PW-Protected write
     EX-Exclusive

 lksb

    OpenVMS usage:lock_status_block
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Lock status block in which $ENQ writes the final completion
    status of the operation. The lksb argument is the 32- or 64-bit
    address of the 8-byte lock status block.

    The lock status block can optionally contain a 16-byte or a 64-
    byte lock value block. The initial value of the lock value block
    is zero (0).

    o  When you specify the LCK$M_VALBLK flag in the flags argument,
       the lock status block contains a lock value block. In this
       case, the 16-byte lock value block appears at the beginning
       of the first byte following the eighth byte of the lock status
       block, bringing the total length of the lock status block to
       24 bytes.

    o  When you specify the LCK$M_XVALBLK flag together with the
       LCK$M_VALBLK flag in the flags argument, the lock status
       block contains an extended lock value block. In this case,
       the 64-byte lock value block appears at the beginning of
       the first byte following the eighth byte of the lock status
       block, bringing the total length of the lock status block to
       72 bytes.

       The LCK$M_XVALBLK flag is valid only on Alpha and Integrity
       server systems.

    To view the lock status block format diagram and status block
    fields table, see the VSI OpenVMS System Services Reference
    Manual.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the $ENQ operation. The flags
    argument is a longword bit mask that is the logical OR of each
    bit set, where each bit corresponds to an option.

    The $LCKDEF macro defines a symbolic name for each flag bit.

    To view the table describing each flag, see the VSI OpenVMS System
    Services Reference Manual.

 resnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the resource to be locked by this lock. The resnam
    argument is the 32- or 64-bit address of a character string
    descriptor pointing to this name. The name string can be from
    1 to 31 bytes in length.

    If you are creating a new lock, the resnam argument should be
    specified because the default value for the resnam argument
    produces an error when it is used to create a lock. The resnam
    argument is ignored for lock conversions.

 parid

    OpenVMS usage:lock_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Lock identification of the parent lock. The parid argument is a
    longword containing this identification value.

    If you do not specify this argument or specify it as 0, $ENQ
    assumes that the lock does not have a parent lock. This argument
    is optional for new locks and is ignored for lock conversions.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference
    AST service routine to be executed when the lock is either
    granted or converted. The astadr argument is the 32- or 64-bit
    address of this routine. The AST is also delivered when the lock
    or conversion request is canceled. Cancellation occurs if you use
    $DEQ with the cancel modifier or if the waiting request is chosen
    to break a deadlock.

    If you specify the astadr argument, the AST routine executes at
    the same access mode as the caller of $ENQ.

 astprm

    OpenVMS usage:user_arg
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    AST parameter to be passed to the AST routine specified by the
    astadr argument. The astprm argument specifies this quadword
    parameter.

 blkast

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference
    Blocking AST routine to be called whenever this lock is granted
    and is blocking any other lock requests. The blkast argument
    is the 32- or 64-bit address of this routine. Locks that are
    converting to a new mode, but that are not yet granted in the new
    mode, do not receive blocking ASTs.

    You can pass a parameter to this routine by using the astprm
    argument.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be associated with the resource name. The acmode
    argument indicates the least privileged access mode from which
    locks can be queued on the resource.

    This argument does not affect the access mode associated with the
    lock or its blocking and completion ASTs. The acmode argument is
    a longword containing the access mode. The $PSLDEF macro defines
    the following symbols for the four access modes:

    Symbol        Access Mode

    PSL$C_KERNEL  Kernel
    PSL$C_EXEC    Executive
    PSL$C_SUPER   Supervisor
    PSL$C_USER    User

    The $ENQ service associates an access mode with the lock in the
    following way:

    o  If you specified a parent lock (with the parid argument),
       $ENQ uses the access mode associated with the parent lock and
       ignores both the acmode argument and the caller's access mode.

    o  If the lock has no parent lock (you did not specify the parid
       argument or specified it as 0), $ENQ uses the least privileged
       of the caller's access mode and the access mode specified
       by the acmode argument. If you do not specify the acmode
       argument, $ENQ uses the caller's access mode.

 rsdm_id

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Resource domain identification. The rsdm_id argument is a
    longword specifying the resource domain association through
    which a new lock is to be taken. This argument is ignored for
    lock conversions and sublocks (parid is nonzero). Valid resource
    domain identifiers are returned from the $SET_RESOURCE_DOMAIN
    service, or by the constants RSDM$K_SYSTEM_RSDM_ID or RSDM$K_
    PROCESS_RSDM_ID, which are defined by the $RSDMDEF macro in
    STARLET.

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument reserved by VSI.

110  –  $ENQW

    Queues a lock on a resource. The $ENQW service completes
    synchronously; that is, it returns to the caller when the
    lock has been either granted or converted. For asynchronous
    completion, use the Enqueue Lock Request ($ENQ) service; $ENQ
    returns to the caller after queuing the lock request, without
    waiting for the lock to be either granted or converted. In
    all other respects, $ENQW is identical to $ENQ. See the $ENQ
    description for all other information about the $ENQW service.

    The $ENQ, $ENQW, $DEQ, and $GETLKI services together provide the
    user interface to the Lock Management facility.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ENQW  [efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid]

                ,[astadr] ,[astprm] ,[blkast] ,[acmode] ,[rsdm_id]

    C Prototype

      int sys$enqw  (unsigned int efn, unsigned int lkmode,

                    struct _lksb *lksb, unsigned int flags,

                    void *resnam, unsigned int parid, void

                    (*astadr)(__unknown_params), unsigned __int64

                    astprm, void (*blkast)(__unknown_params),

                    unsigned int acmode, unsigned int rsdm_id,...);

111  –  $ENTER

    The Enter service inserts a file name in a directory.

    For additional information about this service, see to the OpenVMS
    Record Management Services Reference Manual.

112  –  $ERAPAT

    Generates a security erase pattern.

    Format

      SYS$ERAPAT  [type] ,[count] ,[patadr]

    C Prototype

      int sys$erapat  (int type, unsigned int count, unsigned int

                      *patadr);

112.1  –  Arguments

 type

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Type of storage to be written over with the erase pattern. The
    type argument is a longword containing the type of storage.

    The three storage types, together with their symbolic names,
    are defined by the $ERADEF macro and are listed in the following
    table:

    Storage Type   Symbolic Name

    Main memory    ERA$K_MEMORY
    Disk           ERA$K_DISK
    Tape           ERA$K_TAPE

 count

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of times that $ERAPAT has been called in a single security
    erase operation. The count argument is a longword containing the
    iteration count.

    You should call the $ERAPAT service initially with the count
    argument set to 1, the second time with the count argument set to
    2, and so on, until the status code SS$_NOTRAN is returned.

 patadr

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Security erase pattern to be written. The patadr argument is the
    address of a longword into which the security erase pattern is to
    be written.

113  –  $ERASE

    The Erase service deletes a disk file and removes the file's
    directory entry specified in the path to the file. If additional
    directory entries have been created for this file by the Enter
    service, you must use the Remove service to delete them.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

114  –  $EXIT

    Initiates image rundown when the current image in a process
    completes execution. Control normally returns to the command
    interpreter.

    Format

      SYS$EXIT  [code]

    C Prototype

      int sys$exit  (unsigned int code);

114.1  –  Argument

 code

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Longword value to be saved in the process header as the
    completion status of the current image. If you do not specify
    this argument in a macro call, a value of 1 is passed as the
    completion code for VAX MACRO and VAX BLISS-32, and a value of
    0 is passed for other languages. You can test this value at the
    command level to provide conditional command execution.

115  –  $EXPREG

    Adds a specified number of new virtual pages to a process's
    program region or control region for the execution of the current
    image. Expansion occurs at the current end of that region's
    virtual address space.

    Format

      SYS$EXPREG  pagcnt ,[retadr] ,[acmode] ,[region]

    C Prototype

      int sys$expreg  (unsigned int pagcnt, struct _va_range *retadr,

                      unsigned int acmode, char region);

115.1  –  Arguments

 pagcnt

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of pagelets to add to the current end of the program
    or control region. The pagcnt argument is a longword value
    containing this number.

    On Alpha and Integrity server systems, the specified value is
    rounded up to an even multiple of the CPU-specific page size.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Starting and ending process virtual addresses of the pages that
    $EXPREG has actually added. The retadr argument is the address of
    a 2-longword array containing, in order, the starting and ending
    process virtual addresses.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be associated with the newly added pages. The
    acmode argument is a longword containing the access mode.

    The most privileged access mode used is the access mode of the
    caller.

    The newly added pages are given the following protection:
    (1)  read and write access for access modes equal to or more
    privileged than the access mode used in the call, and (2)  no
    access for access modes less privileged than that used in the
    call.

 region

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number specifying which program region is to be expanded. The
    region argument is a longword value. A value of 0 (the default)
    specifies that the program region (P0 region) is to be expanded.
    A value of 1 specifies that the control region (P1 region) is to
    be expanded.

116  –  $EXPREG 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, adds a specified number of
    demand-zero allocation pages to a process's virtual address space
    for the execution of the current image. Expansion occurs at the
    next free available address within the specified region.

    This service accepts 64-bit addresses.

    Format

      SYS$EXPREG_64  region_id_64 ,length_64 ,acmode ,flags

                     ,return_va_64 ,return_length_64

    C Prototype

      int sys$expreg_64  (struct _generic_64 *region_id_64, unsigned

                         __int64 length_64, unsigned int acmode,

                         unsigned int flags, void *(*(return_va_64)),

                         unsigned __int64 *return_length_64);

116.1  –  Arguments

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the virtual address range to be
    expanded. The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF
    macro in STARLET.MLB define a symbolic name for each of the three
    default regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space to be created. The length
    specified must be a multiple of CPU-specific pages.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode associated with the call to $EXPREG_64. The access
    mode determines the owner mode of the pages as well as the read
    and write protection on the pages. The acmode argument is a
    longword containing the access mode. The $PSLDEF macro defines
    symbols for the four access modes.

    The $EXPREG_64 service uses whichever of the following two access
    modes is least privileged:

    o  The access mode specified by the acmode argument.

    o  The access mode of the caller. The protection of the pages
       is read/write for the resultant access mode and those more
       privileged.

    Address space cannot be created within a region that has a create
    mode associated with it that is more privileged than the caller's
    mode. The condition value SS$_IVACMODE is returned if the caller
    is less privileged than the create mode for the region.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask controlling the characteristics of the demand-zero
    pages created. The flags argument is a longword bit vector in
    which each bit corresponds to a flag. The $VADEF macro and the
    VADEF.H file define a symbolic name for each flag. You construct
    the flags argument by performing a logical OR operation on the
    symbol names for all desired flags.

    All bits in the flags argument are reserved for future use by VSI
    and should be specified as 0. The condition value SS$_IVVAFLG is
    returned if any bits are set.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of a created virtual address
    range. The return_va_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword into which the service
    returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned quadword
    into which the service returns the length in bytes of the virtual
    address range created.

117  –  $EXTEND

    The Extend service increases the amount of space allocated to
    a disk file. This service is most useful for extending relative
    files and indexed files when you are doing block I/O transfers
    using the Write service.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

118  –  $FAO

    Converts a binary value into an ASCII character string in
    decimal, hexadecimal, or octal notation; returns the character
    string in an output string; and inserts variable character-string
    data into an output string.

    The Formatted ASCII Output with List Parameter ($FAOL) service
    provides an alternate method for specifying input parameters when
    calling the $FAO system service.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$FAO  ctrstr ,[outlen] ,outbuf ,[p1]...[pn]

      SYS$FAOL  ctrstr ,[outlen] ,outbuf ,[prmlst]

    C Prototype

      int sys$fao  (void *ctrstr, unsigned short int *outlen, void

                   *outbuf,...);

      int sys$faol  (void *ctrstr, unsigned short int *outlen, void

                    *outbuf, void *prmlst);

118.1  –  Arguments

 ctrstr

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Control string passed to $FAO that contains the text to be output
    together with one or more $FAO directives. $FAO directives are
    used to specify repeat counts or the output field length, or
    both, and they are preceded by an exclamation point (!).  The
    ctrstr argument is the 32- or 64-bit address of a character
    string descriptor pointing to the control string.

    There is no restriction on the length of the control string or
    on the number of $FAO directives it can contain; however, if an
    exclamation point must appear in the output string, it must be
    represented in the control string by a double exclamation point
    (!!).  A single exclamation point in the control string indicates
    to $FAO that the next characters are to be interpreted as FAO
    directives.

    When $FAO processes the control string, it writes to the output
    buffer each character that is not part of an $FAO directive.

    If the $FAO directive is valid, $FAO processes it. If the
    directive requires a parameter, $FAO processes the next
    consecutive parameter in the specified parameter list. If the
    $FAO directive is not valid, $FAO terminates and returns a
    condition value in R0.

    The $FAO service reads parameters from the argument list
    specified in the call; these arguments have the names p1, p2,
    p3, and so on, up to p17. Each argument specifies one parameter.
    Because $FAO accepts a maximum of 17 parameters in a single call,
    you must use $FAOL if the number of parameters exceeds 17. The
    $FAOL service accepts any number of parameters used with the
    prmlst argument.

 outlen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Length in bytes of the fully formatted output string returned by
    $FAO. The outlen argument is the 32- or 64-bit address of a word
    containing this value.

 outbuf

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Output buffer into which $FAO writes the fully formatted output
    string. The outbuf argument is the 32- or 64-bit address of a
    character string descriptor pointing to the output buffer. The
    maximum number of bytes written is limited to 64K.

 p1 to pn

    OpenVMS usage:varying_arg
    type:         quadword (signed)
    access:       read only
    mechanism:    by value
    $FAO directive parameters. The p1 argument is a quadword
    containing the parameter needed by the first $FAO directive
    encountered in the control string, the p2 argument is a quadword
    containing the parameter needed for the second $FAO directive,
    and so on for the remaining arguments up to p17. If an $FAO
    directive does not require a parameter, that $FAO directive is
    processed without reading a parameter from the argument list.

    Depending on the directive, a parameter can be a value to be
    converted, a 32- or 64-bit address of a string to be inserted
    into the output string, or a length or argument count. Each
    directive in the control string might require a corresponding
    parameter or parameters.

 prmlst

    OpenVMS usage:vector_longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    List of $FAO directive parameters to be passed to $FAOL. The
    prmlst argument is the 32- or 64-bit address of a list of
    longwords wherein each longword is a parameter. The $FAOL service
    processes these parameters sequentially as it encounters, in the
    control string, $FAO directives that require parameters.

    The parameter list can be a data structure that already exists in
    a program and from which certain values are to be extracted.

119  –  $FAOL 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, converts a binary value
    into an ASCII character string in decimal, hexadecimal, or octal
    notation; returns the character string in an output string; and
    inserts variable character-string data into an output string.

    $FAOL_64 interprets the parameter list as a list of quadwords
    rather than a list of longwords. In all other respects, $FAOL_64
    is identical to $FAOL. For all other information about the $FAOL_
    64 service, see the help for $FAO/$FAOL.

    This service accepts 64-bit addresses.

    Format

      SYS$FAOL_64  ctrstr_64 [,outlen_64 [,outbuf_64

                   [,quad_prmlst_64]]]

    C Prototype

      int sys$faol_64  (void *ctrstr_64, unsigned short int

                       *outlen_64, void *outbuf_64, void

                       *quad_prmlst_64);

119.1  –  Arguments

 ctrstr_64

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    The 32- or 64-bit address of the control string (64-bit or 32-bit
    string descriptor).

 outlen_64

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit address of the quadword that contains the
    output length, in bytes, of the fully formatted output string.

 outbuf_64

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    The 32- or 64-bit address of a character string descriptor that
    points to the output buffer into which $FAOL_64 writes the fully
    formatted output string.

 quad_prmlst_64

    OpenVMS usage:vector_quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit address of a quadword-aligned array of quadword
    FAO arguments.

120  –  $FILESCAN

    Searches a string for a file specification and parses the
    components of that file specification.

    Format

      SYS$FILESCAN  srcstr ,valuelst ,[fldflags] ,[auxout] ,[retlen]

    C Prototype

      int sys$filescan  (void *srcstr, void *valuelst, unsigned int

                        *fldflags, void *auxout, unsigned short int

                        *retlen);

120.1  –  Arguments

 srcstr

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    String to be searched for the file specification. The srcstr
    argument is the address of a descriptor pointing to this string.

 valuelst

    OpenVMS usage:item_list_2
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Item list specifying which components of the file specification
    are to be returned by $FILESCAN. The components are the full node
    specification, primary node name, primary node's access control,
    secondary node information, device, directory, file name, file
    type, and version number. The itmlst argument is the address of a
    list of item descriptors wherein each item descriptor specifies
    one component. The list of item descriptors is terminated by a
    longword of 0.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

 fldflags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Longword flag mask in which $FILESCAN sets a bit for each file
    specification component found in the input string. The fldflags
    argument is the address of this longword flag mask.

    The $FSCNDEF macro defines a symbolic name for each significant
    flag bit. The following table shows the file specification
    component that corresponds to the symbolic name of each flag
    bit:

    Symbolic Name    Corresponding Component

    FSCN$V_DEVICE    Device name
    FSCN$V_          Directory name
    DIRECTORY
    FSCN$V_NAME      File name
    FSCN$V_NODE      Node name
    FSCN$V_NODE_ACS  Access control string of primary node
    FSCN$V_NODE_     Primary (first) node name
    PRIMARY
    FSCN$V_NODE_     Secondary (additional) node information
    SECONDARY
    FSCN$V_ROOT      Root directory name string
    FSCN$V_TYPE      File type
    FSCN$V_VERSION   Version number

    The fldflags argument is optional. When you want to know which
    components of a file specification are present in a string but
    do not need to know the contents or length of these components,
    specify fldflags instead of valuelst.

 auxout

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Auxiliary output buffer. The auxout argument is the address of a
    character-string descriptor pointing to the auxiliary buffer.

    When you specify an auxiliary output buffer, $FILESCAN copies
    the entire source string, with quotation information reduced and
    simplified for only the primary node, into the auxiliary output
    buffer.

    When the auxiliary output buffer is provided, all addresses
    returned in the item list point to locations in the auxiliary
    output buffer.

 retlen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Length of the auxiliary buffer. The retlen argument is the
    address of a word into which $FILESCAN writes the length of the
    auxiliary buffer name string.

121  –  $FIND

    The Find service locates a specified record in a file and returns
    its record file address in the RAB$W_RFA field of the RAB. The
    Find service can be used with all file organizations.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

122  –  $FIND HELD

    Returns the identifiers held by a specified holder.

    Format

      SYS$FIND_HELD  holder ,[id] ,[attrib] ,[contxt]

    C Prototype

      int sys$find_held  (struct _generic_64 *holder, unsigned int

                         *id, unsigned int *attrib, unsigned int

                         *contxt);

122.1  –  Arguments

 holder

    OpenVMS usage:rights_holder
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Holder whose identifiers are to be found when $FIND_HELD
    completes execution. The holder argument is the address of a
    quadword data structure containing the holder identifier. This
    quadword data structure consists of a longword containing the
    holder UIC, followed by a longword containing the value 0.

 id

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Identifier value found when $FIND_HELD completes execution.
    The id argument is the address of a longword containing the
    identifier value with which the holder is associated.

 attrib

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Attributes associated with the holder returned in id when $FIND_
    HELD completes execution. The attrib argument is the address of a
    longword containing a bit mask specifying the attributes.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The symbols are defined
    in the system macro library ($KGBDEF). The following are the
    symbols for each bit position:

    Bit Position    Meaning When Set

    KGB$V_DYNAMIC   Allows holders of the identifier to remove it
                    from or add it to the process rights list by
                    using the DCL command SET RIGHTS_LIST.

    KGB$V_          Makes any access rights of the identifier
    NOACCESS        null and void. This attribute is intended as
                    a modifier for a resource identifier or the
                    Subsystem attribute.

    KGB$V_          Allows the holder to charge resources, such as
    RESOURCE        disk blocks, to the identifier.

    KGB$V_          Allows holders of the identifier to create and
    SUBSYSTEM       maintain protected subsystems by assigning the
                    Subsystem ACE to the application images in the
                    subsystem.

 contxt

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Context value used when repeatedly calling $FIND_HELD. The contxt
    argument is the address of a longword used while searching for
    all identifiers. The context value must be initialized to 0,
    and the resulting context of each call to $FIND_HELD must be
    presented to each subsequent call. After contxt is passed to
    $FIND_HELD, you must not modify its value.

123  –  $FIND HOLDER

    Returns the holder of a specified identifier.

    Format

      SYS$FIND_HOLDER  id ,[holder] ,[attrib] ,[contxt]

    C Prototype

      int sys$find_holder  (unsigned int id, struct _generic_64

                           *holder, unsigned int *attrib, unsigned

                           int *contxt);

123.1  –  Arguments

 id

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Binary identifier value whose holders are found by $FIND_HOLDER.
    The id argument is a longword containing the binary identifier
    value.

 holder

    OpenVMS usage:rights_holder
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    Holder identifier returned when $FIND_HOLDER completes execution.
    The holder argument is the address of a quadword containing
    the holder identifier. The first longword contains the UIC of
    the holder with the high-order word containing the group number
    and the low-order word containing the member number. The second
    longword contains the value 0.

 attrib

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Mask of attributes associated with the holder record specified
    by holder. The attrib argument is the address of a longword
    containing the attribute mask.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The symbols are defined
    in the system macro library ($KGBDEF). The following are the
    symbols for each bit position:

    Bit Position    Meaning When Set

    KGB$V_DYNAMIC   Allows holders of the identifier to remove it
                    from or add it to the process rights list by
                    using the DCL command SET RIGHTS_LIST. For more
                    information about SET RIGHTS_LIST, see the VSI
                    OpenVMS DCL Dictionary.

    KGB$V_          Makes any rights of the identifier null and void.
    NOACCESS        This attribute is intended as a modifier for a
                    resource identifier or the Subsystem attribute.

    KGB$V_          Allows the holder of an identifier to charge disk
    RESOURCE        space to the identifier. It is used only for file
                    objects.

    KGB$V_          Allows holders of an identifier to create and
    SUBSYSTEM       maintain protected subsystems by assigning the
                    Subsystem ACE to the application images in the
                    subsystem.

 contxt

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Context value used while searching for all the holders of the
    specified identifier when executing $FIND_HOLDER. The contxt
    argument is the address of a longword containing the context
    value. When calling $FIND_HOLDER repeatedly, contxt must be
    set initially to 0 and the resulting context of each call to
    $FIND_HOLDER must be presented to each subsequent call. After
    the argument is passed to $FIND_HOLDER, you must not modify its
    value.

124  –  $FINISH RDB

    Deallocates the record stream and clears the context value used
    with $FIND_HELD, $FIND_HOLDER, or $IDTOASC.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$FINISH_RDB  contxt

    C Prototype

      int sys$finish_rdb  (unsigned int *contxt);

124.1  –  Argument

 contxt

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by 32- or 64-bit reference
    Context value to be cleared when $FINISH_RDB completes execution.
    The contxt argument is a longword containing the address of the
    context value.

125  –  $FLUSH

    The Flush service writes out all modified I/O buffers and file
    attributes associated with the file. This ensures that all record
    activity up to the point at which the Flush service executes is
    actually reflected in the file.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

126  –  $FORCEX

    Causes an Exit ($EXIT) service call to be issued on behalf of a
    specified process.

    Format

      SYS$FORCEX  [pidadr] ,[prcnam] ,[code]

    C Prototype

      int sys$forcex  (unsigned int *pidadr, void *prcnam, unsigned

                      int code);

126.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) of the process to be forced to exit.
    The pidadr argument is the address of a longword containing the
    PID.

    The pidadr argument can refer to a process running on the local
    node or a process running on another node in the OpenVMS Cluster
    system.

    The pidadr argument is optional but must be specified if the
    process that is to be forced to exit is not in the same UIC group
    as the calling process.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Process name of the process that is to be forced to exit. The
    prcnam argument is the address of a character string descriptor
    pointing to the process name string. A process running on the
    local node can be identified with a 1- to 15-character string.
    To identify a process on a particular node in a cluster, specify
    the full process name, which includes the node name as well as
    the process name. The full process name can contain up to 23
    characters.

    The prcnam argument can be used only on behalf of processes in
    the same UIC group as the calling process. To force processes in
    other groups to exit, you must specify the pidadr argument. This
    restriction exists because the operating system interprets the
    UIC group number of the calling process as part of the specified
    process name; the names of processes are unique to UIC groups.

 code

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Completion code value to be used as the exit parameter. The
    code argument is a longword containing this value. If you do
    not specify the code argument, the value 0 is passed as the
    completion code.

127  –  $FORGET RM

    Deletes a Resource Manager instance (RMI) from the calling
    process.

    Format

      SYS$FORGET_RM  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id

    C Prototype

      int sys$forget_rm  (unsigned int efn, unsigned int

                         flags, struct _iosb *iosb, void

                         (*astadr)(__unknown_params), int astprm,

                         unsigned int rm_id);

127.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for the option
    flag listed in $FORGET_RM Option Flag. All undefined bits must be
    0. If this argument is omitted, no flags are used.

    Table SYS-18 $FORGET_RM Option Flag

    Flag Name      Description

    DDTM$M_SYNC    Specifies successful synchronous completion by
                   returning SS$_SYNCH. When SS$_SYNCH is returned,
                   the AST routine is not called, the event flag is
                   not set, and the I/O status block is not filled
                   in.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the completion status of the
    service is returned as a condition value.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the I/O status block diagram.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine executed when the service completes, if SS$_
    NORMAL is returned in R0. The astadr argument is the address of
    the entry mask of this routine. The routine is executed in the
    same access mode as that of the caller of the $FORGET_RM service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter that is passed to the AST routine specified by
    the astadr argument.

 rm_id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The identifier of the RMI to be deleted from the calling process.

128  –  $FORGET RMW

    Deletes a Resource Manager instance (RMI) from the calling
    process.

    $FORGET_RMW always waits for the request to complete before
    returning to the caller. Other than this, it is identical to
    $FORGET_RM.

    Format

      SYS$FORGET_RMW  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id

    C Prototype

      int sys$forget_rmw  (unsigned int efn, unsigned int

                          flags, struct _iosb *iosb, void

                          (*astadr)(__unknown_params), int astprm,

                          unsigned int rm_id);

129  –  $FORMAT ACL

    Formats the specified access control entry (ACE) into a text
    string.

    Format

      SYS$FORMAT_ACL  aclent ,[acllen] ,aclstr ,[width] ,[trmdsc]

                      ,[indent] ,[accnam] ,[nullarg]

    C Prototype

      int sys$format_acl  (void *aclent, unsigned short int

                          *acllen, void *aclstr, unsigned short

                          int *width, void *trmdsc, unsigned short

                          int *indent, unsigned int *accnam, int

                          (*routin)(__unknown_params));

129.1  –  Arguments

 aclent

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Description of the ACE formatted when $FORMAT_ACL completes
    execution. The aclent argument is the address of a descriptor
    pointing to a buffer containing the description of the input ACE.
    The first byte of the buffer contains the length of the ACE; the
    second byte contains a value that identifies the type of ACE,
    which in turn determines the ACE format.

    See the $FORMAT_ACL Description section in the VSI OpenVMS System
    Services Reference Manual for more information about the ACE
    format.

 acllen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Length of the output string resulting when $FORMAT_ACL completes
    execution. The acllen argument is the address of a word
    containing the number of characters written to aclstr.

 aclstr

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Formatted ACE resulting when $FORMAT_ACL completes its execution.
    The aclstr argument is the address of a string descriptor
    pointing to a buffer containing the output string.

 width

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Maximum width of the formatted ACE resulting when $FORMAT_ACL
    completes its execution. The width argument is the address of
    a word containing the maximum width of the formatted ACE. If
    this argument is omitted or contains the value 0, an infinite
    length display line is assumed. When the width is exceeded, the
    character specified by trmdsc is inserted.

 trmdsc

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Line termination characters used in the formatted ACE. The trmdsc
    argument is the address of a descriptor pointing to a character
    string containing the termination characters that are inserted
    for each formatted ACE when the width has been exceeded.

 indent

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Number of blank characters beginning each line of the formatted
    ACE. The indent argument is the address of a word containing
    the number of blank characters that you want inserted at the
    beginning of each formatted ACE.

 accnam

    OpenVMS usage:access_bit_names
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Names of the bits in the access mask when executing the $FORMAT_
    ACL. The accnam argument is the address of an array of 32
    quadword descriptors that define the names of the bits in the
    access mask. Each element points to the name of a bit. The first
    element names bit 0, the second element names bit 1, and so on.

    You can call LIB$GET_ACCNAM to retrieve the access name table for
    the class of object whose ACL is to be formatted.

    If you omit accnam, the following names are used:

    Bit    Name

    Bit 0  READ
    Bit 1  WRITE
    Bit 2  EXECUTE
    Bit 3  DELETE
    Bit 4  CONTROL
    Bit 5  BIT_5
    Bit 6  BIT_6
    .
    .
    .
    Bit    BIT_31
    31

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

130  –  $FORMAT AUDIT

    Converts a security auditing event message from binary format to
    ASCII text.

    Format

      SYS$FORMAT_AUDIT  fmttyp ,audmsg ,[outlen] ,outbuf ,[width]

                        ,[trmdsc] ,[routin] ,[fmtflg]

    C Prototype

      int sys$format_audit  (unsigned int fmttyp, void *audmsg,

                            unsigned short int *outlen, void *outbuf,

                            unsigned short int *width, void *trmdsc,

                            int (*routin)(__unknown_params), unsigned

                            int fmtflg);

130.1  –  Arguments

 fmttyp

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Format for the message. The fmttyp argument is a value indicating
    whether the security audit message should be in brief format,
    which is one line of information, or full format. The default is
    full format. Refer to the VSI OpenVMS System Manager's Manual for
    examples of formatted output.

    The following table defines the brief and full formats:

    Value                  Meaning

    NSA$C_FORMAT_STYLE_    Use a brief format for the message.
    BRIEF
    NSA$C_FORMAT_STYLE_    Use a full format for the message.
    FULL

 audmsg

    OpenVMS usage:char_string
    type:         byte stream (unsigned)
    access:       read only
    mechanism:    by reference
    Security auditing message to format. The audmsg argument is
    the address of a buffer containing the message that requires
    formatting.

 outlen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Length of the formatted security audit message. The outlen
    argument is the address of the word receiving the final length
    of the ASCII message.

 outbuf

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Buffer holding the formatted message. The outbuf argument is
    the address of a descriptor pointing to the buffer receiving the
    message.

 width

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Maximum width of the formatted message. The width argument is the
    address of a word containing the line width value. The default is
    80 columns.

    The width argument does not work consistently. In most cases, if
    you specify both the width argument and the full format style
    (NSA$C_FORMAT_STYLE_FULL), $FORMAT_AUDIT ignores the width
    argument. The minimum width is 80 columns; lower values do not
    limit the width to less than 80. If you specify a width greater
    than 80 columns, most lines are not joined to use the full width.

    In most cases, you should avoid using the width argument.

 trmdsc

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Line termination characters used in a full format message. The
    trmdsc argument is the address of a descriptor pointing to the
    line termination characters to insert within a line segment
    whenever the width is reached.

 routin

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by reference
    Routine that writes a formatted line to the output buffer. The
    routin argument is the address of a routine called each time a
    line segment is formatted. The argument passed to the routine
    is the address of a character string descriptor for the line
    segment.

    When an application wants event messages in the brief format,
    $FORMAT_AUDIT calls the routine twice to format the first event
    message. The first time it is called, the routine passes a string
    containing the column titles for the message. The second and
    subsequent calls to the routine pass the formatted event message.
    By using this routine argument, a caller can gain control at
    various points in the processing of an audit event message.

 fmtflg

    OpenVMS usage:longword (unsigned)
    type:         mask_longword
    access:       read only
    mechanism:    by value
    Determines the formatting of certain kinds of audit messages.
    The fmtflg argument is a mask specifying whether sensitive
    information should be displayed or column titles built for
    messages in brief format. For example, the operating system
    uses bit 0 to suppress plain-text passwords from security alarm
    messages.

    The following table describes the significant bits:

    Bit  Value   Description

    0    1       Do not format sensitive information.
         0       Format sensitive information.
    1    1       Build a column title for messages in brief format.
                 (You must specify a fmttyp of brief and a routin
                 argument.)
         0       Do not build column titles.

131  –  $FREE

    The Free service unlocks all records that were previously locked
    for the record stream.

    Refer to the OpenVMS Record Management Services Reference Manual
    for additional information about this service.

132  –  $FREE USER CAPABILITY (Alpha and Integrity servers)

    On Alpha and Integrity server systems, releases a user
    capability, indicating to other processes that the resource is
    now available.

    This service accepts 64-bit addresses.

    Format

      SYS$FREE_USER_CAPABILITY   cap_num [,prev_num] [,flags]

    C Prototype

      int sys$free_user_capability  (int *cap_num, struct _generic_64

                                    *prev_mask, struct _generic_64

                                    *flags);

132.1  –  Arguments

 cap_num

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Capability number to be released by the calling Kernel thread.
    This number can range from 1 to 16. The cap_num argument is
    the 32- or 64-bit address of the longword containing the user
    capability number.

 prev_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The previous user capability reservation mask before execution
    of this service call. The prev_mask argument is the 32- or 64-bit
    address of a quadword into which the service writes a quadword
    bit mask specifying the previously reserved user capabilities.

 flags

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Options selected for the user capability reservation. The flags
    argument is a quadword bit vector wherein a bit corresponds to an
    option.

    Each option (bit) has a symbolic name, which the $CAPDEF macro
    defines. The flags argument is constructed by performing a
    logical OR operation using the symbolic names of each desired
    option.

    At this time, all bits are Reserved to VSI and must be 0.

133  –  $GET

    The Get service retrieves a record from a file.

    Refer to the OpenVMS Record Management Services Reference Manual
    for additional information about this service.

134  –  $GETDTI

    Returns information about the state of transactions.

    Format

      SYS$GETDTI  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,[log_id]

                  ,[contxt] ,search ,itmlst

    C Prototype

      int sys$getdti  (unsigned int efn, unsigned int flags, struct

                      _iosb *iosb, void (*astadr)(__unknown_params),

                      int astprm, unsigned int log_id [4], unsigned

                      int *contxt, void *search, void *itmlst);

134.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for these option
    flags described in $GETDTI Option Flags. All undefined bits must
    be 0. If this argument is omitted, no flags are used.

    Table SYS-19 $GETDTI Option Flags

    Flag Name        Description

    DDTM$M_FULL_     Indicates that the $GETDTI call for a specified
    STATE            TID is not to complete until the ABORTED
                     or COMMITTED state can be returned. Thus,
                     if another node or coordinating resource
                     manager must be contacted and it is currently
                     unreachable, this service does not return
                     until the node can be contacted. Indicates on
                     a wildcard search that only transactions known
                     to be in the ABORTED or COMMITTED states are to
                     be returned.
    DDTM$M_SYNC      Specifies successful synchronous completion by
                     returning SS$_SYNCH. When SS$_SYNCH is returned,
                     the AST routine is not called, the event flag is
                     not set, and the I/O status block is not filled
                     in.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the completion status of the
    service is returned as a condition value.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the I/O status block diagram.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine executed when the service completes, if SS$_
    NORMAL is returned in R0. The astadr argument is the address of
    the entry mask of this routine. The routine is executed in the
    same access mode as that of the caller of the $GETDTI service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter passed to the AST routine specified by the
    astadr argument.

 log_id

    OpenVMS usage:uid
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The log id of the transaction manager that is coordinating the
    transaction, returned as the log_id argument on a $DECLARE_RM
    operation. The log_id argument verifies that the recovery log
    returning transaction information is the same one used to record
    transaction state information.

    If you do not specify the same log id used by the transaction
    manager to write transaction information, then $GETDTI will
    return an error.

    If the log_id argument is specified as a zero UID, then $GETDTI
    will use the current active log for this node. If the specified
    transaction cannot be found in this log, then the returned state
    will be aborted. The log identifier can only be specified as
    zero when the DTI$_SEARCH_AS_NODE item is absent or results in
    a search that specifies the local node. Note that the log_id
    argument cannot be specified as a zero address.

    To ensure smooth operation in a mixed-network environment,
    refer to the chapter entitled Managing DECdtm Services in the
    VSI OpenVMS System Manager's Manual, for information on defining
    node names.

 contxt

    OpenVMS usage:contxt
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    The address of a longword used to maintain a context between
    sequential calls to $GETDTI. A call to $GETDTI will start a new
    search if the context value is zero or continue the existing
    search if the context is valid.

    The search context is valid only after a successful call to
    $GETDTI and is invalidated by a subsequent call to $GETDTI.

    The context is also used as input to $SETDTI after a successful
    call to $GETDTI. Calls to $SETDTI do not modify or invalidate the
    context.

 search

    OpenVMS usage:item_list_3
    type:         descriptor list
    access:       read only
    mechanism:    by reference
    Item list specifying how the search for transaction information
    is to be bounded.

    The search argument is the address of a list of item descriptors,
    each of which describes a search item. The list of item
    descriptors is terminated by a longword of 0. Each item
    descriptor in the search item list acts as an input argument
    to $GETDTI and as such is only required to be read only.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the single item descriptor format.

    The following table describes the search item descriptor fields:

    Field          Description

    Buffer         A word containing a user-supplied integer
    length         specifying the length (in bytes) of a buffer from
                   which $GETDTI is to read the information. The
                   length of the buffer needed depends on the item
                   code field of the search item descriptor. If the
                   value of buffer length is too small, $GETDTI will
                   return an error status.
    Item code      A word containing a user-supplied symbolic code
                   specifying the search item that $GETDTI is to use.
                   The $DTIDEF macro defines these codes. Each item
                   code is described in the Search Item Codes section
                   below.
    Buffer         A longword containing the user-supplied address
    address        of the buffer from which $GETDTI reads the search
                   information.
    Return         This longword is not used in the search item list,
    length         because all search items are read-only.
    address

 itmlst

    OpenVMS usage:item_list_3
    type:         descriptor list
    access:       read only
    mechanism:    by reference
    Item list specifying the transaction information that $GETDTI
    is to return. The itmlst argument is the address of a list of
    item descriptors, containing a single entry that describes an
    item of information. The list of item descriptors is terminated
    by a longword of 0. The item descriptor in the item list acts
    as an output argument to $GETDTI and as such is required to be
    writeable in caller's mode.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the single item descriptor format.

    The following table describes the itmlst item descriptor fields:

    Field          Description

    Buffer         A word containing a user-supplied integer
    length         specifying the length (in bytes) of the buffer
                   where $GETDTI is to write the information. The
                   length of the buffer needed depends on the item
                   code field of the search item descriptor. If
                   the value of buffer length is too small, $GETDTI
                   truncates the data and returns the condition code
                   value SS$_BUFFEROVF.
    Item code      A word containing a user-supplied symbolic code
                   specifying the search item that $GETDTI is to
                   use. The $DTIDEF macro defines these codes. Each
                   item code is described in the Itmlst Item Codes
                   section.
    Buffer         A longword containing the user-supplied address
    address        of the buffer where $GETDTI is to write the
                   information.
    return         A longword containing the user-supplied address
    length         of a word where $GETDTI writes return length
    address        information.

135  –  $GETDTIW

    Returns information about the resolved state of transactions and
    the process default transaction identifier.

    $GETDTIW always waits for the request to complete before
    returning to the caller. Other than this, it is identical to
    $GETDTI.

    Format

      SYS$GETDTIW  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,[contxt]

                   ,[log_id] ,search ,itmlst

    C Prototype

      int sys$getdtiw  (unsigned int efn, unsigned int flags, struct

                       _iosb *iosb, void (*astadr)(__unknown_params),

                       int astprm, unsigned int log_id [4], unsigned

                       int *contxt, void *search, void *itmlst);

136  –  $GETDVI

    Returns information related to the primary and secondary device
    characteristics of an I/O device.

                                   NOTE

       All pathname-related information pertains only to Alpha and
       Integrity server systems.

    For synchronous completion, use the Get Device/Volume Information
    and Wait ($GETDVIW) service. The $GETDVIW service is identical to
    the $GETDVI service in every way except that $GETDVIW returns to
    the caller with the requested information.

    For additional information about system service completion, see
    the Synchronize ($SYNCH) service.

                          NOTE ABOUT ITEM CODES

       For item codes that return a string data type, failure to
       pass in a buffer that is large enough to hold the returned
       data results in silent data truncation. When $GETDVI
       completes, VSI recommends that you check the returned length
       field of an item list descriptor for each item code that
       can return a string. If the returned length is equal to the
       size of the buffer allocated to hold the returned data, the
       data might have been truncated. In that case, call $GETDVI
       iteratively with a larger buffer until the length of the
       returned data is less than the size of the buffer allocated.

       Unless the description of an item code specifies otherwise,
       VSI recommends that you use a buffer of 32 bytes to hold
       the returned string. $GETDVI pads the unused portion of the
       buffer with null characters.

    Format

      SYS$GETDVI  [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr]

                  [,astprm] [,nullarg] [,pathname]

    C Prototype

      int sys$getdvi  (unsigned int efn, unsigned short int chan,

                      void *devnam, void *itmlst, struct _iosb *iosb,

                      void (*astadr)(__unknown_params), int astprm,

                      struct _generic_64 *nullarg,...);

136.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when $GETDVI returns the
    requested information. The efn argument is a longword containing
    this number; however, $GETDVI uses only the low-order byte.

    Upon request initiation, $GETDVI clears the specified event flag
    (or event flag 0 if efn was not specified). Then, when $GETDVI
    returns the requested information, it sets the specified event
    flag (or event flag 0).

    VSI strongly recommends the use of the EFN$C_ENF "no event flag"
    value as the event flag if you are not using an event flag to
    externally synchronize with the completion of this system service
    call. The $EFNDEF macro defines EFN$C_ENF. For more information,
    see the VSI OpenVMS Programming Concepts Manual.

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Number of the I/O channel assigned to the device about which
    information is desired. The chan argument is a word containing
    this number.

    To identify a device to $GETDVI, you can specify either the chan
    or devnam argument, but do not specify both. If you specify both
    arguments, the chan argument is used.

    If you specify neither chan nor devnam, $GETDVI uses a default
    value of 0 for chan.

 devnam

    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    The name of the device about which $GETDVI is to return
    information. The devnam argument is the address of a character
    string descriptor pointing to this name string.

    The device name string can be either a physical device name
    or a logical name. If the first character in the string is an
    underscore (_),  the string is considered a physical device name;
    otherwise, the string is considered a logical name and logical
    name translation is performed until either a physical device name
    is found or the system default number of translations has been
    performed.

    If the device name string contains a colon (:),  the colon and
    the characters that follow it are ignored.

    To identify a device to $GETDVI, you can specify either the chan
    or devnam argument, but do not specify both. If both arguments
    are specified, the chan argument is used.

    If you specify neither chan nor devnam, $GETDVI uses a default
    value of 0 for chan.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying which information about the device is to be
    returned. The itmlst argument is the address of a list of item
    descriptors, each of which describes an item of information. The
    list of item descriptors is terminated by a longword of 0.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block that is to receive the final completion status.
    The iosb argument is the address of the quadword I/O status
    block.

    When you specify the iosb argument, $GETDVI sets the quadword to
    0 upon request initiation. Upon request completion, a condition
    value is returned to the first longword; the second longword is
    Reserved to VSI.

    Though this 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 service to synchronize completion
       of the service, the I/O status block is a required argument
       for $SYNCH.

    o  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 $GETDVI service. The
       condition value returned in R0 gives you information about the
       success or failure of the service call itself; the condition
       value returned in the I/O status block gives you information
       about the success or failure of the service operation.
       Therefore, to accurately assess the success or failure of the
       call to $GETDVI, you must check the condition values returned
       in both R0 and the I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    AST service routine to be executed when $GETDVI 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 $GETDVI service.

 astprm

    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 is the longword
    parameter.

 nullarg

    OpenVMS usage:null_arg
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Placeholding argument Reserved to VSI.

 pathname

    OpenVMS usage:path_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    On Alpha and Integrity server systems, the name of the path about
    which $GETDVI is to return information. The pathname argument
    is the address of a character string descriptor pointing to this
    name string. The pathname can be used with either the chan or the
    devnam argument.

    Check the definitions of the item codes to see if the pathname
    argument is used. In general, item codes that return information
    that can vary by path make use of the pathname argument. Use
    the SHOW DEVICE /FULL command, the SYS$DEVICE_PATH_SCAN system
    service, or the F$MULTIPATH DCL lexical function to see the paths
    for a multipath device.

    If the pathname argument is used, it is validated against the
    existing paths for the device specified. If the path does not
    exist, the error SS$_NOSUCHPATH is returned, even if the item
    code or codes used do not make use of the pathname argument.

137  –  $GETDVIW

    Returns information about an I/O device; this information
    consists of primary and secondary device characteristics.

    The $GETDVIW service completes synchronously; that is, it returns
    to the caller with the requested information. VSI recommends that
    you use an IOSB with this service. An IOSB prevents the service
    from completing prematurely. In addition, the IOSB contains
    additional status information.

    For asynchronous completion, use the Get Device/Volume
    Information ($GETDVI) service; $GETDVI returns to the caller
    after queuing the information request, without waiting for the
    information to be returned. In all other respects, $GETDVIW
    is identical to $GETDVI. For all other information about the
    $GETDVIW service, see the description of $GETDVI.

                                   NOTE

       All pathname-related information pertains only to Alpha and
       Integrity server systems.

    Format

      SYS$GETDVIW  [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr]

                   [,astprm] [,nullarg,][pathname]

    C Prototype

      int sys$getdviw  (unsigned int efn, unsigned short int chan,

                       void *devnam, void *itmlst, struct _iosb

                       *iosb, void (*astadr)(__unknown_params), int

                       astprm, unsigned __int64 *nullarg,...);

138  –  $GETENV (Alpha Only)

    Returns the value(s) of the specified console environment
    variable(s).

    Format

      SYS$GETENV  itmlst

    C Prototype

      int sys$getenv  (void *itmlst);

138.1  –  Arguments

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    The itmlst argument is the address of a list of item descriptors,
    each of which describes an item of information. The list of item
    descriptors is terminated by a longword of 0.

    The service takes one argument as input, an item list. This item
    list has the following format for a single item descriptor:

    63                31                  0
    +-------------------------------------+
    |  Buffer length   |    Item code     | STENVDEF$L_ITEM_CODE/STENVDEF$L_BUF_LEN
    +-------------------------------------+
    |           Buffer address            | STENVDEF$Q_BUF_ADDR
    +-------------------------------------+
    |       Return length address         | STENVDEF$Q_RET_ADDR
    +-------------------------------------+

    The following table defines the item descriptor fields:

    Descriptor
    Field          Definition

    Item code      A longword indicating which environment variable
                   you want to retrieve. These codes are defined in
                   $STENVDEF.
    Buffer         A longword specifying the length of the buffer
    length         in which GETENV is to write the environment
                   variable's value.
    Buffer         A quadword indicating the address of the buffer
    address        in which GETENV is to write the environment
                   variable's value.
    Return         A quadword indicating the return address in
    length         which to put the length of the value that GETENV
    address        retrieved.

139  –  $GETJPI

    Returns information about one or more processes on the system or
    across the OpenVMS Cluster system.

    The $GETJPI service completes asynchronously. For synchronous
    completion, use the Get Job/Process Information and Wait
    ($GETJPIW) service.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$GETJPI  [efn] ,[pidadr] ,[prcnam] ,itmlst ,[iosb] ,[astadr]

                  ,[astprm]

    C Prototype

      int sys$getjpi  (unsigned int efn, unsigned int *pidadr, void

                      *prcnam, void *itmlst, struct _iosb *iosb, void

                      (*astadr)(__unknown_params), unsigned __int64

                      astprm);

139.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when $GETJPI returns the
    requested information. The efn argument is a quadword containing
    this number; however, $GETJPI uses only the low-order byte.

    Upon request initiation, $GETJPI clears the specified event flag
    (or event flag 0 if efn was not specified). Then, when $GETJPI
    returns the requested information, it sets the specified event
    flag (or event flag 0).

    VSI strongly recommends the use of the EFN$C_ENF "no event flag"
    value as the event flag if you are not using an event flag to
    externally synchronize with the completion of this system service
    call. The $EFNDEF macro defines EFN$C_ENF. For more information,
    see the VSI OpenVMS Programming Concepts Manual.

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by 32- or 64-bit reference
    Process identification (PID) of the process about which $GETJPI
    is to return information. The pidadr argument is the 32- or 64-
    bit address of a longword containing the PID. The pidadr argument
    can refer to a process running on the local node or a process
    running on another node in the cluster.

    If you give pidadr the value -1, $GETJPI assumes a wildcard
    operation and returns the requested information for each process
    on the system that it has the privilege to access, one process
    per call. To perform a wildcard operation, you must call $GETJPI
    in a loop, testing for the condition value SS$_NOMOREPROC after
    each call and exiting from the loop when SS$_NOMOREPROC is
    returned.

    If you use $GETJPI with $PROCESS_SCAN, you can perform wildcard
    searches across the cluster. In addition, with $PROCESS_SCAN
    you can search for specific processes based on many different
    selection criteria.

    You cannot abbreviate a PID. All significant digits of a PID must
    be specified; only leading zeros can be omitted.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the process about which $GETJPI is to return information.
    The prcnam argument is the 32- or 64-bit address of a character
    string descriptor pointing to this name string.

    A process running on the local node can be identified with a 1-
    to 15-character string. To identify a process on a cluster, you
    must specify the full process name, which includes the node name
    as well as the process name. The full process name can contain up
    to 23 characters.

    A local process name can look like a remote process name;
    therefore, if you specify ATHENS::SMITH, the system checks for
    a process named ATHENS::SMITH on the local node before checking
    node ATHENS for a process named SMITH.

    You can use the prcnam argument only if the process identified
    by prcnam has the same UIC group number as the calling process.
    If the process has a different group number, $GETJPI returns
    no information. To obtain information about processes in other
    groups, you must use the pidadr 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 specifying which information about the process or
    processes is to be returned. The itmlst argument is the 32-
    or 64-bit address of a list of item descriptors, each of which
    describes an item of information. An item list in 32-bit format
    is terminated by a longword of 0; an item list in 64-bit format
    is terminated by a quadword of 0. All items in an item list must
    be of the same format-either 32-bit or 64-bit.

    To view the item code diagrams and descriptor fields tables, see
    the VSI OpenVMS System Services Reference Manual.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    I/O status block that is to receive the final completion status.
    The iosb argument is the 32- or 64-bit address of the quadword
    I/O status block.

    When you specify the iosb argument, $GETJPI sets the quadword to
    0 upon request initiation. Upon request completion, a condition
    value is returned to the first longword; the second longword is
    reserved for future use.

    Though this 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 service to synchronize completion
       of the service, the I/O status block is a required argument
       for $SYNCH.

    o  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 $GETJPI service. The
       condition value returned in R0 gives you information about the
       success or failure of the service call itself; the condition
       value returned in the I/O status block gives you information
       about the success or failure of the service operation.
       Therefore, to accurately assess the success or failure of the
       call to $GETJPI, you must check the condition values returned
       in both R0 and the I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference
    AST service routine to be executed when $GETJPI completes. The
    astadr argument is the 32- or 64-bit address of this routine.

    If you specify astadr, the AST routine executes at the same
    access mode as the caller of the $GETJPI service.

 astprm

    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 is the longword
    parameter.

140  –  $GETJPIW

    Returns information about one or more processes on the system.

    The $GETJPIW service completes synchronously; that is, it returns
    to the caller with the requested information. VSI recommends that
    you use an IOSB with this service. An IOSB prevents the service
    from completing prematurely. In addition, the IOSB contains
    status information.

    For asynchronous completion, use the Get Job/Process Information
    ($GETJPI) service; $GETJPI returns to the caller after queuing
    the information request, without waiting for the information to
    be returned.

    In all other respects, $GETJPIW is identical to $GETJPI. For all
    other information about the $GETJPIW service, see the description
    of $GETJPI in this manual.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$GETJPIW  [efn] ,[pidadr] ,[prcnam] ,itmlst ,[iosb]

                   ,[astadr] ,[astprm]

    C Prototype

      int sys$getjpiw  (unsigned int efn, unsigned int *pidadr, void

                       *prcnam, void *itmlst, struct _iosb *iosb,

                       void (*astadr)(__unknown_params), int astprm);

141  –  $GETLKI

    Returns information about the lock database on a system.

    The $GETLKI service completes asynchronously; for synchronous
    completion, use the Get Lock Information and Wait ($GETLKIW)
    service.

    The $GETLKI, $GETLKIW, $ENQ, $ENQW, and $DEQ services together
    provide the user interface to the Lock Management facility.

    Format

      SYS$GETLKI  [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm]

                  [,nullarg]

    C Prototype

      int sys$getlki  (unsigned int efn, unsigned int *lkidadr,

                      void *itmlst, struct _iosb *iosb, void

                      (*astadr)(__unknown_params), int astprm,

                      unsigned int reserved);

141.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when $GETLKI completes. The
    efn argument is a longword containing this number; however,
    $GETLKI uses only the low-order byte. If you do not specify efn,
    $GETLKI sets event flag 0.

    VSI strongly recommends the use of the EFN$C_ENF "no event flag"
    value as the event flag if you are not using an event flag to
    externally synchronize with the completion of this system service
    call. The $EFNDEF macro defines EFN$C_ENF. For more information,
    see the VSI OpenVMS Programming Concepts Manual.

 lkidadr

    OpenVMS usage:lock_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Lock identification (lock ID) for the lock about which
    information is to be returned. The lock ID is the second longword
    in the lock status block, which was created when the lock was
    granted. The lkidadr argument is the address of this longword.

    If the value specified by lkidadr is 0 or -1, $GETLKI assumes
    a wildcard operation and returns information about each lock to
    which the calling process has access, one lock per call.

    To use the $GETLKI service, you must have read/write access to
    the lock ID.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying the lock information that $GETLKI is to
    return. The itmlst argument is the address of a list of item
    descriptors, each of which describes an item of information. The
    list of item descriptors is terminated by a longword of 0.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block that is to receive the final completion status.
    The iosb argument is the address of a quadword.

    When $GETLKI is called, it sets the I/O status block to 0. When
    $GETLKI completes, it writes a condition value to the first
    longword in the quadword. The remaining two words in the quadword
    are unused.

    Although this 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 service to synchronize completion
       of the service, the I/O status block is a required argument
       for $SYNCH.

    o  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 $GETLKI service. The
       condition value returned in R0 gives you information about the
       success or failure of the service call itself; the condition
       value returned in the I/O status block gives you information
       about the success or failure of the service operation.
       Therefore, to accurately assess the success or failure of the
       call to $GETLKI, you must check the condition values returned
       in both R0 and the I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    AST service routine to be executed when the service completes.
    The astadr argument is the address of this routine.

    If you specify this argument, the AST routine executes at the
    same access mode as the caller of the $GETLKI service.

 astprm

    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 is the longword
    parameter.

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument reserved by VSI.

142  –  $GETLKIW

    Returns information about the lock database on a system.

    The $GETLKIW service completes synchronously; that is, it returns
    to the caller with the requested information.

    For asynchronous completion, use the Get Lock Information
    ($GETLKI) service; $GETLKI returns to the caller after queuing
    the information request, without waiting for the information to
    be returned.

    In all other respects, $GETLKIW is identical to $GETLKI. For all
    other information about the $GETLKIW service, see the description
    of $GETLKI in this manual.

    The $GETLKI, $GETLKIW, $ENQ, $ENQW, and $DEQ services together
    provide the user interface to the Lock Management facility.

    Format

      SYS$GETLKIW  [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm]

                   [,nullarg]

    C Prototype

      int sys$getlkiw  (unsigned int efn, unsigned int *lkidadr,

                       void *itmlst, struct _iosb *iosb, void

                       (*astadr)(__unknown_params), int astprm,

                       unsigned int reserved);

143  –  $GETMSG

    Returns message text associated with a given message
    identification code into the caller's buffer. The message can
    be from the system message file or a user-defined message.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$GETMSG  msgid ,msglen ,bufadr ,[flags] ,[outadr]

    C Prototype

      int sys$getmsg  (unsigned int msgid, unsigned short int

                      *msglen, void *bufadr, unsigned int flags,

                      unsigned char outadr [4]);

143.1  –  Arguments

 msgid

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Identification of the message to be retrieved. The msgid argument
    is a longword value containing the message identification. Each
    message has a unique identification, contained in bits 3 through
    27 of system longword condition values.

 msglen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Length of the message string returned by $GETMSG. The msglen
    argument is the 32- or 64-bit address of a word into which
    $GETMSG writes this length.

 bufadr

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Buffer to receive the message string. The bufadr argument is the
    32- or 64-bit address of a character string descriptor pointing
    to the buffer into which $GETMSG writes the message string. The
    maximum size of any message string is 256 bytes.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Message components to be returned. The flags argument is a
    longword bit vector wherein a bit, when set, specifies that the
    message component is to be returned.

    The following table describes the significant bits:

    Bit  Value   Description

    0    1       Include text of message
         0       Do not include text of message
    1    1       Include message identifier
         0       Do not include message identifier
    2    1       Include severity indicator
         0       Do not include severity indicator
    3    1       Include facility name
         0       Do not include facility name

    If you omit this argument in a VAX MACRO or BLISS-32 service
    call, it defaults to a value of 15; that is, all flags are set
    and all components of the message are returned. If you omit this
    argument in a Fortran service call, it defaults to a value of 0;
    the value 0 causes $GETMSG to use the process default flags.

 outadr

    OpenVMS usage:vector_byte_unsigned
    type:         byte (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Optional information to be returned by $GETMSG. The outadr
    argument is the 32- or 64-bit address of a 4-byte array into
    which $GETMSG writes the following information:

    Byte   Contents

    0      Reserved
    1      Count of FAO arguments associated with message
    2      User-specified value in message, if any
    3      Reserved

144  –  $GETQUI

    Returns information about queues and the jobs initiated from
    those queues.

    The $GETQUI service completes asynchronously; for synchronous
    completion, use the Get Queue Information and Wait ($GETQUIW)
    service.

    For additional information about system service completion, see
    the Synchronize ($SYNCH) service.

    Format

      SYS$GETQUI  [efn] ,func [,context] [,itmlst] [,iosb] [,astadr]

                  [,astprm]

    C Prototype

      int sys$getqui  (unsigned int efn, unsigned short int func,

                      unsigned int *context, void *itmlst, struct

                      _iosb *iosb, void (*astadr)(__unknown_params),

                      int astprm);

144.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when $GETQUI completes. The
    efn argument is a longword containing this number; however,
    $GETQUI uses only the low-order byte. The efn argument is
    optional.

    When the request is queued, $GETQUI clears the specified event
    flag (or event flag 0 if efn was not specified). Then, when the
    operation completes, $GETQUI sets the specified event flag (or
    event flag 0).

    VSI strongly recommends the use of the EFN$C_ENF "no event flag"
    value as the event flag if you are not using an event flag to
    externally synchronize with the completion of this system service
    call. The $EFNDEF macro defines EFN$C_ENF. For more information,
    see the VSI OpenVMS Programming Concepts Manual.

 func

    OpenVMS usage:function_code
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Function code specifying the function that $GETQUI is to perform.
    The func argument is a word containing this function code. The
    $QUIDEF macro defines the names of each function code.

    You can specify only one function code in a single call to
    $GETQUI. Most function codes require or allow for additional
    information to be passed in the call. You pass this information
    by using the itmlst argument, which specifies a list of one or
    more item descriptors. Each item descriptor in turn specifies an
    item code, which either describes the specific information to be
    returned by $GETQUI, or otherwise affects the action designated
    by the function code.

    You can use wildcard mode to make a sequence of calls to $GETQUI
    to get information about all characteristics, form definitions,
    queues, or jobs contained in the system job queue file.

    For information on using wildcard mode, see the VSI OpenVMS System
    Services Reference Manual.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Address of a longword containing the number of a context stream
    for this call to the $GETQUI system service. If the argument is
    unspecified or 0, the service uses the default context stream
    (#0).

    To generate a new context stream, the specified longword must
    contain -1. $GETQUI then modifies the longword to hold the
    context number for that stream of operation. The context is
    marked with the caller's mode (user, supervisor, executive, or
    kernel). Any attempt to use that context in successive calls
    is checked and no call from a mode outside the recorded mode is
    allowed access.

    To clean up a context, make a $GETQUI call using the QUI$_CANCEL_
    OPERATION function code and specify the address of the context
    number as the context argument.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list supplying information to be used in performing 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 item descriptors, each of which contains an item code. The
    item list is terminated by an item code of 0 or by a longword of
    0.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block into which $GETQUI writes the completion status
    after the requested operation has completed. The iosb argument is
    the address of the I/O status block.

    At request initiation, $GETQUI sets the value of the quadword I/O
    status block to 0. When the requested operation has completed,
    $GETQUI writes a condition value in the first longword of the
    I/O status block. It writes the value 0 into the second longword;
    this longword is unused and reserved for future use.

    The condition values returned by $GETQUI in the I/O status block
    are condition values from the JBC facility, which are defined by
    the $JBCMSGDEF macro. The condition values returned from the JBC
    facility are listed in the section Condition Values Returned in
    the I/O Status Block section.

    Though this 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 service to synchronize completion
       of the service, the I/O status block is a required argument
       for $SYNCH.

    o  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 $GETQUI service. The
       condition value returned in R0 gives you information about the
       success or failure of the service call itself; the condition
       value returned in the I/O status block gives you information
       about the success or failure of the service operation.
       Therefore, to accurately assess the success or failure of the
       call to $GETQUI, you must check the condition values returned
       in both R0 and the I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    AST service routine to be executed when $GETQUI completes. The
    astadr argument is the address of this routine.

    If specified, the AST routine executes at the same access mode as
    the caller of $GETQUI.

 astprm

    OpenVMS usage:user_parm
    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 is this longword
    parameter.

145  –  $GETQUIW

    Returns information about queues and jobs initiated from those
    queues. The $SNDJBC service is the major interface to the Job
    Controller, which is the queue and accounting manager.

    The $GETQUIW service completes synchronously; that is, it returns
    to the caller with the requested information. For asynchronous
    completion, use the Get Queue Information ($GETQUI) service;
    $GETQUI returns to the caller after queuing the information
    request, without waiting for the information to be returned.

    In all other respects, $GETQUIW is identical to $GETQUI.

    For additional information about system service completion, see
    the Synchronize ($SYNCH) service.

    Format

      SYS$GETQUIW  [efn] ,func [,context] [,itmlst] [,iosb] [,astadr]

                   [,astprm]

    C Prototype

      int sys$getquiw  (unsigned int efn, unsigned short int func,

                       unsigned int *context, void *itmlst, struct

                       _iosb *iosb, void (*astadr)(__unknown_params),

                       int astprm);

146  –  $GETRMI

    Returns system performance information about the local system.
    $GETRMI is an asynchronous system service and requires the
    $SYNCH service or another wait-state synchronous mechanism to
    guarantee that the required information is available. There is no
    synchronous wait form for this system service.

    For additional information about system service completion, see
    the Synchronize ($SYNCH) service.

    Format

      SYS$GETRMI  [efn] [,nullarg] [,nullarg] ,itmlst [,iosb]

                  [,astadr] [,astprm]

    C Prototype

      int sys$getrmi  (unsigned int efn, unsigned int nullarg,

                      unsigned int nullarg, void *itmlst, struct

                      _iosb *iosb, void (*astadr)(__unknown_params),

                      int astprm);

146.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of event flag to be set when the $GETRMI request
    completes. The efn argument is a longword containing this number;
    however, $GETRMI uses only the low order byte.

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying which information is to be returned about
    the local node. The itmlst argument is the address of a list of
    item descriptors, each of which describes an item of information.
    The list of descriptors is terminated by a longword of 0.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block to receive the final completion status. The iosb
    argument is the address of the quadword I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    AST service routine to be executed when $GETRMI completes. The
    astadr argument is the address of this routine.

 astprm

    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.

147  –  $GETSYI

    Returns information about the local system or about other
    systems in an OpenVMS Cluster system. The $GETSYI service
    completes asynchronously; for synchronous completion, use the
    Get Systemwide Information and Wait ($GETSYIW) service.

    For additional information about system service completion, see
    the Synchronize ($SYNCH) service.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$GETSYI  [efn] ,[csidadr] ,[nodename] ,itmlst [,iosb]

                  [,astadr] [,astprm]

    C Prototype

      int sys$getsyi  (unsigned int efn, unsigned int *csidadr, void

                      *nodename, void *itmlst, struct _iosb *iosb,

                      void (*astadr)(__unknown_params), unsigned

                      __int64 astprm);

147.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when the $GETSYI request
    completes. The efn argument is a longword containing this number;
    however, $GETSYI uses only the low-order byte.

    Upon request initiation, $GETSYI clears the specified event
    flag (or event flag 0 if efn was not specified). Then, when the
    request completes, the specified event flag (or event flag 0) is
    set.

    VSI strongly recommends the use of the EFN$C_ENF "no event flag"
    value as the event flag if you are not using an event flag to
    externally synchronize with the completion of this system service
    call. The $EFNDEF macro defines EFN$C_ENF. For more information,
    see the VSI OpenVMS Programming Concepts Manual.

 csidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by 32- or 64-bit reference
    OpenVMS Cluster system identification of the node about which
    $GETSYI is to return information. The csidadr argument is the 32-
    or 64-bit address of a longword containing this identification
    value.

    The cluster-connection software assigns the OpenVMS Cluster
    system identification of a node. You can obtain this information
    by using the DCL command SHOW CLUSTER. The value of the cluster
    system identification for a node is not permanent; a new value is
    assigned to a node whenever it joins or rejoins the cluster.

    You can also specify a node to $GETSYI by using the nodename
    argument. If you specify csidadr, you need not specify nodename,
    and vice versa. If you specify both, they must identify the
    same node. If you specify neither argument, $GETSYI returns
    information about the local node; however, for wildcard
    operations, you must use the csidadr argument.

    If you specify csidadr as -1, $GETSYI assumes a wildcard
    operation and returns the requested information for each node in
    the cluster, one node per call. In this case, the program should
    test for the condition value SS$_NOMORENODE after each call to
    $GETSYI and should stop calling $GETSYI when SS$_NOMORENODE is
    returned.

 nodename

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the node about which $GETSYI is to return information.
    The nodename argument is the 32- or 64-bit address of a character
    string descriptor pointing to this name string.

    The node name string must contain from 1 to 15 characters and
    must correspond exactly to the node name; no trailing blanks or
    abbreviations are permitted.

    You can also specify a node to $GETSYI by using the csidadr
    argument. See the description of csidadr.

 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 specifying which information is to be returned about
    the node or nodes. The itmlst argument is the 32- or 64-bit
    address of a list of item descriptors, each of which describes an
    item of information. An item list in 32-bit format is terminated
    by a longword of 0; an item list in 64-bit format is terminated
    by a quadword of 0. All items in an item list must be of the same
    format-either 32-bit or 64-bit.

    To view the item code diagrams and descriptor fields tables, see
    the VSI OpenVMS System Services Reference Manual.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    I/O status block to receive the final completion status. The
    iosb argument is or the 32- or 64-bit address of the quadword I/O
    status block.

    When you specify the iosb argument, $GETSYI sets the quadword to
    0 upon request initiation. Upon request completion, a condition
    value is returned to the first longword; the second longword is
    reserved for future use.

    Though this 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 service to synchronize completion
       of the service, the I/O status block is a required argument
       for $SYNCH.

    o  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 $GETSYI service. The
       condition value returned in R0 gives you information about the
       success or failure of the service call itself; the condition
       value returned in the I/O status block gives you information
       about the success or failure of the service operation.
       Therefore, to accurately assess the success or failure of the
       call to $GETSYI, you must check the condition values returned
       in both R0 and the I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference
    AST service routine to be executed when $GETSYI completes. The
    astadr argument is the 32- or 64-bit address of this routine.

    If you specify astadr, the AST routine executes at the same
    access mode as the caller of the $GETSYI service.

 astprm

    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 is the longword
    parameter.

148  –  $GETSYIW

    Returns information about the local system or about other systems
    in a cluster.

    The $GETSYIW service completes synchronously; that is, it returns
    to the caller with the requested information. For asynchronous
    completion, use the Get Systemwide Information ($GETSYI) service;
    $GETSYI returns to the caller after queuing the information
    request, without waiting for the information to be returned. In
    all other respects, these services are identical; For information
    about the $GETSYIW service, see the documentation about $GETSYI.

    Format

      SYS$GETSYIW  [efn] ,[csidadr] ,[nodename] ,itmlst [,iosb]

                   [,astadr] [,astprm]

    C Prototype

      int sys$getsyiw  (unsigned int efn, unsigned int *csidadr, void

                       *nodename, void *itmlst, struct _iosb *iosb,

                       void (*astadr)(__unknown_params), int astprm);
    You must specify either the csidadr or the nodename argument,
    but not both. For wildcard operations, however, you must use the
    csidadr argument.

149  –  $GETTIM

    Returns the current system time in a 64-bit format.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$GETTIM  timadr,[flags]

    C Prototype

      int sys$gettim  (struct _generic_64 *timadr,...);

149.1  –  Arguments

 timadr

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit address of a quadword to receive the current
    time in 64-bit format.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value (Alpha and Integrity servers)
    An optional argument that modifies the form of the returned
    time value. If this argument is not specified, it is same as
    specifying an argument of 0.

150  –  $GETTIM PREC

    Returns the current high precision system time in a 64-bit
    format.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$GETTIM_PREC  timadr

    C Prototype

      int sys$gettim_prec  (struct _generic_64 *timadr);

150.1  –  Argument

 timadr

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 64-bit reference
    The 64-bit address of a quadword to receive the current time in
    64-bit format.

151  –  $GETUAI

    Returns authorization information about a specified user.

    Format

      SYS$GETUAI  [nullarg] ,[contxt] ,usrnam ,itmlst ,[nullarg]

                  ,[nullarg] ,[nullarg]

    C Prototype

      int sys$getuai  (unsigned int efn, unsigned int *contxt, void

                      *usrnam, void *itmlst, struct _iosb *iosb, void

                      (*astadr)(__unknown_params), int astprm);

151.1  –  Arguments

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

 contxt

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    An optional longword used to maintain an open channel to the
    authorization file. The contxt argument is the address of a
    longword to receive a $GETUAI context value. If the contxt
    argument is specified on the initial call, this longword should
    contain the value -1, and on subsequent calls, the value of the
    contxt argument from the previous call should be passed back in.

 usrnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the user about whom $GETUAI returns authorization
    information. The usrnam argument is the address of a descriptor
    pointing to a character text string containing the user name.
    The user name string can contain a maximum of 12 alphanumeric
    characters.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying which information from the specified user's
    user authorization file (UAF) record is to be returned. The
    itmlst argument is the address of a list of one or more item
    descriptors, each of which specifies an item code. The item list
    is terminated by an item code value of 0 or by a longword value
    of 0.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

 nullarg

    OpenVMS usage:nullarg
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    Placeholding argument Reserved to VSI.

 nullarg

    OpenVMS usage:nullarg
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    Placeholding argument Reserved to VSI.

 nullarg

    OpenVMS usage:nullarg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

152  –  $GETUTC

    Returns the current time in 128-bit UTC format.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$GETUTC  utcadr

    C Prototype

      int sys$getutc  (unsigned int *utcadr [4]);

152.1  –  Arguments

 utcadr

    OpenVMS usage:coordinated universal time
    type:         utc_date_time
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers);
    The 128-bit time value to be returned.

153  –  $GET ALIGN FAULT DATA (Alpha and Integrity servers)

    On Alpha and Integrity server systems, obtains data from the user
    image alignment fault buffer if buffered user alignment fault
    data reporting has been enabled.

    This service accepts 64-bit addresses.

    Format

      SYS$GET_ALIGN_FAULT_DATA  buffer ,buffer_size ,return_size

    C Prototype

      int sys$get_align_fault_data  (void *buffer, int buffer_size,

                                    int *return_size);

153.1  –  Arguments

 buffer

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read/write
    mechanism:    by 32- or 64-bit reference
    The user buffer in which the alignment fault data is to be
    stored. The buffer is the 32- or 64-bit address of this user
    buffer.

 buffer_size

    OpenVMS usage:byte count
    type:         longword (signed)
    access:       read
    mechanism:    by value
    The size, in bytes, of the buffer specified by the buffer
    argument.

 return_size

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write
    mechanism:    by 32- or 64-bit reference
    The amount of data, in bytes, stored in the buffer. The return_
    size argument is the 32- or 64-bit address of a naturally aligned
    longword into which the service returns the size of the buffer.
    The return_size is set to 0 if there is no data in the buffer.

154  –  $GET ARITH EXCEPTION (Alpha only)

    On Alpha systems, returns information about the exception context
    for a given arithmetic exception. There are two forms the signal
    argument vectors: one for use with 32-bit addresses and one for
    use with 64-bit addresses.

    For more information, see the section "Signal Argument Vector" in
    the VSI OpenVMS Calling Standard.

    Format

      SYS$GET_ARITH_EXCEPTION  sigarg ,mcharg ,buffer

    C Prototype

      int sys$get_arith_exception  (void *sigarg, void *mcharg, void

                                   *buffer);

154.1  –  Arguments

 sigarg

    OpenVMS usage:signal array
    type:         vector_longword_signed
    access:       read only
    mechanism:    by reference
    Address of the signal array for the given arithmetic exception.

 mcharg

    OpenVMS usage:mech array
    type:         vector_quadword_unsigned
    access:       read only
    mechanism:    by reference
    Address of the mechanism array for the given arithmetic
    exception.

 buffer

    OpenVMS usage:vector_quadword
    type:         vector_quadword_unsigned
    access:       write only
    mechanism:    by descriptor
    Four-quadword buffer to receive additional exception context.
    The buffer argument is the address of a descriptor that points to
    this buffer.

155  –  $GET DEFAULT TRANS

    Returns the default transaction of the calling process.

    Format

      SYS$GET_DEFAULT_TRANS  tid

    C Prototype

      int sys$get_default_trans  (unsigned int tid [4]);

155.1  –  Arguments

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of an octaword in which the identifier (TID) of the
    default transaction of the calling process is returned.

156  –  $GET GALAXY LOCK INFO (Alpha Only)

    Returns "interesting" fields from the specified lock.

    Note that this system service is supported only in an OpenVMS
    Alpha Galaxy environment. For more information about programming
    with OpenVMS Galaxy system services, refer to the VSI OpenVMS
    Alpha Partitioning and Galaxy Guide.

    Format

      SYS$GET_GALAXY_LOCK_INFO  handle ,name ,timeout ,size ,ipl

                                ,rank ,flags [,name_length]

    C Prototype

      int sys$get_galaxy_lock_info  (unsigned __int64 lock_handle,

                                    char *name, unsigned int

                                    *timeout, unsigned int *size,

                                    unsigned int *ipl, unsigned int

                                    *rank, unsigned short int *flags

                                    unsigned short int *name_length);

156.1  –  Arguments

 handle

    OpenVMS usage:handle for the galaxy lock
    type:         quadword (unsigned)
    access:       read
    mechanism:    input by value
    The 64-bit lock handle that identifies the lock on which to
    return information. This value is returned by SYS$CREATE_GALAXY_
    LOCK.

 name

    OpenVMS usage:address
    type:         zero-terminated string
    access:       write
    mechanism:    output by reference
    Pointer to a buffer. This buffer must be large enough to receive
    the name of the lock. Locks names are zero-terminated strings
    with a maximum size of 16 bytes.

 timeout

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write
    mechanism:    output by reference
    Pointer to a longword. The value returned is the timeout value of
    the lock.

 size

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write
    mechanism:    output by reference
    Pointer to a longword. The value returned is the size of the lock
    in bytes.

 ipl

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write
    mechanism:    output by reference
    Pointer to a longword. The value returned is the IPL of the lock.

 rank

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write
    mechanism:    output by reference
    Pointer to a longword. The value returned is the rank of the
    lock.

 flags

    OpenVMS usage:address
    type:         word (unsigned)
    access:       write
    mechanism:    output by reference
    Pointer to a word. The value returned is the word mask of lock
    flags.

 name_length

    OpenVMS usage:address
    type:         word (unsigned)
    access:       write
    mechanism:    output by reference
    Length of the string returned in the name argument.

157  –  $GET GALAXY LOCK SIZE (Alpha Only)

    Returns the minimum and maximum size of an OpenVMS Galaxy lock.

    Note that this system service is supported only in an OpenVMS
    Alpha Galaxy environment.

    For more information about programming with OpenVMS Galaxy system
    services, refer to the VSI OpenVMS Alpha Partitioning and Galaxy
    Guide.

    Format

      SYS$GET_GALAXY_LOCK_SIZE  min_size ,max_size

    C Prototype

      int sys$get_galaxy_lock_size  (unsigned int *min_size, unsigned

                                    int *max_size);

157.1  –  Arguments

 min_size

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write
    mechanism:    output by reference
    Pointer to a longword. The value returned is minimum legal size
    of a galaxy lock structure.

 max_size

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write
    mechanism:    output by reference
    Pointer to a longword. The value returned is maximum legal size
    of a galaxy lock structure.

158  –  $GET REGION INFO (Alpha and Integrity servers)

    On Alpha and Integrity server systems, gets information about a
    specified virtual region.

    This service accepts 64-bit addresses.

    Format

      SYS$GET_REGION_INFO  function_code ,region_id_64 ,start_va_64

                           ,nullarg ,buffer_length ,buffer_address_64

                           ,return_length_64

    C Prototype

      int sys$get_region_info  (unsigned int function_code, struct

                               _generic_64 *region_id_64, void

                               *start_va_64, void *reserved,

                               unsigned int buffer_length, void

                               *buffer_address_64, unsigned int

                               *return_length_64);

158.1  –  Arguments

 function_code

    OpenVMS usage:function code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Function code specifying how the information you are requesting
    should be looked up. All function codes return region summary
    information in the return buffer in the format of the Region
    Summary Buffer. The Region Summary Buffer format is shown in the
    table in the buffer_address_64 argument.

    If less buffer space is specified than the length of the Region
    Summary Buffer, only the amount of information requested is
    returned. If more buffer space is specified than the length of
    the Region Summary Buffer, the service will fill in the buffer.
    The return length will reflect the amount of useful information
    written to the buffer, the size of the Region Summary Buffer.

    The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in
    STARLET.MLB define a symbolic name for each function code.

    The following function codes are defined:

    Symbolic Name        Description

    VA$_REGSUM_BY_ID     Return the region summary information for
                         the region whose ID is specified in the
                         region_id_64 argument.
    VA$_REGSUM_BY_VA     Return the region summary information for
                         the region that contains the virtual address
                         specified in the start_va_64 argument.
    VA$_NEXT_REGSUM_     Return the region summary information for
    BY_VA                the region containing the starting address.
                         If the starting address is not in a region,
                         return the region summary information for
                         the next region with a starting address
                         higher than the specified address.

                         Note: For the VA$_NEXT_REGSUM_BY_VA
                         function, OpenVMS checks for a start_va_64
                         argument in the inaccessible address range
                         in P2 space. If it finds one, OpenVMS
                         adjusts the address to account for the
                         discontinuity. For more information about
                         the layout of the 64-bit virtual address
                         space, see the VSI OpenVMS Programming
                         Concepts Manual.

                         This function code can be used for wildcard
                         operations. See the description of the
                         start_va_64 argument for information on how
                         to program a wildcard operation on regions.

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region about which information
    is requested. This argument is read only if the function code
    VA$_REGSUM_BY_ID is specified.

    The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in
    STARLET.MLB define a symbolic name for each of the three default
    regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified.

 start_va_64

    OpenVMS usage:input address
    type:         quadword address
    access:       read only
    mechanism:    by value
    Virtual address associated with region about which information
    is requested. This argument is read only if the function_code
    argument is VA$_REGSUM_BY_VA or VA$_NEXT_REGSUM_BY_VA.

    If the function_code argument is VA$_REGSUM_BY_VA, this argument
    is a virtual address within the region about which you are
    requesting information.

    To perform a wildcard search on all regions, specify VA$_
    NEXT_REGSUM_BY_VA as the function code and begin with the
    start_va_64 argument specified as -1. For subsequent calls,
    specify start_va_64 as the sum of the previous region's start
    address and length. Call the $GET_REGION_INFO service in a loop
    until the condition SS$_NOMOREREG is returned.

                                   NOTE

       Before performing the lookup function, OpenVMS sign-extends
       the 64-bit starting address so that it represents a properly
       formed virtual address for the CPU.

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

 buffer_length

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the buffer into which information is returned.

 buffer_address_64

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a quadword-aligned buffer
    into which to return information if the buffer_length argument is
    nonzero.

    This argument is ignored if the buffer_length argument is zero.

    The following table shows the format of the Region Summary
    Buffer:

    Table SYS-20 Region Summary Buffer Format

                                               Field
                                               Size    Field Offset
    Field name           Meaning               (Bytes) (Decimal)

    VA$L_FLAGS           Flags used when       4       8
                         region was created
    VA$L_REGION_         Create and owner      4       12
    PROTECT              mode of region
    VA$Q_REGION_ID       Region identifier     8       0
    VA$PQ_START_VA       Starting (lowest)     8       16
                         virtual address of
                         region
    VA$Q_REGION_SIZE     Total length of       8       24
                         region
    VA$PQ_FIRST_FREE_    First free virtual    8       32
    VA                   address in region
    VA$C_REGSUM_LENGTH   Length of Region      constant 40
                         Summary Buffer

    The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF MACRO in
    STARLET.MLB define the REGSUM structure.

 return_length_64

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned longword
    into which the service returns the length of the information in
    bytes.

159  –  $GET SECURITY

    Retrieves the security characteristics of an object.

    Format

      SYS$GET_SECURITY  [clsnam] ,[objnam] ,[objhan] ,[flags]

                        ,[itmlst] ,[contxt] ,[acmode]

    C Prototype

      int sys$get_security  (void *clsnam, void *objnam, unsigned

                            int *objhan, unsigned int flags, void

                            *itmlst, unsigned int *contxt, unsigned

                            int *acmode);

159.1  –  Arguments

 clsnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Name of the object class. The clsnam argument is the address of a
    descriptor pointing to a string containing the name of the object
    class.

    The following is a list of protected object class names:

       CAPABILITY
       COMMON_EVENT_CLUSTER
       DEVICE
       FILE
       GLXSYS_GLOBAL_SECTION
       GLXGRP_GLOBAL_SECTION
       GROUP_GLOBAL_SECTION
       ICC_ASSOCIATION
       LOGICAL_NAME_TABLE
       QUEUE
       RESOURCE_DOMAIN
       SECURITY_CLASS
       SYSTEM_GLOBAL_SECTION
       VOLUME

 objnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Name of the protected object whose associated security profile
    is going to be retrieved. The objnam argument is the address
    of a descriptor pointing to a string containing the name of the
    protected object.

    The format of an object name is class specific. The following
    table lists object names and describes their formats:

    Object Class        Object Name Format

    CAPABILITY          A character string. Currently, the only
                        capability object is VECTOR.
    COMMON_EVENT_       Name of the event flag cluster, as defined
    CLUSTER             in the Associate Common Event Flag Cluster
                        ($ASCEFC) system service.
    DEVICE              Standard device specification, described in
                        the OpenVMS User's Manual.
    FILE                Standard file specification, described in the
                        OpenVMS User's Manual.
    GROUP_GLOBAL_       Section name, as defined in the Create and
    SECTION             Map Section ($CRMPSC) system service.
    ICC_ASSOCIATION     ICC security object name node::association_
                        name. The special node name, ICC$::, refers
                        to entries in the clusterwide registry. For
                        registry entries, the Access Access Type does
                        not apply.
    LOGICAL_NAME_TABLE  Table name, as defined in the Create Logical
                        Name Table ($CRELNT) system service.
    QUEUE               Standard queue name, as described in the Send
                        to Job Controller ($SNDJBC) system service.
    RESOURCE_DOMAIN     An identifier or octal string enclosed in
                        brackets.
    SECURITY_CLASS      Any class name shown in column 1, or a
                        class name followed by a period (.) and
                        the template name. Use the DCL command SHOW
                        SECURITY to display possible template names.
    SYSTEM_GLOBAL_      Section name, as defined in the Create and
    SECTION             Map Section ($CRMPSC) system service.
    VOLUME              Volume name or name of the device on which
                        the volume is mounted.

 objhan

    OpenVMS usage:object_handle
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Data structure identifying the object whose associated
    characteristics are going to be retrieved. The objhan argument
    is an address of a longword containing the object handle. You can
    use the objhan argument as an alternative to the objnam argument;
    for example, channel number clearly specifies the file open on
    the channel and can serve as an object handle.

    The following table shows the format of the object classes:

    Object Class           Object Handle Format

    COMMON_EVENT_CLUSTER   Event flag number
    DEVICE                 Channel number
    FILE                   Channel number
    RESOURCE_DOMAIN        Resource domain identifier
    VOLUME                 Channel number

 flags

    OpenVMS usage:flags
    type:         mask_longword
    access:       read only
    mechanism:    by value
    Mask specifying processing options. The flags argument is a
    longword bit vector wherein a bit, when set, specifies the
    processing option. The flags argument requires the contxt
    argument.

    The following table describes each flag:

    Symbolic Name   Description

    OSS$M_RELCTX    Release the context structure at the completion
                    of this request.

    OSS$M_WLOCK     Maintain a write lock on the security profile
                    at the completion of this request. $GET_SECURITY
                    ignores the flag if the context has already been
                    established.

    These symbolic names are defined in the $OSSDEF macro. You
    construct the flags argument by specifying the symbolic names
    of each flag.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying which information about the process or
    processes is to be returned. The itmlst argument is the address
    of a list of item descriptors, each of which describes an item
    of information. The list of item descriptors is terminated by a
    longword of 0.

    With the item list, the user retrieves the protected object's
    characteristics. The user defines which security characteristics
    to retrieve. If this argument is not present, only the flags
    argument is processed. Without the itmlst argument, you can only
    manipulate the security profile lock or release contxt resources.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

 contxt

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value used to maintain the processing context when dealing with
    a single protected object across multiple $GET_SECURITY/$SET_
    SECURITY calls. Whenever the context value is nonzero, the class
    name, object name, or object handle arguments are disregarded.
    An input value of 0 indicates that a new context should be
    established.

    Because an active context block consumes process memory, be sure
    to release the context block by setting the RELCTX flag when the
    profile processing is complete. $GET_SECURITY sets the context
    argument to 0 once the context is released.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Access mode to be used in the object protection check. The acmode
    argument is the address of a longword containing the access mode.
    The acmode argument defaults to kernel mode; however, the system
    compares acmode with the caller's access mode and uses the least
    privileged mode. The access modes are defined in the system macro
    $PSLDEF library. VSI recommends that this argument be omitted
    (passed as zero).

160  –  $GET SYS ALIGN FAULT DATA (Alpha and Integrity servers)

    On Alpha and Integrity server systems, obtains data from the
    system alignment fault buffer if buffered system alignment fault
    data reporting has been enabled.

    This service accepts 64-bit addresses.

    Format

      SYS$GET_SYS_ALIGN_FAULT_DATA  buffer ,buffer_size ,return_size

    C Prototype

      int sys$get_sys_align_fault_data  (void *buffer, int

                                        buffer_size, int

                                        *return_size);

160.1  –  Arguments

 buffer

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read/write
    mechanism:    by 32- or 64-bit reference
    The user buffer in which the alignment fault data is to be
    stored. The buffer argument is the 32- or 64-bit virtual address
    of this buffer.

 buffer_size

    OpenVMS usage:byte count
    type:         longword (signed)
    access:       read
    mechanism:    by value
    The size, in bytes, of the buffer specified by the buffer
    argument.

 return_size

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write
    mechanism:    by 32- or 64-bit reference
    The amount of data, in bytes, stored in the buffer. The return_
    size argument is the 32- or 64-bit virtual address of a naturally
    aligned longword into which the service returns the amount of
    data, in bytes, stored in the buffer. The return_size argument is
    set to 0 if there is no data in the buffer.

161  –  $GET UNWIND ENTRY INFO (Integrity servers Only)

    Gets fixed-up unwind entry information.

    Format

      SYS$GET_UNWIND_ENTRY_INFO  pc, get_ue_block, name

    C Prototype

      int SYS$GET_UNWIND_ENTRY_INFO  (unsigned __int64 pc, void

                                     *get_ue_block, void *name);

161.1  –  Arguments

 pc

    OpenVMS usage: PC value
    type:          quadword (unsigned)
    access:        read only
    mechanism:     by value
    Input quadword, target PC (that is, the PC for a code region the
    user wants unwind information for).

 get_ue_block

    OpenVMS usage: unwind_entry_data_block
    type:          quadword (unsigned)
    access:        write
    mechanism:     by reference
    Address of a 4-quadword block to be filled in. That is, input the
    address of a 4 quadword block and, on successful returned status,
    that block will be updated with the following information:

    o  code_start_va - Output quadword, the process virtual starting
       c unwind region containing the input IP.

    o  code_end_va - Output quadward, the process virtual ending code
       address of the unwind region containing the input IP.

    o  uib_start_va - Output quadword, the process virtual address of
       the UIB for the unwind region containing the input IP.

    o  gp_value - Output quadword, the GP value for this code region.

 name

    OpenVMS usage: pseudo-image-name
    type:          character-code-text-string
    access:        modify
    mechanism:     by descriptor-fixed-length string descriptor
    Optional, that is, may be zero. If the name parameter is
    specified and if a name was registered for the unwind region,
    then the descriptor pointer and length are updated to point to
    that stored name. Note that if the name parameter is specified
    but no name exists in the unwind tables, then the name descriptor
    is updated to zero length.

162  –  $GET USER CAPABILITY (Alpha and Integrity servers)

    On Alpha and Integrity server systems, reserves a user
    capability, indicating to other processes that the resource is
    in use.

    This service accepts 64-bit addresses.

    Format

      SYS$GET_USER_CAPABILITY   cap_num [,select_num] [,select_mask]

                                [,prev_mask] [,flags]

    C Prototype

      int sys$get_user_capability  (*cap_num, int *select_num, struct

                                   _generic_64 *select_mask, struct

                                   _generic_64 *prev_mask, struct

                                   _generic_64 *flags);

162.1  –  Arguments

 cap_num

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Capability number to be reserved by the calling kernel thread.
    This number can range from 1 to 16 for an explicit request, or
    the symbolic constant CAP$K_GET_FREE_CAP can be specified to
    get the next available user capability. The cap_num argument is
    the 32- or 64-bit address of the longword containing the user
    capability number or symbolic constant.

 select_num

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The number of the user capability selected by the service
    call. The select_num argument is the 32- or 64-bit address of
    a longword into which the system writes the user capability
    number. For an explicit numeric request, the value returned in
    this longword will match that specified in cap_num; otherwise,
    this cell contains the next available user capability.

 select_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    A quadword bit mask with a single bit position set, reflecting
    the user capability selected by the service. The select_
    mask argument is the 32- or 64-bit address of a quadword into
    which the system writes the selected user capability bit mask.
    This bit mask is the most efficient method for indicating the
    reserved user capability with the $CPU_CAPABILITIES and $PROCESS_
    CAPABILITIES services.

 prev_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The previous user capability reservation mask before execution
    of this service call. The prev_mask argument is the 32- or 64-bit
    address of a quadword into which the service writes a quadword
    bit mask specifying the previously reserved user capabilities
    taken from the global cell SCH$GQ_RESERVED_USER_CAPS.

 flags

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Options selected for the user capability reservation. The flags
    argument is a quadword bit vector wherein a bit corresponds to an
    option.

    Each option (bit) has a symbolic name, which the $CAPDEF macro
    defines. The flags argument is constructed by performing a
    logical OR operation using the symbolic names of each desired
    option.

    At this time, all bits are Reserved to VSI and must be 0.

163  –  $GOTO UNWIND (Alpha Only)

    On Alpha systems, unwinds the call stack. On Integrity server
    systems, do not use this service; use $GOTO_UNWIND_64 instead.

    Format

      SYS$GOTO_UNWIND  target_invo ,target_pc ,[new_r0] ,[new_r1]

    C Prototype

      int sys$goto_unwind  (void *target_invo, void *(*(target_pc)),

                           unsigned __int64 *new_r0, unsigned

                           __int64 *new_r1);

163.1  –  Arguments

 target_invo

    OpenVMS usage:invo_handle
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    The address of a location that contains a handle for the target
    invocation.

    If you do not specify the target_invo argument, or if the handle
    value is 0, an exit unwind is initiated.

 target_pc

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    The address of a location that contains the address at which
    execution should continue in the target invocation.

    If the target_pc argument is omitted or the value is 0, a system-
    defined target PC is assumed and execution resumes at the
    location specified at the return address for the call frame of
    the target procedure invocation.

 new_r0

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    The address of a location that contains the value to place in the
    saved R0 location of the mechanism argument vector. The contents
    of this location are then loaded into the processor R0 register
    at the time that execution continues in the target invocation.

    If the new_r0 argument is omitted, the contents of the processor
    R0 register at the time of the call to $GOTO_UNWIND are used.

 new_r1

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a location that contains the value to place in the
    saved R1 location of the mechanism argument vector. The contents
    of the location are then loaded into the processor R1 register at
    the time that execution continues in the target invocation.

    If the new_r1 argument is omitted, the contents of the processor
    R1 register at the time of the call to $GOTO_UNWIND are used.

164  –  $GOTO UNWIND 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, unwinds the call stack.

    Format

      SYS$GOTO_UNWIND  target_invo ,target_pc ,[NewRetVal] ,

                       [NewRetVal2]

    C Prototype

      int sys$goto_unwind_64  (void *target_invo_64, void

                              *(*(target_pc_64)), unsigned_int64

                              *new_retval, unsigned_int64

                              *newretval2);

164.1  –  Arguments

 target_invo

    OpenVMS usage:invo_handle
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    The address of a location that contains a handle for the target
    invocation.

    If you do not specify the target_invo argument, or if the handle
    value is 0, the effect of the call is undefined.

 target_pc

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    The address of a location that contains the address at which
    execution should continue in the target invocation.

    If the target_pc argument is omitted or the value is 0, execution
    resumes at the location specified at the return address for the
    call frame of the target procedure invocation.

    If the target_invo argument is omitted or the value is 0, the
    target_pc argument is ignored. In this case, a system-defined
    target PC is assumed.

 NewRetVal

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    The address of a location that contains the value to place in
    the saved RetVal location of the mechanism argument vector. The
    contents of this location are then loaded into RetVal at the time
    that execution continues in the target invocation.

    If the NewRetVal argument is omitted, the contents of RetVal at
    the time of the call to $GOTO_UNWIND_64 are used.

    This argument is called New_R0 in SYS$GOTO_UNWIND for
    compatibility with Alpha.

 NewRet2

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    The address of a location that contains the value to place in
    the saved RetVal2 location of the mechanism argument vector. The
    contents of the location are then loaded into RetVal2 at the time
    that execution continues in the target invocation.

    If the NewRet2 argument is omitted, the contents of RetVal2 at
    the time of the call to $GOTO_UNWIND_64 are used.

    This argument is called New_R1 in SYS$GOTO_UNWIND for
    compatibility with Alpha.

165  –  $GRANTID

    Adds the specified identifier record to the rights list of the
    process or the system.

    Format

      SYS$GRANTID  [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]

    C Prototype

      int sys$grantid  (unsigned int *pidadr, void *prcnam, struct

                       _generic_64 *id, void *name, unsigned int

                       *prvatr, unsigned int segment);

165.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) number of the process affected when
    $GRANTID completes execution. The pidadr argument is the address
    of a longword containing the PID of the process to be affected.
    You use -1 to indicate the system rights list. When pidadr is
    passed, it is also returned; therefore, you must pass it as a
    variable rather than a constant. If you specify neither pidadr
    nor prcnam, your own process is used.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Process name on which $GRANTID operates. The prcnam argument
    is the address of a character string descriptor containing the
    process name. The maximum length of the name is 15 characters.
    Because the UIC group number is interpreted as part of the
    process name, you must use pidadr to specify the rights list
    of a process in a different group. If you specify neither pidadr
    nor prcnam, your own process is used.

 id

    OpenVMS usage:rights_holder
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference
    Identifier and attributes to be granted when $GRANTID completes
    execution. The id argument is the address of a quadword
    containing the binary identifier code to be granted in the first
    longword and the attributes in the second longword.

    Use the id argument to modify the attributes of the identifier.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The following symbols
    for each bit position are defined in the macro library ($KGBDEF):

    Bit Position           Meaning When Set

    KGB$V_DYNAMIC          Allows holders of the identifier to remove
                           it from or add it to the process rights
                           database using the DCL command SET RIGHTS_
                           LIST.
    KGB$V_NOACCESS         Makes any access rights of the identifier
                           null and void. This attribute is intended
                           as a modifier for a resource identifier or
                           the Subsystem attribute.
    KGB$V_RESOURCE         Allows holders of an identifier to charge
                           disk space to the identifier. It is used
                           only for file objects.
    KGB$V_SUBSYSTEM        Allows holders of the identifier to
                           create and maintain protected subsystems
                           by assigning the Subsystem ACE to the
                           application images in the subsystem.

    You must specify either id or name. Because the id argument is
    returned as well as passed if you specify name, you must pass it
    as a variable rather than a constant in this case.

 name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the identifier granted when $GRANTID completes execution.
    The name argument is the address of a descriptor pointing to
    the name of the identifier. The identifier is granted as it is
    created. You must specify either id or name.

 prvatr

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Previous attributes of the identifier. The prvatr argument is
    the address of a longword used to store the attributes of the
    identifier if it was previously present in the rights list. If
    you added rather than modified the identifier, prvatr is ignored.

166  –  $HASH PASSWORD

    Applies the hash algorithm you select to an ASCII password string
    and returns a quadword hash value that represents the encrypted
    password.

    Format

      SYS$HASH_PASSWORD  pwd ,alg ,[salt] ,usrnam ,hash

    C Prototype

      int sys$hash_password  (void *pwd, unsigned char alg, unsigned

                             short int salt, void *usrnam, struct

                             _generic_64 *hash);

166.1  –  Arguments

 pwd

    OpenVMS usage: char_string
    type:          character-coded text string
    access:        read only
    mechanism:     by descriptor-fixed-length string descriptor
    ASCII password string to be encrypted. The pwd argument is the
    address of a character string descriptor pointing to the ASCII
    password. The password string can contain between 1 and 32
    characters and use the uppercase characters A through Z, the
    numbers 0 through 9, the dollar sign ($),  and the underscore
    (_).

    The caller must validate the password string before calling
    $HASH_PASSWORD to ensure that only permitted characters are
    included.

 alg

    OpenVMS usage: byte_unsigned
    type:          byte (unsigned)
    access:        read only
    mechanism:     by value
    Algorithm used to hash the ASCII password string. The alg
    argument is an unsigned byte specifying the hash algorithm.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the table of recognized algorithms.

    Values ranging from 128 to 255 are reserved for customer use; the
    constant UAI$K_CUST_ALGORITHM defines the start of this range.

    You can use the UAI$_ENCRYPT and UAI$_ENCRYPT2 item codes with
    the $GETUAI system service to retrieve the primary and secondary
    password hash algorithms for a user.

 salt

    OpenVMS usage: word_unsigned
    type:          word (unsigned)
    access:        read only
    mechanism:     by value
    Value used to increase the effectiveness of the hash. The salt
    argument is an unsigned word containing 16 bits of data that is
    used by the hash algorithms when encrypting a password for the
    associated user name. The $GETUAI item code UAI$_SALT is used to
    retrieve the SALT value for a given user. If you do not specify a
    SALT value, $HASH_PASSWORD uses the value of 0.

 usrnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the user associated with the password. The usrnam
    argument is the address of a descriptor pointing to a character
    text string containing the user name. The current password
    encryption algorithm (UAI$C_PURDY_S) folds the user name into
    the ASCII password string to ensure that different users with the
    same password produce different hash values. This argument must
    be supplied for all calls to $HASH_PASSWORD but is ignored when
    using the CRC algorithm (UAI$C_AD_II).

 hash

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    Output hash value representing the encrypted password. The hash
    argument is the address of an unsigned quadword to which $HASH_
    PASSWORD writes the output of the hash. If you use the UAI$C_AD_
    II algorithm, the second longword of the hash is always set to 0.

167  –  $HIBER

    Allows a process to make itself inactive but to remain known to
    the system so that it can be interrupted; for example, to receive
    ASTs.

    Format

      SYS$HIBER

    C Prototype

      int sys$hiber  (void);

167.1  –  Arguments

    None.

168  –  $ICC ACCEPT

    Responds to an incoming connection request. This call is used to
    complete an ICC connection from the server side.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_ACCEPT  conn_handle ,[accept_buf] ,[accept_len]

                      ,[user_context] ,[flags]

    C Prototype

      int sys$icc_accept  (unsigned int conn_handle, char *

                          accept_buf, unsigned int accept_len,

                          unsigned int user_context, unsigned int

                          flags);

168.1  –  Arguments

 conn_handle

    OpenVMS usage:connection_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The handle of the requested connection.

 accept_buf

    OpenVMS usage:byte_stream
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    A buffer of up to 1000 bytes of accept data that is sent to the
    source of the connection at the completion of the connection
    process.

 accept_len

    OpenVMS usage:buffer_length
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The actual number of bytes in accept_buf to be sent.

 user_context

    OpenVMS usage:user_arg
    type:          quadword (Alpha and Integrity servers)
    access:       read only
    mechanism:    by value
    A user-specified value that is subsequently returned on any
    disconnect or data events on this connection.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    ICC$M_SYNCH_MODE can be specified to indicate that the data
    transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE,
    and $ICC_REPLY are allowed to return the status SS$_SYNCH in
    the case of synchronous completion, and that the AST will not be
    called.

169  –  $ICC CLOSE ASSOC

    Closes the application's association with ICC.

    Format

      SYS$ICC_CLOSE_ASSOC  assoc_handle

    C Prototype

      int sys$icc_close_assoc  (unsigned int assoc_handle);

169.1  –  Arguments

 assoc_handle

    OpenVMS usage:association_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The handle of the association to be closed.

170  –  $ICC CONNECT

    Establishes a connection to a remote application over an open
    association.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_CONNECT  ios_icc ,[astadr] ,[astprm] ,assoc_handle

                       ,conn_handle ,remote_assoc ,[remote_node]

                       ,[user_context] ,[conn_buf] ,[conn_buf_len]

                       ,[return_buf] ,[return_buf_len] ,[retlen_addr]

                       ,[flags]

    C Prototype

      int sys$icc_connect  (struct _ios_icc *ios_icc, void

                           (*astadr)(__unknown_params), __int64

                           astprm, unsigned int assoc_handle,

                           unsigned int *conn_handle, void

                           *remote_assoc, void *remote_node, unsigned

                           int user_context, char *conn_buf, unsigned

                           int conn_buf_len, char *return_buf,

                           unsigned int return_buf_len, unsigned int

                           *retlen_addr, unsigned int flags);

170.1  –  Arguments

 ios_icc

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    I/O status block:

                           +2                       0
    -------------------------------------------------
    |       Undefined       |   Completion status   |
    -------------------------------------------------
    |               ios_icc$l_remstat               |
    -------------------------------------------------
                           +6                      +4

    Completion status values:

    SS$_NORMAL, SS$_BUFFEROVF, SS$_EXQUOTA, SS$_INSFMEM,
    SS$_IVBUFLEN, SS$_LINKABORT, SS$_LINKDISCON, SS$_NOLOGNAM,
    SS$_NOSUCHOBJ, SS$_NOSUCHNODE, SS$_PATHLOST, SS$_REJECT,
    SS$_SSFAIL, SS$_UNREACHABLE, SS$_WRONGSTATE

    The second longword is undefined unless the completion code
    is SS$_REJECT. In this case, the application-defined rejection
    reason code is supplied by the server when $ICC_REJECT is called.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure_entry_mask
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit linkage reference (Alpha and
                  Integrity servers)
    The AST routine to be executed when the operation completes.

 astprm

    OpenVMS usage:user_arg
    type:         quadword (unsigned) (Alpha and Integrity servers)
    access:       read only
    mechanism:    by 64-bit value (Alpha and Integrity servers)
    The parameter to be passed to the AST routine.

 assoc_handle

    OpenVMS usage:association_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The handle of the association on which the connection is to be
    opened. The constant ICC$C_DFLT_ASSOC_HANDLE, if used, indicates
    that the default association is to be used (and opened if
    necessary).

 conn_handle

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    The 32-bit or 64-bit address (on Alpha and Integrity server
    systems) of a longword into which $ICC_CONNECT writes the
    connection handle of the created connection on a successful call.

 remote_assoc

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit descriptor (Alpha and Integrity
                  servers)
    An ASCII character string (31 characters maximum) specifying the
    name of the target application to connect to. Association names
    are case sensitive.

 remote_node

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit descriptor (Alpha and Integrity
                  servers)
    The name of the node where the target association resides. A
    null or blank string can be used to indicate the local node.
    If omitted (by passing zero by value), the simple clusterwide
    association registry is to be used. Each node name is a one-to-
    six character SCS node name. A comma-delimited list of nodes may
    be specified, indicating that one is to be chosen at random.

 user_context

    OpenVMS usage:user_arg
    type:          quadword (Alpha and Integrity servers)
    access:       read only
    mechanism:    by value
    A user-specified value to be subsequently returned on any
    disconnect or data events on this connection.

 conn_buf

    OpenVMS usage:byte_stream
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    A buffer of up to 1000 bytes of connection data to be sent to the
    target of the connection during the connection process.

 conn_buf_len

    OpenVMS usage:buffer_length
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The number of bytes in conn_buf to be sent.

 return_buf

    OpenVMS usage:byte_stream
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    A buffer of up to 1000 bytes in length to receive any incoming
    connection accept or reject data returned.

 return_buf_len

    OpenVMS usage:buffer_length
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The length of the supplied return_buf.

 retlen_addr

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    The 32-bit or 64-bit address (on Alpha and Integrity server
    systems) of a longword into which $ICC_CONNECT writes the actual
    length (in bytes) of any user accept or reject data returned in
    the buffer return_buf.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    ICC$M_SYNCH_MODE can be specified to indicate that the data
    transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE,
    and $ICC_REPLY are allowed to return the status SS$_SYNCH in the
    case of synchronous completion, indicating that the AST will not
    be called.

171  –  $ICC CONNECTW

    Establishes a link between two ICC associations.

    The $ICC_CONNECTW service completes synchronously; that is, it
    returns to the caller after the server has either accepted or
    rejected the connection request.

    For asynchronous completion, use the $ICC_CONNECT service; $ICC_
    CONNECT returns to the caller as soon as the connection request
    has been sent to the server, without waiting for a response from
    the server.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_CONNECTW  ios_icc, [astadr], [astprm], assoc_handle,

                        conn_handle, remote_assoc, [remote_node],

                        [user_context], [conn_buf], [conn_buf_len],

                        [return_buf], [return_buf_len],

                        [retlen_addr], [flags]

    C Prototype

      int sys$icc_connectw  (struct _ios_icc *ios_icc, void

                            (*astadr)(__unknown_params), __int64

                            astprm, unsigned int assoc_handle,

                            unsigned int *conn_handle, void

                            *remote_assoc, void *remote_node,

                            unsigned int user_context, char

                            *conn_buf, unsigned int conn_buf_len,

                            char *return_buf, unsigned int

                            return_buf_len, unsigned int

                            *retlen_addr, unsigned int flags);

172  –  $ICC DISCONNECT

    Terminates the specified connection.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_DISCONNECT  conn_handle ,iosb ,[astadr] ,[astprm]

                          ,[disc_buf] ,[disc_buf_len]

    C Prototype

      int sys$icc_disconnect  (unsigned int conn_handle,

                              struct _iosb, *iosb, void

                              (*astadr)(__unknown_params),

                              __int64 astprm, char * disc_buf,

                              unsigned int disc_buf_len);

172.1  –  Arguments

 conn_handle

    OpenVMS usage:connection_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The ID of the connection to be disconnected.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    I/O status block:

                           +2                       0
    -------------------------------------------------
    |       Undefined       |   Completion status   |
    -------------------------------------------------
    |        Unused         |        Unused         |
    -------------------------------------------------
                           +6                      +4

    Completion status values:

    SS$_NORMAL, SS$_EXQUOTA, SS$_LINKDISCON, $ICC_REJECT

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure_entry_mask
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit linkage reference (Alpha and
                  Integrity servers)
    The AST routine to be executed when the operation completes.

 astprm

    OpenVMS usage:user_arg
    type:         quadword (unsigned) (Alpha and Integrity servers)
    access:       read only
    mechanism:    by 64-bit value (Alpha and Integrity servers)
    The parameter to be passed to the AST routine.

 disc_buf

    OpenVMS usage:byte_stream
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    A buffer of up to 1000 bytes of disconnect data to be sent to the
    partner in the connection when notifying it that disconnection is
    being initiated. Delivery of this data is not guaranteed.

 disc_buf_len

    OpenVMS usage:buffer_length
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The number of bytes in disc_buf to be sent.

173  –  $ICC DISCONNECTW

    Terminates a link between two ICC associations.

    The $ICC_DISCONNECTW service completes synchronously; that is,
    it returns to the caller after the connection has completely
    finished the disconnection request.

    For asynchronous completion, use the $ICC_DISCONNECT service;
    $ICC_DISCONNECT returns to the caller as soon as the
    disconnection request has been sent to the transport layer,
    without waiting for notification that the disconnection has
    completed.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_DISCONNECTW  conn_handle ,iosb ,[astadr] ,[astprm]

                           ,[disc_buf] ,[disc_buf_len]

    C Prototype

      int sys$icc_disconnectw  (unsigned int conn_handle,

                               struct _iosb, *iosb, void

                               (*astadr)(__unknown_params), __int64

                               astprm, char * disc_buf, unsigned int

                               disc_buf_len);

174  –  $ICC OPEN ASSOC

    Declares an application association with ICC.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_OPEN_ASSOC  assoc_handle ,[assoc_name] ,[logical_name]

                          ,[logical_table] ,[conn_event_rtn]

                          ,[disc_event_rtn] ,[recv_rtn]

                          ,[maxflowbufcnt] ,[prot]

    C Prototype

      int sys$icc_open_assoc  (unsigned int *assoc_handle, void

                              *assoc_name, void *logical_name,

                              void *logical_table, void

                              (*conn_event_rtn)(__unknown_params),

                              void

                              (*disc_event_rtn)(__unknown_params),

                              void (*recv_rtn)(__unknown_params),

                              unsigned int maxflowbufcnt, unsigned

                              int prot);

174.1  –  Arguments

 assoc_handle

    OpenVMS usage:association_id
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    The 32-bit or 64-bit address (on Alpha and Integrity server
    systems) into which $ICC_OPEN_ASSOC writes the handle assigned
    to the opened association.

 assoc_name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit descriptor (Alpha and Integrity
                  servers)
    An ASCII character string of up to 31 characters in length
    specifying the name of the application opening the association.
    Null (0 length), and empty or blank association names are not
    allowed. If this argument is omitted (that is, a zero is passed
    in by value), it signifies that the user wants to open the
    default association. This argument is case sensitive.

 logical_name

    OpenVMS usage:logical name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit descriptor (Alpha and Integrity
                  servers)
    A logical name in a clusterwide logical name table used to
    maintain the simple association registry. The logical name
    represents the name of the service provided by the application.
    Logical names are case sensitive.

 logical_table

    OpenVMS usage:logical name table
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit descriptor (Alpha and Integrity
                  servers)
    The table containing the logical name logical_name. Logical
    name tables are converted to uppercase. Unless your application
    requires an application-specific logical name table,
    this argument should be either the default ICC Registry
    search list (ICC$REGISTRY), or the default registry table
    (ICC$REGISTRY_TABLE).

 conn_event_rtn

    OpenVMS usage:user_routine
    type:         procedure_entry_mask
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit linkage reference (Alpha and
                  Integrity servers)
    The address of the AST routine to be called for incoming connect
    events. This routine will be called in the mode of the caller.
    (No mechanism is provided for the routine to be called at a
    different mode).

    You must have a conn_event_rtn to operate as a server.

 disc_event_rtn

    OpenVMS usage:user_routine
    type:         procedure_entry_mask
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit linkage reference (Alpha and
                  Integrity servers)
    The address of the AST routine to be called for incoming
    disconnect events. This routine will be called in the mode of the
    caller. (No mechanism is provided for the routine to be called at
    a different mode). The arguments, conn_event_rtn, and disc_event_
    rtn, may reference the same routine.

 recv_rtn

    OpenVMS usage:user_routine
    type:         procedure_entry_mask
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit linkage reference (Alpha and
                  Integrity servers)
    The address of the AST routine to be called for incoming new data
    events.

    If the user provides this routine, it indicates that the
    user will supply a buffer of the size required (specified in
    an argument to the recv_rtn at each call) each time one is
    requested. If the user supplies this routine, receive calls
    should only be issued after receive events arrive and sufficient
    buffer space has been allocated to handle the incoming data.

    This routine will be called in the mode of the caller. (No
    mechanism is provided for the routine to be called at a different
    mode).

 maxflowbufcnt

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The maximum number of pending inbound messages (per connection)
    that ICC will allow the user before initiating flow control. A
    message is pending if it is being held within ICC but no receive
    call(s) are outstanding from the user.

    Default = 5 (Pass 0 to get the default)

 prot

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    This argument is ignored for non-server applications.

    The default protection scheme for this association is as follows:

    0 - access for everyone (default)
    1 - stops WORLD access
    2 - stops both WORLD and GROUP access

    Advanced access control is provided by ICC Security objects. For
    information about ICC system management and security, see the VSI
    OpenVMS System Manager's Manual.

175  –  $ICC RECEIVE

    Receives a single message over a connection.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_RECEIVE  conn_handle ,ios_icc ,[astadr] ,[astprm]

                       ,recv_buf ,recv_buf_len

    C Prototype

      sys$icc_receive  (unsigned int conn_handle, struct _ios_icc

                       *ios_icc, void (*astadr)(__unknown_params),

                       __int64 astprm, char *recv_buf, unsigned int

                       recv_buf_len);

175.1  –  Arguments

 conn_handle

    OpenVMS usage:connection_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The handle of the fully established connection.

 ios_icc

    OpenVMS usage:io_status_block
    type:         four longwords (unsigned)
    access:       write only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    I/O status block:

                           +2                       0
    -------------------------------------------------
    |       Undefined       |   Completion status   |
    -------------------------------------------------
    |     ios_icc$l_rcv_len:  recvlen               | +4
    -------------------------------------------------
    |     ios_icc$l_req_handle:  request_handle     | +8
    -------------------------------------------------
    |     ios_icc$l_reply_len:  reply_len           | +12
    -------------------------------------------------

    Completion codes:

    SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKDISCON, SS$_BUFOVL,
    SS$_ACCVIO

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure_entry_mask
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit linkage reference (Alpha and
                  Integrity servers)
    The AST routine to be executed when the operation completes.

 astprm

    OpenVMS usage:user_arg
    type:         quadword (unsigned) (Alpha and Integrity servers)
    access:       read only
    mechanism:    by 64-bit value (Alpha and Integrity servers)
    The parameter to be passed to the AST routine.

 recv_buf

    OpenVMS usage:byte_stream
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    The 32-bit or 64-bit address (on Alpha and Integrity server
    systems) of the buffer to receive the incoming data. The length
    of this buffer is specified by the argument recv_buf_len.

 recv_buf_len

    OpenVMS usage:buffer_length
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The length (in bytes) of the buffer available to hold the
    incoming data. This value specifies the length of the buffer
    recv_buf.

    IOS_ICC Arguments:

 recvlen (output)

    OpenVMS usage:longword unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value
    This parameter is returned in the ios_icc. $ICC_RECEIVE writes
    the actual length of the incoming data message received from the
    target application (in bytes) into offset ios_icc$l_rcv_len of
    the ios_icc.

 request_handle (output)

    OpenVMS usage:request_id
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value
    This parameter is returned in the ios_icc. $ICC_RECEIVE writes
    the Request/Response handle into offset ios_icc$l_req_handle
    of the ios_icc. The request_handle argument is nonzero if the
    application is expected to reply to this message.

 reply_len (output)

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value
    This parameter is returned in the ios_icc. The $ICC_RECEIVE
    service writes the maximum length (in bytes) of the expected
    Reply message into offset ios_icc$l_reply_len of the ios_icc, if
    request_handle is nonzero.

176  –  $ICC RECEIVEW

    The Intra-Cluster Communications Receive and Wait service queues
    a receive request to the specified connection.

    The $ICC_RECEIVEW service completes synchronously; that is, it
    returns to the caller with data.

    For asynchronous completion, use the $ICC_RECEIVE service; $ICC_
    RECEIVE returns to the caller as soon as the receive request is
    queued, without waiting for data on the connection.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_RECEIVEW  conn_handle ,ios_icc ,[astadr] ,[astprm]

                        ,recv_buf ,recv_buf_len

    C Prototype

      sys$icc_receivew  (unsigned int conn_handle, struct _ios_icc

                        *ios_icc, void (*astadr)(__unknown_params),

                        __int64 astprm, char *recv_buf, unsigned int

                        recv_buf_len);

177  –  $ICC REJECT

    Refuses a connection request.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_REJECT  conn_handle, [reject_buf], [reject_buf_len],

                      [reason]

    C Prototype

      int sys$icc_reject  (unsigned int conn_handle, char *

                          reject_buf, unsigned int reject_buf_len,

                          unsigned int reason);

177.1  –  Arguments

 conn_handle

    OpenVMS usage:connection_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The handle of the requested connection.

 reject_buf

    OpenVMS usage:byte_stream
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    A buffer of up to 1000 bytes of reject data to be sent to the
    source of the connection at the completion of the rejection
    process.

 reject_buf_len

    OpenVMS usage:buffer_length
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The number of bytes in reject_buf to be sent.

 reason

    OpenVMS usage:cond_code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    User-specified reject reason code to be supplied to the remote
    application.

    Default = SS$_REJECT

178  –  $ICC REPLY

    Sends a single message over a connection. This service is used
    in response to the reception of a Request Handle in a previous
    $ICC_RECEIVE system service.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_REPLY  conn_handle ,ios_icc ,[astadr] ,[astprm]

                     ,reply_buf ,reply_len

    C Prototype

      sys$icc_reply  (unsigned int conn_handle, struct _ios_icc

                     *ios_icc, void (*astadr)(__unknown_params),

                     __int64 astprm, char *reply_buf, unsigned int

                     reply_len);

178.1  –  Arguments

 conn_handle

    OpenVMS usage:connection_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The handle of the fully established connection.

 ios_icc

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    I/O status block:

                           +2                       0
    -------------------------------------------------
    |       Undefined       |   Completion status   |
    -------------------------------------------------
    | ios_icc$l_replyto_handle:  request_handle     | +4
    -------------------------------------------------

    Completion status values:

    SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKABORT,
    SS$_LINKDISCON

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure_entry_mask
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit linkage reference (Alpha and
                  Integrity servers)
    The AST routine to be executed when the operation completes.

 astprm

    OpenVMS usage:user_arg
    type:         quadword (unsigned) (Alpha and Integrity servers)
    access:       read only
    mechanism:    by 64-bit value (Alpha and Integrity servers)
    The parameter to be passed to the AST routine.

 reply_buf

    OpenVMS usage:byte_stream
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    The 32-bit or 64-bit address (on Alpha and Integrity server
    systems) of the buffer containing the reply data to be sent.
    The length of this buffer is specified by the argument reply_len.

 reply_len

    OpenVMS usage:buffer_length
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The length (in bytes) of the reply data to be sent over the
    connection. This value specifies the length of the buffer reply_
    buf. ICC segments larger buffers internally.

    The maximum Reply length is the smaller of the Reply buffer size
    supplied in the $ICC_RECEIVE call, or 1MB.

    IOS_ICC Argument:

 request_handle (input)

    OpenVMS usage:request_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    This parameter is passed through the ios_icc. The
    Request/Response handle from the received Transceive request
    is placed at offset ios_icc$l_replyto_handle of the ios_icc.

179  –  $ICC REPLYW

    The Intra-Cluster Communications Reply and Wait service transmits
    a single message over a connection in response to a $ICC_
    TRANSCEIVE[W] request.

    The $ICC_REPLYW service completes synchronously; that is, it
    returns to the caller when the underlying transport layer has
    released use of the reply buffer.

    For asynchronous completion, use the $ICC_REPLY service; $ICC_
    REPLY returns to the caller as soon as the transmission request
    has been queued to the transport layer, without waiting for
    notification that the transport layer has released control of
    the data buffer.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_REPLYW  conn_handle, ios_icc, [astadr], [astprm],

                      reply_buf, reply_len

    C Prototype

      sys$icc_replyw  (unsigned int conn_handle, struct _ios_icc

                      *ios_icc, void (*astadr)(__unknown_params),

                      __int64 astprm, char *reply_buf, unsigned int

                      reply_len);

180  –  $ICC TRANSCEIVE

    Sends a single message over a connection and then waits for a
    reply.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_TRANSCEIVE  conn_handle ,ios_icc ,[astadr] ,[astprm]

                          ,send_buf ,send_len

    C Prototype

      sys$icc_transceive  (unsigned int conn_handle, struct _ios_icc

                          *ios_icc, void (*astadr)(__unknown_params),

                          __int64 astprm, char *send_buf, unsigned

                          int send_len);

180.1  –  Arguments

 conn_handle

    OpenVMS usage:connection_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The handle of the fully established (open) connection.

 ios_icc

    OpenVMS usage:io_status_block
    type:         five longwords (unsigned)
    access:       modify
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    I/O status block:

                           +2                       0
    --------------------------------------------------
    |       Undefined        |   Completion status   |
    --------------------------------------------------
    |       ios_icc$l_txrcv_len: returned_data_len   | +4
    --------------------------------------------------
    |       ios_icc$a_reply_buffer: reply_buf        | +8
    |                                                | +12
    --------------------------------------------------
    |       ios_icc$l_txreply_len: reply_buf_len     | +16
    --------------------------------------------------

    Completion status values:

    SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_BUFOVFL, SS$_LINKABORT,
    SS$_LINKDISCON

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure_entry_mask
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit linkage reference (Alpha and
                  Integrity servers)
    The AST routine to be executed when the operation completes.

 astprm

    OpenVMS usage:user_arg
    type:         quadword (unsigned) (Alpha and Integrity servers)
    access:       read only
    mechanism:    by 64-bit value (Alpha and Integrity servers)
    The parameter to be passed to the AST routine.

 send_buf

    OpenVMS usage:byte_stream
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    The 32-bit or 64-bit address (on Alpha and Integrity server
    systems) of the buffer containing the data to be sent. The length
    of this buffer is specified by the argument send_len.

 send_len

    OpenVMS usage:buffer size
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The length (in bytes) of the data to be sent over the connection.
    This value specifies the length of the buffer send_buf.

    IOS_ICC Arguments:

 returned_data_len (output)

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value
    This parameter is passed through the ios_icc. The $ICC_TRANSCEIVE
    service writes the actual length (in bytes) of the reply data
    received into offset ios_icc$l_txrcv_len of the ios_icc. This
    value represents how much data in reply_buf was returned by the
    target application.

 reply_buf (input)

    OpenVMS usage:byte_stream
    type:         character-coded text string
    access:       write only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    This parameter is passed through the ios_icc. The 32-bit or 64-
    bit address (on Alpha and Integrity server systems) of the buffer
    available to receive the incoming reply message is placed in
    offset ios_icc$a_reply_buffer of the ios_icc.

 reply_buf_len (input)

    OpenVMS usage:buffer_size
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    This parameter is passed through the ios_icc. The length (in
    bytes) of the buffer to receive the reply message. This value
    specifies the length of the buffer reply_buf. This value is
    placed in offset ios_icc$l_txreply_len of the ios_icc.

181  –  $ICC TRANSCEIVEW

    Sends a single message over a connection and waits for a reply.

    The $ICC_TRANSCEIVEW service completes synchronously; that is, it
    returns to the caller when the data from the reply is available.

    For asynchronous completion, use the $ICC_TRANSCEIVE service;
    $ICC_TRANSCEIVE returns to the caller when the transmit portion
    of the tranceive request has been queued to the transport layer,
    but without waiting for notification that the transport layer has
    released control of the data buffer or for the reply data from
    the receiving end of the connection.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_TRANSCEIVEW   conn_handle ,ios_icc ,[astadr] ,[astprm]

                           ,send_buf ,send_len

    C Prototype

      sys$icc_transceivew  (unsigned int conn_handle,

                           struct _ios_icc *ios_icc, void

                           (*astadr)(__unknown_params), __int64

                           astprm, char *send_buf, unsigned int

                           send_len);

182  –  $ICC TRANSMIT

    Sends a single message over a connection.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_TRANSMIT  conn_handle ,ios_icc ,[astadr] ,[astprm]

                        ,send_buf ,send_len

    C Prototype

      sys$icc_transmit  (unsigned int conn_handle, struct _ios_icc

                        *ios_icc, void (*astadr)(__unknown_params),

                        __int64 astprm, char *send_buf, unsigned int

                        send_len);

182.1  –  Arguments

 conn_handle

    OpenVMS usage:connection_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The handle of the fully established (open) connection to send the
    data over.

 ios_icc

    OpenVMS usage:ios_status_block
    type:         structure IOS_ICC
    access:       write only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    I/O status block:

                           +2                       0
    -------------------------------------------------
    |       Undefined       |   Completion status   |
    -------------------------------------------------
    |                    Unused                     |
    -------------------------------------------------
                           +6                      +4

    Completion status values:

    SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKABORT,
    SS$_LINKDISCON

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure_entry_mask
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit linkage reference (Alpha and
                  Integrity servers)
    The AST routine to be executed when the operation completes.

 astprm

    OpenVMS usage:user_arg
    type:         quadword (unsigned) (Alpha and Integrity servers)
    access:       read only
    mechanism:    by 64-bit value (Alpha and Integrity servers)
    The parameter to be passed to the AST routine.

 send_buf

    OpenVMS usage:byte_stream
    type:         character-coded text string
    access:       read only
    mechanism:    by 32-bit or 64-bit reference (Alpha and Integrity
                  servers)
    The 32-bit or 64-bit address (on Alpha and Integrity server
    systems) of the buffer containing the data to be sent. The length
    of this buffer is specified by the argument send_len.

 send_len

    OpenVMS usage:buffer_length
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The length (in bytes) of the data to be sent over the connection.
    This value specifies the length of the buffer send_buf. The
    maximum transmission size is 1MB.

183  –  $ICC TRANSMITW

    Sends a single message over a connection.

    The $ICC_TRANSMITW service completes synchronously; that is, it
    returns to the caller when the underlying transport layer has
    released use of the Transmit buffer. This does not mean that the
    data has been received by the partner application.

    For asynchronous completion, use the $ICC_TRANSMIT service.
    The $ICC_TRANSMIT service returns to the caller as soon as the
    transmission request has been queued to the transport layer,
    without waiting for notification that the transport layer has
    released control of the data buffer.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$ICC_TRANSMITW  conn_handle ,ios_icc ,[astadr] ,[astprm]

                         ,send_buf ,send_len

    C Prototype

      sys$icc_transmitw  (unsigned int conn_handle, struct _ios_icc

                         *ios_icc, void (*astadr)(__unknown_params),

                         __int64 astprm, char *send_buf, unsigned int

                         send_len);

184  –  $IDTOASC

    Translates the specified identifier value to its identifier name.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$IDTOASC  id ,[namlen] ,[nambuf] ,[resid] ,[attrib]

                   ,[contxt]

    C Prototype

      int sys$idtoasc  (unsigned int id, unsigned short int *namlen,

                       void *nambuf, unsigned int *resid, unsigned

                       int *attrib, unsigned int *contxt);

184.1  –  Arguments

 id

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Binary identifier value translated by $IDTOASC. The id argument
    is a longword containing the binary value of the identifier. To
    determine the identifier names of all identifiers in the rights
    database, you specify id as -1 and call $IDTOASC repeatedly until
    it returns the status code SS$_NOSUCHID. The identifiers are
    returned in alphabetical order.

 namlen

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Number of characters in the identifier name translated by
    $IDTOASC. The namlen argument is the 32- or 64-bit address (on
    Alpha and Integrity server systems) of a word containing the
    length of the identifier name written to nambuf.

 nambuf

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor (Alpha and Integrity servers)
    Identifier name text string returned when $IDTOASC completes the
    translation. The nambuf argument is the 32- or 64-bit address (on
    Alpha and Integrity server systems) of a descriptor pointing to
    the buffer in which the identifier name is written.

 resid

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Identifier value of the identifier name returned in nambuf.
    The resid argument is the 32- or 64-bit address (on Alpha and
    Integrity server systems) of a longword containing the 32-bit
    code of the identifier.

 attrib

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Mask of attributes associated with the identifier returned in
    resid. The attrib argument is the 32- or 64-bit address (on
    Alpha and Integrity server systems) of a longword containing
    the attribute mask.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The following symbols
    for each bit position are defined in the system macro library
    ($KGBDEF):

    Bit Position           Meaning When Set

    KGB$V_DYNAMIC          Allows holders of the identifier to remove
                           it from or add it to the process rights
                           list using the DCL command SET RIGHTS_
                           LIST.
    KGB$V_NAME_HIDDEN      Allows holders of an identifier to have
                           it translated, either from binary to ASCII
                           or vice versa, but prevents unauthorized
                           users from translating the identifier.
    KGB$V_NOACCESS         Makes any access rights of the identifier
                           null and void. This attribute is intended
                           as a modifier for a resource identifier or
                           the Subsystem attribute.
    KGB$V_RESOURCE         Allows holders of an identifier to charge
                           disk space to the identifier. It is used
                           only for file objects.
    KGB$V_SUBSYSTEM        Allows holders of the identifier to
                           create and maintain protected subsystems
                           by assigning the Subsystem ACE to the
                           application images in the subsystem.

 contxt

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Context value used when repeatedly calling $IDTOASC. The contxt
    argument is the 32- or 64-bit address (on Alpha and Integrity
    server systems) of a longword used while $IDTOASC searches for
    all identifiers. The context value must be initialized to the
    value 0, and the resulting context of each call to $IDTOASC must
    be presented to each subsequent call. After contxt is passed to
    $IDTOASC, you must not modify its value.

185  –  $IEEE SET FP CONTROL (Alpha and Integrity servers)

    On Alpha and Integrity server systems, modifies IEEE floating-
    point state and, optionally, returns the previous value.

    The service provides the mechanism to set the specified state
    bits, to clear the specified state bits, and to swap one set of
    state bits for another.

    Format

      SYS$IEEE_SET_FP_CONTROL  [clrmsk] ,[setmsk] ,[prvmsk]

    C Prototype

      int sys$ieee_set_fp_control  (struct _ieee *clrmsk, struct

                                   _ieee *setmsk, struct _ieee

                                   *prvmsk);

185.1  –  Arguments

 clrmsk

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a quadword bit mask to be cleared in the IEEE
    floating-point control register.

    The $IEEEDEF macro defines symbols for the floating-point
    control register. The following table shows the symbols, their
    corresponding masks, and their meaning:

    Table SYS-21 Format of the IEEE Floating-Point Control Register
                 (Alpha and Integrity servers)

    Symbol                 Mask    Meaning

    IEEE$M_TRAP_ENABLE_    2       Enable invalid operation exception
    INV
    IEEE$M_TRAP_ENABLE_    4       Enable divide by 0 exception
    DZE
    IEEE$M_TRAP_ENABLE_    8       Enable overflow exception
    OVF
    IEEE$M_TRAP_ENABLE_    10      Enable underflow exception
    UNF
    IEEE$M_TRAP_ENABLE_    20      Enable inexact exception
    INE
    IEEE$M_TRAP_ENABLE_    40      Enable denormal operand exception
    DNOE
    IEEE$M_MAP_DNZ         2000    Denormal operands are mapped to
                                   0.0
    IEEE$M_MAP_UMZ         4000    Underflow results are mapped to
                                   0.0
    IEEE$M_INHERIT         8000    Inherit FP state on thread create
    IEEE$M_STATUS_INV      20000   Invalid operation
    IEEE$M_STATUS_DZE      40000   Divide by 0
    IEEE$M_STATUS_OVF      80000   Overflow
    IEEE$M_STATUS_UNF      100000  Underflow
    IEEE$M_STATUS_INE      200000  Inexact
    IEEE$M_STATUS_DNO      400000  Denormal operand

 setmsk

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a quadword bit mask to be set in the IEEE floating-
    point control register.

    See the clrmsk argument for the format of the IEEE floating-point
    control register.

 prvmsk

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of a quadword to receive the previous value of the IEEE
    floating-point control register.

186  –  $IEEE SET PRECISION MODE (Integrity servers Only)

    On Integrity server systems, modifies the IEEE precision mode
    and, optionally, returns the previous value.

    Format

      SYS$IEEE_SET_PRECISION_MODE  new_value , [*prev_value]

    C Prototype

      int sys$ieee_set_rounding_mode  (int new_value, int

                                      *prev_value);

186.1  –  Arguments

 new_value

    OpenVMS usage:IEEE precision mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The new value can be one of the following:

    Symbol                          ValueMeaning

    IEEE$C_PM_NO_CHANGE             -1   No change. Just get previous
                                         value
    IEEE$C_PM_SINGLE                0    Single Precision
    IEEE$C_PM_DOUBLE                2    Double Precision
    IEEE$C_PM_DOUBLE_EXTENDED       3    Double-Extended Precision

 prev_value

    OpenVMS usage:IEEE precision mode
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    The previous value is a pointer to a return value that can be one
    of the last three items from the table showing new values.

187  –  $IEEE SET ROUNDING MODE (Integrity servers Only)

    On Integrity server systems, modifies the IEEE rounding mode and,
    optionally, returns the previous value.

    Format

      SYS$IEEE_SET_ROUNDING_MODE  new_value , [*prev_value]

    C Prototype

      int sys$ieee_set_rounding_mode  (int new_value, int

                                      *prev_value); ,

187.1  –  Arguments

 new_value

    OpenVMS usage:IEEE rounding mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The new value can be one of the following:

    Symbol              ValueMeaning

    IEEE$C_RM_NO_       -1   No change. Just get previous value
    CHANGE
    IEEE$C_RM_NEAREST   0    Nearest (or even)
    IEEE$C_RM_DOWN      1    -Infinity (down)
    IEEE$C_RM_UP        2    +Infinity (up)
    IEEE$C_RM_TRUNCATE  3    Zero (truncate/chop)

 prev_value

    OpenVMS usage:IEEE rounding mode
    type:         longword (unsigned)
    access:        write only
    mechanism:    by reference
    The previous value is a pointer to a return value that can be one
    of the last four items from the table showing new values.

188  –  $INIT SYS ALIGN FAULT REPORT (Alpha and Integrity servers)

    On Alpha and Integrity server systems, initializes system process
    alignment fault reporting.

    This service accepts 64-bit addresses.

    Format

      SYS$INIT_SYS_ALIGN_FAULT_REPORT  match_table ,buffer_size

                                       ,flags

    C Prototype

      int sys$init_sys_align_fault_report  (void *match_table, int

                                           buffer_size, unsigned int

                                           flags);

188.1  –  Arguments

 match_table

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read
    mechanism:    by 32-bit or 64-bit reference
    Describes the system fault match table. The match_table argument
    is the 32-bit or 64-bit virtual address of an array of longwords
    describing the system fault match table. The first longword is
    the number of match entries; the remaining longwords are the
    match entries.

    The match table is used to restrict the number of alignment
    faults reported. Each entry in the table is a bit mask divided
    into three groups: mode bits, program counter (PC) space bits,
    and virtual address (VA) space bits.

    The following table lists the symbols that can be used to define
    these bits:

    Bit Type       Symbols

    Mode bits      AME$M_KERNEL_MODE  Kernel mode
                   AME$M_EXEC_MODE    Executive mode
                   AME$M_SUPER_MODE   Supervisor mode
                   AME$M_USER_MODE    User mode
    Program        AME$M_USER_PC      PC in User space
    counter bits
                   AME$M_SYSTEM_PC    PC in System space
    Virtual        AME$M_SYSTEM_VA    VA in System space
    address bits
                   AME$M_USER_VA_P0   VA in User P0 space
                   AME$M_USER_VA_P1   VA in User P1 space
                   AME$M_USER_VA_P2   VA in User P2 space

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the data structure of the match table.

    When an alignment fault occurs, a fault bit mask is created with
    one bit set in each group. The alignment fault handler then
    compares this fault bit mask against each entry in the match
    table. If the fault bit mask is a subset of an entry in the match
    table, the fault is reported.

 buffer_size

    OpenVMS usage:byte count
    type:         longword (signed)
    access:       read
    mechanism:    by value
    The number of bytes to allocate, from nonpaged pool, to save the
    alignment fault data. The buffer you allocate must be sufficient
    to accommodate one data item of the size specified in the flags
    argument.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag bit mask specifying options for the $GET_SYS_ALIGN_FAULT_
    DATA operation.

    If the flags argument is 0, data items of size AFR$K_VMS_LENGTH
    will be returned. If the flags argument is AFR$M_USER_INFO, the
    user name and image name are added to each data item and they
    are returned in a buffer of length AFR$K_EXTENDED_LENGTH. If the
    user name and image name are not available, an empty string is
    returned in the data item.

189  –  $INIT VOL

    Formats a disk or magnetic tape volume and writes a label on the
    volume. At the end of initialization, the disk is empty except
    for the system files containing the structure information. All
    former contents of the volume are lost.

    Format

      SYS$INIT_VOL  devnam, volnam [,itmlst]

    C Prototype

      int sys$init_vol  (void *devnam, void *volnam, void *itmlst);

189.1  –  Arguments

 devnam

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Name of the device on which the volume is physically mounted. The
    descriptor must point to the device name, a character string of 1
    to 64 characters. The device name can be a physical device name
    or a logical name; if it is a logical name, it must translate to
    a physical name.

    The device does not have to be currently allocated; however,
    allocating the device before initializing it is recommended.

 volnam

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Identification to be encoded on the volume. The descriptor
    must point to the volume name, a character string of 1 to 12
    characters. For a disk volume name, you can specify a maximum
    of 12 ANSI characters; for a magnetic tape volume name, you can
    specify a maximum of 6 ANSI "a" characters.

    Any valid ANSI "a" characters can be used; these include numbers,
    uppercase letters, and any one of the following nonalphanumeric
    characters:

    ! " % ' ( ) * + , - . / : ; < = >

    VSI strongly recommends that a disk volume name consist of only
    alphanumeric characters, dollar signs ($),  underscores (_), and
    hyphens (-).

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying options that can be used when initializing
    the volume. The itmlst argument is the address of a list of item
    descriptors, each of which describes one option. The list of item
    descriptors is terminated by a longword of 0.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

190  –  $IO CLEANUP (Alpha and Integrity servers)

    On Alpha and Integrity server systems, returns all resources
    allocated by $IO_SETUP.

    This service accepts 64-bit addresses.

    Format

      SYS$IO_CLEANUP  fandle

    C Prototype

      int sys$io_cleanup  (unsigned __int64 fandl);

190.1  –  Arguments

 fandle

    OpenVMS usage:fandle
    type:         64-bit integer (unsigned)
    access:       read only
    mechanism:    by value
    A fandle, passed by value, returned by a previous call to $IO_
    SETUP.

191  –  $IO FASTPATH (Alpha and Integrity servers)

    On Alpha and Integrity server systems, provides the ability to
    control the set of Fast Path devices and their assignment to CPUs
    enabled for Fast Path use.

    Format

      SYS$IO_FASTPATH  efn, cpu_mask,function_code, [iosb], [astadr],

                       [astprm] [,[mask_length]]

    C Prototype

      int sys$io_fastpath  (unsigned int efn, UINT32_PQ cpu_mask,

                           int function_code, struct_iosb *iosb,

                           void (*astadr)(__unknown_params), __int64

                           astprm, ...) ;)

191.1  –  Arguments

 efn

    OpenVMS usage:integer
    type:         longword bit mask (unsigned)
    access:       read
    mechanism:    by value
    Number of the event flag to be set when the IO_FASTPATH(W)
    operation completes. The efn argument is a longword containing
    the number of the event flag.

 cpu_mask

    OpenVMS usage:bitmap
    type:         quadword bitmap
    access:       read
    mechanism:    by 32- or 64-bit reference
    The cpu_mask argument specifies a set of CPUs to be operated
    upon.

 function_code

    OpenVMS usage:integer
    type:         longword (unsigned)
    access:       read
    mechanism:    by value
    The function_code specifies the operation to be performed. Note
    that there is currently only one function code:

    FP$K_BALANCE_PORTS - Distribute Fast Path ports across CPUs.

 mask_length

    OpenVMS usage:integer
    type:         longword length
    access:       read
    mechanism:    by value
    The mask_length specifies the length of the cpu_mask bitmap in
    bytes. If the mask_length is not supplied or is specified as
    zero, a length of 4 bytes is used.

192  –  $IO FASTPATHW

    On Alpha and Integrity server systems, performs operations on the
    set of Fast Path devices and CPUs enabled for Fast Path use.

    The $IO_FASTPATHW system service is functionally equivalent to
    the $IO_FASTPATH service except that it completes synchronously.
    That is, it returns after the operation is complete.

    Format

      SYS$IO_FASTPATHW  efn, cpu_mask, function_code, [iosb],

                        [astadr], [astprm], [,[mask_length]]

    C Prototype

      int sys$io_fastpathw  (unsigned int efn, UINT32_PQ cpu_mask,

                            int function_code, struct_iosb *iosb,

                            void (*astadr)(_ _unknown_params),

                            _ _int64 astprm, ...) ;)

193  –  $IO PERFORM (Alpha and Integrity servers)

    On Alpha and Integrity server systems, starts the Fast I/O
    operation. The $IO_PERFORM service completes asynchronously.
    For synchronous completion, use the Perform Fast I/O and Wait
    ($IO_PERFORMW) service.

    This service accepts 64-bit addresses.

    Format

      SYS$IO_PERFORM  fandle ,chan ,iosadr ,bufadr ,buflen ,devdata

    C Prototype

      int sys$io_perform  (unsigned __int64 fandl, unsigned short int

                          chan, struct _iosa *iosadr, void *bufadr,

                          unsigned __int64 buflen, unsigned __int64

                          devdata);

193.1  –  Arguments

 fandle

    OpenVMS usage:fandle
    type:         64-bit integer (unsigned)
    access:       read only
    mechanism:    by value
    A fandle returned by a previous call to $IO_SETUP.

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read
    mechanism:    by value
    Software I/O channel number.

 iosadr

    OpenVMS usage:address
    type:         address
    access:       read only
    mechanism:    by value
    Address of the I/O Status Area (IOSA). This value cannot be 0;
    that is, an IOSA is required. The iosadr must be aligned to a
    quadword boundary.

 bufadr

    OpenVMS usage:char_string
    type:         address
    access:       read only
    mechanism:    by value
    The process buffer address. Must be aligned on a 512-byte
    boundary.

 buflen

    OpenVMS usage:byte count
    type:         64-bit integer
    access:       read only
    mechanism:    by value
    The byte count for the I/O. The buflen argument must be a
    multiple of 512 bytes. Drivers have further limitations on the
    maximum size of an I/O request.

 devdata

    OpenVMS usage:address
    type:         pointer or integer
    access:       read only
    mechanism:    by value
    A hardware integer passed unchanged to the driver. For disk
    devices, this is the media address for the transfer; that is,
    the virtual block number (VBN) for virtual I/O functions or
    the logical block number (LBN) for logical I/O functions. This
    argument is ignored for tape devices.

    For drivers with complex parameters, devdata would be the address
    of a descriptor or buffer specific to the device and function and
    would be documented with the driver.

194  –  $IO PERFORMW (Alpha and Integrity servers)

    On Alpha and Integrity server systems, starts a Fast I/O
    operation. The $IO_PERFORMW service completes synchronously;
    that is, it returns to the caller after performing the Fast I/O
    operation.

    In all other respects, $IO_PERFORMW is identical to $IO_PERFORM.
    For all other information about the IO_PERFORMW service, see the
    help for $IO_PERFORM.

    Format

      SYS$IO_PERFORMW  fandle ,chan ,iosadr ,bufadr ,buflen ,devdata

    C Prototype

      int sys$io_performw  (unsigned __int64 fandl, unsigned short

                           int chan, struct _iosa *iosadr, void

                           *bufadr, unsigned __int64 buflen, unsigned

                           __int64 devdata);

195  –  $IO SETUP (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allocates resources for
    Fast I/O.

    This service accepts 64-bit addresses.

    Format

      SYS$IO_SETUP  func ,bufobj ,iosobj ,astadr ,flags

                    ,return_fandle

    C Prototype

      int sys$io_setup  (unsigned int func, struct _generic_64

                        *bufobj, struct _generic_64 *iosobj, void

                        (*astadr)(struct _iosa *), unsigned int

                        flags, unsigned __int64 *return_fandle);

195.1  –  Arguments

 func

    OpenVMS usage:function_code
    type:         longword
    access:       read only
    mechanism:    by value
    I/O function code. Must be one of the following:

    o  IO$_READVBLK

    o  IO$_WRITEVBLK

    o  IO$_READLBLK

    o  IO$_WRITELBLK

    Various function modifiers are supported, depending on the
    device and driver. Disk drivers support IO$M_NOVCACHE and
    IO$M_DATACHECK. Some tape devices support IO$M_REVERSE. Illegal
    modifiers are detected by the $IO_PERFORM(W) service.

 bufobj

    OpenVMS usage:buffer object
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Handle describing the buffer object that contains the user's
    buffer. This identifier cannot be 0.

 iosobj

    OpenVMS usage:object handle
    type:         vector longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Buffer object handle describing the buffer object that contains
    the I/O Status Area (IOSA). This might or might not be the same
    identifier as the bufobj argument. This identifier cannot be 0.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Completion AST routine address (0, if none). There is no
    AST parameter argument. When the AST routine is called, the AST
    parameter will be the address of the IOSA for the operation.
    Applications can store data in the IOSA at offset IOSA$IH_
    CONTEXT.

 flags

    OpenVMS usage:mask_longword
    type:         64-bit integer (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask. The flags argument is a bit vector in which each bit
    corresponds to a flag. Flags are defined in the module IOSADEF.

    The following table describes the flags that are valid for the
    $IO_SETUP service:

    Flag            Description

    FIO$M_          This is a high priority I/O; that is, it is
    EXPEDITE        to be given preferential treatment by the I/O
                    subsystem. Use of this bit requires ALTPRI or
                    PHY_IO privilege.

    FIO$M_AST_      The AST procedure does not use, or call any
    NOFLOAT         procedure that uses, any floating-point
                    registers. This is a performance option. If
                    set, AST delivery will neither save nor restore
                    floating-point registers. Caution: Use of
                    floating-point registers when FIO$M_AST_NOFLOAT
                    has been specified can cause unpredictable,
                    difficult to detect, error conditions.

    All other bits in the flags argument are reserved for future use
    by VSI and should be specified as 0.

 return_fandle

    OpenVMS usage:fandle
    type:         64-bit integer (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Address of an aligned quadword to receive the fandle for this I/O
    operation.

196  –  $JOIN RM

    Adds a new Resource Manager (RM) participant to a transaction.

    Format

      SYS$JOIN_RM  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id

                   [,[tid] ,[part_name] ,[rm_context] ,[timout]

                   ,[bid]]

    C Prototype

      int sys$join_rm  (unsigned int efn, unsigned int flags, struct

                       _iosb *iosb, void (*astadr)(__unknown_params),

                       int astprm, unsigned int rm_id,...);

196.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for these option
    flags described in $JOIN_RM Option Flags. All undefined bits must
    be 0. If this argument is omitted, no flags are used.

    Table SYS-22 $JOIN_RM Option Flags

    Flag Name          Description

    DDTM$M_            Set this flag to specify that the new RM
    COORDINATOR        participant is to be a coordinator of the
                       transaction on this node.
    DDTM$M_SYNC        Specifies successful synchronous completion
                       by returning SS$_SYNCH. When SS$_SYNCH is
                       returned, the AST routine is not called, the
                       event flag is not set, and the I/O status
                       block is not filled in.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the completion status of the
    service is returned as a condition value.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the I/O status block diagram.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine that is executed when the service completes, if
    SS$_NORMAL is returned in R0. The astadr argument is the address
    of the entry mask of this routine. The routine is executed in the
    same access mode as that of the caller of the $JOIN_RM service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter that is passed to the AST routine specified by
    the astadr argument.

 rm_id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The identifier of the RMI with which the new RM participant is
    associated. This identifies:

    o  Types of event that are to be reported to the new RM
       participant.

    o  Event handler to which these event reports are to be
       delivered, and the access mode in which its ASTs are to be
       fired.

    o  Minimum access mode that the new RM participant must be in to
       acknowledge one of these event reports by calling $ACK_EVENT.

    o  Whether or not the DECdtm transaction manager may log
       information about the new RM participant.

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (TID) of the transaction to which the new RM
    participant is to be added.

    If this argument is omitted (the default) or its value is zero,
    $JOIN_RM adds an RM participant to the default transaction of the
    calling process.

 part_name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    The name of the new RM participant.

    Used by recoverable resource managers to specify the RM
    participant to use in a subsequent call to $GETDTI or $SETDTI
    during recovery.

    This argument has no effect if the RMI is volatile. If this
    argument is omitted (the default) or its value is zero, the name
    of the new RM participant is the same as that of the RMI with
    which it is associated.

    The string passed in this argument can be no longer than 32
    characters.

    To ensure smooth operation in a mixed-network environment,
    refer to the chapter entitled Managing DECdtm Services in the
    VSI OpenVMS System Manager's Manual, for information on defining
    node names.

 rm_context

    OpenVMS usage:userarg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The context associated with the new RM participant. This is
    passed in the event reports subsequently delivered to the new
    RM participant.

    If this argument is omitted (the default) or is zero, the context
    associated with the new RM participant is the same as that of the
    RMI with which it is associated.

 timout

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Reserved to VSI.

 bid

    OpenVMS usage:branch_id
    type:         octaword (unsigned)
    access:       write only
    mechanism:    by reference
    The identifier of an authorized branch (BID) that may be added
    to the transaction by a subsequent call to $START_BRANCH on the
    same node as that of the RMI. This argument is ignored if the
    DDTM$M_COORDINATOR flag is clear in the flags argument. The call
    to $START_BRANCH should specify the node of the RMI for the tm_
    name argument.

197  –  $JOIN RMW

    Adds a new Resource Manager (RM) participant to a transaction.

    $JOIN_RMW always waits for the request to complete before
    returning to the caller. Other than this, it is identical to
    $JOIN_RM.

    Format

      SYS$JOIN_RMW  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id

                    [,[tid] ,[part_name] ,[rm_context] ,[timout]

                    ,[bid] ]

    C Prototype

      int sys$join_rmw  (unsigned int efn, unsigned int

                        flags, struct _iosb *iosb, void

                        (*astadr)(__unknown_params), int

                        astprm, unsigned int rm_id,...);

198  –  $LCKPAG

    Locks a page or range of pages in memory. The specified virtual
    pages are forced into the working set and then locked in memory.
    A locked page is not swapped out of memory if the working set of
    the process is swapped out. These pages are not candidates for
    page replacement and in this sense are locked in the working set
    as well.

    Format

      SYS$LCKPAG  inadr ,[retadr] ,[acmode]

    C Prototype

      int sys$lckpag  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode);

198.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Starting and ending virtual addresses of the range of pages to be
    locked. The inadr argument is the address of a 2-longword array
    containing, in order, the starting and ending process virtual
    addresses. Only the virtual page number portion of each virtual
    address is used; the low-order byte-within-page bits are ignored.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Starting and ending process virtual addresses of the pages that
    $LCKPAG actually locked. The retadr argument is the address of
    a 2-longword array containing, in order, the starting and ending
    process virtual addresses.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be associated with the pages to be locked. The
    acmode argument is a longword containing the access mode. The
    $PSLDEF macro defines the four access modes.

    The most privileged access mode used is the access mode of the
    caller. For the $LCKPAG service to complete successfully, the
    resultant access mode must be equal to or more privileged than
    the access mode already associated with the pages to be locked.

199  –  $LCKPAG 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, locks a range of pages in
    memory. The specified virtual pages are forced into the working
    set and then locked in memory. A locked page is not swapped out
    of memory if the working set of the process is swapped out. These
    pages are not candidates for page replacement and, in this sense,
    are locked in the working set as well.

    This service accepts 64-bit addresses.

    Format

      SYS$LCKPAG_64  start_va_64 ,length_64 ,acmode ,return_va_64

                     ,return_length_64

    C Prototype

      int sys$lckpag_64  (void *start_va_64, unsigned __int64

                         length_64, unsigned int acmode, void

                         *(*(return_va_64)), unsigned __int64

                         *return_length_64);

199.1  –  Arguments

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address of the pages to be locked. The
    specified virtual address will be rounded down to a CPU-specific
    page boundary.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space to be locked. The specified
    length will be rounded up to a CPU-specific page boundary so that
    it includes all CPU-specific pages in the requested range.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode associated with the pages to be locked. The acmode
    argument is a longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. For the $LCKPAG_64 service to complete successfully, the
    resultant access mode must be equal to or more privileged than
    the access mode already associated with the pages to be locked.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of the pages locked in memory.
    The return_va_64 argument is the 32- or 64-bit virtual address of
    a naturally aligned quadword into which the service returns the
    virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned quadword
    into which the service returns the length of the virtual address
    range locked in bytes.

200  –  $LKWSET

    Locks a range of pages in the working set; if the pages are not
    already in the working set, it brings them in and locks them. A
    page locked in the working set does not become a candidate for
    replacement.

    Format

      SYS$LKWSET  inadr ,[retadr] ,[acmode]

    C Prototype

      int sys$lkwset  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode);

200.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Starting and ending virtual addresses of the range of pages to be
    locked in the working set. The inadr argument is the address of
    a 2-longword array containing, in order, the starting and ending
    process virtual addresses. Only the virtual page number portion
    of each virtual address is used; the low-order byte-within-page
    bits are ignored.

    On Alpha and Integrity server systems, if the first address in
    the 2-longword array is within an image mapped to your process,
    the entire image specified by the address is locked in the
    working set.

    Be sure to check calls to the SYS$LKWSET and SYS$LKWSET_64 system
    services for correct arguments. This affects only process-based
    code running above IPL2. Compiler and linker differences might
    cause your program layout to change from Alpha, resulting in
    incorrectly calculated starting and ending addresses for calls
    to SYS$LKWSET and SYS$LKWSET_64. Calling these services with
    incorrect arguments and then executing this code above IPL2 could
    cause PGFIPLHI bugchecks. Note that SYS$LKWSET and SYS$LKWSET_
    64 automatically lock linker-generated short data sections
    associated with code sections locked in the working set.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Starting and ending process virtual addresses of the range of
    pages actually locked by $LKWSET. The retadr argument is the
    address of a 2-longword array containing, in order, the starting
    and ending process virtual addresses.

    On Alpha and Integrity server systems, if the inadr argument
    specifies an address within an image mapped to your process,
    retadr specifies only one range of pages locked in the working
    set. Many ranges of pages might be locked.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be associated with the pages to be locked. The
    acmode argument is a longword containing the access mode. The
    $PSLDEF macro defines the four access modes.

    The most privileged access mode used is the access mode of the
    caller. For the $LKWSET service to complete successfully, the
    resultant access mode must be equal to or more privileged than
    the access mode already associated with the pages to be locked.

201  –  $LKWSET 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, locks a range of virtual
    addresses in the working set. If the pages are not already in
    the working set, the service brings them in and locks them. A
    page locked in the working set does not become a candidate for
    replacement.

    This service accepts 64-bit addresses.

    Format

      SYS$LKWSET_64  start_va_64 ,length_64 ,acmode ,return_va_64

                     ,return_length_64

    C Prototype

      int sys$lkwset_64  (void *start_va_64, unsigned __int64

                         length_64, unsigned int acmode, void

                         *(*(return_va_64)), unsigned __int64

                         *return_length_64);

201.1  –  Arguments

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address of the pages to be locked in the
    working set. The specified virtual address will be rounded down
    to a CPU-specific page boundary.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space to be locked in the working
    set. The specified length will be rounded up to a CPU-specific
    page boundary so that it includes all CPU-specific pages in the
    requested range.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode associated with the pages to be locked. The acmode
    argument is a longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. For the $LKWSET_64 service to complete successfully, the
    resultant access mode must be equal to or more privileged than
    the access mode already associated with the pages to be locked.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of the pages locked in the
    working set. The return_va_64 argument is the 32- or 64-bit
    virtual address of a naturally aligned quadword into which the
    service returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the virtual address range locked in the working
    set. The return_length_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword into which the service
    returns the length of the virtual address range in bytes.

202  –  $MGBLSC

    Establishes a correspondence between pages (maps) in the virtual
    address space of the process and physical pages occupied by a
    global section.

    Format

      SYS$MGBLSC  inadr ,[retadr] ,[acmode] ,[flags] ,gsdnam ,[ident]

                  ,[relpag]

    C Prototype

      int sys$mgblsc  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode, unsigned int

                      flags, void *gsdnam, struct _secid *ident,

                      unsigned int relpag);

202.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Starting and ending virtual addresses into which the section is
    to be mapped. The inadr argument is the address of a 2-longword
    array containing, in order, the starting and ending process
    virtual addresses. Only the virtual page number portion of each
    virtual address is used to specify which pages are to be mapped;
    the low-order byte-within-page bits are ignored for this purpose.

    The interpretation of the inadr argument depends on the setting
    of SEC$M_EXPREG in the inadr argument and whether you are
    using an Alpha or an Integrity servers system. For a complete
    description of these differences, see the VSI OpenVMS System
    Services Reference Manual.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Starting and ending process virtual addresses into which the
    section was actually mapped by $MGBLSC. The retadr argument
    is the address of a 2-longword array containing, in order, the
    starting and ending process virtual addresses.

    On Alpha and Integrity server systems, the retadr argument
    returns the starting and ending addresses of the usable range
    of addresses. This might differ from the total amount mapped.
    The retadr argument is required when the relpag argument is
    specified. If the section being mapped does not completely
    fill the last page used to map the section, the retadr argument
    indicates the highest address that actually maps the section.
    If the relpag argument is used to specify an offset into the
    section, the retadr argument reflects the offset.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be associated with the pages mapped into the
    process virtual address space. The acmode argument is a longword
    containing the access mode. The $PSLDEF macro defines symbols for
    the four access modes.

    The most privileged access mode used is the access mode of the
    caller.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying options for the operation. The flags
    argument is a longword bit vector wherein a bit when set
    specifies the corresponding option.

    The $SECDEF macro defines symbolic names for the flag bits. You
    construct the flags argument by specifying the symbolic names of
    each desired option in a logical OR operation.

    The following table describes each flag option:

    Flag Option   Description

    SEC$M_WRT     Map the section with read/write access. By default,
                  the section is mapped with read-only access. If
                  SEC$M_WRT is specified and the section is not copy-
                  on-reference, write access is required.

    SEC$M_SYSGBL  Map a system global section. By default, the
                  section is a group global section.

    SEC$M_EXPREG  Map the section into the first available virtual
                  address range. By default, the section is mapped
                  into the range specified by the inadr argument.

                  See the inadr argument description for a complete
                  explanation of how to set the SEC$M_EXPREG flag.
    SEC$M_        Flag that must be set when a PFN-mapped section
    UNCACHED      is created if this section must be treated as
                  uncached memory. Flag is ignored on Alpha systems;
                  it applies only to Integrity server systems.

 gsdnam

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the global section. The gsdnam argument is the address of
    a character string descriptor pointing to this name string.

    For group global sections, the operating system interprets the
    group UIC as part of the global section name; thus, the names
    of global sections are unique to UIC groups. Further, all global
    section names are implicitly qualified by their identification
    fields.

    You can specify any name from 1 to 43 characters. All processes
    mapping to the same global section must specify the same name.
    Note that the name is case sensitive.

    Use of characters valid in logical names is strongly encouraged.
    Valid values include alphanumeric characters, the dollar sign
    ($), and the underscore (_). If the name string begins with an
    underscore (_), the underscore is stripped and the resultant
    string is considered to be the actual name. Use of the colon (:)
    is not permitted.

    Names are first subject to a logical name translation, after
    the application of the prefix GBL$ to the name. If the result
    translates, it is used as the name of the section. If the
    resulting name does not translate, the name specified by the
    caller is used as the name of the section.

    Additional information on logical name translations and
    on section name processing is available in the VSI OpenVMS
    Programming Concepts Manual.

 ident

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Identification value specifying the version number of a global
    section and, for processes mapping to an existing global section,
    the criteria for matching the identification. The ident argument
    is the address of a quadword structure containing three fields.

    The first longword specifies, in the low-order two bits, the
    matching criteria. Their valid values, the symbolic names by
    which they can be specified, and their meanings are as follows:

    Value/Name      Match Criteria

    0 SEC$K_        Match all versions of the section.
    MATALL
    1 SEC$K_        Match only if major and minor identifications
    MATEQU          match.
    2 SEC$K_        Match if the major identifications are equal and
    MATLEQ          the minor identification of the mapper is less
                    than or equal to the minor identification of the
                    global section.

    The version number is in the second longword and contains two
    fields: a minor identification in the low-order 24 bits and a
    major identification in the high-order 8 bits.

    If you do not specify ident or specify it as the value 0 (the
    default), the version number and match control fields default to
    the value 0.

 relpag

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Relative page number within the section of the first page to be
    mapped. The relpag argument is a longword containing this number.

    On Alpha and Integrity server systems, the relpag argument is
    interpreted as an index into the section file, measured in
    pagelets for a file-backed section or CPU-specific pages for a
    PFN-mapped section.

    On Alpha, Integrity servers systems, if you do not specify relpag
    or specify it as the value 0 (the default), the global section
    is mapped beginning with the first virtual block in a file-backed
    section or the first CPU-specific page in a PFN-mapped section.

203  –  $MGBLSC 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, establishes a
    correspondence between pages in the virtual address space of
    the process and the pages occupied by a global disk file, page
    file, or demand-zero section and can map to a demand-zero section
    with shared page tables.

    This service accepts 64-bit addresses.

    Format

      SYS$MGBLSC_64  gs_name_64 ,ident_64 ,region_id_64

                     ,section_offset_64 ,length_64 ,acmode

                     ,flags ,return_va_64 ,return_length_64

                     [,start_va_64]

    C Prototype

      int sys$mgblsc_64  (void *gsdnam_64, struct _secid *ident_64,

                         struct _generic_64 *region_id_64, unsigned

                         __int64 section_offset_64, unsigned __int64

                         length_64, unsigned int acmode, unsigned int

                         flags, void *(*(return_va_64)), unsigned

                         __int64 *return_length_64,...);

203.1  –  Arguments

 gs_name_64

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section. The gs_name_64 argument is the 32-
    or 64-bit virtual address of a naturally aligned 32-bit or 64-bit
    string descriptor pointing to this name string.

    You can specify any name from 1 to 43 characters. All processes
    mapping to the same global section must specify the same name.
    Note that the name is case sensitive.

    Use of characters valid in logical names is strongly encouraged.
    Valid values include alphanumeric characters, the dollar sign
    ($), and the underscore (_). If the name string begins with an
    underscore (_), the underscore is stripped and the resultant
    string is considered to be the actual name. Use of the colon (:)
    is not permitted.

    Names are first subject to a logical name translation, after
    the application of the prefix GBL$ to the name. If the result
    translates, it is used as the name of the section. If the
    resulting name does not translate, the name specified by the
    caller is used as the name of the section.

    Additional information on logical name translations and
    on section name processing is available in the VSI OpenVMS
    Programming Concepts Manual.

 ident_64

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of a global
    section. The ident_64 argument is a quadword containing three
    fields. The ident_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword that contains the
    identification value.

    The first longword specifies the matching criteria in its low-
    order two bits.

    The valid values, symbolic names by which they can be specified,
    and their meanings are as follows:

           Symbolic
    Value  Name           Match Criteria

    0      SEC$K_MATALL   Match all versions of the section.
    1      SEC$K_MATEQU   Match only if major and minor
                          identifications match.
    2      SEC$K_MATLEQ   Match if the major identifications are
                          equal and the minor identification of the
                          mapper is less than or equal to the minor
                          identification of the global section.

    If you specify the ident_64 argument as 0, the version number and
    match control fields default to 0.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. You
    can assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region to map the global
    section. The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF
    macro in STARLET.MLB define a symbolic name for each of the three
    default regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified.

 section_offset_64

    OpenVMS usage:byte offset
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Offset into the global section at which to start mapping into the
    process's virtual address space.

    If a map to a global disk file section is being requested, the
    section_offset_64 argument specifies an even multiple of disk
    blocks. If a map to a global page file or demand-zero section is
    being requested, the section_offset_64 argument specifies an even
    multiple of CPU-specific pages. If zero is specified, the global
    section is mapped beginning with the first page of the section.

    If the region_id_64 argument specifies a shared page table
    region, section_offset_64 must be an even multiple of pages
    mapped by a page table page.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length, in bytes, of the desired mapping of the global disk file
    section.

    If a map to a global section is being requested, the length_64
    argument must specify an even multiple of disk blocks. If a map
    to a global page file or demand-zero section is being requested,
    the length_64 argument must specify an even multiple of CPU-
    specific pages. If zero is specified, the size of the disk file
    is used.

    If a shared page-table region is specified by the region_id_64
    argument, length_64 must be an even multiple of the number of
    bytes that can be mapped by a CPU-specific page-table page or
    must include the last page within the memory-resident global
    section.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode that is to be the owner of the pages created during
    the mapping. This is also the read access mode and, if the SEC$M_
    WRT flag is specified, the write access mode. The acmode argument
    is a longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. Address space cannot be created within a region that has
    a create mode associated with it that is more privileged than
    the caller's mode. The condition value SS$_IVACMODE is returned
    if the caller is less privileged than the create mode for the
    region.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying options for the operation. The flags
    argument is a longword bit vector in which each bit corresponds
    to a flag. The $SECDEF macro and the SECDEF.H file define a
    symbolic name for each flag. You construct the flags argument
    by performing a logical OR operation on the symbol names for all
    desired flags.

    The following table describes each flag that is valid for the
    $MGBLSC_64 service:

    Flag          Description

    SEC$M_EXPREG  Pages are mapped into the first available space at
                  the current end of the specified region.

                  If /ALLOCATE was specified when the memory-resident
                  global section was registered in the Reserved
                  Memory Registry, virtually aligned addresses
                  after the first available space are chosen for
                  the mapping.

                  It the region_id_64 argument specifies a shared
                  page-table region, the first available space is
                  round up to the beginning of the next CPU-specific
                  page-table page.
    SEC$M_GBL     Pages form a global section. By default, this flag
                  is always present in this service and cannot be
                  disabled.
    SEC$M_NO_     Pages cannot overmap existing address space.
    OVERMAP
    SEC$M_SHMGS   On OpenVMS Galaxy systems, create a shared-memory
                  global section.
    SEC$M_SYSGBL  The global section map is a system global section.
                  By default, the section is a group global section.
    SEC$M_WRT     Map the section with read/write access.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set or if
    an attempt is made to use the SEC$M_PAGFIL flag, which applies
    only to the creation of a page-file backed section.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The process virtual address into which the global disk or page
    file section was mapped. The return_va_64 argument is the 32- or
    64-bit virtual address of a naturally aligned quadword into which
    the service returns the virtual address.

    Upon successful completion of this service, if the
    section_offset_64 argument was specified, the virtual address
    returned in the return_va_64 argument reflects the offset into
    the global section mapped such that the virtual address returned
    cannot be aligned on a CPU-specific page boundary. The virtual
    address returned will always be on an even virtual disk block
    boundary.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the usable virtual address range mapped. The
    return_length_64 argument is the 32- or 64-bit virtual address
    of a naturally aligned quadword into which the service returns
    the length of the virtual address range mapped in bytes.

    Upon successful completion of this service, the value in the
    return_length_64 argument might differ from the total amount
    of virtual address space mapped. The value in the return_va_64
    argument plus the value in the return_length_64 argument
    indicates the address of the first byte beyond the end of the
    mapping of the global disk file section.

    If the value in the section_offset_64 argument plus the value in
    the length_64 argument did not specify to map the entire global
    section, this byte can be located at an even virtual disk block
    boundary within the last page of the mapping.

    If the section being mapped does not completely fill the last
    page used to represent the global disk file section, this byte
    can be mapped into your address space; however, it is not backed
    up by the disk file.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address to which to map the global section.
    The specified virtual address must be a CPU-specific page-aligned
    address. If the flag SEC$M_EXPREG is specified, the start_va_64
    argument must not be specified or must be specified as 0. If
    SEC$M_EXPREG is set and the start_va_64 argument is nonzero, the
    condition value SS$_IVSECFLG is returned.

    If the region_id_64 argument specifies a shared page-table
    region, start_va_64 must be aligned to a CPU-specific page-table
    page boundary.

204  –  $MGBLSC GPFN 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, establishes a
    correspondence between pages in the virtual address space of the
    process and the pages occupied by a global page frame section.

    This service accepts 64-bit addresses.

    Format

      SYS$MGBLSC_GPFN_64  gs_name_64 ,ident_64 ,region_id_64

                          ,relative_page ,page_count ,acmode

                          ,flags ,return_va_64 ,return_length_64

                          [,start_va_64]

    C Prototype

      int sys$mgblsc_gpfn_64  (void *gsdnam_64, struct _secid

                              *ident_64, struct _generic_64

                              *region_id_64, unsigned int

                              relative_page, unsigned int

                              page_count, unsigned int

                              acmode, unsigned int flags, void

                              *(*(return_va_64)), unsigned __int64

                              *return_length_64,...);

204.1  –  Arguments

 gs_name_64

    OpenVMS usage:section_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Name of the global section. The gs_name argument is the 32- or
    64-bit virtual address of a naturally aligned 32-bit or 64-bit
    descriptor pointing to this name string.

    You can specify any name from 1 to 43 characters. All processes
    mapping to the same global section must specify the same name.
    Note that the name is case sensitive.

    Use of characters valid in logical names is strongly encouraged.
    Valid values include alphanumeric characters, the dollar sign
    ($), and the underscore (_). If the name string begins with an
    underscore (_), the underscore is stripped and the resultant
    string is considered to be the actual name. Use of the colon (:)
    is not permitted.

    Names are first subject to a logical name translation, after
    the application of the prefix GBL$ to the name. If the result
    translates, it is used as the name of the section. If the
    resulting name does not translate, the name specified by the
    caller is used as the name of the section.

    Additional information on logical name translations and
    on section name processing is available in the VSI OpenVMS
    Programming Concepts Manual.

 ident_64

    OpenVMS usage:section_id
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Identification value specifying the version number of a global
    section. The ident_64 argument is a quadword containing three
    fields. The ident_64 argument is the 32- or 64-bit virtual
    address of a naturally aligned quadword that contains the
    identification value.

    The first longword specifies the matching criteria in its low-
    order two bits. The valid values, symbolic names by which they
    can be specified, and their meanings are as follows:

           Symbolic
    Value  Name           Match Criteria

    0      SEC$K_MATALL   Match all versions of the section.
    1      SEC$K_MATEQU   Match only if major and minor
                          identifications match.
    2      SEC$K_MATLEQ   Match if the major identifications are
                          equal and the minor identification of the
                          mapper is less than or equal to the minor
                          identification of the global section.

    If you specify the ident_64 argument as 0, the version number and
    match control fields default to 0.

    The version number is in the second longword. The version number
    contains two fields: a minor identification in the low-order 24
    bits and a major identification in the high-order 8 bits. You
    can assign values for these fields by installation convention to
    differentiate versions of global sections. If no version number
    is specified when a section is created, processes that specify a
    version number when mapping cannot access the global section.

 region_id_64

    OpenVMS usage:region identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The region ID associated with the region to map the private page
    frame section. The file VADEF.H in SYS$STARLET_C.TLB and the
    $VADEF macro in STARLET.MLB define a symbolic name for each of
    the three default regions in P0, P1, and P2 space.

    The following region IDs are defined:

    Symbol     Region

    VA$C_P0    Program region
    VA$C_P1    Control region
    VA$C_P2    64-bit program region

    Other region IDs, as returned by the $CREATE_REGION_64 service,
    can be specified.

 relative_page

    OpenVMS usage:CPU-specific page count
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Relative CPU-specific page number within the global section to
    start mapping.

 page_count

    OpenVMS usage:CPU-specific page count
    type:         longword (unsigned) on Alpha, quadword (unsigned)
                  on Integrity servers
    access:       read only
    mechanism:    by value
    Length of mapping in CPU-specific pages. If zero is specified,
    the global page frame section is mapped to the end of the
    section.

 acmode

    OpenVMS usage:access-mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be associated with the pages mapped into the
    process virtual address space. The acmode argument is a longword
    containing the access mode. The $PSLDEF macro defines symbols for
    the four access modes.

    The most privileged access mode used is the access mode of the
    caller. Address space cannot be created within a region that has
    a create mode associated with it that is more privileged than
    the caller's mode. The condition value SS$_IVACMODE is returned
    if the caller is less privileged than the create mode for the
    region.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying options for the operation. The flags
    argument is a longword bit vector in which each bit corresponds
    to a flag. The $SECDEF macro and the SECDEF.H file define a
    symbolic name for each flag. You construct the flags argument
    by performing a logical OR operation on the symbol names for all
    desired flags.

    The following table describes each flag that is valid for the
    $MGBLSC_GPFN_64 service:

    Flag          Description

    SEC$M_ARGS64  Indicates that all parameters, specifically start_
                  pfn and page_count, are passed as 64-bit numbers.
                  This flag is ignored on OpenVMS Alpha but must be
                  set on Integrity server systems. If the flag is
                  not set on Integrity servers, the error code SS$_
                  IVSECFLG is returned.

    SEC$M_GBL     Pages form a global section. By default, this flag
                  is always present in this service and cannot be
                  disabled.

    SEC$M_EXPREG  Map the section into the first available space at
                  the current end of the specified region. If this
                  flag is specified, the start_va_64 argument is not
                  used.

    SEC$M_PERM    Pages are permanent. By default, this flag is
                  always present in this service and cannot be
                  disabled.

    SEC$M_PFNMAP  Pages form a page frame section. By default, this
                  flag is always present in this service and cannot
                  be disabled.

    SEC$M_PAGFIL  Pages form a global page-file section. SEC$M_PAGFIL
                  also implies SEC$M_WRT and SEC$M_DZRO.

    SEC$M_SYSGBL  Map a system global section. By default, the
                  section is a group global section.

    SEC$M_        Flag accepted but ignored on Integrity server
    UNCACHED      systems. The cached/uncached characteristic is
                  stored as a section attribute, and the system uses
                  this attribute when the section is mapped. Refer to
                  this flag in the documentation of the SYS$CREATE_
                  GPFN system service.

    SEC$M_WRT     Map the section with read/write access. By default,
                  the section is mapped with read-only access. If
                  SEC$M_WRT is specified, write access is required.

    All other bits in the flags argument are reserved for future
    use by VSI and should be specified as 0. The condition value
    SS$_IVSECFLG is returned if any undefined bits are set or if
    an illegal combination of flags is set.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address into which the global page
    frame section was mapped. The return_va_64 argument is the 32-
    or 64-bit virtual address of a naturally aligned quadword that
    contains the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The 32- or 64-bit virtual address of a naturally aligned quadword
    into which the $MGBLSC_GPFN_64 service returns the length of the
    virtual address range in bytes.

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address to map the global section. The
    specified virtual address must be a CPU-specified page-aligned
    address. If the flag SEC$M_EXPREG is specified, the start_va_64
    argument must not be specified or must be specified as 0. If
    SEC$M_EXPREG is set and the start_va_64 argument is nonzero, the
    condition value SS$_IVSECFLG is returned.

    Always refer to the return_va_64 and return_length_64 arguments
    to determine the range of virtual addresses mapped.

205  –  $MOD HOLDER

    Modifies the specified holder record of the target identifier in
    the rights database.

    Format

      SYS$MOD_HOLDER  id ,holder ,[set_attrib] ,[clr_attrib]

    C Prototype

      int sys$mod_holder  (unsigned int id, struct _generic_64

                          *holder, unsigned int set_attrib, unsigned

                          int clr_attrib);

205.1  –  Arguments

 id

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Binary value of target identifier whose holder record is modified
    when $MOD_HOLDER completes execution. The id argument is a
    longword containing the identifier value.

 holder

    OpenVMS usage:rights_holder
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Identifier of holder being modified when $MOD_HOLDER completes
    execution. The holder argument is the address of a quadword
    containing the UIC identifier of the holder in the first longword
    and the value of 0 in the second longword.

 set_attrib

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Bit mask of attributes to be enabled for the identifier when
    $MOD_HOLDER completes execution. The set_attrib argument is a
    longword containing the attribute mask.

    The attributes actually enabled are the intersection of those
    specified and the attributes of the identifier. If you specify
    the same attribute in set_attrib and clr_attrib, the attribute is
    enabled.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The following symbols
    for each bit position are defined in the system macro library
    ($KGBDEF):

    Bit Position    Meaning When Set

    KGB$V_DYNAMIC   Allows holders of the identifier to remove it
                    from or add it to the process rights list by
                    using the DCL command SET RIGHTS_LIST.

    KGB$V_          Makes any access rights of the identifier
    NOACCESS        null and void. This attribute is intended as
                    a modifier for a resource identifier or the
                    Subsystem attribute.

    KGB$V_          Allows the holder to charge resources, such as
    RESOURCE        disk blocks, to the identifier.

    KGB$V_          Allows holders of the identifier to create and
    SUBSYSTEM       maintain protected subsystems by assigning the
                    Subsystem ACE to the application images in the
                    subsystem.

 clr_attrib

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Bit mask of attributes to be disabled for the identifier when
    $MOD_HOLDER completes execution. The clr_attrib argument is a
    longword containing the attribute mask.

    If you specify the same attribute in set_attrib and clr_attrib,
    the attribute is enabled.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The following symbols
    for each bit position are defined in the system macro library
    ($KGBDEF):

    Bit Position    Meaning When Set

    KGB$V_DYNAMIC   Allows holders of the identifier to remove it
                    from or add it to the process rights list by
                    using the DCL command SET RIGHTS_LIST.
    KGB$V_          Makes any access rights of the identifier
    NOACCESS        null and void. This attribute is intended as
                    a modifier for a resource identifier or the
                    Subsystem attribute.

    KGB$V_          Allows the holder to charge resources, such as
    RESOURCE        disk blocks, to the identifier.

    KGB$V_          Allows holders of the identifier to create and
    SUBSYSTEM       maintain protected subsystems by assigning the
                    Subsystem ACE to the application images in the
                    subsystem.

206  –  $MOD IDENT

    Modifies the specified identifier record in the rights database.

    Format

      SYS$MOD_IDENT  id ,[set_attrib] ,[clr_attrib] ,[new_name]

                     ,[new_value]

    C Prototype

      int sys$mod_ident  (unsigned int id, unsigned int set_attrib,

                         unsigned int clr_attrib, void *new_name,

                         unsigned int new_value);

206.1  –  Arguments

 id

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Binary value of identifier whose identifier record is modified
    when $MOD_IDENT completes execution. The id argument is a
    longword containing the identifier value.

 set_attrib

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Bit mask of attributes to be enabled for the identifier when
    $MOD_IDENT completes execution. The set_attrib argument is a
    longword containing the attribute mask.

    The attributes actually enabled are the intersection of those
    specified and the attributes of the identifier. If you specify
    the same attribute in set_attrib and clr_attrib, the attribute is
    enabled.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The following symbols
    for each bit position are defined in the system macro library
    ($KGBDEF):

    Bit Position           Meaning When Set

    KGB$V_DYNAMIC          Allows holders of the identifier to remove
                           it from or add it to the process rights
                           list by using the DCL command SET_RIGHTS_
                           LIST.
    KGB$V_HOLDER_HIDDEN    Prevents someone from getting a list of
                           users who hold an identifier, unless they
                           own the identifier themselves.
    KGB$V_NAME_HIDDEN      Allows holders of an identifier to have it
                           translated-either from binary to ASCII or
                           vice versa-but prevents unauthorized users
                           from translating the identifier.
    KGB$V_NOACCESS         Makes any access rights of the identifier
                           null and void. This attribute is intended
                           as a modifier for a resource identifier or
                           the Subsystem attribute.
    KGB$V_RESOURCE         Allows holders of an identifier to charge
                           disk space to the identifier. It is used
                           only for file objects.
    KGB$V_SUBSYSTEM        Allows holders of the identifier to
                           create and maintain protected subsystems
                           by assigning the Subsystem ACE to the
                           application images in the subsystem.

 clr_attrib

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Bit mask of attributes to be disabled for the identifier when
    $MOD_IDENT completes execution. The clr_attrib argument is a
    longword containing the attribute mask.

    If you specify the same attribute in set_attrib and clr_attrib,
    the attribute is enabled.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The following symbols
    for each bit position are defined in the system macro library
    ($KGBDEF):

    Bit Position           Meaning When Set

    KGB$V_DYNAMIC          Allows holders of the identifier to remove
                           it from or add it to the process rights
                           list by using the DCL command SET_RIGHTS_
                           LIST.
    KGB$V_HOLDER_HIDDEN    Prevents someone from getting a list of
                           users who hold an identifier, unless they
                           own the identifier themselves.
    KGB$V_NAME_HIDDEN      Allows holders of an identifier to have it
                           translated-either from binary to ASCII or
                           vice versa-but prevents unauthorized users
                           from translating the identifier.
    KGB$V_NOACCESS         Makes any access rights of the identifier
                           null and void. This attribute is intended
                           as a modifier for a resource identifier or
                           the Subsystem attribute.
    KGB$V_RESOURCE         Allows holders of an identifier to charge
                           disk space to the identifier. It is used
                           only for file objects.
    KGB$V_SUBSYSTEM        Allows holders of the identifier to
                           create and maintain protected subsystems
                           by assigning the Subsystem ACE to the
                           application images in the subsystem.

 new_name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    New name to be given to the specified identifier. The new_
    name argument is the address of the descriptor pointing to the
    identifier name string.

    An identifier name consists of 1 to 31 alphanumeric characters,
    including dollar signs ($)  and underscores (_), and must contain
    at least one nonnumeric character. Any lowercase characters
    specified are automatically converted to uppercase.

 new_value

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    New value to be assigned to the specified identifier. The new_
    value argument is a longword containing the binary value of the
    specified identifier. When the identifier value is changed, $MOD_
    IDENT also changes the value of the identifier in all of the
    holder records in which the specified identifier appears.

207  –  $MOUNT

    Mounts a tape, disk volume, or volume set and specifies options
    for the mount operation.

    Format

      SYS$MOUNT  itmlst

    C Prototype

      int sys$mount  (void *itmlst);

207.1  –  Argument

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying options for the mount operation. The itmlst
    argument is the address of a list of item descriptors, each of
    which specifies an option and provides the information needed to
    perform the operation.

    The item list must include at least one device item descriptor
    and is terminated by a longword value of 0.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

208  –  $MTACCESS

    Allows installations to provide their own routine to interpret
    and output the accessibility field in the VOL1 and HDR1 labels of
    an ANSI labeled magnetic tape.

    Format

      SYS$MTACCESS  lblnam ,[uic] ,[std_version] ,[access_char]

                    ,[access_spec] ,type

    C Prototype

      int sys$mtaccess  (unsigned int *lblnam, unsigned int uic,

                        unsigned int std_version, unsigned int

                        access_char, unsigned int access_spec,

                        unsigned int type);

208.1  –  Arguments

 lblnam

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    ANSI label to be processed. The lblnam argument is the address
    of a longword containing the label. On input, the label passed
    is either the VOL1 or HDR1 label read from the magnetic tape; on
    output of labels, the value of this field is 0. The type of label
    passed is determined by type.

 uic

    OpenVMS usage:uic
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    UIC of the user performing the operation. The uic argument is a
    longword containing the UIC.

 std_version

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Decimal equivalent of the ANSI standard version read from the
    VOL1 label. The std_version argument is a longword containing the
    standard version number.

 access_char

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Accessibility character specified by the user. The access_char
    argument is a byte containing the accessibility character used
    for the output of labels.

 access_spec

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Value specifying whether the accessibility character passed in
    access_char was specified by the user.

    The access_spec argument is a byte containing one of the
    following values:

    Value            Meaning

    MTA$K_           Yes
    CHARVALID
    MTA$K_NOCHAR     No

    This argument is used only for the output of labels.

 type

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Type of accessibility field to process.

    The type argument is a byte containing one of the following
    values:

    Value            Meaning

    MTA$K_INVOL1     Input a VOL1 label
    MTA$K_INHDR1     Input a HDR1 label
    MTA$K_OUTVOL1    Output a VOL1 label
    MTA$K_OUTHDR1    Output a HDR1 label

209  –  $NUMTIM

    Converts an absolute or delta time from 64-bit system time format
    to binary integer date and time values.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$NUMTIM  timbuf ,[timadr]

    C Prototype

      int sys$numtim  (unsigned short int timbuf [7], struct

                      _generic_64 *timadr);

209.1  –  Arguments

 timbuf

    OpenVMS usage:vector_word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Buffer into which $NUMTIM writes the converted date and time.
    The timbuf argument is the 32- or 64-bit address (on Alpha and
    Integrity server systems) of a 7-word structure.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the diagram of the fields in this structure.

    If the timadr argument specifies a delta time, $NUMTIM returns
    the value 0 in the year since 0 and month of year fields. It
    returns in the day of month field the number of days specified by
    the delta time.

 timadr

    OpenVMS usage:date_time
    type:         quadword
    access:       read only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    The 64-bit time value to be converted. The timadr argument is the
    32- or 64-bit address (on Alpha and Integrity server systems) of
    a quadword containing this time. A positive-time value represents
    an absolute time, while a negative time value indicates a delta
    time.

    If you do not specify timadr, $NUMTIM returns the current system
    time.

    If timadr specifies the value 0, $NUMTIM returns the base date
    (November 17, 1858).

210  –  $NUMUTC

    Converts an absolute 128-bit binary time into its numeric
    components. The numeric components are returned in local time.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$NUMUTC  timbuf ,[utcadr]

    C Prototype

      int sys$numutc  (unsigned short int timbuf [13], unsigned int

                      *utcadr [4]);

210.1  –  Arguments

 timbuf

    OpenVMS usage:vector_word_unsigned
    type:         word
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Buffer into which $NUMUTC writes the converted date and time.
    The timbuf argument is the 32- or 64-bit address (on Alpha and
    Integrity server systems) of a 13-word structure containing
    time, inaccuracy of time, and time differential factor. The time
    differential factor encoded in the 128-bit buffer is used to
    convert the UTC to its numerical components. Negative values in
    the inaccuracy field indicate an infinite inaccuracy.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the diagram of the fields in this structure.

 utcadr

    OpenVMS usage:coordinated universal time
    type:         utc_date_time
    access:       read only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    The 128-bit UTC time value to be converted.

    The utcadr argument is optional; if it is not used, $NUMUTC will
    use the current time.

211  –  $NXTVOL

    The Next Volume service allows you to process the next tape
    volume in a multiple volume set. This service applies only to
    files on magnetic tape volumes.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

212  –  $OPEN

    The Open service makes an existing file available for processing
    by your program. The Open service specifies the type of record
    access to be used and determines whether the file can be shared.
    The Open service also performs an implicit Display service.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

213  –  $PARSE

    The Parse service analyzes the file specification string and
    fills in various NAM block fields.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

214  –  $PARSE ACL

    Parses the specified text string and converts it to the binary
    representation for an access control entry (ACE).

    Format

      SYS$PARSE_ACL  aclstr ,aclent ,[errpos] ,[accnam] ,[nullarg]

    C Prototype

      int sys$parse_acl  (void *aclstr, void *aclent, unsigned

                         short int *errpos, void *accnam, int

                         (*routin)(void));

214.1  –  Arguments

 aclstr

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Formatted ACE that is parsed when $PARSE_ACL completes execution.
    The aclstr argument is the address of a string descriptor
    pointing to the text string to be parsed.

 aclent

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Description of the ACE that is parsed when $PARSE_ACL completes
    execution. The aclent argument is the address of a descriptor
    pointing to the buffer in which the ACE is written. The first
    byte of the buffer contains the length of the ACE; the second
    byte contains a value that identifies the type of ACE, which in
    turn defines the format of the ACE.

    For information about the ACE types and their associated formats,
    see $FORMAT_ACL system service documentation.

 errpos

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Number of characters from aclstr processed by $PARSE_ACL. The
    errpos argument is the address of a word that receives the number
    of characters actually processed by the service. If the service
    fails, this count points to the failing point in the string.

 accnam

    OpenVMS usage:access_bit_names
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Names of the bits in the access mask when $PARSE_ACL is
    executing. The accnam argument is the address of an array of
    32 quadword descriptors that define the names of the bits in the
    access mask. Each element points to the name of a bit. The first
    element names bit 0, the second element names bit 1, and so on.

    You can call LIB$GET_ACCNAM to retrieve the access name table
    for the class of object whose ACL is to be formatted. If you omit
    accnam, the following names are used:

    Bit    Name

    Bit 0  READ
    Bit 1  WRITE
    Bit 2  EXECUTE
    Bit 3  DELETE
    Bit 4  CONTROL
    Bit 5  BIT_5
    Bit 6  BIT_6
    .
    .
    .
    Bit    BIT_31
    31

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

215  –  $PERM DIS ALIGN FAULT REPORT (Alpha and Integrity servers)

    On Alpha and Integrity server systems, disables user process
    alignment fault reporting.

    Format

      SYS$PERM_DIS_ALIGN_FAULT_REPORT

    C Prototype

      int sys$perm_dis_align_fault_report  (void);

215.1  –  Arguments

    None.

216  –  $PERM REPORT ALIGN FAULT (Alpha and Integrity servers)

    On Alpha and Integrity server systems, initializes user process
    alignment fault reporting.

    Format

      SYS$PERM_REPORT_ALIGN_FAULT

    C Prototype

      int sys$perm_report_align_fault  (void);

216.1  –  Arguments

    None.

217  –  $PERSONA ASSUME (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows an OpenVMS thread
    to assume the identity of another persona.

    Format

      SYS$PERSONA_ASSUME  persona ,[flags], [previous], [acmode]

    C Prototype

      int sys$persona_assume  (unsigned int *persona, unsigned int

                              flags, unsigned int *previous, unsigned

                              int acmode);

217.1  –  Arguments

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword in which the persona identification handle
    is expected.

    If the value passed is ISS$C_ID_NATURAL, then the state of the
    calling thread is returned to the natural persona.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Ignored.

 previous

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of a longword into which the persona identification
    handle of the currently active persona being replaced is written.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be considered when assuming a persona. The acmode
    argument is a longword containing the access mode.

    The most privileged access mode used is the access mode of the
    caller. Only equal or more privileged access modes can use this
    persona.

218  –  $PERSONA CLONE (Alpha and Integrity servers)

    On Alpha and Integrity server systems, creates a copy of an
    existing persona within the context of the current process. The
    service returns the assigned persona identification for the new
    persona in the persona argument. This persona can be assumed
    using the $PERSONA_ASSUME service.

    Format

      SYS$PERSONA_CLONE  persona ,[input]

    C Prototype

      int sys$persona_clone  (unsigned int *persona, unsigned int

                             *input);

218.1  –  Arguments

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of a longword into which the persona identification
    handle is written.

 input

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of a longword containing the persona identification of
    the persona to be cloned. If this argument is 0, null, or absent,
    the currently active persona is cloned.

219  –  $PERSONA CREATE (Alpha and Integrity servers)

    On Alpha and Integrity server systems, creates a persona that can
    be assumed using the $PERSONA_ASSUME service.

    Format

      SYS$PERSONA_CREATE  persona ,[usrnam] ,[flags], [usrpro],

                          [itmlst]

    C Prototype

      int sys$persona_create  (unsigned int *persona, void *usrnam,

                              unsigned int flags, unsigned int

                              *usrpro, unsigned int *itmlst);

219.1  –  Arguments

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of a longword into which the persona identification
    handle is written.

 usrnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length descriptor
    Name of the user to be impersonated. The usrnam argument is
    the address of a descriptor pointing to a character string
    containing the user name. The string can contain a maximum of
    32 alphanumeric characters.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The $ISSDEF macro defines these codes:

    o  ISS$V_CREATE_AUTHPRIV - This bit is used to create a persona
       with the privilege fields set to the authorized privileges of
       the specified user.

    o  ISS$V_CREATE_DEFPRIV - This bit is used for backward
       compatibility with the previous implementation of personae.
       This bit is accepted but not processed, as it describes the
       default behavior of the service.

    o  ISS$V_NOACCESS - Tells $PERSONA_CREATE not to access the
       SYSUAF file. Only valid in exec or kernel mode.

 usrpro

    OpenVMS usage:char_string
    type:         opaque byte stream
    access:       read only
    mechanism:    by descriptor
    Buffer containing an encoded security profile. The usrpro
    argument is the address of a descriptor pointing to a buffer
    that contains encoded security profile data. This profile can be
    created by calling the SYS$CREATE_USER_PROFILE system service.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword
    access:       read only
    mechanism:    by reference
    Attributes describing modifications to the security profile. The
    itmlst argument is the address of an item_list defining changes
    to be made to the specified user profile.

220  –  $PERSONA CREATE EXTENSION (Alpha and Integrity servers)

    On Alpha and Integrity server systems, creates an extension on
    the current persona. A persona extension is a mechanism to attach
    support for additional security credentials.

    Format

      SYS$PERSONA_CREATE_EXTENSION  persona ,extensionID ,buffer

                                    ,length ,flags

    C Prototype

      int sys$persona_create_extension  (unsigned int *persona,

                                        unsigned int *extensionID,

                                        void *buffer, unsigned

                                        int *length, unsigned int

                                        *flags);

220.1  –  Arguments

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing the persona identification to
    which $PERSONA_CREATE_EXTENSION attaches a new persona extension.

    Two special values for persona are also permitted: 0, which means
    the current persona, and -1, which means the process' natural
    persona is used.

 extensionID

    OpenVMS usage:extension_ID
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing the extension identification
    (EID) for which the registered CREATE routine will be called to
    create a new persona extension block.

 buffer

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a buffer containing data to be used in creating the
    persona extension data structure. The interpretation of the
    data within this buffer is the responsibility of the extension
    create routine. For example, this data could be a Type-Length-
    Value (TLV) structure containing fields in the extension data
    structure. Specifying this buffer is optional; a caller who does
    not want to supply a buffer should specify an address of zero
    (0).

 length

    OpenVMS usage:size
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing the size, in bytes, of the
    buffer argument. Specifying length is optional; a caller who
    does not want to supply a length should specify an address of
    zero (0). Specifying a buffer without a length is the same as not
    specifying a buffer.

 flags

    OpenVMS usage:flags
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Flag mask specifying the options to be employed when the persona
    extension is created. Specifying flags is optional; a caller who
    does not want to supply flags should specify an address of zero
    (0).

    Flag       Description

    PXB$V_     This extension is recorded as the persona's primary
    PRIMARY_   extension. If a persona already has a primary
    EXTENSION  extension, the error SS$_UNSUPPORTED is returned and
               the extension is not created. The primary extension is
               returned when the persona is queried for its "Primary
               Extension." There is no other meaning for this value.

221  –  $PERSONA DELEGATE (Alpha and Integrity servers)

    On Alpha and Integrity server systems, delegates or assigns the
    currently active persona to another process.

    Format

      SYS$PERSONA_DELEGATE  serverPID ,persona ,input

    C Prototype

      int sys$persona_delegate  (unsigned int *serverPID, unsigned

                                int *persona, unsigned int *input);

221.1  –  Arguments

 serverPID

    OpenVMS usage:process_ID
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing the extended process
    identification (PID) of the server process to which $PERSONA_
    DELEGATE grants the current persona.

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing the identification that the
    $PERSONA_RESERVE service reserved in the server's process for
    this client's persona.

 input

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing the persona identification that
    describes which persona is delegated to the server. If the input
    argument is zero (0) or null, or if the input value is zero (0),
    the current persona is delegated. If the input value is -1, then
    the natural persona of the process is delegated.

222  –  $PERSONA DELETE

    Deletes a persona created using the $PERSONA_CREATE, the
    $PERSONA_CLONE, or the $PERSONA_RESERVE service.

    Format

      SYS$PERSONA_DELETE  persona

    C Prototype

      int sys$persona_delete  (unsigned int *persona);

222.1  –  Arguments

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword in which the persona identification handle
    is expected.

223  –  $PERSONA DELETE EXTENSION (Alpha and Integrity servers)

    On Alpha and Integrity server systems, deletes an extension
    attached to a persona.

    Format

      SYS$PERSONA_DELETE_EXTENSION  persona ,extensionID

    C Prototype

      int sys$persona_delete_extension  (unsigned int *persona,

                                        unsigned int *extensionID);

223.1  –  Arguments

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing the persona identification for
    which $PERSONA_DELETE_EXTENSION calls the registered Extension
    Delete function.

 extensionID

    OpenVMS usage:extension_ID
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing the extension identification
    (EID) for which the registered DELETE routine is called in order
    to delete a persona extension block from the specified persona.

224  –  $PERSONA EXTENSION LOOKUP (Alpha and Integrity servers)

    On Alpha and Integrity server systems, translates a text name
    of an extension (for example, VMS or NT) into an extension
    identification (EID) that can be used in other persona-related
    system services.

    Format

      SYS$PERSONA_EXTENSION_LOOKUP  extensionName ,extensionID

    C Prototype

      int sys$persona_extension_lookup  (void *extensionName,

                                        unsigned int *extensionID);

224.1  –  Arguments

 extensionName

    OpenVMS usage:extension_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length descriptor
    Address of a character string descriptor pointing to the name of
    the extension being looked up.

 extensionID

    OpenVMS usage:extension_ID
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of a longword into which the value of the extension
    identification (EID) returned by the service is written.

225  –  $PERSONA FIND (Alpha and Integrity servers)

    On Alpha and Integrity server systems, enables the caller to find
    the personae within a process that have certain attributes or
    settings.

    Format

      SYS$PERSONA_FIND  persona ,itmlst ,contxt

    C Prototype

      int sys$persona_find  (unsigned int *persona, void *itmlst,

                            unsigned int *contxt);

225.1  –  Arguments

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of a longword into which the persona identification that
    matches all of the items present in the item list is written.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Attributes specifying which information about the persona is
    to be compared. The itmlst argument is the address of a list of
    item descriptors, each describing an item of information or an
    item list processing directive. The list of item descriptors is
    terminated by a longword value of 0.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

 contxt

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Context value used when repeatedly calling $PERSONA_FIND. The
    contxt argument is the address of a longword used while $PERSONA_
    FIND searches for all personae that match the criteria. The
    context value must be initialized to zero, and the resulting
    context of each call to $PERSONA_FIND must be presented to each
    subsequent call. After contxt is passed to $PERSONA_FIND, you
    must not modify its value.

226  –  $PERSONA MODIFY (Alpha and Integrity servers)

    On Alpha and Integrity server systems, sets attribute values for
    a persona.

    Format

      SYS$PERSONA_MODIFY  persona ,itmlst

    C Prototype

      int sys$persona_modify  (unsigned int *persona, void *itmlst);

226.1  –  Arguments

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing the persona identification for
    which this service is to set information.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Attributes specifying which information in the persona is to
    be modified. The itmlst argument is the address of a list of
    item descriptors, each describing an item of information or an
    item list processing directive. The list of item descriptors is
    terminated by a longword value of 0.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

227  –  $PERSONA QUERY (Alpha and Integrity servers)

    On Alpha and Integrity server systems, retrieves attribute values
    from a persona (and accompanying extensions).

    Format

      SYS$PERSONA_QUERY  persona ,itmlst

    C Prototype

      int sys$persona_query  (unsigned int *persona, void *itmlst);

227.1  –  Arguments

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword into which the persona identification
    handle is written.

    Two special values for persona are also permitted: 0, which means
    use the current persona, and -1, which means use the process'
    natural persona.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Attributes describing which information about the persona is to
    be returned. The itmlst argument is the address of a list of item
    descriptors, each of which describes an item of information or an
    item list processing directive. The list of item descriptors is
    terminated by a longword value of 0.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

228  –  $PERSONA RESERVE (Alpha and Integrity servers)

    On Alpha and Integrity server systems, reserves a persona ID
    in the server's persona table to be filled in by the $PERSONA_
    DELEGATE system service.

    Format

      SYS$PERSONA_RESERVE  clientPID ,persona

    C Prototype

      int sys$persona_reserve  (unsigned int *clientPID, unsigned int

                               *persona);

228.1  –  Arguments

 clientPID

    OpenVMS usage:process_ID
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing the External Process
    Identification (EPID) of the client process for which the server
    is reserving the slot.

 persona

    OpenVMS usage:persona
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of a longword into which the persona identification
    is written. This service sets aside the identification for the
    client's to-be-delegated persona.

229  –  $POWER CONTROL

    Manipulates the platform's power and performance settings to the
    value specified in the power_setting parameter. This applies to
    the entire system just as though commanded through the Integrated
    Lights-Out (iLO) web interface.

    Format

      SYS$POWER_CONTROL  power_setting, current_value

    C Prototype

      int sys$power_control  unsigned __int64 power_setting, unsigned

                             __int64 *current_value;

229.1  –  Arguments

 power_setting

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 64-bit value
    A quadword value to specify the new power or performance setting.

 current_value

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 64-bit value
    The address of a quadword for the service to return the current
    setting (optional).

230  –  $PROCESS AFFINITY (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows modification of the
    CPU affinity set for a specified kernel thread.

    This service accepts 64-bit addresses.

    Format

      SYS$PROCESS_AFFINITY  [pidadr], [prcnam], [select_mask],

                            [modify_mask], [prev_mask], [flags]

                            [,[mask_length]]

    C Prototype

      int sys$process_affinity  (unsigned int *pidadr, void *prcnam,

                                struct _generic_64 *select_mask,

                                struct _generic_64 *modify_mask,

                                struct _generic_64 *prev_mask, struct

                                _generic_64 *flags,...);

230.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Process identification (PID) of a kernel thread whose affinity
    mask is to be modified or returned. The pidadr argument is the
    32- or 64-bit address of a longword that contains the PID.

    Process selection is made through a combination of the pidadr
    and prcnam arguments. If neither are specified or if both have a
    zero value, the service operations are made to the user affinity
    mask of the current kernel thread of the calling process. The
    pidadr argument takes precedence over the prcnam argument in any
    circumstances where both are supplied in the service call.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Process name of the process whose affinity mask is to be modified
    or returned. The prcnam argument is the 32- or 64-bit address
    of a character string descriptor pointing to the process name
    string. A process can be identified with a 1- to 15-character
    string. The service operations are made to the user affinity mask
    of the initial thread of the specified process.

    If pidadr and prcnam are both specified, then pidadr is modified
    or returned and prcnam is ignored. If neither argument is
    specified, then the context of the current kernel thread of the
    calling process is modified or returned.

 select_mask

    OpenVMS usage:bitmap
    type:         quadword bitmap
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The select-mask argument specifies which bits of the specified
    process's affinity mask are to be modified. The select_mask
    argument is the 32- or 64-bit address of a quadword bit vector
    wherein a bit, when set, specifies that the corresponding CPU
    position in the mask is to be modified.

 modify_mask

    OpenVMS usage:bitmap
    type:         quadword bitmap
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Mask specifying the settings for those explicit affinities
    selected in the select_mask argument. The modify_mask argument is
    the 32- or 64-bit address of a quadword bit vector wherein a bit,
    when set, specifies that the corresponding CPU is to be added to
    the specified process affinity set; when clear, the corresponding
    CPU is to be removed from the specified process affinity set.

    To add a specific CPU to the affinity mask set, that bit position
    must be set in both select_mask and modify_mask. To remove a
    specific CPU from the affinity mask set, that bit position must
    be set in select_mask and clear in modify_mask.

    The constant CAP$K_ALL_CPU_ADD, when specified in modify_mask,
    indicates that all CPUs specified in select_mask are to be added
    to the affinity mask set. The constant CAP$K_ALL_CPU_REMOVE
    indicates that all CPUs in select_mask are to be removed from
    the affinity mask set.

 prev_mask

    OpenVMS usage:bitmap
    type:         quadword bitmap
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Previous CPU affinity mask for the specified kernel thread before
    execution of this call to $PROCESS_AFFINITY. The prev_mask
    argument is the 32- or 64-bit address of a quadword into which
    $PROCESS_AFFINITY writes the previous explicit affinity bitmap.

 flags

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Options selected for affinity modification. The flags argument
    is a quadword bit vector wherein a bit corresponds to an option.
    Only the bits specified below are used; the remainder of the
    quadword bits are reserved and must be 0.

    Each option (bit) has a symbolic name, which the $CAPDEF macro
    defines. The flags argument is constructed by performing a
    logical OR operation using the symbolic names of each desired
    option.

    The following table describes the symbolic name of each option:

    Symbolic Name          Description

    CAP$M_FLAG_PERMANENT   Indicates whether to modify the permanent
                           process affinities in addition to the
                           current image copy. If CAP$M_FLAG_
                           PERMANENT is set, then both the permanent
                           and current affinities are modified.
                           If the flag bit is clear or flags is
                           unspecified, then just the current image
                           process affinities are modified.

                           This bit also determines which of the
                           affinity masks are returned in prev_
                           mask. If set, the permanent mask, used
                           to reinitialize the current set at image
                           rundown, is returned. If the bit is clear
                           or the flags argument is not specified,
                           the current running mask is returned.

    CAP$M_FLAG_CHECK_CPU   Determines whether the kernel thread
                           can be left in a nonrunnable state under
                           some circumstances. No operation of this
                           service will allow a transition from a
                           runnable to blocked state; however, if
                           the kernel thread is already at a blocked
                           state, this bit determines whether the
                           result of the operation must leave it
                           runnable. If CAP$M_FLAG_CHECK_CPU is set
                           or flags is unspecified, the kernel thread
                           will be checked to ensure it can safely
                           run on one of the CPUs in the active set;
                           otherwise, any valid state operations on
                           kernel threads already in a blocked state
                           will be allowed.

    CAP$M_FLAG_CHECK_CPU_  Indicates whether a check is made to
    ACTIVE                 verify that all CPUs in the select mask
                           that are about to be selected for affinity
                           binding are in the active set. This does
                           not apply to CPUs that are about to be
                           cleared from the current affinity set.
                           Unlike CAP$M_FLAG_CHECK_CPU where only
                           a single CPU has to be valid for the
                           condition to pass, CAP$M_FLAG_CHECK_
                           CPU_ACTIVE requires that all CPUs in the
                           selected set must pass the criteria.

    CAP$M_PURGE_WS_IF_     Causes the working set of the process
    NEW_RAD                to be purged if the choice of affinity
                           results in a change to the home RAD of the
                           process.

 mask_length

    OpenVMS usage:bitmap
    type:         quadword bitmap
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The mask_length specifies the length in bytes of each of the
    three bitmaps: select_mask, modify_mask, prev_mask. If mask_
    length is not supplied or specified as zero, a length of 8 bytes
    is used.

    The correct value for mask_length is determined by the number of
    supported CPUs on the system. You can compute the number of bytes
    needed for the bitmap as follows: Use the $GETSYI system service
    with an item code of SYI$_MAX_CPUS to find the minimum number of
    bits needed, round this number up to a multiple of 64, and divide
    the result by 8.

231  –  $PROCESS CAPABILITIES (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows modification of
    the user capability set for a specified kernel thread, or for the
    global user capability process default.

    This service accepts 64-bit addresses.

    Format

      SYS$PROCESS_CAPABILITIES  [pidadr] [,prcnam] [,select_mask]

                                [,modify_mask] [,prev_mask] [,flags]

    C Prototype

      int sys$process_capabilities  (unsigned int *pidadr, void

                                    *prcnam, struct _generic_64

                                    *select_mask, struct _generic_64

                                    *modify_mask, struct _generic_64

                                    *prev_mask, struct _generic_64

                                    *flags);

231.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Process identification (PID) of a kernel thread whose user
    capability mask is to be modified or returned. The pidadr
    argument is the 32- or 64-bit address of a longword that contains
    the PID.

    Process selection is made through a combination of the pidadr and
    prcnam arguments. If neither are specified or if both have a zero
    value, the service operations are made to the user capability
    mask of the current kernel thread of the calling process. The
    pidadr argument takes precedence over the prcnam argument where
    both are supplied in the service call.

    If the constant CAP$M_FLAG_DEFAULT_ONLY is specified in flags,
    then the user portion of the default process user capability
    mask is modified or returned instead, regardless of the values
    specified in pidadr.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Process name of the process whose user capability mask is to
    be modified or returned. The prcnam argument is the 32- or 64-
    bit address of a character string descriptor pointing to the
    process name string. A process can be identified with a 1- to
    15-character string. The service operations are made to the user
    capability mask of the initial thread of the specified process.

    You can use the prcnam argument only if the process identified
    by the descriptor has the same UIC group number as the calling
    process. To obtain information about processes in other groups,
    the pidadr argument must be used.

    If pidadr and prcnam are both specified, then prcnam is ignored.
    If neither argument is specified, then the context of the current
    kernel thread of the calling process is modified or returned.

 select_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Mask specifying which bits of the specified process' user
    capability mask are to be modified. The select_mask argument
    is the 32- or 64-bit address of a quadword bit vector wherein a
    bit, when set, specifies that the corresponding user capability
    is to be modified.

    The individual user capability bits in select_mask can be
    referenced by their symbolic bit constant names, CAP$M_USER1
    through CAP$M_USER16. These constants (not zero-relative) specify
    the position in the mask quadword that corresponds to the bit
    name. Multiple capabilities can be selected by ORing together the
    appropriate bits.

    Alternatively, the constant CAP$K_ALL_USER, when specified as the
    select_mask argument, selects all user capabilities.

 modify_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Mask specifying the settings for those capabilities selected in
    the select_mask argument. The modify_mask argument is the 32- or
    64-bit address of a quadword bit vector wherein a bit, when set,
    specifies that the corresponding user capability is to be added
    to the specified kernel thread; when clear, the corresponding
    user capability is to be removed.

    The symbolic bit constants CAP$M_USER1 through CAP$M_USER16 can
    be used to modify the appropriate bit position in modify_mask.
    Multiple capabilities can be modified by ORing together the
    appropriate bits.

    To add a specific user capability to a kernel thread, that bit
    position must be set in both select_mask and modify_mask. To
    remove a specific user capability from a kernel thread, that bit
    position must be set in select_mask and clear in modify_mask.

    The symbolic constant CAP$K_ALL_USER_ADD, when specified in
    modify_mask, indicates that all capabilities specified in
    select_mask are to be added to the appropriate capability set.
    The symbolic constant CAP$K_ALL_USER_REMOVE indicates that all
    specified capabilities are to be removed from the set.

 prev_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Previous user capability mask for the specified process or thread
    before execution of this call to $PROCESS_CAPABILITIES. The
    prev_mask argument is the 32- or 64-bit address of a quadword
    into which $PROCESS_CAPABILITIES writes the previous bit mask.
    If CAP$M_FLAG_DEFAULT_ONLY is set in the flags argument, then
    prev_mask will contain the user portion of the global default
    capability mask.

 flags

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Options selected for the user capability modification. The flags
    argument is a quadword bit vector wherein a bit corresponds to an
    option. Only the bits specified below are used; the remainder of
    the quadword bits are reserved and must be zero.

    Each option (bit) has a symbolic name, defined by the $CAPDEF
    macro. The flags argument is constructed by performing a logical
    OR operation using the symbolic names of each desired option.

    The following table describes the symbolic name of each option:

    Symbolic Name          Description

    CAP$M_FLAG_DEFAULT_    Indicates that the specified operations
    ONLY                   are to be performed on the global
                           context cell instead of on a specific
                           kernel thread. This bit supersedes any
                           individual kernel thread specified in
                           pidadr or prcnam. Specifying this bit
                           constant applies the service operations
                           to the capabilities for all newly created
                           processes.

    CAP$M_FLAG_PERMANENT   Indicates whether to modify the permanent
                           user process capabilities in addition to
                           the current image copy. If CAP$M_FLAG_
                           PERMANENT is set, then both the permanent
                           and current user process capabilities are
                           modified. If this bit is clear or flags is
                           unspecified, then just the current image
                           process capabilities are modified.

                           This bit also determines which of the
                           capability masks are returned in prev_
                           mask. If set, the permanent mask, used
                           to reinitialize the current set at image
                           rundown, is returned. If the bit is clear
                           or the flags argument is not specified,
                           the current running mask is returned.

    CAP$M_FLAG_CHECK_CPU   Determines whether the kernel thread can
                           be left in a nonrunnable state under some
                           circumstances. No operation of this
                           service will allow a transition from
                           runnable to blocked state; however, if
                           the kernel thread is already at a blocked
                           state, this bit determines whether the
                           result of the operation must leave it
                           runnable. If CAP$M_FLAG_CHECK_CPU is set
                           or flags is unspecified, the kernel thread
                           will be checked to ensure it can safely
                           run on one of the CPUs in the active set;
                           otherwise, any state operations on kernel
                           threads already in a blocked state will be
                           allowed.

    CAP$M_PURGE_WS_IF_     Causes the working set of the process
    NEW_RAD                to be purged if the choice of capability
                           results in a change to the home RAD of the
                           process.

232  –  $PROCESS SCAN

    Creates and initializes a process context that is used by $GETJPI
    to scan processes on the local system or across the nodes in an
    OpenVMS Cluster system.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$PROCESS_SCAN  pidctx [,itmlst]

    C Prototype

      int sys$process_scan  (unsigned int *pidctx, void *itmlst);

232.1  –  Arguments

 pidctx

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Context value supplied by $PROCESS_SCAN to be used as the pidadr
    argument of $GETJPI. The pidctx argument is the 32- or 64-bit
    address (on Alpha and Integrity server systems) of a longword
    that is to receive the process context longword. This longword
    normally contains 0 or a previous context. If it contains a
    previous context, the old context is deleted. If it contains
    a value other than 0 or a previous context, the old value is
    ignored.

 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 (Alpha and Integrity
                  servers)
    Item list specifying selection criteria to be used by the scan or
    to control the scan.

    The itmlst argument is the 32- or 64-bit address (on Alpha and
    Integrity server systems) of a list of item descriptors, each of
    which describes one selection criterion or control option. Within
    each selection criterion you can include several item entries. An
    item list in 32-bit format is terminated by a longword of 0; an
    item list in 64-bit format is terminated by a quadword of 0. All
    items in an item list must be of the same format-either 32-bit or
    64-bit.

    The information in the item list is passed to the item descriptor
    in one of two ways. If the item descriptor can always hold the
    actual value of the selection criterion, the value is placed in
    the second longword of the item descriptor and the buffer length
    is specified as 0. If the item descriptor points to the actual
    value of the selection criterion, the address of the value is
    placed in the second longword of the item descriptor and you must
    specify the buffer length for the selection criterion. Each item
    code description specifies whether the information is passed by
    value or by reference.

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

233  –  $PURGWS

    Removes a specified range of pages from the current working set
    of the calling process to make room for pages required by a new
    program segment.

    Format

      SYS$PURGWS  inadr

    C Prototype

      int sys$purgws  (struct _va_range *inadr);

233.1  –  Argument

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Starting and ending virtual addresses of the range of pages to be
    purged. The inadr argument is the address of a 2-longword array
    containing, in order, the starting and ending process virtual
    addresses. The addresses are adjusted up or down to fall on CPU-
    specific page boundaries. Only the virtual page number portion of
    each virtual address is used; the low-order byte-within-page bits
    are ignored.

234  –  $PURGE WS (Alpha and Integrity servers)

    On Alpha and Integrity server systems, removes a specified range
    of pages from the current working set of the calling process to
    make room for pages required by a new program segment.

    This service accepts 64-bit addresses.

    Format

      SYS$PURGE_WS  start_va_64 ,length_64

    C Prototype

      int sys$purge_ws  (void *start_va_64, unsigned __int64

                        length_64);

234.1  –  Arguments

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address of the pages to be purged from the
    working set. The specified virtual address will be rounded down
    to a CPU-specific page boundary.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space to be purged from the working
    set. The specified length will be rounded up to a CPU-specific
    page boundary so that it includes all CPU-specific pages in the
    requested range.

235  –  $PUT

    The Put service inserts a record into a file.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

236  –  $PUTMSG

    Writes informational and error messages to processes.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

                                   NOTE

       The return value from *actrtn is checked to determine
       whether or not the message is output.

    Format

      SYS$PUTMSG  msgvec ,[actrtn] ,[facnam] ,[actprm]

    C Prototype

      int sys$putmsg  (void *msgvec, int (*actrtn)(__unknown_params),

                      void *facnam, unsigned __int64 actprm);

236.1  –  Arguments

 msgvec

    OpenVMS usage:cntrlblk
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Message argument vector specifying the message or messages to be
    written and options that $PUTMSG is to use in writing the message
    or messages. The msgvec argument is the 32- or 64-bit address (on
    Alpha and Integrity server systems) of the message vector.

    The message vector consists of one longword followed by one or
    more message descriptors, one descriptor per message.

    To view the diagram of the contents of the first longword and the
    message vector fields table, see the VSI OpenVMS System Services
    Reference Manual.

 actrtn

    OpenVMS usage:procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    User-supplied action routine to be executed during message
    processing. The actrtn argument is the 32- or 64-bit address
    (on Alpha and Integrity server systems) of this routine.

    Note that the first argument passed to the action routine is the
    address of a character string descriptor pointing to the message
    text; the parameter specified by actprm is the second.

    The action routine receives control after a message is formatted
    but before it is actually written to the user.

    The completion code in general register R0 from the action
    routine indicates whether the message should be written. If the
    low-order bit of R0 is set (1), then the message will be written.
    If the low-order bit is cleared (0), then the message will not be
    written.

    If you do not specify actrtn or specify it as 0 (the default), no
    action routine executes.

    Because $PUTMSG writes messages only to SYS$ERROR and SYS$OUTPUT,
    an action routine is useful when output must be directed to, for
    example, a file.

 facnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor: fixed-length string
                  descriptor (Alpha and Integrity servers)
    Facility prefix to be used in the first or only message written
    by $PUTMSG. The facnam argument is the 32- or 64-bit address
    (on Alpha and Integrity server systems) of a character string
    descriptor pointing to this facility prefix.

    If you do not specify facnam, $PUTMSG uses the default facility
    prefix associated with the message.

 actprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Parameter to be passed to the action routine. The actprm argument
    is a longword value containing this parameter. If you do not
    specify actprm, no parameter is passed.

237  –  $QIO

    Queues an I/O request to a channel associated with a device. This
    service completes asynchronously; for synchronous completion, use
    the Queue I/O Request and Wait ($QIOW) service.

    Format

      SYS$QIO  [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,[p1]

               ,[p2] ,[p3] ,[p4] ,[p5] ,[p6]

    C Prototype

      int sys$qio  (unsigned int efn, unsigned short int chan,

                   unsigned int func, struct _iosb *iosb, void

                   (*astadr)(__unknown_params), __int64  astprm, void

                   *p1, __int64 p2, __int64  p3, __int64 p4, __int64

                   p5, __int64 p6);

237.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Event flag that $QIO is to set when the I/O operation completes.
    The efn argument is a longword value containing the number of the
    event flag; however, $QIO uses only the low-order byte.

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    I/O channel assigned to the device to which the request is
    directed. The chan argument is a word value containing the number
    of the I/O channel; however, $QIO uses only the low-order word.

    Specifying an invalid value for the chan argument will result in
    either SS$_IVCHAN or SS$_IVIDENT being returned.

 func

    OpenVMS usage:function_code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Device-specific function codes and function modifiers specifying
    the operation to be performed. The func argument is a longword
    containing the function code.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    I/O status block to receive the final completion status of the
    I/O operation. The iosb argument is the address of the quadword
    I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    AST service routine to be executed when the I/O completes. The
    astadr argument is the address of the AST routine.

    The AST routine executes at the access mode of the caller of
    $QIO.

 astprm

    OpenVMS usage:user_arg
    type:         quadword unsigned (Alpha and Integrity servers)
    access:       read only
    mechanism:    by 64-bit value (Alpha and Integrity servers)
    AST parameter to be passed to the AST service routine. On Alpha
    and Integrity server systems, the astprm argument is a quadword
    value containing the AST parameter.

 p1 to p6

    OpenVMS usage:varying_arg
    type:         quadword (unsigned) (Alpha and Integrity servers)
    access:       read only
    mechanism:    by 32- or 64-bit reference or by 64-bit value,
                  depending on the I/O function (Alpha and Integrity
                  servers)
    Optional device-specific and function-specific I/O request
    parameters.

238  –  $QIOW

    The Queue I/O Request and Wait service queues an I/O request to a
    channel associated with a device.

    The $QIOW service completes synchronously; however, VSI
    recommends that you use an IOSB with this service to avoid
    premature completion.

    For asynchronous completion, use the Queue I/O Request ($QIO)
    service.

    In all other respects, $QIOW is identical to $QIO. For more
    information about $QIOW, refer to the description of $QIO.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$QIOW  [efn] ,chan ,func ,[iosb] ,[astadr]

                ,[astprm] ,[p1] ,[p2] ,[p3]

                ,[p4] ,[p5] ,[p6]

    C Prototype

      int sys$qiow  (unsigned int efn, unsigned short int chan,

                    unsigned int func, struct _iosb *iosb, void

                    (*astadr)(__unknown_params), __int64  astprm,

                    void *p1, __int64 p2, __int64  p3, __int64 p4,

                    __int64 p5, __int64  p6);

239  –  $READ

    The Read service retrieves a specified number of bytes from
    a file (beginning on a block boundary) and transfers them to
    memory. A Read service using block I/O can be performed on any
    file organization.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

240  –  $READEF

    Returns the current status of all 32 event flags in a local or
    common event flag cluster and indicates whether the specified
    event flag is set or clear.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$READEF  efn ,state

    C Prototype

      int sys$readef  (unsigned int efn, unsigned int *state);

240.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of any event flag in the cluster whose status is to be
    returned. The efn argument is a longword containing this number;
    however, $READEF uses only the low-order byte. Specifying an
    event flag within a cluster requests that $READEF return the
    status of all event flags in that cluster.

    There are two local event flag clusters, which are local to the
    process: cluster 0 and cluster 1. Cluster 0 contains event flag
    numbers 0 to 31, and cluster 1 contains event flag numbers 32 to
    63.

    There are two common event flag clusters: cluster 2 and cluster
    3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3
    contains event flag numbers 96 to 127.

 state

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    State of all event flags in the specified cluster. The state
    argument is the 32- or 64-bit address (on Alpha and Integrity
    server systems) of a longword into which $READEF writes the state
    (set or clear) of the 32 event flags in the cluster.

241  –  $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, ...);

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

242  –  $REGISTRYW (Alpha and Integrity servers)

    On Alpha and Integrity server systems, interface to the OpenVMS
    Registry database server.

    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$REGISTRYW  [efn] ,func ,0 ,itmlst ,[iosb or iosa_64]

                     [,astadr or astadr_64] [,astprm or astprm_64]

                     [,timeout]

    C Prototype

      int sys$registryw  (unsigned int efn, unsigned int func, void

                         *, void *itmlst, struct _iosb *iosb, ...);

243  –  $RELEASE

    The Release service unlocks the record specified by the contents
    of the record file address (RAB$W_RFA) field of the RAB.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

244  –  $RELEASE GALAXY LOCK (Alpha Only)

    Releases ownership of an OpenVMS Galaxy lock.

    Note that this system service is supported only in an OpenVMS
    Alpha Galaxy environment.

    For more information about programming with OpenVMS Galaxy system
    services, see the VSI OpenVMS Alpha Partitioning and Galaxy Guide.

    Format

      SYS$RELEASE_GALAXY_LOCK  handle

    C Prototype

      int sys$release_galaxy_lock  (unsigned __int64 lock_handle);

244.1  –  Arguments

 handle

    OpenVMS usage:galaxy lock handle
    type:         quadword (unsigned)
    access:       read
    mechanism:    input by value
    The 64-bit lock handle that identifies the lock to be released.
    This value is returned by SYS$CREATE_GALAXY_LOCK.

245  –  $REMOVE

    The Remove service deletes a file name from a directory. It is
    the reverse of the Enter service.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

246  –  $REM HOLDER

    Deletes the specified holder record from the target identifier's
    list of holders.

    Format

      SYS$REM_HOLDER  id ,holder

    C Prototype

      int sys$rem_holder  (unsigned int id, struct _generic_64

                          *holder);

246.1  –  Arguments

 id

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Binary value of target identifier whose holder is deleted when
    $REM_HOLDER completes execution. The id argument is a longword
    containing the identifier value.

 holder

    OpenVMS usage:rights_holder
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Identifier of holder being deleted when $REM_HOLDER completes
    execution. The holder argument is the address of a quadword
    containing the UIC identifier of the holder in the first longword
    and the value of 0 in the second longword.

247  –  $REM IDENT

    Removes the specified identifier record and all its holder
    records (if any) from the rights database.

    Format

      SYS$REM_IDENT  id

    C Prototype

      int sys$rem_ident  (unsigned int id);

247.1  –  Argument

 id

    OpenVMS usage:rights_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Binary value of identifier deleted from rights database when
    $REM_IDENT completes execution. The id argument is a longword
    containing the identifier value.

248  –  $RENAME

    You can use the Rename service to change the name, type, or
    version of a file, or to move a file to another directory by
    changing its directory specification. However, you cannot use
    this service to move a file to another device.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

249  –  $RESCHED

    Requests reschedule of a process.

    Format

      SYS$RESCHED

    C Prototype

      int sys$resched  (void);

249.1  –  Arguments

    None.

250  –  $RESUME

    Causes a process previously suspended by the Suspend Process
    ($SUSPND) service to resume execution or cancels the effect of a
    subsequent suspend request.

    Format

      SYS$RESUME  [pidadr] ,[prcnam]

    C Prototype

      int sys$resume  (unsigned int *pidadr, void *prcnam);

250.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) of the process to be resumed. The
    pidadr argument is the address of a longword containing the PID.
    The pidadr argument can refer to a process running on the local
    node or a process running on another node in the cluster.

    You must specify the pidadr argument to delete processes in other
    UIC groups.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the process to be resumed. The prcnam argument is the
    address of a character string descriptor pointing to the process
    name.

    A process running on the local node can be identified with a 1-
    to 15-character string. To identify a process on a particular
    node on a cluster, specify the full process name, which includes
    the node name as well as the process name. The full process name
    can contain up to 23 characters.

    You can use the prcnam argument to resume only processes in the
    same UIC group as the calling process, because process names
    are unique to UIC groups, and the operating system uses the UIC
    group number of the calling process to interpret the process
    name specified by the prcnam argument. You must use the pidadr
    argument to delete processes in other UIC groups.

251  –  $REVOKID

    Removes the specified identifier from the rights list of the
    process or the system. If the identifier is listed as a holder
    of any other identifier, the appropriate holder records are also
    deleted.

    Format

      SYS$REVOKID  [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]

    C Prototype

      int sys$revokid  (unsigned int *pidadr, void *prcnam, struct

                       _generic_64 *id, void *name, unsigned int

                       *prvatr, unsigned int segment);

251.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) number of the process affected when
    $REVOKID completes execution. The pidadr argument is the address
    of a longword containing the PID of the process to be affected.
    You use -1 to indicate the system rights list. When pidadr is
    passed, it is also returned; therefore, you must pass it as a
    variable rather than a constant.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Process name on which $REVOKID operates. The prcnam argument
    is the address of a character string descriptor containing the
    process name. The maximum length of the name is 15 characters.
    Because the UIC group number is interpreted as part of the
    process name, you must use pidadr to specify the rights list
    of a process in a different group.

 id

    OpenVMS usage:rights_id
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference
    Identifier and attributes to be removed when $REVOKID completes
    execution. The id argument is the address of a quadword
    containing the binary identifier code to be removed in the first
    longword and the attributes in the second longword.

    Symbol values are offsets to the bits within the longword. You
    can also obtain the values as masks with the appropriate bit set
    using the prefix KGB$M rather than KGB$V. The following symbols
    for each bit position are defined in the system macro library
    ($KGBDEF):

    Bit Position           Meaning When Set

    KGB$V_DYNAMIC          Allows unprivileged holders of the
                           identifier to remove it from or add it
                           to the process rights database by using
                           the DCL command SET RIGHTS_LIST.

    KGB$V_NOACCESS         Makes any access rights of the identifier
                           null and void. This attribute is intended
                           as a modifier for a resource identifier or
                           the Subsystem attribute.

    KGB$V_RESOURCE         Allows holders of an identifier to charge
                           disk space to the identifier. It is used
                           only for file objects.

    KGB$V_SUBSYSTEM        Allows holders of the identifier to
                           create and maintain protected subsystems
                           by assigning the Subsystem ACE to the
                           application images in the subsystem.

    You must specify either id or name. Because the id argument is
    returned as well as passed if you specify name, you must pass it
    as a variable rather than a constant in this case.

 name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the identifier removed when $REVOKID completes execution.
    The name argument is the address of a descriptor pointing to the
    name of the identifier.

 prvatr

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Attributes of the deleted identifier. The prvatr argument is
    the address of a longword used to store the attributes of the
    identifier.

252  –  $REWIND

    The Rewind service sets the context of a record stream to the
    first record in the file. RMS alters the context of the next
    record to indicate the first record as being the next record.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

253  –  $RMSRUNDWN

    Closes all files opened by OpenVMS RMS for the image or process
    and halts I/O activity. This routine performs a $CLOSE service
    for each file opened for processing.

    Format

      SYS$RMSRUNDWN  buf-addr ,type-value

    C Prototype

      int sys$rmsrundwn  (void *buf-addr, unsigned char *type-value);

253.1  –  Arguments

 buf-addr

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor
    A descriptor pointing to a 22-byte buffer that is to receive the
    device identification (16 bytes) and the file identification (6
    bytes) of an improperly closed output file. The buf-addr argument
    is the address of the descriptor that points to the buffer.

 type-value

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by value
    A single byte code that specifies the type of I/O rundown to be
    performed. The type-value argument is the actual value used.

    This type of code has the following values and meanings:

    0     Rundown of image and indirect I/O for process permanent
          files.
    1     Rundown of image and process permanent files. The caller's
          mode must not be user.
    2     Abort RMS I/O. The caller's mode must be either executive
          or kernel (the system calls the I/O rundown control routine
          with this argument for process deletion).

254  –  $RPCC 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, returns a 64-bit, process-
    based, high-resolution time counter.

    Format

      SYS$RPCC_64

    C Prototype

      uint64 sys$rpcc_64  ();

255  –  $SCAN INTRUSION

    Scans the intrusion database for suspects or intruders during a
    login attempt, audits login failures and updates records, or adds
    new records to the intrusion database.

    Format

      SYS$SCAN_INTRUSION  logfail_status ,failed_user ,job_type

                          ,[source_terminal] ,[source_node]

                          ,[source_user] ,[source_address]

                          ,[failed_password] ,[parent_user]

                          ,[parent_id] ,[flags]

    C Prototype

      int sys$scan_intrusion  (unsigned int logfail_status,

                              void *failed_user, unsigned int

                              job_type, void *source_terminal, void

                              *source_node, void *source_user, void

                              *source_address, void *failed_password,

                              void *parent_user, unsigned int

                              parent_id, unsigned int flags);

255.1  –  Arguments

 logfail_status

    OpenVMS usage:status code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Reason why the user's login attempt failed. The logfail_status
    argument is a longword containing the login failure status code.

    The logfail_status argument can contain any valid message code.
    For example, the value of the logfail_status argument is SS$_
    NOSUCHUSER if the user name the user entered does not exist on
    the system.

    If the logfail_status argument contains a failure status, the
    service performs a suspect scan. Here, the service searches the
    intrusion database for intruder suspects as well as intruders.
    If the value of the logfail_status argument is a successful
    message, such as SS$_NORMAL, the service scans the database only
    for intruders. For more information about how the database works,
    see the VSI OpenVMS Guide to System Security.

 failed_user

    OpenVMS usage:char_string or item_list_3
    type:         character-coded text string or longword (unsigned)
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor or by
                  reference
    If the CIA$M_ITEMLIST flag is FALSE:

    This argument is the user name associated with the unsuccessful
    login attempt. The failed_user argument is the address of a
    character-string descriptor pointing to the failed user name.

    A failed user name consists of 1 to 32 alphanumeric characters.

    If the CIA$M_ITEMLIST flag is TRUE:

    The failed_user argument is the address of a 32-bit item list. If
    the item list is used, one item, the CIA$_FAILED_USERNAME item,
    must be present in the item list.

    The following table lists the valid item descriptions for the
    failed_user argument:

    Item               Description

    CIA$_FAILED_       Address of a buffer containing the failed user
    USERNAME           name.
    CIA$_SCSNODE       Address of the 8-character null-padded SCS
                       node name on which the intrusion happened.
    CIA$_USER_DATA     Address of a 256-byte buffer, available for
                       passing third party specified data.

 job_type

    OpenVMS usage:job type
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Type of job that failed. The job_type argument is a longword
    indicating the type of job that failed.

    The $JPIDEF macro defines the following values for the job_type
    argument:

    o  JPI$K_BATCH

    o  JPI$K_DETACHED

    o  JPI$K_DIALUP

    o  JPI$K_LOCAL

    o  JPI$K_NETWORK

    o  JPI$K_REMOTE

 source_terminal

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Source terminal where the login attempt is occurring. The source_
    terminal argument is the address of a character-string descriptor
    pointing to the device name of the terminal from which the login
    attempt originates.

    A source terminal device name consists of 1 to 64 alphanumeric
    characters, including underscores (_)  and colons (:).

 source_node

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the node from which the user's login attempt originates.
    The source_node argument is the address of a character-string
    descriptor pointing to the source node name string.

    A source node name consists of 1 to 1024 characters. No specific
    characters, format, or case is required for a source node name
    string.

 source_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    User name associated with the login attempt. The source_user
    argument is the address of a character-string descriptor pointing
    to the source user name string.

    A source user name consists of 1 to 32 alphanumeric characters,
    including dollar signs ($)  and underscores (_).

 source_addr

    OpenVMS usage:node address
    type:         descriptor
    access:       read only
    mechanism:    by reference
    Source DECnet for OpenVMS address from which the login attempt
    originates. The source_addr argument is the address of a
    descriptor containing the source node address.

 failed_password

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Password the user entered for the login attempt. The failed_
    password argument is the address of a character-string descriptor
    pointing to the plaintext password the user entered to log in.

    A failed password is a password of 0 to 32 characters that did
    not allow the user to log in to the system. This argument is not
    stored in the intrusion database and is only used for auditing
    during break-in attempts.

 parent_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Parent process name of the failed login. The parent_user argument
    is the address of a character-string descriptor pointing to the
    parent process name of the failed login process.

    A parent process name consists of 1 to 15 characters. This
    argument should be specified only for failed spawn commands.

 parent_id

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Process identification of the parent process from which the login
    was attempted. The parent_id argument is a longword containing
    the parent process identification.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Operational instructions for the service. The flags argument is a
    longword bit mask wherein each bit corresponds to an option.

    Each flag option has a symbolic name. The $CIADEF macro defines
    the following valid names for the $SCAN_INTRUSION service:

    Symbolic Name      Description

    CIA$M_NOAUDIT      If set, this flag indicates that the service
                       should instruct the security server to not
                       audit the login failure or the break-in
                       attempt. If the flag is set, you are expected
                       to do your own auditing.
    CIA$M_IGNORE_      Specifies that the service should not wait for
    RETURN             the return status from the security server. No
                       return status from the server's function will
                       be returned to the caller.
    CIA$M_ITEMLIST     If FALSE, the failed_user argument is a
                       character string. If TRUE, this argument is
                       a 32-bit item list.
    CIA$M_REAL_        If set, indicates that the user name passed as
    USERNAME           the failed user name is read and known to the
                       system.
    CIA$M_SECONDARY_   Indicates that the failed password passed to
    PASSWORD           the service was the secondary password. If the
                       flag is clear, the password is assumed to be
                       the primary password.

256  –  $SCHDWK

    Schedules the awakening (restarting) of a process that has placed
    itself in a state of hibernation with the Hibernate ($HIBER)
    service.

    Format

      SYS$SCHDWK  [pidadr] ,[prcnam] ,daytim ,[reptim]

    C Prototype

      int sys$schdwk  (unsigned int *pidadr, void *prcnam, struct

                      _generic_64 *daytim, struct _generic_64

                      *reptim);

256.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) of the process to be awakened. The
    pidadr argument is the address of a longword containing the PID.
    The pidadr argument can refer to a process running on the local
    node or a process running on another node in the OpenVMS Cluster
    system.

    You must specify the pidadr argument to awaken processes in other
    UIC groups.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the process to be awakened. The prcnam is the address
    of a character string descriptor pointing to the process name. A
    process running on the local node can be identified with a string
    of from 1 to 15 characters.

    To identify a process on a particular node on a cluster, specify
    the full process name, which includes the node name as well as
    the process name. The full process name can contain up to 23
    characters.

    You can use the prcnam argument to awaken only processes in the
    same UIC group as the calling process because process names are
    unique to UIC groups, and the operating system uses the UIC
    group number of the calling process to interpret the process
    name specified by the prcnam argument. You must use the pidadr
    argument to awaken processes in other UIC groups.

 daytim

    OpenVMS usage:date_time
    type:         quadword
    access:       read only
    mechanism:    by reference
    Time at which the process is to be awakened. The daytim argument
    is the address of a quadword containing this time in the system
    64-bit time format. A positive time value specifies an absolute
    time at which the specified process is to be awakened. A negative
    time value specifies an offset (delta time) from the current
    time.

 reptim

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Time interval at which the wakeup request is to be repeated.
    The reptim argument is the address of a quadword containing this
    time interval. The time interval must be expressed in delta time
    format.

    The time interval specified cannot be less than 10 milliseconds;
    if it is, $SCHDWK automatically increases it to 10 milliseconds.

    If you do not specify reptim, a default value of 0 is used, which
    specifies that the wakeup request is not to be repeated.

257  –  $SCHED

    Affects process scheduling. This service is intended for use by a
    class scheduler process.

    Format

      SYS$SCHED  func ,p1 ,p2 ,p3

    C Prototype

      int sys$sched  (unsigned int func, unsigned int *p1, unsigned

                     int *p2, unsigned int *p3);

257.1  –  Arguments

 func

    OpenVMS usage:function_code
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value
    Function code specifying the action $SCHED is to perform. The
    func argument is a longword containing this code.

    For a list of the valid function codes for $SCHED, see the VSI
    OpenVMS System Services Reference Manual.

 p1, p2, p3

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       varies
    mechanism:    varies
    The meaning of the p1, p2, and p3 arguments depends on the
    function code specified in the func argument, and is defined
    in the Function Codes section.

258  –  $SEARCH

    The Search service scans a directory file and fills in various
    NAM block fields. This service should be preceded by the Parse
    service, in order to initialize the NAM block appropriately.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

259  –  $SETAST

    Enables or disables the delivery of asynchronous system traps
    (ASTs) for the access mode from which the service call was
    issued.

    Format

      SYS$SETAST  enbflg

    C Prototype

      int sys$setast  (char enbflg);

259.1  –  Argument

 enbflg

    OpenVMS usage:boolean
    type:         byte (unsigned)
    access:       read only
    mechanism:    by value
    Value specifying whether ASTs are to be enabled. The enbflg
    argument is a byte containing this value. The value 1 enables
    AST delivery for the calling access mode; the value 0 disables
    AST delivery.

260  –  $SETCLUEVT

    Establishes a request for notification when an OpenVMS Cluster
    configuration event occurs.

    Format

      SYS$SETCLUEVT  event ,astadr ,[astprm] ,[acmode] ,[handle]

    C Prototype

      int sys$setcluevt  (unsigned int event, void

                         (*astadr)(__unknown_params), int

                         astprm, unsigned int acmode, struct

                         _generic_64 *handle);

260.1  –  Arguments

 event

    OpenVMS usage:event_code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Event code indicating the type of cluster configuration event for
    which an AST is to be delivered. The event argument is a value
    indicating which type of event is of interest.

    Each event type has a symbolic name. The $CLUEVTDEF macro defines
    the following symbolic names:

    Symbolic Name      Description

    CLUEVT$C_ADD       One or more OpenVMS nodes have been added to
                       the OpenVMS Cluster system.
    CLUEVT$C_REMOVE    One or more OpenVMS nodes have been removed
                       from the OpenVMS Cluster system.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    Notification AST routine to receive control after a change in
    OpenVMS Cluster configuration occurs.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Optional AST parameter to be passed to the AST service routine.
    The astprm argument is a longword value containing the AST
    parameter.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Optional access mode at which the configuration event AST is to
    execute. The acmode argument is a longword containing the access
    mode.

    Each access mode has a symbolic name. The $PSLDEF macro defines
    the following symbols for the four access modes:

    Symbol         Access Mode

    PSL$C_KERNEL   Kernel
    PSL$C_EXEC     Executive
    PSL$C_SUPER    Supervisor
    PSL$C_USER     User

    The value of the access mode must not be more privileged than the
    access mode of the caller.

 handle

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    Optional identifier to receive a value that uniquely identifies
    this AST request. $SETCLUEVT sets this handle to a unique value
    so that it can later be used to identify the request in the
    $CLRCLUEVT and $TSTCLUEVT services.

261  –  $SETDDIR

    Allows you to read and change the default directory string for
    the process. Do not include any device or file name strings in
    the default directory string; include only the [DIR] syntax.
    Modify the device portion of the current default directory
    location through the specification of the SYS$DISK logical name.
    Redefine this logical name using either the $CRELNM edtsystem
    service or the LIB$SET_LOGICAL RTL routine.

    Format

      SYS$SETDDIR  [new-dir-addr] ,[length-addr] ,[cur-dir-addr]

    C Prototype

      int sys$setddir  (void *newdiraddr, unsigned short int

                       *lengthaddr, void *curdiraddr);

261.1  –  Arguments

 new-dir-addr

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    A descriptor of the new default directory. The new-dir-addr
    argument is the address of the descriptor that points to the
    buffer containing the new directory specification that RMS will
    use to set the new process-default directory. If the default
    directory is not to be changed, the value of the new-dir-addr
    argument should be 0.

 length-addr

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    A word that is to receive the length of the current default
    directory. The length-addr argument is the address of the word
    that will receive the length. If you do not want this value
    returned, specify the value 0.

 cur-dir-addr

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    A descriptor of a buffer that is to receive the current default
    directory string. The cur-dir-addr argument is the address of the
    descriptor that points to the buffer area that is to receive the
    current directory string.

262  –  $SETDFPROT

    Allows you to read and write the default file protection for the
    process.

    Format

      SYS$SETDFPROT  [new-def-prot-addr] ,[cur-def-prot-addr]

    C Prototype

      int sys$setdfprot  (unsigned short int *newdefprotaddr,

                         unsigned short int *curdefprotaddr);

262.1  –  Arguments

 new-def-prot-addr

    OpenVMS usage:file_protection
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    A word that specifies the new default file protection
    specification. The new-def-prot-addr argument is the address
    of the word that specifies the desired protection. If you do not
    want the process-default file protection to be changed, specify
    the value 0.

 cur-def-prot-addr

    OpenVMS usage:file_protection
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    A word that is to receive the current default file protection
    specification. The cur-def-prot-addr argument is the address of
    the word that receives the current process-default protection. If
    you do not want the current default file protection, specify the
    value 0.

263  –  $SETDTI

    The Set Distributed Transaction Information service removes
    resource managers from transactions. It can also be used to
    modify transaction states.

    Format

      SYS$SETDTI  [efn], [flags], iosb, [astadr], [astprm], [contxt],

                  func, itmlst

    C Prototype

      int sys$setdti  (unsigned int efn, unsigned int flags, struct

                      _iosb *iosb, void (*astadr)(__unknown_params),

                      int astprm, unsigned int *contxt, unsigned

                      short int *func, void *itmlst);

263.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for the option
    flag described in $SETDTI Operation Flag. All undefined bits must
    be 0. If this argument is omitted, no flags are used.

    Table SYS-23 $SETDTI Operation Flag

    Flag Name      Description

    DDTM$M_SYNC    Specifies successful synchronous completion by
                   returning SS$_SYNCH. When SS$_SYNCH is returned,
                   the AST routine is not called, the event flag is
                   not set, and the I/O status block is not filled
                   in.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the completion status of the
    service is returned as a condition value.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the I/O status block diagram.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine executed when the service completes, if SS$_
    NORMAL is returned in R0. The astadr argument is the address of
    the entry mask of this routine. The routine is executed in the
    same access mode as that of the caller of the $SETDTI service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter passed to the AST routine specified by the
    astadr argument.

 contxt

    OpenVMS usage:contxt
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Context value obtained from a call to $GETDTI. It implicitly
    specifies a node and transaction manager log identifier.

 func

    OpenVMS usage:function_code
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Function modifier that specifies the set operation to be
    performed. The func argument is a longword value containing the
    function code.

    $SETDTI Function Codes lists the available function codes:

    Table SYS-24 $SETDTI Function Codes

    Function           Description

    DTI$K_DELETE_RM_   Deletes the resource manager specified in
    NAME               itmlst item DTI$_TRANSACTION_INFORMATION,
                       DTI$T_PART_NAME from the transaction specified
                       by DTI$_TRANSACTION_INFORMATION, DTI$T_TID.
    DTI$K_DELETE_      Deletes the transaction specified by itmlst
    TRANSACTION        item DTI$_TRANSACTION_INFORMATION, DTI$T_TID.
    DTI$K_MODIFY       Modifies the transaction specified by itmlst
    STATE              item DTI$_TRANSACTION_INFORMATION, DTI$T_TID,
                       using the transaction state specified in DTI$_
                       B_STATE.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying the transaction information that $SETDTI
    is to use. The itmlst argument is the address of a list of item
    descriptors, each of which describes an item of information. The
    list of item descriptors is terminated by a longword of 0. Each
    item descriptor in the item list acts as an input argument to
    $SETDTI and as such is only required to be read only.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the single item descriptor format.

    The following table describes the itmlst item descriptor fields:

    Field          Description

    Buffer         A word containing a user-supplied integer
    length         specifying the length (in bytes) of a buffer from
                   which $SETDTI is to read the information. The
                   length of the buffer needed depends on the item
                   code specified in the item code field of the item
                   descriptor. If the value of buffer length is too
                   small, $SETDTI will return an error status.
    Item code      A word containing a user-supplied symbolic code
                   specifying the search item that $SETDTI is to use.
                   The $DTIDEF macro defines these codes. Each item
                   code is described in the Item Codes section.
    Buffer         A longword containing the user-supplied address
    address        of the buffer from which $SETDTI reads the item
                   information.
    Return         This longword that is not used in the item list as
    length         all items are read-only.
    address

263.2  –  Item Codes

 DTI$_TRANSACTION_INFORMATION

    When you specify DTI$_TRANSACTION_INFORMATION, $SETDTI uses the
    fields in the following table to perform the $SETDTI call. Each
    function requires a specific set of fields from the transaction
    record to perform its operation. If one or more of these fields
    is not present or valid, then the $SETDTI call will fail. The
    fields required by each function are listed in the func argument
    description.

    Item               Description

    DTI$B_PART_NAME_   A byte containing the length of the
    LEN                participant name field DTI$T_PART_NAME.
    DTI$B_STATE        A byte containing the state of the
                       transaction. Two states are valid: DTI$K_
                       COMMITTED and DTI$K_ABORTED.
    DTI$T_PART_NAME    A character field containing DTI$B_PART_
                       NAME_LEN characters that specifies a resource
                       manager name.

                       To ensure smooth operation in a mixed-network
                       environment, refer to the chapter entitled
                       Managing DECdtm Services in the VSI OpenVMS
                       System Manager's Manual, for information on
                       defining node names.
    DTI$T_PART_LOG_ID  Reserved by VSI.
    DTI$T_TID          A 16-byte field containing the transaction
                       identifier.

264  –  $SETDTIW

    Sets the process current transaction and removes resource
    managers from transactions.

    $SETDTIW$ always waits for the request to complete before
    returning to the caller. Other than this, it is identical to
    $SETDTI.

    Format

      SYS$SETDTIW  [efn], [flags], iosb, [astadr], [astprm],

                   [contxt], func, itmlst

    C Prototype

      int sys$setdtiw  (unsigned int efn, unsigned int flags, struct

                       _iosb *iosb, void (*astadr)(__unknown_params),

                       int astprm, unsigned int *contxt, unsigned

                       short int *func, void *itmlst);

265  –  $SETEF

    Sets an event flag in a local or common event flag cluster.
    The condition value returned by $SETEF indicates whether the
    specified flag was previously set or clear. After the event flag
    is set, processes waiting for the event flag to be set resume
    execution.

    Format

      SYS$SETEF  efn

    C Prototype

      int sys$setef  (unsigned int efn);

265.1  –  Argument

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set. The efn argument is a
    longword containing this number; however, $SETEF uses only the
    low-order byte.

    Two local event flag clusters are local to the process: cluster 0
    and cluster 1. Cluster 0 contains event flag numbers 0 to 31, and
    cluster 1 contains event flag numbers 32 to 63.

    There are two common event flag clusters: cluster 2 and cluster
    3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3
    contains event flag numbers 96 to 127.

266  –  $SETEXV

    Assigns a condition handler address to the primary, secondary, or
    last chance exception vectors, or removes a previously assigned
    handler address from any of these three vectors.

    Format

      SYS$SETEXV  [vector] ,[addres] ,[acmode] ,[prvhnd]

    C Prototype

      int sys$setexv  (unsigned int vector, int

                      (*addres)(__unknown_params), unsigned

                      int acmode, void *(*(prvhnd)));

266.1  –  Arguments

 vector

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Vector for which a condition handler is to be established or
    removed. The vector argument is a longword value. The value
    0 (the default) specifies the primary exception vector; the
    value 1, the secondary vector; and the value 2, the last chance
    exception vector.

 addres

    OpenVMS usage:procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    Condition handler address to be established for the exception
    vector specified by the vector argument. The addres argument is
    a longword value containing the address of the condition handler
    routine.

    If you do not specify addres or specify it as the value 0, the
    condition handler address already established for the specified
    vector is removed; that is, the contents of the longword vector
    is set to 0.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode for which the exception vector is to be modified.
    The acmode argument is a longword containing the access mode. The
    $PSLDEF macro defines symbols for the four access modes.

    The most privileged access mode used is the access mode of the
    caller. Exception vectors for access modes more privileged than
    the caller's access mode cannot be modified.

 prvhnd

    OpenVMS usage:procedure value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Previous condition handler address contained by the specified
    exception vector. The prvhnd argument is the address of a
    longword into which $SETEXV writes the handler's procedure value.

267  –  $SETFLT

    On Alpha and Integrity server systems, allows a process to change
    the fault characteristic on a page or range of pages.

    Format

      SYS$SETFLT  inadr ,[retadr] ,[acmode] ,fault_flag

    C Prototype

      int sys$setflt  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode, unsigned int

                      fault_flag);

267.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Starting and ending virtual addresses of the range of pages whose
    fault characteristic is to be changed. The inadr argument is the
    address of a 2-longword array containing, in order, the starting
    and ending process virtual addresses.

    Addresses are adjusted up or down to fall on CPU-specific page
    boundaries. Only the virtual page number portion of each virtual
    address is used; the low-order byte-within-page bits are ignored.

    If the starting and ending virtual addresses are the same, the
    fault characteristic is changed for a single page.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference-array reference or descriptor
    Starting and ending virtual addresses of the range of pages whose
    fault characteristic was actually changed by $SETFLT. The retadr
    argument is the address of a 2-longword array containing, in
    order, the starting and ending process virtual addresses.

    If an error occurs while the fault characteristic is being
    changed, $SETFLT writes into retadr the range of pages that were
    successfully changed before the error occurred. If no pages were
    affected before the error occurred, $SETFLT writes the value -1
    into each longword of the 2-longword array.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode associated with the call to $SETFLT. The acmode
    argument is a longword containing the access mode. The $PSLDEF
    macro defines symbols for the access modes.

    The $SETFLT service uses whichever of the following two access
    modes is less privileged: (1)  the access mode specified by
    acmode or (2)  the access mode of the caller. To change the fault
    characteristic of any page in the specified range, the resultant
    access mode must be equal to or more privileged than the access
    mode of the owner of that page.

 fault_flag

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the request options. The fault_flag argument
    is a longword bit vector in which each bit corresponds to a flag.
    The $FLTDEF macro and the FLTDEF.H file define a symbolic name
    for each flag.

    The $FLTDEF macro defines the following symbolic names for the
    fault characteristic codes:

    Symbol             Description

    FLT$M_NO_EXECUTE   Fault on execute access attempt
    FLT$M_EXECUTABLE   Allow execute access

    If you specify the fault characteristic as the value 0, the
    characteristic defaults to no execute access.

268  –  $SETFLT 64

    On Alpha and Integrity server systems, allows a process to change
    the fault characteristic (for example, no execute) on a page or
    range of pages.

    Format

      $SETFLT_64  start_va_64 ,length_64 ,acmode ,fault_flag

                  ,return_va_64 ,return_length_64

268.1  –  Arguments

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address of the range of pages whose fault
    characteristic is to be changed. The specified virtual address
    will be rounded down to a CPU-specifie page boundary.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space whose fault characteristic
    is to be changed. The specified length will be rounded up to a
    CPU-specific page boundary so that it includes all CPU-specific
    pages in the requested range.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode associated with the call to $SETFLT_64. The acmode
    argument is a longword containing the access mode. The $PSLDEF
    macro defines symbols for the four access modes.

    The most privileged access mode used is the access mode of the
    caller. The calling process can modify pages only if those pages
    are owned by an access mode equal to or less privileged than the
    access mode of the calling process.

 fault_flag

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:     by value
    Flag mask specifying the request options. The fault_flag argument
    is a longword bit vector in which each bit corresponds to a flag.
    The $FLTDEF macro and the FLTDEF.H file define a symbolic name
    for each flag.

    The $FLTDEF macro defines the following symbolic names for the
    fault characteristic codes:

    Symbol             Description

    FLT$M_NO_EXECUTE   Fault on execute access attempt
    FLT$M_EXECUTABLE   Allow execute access

    If you specify the fault characteristic as the value 0, the
    characteristic defaults to no execute access.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32-bit or 64-bit reference
    The lowest process virtual address of the range of pages whose
    fault characteristics were actually changed.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32-bit or 64-bit reference
    The length of the virtual address range whose fault
    characteristics were actually changed. The return_length_64
    argument is the 32-bit or 64-bit virtual address of a naturally
    aligned quadword into which the service returns the length of the
    virtual address range in bytes.

268.2  –  Description

    The Set Fault Characteristic service sets the fault
    characteristics (for example, no execute) for the specified
    range of pages, checking that the specified mode is at least
    as privileged as the owner of the page.

    If the condition value SS$_ACCVIO is returned by this service, a
    value might not be returned in the memory locations pointed to by
    the return_va_64 and return_length_64 arguments.

    If a condition value other than SS$_ACCVIO is returned, the
    returned address and returned length indicate the pages that were
    successfully changed before the error occurred. If no pages were
    changed, the return_va_64 argument will contain the value -1, and
    a value might not be returned in the memory location pointed to
    by the return_length_64 argument.

    Required Privileges

    None

    Required Quota

    None

    Related Services

    $CRETVA_64, $EXPREG_64, $SETPRT_64

268.3  –  Condition Values Returned

    SS$_NORMAL         The service completed successfully.
    SS$_ACCVIO         The return_va_64 or return_length_64 argument
                       cannot be written by the caller.
    SS$_BADPARAM       A bad fault_flag argument was specified.
    SS$_LENVIO         A page in the specified range is beyond
                       the length of virtual addresses within that
                       region.
    SS$_NOSUCHPAG      An attempt was made to change the fault
                       characteristic on a nonexistent page.
    SS$_PAGNOTINREG    A page in the specified range is not in
                       process private adress space.
    SS$_PAGOWNVIO      The process attempted to change the protection
                       on a page owned by a more privileged access
                       mode.

269  –  $SETIME

    Changes the value of, or recalibrates, the system time.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$SETIME  [timadr]

    C Prototype

      int sys$setime  (struct _generic_64 *timadr);

269.1  –  Argument

 timadr

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    New absolute time value for the system time, specifying the
    number of 100-nanosecond intervals since 00:00 o'clock, November
    17, 1858. The timadr argument is the 32- or 64-bit address (on
    Alpha and Integrity server systems) of a quadword containing the
    new system time value. A negative (delta) time value is invalid.

    If you do not specify the value of timadr or specify it as 0,
    $SETIME recalibrates the system time using the time-of-year
    clock.

270  –  $SETIMR

    Sets the timer to expire at a specified time.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$SETIMR  [efn] ,daytim ,[astadr] ,[reqidt] ,[flags]

    C Prototype

      int sys$setimr  (unsigned int efn, struct _generic_64 *daytim,

                      void (*astadr)(__unknown_params), unsigned

                      __int64 reqidt, unsigned int flags);

270.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Event flag to be set when the timer expires. The efn argument
    is a longword value containing the number of the event flag;
    however, $SETIMR uses only the low-order byte.

    If you do not specify efn, event flag 0 is used.

    When $SETIMR first executes, it clears the specified event flag
    or event flag 0.

 daytim

    OpenVMS usage:date_time
    type:         quadword
    access:       read only
    mechanism:    by 64-bit reference (Alpha and Integrity servers)
    Time at which the timer expires. The daytim argument is the 64-
    bit address (on Alpha and Integrity server systems) of a quadword
    time value. A positive time value specifies an absolute time
    at which the timer expires; a negative time value specifies an
    offset (delta time) from the current time.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 64-bit reference (Alpha and Integrity servers)
    AST service routine that is to execute when the timer expires.
    The astadr argument is the 64-bit address (on Alpha and Integrity
    server systems) of the procedure value of this routine. If you do
    not specify the value of astadr or specify it as 0 (the default),
    no AST routine executes.

    The AST routine, if specified, executes at the access mode of the
    caller.

 reqidt

    OpenVMS usage:user_arg
    type:         quadword
    access:       read only
    mechanism:    by value
    Identification of the timer request. The reqidt argument is a
    quadword value containing a number that uniquely identifies the
    timer request. If you do not specify reqidt, the value 0 is used.

    To cancel a timer request, the identification of the timer
    request (as specified by reqidt in $SETIMR) is passed to the
    Cancel Timer ($CANTIM) service (as the reqidt argument).

    If you want to cancel specific timer requests but not all timer
    requests, be sure to specify a nonzero value for reqidt in the
    $SETIMR call; $CANTIM interprets an identification value of 0 as
    a request to cancel all timer requests.

    You can specify unique values for reqidt for each timer request
    or give the same value to related timer requests. This permits
    selective canceling of a single timer request, a group of related
    timer requests, or all timer requests.

    If you specify the astadr argument in the $SETIMR call, the value
    specified by the reqidt argument is passed as a parameter to the
    AST routine. If the AST routine requires more than one parameter,
    specify an address for the value of reqidt; the AST routine
    can then interpret that address as the beginning of a list of
    parameters.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Longword of bit flags for the set timer operation. Currently,
    only bit 0 is used for the flags argument. When the low bit (bit
    0) is set, it indicates that this timer request should be in
    units of CPU time, rather than elapsed time. When bit 0 is clear
    (the default), the timer request is in units of elapsed time. The
    flags argument is optional.

271  –  $SETPRA

    Establishes a routine to receive control after a power recovery
    is detected.

    Format

      SYS$SETPRA  astadr ,[acmode]

    C Prototype

      int sys$setpra  (int (*astadr)(__unknown_params), unsigned int

                      acmode);

271.1  –  Arguments

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    Power recovery AST routine to receive control when a power
    recovery is detected. The astadr argument is the address of this
    routine.

    If you specify astadr as the value 0, an AST is not delivered to
    the process when a power recovery is detected.

    The system passes one parameter to the specified AST routine.
    This parameter is a longword value containing the length of time
    that the power was off, expressed as the number of 1/100th-of-a-
    second intervals that have elapsed.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode at which the power recovery AST routine is to
    execute. The acmode argument is a longword containing the access
    mode. The $PSLDEF macro defines symbols for the access modes.

    The most privileged access mode used is the access mode of the
    caller.

272  –  $SETPRI

    Changes the base priority of the process. The base priority is
    used to determine the order in which executable processes are to
    run.

    Format

      SYS$SETPRI  [pidadr] ,[prcnam] ,pri ,[prvpri] ,[nullarg]

                  ,[nullarg]

    C Prototype

      int sys$setpri  (unsigned int *pidadr, void *prcnam, unsigned

                      int pri, unsigned int *prvpri, unsigned int

                      *pol, unsigned int *prvpol);

272.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) of the process whose priority is to
    be set. The pidadr argument is the address of the PID. The pidadr
    argument can refer to a process running on the local node or a
    process running on another node in the cluster.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Process name of the process whose priority is to be changed. The
    prcnam argument is the address of a character string descriptor
    pointing to the process name.

    A process running on the local node can be identified with a 1-
    to 15-character string. To identify a process on a particular
    node on a cluster, specify the full process name, which includes
    the node name as well as the process name. The full process name
    can contain up to 23 characters.

    You can use the prcnam argument only on behalf of processes in
    the same UIC group as the calling process. To set the priority
    for processes in other groups, you must specify the pidadr
    argument.

 pri

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    New base priority to be established for the process. The pri
    argument is a longword value containing the new priority.
    Priorities that are not real time are in the range 0 through
    15; real-time priorities are in the range 16 through 31.

    If the specified priority is higher than the base priority of the
    target process, and if the caller does not have ALTPRI privilege,
    then the base priority of the target process is used.

 prvpri

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Base priority of the process before the call to $SETPRI. The
    prvpri argument is the address of a longword into which $SETPRI
    writes the previous base priority of the process.

 policy

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    On Alpha and Integrity server systems, address of a longword
    containing the new scheduling policy for the process.

    The $JPIDEF macro defines the following symbols for the policy
    argument:

    Symbol            Meaning

    JPI$K_DEFAULT_    The normal scheduling policy. The priority
    POLICY            interval for this policy is defined as [0..n],
                      such that priorities [0..15] are interactive
                      and priorities [16..n] are real time.

    JPI$K_PSX_FIFO_   POSIX FIFO scheduling policy. The priority
    POLICY            interval for this policy is defined as [n..m]
                      real-time priorities.

    JPI$K_PSX_RR_     POSIX round-robin policy. The priority interval
    POLICY            for this policy is defined as [n..m] real-time
                      priorities.

 prvpol

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    On Alpha and Integrity server systems, address of a longword into
    which the previous scheduling policy for the process is written.
    If the policy argument is null, no change in policy is requested
    and prvpol returns the current policy.

    The valid priority intervals for specific scheduling policies
    might change in the future. Applications should, therefore,
    not use embedded numeric constants for scheduling priority, but
    should use the appropriate $GETSYI item codes to fetch the legal
    priority intervals. The application can then dynamically select
    a priority value that is within the interval. The $GETSYI item
    codes are:

    o  SYI$_DEF_PRIO_MAX, SYI$_DEF_PRIO_MIN

    o  SYI$_PSXFIFO_PRIO_MAX, SYI$_PSXFIFO_PRIO_MIN

    o  SYI$_PSXRR_PRIO_MAX, SYI$_PSXRR_PRIO_MIN

    For more information about these item codes, see the $GETSYI
    service description in the VSI OpenVMS System Services Reference
    Manual.

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

273  –  $SETPRN

    Allows a process to establish or to change its own process name.

    Format

      SYS$SETPRN  [prcnam]

    C Prototype

      int sys$setprn  (void *prcnam);

273.1  –  Argument

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Process name to be given to the calling process. The prcnam
    argument is the address of a character string descriptor pointing
    to a 1- to 15-character process name string. If you do not
    specify prcnam, the calling process is given no name.

274  –  $SETPRT

    Allows a process to change the protection on a page or range of
    pages.

    Format

      SYS$SETPRT  inadr ,[retadr] ,[acmode] ,prot ,[prvprt]

    C Prototype

      int sys$setprt  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode, unsigned int

                      prot, unsigned char *prvprt);

274.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Starting and ending virtual addresses of the range of pages whose
    protection is to be changed. The inadr argument is the address of
    a 2-longword array containing, in order, the starting and ending
    process virtual addresses.

    Addresses are adjusted up or down to fall on CPU-specific page
    boundaries. Only the virtual page number portion of each virtual
    address is used; the low-order byte-within-page bits are ignored.

    If the starting and ending virtual addresses are the same, the
    protection is changed for a single page.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference-array reference or descriptor
    Starting and ending virtual addresses of the range of pages whose
    protection was actually changed by $SETPRT. The retadr argument
    is the address of a 2-longword array containing, in order, the
    starting and ending process virtual addresses.

    If an error occurs while the protection is being changed, $SETPRT
    writes into retadr the range of pages that were successfully
    changed before the error occurred. If no pages were affected
    before the error occurred, $SETPRT writes the value -1 into each
    longword of the 2-longword array.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode associated with the call to $SETPRT. The acmode
    argument is a longword containing the access mode. The $PSLDEF
    macro defines symbols for the access modes.

    The $SETPRT service uses whichever of the following two access
    modes is least privileged: (1)  the access mode specified by
    acmode or (2)  the access mode of the caller. To change the
    protection of any page in the specified range, the resultant
    access mode must be equal to or more privileged than the access
    mode of the owner of that page.

 prot

    OpenVMS usage:page_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Page protection to be assigned to the specified pages. The prot
    argument is a longword value containing the protection code. Only
    bits 0 to 3 are used; bits 4 to 31 are ignored.

    The $PRTDEF macro defines the following symbolic names for the
    protection codes:

    Symbol        Description

    PRT$C_NA      No access
    PRT$C_KR      Kernel read only
    PRT$C_KW      Kernel write
    PRT$C_ER      Executive read only
    PRT$C_EW      Executive write
    PRT$C_SR      Supervisor read only
    PRT$C_SW      Supervisor write
    PRT$C_UR      User read only
    PRT$C_UW      User write
    PRT$C_ERKW    Executive read; kernel write
    PRT$C_SRKW    Supervisor read; kernel write
    PRT$C_SREW    Supervisor read; executive write
    PRT$C_URKW    User read; kernel write
    PRT$C_UREW    User read; executive write
    PRT$C_URSW    User read; supervisor write

    OpenVMS Alpha and Integrity server systems convert PRT$C_NA to
    the next highest protection, kernel-read.

    If you specify the protection as the value 0, the protection
    defaults to kernel read only.

 prvprt

    OpenVMS usage:page_protection
    type:         byte (unsigned)
    access:       write only
    mechanism:    by reference
    Protection previously assigned to the last page in the range.
    The prvprt argument is the address of a byte into which $SETPRT
    writes the protection of this page. The prvprt argument is useful
    only when protection for a single page is being changed.

275  –  $SETPRT 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows a process to change
    the protection on a page or range of pages.

    This service accepts 64-bit addresses.

    Format

      SYS$SETPRT_64  start_va_64 ,length_64 ,acmode ,prot

                     ,return_va_64 ,return_length_64 ,return_prot_64

    C Prototype

      int sys$setprt_64  (void *start_va_64, unsigned __int64

                         length_64, unsigned int acmode, unsigned

                         int prot, void *(*(return_va_64)), unsigned

                         __int64 *return_length_64, unsigned int

                         *return_prot_64);

275.1  –  Arguments

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address of the range of pages whose
    protection is to be changed. The specified virtual address will
    be rounded down to a CPU-specific boundary.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space whose protection is to
    be changed. The specified length will be rounded up to a CPU-
    specific page boundary so that it includes all CPU-specific pages
    in the requested range.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode associated with the call to $SETPRT_64. The acmode
    argument is a longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. To change the protection of any page in the specified
    range, the resultant access mode must be equal to or more
    privileged than the access mode of the owner of that page.

 prot

    OpenVMS usage:page_protection
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Page protection to be assigned to the specified pages. The prot
    argument is a longword value containing the protection code. Only
    bits 0 to 3 are used; bits 4 to 31 are ignored.

    The $PRTDEF macro for MACRO-32 and the include file PRTDEF.H for
    C define the symbolic names for the protection codes.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of the range of pages whose
    protection was actually changed. The return_va_64 argument is
    the 32- or 64-bit virtual address of a naturally aligned quadword
    into which the service returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the virtual address range whose protection was
    actually changed. The return_length_64 argument is the 32- or
    64-bit virtual address of a naturally aligned quadword into which
    the service returns the length of the virtual address range in
    bytes.

 return_prot_64

    OpenVMS usage:page_protection
    type:         longword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Protection previously assigned to the last page in the range.
    The return_prot_64 argument is the 32- or 64-bit virtual address
    of a naturally aligned longword into which $SETPRT_64 writes the
    protection of this page. The return_prot_64 argument is useful
    only when protection for a single page is being changed.

276  –  $SETPRV

    Enables or disables specified privileges for the calling process.

    Format

      SYS$SETPRV  [enbflg] ,[prvadr] ,[prmflg] ,[prvprv]

    C Prototype

      int sys$setprv  (char enbflg, struct _generic_64 *prvadr, char

                      prmflg, struct _generic_64 *prvprv);

276.1  –  Arguments

 enbflg

    OpenVMS usage:boolean
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Indicator specifying whether the specified privileges are to be
    enabled or disabled. The enbflg argument is a longword value.
    The value 1 indicates that the privileges specified in the prvadr
    argument are to be enabled. The value 0 (the default) indicates
    that the privileges are to be disabled.

 prvadr

    OpenVMS usage:mask_privileges
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Privileges to be enabled or disabled for the calling process. The
    prvadr argument is the address of a quadword bit vector wherein
    each bit corresponds to a privilege that is to be enabled or
    disabled.

    Each bit has a symbolic name. The $PRVDEF macro defines these
    names. You form the bit vector by specifying the symbolic
    name of each desired privilege in a logical OR operation. The
    following table provides the symbolic name and description of
    each privilege:

    User
    Privilege   Symbolic Name      Description

    ACNT        PRV$M_ACNT         Create processes for which no
                                   accounting is done
    ALLSPOOL    PRV$M_ALLSPOOL     Allocate a spooled device
    ALTPRI      PRV$M_ALTPRI       Set (alter) any process priority
    AUDIT       PRV$V_AUDIT        Generate audit records
    BUGCHK      PRV$M_BUGCHK       Make bugcheck error log entries
    BYPASS      PRV$M_BYPASS       Bypass all protection
    CMEXEC      PRV$M_CMEXEC       Change mode to executive
    CMKRNL      PRV$M_CMKRNL       Change mode to kernel
    DIAGNOSE    PRV$M_DIAGNOSE     Can diagnose devices
    DOWNGRADE   PRV$V_DOWNGRADE    Can downgrade classification
    EXQUOTA     PRV$M_EXQUOTA      Can exceed quotas
    GROUP       PRV$M_GROUP        Group process control
    GRPNAM      PRV$M_GRPNAM       Place name in group logical name
                                   table
    GRPPRV      PRV$V_GRPPRV       Group access by means of system
                                   protection field
    IMPERSONATE PRV$M_             Create detached processes under
                IMPERSONATE        another UIC
    IMPORT      PRV$V_IMPORT       Mount a nonlabeled tape volume
    LOG_IO      PRV$M_LOG_IO       Perform logical I/O operations
    MOUNT       PRV$M_MOUNT        Issue mount volume QIO
    NETMBX      PRV$M_NETMBX       Create a network device
    OPER        PRV$M_OPER         All operator privileges
    PFNMAP      PRV$M_PFNMAP       Map to section by physical page
                                   frame number
    PHY_IO      PRV$M_PHY_IO       Perform physical I/O operations
    PRMCEB      PRV$M_PRMCEB       Create permanent common event flag
                                   clusters
    PRMGBL      PRV$M_PRMGBL       Create permanent global sections
    PRMMBX      PRV$M_PRMMBX       Create permanent mailboxes
    PSWAPM      PRV$M_PSWAPM       Change process swap mode
    READALL     PRV$V_READALL      Possess read access to everything
    SECURITY    PRV$V_SECURITY     Can perform security functions
    SETPRV      PRV$M_SETPRV       Set any process privileges
    SHARE       PRV$M_SHARE        Can assign a channel to a
                                   nonshared device
    SHMEM       PRV$M_SHMEM        Allocate structures in memory
                                   shared by multiple processors
    SYSGBL      PRV$M_SYSGBL       Create system global sections
    SYSLCK      PRV$M_SYSLCK       Queue systemwide locks
    SYSNAM      PRV$M_SYSNAM       Place name in system logical name
                                   table
    SYSPRV      PRV$M_SYSPRV       Access files and other resources
                                   as if you have a system UIC
    TMPMBX      PRV$M_TMPMBX       Create temporary mailboxes
    UPGRADE     PRV$V_UPGRADE      Can upgrade classification
    VOLPRO      PRV$M_VOLPRO       Override volume protection
    WORLD       PRV$M_WORLD        World process control

    If you do not specify prvadr or assign it the value 0, the
    privileges are not altered.

 prmflg

    OpenVMS usage:boolean
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Indicator specifying whether the privileges are to be affected
    permanently or temporarily. The prmflg argument is a longword
    value. The value 1 specifies that the privileges are to be
    affected permanently, that is, until you change them again
    by using $SETPRV or until the process is deleted. The value 0
    (the default) specifies that the privileges are to be affected
    temporarily, that is, until the current image exits (at which
    time the permanently enabled privileges of the process will be
    restored).

    Setting the prmflg argument to nonzero changes privilege bits in
    both the CURPRIV mask and the PROCPRIV mask.

 prvprv

    OpenVMS usage:mask_privileges
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    Privileges previously possessed by the calling process. The
    prvprv argument is the address of a quadword bit vector wherein
    each bit corresponds to a privilege that was previously either
    enabled or disabled. If you do not specify prvprv or assign it
    the value 0, the previous privilege mask is not returned.

277  –  $SETRWM

    Allows a process to specify what action system services should
    take when system resources required for their execution are
    unavailable.

                                 CAUTION

       Disabling resource waiting should be performed with caution,
       as doing so can have unexpected effects on constituent
       sharable images and runtime libraries.

    Format

      SYS$SETRWM  [watflg]

    C Prototype

      int sys$setrwm  ( char watflg);

277.1  –  Argument

 watflg

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Indicator specifying whether system services should wait for
    required resources. The watflg argument is a longword value. The
    value 0 (the default) specifies that system services should wait
    until resources needed for their execution become available.
    The value 1 specifies that system services should return failure
    status immediately when resources needed for their execution are
    unavailable.

    The operating system enables resource wait mode for all
    processes. You can disable resource wait mode only by calling
    $SETRWM.

    If resource wait mode is disabled, it remains disabled until it
    is explicitly reenabled or until the process is deleted.

278  –  $SETSHLV

    Controls whether a process automatically unshelves files.

    Format

      SYS$SETSHLV  [pidadr] ,[prcnam] ,[shlvflg]

    C Prototype

      int sys$setshlv  (unsigned int *pidadr, void *prcnam, unsigned

                       int shlvflg);

278.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) of the process. The pidadr argument
    is the address of the PID. The pidadr argument can only refer to
    a process running on the local node. You cannot modify a process
    on a remote node.

    You must specify the pidadr argument to modify a process whose
    UIC group number is different from that of the calling process.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Process name of the process. The prcnam argument is the address
    of a character string descriptor pointing to the process name.
    You identify a process with a 1- to 15-character string.

    You can only use the prcnam argument to modify a process in the
    same UIC group as the calling process. To modify a process in
    another UIC group, you must specify the pidadr argument.

 shlvflg

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Value specifying whether automatic unshelving is to be turned on
    or off. The shlvflg argument is a longword containing this value.
    The value 0 turns automatic unshelving on. The value 1 turns
    automatic unshelving off.

278.2  –  Description

    The Set Automatic Unshelving service controls whether a process
    automatically unshelves files.

    The pidadr and prcnam default to the current process. If the
    longword at address pidadr is 0, the PID of the target process is
    returned.

    The setting for automatic unshelving is inherited by
    subprocesses.

    The DCL command SET PROCESS/[NO]AUTOUNSHELVE also controls
    automatic unshelving for a process; for details, see the VSI
    OpenVMS DCL Dictionary.

    Required Access or Privileges

    Depending on the operation, the calling process might need one of
    the following privileges to use $SETSHLV:

    o  GROUP privilege to modify a process in the same group, unless
       the target process has the same UIC as the calling process.

    o  WORLD privilege to modify any process in the system.

    Required Quota

    None

    Related Services

    $GETJPI

278.3  –  Condition Values Returned

    SS$_WASCLR         The service completed successfully. Automatic
                       unshelving was previously on.
    SS$_WASSET         The service completed successfully. Automatic
                       unshelving was previously off.
    SS$_ACCVIO         An argument was not accessible by the caller.
    SS$_BADPARAM       The shlvflg argument was invalid.
    SS$_IVLOGNAM       The prcnam argument was invalid. The process
                       name string had either 0 characters or more
                       than 15 characters.
    SS$_NONEXPR        The specified process did not exist, or the
                       specified process identification was invalid.
    SS$_NOPRIV         The caller did not have the privilege to
                       modify other processes.
    SS$_REMOTE_PROC    The specified process was not on the local
                       node. The service cannot modify a process on a
                       remote node.

279  –  $SETSTK

    Allows a process to change the size of its supervisor, executive,
    and kernel stacks by altering the values in the stack limit for a
    memory stack and base arrays held in P1 (per-process) space.

    Format

      SYS$SETSTK  inadr ,[retadr] ,[acmode]

    C Prototype

      int sys$setstk  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode);

279.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Range of addresses that express the stack's new limits. The inadr
    argument is the address of a 2-longword array containing, in
    order, the address of the top of the stack and the address of the
    base of the stack. Because stacks in P1 space expand from high
    to low addresses, the address of the base of the stack must be
    greater than the address of the top of the stack.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Range of addresses that express the stack's previous limits. The
    retadr argument is the address of a 2-longword array into which
    $SETSTK writes, in the first longword, the previous address of
    the top of the stack and, in the second longword, the previous
    address of the base of the stack.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode of the stack to be altered. The acmode argument is
    a longword containing the access mode. The $PSLDEF macro defines
    symbols for the four access modes. The most privileged access
    mode used is the access mode of the caller.

    If acmode specifies user mode, $SETSTK performs no operation and
    returns the SS$_NORMAL condition value.

280  –  $SETSTK 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, allows a process to change
    the size of its supervisor, executive, and kernel stacks by
    altering the values in the stack limit for a memory stack or a
    register stack and base arrays held in P1 (per-process) space.

    Format

      SYS$SETSTK_64  start_va_64 ,length_64 ,acmode, flags,

                     prev_start_va, prev_length

    C Prototype

      int sys$setstk_64  (void *start_va_64, unsigned __int64

                         length_64, unsigned int acmode, unsigned int

                         flags, void ** prev_start_va_64, unsigned

                         __int64 * prev_length_64);

280.1  –  Arguments

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    Lowest address in range of addresses that express the stack's new
    limits. For a memory stack, this address is the stack limit. For
    an Integrity servers register stack, this address is the stack
    base.

 length_64

    OpenVMS usage:length
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the range of addresses that express the stack's new
    limits.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode of the stack to be altered. The acmode argument is
    a longword containing the access mode. The $PSLDEF macro defines
    symbols for the four access modes. The most privileged access
    mode used is the access mode of the caller.

    If acmode specifies user mode, $SETSTK_64 performs no operation
    and returns the SS$_NORMAL condition value.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    0 for memory stack (Alpha and Integrity servers VA$M_SETSTK_
    REGISTER for register stack (Integrity servers only)

    The $VADEF macro and VADEF.H file define symbolic names for the
    flags argument.

 prev_start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by reference
    Lowest address in the range of addresses that express the stack's
    previous limits. For a memory stack, this address was the stack
    limit. For an Integrity servers register stack, this address was
    the stack base.

 prev_length_64

    OpenVMS usage:length
    type:         quadword
    access:       write only
    mechanism:    by reference
    Length of the range of addresses that express the stack's
    previous limits.

281  –  $SETSWM

    Allows a process to control whether it can be swapped out of the
    balance set.

    Format

      SYS$SETSWM  [swpflg]

    C Prototype

      int sys$setswm  (char swpflg);

281.1  –  Argument

 swpflg

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Indicator specifying whether the process can be swapped. The
    swpflg argument is a longword value. The value 0 (the default)
    enables process swap mode, meaning the process can be swapped.
    The value 1 disables process swap mode, meaning the process
    cannot be swapped.

282  –  $SETUAI

    Modifies the user authorization file (UAF) record for a specified
    user.

    Format

      SYS$SETUAI  [nullarg] ,[contxt] ,usrnam ,itmlst ,[nullarg]

                  ,[nullarg] ,[nullarg]

    C Prototype

      int sys$setuai  (unsigned int efn, unsigned int *contxt, void

                      *usrnam, void *itmlst, struct _iosb *iosb, void

                      (*astadr)(__unknown_params), int astprm);

282.1  –  Arguments

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

 contxt

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    A longword used to maintain authorization file context. The
    contxt argument is the address of a longword to receive a $SETUAI
    context value. On the initial call, this longword should contain
    the value -1. On subsequent calls, the value of the contxt
    argument from the previous call should be passed back in.

 usrnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the user whose UAF record is modified. The usrnam
    argument is the address of a descriptor pointing to a character
    text string containing the user name. The user name string can
    contain a maximum of 32 alphanumeric characters.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying which information from the specified UAF
    record is to be modified. The itmlst argument is the address of a
    list of one or more item descriptors, each of which specifies an
    item code. The item list is terminated by the item code 0 or by
    the longword 0.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

 nullarg

    OpenVMS usage:nullarg
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    Placeholding argument Reserved to VSI.

 nullarg

    OpenVMS usage:nullarg
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    Placeholding argument Reserved to VSI.

 nullarg

    OpenVMS usage:nullarg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

283  –  $SETUP AVOID PREEMPT

    Performs initial setup for process preemption avoidance.

    Format

      SYS$SETUP_AVOID_PREEMPT  enable

    C Prototype

      int sys$setup_avoid_preempt  (int enable);

283.1  –  Arguments

 enable

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Enables or disables preemption avoidance. If the enable argument
    is set to 1, preemption avoidance is enabled; if 0, preemption
    avoidance is disabled.

284  –  $SET DEFAULT TRANS

    Sets or clears the default transaction of the calling process.

    Format

      SYS$SET_DEFAULT_TRANS  [efn] ,[flags] ,iosb [,[astadr]

                             ,[astprm] ,[new_tid] ,[old_tid]]

    C Prototype

      int sys$set_default_trans  (unsigned int efn, unsigned int

                                 flags, struct _iosb *iosb,...);

284.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for the option
    flag, described in $SET_DEFAULT_TRANS Option Flag. All undefined
    bits must be 0. If this argument is omitted, no flags are used.

    Table SYS-25 $SET_DEFAULT_TRANS Option Flag

    Flag Name      Description

    DDTM$M_SYNC    Specifies successful synchronous completion by
                   returning SS$_SYNCH. When SS$_SYNCH is returned,
                   the AST routine is not called, the event flag is
                   not set, and the I/O status block is not filled
                   in.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the completion status of the
    service is returned as a condition value.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the I/O status block diagram.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine executed when the service completes, if SS$_
    NORMAL is returned in R0. The astadr argument is the address of
    the entry mask of this routine. The routine is executed in the
    same access mode as that of the caller of the $SET_DEFAULT_TRANS
    service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter passed to the AST routine specified by the
    astadr argument.

 new_tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (TID) of the new default transaction for the
    calling process. If this argument is zero (the default) or if it
    specifies a zero TID (an octaword of zeros), the service clears
    the default transaction of the calling process.

 old_tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       write only
    mechanism:    by reference
    An octaword in which the service returns the identifier (TID) of
    the calling process' previous transaction (the one that was set
    or cleared by this call to $SET_DEFAULT_TRANS).

    A zero TID is returned if the calling process did not have a
    default transaction prior to the call.

285  –  $SET DEFAULT TRANSW

    Sets or clears the default transaction of the calling process.

    $SET_DEFAULT_TRANSW always waits for the request to complete
    before returning to the caller. Other than this, it is identical
    to $SET_DEFAULT_TRANS.

    Format

      SYS$SET_DEFAULT_TRANSW  [efn] ,[flags] ,iosb [,[astadr]

                              ,[astprm] ,[new_tid] ,[old_tid]]

    C Prototype

      int sys$set_default_transw  (unsigned int efn, unsigned int

                                  flags, struct _iosb *iosb,...);

286  –  $SET DEVICE

    Modifies the characteristics of a device or the paths used to
    access that device.

    For synchronous completion, use the Set Device Characteristics
    and Wait ($SET_DEVICEW) service. The $SET_DEVICEW service is
    identical to the $SET_DEVICE service, except that $SET_DEVICEW
    returns to the caller only after the requested action has taken
    effect.

    For additional information about system service completion, see
    the Synchronize ($SYNCH) service.

    Format

      SYS$SET_DEVICE  [efn] [,chan] [,devnam] ,itmlst [,iosb]

                      [,astadr] [,astprm] [,nullarg]

    C Prototype

      int sys$set_device  (unsigned int efn, unsigned short int chan,

                          void *devnam, void *itmlst, struct _iosb

                          *iosb, void (*astadr)(__unknown_params),

                          int astprm, struct_generic_64 *nullarg);

286.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when $SET_DEVICE returns the
    requested information. The efn argument is a longword containing
    this number; however, $SET_DEVICE uses only the low-order byte.

    Upon request initiation, $SET_DEVICE clears the specified event
    flag (or event flag 0 if efn was not specified). Then, when $SET_
    DEVICE returns the requested information, it sets the specified
    event flag (or event flag 0).

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Number of the I/O channel assigned to the device about which
    information is desired. The chan argument is a word containing
    this number.

    To identify a device to $SET_DEVICE, you can specify either the
    chan or devnam parameters, but you should not specify both. If
    you specify both arguments, the chan argument is used.

    If you specify neither chan nor devnam, $SET_DEVICE uses a
    default value of 0 for chan.

 devnam

    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    The name of the device about which $SET_DEVICE is to modify the
    characteristics or path settings. The devnam argument is the
    address of a character string descriptor pointing to this name
    string.

    The device name string can be either a physical device name
    or a logical name. If the first character in the string is an
    underscore (_),  the string is considered a physical device name;
    otherwise, the string is considered a logical name and logical
    name translation is performed until either a physical device name
    is found or the system default number of translations has been
    performed.

    If the device name string contains a colon (:),  the colon and
    the characters that follow it are ignored.

    To identify a device to $SET_DEVICE, you can specify either the
    chan or devnam argument, but you should not specify both. If both
    arguments are specified, the chan argument is used.

    If you specify neither chan nor devnam, $SET_DEVICE uses a
    default value of 0 for chan.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying which information about the device is to be
    returned. The itmlst argument is the address of a list of item
    descriptors, each of which describes an item of information. The
    list of item descriptors is terminated by a longword of 0.

    Currently, $SET_DEVICE allows only one valid item list entry.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block that is to receive the final completion status.
    The iosb argument is the address of the quadword I/O status
    block. See iosb in the $GETDVI system service description for
    more information.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    AST service routine to be executed when $SET_DEVICE 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 $SET_DEVICE service.

 astprm

    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 is the longword
    parameter.

 nullarg

    OpenVMS usage:null_arg
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Placeholding argument Reserved to VSI and should be zero.

287  –  $SET DEVICEW

    Modifies the characteristics of a device or the paths used to
    access that device.

    The $SET_DEVICEW completes synchronously; that is, it returns to
    the caller only after the requested action has taken effect.

    Format

      SYS$SET_DEVICEW  [efn] [,chan] [,devnam] ,itmlst [,iosb]

                       [,astadr] [,astprm] [,nullarg]

    C Prototype

      int sys$set_devicew  (unsigned int efn, unsigned short

                           int chan, void *devnam, void

                           *itmlst, struct _iosb *iosb, void

                           (*astadr)(__unknown_params), int astprm,

                           struct_generic_64 *nullarg);

288  –  $SET IMPLICIT AFFINITY (Alpha and Integrity servers)

    On Alpha and Integrity server systems, controls or retrieves the
    activation state for the implicit affinity system capability of a
    specific kernel thread or of the global process default.

    This service accepts 64-bit addresses.

    Format

      SYS$SET_IMPLICIT_AFFINITY  [pidadr] [,prcnam] [,state]

                                 [,cpu_id] [,prev_mask]

    C Prototype

      int sys$set_implicit_affinity  (unsigned int *pidadr, void

                                     *prcnam, struct _generic_64

                                     *state, int cpu_id, struct

                                     _generic_64 *prev_mask);

288.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Process identification (PID) of a kernel thread whose implicit
    affinity is to be modified or returned. The pidadr argument is
    the 32- or 64-bit address of a longword that contains the PID.

    Process selection is made through a combination of the pidadr and
    prcnam arguments. If neither are specified or if both have a zero
    value, the service operations are made to the user capability
    mask of the current kernel thread of the current calling process.
    The pidadr argument takes precedence over the prcnam argument
    where both are supplied in the service call.

    If the bit constant CAP$M_IMPLICIT_DEFAULT_ONLY is specified in
    the state argument, then the implicit affinity state portion of
    the default capability mask is modified or returned instead.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Process name of the process whose implicit affinity capability
    state is to be modified or returned. The prcnam argument is the
    32- or 64-bit address of a character string descriptor pointing
    to the process name string. A process can be identified with a
    1- to 15-character string. The service operations are made to
    the user capability mask of the initial thread of the specified
    process.

    If pidadr and prcnam are both specified, then pidadr is modified
    or returned and prcnam is ignored. If neither argument is
    specified, then the context of the current kernel thread of the
    calling process is modified or returned.

 state

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    State options that can be selected for the affected thread's
    implicit affinity. The state argument is a pointer to a quadword
    bit vector wherein a bit corresponds to a requested state for
    the implicit affinity feature. Only the bits specified below are
    used; the remainder of the quadword bits are reserved.

    Each option (bit) has a symbolic name, defined in the $CAPDEF
    macro. The state argument is constructed by performing a logical
    OR operation using the symbolic names of each desired option.

    The following table describes the symbolic name of each option:

    Symbolic Name          Description

    CAP$M_IMPLICIT_        Indicates the specified operations are to
    DEFAULT_ONLY           be performed on the global cell instead
                           of on a specific kernel thread. This bit
                           supersedes any individual kernel thread
                           specified in pidadr or prcnam. Specifying
                           this bit constant applies the implicit
                           affinity operations to all newly created
                           processes.

    CAP$M_IMPLICIT_        Indicates that the implicit affinity
    AFFINITY_SET           capability bit is to be set for the
                           specified kernel thread. This is mutually
                           exclusive with CAP$M_IMPLICIT_AFFINITY_
                           CLEAR.

    CAP$M_IMPLICIT_        Indicates that the implicit affinity
    AFFINITY_CLEAR         capability bit is to be cleared for the
                           specified kernel thread. This is mutually
                           exclusive with CAP$M_IMPLICIT_AFFINITY_
                           SET.

 cpu_id

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Identifier of the CPU requested as the first CPU on which this
    kernel thread is to execute. The cpu_id is a longword containing
    this number, which is in the supported range of individual CPUs
    from 0 to SYI$_MAX_CPUS -1.

    If no explicit CPU is needed, specifying a value of -1 in
    this argument indicates the system is to select the initial
    association based on system dynamics and load balancing.

    Note that, regardless of what explicit CPU is supplied to this
    argument, it will be taken only as a suggestion. This service
    will attempt to make the requested association, but it will be
    superseded by another CPU if the system dynamics are adversely
    affected by the operation.

 prev_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Previous implicit affinity state mask for the specified kernel
    thread before execution of this call to $SET_IMPLICIT_AFFINITY.
    The prev_mask argument is the 32- or 64-bit address of a quadword
    into which $SET_IMPLICIT_AFFINITY writes a bit mask specifying
    the implicit affinity state.

    The current state of the kernel thread's current implicit
    affinity feature can be determined by testing the returned
    mask with the symbolic bit definitions described for the state
    argument. These bit definitions are found in the $CAPDEF macro.

289  –  $SET PROCESS PROPERTIESW (Alpha and Integrity servers)

    On Alpha and Integrity server systems, sets a simple value
    associated with a process.

    Format

      SYS$SET_PROCESS_PROPERTIESW  mbz1 ,pidadr ,prcnam ,property

                                   ,value ,prev_value [,bufsiz

                                   ,bufcnt ,flags]

    C Prototype

      int sys$set_process_propertiesw  (mbz1, unsigned int *pidadr,

                                       unsigned int *prcnam, unsigned

                                       int property, unsigned __int64

                                       value, unsigned __int64

                                       *prev_value,...);

289.1  –  Arguments

 mbz1

    type:
    access:
    mechanism:    0
    Reserved for future use by VSI. Must be specified as 0.

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) of the process whose system service
    logging characteristics are to be modified. The pidadr argument
    is the address of the PID.

    Supported only for use with PPROP$C_SS_LOG_ENABLE, PPROP$C_
    SS_LOG_DISABLE, and PPROP$C_SS_LOG_UNLOAD. Otherwise, must be
    specified as 0.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Process name of the process whose priority is to be changed. The
    prcnam argument is the address of a character string descriptor
    pointing to the process name. The process name can be 1 - 15
    characters long.

    You can use the prcnam argument only on behalf of processes
    in the same UIC group as the calling process. To affect system
    service logging for processes in other groups, you must specify
    the pidadr argument.

    Supported only for use with PPROP$C_SS_LOG_ENABLE, PPROP$C_
    SS_LOG_DISABLE, and PPROP$C_SS_LOG_UNLOAD. Otherwise, must be
    specified as 0.

 property

    OpenVMS usage:integer
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    A constant that selects which property to set.

    Valid values for property are defined by the $PPROPDEF macro as
    follows:

    Property Code         Description

    PPROP$C_CASE_         The type of case lookup to use. This value
    LOOKUP_TEMP           is set for the life of the currently
                          active image. This value reverts to the
                          permanent case setting on image rundown.
                          In the absence of an explicit case lookup
                          specification in a user-provided NAML,
                          RMS uses this value to determine the case
                          setting for the current file operation.
                          Valid values are PPROP$K_CASE_BLIND and
                          PPROP$K_CASE_SENSITIVE.

                          For additional information, see the Guide
                          to OpenVMS File Applications.

    PPROP$C_CASE_         The type of case lookup to use. This value
    LOOKUP_PERM           is set for the life of the process or
                          until the case is set again. Setting
                          this value affects only future activated
                          images for this process. To change the case
                          setting for the current active image, you
                          must modify the PPROP$C_CASE_LOOKUP_TEMP
                          setting.

                          Valid values are PPROP$K_CASE_BLIND and
                          PPROP$K_CASE_SENSITIVE.

                          For additional information, see the Guide
                          to OpenVMS File Applications.

    PPROP$C_SEARCH_       Processes the active search mode. The value
    SYMLINK_TEMP          reverts to the permanent setting on image
                          rundown. Valid values are PPROP$K_SEARCH_
                          SYMLINK_NONE, PPROP$K_SEARCH_SYMLINK_ALL,
                          and PROP$K_SEARCH_SYMLINK_NOELLIPS.

    PPROP$C_SEARCH_       Processes the permanent search mode. This
    SYMLINK_PERM          value is set for the life of the process.
                          Changing this setting only changes the
                          behavior of subsequently activated images.
                          Valid values are PPROP$K_SEARCH_SYMLINK_
                          NONE, PPROP$K_SEARCH_SYMLINK_ALL, and
                          PROP$K_SEARCH_SYMLINK_NOELLIPS.

    PPROP$C_DEADLOCK_     The per-process deadlock wait time (in
    WAIT                  100-ns units). A value of zero resets and
                          disables the per-process deadlock wait time
                          and fallback to the systemwide deadlock
                          wait time that comes from the system
                          parameter DEADLOCK_WAIT. Valid values are
                          in the range of 100000 (=10ms) and 10000000
                          (=1 s). If the value is too small, the per-
                          process deadlock wait is set to 10 ms; if
                          the value is too large, it is set to 1 s.

    PPROP$C_HOME_RAD      The Resource Affinity Domain (RAD) to which
                          the process is assigned. Newly mapped
                          memory in the process will come from the
                          home RAD of the process. Currently mapped
                          memory will not move into the new home RAD
                          unless $PURGWS is issued.

                          Valid values are integers between 0 and the
                          maximum RAD on the system. Valid home RADs
                          must also contain either memory or CPUs.

    PPROP$C_KERNEL_       Sets the process specific limit of the
    THREAD_LIMIT          number of kernel threads that can be
                          created. By default, this is controlled
                          systemwide through the SYSGEN parameter
                          MULTITHREAD. A value between 0 (use
                          default) and the current setting of the
                          MULTITHREAD parameter can be used.

    PPROP$C_MEDDLE        Reserved for use by VSI.

    PPROP$C_MEDDLE_       Reserved for use by VSI.
    ENABLE

    PPROP$C_PARSE_        The type of command parsing to use. This
    STYLE_TEMP            value is set only for the life of the
                          image. The value reverts to the permanent
                          style on image rundown. Valid values
                          are PARSE_STYLE$C_TRADITIONAL and PARSE_
                          STYLE$C_EXTENDED.

    PPROP$C_PARSE_        The type of command parsing to use. This
    STYLE_PERM            value is set for the life of the process
                          unless the style is set again. Valid values
                          are PARSE_STYLE$C_TRADITIONAL and PARSE_
                          STYLE$C_EXTENDED.

    PPROP$C_SS_LOG_       Stop logging system service requests
    DISABLE               for the current or specified process. If
                          logging was previously disabled, the value
                          returned in prev_value is 0. If logging was
                          previously enabled, the value returned is
                          1.

                          For more information, see the VSI OpenVMS
                          System Analysis Tools Manual.

    PPROP$C_SS_LOG_       Allocate log buffers and enable logging of
    ENABLE                system service requests for the current
                          or specified process. If logging was
                          previously disabled, the value returned in
                          prev_value is 0. If logging was previously
                          enabled, the value returned is 1.

                          For more information, see the VSI OpenVMS
                          System Analysis Tools Manual.

    PPROP$C_SS_LOG_       Stop logging system service requests for
    UNLOAD                the current or specified process and close
                          the log file so that it can be analyzed. If
                          logging was previously disabled, the value
                          returned in prev_value is 0. If logging was
                          previously enabled, the value returned is
                          1.

                          For more information, see the VSI OpenVMS
                          System Analysis Tools Manual.

    PPROP$C_TOKEN         Controls the token size used by DCL. When
                          the bit is clear (the default), traditional
                          tokens are used, and each command token can
                          hold up to 255 characters. When the bit is
                          set, extended tokens are used; each command
                          token can be up to 4000 characters.

    PPROP$C_UNITS         Controls the process units. When the bit
                          is clear (the default), all size-related
                          numbers are displayed in blocks. When
                          the bit is set, size-related numbers are
                          converted to bytes.

 value

    OpenVMS usage:integer
    type:         quadword (unsigned)
    access:       read
    mechanism:    by value
    A quadword value to which to set the property.

 prev_value

    OpenVMS usage:access_mode
    type:         quadword (unsigned) address of a quadword value
    access:       write
    mechanism:    by reference
    The address of a quadword that will receive the previous value of
    the property.

 bufsize

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The requested system service log buffer size in bytes. Supported
    only for use with PPROP$C_SS_LOG_ENABLE. If omitted, it defaults
    to 65,024 bytes. The maximum value is 65,024 bytes. The minimum
    value is 4096 bytes.

 bufcnt

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The requested number of system service log buffers. Supported
    only for use with PPROP$C_SS_LOG_ENABLE. If omitted, it defaults
    to 2. The maximum number of buffers is 6.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flag mask specifying the enable logging request. The flags
    argument is a longword bit vector in which each bit corresponds
    to a flag. The $LOGTYPDEF macro and the LOGTYPDEF.H file define a
    symbolic name for each flag.

    The $LOGTYPDEF macro defines the following symbolic names for the
    fault characteristic codes:

    Symbol         Description

    LOGTYP$M_      Log system service arguments.
    ARGS
    LOGTYP$M_      Write log information to a file.
    FILE

    If you specify the flags argument as 0, the service defaults to
    logging to a file and logging arguments.

    If you specify LOGTYP$M_ARGS but lack privilege, service
    arguments are not logged.

290  –  $SET RESOURCE DOMAIN

    Controls the association between a calling process and resource
    domains.

    Format

      SYS$SET_RESOURCE_DOMAIN  func ,rsdm_id ,domain_number

                               ,[nullarg] ,[access] ,[acmode]

    C Prototype

      int sys$set_resource_domain  (unsigned int func, unsigned

                                   int *rsdm_id, unsigned int

                                   domain_number, unsigned int

                                   nullarg, unsigned int access,

                                   unsigned int acmode);

290.1  –  Arguments

 func

    OpenVMS usage:function_code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Function code specifying the action that $SET_RESOURCE_DOMAIN
    is to perform. The func argument is a longword containing this
    function code.

    See the Function Codes section in the VSI OpenVMS System Services
    Reference Manual for a description of $SET_RESOURCE_DOMAIN
    function codes.

 rsdm_id

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       write only to join, read only to leave
    mechanism:    by reference
    Resource domain identification. The rsdm_id argument is the
    address of a longword specifying the association of the calling
    process with the resource domain.

    The RSDM$_JOIN_DOMAIN function returns a resource domain
    identification. The RSDM$_LEAVE function requires the rsdm_id
    argument as input to specify which resource domain association
    the process is leaving.

    The resource domain identification can be used as input to the
    $ENQ and $ENQW system services.

 domain_number

    OpenVMS usage:longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Domain number that identifies the resource domain. The domain_
    number argument is a longword value containing the resource
    domain number.

    The domain_number argument is required for the RSDM$_JOIN_DOMAIN
    function but ignored for the RSDM$_LEAVE function.

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholder Reserved to VSI. You must specify 0.

 access

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Types of access desired when using the lock management services
    within the resource domain. The access argument is a longword
    bit mask specifying the access types required; these can include
    read, write, and lock.

    The following table lists the symbols that the $RSDMDEF macro
    defines, their descriptions, and the lock management system
    services that might require each type of access:

                   Access
    Symbol         Description      System Service

    RSDM$M_READ    Read lock value  $DEQ, $ENQ, $ENQW, $GETLKI,
                   blocks           $GETLKIW
    RSDM$M_WRITE   Write lock       $DEQ, $ENQ, $ENQW,
                   value blocks
    RSDM$M_LOCK    Take locks       $ENQ, $ENQW

    The service grants the desired access, provided your process has
    the necessary access rights to the resource domain. If you do not
    specify the access argument or if you specify 0, $SET_RESOURCE_
    DOMAIN attempts to access the domain in the following order:

    1. Read, write, lock

    2. Read, lock

    3. Write, lock

    4. Lock

    The access attempt terminates with the first success.

    The access argument defaults to 0. It is ignored for the RSDM$_
    LEAVE function.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode requested for the association to the resource domain.
    The most privileged access mode granted is the access mode of the
    caller. Locks cannot be taken from access modes less privileged
    than the access mode of the association.

    The acmode argument is a longword containing the access mode. The
    $PSLDEF macro defines the following symbols for the access modes:

    Symbolic      Access     Privilege
    Name          Mode       Rank

    PSL$C_KERNEL  Kernel     High
    PSL$C_EXEC    Executive  -
    PSL$C_SUPER   Supervisor -
    PSL$C_USER    User       Low

    The acmode argument is optional for the RSDM$_JOIN_DOMAIN
    function. If you do not specify the acmode argument, the access
    mode is set to the access mode of the calling process. The acmode
    argument is ignored for the RSDM$_LEAVE function.

291  –  $SET RETURN VALUE (Alpha and Integrity servers)

    On Alpha and Integrity server systems, sets the return values
    or condition codes in the Mechanism Array, independent of the
    architecture.

    Format

      SYS$SET_RETURN_VALUE  mechanism_arg, return_type, return_value

    C Prototype

      int sys$set_return_value  (void *mechanism_arg, unsigned int

                                *return_type, void *return_value);

291.1  –  Arguments

 mechanism_arg

    OpenVMS usage:mechanism vector address
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    The address of the location of the mechanism vector. If the
    mechanism_arg argument is 0, the mechanism vector for the
    currently active signal is used.

    If the address of the return_type argument is 0, the return_
    value argument is fetched by value and is treated as return-type
    PSIG$K_FR_U32. This combination of arguments can be used to set a
    condition code, such as SS$_ACCVIO, as a return value.

 return_type

    OpenVMS usage:integer
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    The address of the location of a longword that contains one of
    the function return signature codes.

    If the address of the return_type argument is 0, the return_
    value argument is fetched by value and is treated as return-type
    PSIG$K_FR_U32. This combination of arguments can be used to set a
    condition code, such as SS$_ACCVIO, as a return value.

 return_value

    OpenVMS usage:buffer
    type:         scalar
    access:       read only
    mechanism:    by reference
    The address of the location that contains a value of the
    appropriate type. The referenced value is read as a longword,
    quadword, or octaword, depending on the return_type.

    If the address of the return_type argument is 0, the return_
    value argument is fetched by value and is treated as return-type
    PSIG$K_FR_U32. This combination of arguments can be used to set a
    condition code, such as SS$_ACCVIO, as a return value.

292  –  $SET SECURITY

    Modifies the security characteristics of a protected object.

    Format

      SYS$SET_SECURITY  [clsnam] ,[objnam] ,[objhan] ,[flags]

                        ,[itmlst] ,[contxt] ,[acmode]

    C Prototype

      int sys$set_security  (void *clsnam, void *objnam, unsigned

                            int *objhan, unsigned int flags, void

                            *itmlst, unsigned int *contxt, unsigned

                            int *acmode);

292.1  –  Arguments

 clsnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Name of the object class. The clsnam argument is the address of
    a descriptor pointing to a string that contains the name of the
    object class.

    The following is a list of the protected object class names:

       CAPABILITY
       COMMON_EVENT_CLUSTER
       DEVICE
       FILE
       GLXGRP_GLOBAL_SECTION
       GLXSYS_GLOBAL_SECTION
       GROUP_GLOBAL_SECTION
       ICC_ASSOCIATION
       LOGICAL_NAME_TABLE
       QUEUE
       RESOURCE_DOMAIN
       SECURITY_CLASS
       SYSTEM_GLOBAL_SECTION
       VOLUME

 objnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Name of the protected object whose associated security profile
    is going to be retrieved. The objnam argument is the address
    of a descriptor pointing to a string containing the name of the
    protected object.

    The format of an object name is class specific. The following
    table lists object names and describes their formats:

    Object Class        Object Name Format

    CAPABILITY          A character string. Currently, the only
                        capability object is VECTOR.

    COMMON_EVENT_       Name of the event flag cluster, as defined
    CLUSTER             in the Associate Common Event Flag Cluster
                        ($ASCEFC) system service.

    DEVICE              Standard device specification, described in
                        the OpenVMS User's Manual.

    FILE                Standard file specification, described in the
                        OpenVMS User's Manual.

    GROUP_GLOBAL_       Section name, as defined in the Create and
    SECTION             Map Section ($CRMPSC) system service.

    ICC_ASSOCIATION     ICC security object name node::association_
                        name. The special node name, ICC$::, refers
                        to entries in the clusterwide registry. For
                        registry entries, the Access Access Type does
                        not apply.

    LOGICAL_NAME_TABLE  Table name, as defined in the Create Logical
                        Name Table ($CRELNT) system service.

    QUEUE               Standard queue name, as described in the Send
                        to Job Controller ($SNDJBC) system service.

    RESOURCE_DOMAIN     An identifier or octal string enclosed in
                        brackets.

    SECURITY_CLASS      Any class name shown in the Object Class
                        column of this table, or a class name
                        followed by a period (.) and the template
                        name. Use the DCL command SHOW SECURITY to
                        display possible template names.

    SYSTEM_GLOBAL_      Section name, as defined in the Create and
    SECTION             Map Section ($CRMPSC) system service.

    VOLUME              Volume name or name of the device on which
                        the volume is mounted.

 objhan

    OpenVMS usage:object_handle
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Data structure identifying the object to address. The objhan
    argument is an address of a longword containing the object
    handle. You can use the objhan argument as an alternative to the
    objnam argument; for example, a channel number clearly specifies
    the file open on the channel and can serve as an object handle.

    The following table shows the format of the object classes:

    Object Class         Object Handle Format

    COMMON_EVENT_        Event flag number
    CLUSTER
    DEVICE               Channel number
    FILE                 Channel number
    RESOURCE_DOMAIN      Resource domain identifier
    VOLUME               Channel number

 flags

    OpenVMS usage:flags
    type:         mask_longword
    access:       read only
    mechanism:    by value
    Mask specifying processing options. The flags argument is a
    longword bit vector wherein a bit, when set, specifies the
    corresponding option. The flags argument requires the contxt
    argument.

    The following table describes each flag:

    Symbolic Name   Description

    OSS$M_LOCAL     Do not update the master profile for the
                    specified object. This flag allows you to call
                    $SET_SECURITY several times to modify a local
                    copy of a profile; once the modifications are
                    satisfactory, you can clear the OSS$M_LOCAL flag,
                    set the OSS$M_RELCTX flag, and have $SET_SECURITY
                    update the master profile. The flag applies only
                    to calls made with the contxt argument.

    OSS$M_RELCTX    Release the context structure at the completion
                    of this request.

    The $OSSDEF macro defines symbolic names for the flag bits. You
    construct the flags argument by specifying the symbolic names of
    each desired option.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying which information about the process or
    processes is to be modified. The itmlst argument is the address
    of a list of item descriptors, each of which describes an item
    of information. The list of item descriptors is terminated by a
    longword of 0.

    With the item list, the user modifies the protected object's
    characteristics. The user defines which security characteristics
    to modify. If this argument is not present, only the flags
    argument is processed. Without the itmlst argument, you can
    only manipulate the security profile locks or release contxt
    resources.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the item code diagram and descriptor fields table.

 contxt

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value used to maintain protected object processing context when
    dealing with a single protected object across multiple $GET_
    SECURITY/$SET_SECURITY calls. Whenever the context value is
    nonzero, the class name, object name, or object handle arguments
    are disregarded. An input value of 0 indicates that a new context
    should be established.

    Because an active context block consumes process memory, be sure
    to release the context block by setting the RELCTX flag when the
    profile processing is complete. $SET_SECURITY sets the context
    argument to 0 once the context is released.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Access mode to be used in the object protection check. The acmode
    argument is the address of a longword containing the access mode.
    The acmode argument defaults to kernel mode; however, the system
    compares acmode with the caller's access mode and uses the least
    privileged mode. The access modes are defined in the system macro
    $PSLDEF library.

    VSI recommends that this argument be omitted (passed as zero).

293  –  $SET SYSTEM EVENT (Alpha and Integrity servers)

    On Alpha and Integrity server systems, establishes a request for
    notification when an OpenVMS system event occurs.

    Format

      SYS$SET_SYSTEM_EVENT  event ,astadr ,astprm ,acmode ,flags

                            ,handle

    C Prototype

      int sys$set_system_event  (unsigned int event, void

                                (*astadr)(__unknown_params), int

                                astprm, unsigned int acmode, unsigned

                                int flags, struct _generic_64 *

                                handle);

293.1  –  Arguments

 event

    OpenVMS usage:event_code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Event code indicating the type of system event for which an AST
    is to be delivered. The event argument is a value indicating
    which type of event is of interest.

    Each event type has a symbolic name. The $SYSEVTDEF macro defines
    the following symbolic names:

    Symbolic Name               Description

    SYSEVT$C_ADD_MEMBER         One or more OpenVMS instances have
                                joined the OpenVMS Galaxy sharing
                                community.
    SYSEVT$C_DEL_MEMBER         One or more OpenVMS instances have
                                left the OpenVMS Galaxy sharing
                                community.
    SYSEVT$C_ADD_ACTIVE_CPU     One or more processors have become
                                active within this OpenVMS instance.
    SYSEVT$C_DEL_ ACTIVE_CPU    One or more processors have become
                                inactive within this OpenVMS
                                instance.
    SYSEVT$C_ADD_CONFIG_CPU     One or more CPUs have been added to
                                the set of available CPUs for this
                                OpenVMS instance.
    SYSEVT$C_DEL_CONFIG_CPU     One or more processors have been
                                removed from this OpenVMS instance.
    SYSEVT$C_TDF_CHANGE         The system's time differential factor
                                has changed.
    SYSEVT$C_CPU_DEALLOCATE     One or more processors have been
                                deallocated from this OpenVMS
                                instance.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32-bit or 64-bit reference
    Notification AST routine to receive control after a change in
    OpenVMS system configuration occurs.

 astprm

    OpenVMS usage:user_arg
    type:         quadword
    access:       read only
    mechanism:    by value
    The quadword AST parameter to be passed to the AST routine.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode at which the system event AST is to execute. The
    acmode argument is a longword containing the access mode.

    Each access mode has a symbolic name. The $PSLDEF macro defines
    the following symbols for the four access modes.

    Symbolic Name      Description

    PSL$C_KERNEL       Kernel
    PSL$C_EXEC         Executive
    PSL$C_SUPER        Supervisor
    PSL$C_USER         User

    The value of the access mode is maximized with the access mode of
    the caller.

 flags

    type:
    access:
    mechanism:    0
    Defined in SYSEVTDEF.

    SYSEVT$M_REPEAT_       When this flag is set, event notification
    NOTIFY                 is repeated.

 handle

    OpenVMS usage:handle
    type:         quadword (unsigned)
    access:       read/write
    mechanism:    by reference
    The virtual address of a naturally aligned quadword for the event
    handle.

294  –  $SET UNWIND TABLE (Integrity servers Only)

    Registers or extends unwind table (UT) information.

    Format

      SYS$SET_UNWIND_TABLE  code_base_va, code_size, ut_base_va,

                            ut_size, gp_value, unwind_info_base, name

    C Prototype

      ind SYS$SET_UNWIND_TABLE  (unsigned __int64 code_base_va,

                                unsigned __int64 code_size, unsigned

                                __int64 ut_base_va, unsigned __int64

                                ut_size, unsigned __int64 gp_value,

                                unsigned __int64 unwind_info_base,

                                void *name);

294.1  –  Arguments

 code_base_va

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        read only
    mechanism:     by value
    With code_size, defines the potential code range. code_base_va
    is required for both creation and extension calls. code_base_va
    is the process virtual address of the start of the code region.
    code_size is the size of the code region in bytes. An error is
    returned if this overlaps any existing range.

 code_size

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        read only
    mechanism:     by value
    With code_base_va, defines the potential code range. code_base_va
    is required for both creation and extension calls. code_base_va
    is the process virtual address of the start of the code region.
    code_size is the size of the code region in bytes. An error is
    returned if this overlaps any existing range.

 ut_base_va

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        read only
    mechanism:     by value
    With ut_size, describes the unwind table (UT). ut_base_va is the
    process virtual address of the UT and must be quadword aligned.
    ut_size is the size of the UT in bytes and must be a multiple of
    the size (24 bytes: 3 quadwords) of an unwind table entry (UTE).
    The UTEs must describe nonoverlapping code subregions within the
    overall code region.

 ut_size

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        read only
    mechanism:     by value
    With ut_base_va, describes the unwind table (UT). ut_base_va
    is the process virtual address of the UT and must be quadword
    aligned. ut_size is the size of the UT in bytes and must be
    a multiple of the size (24 bytes: 3 quadwords) of an unwind
    table entry (UTE). The UTEs must describe nonoverlapping code
    sub regions within the overall code region.

 gp_value

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        read only
    mechanism:     by value
    Ignored on extension calls, required on create calls. The Global
    Data Pointer (GP) value for the routines described by these
    unwind tables.

 unwind_info_base

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        read only
    mechanism:     by value
    Ignored on extension calls; required on create calls. The unwind_
    info_base plus a particular UTE UIB offset must add up to the
    process virtual address of that UIB. Typically for static
    code (activated images from disk), this specifies the process
    virtual base address of the segment containing the UIBs. However,
    dynamically generated code, for example, can pass a zero for the
    unwind_info_base and have the full process virtual addresses of
    the UIBs in their UTEs.

 name

    OpenVMS usage: pseudo-image-name
    type:          character-code-text-string
    access:        read only
    mechanism:     by descriptor-fixed-length string descriptor
    Passed by descriptor (ignored on extension calls). May be used
    for traceback. Need not be unique. Should be less than 255
    characters (will be truncated, otherwise).

295  –  $SHOW INTRUSION

    Searches for and returns information about records in the
    intrusion database matching the caller's specifications.

    Format

      SYS$SHOW_INTRUSION  user_criteria ,intruder ,intruder_len

                          ,breakin_block ,[flags] ,[context]

    C Prototype

      int sys$show_intrusion  (void *user_criteria, void *intruder,

                              unsigned short int *intruder_len, void

                              *breakin_block, unsigned int flags,

                              unsigned int *context);

295.1  –  Arguments

 user_criteria

    OpenVMS usage:char_string or item_list_3
    type:         character-coded text string or longword (unsigned)
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor or by
                  reference
    If the CIA$M_ITEMLIST flag is FALSE:

    The user_criteria argument is the description of intruder
    or suspect. The user_criteria argument is the address of a
    character-string descriptor pointing to a buffer containing the
    user criteria to match an intrusion record's user specification
    in the intrusion database.

    The user_criteria argument is a character string of between 1 and
    1058 bytes containing characters to match the user specification
    on records in the intrusion database.

    A user specification is any combination of the suspect's or
    intruder's source node name, source user name, source DECnet
    for OpenVMS address, local failed user name, local terminal,
    or the string UNKNOWN. The user specification for an intrusion
    record is based on the input to the $SCAN_INTRUSION service and
    the settings of the LGI system parameter. For more information,
    see the VSI OpenVMS Guide to System Security.

    Wildcards are allowed for the user_criteria argument.

    For more information about using wildcards to scan the intrusion
    database, see the $SHOW_INTRUSION Description section in the VSI
    OpenVMS System Services Reference Manual.

    If the CIA$M_ITEMLIST flag is TRUE:

    The user_criteria argument is now the address of an 32-bit item
    list. If the item list is used, one item, the CIA$_USER_CRITERIAL
    item, must be present in the item list.

    The following table lists the valid item descriptions for the
    user_criteria argument:

    Item               Description

    CIA$_OUTPUT_LIST   Address of an 8192-byte buffer into which the
                       service writes the associated node information
                       for the returned intrusion record.
    CIA$_SCSNODE_LIST  Address of a list of 8-character null-padded
                       SCS nodenames for which the caller wants to
                       see intrusion information about.
    CIA$_USER_         Address of a buffer, 1-1058 bytes long,
    CRITERIAL          containing the intruder or suspect.

    If a CIA$_SCSNODE_LIST item is provided, an intrusion record will
    only be returned if it originated on one of the nodes specified.
    If a CIA$_SCSNODE_LIST item is not provided, records from all
    nodes will be candidates for display. Multiple CIA$_SCSNODE_LIST
    items are permitted in the item list.

    If a CIA$_OUTPUT_LIST item is provided, the item is filled with
    node-count records on return. The returned intrusion record will
    have a breakin block with a valid attempt-count field. The node-
    count records will have the name and attempt-count for each node
    represented.

 intruder

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    User specification of the matched intruder or suspect record in
    the intrusion database. The intruder argument is the address of
    a character-string descriptor pointing to a buffer to receive
    the user specification of the matched record in the intrusion
    database.

    The intruder argument is a 1058-byte string that will receive
    the user specification of a record in the intrusion database
    that matches the specifications in the user_criteria and flags
    arguments.

 intruder_len

    OpenVMS usage:string length
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Length of returned string in the intrusion buffer. The intruder_
    len argument is the address of a longword to receive the length
    of the returned intrusion buffer.

    The possible range of the intruder_len argument is 0 to 1058
    bytes. If the longword specified by the argument contains a 0
    after the call to the service, either the service did not find a
    record that matched the user criteria in the intrusion database,
    or there are no more matching items in the intrusion database.

 breakin_block

    OpenVMS usage:record
    type:         block of 2 longwords (unsigned) and
                  1 quadword (unsigned)
    access:       write only
    mechanism:    by reference
    Block to receive various information in the intrusion database
    about a record matching the user criteria.

    Refer to the VSI OpenVMS System Services Reference Manual to view
    the breakin_block argument diagram and descriptor fields table.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Type of records in the intrusion database about which information
    is to be returned. The flags argument is a longword bit mask
    wherein each bit corresponds to an option.

    Each option has a symbolic name. The $CIADEF macro defines the
    following valid names:

    Symbolic Name      Description

    CIA$M_ALL          All records will be shown. If the flags
                       argument is omitted, this value is assumed.

    CIA$M_INTRUDERS    Only intruder records matching the criteria
                       specified by the user_criteria argument will
                       be returned. The value of the flag field in
                       the break-in block will always be 1.

    CIA$M_ITEMLIST     If FALSE, the user_criteria argument is a
                       character string. If TRUE, this argument is a
                       32-bit item list.

    CIA$M_SUSPECTS     Only suspect records matching the criteria
                       specified by the user_criteria argument will
                       be returned. The value of the flag field in
                       the break-in block will always be 0.

    Each of these options is mutually exclusive.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Context information to keep between related calls to the $SHOW_
    INTRUSION service. The context argument is the address of a
    longword that receives a context from the service.

    The initial value contained in the unsigned longword pointed to
    by the context argument must be 0. The contents of the unsigned
    longword must not be changed after the service has set its value.
    If the contents of the context argument are changed between calls
    to the service, SS$_BADCONTEXT will be returned.

    Contexts become invalid after one-half hour of non-use. This
    means that if you call the $SHOW_INTRUSION service with a
    wildcard in the user_criteria argument and do not call the
    service to get the next matching record within one-half hour,
    the context becomes invalid. If the context has become invalid,
    you must restart your search of the intrusion database from the
    beginning by resetting the context to 0.

296  –  $SIGNAL ARRAY 64

    Returns the address of a 64-bit signal array. A 32-bit signal
    array and a mechanism array are passed to a condition handler
    when it is called. $SIGNAL_ARRAY_64 provides the address of the
    64-bit signal array, which might be required for programs that
    use 64-bit address space.

    This service accepts 64-bit addresses.

    Format

      SYS$SIGNAL_ARRAY_64  mcharg, sigarg_64

    C Prototype

      int sys$signal_array_64  (unsigned __int64 mcharg, unsigned

                               __int64 sigarg_64);

296.1  –  Arguments

 mcharg

    OpenVMS usage:mechanism array
    type:         vector quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference, array reference
    The mechanism array. The mcharg argument is the 32- or 64-bit
    address of this array, which was passed to the condition handler.
    $SIGNAL_ARRAY_64 uses this structure to determine the 64-bit
    signal array address.

 sigarg_64

    OpenVMS usage:64-bit signal array
    type:         vector quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference, array reference
    The 32- or 64-bit address of the 64-bit signal array is returned
    in this argument.

297  –  $SNDERR

    Writes a user-specified message to the system error log file,
    preceding it with the date and time.

    Format

      SYS$SNDERR  msgbuf

    C Prototype

      int sys$snderr  (void *msgbuf);

297.1  –  Argument

 msgbuf

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Message to be written to the error log file. The msgbuf argument
    is the address of a character string descriptor pointing to the
    message text.

298  –  $SNDJBC

    Creates, stops, and manages queues and the batch and print jobs
    in those queues. The $SNDJBC service completes asynchronously;
    to synchronize the completion of most operations, use the Send to
    Job Controller and Wait ($SNDJBCW) service.

    Format

      SYS$SNDJBC  [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr]

                  [,astprm]

    C Prototype

      int sys$sndjbc  (unsigned int efn, unsigned short int func,

                      unsigned int nullarg, void *itmlst, struct

                      _iosb *iosb, void (*astadr)(__unknown_params),

                      int astprm);

298.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when $SNDJBC completes. The
    efn argument is a longword containing this number; however,
    $SNDJBC uses only the low-order byte.

    When you queue the request, $SNDJBC clears the specified event
    flag (or event flag 0 if efn was not specified). Then, when the
    operation completes, $SNDJBC sets the specified event flag (or
    event flag 0).

 func

    OpenVMS usage:function_code
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Function code specifying the function that $SNDJBC is to perform.
    The func argument is a word containing this function code. The
    $SJCDEF macro defines the names of each function code.

    You can specify only one function code in a single call to
    $SNDJBC. Most function codes require or allow for additional
    information to be passed in the call. You pass this information
    by using the itmlst argument, which specifies a list of one or
    more item descriptors. Each item descriptor in turn specifies an
    item code, which modifies, restricts, or otherwise affects the
    action designated by the function code.

 nullarg

    OpenVMS usage:null_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Placeholding argument Reserved to VSI.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list supplying information to be used in performing 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 item descriptors, each of which specifies an item code. The
    item list is terminated by an item code of 0 or by a longword of
    0.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block into which $SNDJBC writes the completion status
    after the requested operation has completed. The iosb argument is
    the address of the I/O status block.

    At request initiation, $SNDJBC sets the value of the quadword
    I/O status block to 0. When the requested operation completes,
    $SNDJBC writes a condition value in the first longword of the
    I/O status block. It writes the value 0 into the second longword;
    this longword is unused and reserved for future use.

    The condition values returned by $SNDJBC in the I/O status
    block are usually condition values from the JBC facility. These
    condition values are defined by the $JBCMSGDEF macro. In some
    cases, the condition value returned by $SNDJBC can be an error
    return from a system service or an OpenVMS RMS service that
    is used in executing the request. For the SJC$_SYNCHRONIZE_JOB
    request, the condition value returned is the completion status of
    the requested job.

    The condition values returned from the JBC facility are listed in
    the Condition Values Returned in the I/O Status Block section.

    Though this 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 service to synchronize completion
       of the service, the I/O status block is a required argument
       for $SYNCH.

    o  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 $SNDJBC service. The
       condition value returned in R0 gives you information about the
       success or failure of the service call itself; the condition
       value returned in the I/O status block gives you information
       about the success or failure of the service operation.
       Therefore, to accurately assess the success or failure of the
       call to $SNDJBC, you must check the condition values returned
       in both R0 and the I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    AST service routine to be executed when $SNDJBC completes. The
    astadr argument is the address of this routine.

    If specified, the AST routine executes at the same access mode as
    the caller of $SNDJBC.

 astprm

    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 is this longword
    parameter.

299  –  $SNDJBCW

    The Send to Job Controller and Wait and $GETQUI services together
    provide the user interface to the Job Controller (JBC) facility.
    The $SNDJBCW service allows you to create, stop, and manage
    queues and the jobs in those queues. Queues can be generic,
    batch, execution, or output queues. Jobs can be batch or print
    jobs.

    The $SNDJBCW service queues a request to the job controller. For
    most operations, $SNDJBCW completes synchronously; that is, it
    returns to the caller after the operation completes; however, if
    the requested operation is a pause queue, stop queue, or abort
    job operation, $SNDJBCW returns to the caller after queuing
    the request. There is no way to synchronize completion of these
    operations. Also, $SNDJBCW does not wait for a job to complete
    before it returns to the caller. To synchronize completion of a
    job, the caller must specify the SJC$_SYNCHRONIZE_JOB function
    code.

    The $SNDJBCW service is identical to the Send to Job Controller
    ($SNDJBC) service except that $SNDJBC completes asynchronously;
    the $SNDJBC service returns to the caller immediately after
    queuing the request, without waiting for the operation to
    complete.

    The $SNDJBC and $SNDJBCW services supersede the Send Message to
    Symbiont Manager ($SNDSMB) and Send Message to Accounting Manager
    ($SNDACC) services. You should write new programs using $SNDJBC
    or $SNDJBCW, instead of $SNDSMB or $SNDACC. You should convert
    old programs using $SNDSMB or $SNDACC to use $SNDJBC or $SNDJBCW,
    as convenient.

    Format

      SYS$SNDJBCW  [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr]

                   [,astprm]

    C Prototype

      int sys$sndjbcw  (unsigned int efn, unsigned short int func,

                       unsigned int nullarg, void *itmlst, struct

                       _iosb *iosb, void (*astadr)(__unknown_params),

                       int astprm);

300  –  $SNDOPR

    Performs the following functions:

    o  Sends a user request to operator terminals

    o  Sends a user cancellation request to operator terminals

    o  Sends an operator reply to a user terminal

    o  Enables an operator terminal

    o  Displays the status of an operator terminal

    o  Initializes the operator log file

    Format

      SYS$SNDOPR  msgbuf ,[chan]

    C Prototype

      int sys$sndopr  (void *msgbuf, unsigned short int chan);

300.1  –  Arguments

 msgbuf

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    User buffer specifying the operation to be performed and the
    information needed to perform that operation. The msgbuf argument
    is the address of a character string descriptor pointing to the
    buffer.

    The format and contents of the buffer vary with the requested
    operation; however, the first byte in any buffer is the request
    code, which specifies the operation to be performed. The $OPCMSG
    macro defines the symbolic names for these request codes.

    The following table shows each operation that $SNDOPR performs
    and the request code that specifies that operation:

    Request Code   Corresponding Operation

    OPC$_RQ_       Sends a user cancellation request to specified
    CANCEL         operator terminals. You use this request code
                   to notify one or more operators that a previous
                   request is to be canceled. To specify OPC$_RQ_
                   CANCEL, you must also specify the chan argument.

    OPC$_RQ_LOGI   Initializes the operator log file.

    OPC$_RQ_       Sends an operator reply to a user who has made a
    REPLY          request. Operators use this request code to report
                   the status of a user request. The format of the
                   message buffer for this request is the format
                   of the reply found in the user's mailbox after
                   the call to $SNDOPR completes. All functions of
                   $SNDOPR that deliver a reply to a mailbox do so in
                   the format described for this request code.

    OPC$_RQ_RQST   Sends a user request to operator terminals. This
                   request code is used to make an operator request.
                   If you specify a reply to the request (by using
                   the chan argument), the operator request is kept
                   active until the operator responds.

    OPC$_RQ_       Reports the status of an operator terminal.
    STATUS         Operators use this request to display the operator
                   classes for which the specified terminal is
                   enabled and a list of outstanding requests.

    OPC$_RQ_       Enables an operator terminal. You use this request
    TERME          to enable a specified terminal to receive operator
                   messages.

    Refer to the VSI OpenVMS System Services Reference Manual to
    view the diagrams depicting the message buffer for each of these
    request codes.

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    Channel assigned to the mailbox to which the reply is to be sent.
    The chan argument is a longword value containing the number of
    the channel. If you do not specify chan or specify it as the
    value 0 (the default), no reply is sent.

    If a reply from the operator is desired, you must specify the
    chan argument.

301  –  $SPACE

    The Space service lets you space (skip) a tape file forward or
    backward a specified number of blocks.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

302  –  $START ALIGN FAULT REPORT (Alpha and Integrity servers)

    On Alpha and Integrity server systems, initializes user image
    alignment fault reporting.

    Format

      SYS$START_ALIGN_FAULT_REPORT  report_method ,report_buffer

                                    ,buffer_length

    C Prototype

      int sys$start_align_fault_report  (int report_method,

                                        void *report_buffer, int

                                        buffer_length);

302.1  –  Arguments

 report_method

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read
    mechanism:    by value
    Method by which image alignment faults are to be reported.

    The following table shows valid values for the report_method
    argument:

    Value          Meaning

    AFR$C_         Alignment fault PCs and fault addresses are saved
    BUFFERED       in a user-supplied buffer.
    AFR$C_         Alignment faults are elevated to user mode
    EXCEPTION      exceptions.

 report_buffer

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read
    mechanism:    by reference
    The 32-bit address of the buffer into which to write the fault
    data. The report_buffer argument is needed only if the value of
    the report_method argument is AFR$C_BUFFERED.

 buffer_length

    OpenVMS usage:byte count
    type:         longword (signed)
    access:       read
    mechanism:    by value
    Length of the buffer specified in the report_buffer argument.

    The buffer must have a minimum size of AFR$K_USER_LENGTH +
    32. However, a larger buffer allows for more information to be
    collected.

303  –  $START BRANCH

    Adds a new branch to a transaction.

    Format

      SYS$START_BRANCH  [efn] ,[flags] ,iosb ,[astadr] ,[astprm]

                        ,tid ,tm_name ,bid [,[timout], [acmode],

                        [tx_class]]

    C Prototype

      int sys$start_branch  (unsigned int efn, unsigned int

                            flags, struct _iosb *iosb, void

                            (*astadr)(__unknown_params), int astprm,

                            unsigned int tid [4], void *tm_name,

                            unsigned int bid [4],...);

303.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for these option
    flags, described in $START_BRANCH Option Flags. All undefined
    bits must be 0. If this argument is omitted, no flags are used.

    Table SYS-26 $START_BRANCH Option Flags

    Flag Name          Description

    DDTM$M_BRANCH_     Specifies that the new branch is
    UNSYNCHED          unsynchronized.

                       If this flag is clear, the new branch is
                       synchronized.
    DDTM$M_NONDEFAULT  Set this flag if you do not want the
                       transaction to be the default transaction
                       of the calling process. If this flag is
                       clear, the transaction becomes the default
                       transaction of the calling process.

                       An error is returned if this flag is clear
                       and the calling process has an current default
                       transaction.
    DDTM$M_SYNC        Specifies successful synchronous completion
                       by returning SS$_SYNCH. When SS$_SYNCH is
                       returned, the AST routine is not called, the
                       event flag is not set, and the I/O status
                       block is not filled in.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the completion status of the
    service is returned as a condition value.

    To view the I/O status block diagram, see the VSI OpenVMS System
    Services Reference Manual.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine executed when the service completes, if SS$_
    NORMAL is returned in R0. The astadr argument is the address
    of the entry mask of this routine. The routine is executed in
    the same access mode as that of the caller of the $START_BRANCH
    service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter passed to the AST routine specified by the
    astadr argument.

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (TID) of the transaction to which the new branch
    will be added.

 tm_name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    The name of the node on which the call was made to $ADD_BRANCH
    that authorized the new branch to be added to the transaction.
    Note that this cannot be a cluster alias.

    To ensure smooth operation in a mixed-network environment,
    refer to the chapter entitled Managing DECdtm Services in the
    VSI OpenVMS System Manager's Manual, for information on defining
    node names.

 bid

    OpenVMS usage:branch_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (BID) of the new branch that is to be added to the
    transaction.

    An BID value of zero is invalid.

 timout

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Reserved to VSI.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The access mode of the new branch in this process. This is the
    least privileged mode that a caller must be in to remove this
    branch from the transaction by calling $END_BRANCH. Note that it
    can be removed from the transaction by calling $ABORT_TRANS from
    any access mode.

    This argument only influences the access mode of the first branch
    in this process. Subsequent branches have the same access mode
    as the first. The access mode of the new branch is the least
    privileged of:

    o  The access mode of the caller.

    o  The access mode specified by the acmode argument.

    Note that if a branch already exists in this process, then
    neither the access mode of the caller nor the access mode
    specified by the acmode argument may be less privileged than
    that branch.

    The default value of this argument is the access mode of the
    caller.

 tx_class

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    A string that specifies the transaction class for the transaction
    on the local node if the transaction does not already have a
    transaction class on the local node. This string is passed in the
    event reports delivered to Resource Manager identifiers (RMIs)
    and Resource Manager (RM) participants on the local node.

    This argument is ignored if the transaction already has a
    transaction class on the local node.

    This string must be no longer than 31 characters.

304  –  $START BRANCHW

    Adds a new branch to a transaction.

    $START_BRANCHW always waits for the request to complete before
    returning to the caller. Other than this, it is identical to
    $START_BRANCH.

    Format

      SYS$START_BRANCHW  [efn] ,[flags] ,iosb ,[astadr] ,[astprm]

                         ,tid ,tm_name ,bid [,[timout] ,[acmode],

                         [tx_class]]

    C Prototype

      int sys$start_branchw  (unsigned int efn, unsigned int

                             flags, struct _iosb *iosb, void

                             (*astadr)(__unknown_params), int astprm,

                             unsigned int tid [4], void *tm_name,

                             unsigned int bid [4],...);

305  –  $START TRANS

    Starts a new transaction.

    Format

      SYS$START_TRANS  [efn] ,[flags] ,iosb [,[astadr] ,[astprm]

                       ,[tid] ,[timout] ,[acmode] ,[tx_class]]

    C Prototype

      int sys$start_trans  (unsigned int efn, unsigned int flags,

                           struct _iosb *iosb,...);

305.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the service. The flags argument is
    a longword bit mask in which each bit corresponds to an option
    flag. The $DDTMDEF macro defines symbolic names for these option
    flags, which are described in $START_TRANS Option Flags. All
    undefined bits must be 0. If this argument is omitted, no flags
    are used.

    Table SYS-27 $START_TRANS Option Flags

    Flag                Description

    DDTM$M_NONDEFAULT   Set this flag if you do not want the new
                        transaction to be the default transaction of
                        the calling process. An error is returned if
                        this flag is set and the tid argument is zero
                        or omitted.

                        If this flag is clear, the new transaction
                        becomes the default transaction of the
                        calling process. An error is returned if
                        this flag is clear and the calling process
                        already has a default transaction.

    DDTM$M_SYNC         Set this flag to specify that successful
                        synchronous completion is to be indicated
                        by returning SS$_SYNCH. When SS$_SYNCH is
                        returned, the AST routine is not called, the
                        event flag is not set, and the I/O status
                        block is not filled in.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block in which the completion status of the service is
    returned as a condition value.

    To view the I/O status block diagram, see the VSI OpenVMS System
    Services Reference Manual.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    AST routine that is executed when the service completes if SS$_
    NORMAL is returned in R0. The astadr argument is the address of
    this routine. This routine is executed in the same access mode of
    the caller of the $START_TRANS service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    AST parameter that is passed to the AST routine specified by the
    astadr argument.

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of an octaword in which the service returns the
    identifier (TID) of the new transaction.

    No other call to $START_TRANS on any node ever returns the same
    TID value.

    The default value of this argument is zero. An error is returned
    if the DDTM$M_NONDEFAULT flag is set and this argument is either
    omitted or zero.

 timout

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Timeout for the new transaction. This is the time at which the
    DECdtm transaction manager is to abort the transaction if the
    transaction has not already committed.

    A positive time value specifies an absolute time. The absolute
    value of a negative time specifies an offset (delta time) from
    the current time.

    The transaction is aborted at the next timer interval if you
    specify either a zero time value or any time in the past. If this
    argument is omitted, the new transaction has no timeout.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    An access mode of the new branch of the new transaction.

    An access mode is maintained for each transaction per process.
    All branches in a transaction in a process have the same access
    mode. Subsequent operations do not alter it. The access mode of a
    branch is the least privileged mode in which a successful call to
    $END_TRANS may be made.

    Note that the transaction may be aborted by a call to $ABORT_
    TRANS from any access mode.

    The access mode of the branch is the least privileged of the
    following:

    o  The access mode of the caller

    o  The access mode specified by the acmode argument

    If the acmode argument is omitted, the access mode of the new
    branch is the same as that of the caller.

 tx_class

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    A string that specifies the transaction class for the new
    transaction on the local node. This string is passed in the event
    reports delivered to RMIs and RM participants on the local node.

    This string must be no longer than 31 characters. If this
    argument is omitted or the string is of length zero, the new
    transaction has no transaction class on the local node. In this
    case, the class of the transaction on the local node can be
    specified by a subsequent call to $START_BRANCH on that node.

306  –  $START TRANSW

    Starts a new transaction.

    $START_TRANSW always waits for the request to complete before
    returning to the caller. Other than this, it is identical to
    $START_TRANS.

307  –  $STOP ALIGN FAULT REPORT (Alpha and Integrity servers)

    On Alpha and Integrity server systems, disables user image
    alignment fault reporting.

    Format

      SYS$STOP_ALIGN_FAULT_REPORT

    C Prototype

      int sys$stop_align_fault_report  (void);

307.1  –  Arguments

    None.

308  –  $STOP SYS ALIGN FAULT REPORT (Alpha and Integrity servers)

    On Alpha and Integrity server systems, disables systemwide
    alignment fault reporting.

    Format

      SYS$STOP_SYS_ALIGN_FAULT_REPORT

    C Prototype

      int sys$stop_sys_align_fault_report  (void);

308.1  –  Arguments

    None.

309  –  $SUBSYSTEM

    Saves or restores the process image rights for the current
    protected subsystem.

    Format

      SYS$SUBSYSTEM  enbflg

    C Prototype

      int sys$subsystem  (unsigned int enbflg);

309.1  –  Argument

 enbflg

    OpenVMS usage:boolean
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Value specifying whether the protected subsystem identifiers are
    to be saved or restored. If the enbflg argument is set to 0, the
    active subsystem is saved. If it is set to 1, the subsystem is
    restored.

310  –  $SUSPND

    Allows a process to suspend itself or another process.

    Format

      SYS$SUSPND  [pidadr] ,[prcnam] ,[flags]

    C Prototype

      int sys$suspnd  (unsigned int *pidadr, void *prcnam, unsigned

                      int flags);

310.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Process identification (PID) of the process to be suspended. The
    pidadr argument is the address of the longword PID.

    The pidadr argument can refer to a process running on the local
    node or a process running on another node in the OpenVMS Cluster
    system.

    You must specify the pidadr argument to suspend a process whose
    UIC group number is different from that of the calling process.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Name of the process to be suspended. The prcnam argument is the
    address of a character string descriptor pointing to the process
    name. A process running on the local node can be identified with
    a 1- to 15-character string.

    To identify a process on a particular node on a cluster, specify
    the full process name, which includes the node name as well as
    the process name. The full process name can contain up to 23
    characters.

    A process name is implicitly qualified by its UIC group number.
    Because of this, you can use the prcnam argument only to suspend
    processes in the same UIC group as the calling process.

    To suspend processes in other groups, you must specify the pidadr
    argument.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Longword of bit flags specifying options for the suspend
    operation. Currently, only bit 0 is used for the flags argument.
    When bit 0 is set, the process is suspended at kernel mode and
    ASTs are not deliverable to the process.

    To request a kernel mode suspend, the caller must be in either
    kernel mode or executive mode. The default (bit 0 is clear) is
    to suspend the process at supervisor mode, where executive or
    kernel mode ASTs can be delivered to the process. If executive
    or kernel mode ASTs have been delivered to a process suspended at
    supervisor mode, that process will return to its suspended state
    after the AST routine executes.

311  –  $SYNCH

    Checks the completion status of a system service that completes
    asynchronously.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$SYNCH  [efn] ,[iosb]

    C Prototype

      int sys$synch  (unsigned int efn, struct _iosb *iosb);

311.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag specified in the call to the system
    service whose completion status is to be checked by $SYNCH.
    The efn argument is a longword containing this number; however,
    $SYNCH uses only the low-order byte.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    I/O status block specified in the call to the system service
    whose completion status is to be checked by $SYNCH. The iosb
    argument is the address of this quadword I/O status block.

312  –  $TIMCON

    Converts 128-bit Coordinated Universal Time (UTC) format to 64-
    bit system format or 64-bit system format to 128-bit UTC format
    based on the value of the convert flag.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$TIMCON  [smnadr] ,[utcadr] ,cvtflg

    C Prototype

      int sys$timcon  (struct _generic_64 *smnadr, unsigned int

                      *utcadr [4], unsigned long int cvtflg);

312.1  –  Arguments

 smnadr

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read/write
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    The 64-bit system format value that $TIMCON will use in the
    conversion. The smnadr argument will be read from or written to
    based on the value of the cvtflg argument. The smnadr is required
    when converting UTC time to 64-bit system format.

 utcadr

    OpenVMS usage:coordinated universal time
    type:         utc_date_time
    access:       read/write
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    UTC time value that $TIMCON will use in the conversion. The
    utcadr argument will be read from or written to based on the
    value of the cvtflg argument. The utcadr argument is required
    when converting 64-bit system format to UTC time.

 cvtflg

    OpenVMS usage:conversion flag
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    A longword indicating the direction of the conversion. If the
    cvtflg value is 0, UTC time is converted to 64-bit system value.
    If the cvtflg value is 1, 64-bit system format is converted to
    UTC time.

313  –  $TRANS EVENT

    Forces a transaction state change for a transaction in which
    there is at least one RM participant that has set the DDTM$M_
    COORDINATOR flag.

    Format

      SYS$TRANS_EVENT  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid

                       ,rm_id ,tx_event

    C Prototype

      int sys$trans_event  (unsigned int efn, unsigned int

                           flags, struct _iosb *iosb, void

                           (*astadr)(__unknown_params), int astprm,

                           unsigned int tid [4], unsigned int rm_id,

                           unsigned int tx_event);

313.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Reserved to VSI. This argument must be zero.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the completion status of the
    service is returned as a condition value.

    The outcome of the state change is indicated by the contents of
    the I/O status block.

    To view the I/O status block diagram, see the VSI OpenVMS System
    Services Reference Manual.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine that is executed when the service completes, if
    SS$_NORMAL is returned in R0. The astadr argument is the address
    of the entry mask of this routine. The routine is executed in
    the same access mode as that of the caller of the $TRANS_EVENT
    service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter passed to the AST routine specified by the
    astadr argument.

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (TID) of transaction to which the state change is
    to be applied.

 rm_id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The identifier of the Resource Manager identifier (RMI) with
    which the coordinating Resource Manager (RM) participant is
    associated.

 tx_event

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The operation to be performed on the transaction. For a list of
    the permitted values and the possible successful outcomes, see
    the VSI OpenVMS System Services Reference Manual.

314  –  $TRANS EVENTW

    Forces a transaction state change for a transaction in which
    there is at least one RM participant that has specified the
    DDTM$M_COORDINATOR flag.

    $TRANS_EVENTW always waits for the request to complete before
    returning to the caller. Other than this, it is identical to
    $TRANS_EVENT.

    Format

      SYS$TRANS_EVENTW  [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid

                        ,rm_id ,tx_event

    C Prototype

      int sys$trans_eventw  (unsigned int efn, unsigned int

                            flags, struct _iosb *iosb, void

                            (*astadr)(__unknown_params), __int64

                            astprm, )

315  –  $TRNLNM

    Returns information about a logical name.

    On Alpha and Integrity server systems, this service accepts 64-
    bit addresses.

    Format

      SYS$TRNLNM  [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]

    C Prototype

      int sys$trnlnm  (unsigned int *attr, void *tabnam, void

                      *lognam, unsigned char *acmode, void *itmlst);

315.1  –  Arguments

 attr

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Attributes controlling the search for the logical name. The
    attr argument is the 32- or 64-bit address (on Alpha and
    Integrity server systems) of a longword bit mask specifying these
    attributes.

    Each bit in the longword corresponds to an attribute and has a
    symbolic name. The $LNMDEF macro defines these symbolic names.
    To specify an attribute, use its symbolic name or set its
    corresponding bit. All undefined bits in the longword have the
    value 0.

    If you do not specify this argument or specify it as the value 0
    (no bits set), the following attributes are not used:

    Attribute        Description

    LNM$M_CASE_      If set, $TRNLNM does not distinguish between
    BLIND            uppercase and lowercase letters in the logical
                     name to be translated.
    LNM$M_           If set, $TRNLNM does not translate the current
    INTERLOCKED      logical name until any clusterwide logical
                     name modifications in progress are completed.
                     This attribute is not set by default. If
                     your application requires translation using
                     the most recent definition of a clusterwide
                     logical name, use this attribute to ensure that
                     the translation is stalled until all pending
                     modifications have been made.

 tabnam

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor (Alpha and Integrity servers)
    Name of the logical name table or the name of a searchlist
    logical name that translates the name of one or more tables
    in which to search for the specified logical name. The tabnam
    argument is the 32- or 64-bit address (on Alpha and Integrity
    server systems) of a descriptor pointing to this name. This
    argument is required.

    The name must be entered in uppercase letters. (This requirement
    differs from the $CRELNT system service, which automatically
    changes tabnam to uppercase.)

    If the table name is not the name of a logical name table, it is
    assumed to be a logical name and is translated iteratively until
    either the name of a logical name table is found or the number
    of translations allowed by the system have been performed. If
    the table name translates to a list of logical name tables, the
    tables are searched in the specified order.

 lognam

    OpenVMS usage:logical_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor (Alpha and Integrity servers)
    Logical name about which information is to be returned. The
    lognam argument is the 32- or 64-bit address (on Alpha and
    Integrity server systems) of a descriptor pointing to the logical
    name string. This argument is required.

 acmode

    OpenVMS usage:access_mode
    type:         byte (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference (Alpha and Integrity
                  servers)
    Access mode to be used in the translation. The acmode argument is
    the 32- or 64-bit address (on Alpha and Integrity server systems)
    of a byte specifying the access mode. The $PSLDEF macro defines
    symbolic names for the four access modes.

    When you specify the acmode argument, $TRNLNM ignores all
    names (both logical names and table names) at access modes less
    privileged than the specified access mode. The specified access
    mode is not checked against that of the caller.

    If you do not specify acmode, $TRNLNM performs the translation
    without regard to access mode; however, the translation process
    proceeds from the outermost to the innermost access modes. Thus,
    if two logical names with the same name but at different access
    modes exist in the same table, $TRNLNM translates the name with
    the outermost access mode.

 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 (Alpha and Integrity
                  servers)
    Item list describing the information that $TRNLNM is to return.
    The itmlst argument is the 32- or 64-bit address (on Alpha
    and Integrity server systems) of a list of item descriptors,
    each of which specifies or controls an item of information to
    be returned. An item list in 32-bit format is terminated by a
    longword of 0; an item list in 64-bit format is terminated by
    a quadword of 0. All items in an item list must be of the same
    format-either 32-bit or 64-bit.

    To view the item code diagrams and descriptor fields tables, see
    the VSI OpenVMS System Services Reference Manual.

316  –  $TRUNCATE

    The Truncate service shortens a sequential file.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

317  –  $TSTCLUEVT

    Simulates the occurrence of a cluster configuration event to test
    the functionality of the notification AST.

    Format

      SYS$TSTCLUEVT  [handle] ,[acmode] ,[event]

    C Prototype

      int sys$tstcluevt  (unsigned int *handle, unsigned int acmode,

                         unsigned int event);

317.1  –  Arguments

 handle

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Identification of the asynchronous system trap (AST) to be
    tested. The handle argument uniquely identifies the request and
    is returned when the $SETCLUEVT service is called.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode for which a configuration event AST is to be
    triggered. The acmode argument is a longword containing the
    access mode.

    Each access mode has a symbolic name. The $PSLDEF macro defines
    the following symbols for the four access modes:

    Symbol         Access Mode

    PSL$C_KERNEL   Kernel
    PSL$C_EXEC     Executive
    PSL$C_SUPER    Supervisor
    PSL$C_USER     User

 event

    OpenVMS usage:event_code
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Event code indicating the type of configuration for which an AST
    is to be triggered.

    Each event type has a symbolic name. The $CLUEVTDEF macro defines
    the following symbolic names:

    Symbolic Name      Description

    CLUEVT$C_ADD       One or more OpenVMS nodes have been added to
                       the OpenVMS Cluster system.
    CLUEVT$C_REMOVE    One or more OpenVMS nodes have been removed
                       from the OpenVMS Cluster system.

318  –  $ULKPAG

    Unlocks pages that were previously locked in memory by the Lock
    Pages in Memory ($LCKPAG) service. Locked pages are automatically
    unlocked and deleted at image exit.

    Format

      SYS$ULKPAG  inadr ,[retadr] ,[acmode]

    C Prototype

      int sys$ulkpag  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode);

318.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Starting and ending virtual addresses of the pages to be
    unlocked. The inadr argument is the address of a 2-longword array
    containing, in order, the starting and ending process virtual
    addresses.

    Only the virtual page number portion of each virtual address is
    used; the low-order byte-within-page bits are ignored. If the
    starting and ending virtual addresses are the same, a single page
    is unlocked.

    If more than one page is being unlocked and you need to determine
    specifically which pages had been previously unlocked, you should
    unlock the pages one at a time, that is, one page per call
    to $ULKPAG. The condition value returned by $ULKPAG indicates
    whether the page was previously unlocked.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference-array reference or descriptor
    Starting and ending process virtual addresses of the pages
    actually unlocked by $ULKPAG. The retadr argument is the address
    of a 2-longword array containing, in order, the starting and
    ending process virtual addresses.

    If an error occurs while multiple pages are being unlocked,
    retadr specifies those pages that were successfully unlocked
    before the error occurred. If no pages were successfully
    unlocked, both longwords in the retadr array contain the value
    -1.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode on behalf of which the request is being made. The
    acmode argument is a longword containing the access mode. The
    $PSLDEF macro defines the symbols for the four access modes.

    The most privileged access mode used is the access mode of the
    caller. To unlock any specified page, the resultant access mode
    must be equal to or more privileged than the access mode of the
    owner of that page.

319  –  $ULKPAG 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, unlocks pages that were
    previously locked in memory by the Lock Pages in Memory ($LCKPAG_
    64) service.

    This service accepts 64-bit addresses.

    Format

      SYS$ULKPAG_64  start_va_64 ,length_64 ,acmode ,return_va_64

                     ,return_length_64

    C Prototype

      int sys$ulkpag_64  (void *start_va_64, unsigned __int64

                         length_64, unsigned int acmode, void

                         *(*(return_va_64)), unsigned __int64

                         *return_length_64);

319.1  –  Arguments

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address of the pages to be unlocked. The
    specified virtual address will be rounded down to a CPU-specific
    page boundary.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space to be unlocked. The specified
    length will be rounded up to a CPU-specific page boundary so that
    it includes all CPU-specific pages in the requested range.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode on behalf of which the request is being made. The
    acmode argument is a longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. To unlock any specified page, the resultant access mode
    must be equal to or more privileged than the access mode of the
    owner of that page.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of the unlocked virtual
    address range. The return_va_64 argument is the 32- or 64-bit
    virtual address of a naturally aligned quadword into which the
    service returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the virtual address range unlocked. The
    return_length_64 argument is the 32- or 64-bit virtual address
    of a naturally aligned quadword into which the service returns
    the length of the virtual address range in bytes.

320  –  $ULWSET

    Unlocks pages that were previously locked in the working set by
    the Lock Pages in Working Set ($LKWSET) service.

    Format

      SYS$ULWSET  inadr ,[retadr] ,[acmode]

    C Prototype

      int sys$ulwset  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode);

320.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference-array reference or descriptor
    Starting and ending virtual addresses of the pages to be
    unlocked. The inadr argument is the address of a 2-longword array
    containing, in order, the starting and ending process virtual
    addresses.

    Only the virtual page number portion of each virtual address is
    used; the low-order byte-within-page bits are ignored. If the
    starting and ending virtual address are the same, a single page
    is unlocked.

    If more than one page is being unlocked and you need to determine
    specifically which pages had been previously unlocked, you should
    unlock the pages one at a time, that is, one page per call
    to $ULWSET. The condition value returned by $ULWSET indicates
    whether the page was previously unlocked.

    On Alpha and Integrity server systems, if the first address in
    the 2-longword array is within an image mapped to your process,
    the entire image specified by the address is unlocked from the
    working set.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference-array reference or descriptor
    Starting and ending process virtual addresses of the pages that
    were actually unlocked by $CRMPSC. The retadr argument is the
    address of a 2-longword array containing, in order, the starting
    and ending process virtual addresses.

    If an error occurs while multiple pages are being unlocked,
    retadr specifies those pages that were successfully unlocked
    before the error occurred. If no pages were successfully
    unlocked, both longwords in the retadr array contain the value
    -1.

    On Alpha and Integrity server systems, if the inadr argument
    specifies an address within an image mapped to your process,
    retadr specifies only one range of pages unlocked from the
    working set. Many ranges of pages might be unlocked.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode on behalf of which the request is being made. The
    acmode argument is a longword containing the access mode. The
    $PSLDEF macro defines the symbols for the four access modes.

    The most privileged access mode used is the access mode of the
    caller. To unlock any specified page, the resultant access mode
    must be equal to or more privileged than the access mode of the
    owner of that page.

321  –  $ULWSET 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, unlocks a virtual address
    range that was previously locked in the working set by the Lock
    Pages in Working Set ($LKWSET_64) service.

    This service accepts 64-bit addresses.

    Format

      SYS$ULWSET_64  start_va_64 ,length_64 ,acmode ,return_va_64

                     ,return_length_64

    C Prototype

      int sys$ulwset_64  (void *start_va_64, unsigned __int64

                         length_64, unsigned int acmode, void

                         *(*(return_va_64)), unsigned __int64

                         *return_length_64);

321.1  –  Arguments

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address of the pages to be unlocked from the
    working set. The specified virtual address will be rounded down
    to a CPU-specific page boundary.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address space to be unlocked from the
    working set. The specified length will be rounded up to a CPU-
    specific page boundary so that it includes all CPU-specific pages
    in the requested range.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode on behalf of which the request is being made. The
    acmode argument is a longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. To unlock any specified page, the resultant access mode
    must be equal to or more privileged than the access mode of the
    owner of that page.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The lowest process virtual address of the unlocked virtual
    address range. The return_va_64 argument is the 32- or 64-bit
    virtual address of a naturally aligned quadword into which the
    service returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the virtual address range unlocked. The
    return_length_64 argument is the 32- or 64-bit virtual address
    of a naturally aligned quadword into which the service returns
    the length of the virtual address range in bytes.

322  –  $UNWIND

    Unwinds the procedure call stack.

    Format

      SYS$UNWIND  [depadr] ,[newpc]

    C Prototype

      int sys$unwind  (unsigned int *depadr, void *newpc);

322.1  –  Arguments

 depadr

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Depth to which the procedure call stack is to be unwound. The
    depadr argument is the address of a longword value. The value 0
    specifies the call frame of the procedure that was executing when
    the condition occurred (that is, no call frames are unwound); the
    value 1 specifies the caller of that frame; the value 2 specifies
    the caller of the caller of that frame, and so on.

    If depadr specifies the value 0, no unwind occurs and $UNWIND
    returns a successful condition value in R0.

    If you do not specify depadr (or with some languages you specify
    an address of 0), $UNWIND unwinds the stack to the call frame
    of the procedure that called the procedure that established the
    condition handler that is calling the $UNWIND service. This is
    the default and the normal method of unwinding the procedure call
    stack.

 newpc

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    New value for the program counter (PC); this value replaces the
    current value of the PC in the call frame of the procedure that
    receives control when the unwinding operation is complete. The
    newpc argument is a longword value containing the address at
    which execution is to resume.

    Execution resumes at this address when the unwinding operation is
    complete.

    If you do not specify newpc, execution resumes at the location
    specified by the PC in the call frame of the procedure that
    receives control when the unwinding operation is complete.

323  –  $UPDSEC

    Writes all modified pages in an active private or global section
    back into the section file on disk. One or more I/O requests are
    queued, based on the number of pages that have been modified.

    Format

      SYS$UPDSEC  inadr ,[retadr] ,[acmode] ,[updflg] ,[efn] ,[iosb]

                  ,[astadr] ,[astprm]

    C Prototype

      int sys$updsec  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode, char updflg,

                      unsigned int efn, struct _iosb *iosb, void

                      (*astadr)(__unknown_params), int astprm);

323.1  –  Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference-array reference or descriptor
    Starting and ending virtual addresses of the pages that are to
    be written to the section file if they have been modified. The
    inadr argument is the address of a 2-longword array containing,
    in order, the starting and ending process virtual addresses.
    Addresses are adjusted up or down to CPU-specific pages.

    Only the virtual page number portion of each virtual address is
    used; the low-order byte-within-page bits are ignored.

    $UPDSEC scans pages starting at the address contained in the
    first longword specified by inadr and ending at the address
    contained in the second longword. Within this range, $UPDSEC
    locates read/write pages that have been modified and writes
    them (contiguously, if possible) to the section file on disk.
    Unmodified pages are also written to disk if they share the same
    cluster with modified pages.

    If the starting and ending virtual addresses are the same, a
    single page is written to the section file if the page has been
    modified.

    The address specified by the second longword might be smaller
    than the address specified by the first longword.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference-array reference or descriptor
    Addresses of the first and last pages that were actually queued
    for writing, in the first $QIO request, back to the section file
    on disk. The retadr argument is the address of a 2-longword array
    containing, in order, the addresses of the first and last pages.
    Addresses always are adjusted up or down to fall on CPU-specific
    boundaries.

    If $UPDSEC returns an error condition value in R0, each longword
    specified by retadr contains the value -1. In this case, an event
    flag is not set, no asynchonous system trap (AST) is delivered,
    and the I/O status block is not written to.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode on behalf of which the service is performed. The
    acmode argument is a longword containing the access mode. The
    $PSLDEF macro defines the symbols for the four access modes.

    The most privileged access mode used is the access mode of the
    caller. A page cannot be written to disk unless the access mode
    used by $UPDSEC is equal to or more privileged than the access
    mode of the owner of the page to be written.

 updflg

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Update specifier for read/write global sections. The updflg
    argument is a longword value. The value 0 (the default) specifies
    that all read/write pages in the global section are to be written
    to the section file on disk, whether or not they have been
    modified. The value 1 specifies that the caller is the only
    or the last process having the global section mapped for write
    access and that only modified pages should be written to the
    section file on disk.

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Event flag to be set when the section file on disk is actually
    updated. The efn argument is a longword specifying the number of
    the event flag; however, $UPDSEC uses only the low-order byte.

    If you do not specify efn, event flag 0 is used.

    When you invoke $UPDSEC, the specified event flag or event flag 0
    is cleared; when the update operation is complete, the event flag
    is set.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block to receive the final completion status of the
    updating operation. The iosb argument is the address of the
    quadword I/O status block.

    When you invoke $UPDSEC, the I/O status block is cleared. After
    the update operation is complete, that is, when all I/O to the
    disk is complete, the I/O status block is written as follows:

    o  The first word contains the condition value returned by $QIO,
       indicating the final completion status.

    o  The first bit in the second word is set only if an error
       occurred during the I/O operation and the error was a hardware
       write error. The remaining bits of the second word are zeros.

    o  The second longword contains the virtual address of the first
       page that was not written.

    Though this 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 $SYNCH to synchronize completion of the
       service, the I/O status block is a required argument for
       $SYNCH.

    o  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 $UPDSEC. The condition
       value returned in R0 gives you information about the success
       or failure of the service call itself; the condition value
       returned in the I/O status block gives you information about
       the success or failure of the service operation. Therefore,
       to accurately assess the success or failure of the call to
       $UPDSEC, you must check the condition values returned in both
       R0 and the I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference-procedure reference or descriptor
    AST routine to be executed when the section file has been
    updated. The astadr argument is the address of this routine.

    If you specify astadr, the AST routine executes at the access
    mode from which the section file update was requested.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    AST parameter to be passed to the AST routine. The astprm
    argument is this longword parameter.

324  –  $UPDSECW

    Writes all modified pages in an active private or global section
    back into the section file on disk. One or more I/O requests are
    queued, based on the number of pages that have been modified.

    The $UPDSECW service completes synchronously; that is, it returns
    to the caller after writing all updated pages.

    For asynchronous completion, use the Update Section File on Disk
    ($UPDSEC) service; $UPDSEC returns to the caller after queuing
    the update request, without waiting for the pages to be updated.

    In all other respects, $UPDSECW is identical to $UPDSEC. For
    additional information about the $UPDSECW service, see the
    description of $UPDSEC.

    Format

      SYS$UPDSECW  inadr [,retadr] [,acmode] [,updflg] [,efn] [,iosb]

                   [,astadr] [,astprm]

    C Prototype

      int sys$updsecw  (struct _va_range *inadr, struct _va_range

                       *retadr, unsigned int acmode, char updflg,

                       unsigned int efn, struct _iosb *iosb, void

                       (*astadr)(__unknown_params), int astprm);

325  –  $UPDSEC 64 (Alpha and Integrity servers)

    On Alpha and Integrity server systems, writes all pages (or
    only those pages modified by the current process) in an active
    private or global disk file section back into the section file
    on disk. One or more I/O requests are queued to perform the write
    operation.

    The $UPDSEC_64 service completes asynchronously. For synchronous
    completion, use the Update Global Section File on Disk and Wait
    ($UPDSEC_64W) service.

    This service accepts 64-bit addresses.

    Format

      SYS$UPDSEC_64  start_va_64 ,length_64 ,acmode ,updflg ,efn

                     ,iosa_64 ,return_va_64 ,return_length_64

                     [,astadr_64 [,astprm_64]]

    C Prototype

      int sys$updsec_64  (void *start_va_64, unsigned __int64

                         length_64, unsigned int acmode, unsigned

                         int updflg, unsigned int efn, struct _iosa

                         *iosa_64, void *(*(return_va_64)), unsigned

                         __int64 *return_length_64,...);

325.1  –  Arguments

 start_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       read only
    mechanism:    by value
    The starting virtual address of the pages to be written to the
    section file. The specified virtual address is rounded down to a
    CPU-specific page boundary.

 length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by value
    Length of the virtual address range to be written to the section
    file. The length specified is rounded up to a CPU-specific
    page boundary so that it includes all CPU-specific pages in the
    requested range.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode on behalf of which the service is performed. The
    acmode argument is a longword containing the access mode.

    The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
    SYS$STARLET_C.TLB define the following symbols and their values
    for the four access modes:

    Value      Symbolic Name      Access Mode

    0          PSL$C_KERNEL       Kernel
    1          PSL$C_EXEC         Executive
    2          PSL$C_SUPER        Supervisor
    3          PSL$C_USER         User

    The most privileged access mode used is the access mode of the
    caller. A page cannot be written to disk unless the access mode
    used by $UPDSEC_64 is equal to or more privileged than the access
    mode of the owner of the page to be written.

 updflg

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The update specifier for read/write global sections. The updflg
    argument is a longword value. The value 0 (the default) specifies
    that all read/write pages in the global section are to be written
    to the section file on disk, whether or not they have been
    modified. The value UPDFLG$M_WRT_MODIFIED specifies that the
    caller is the only process actually writing the global section
    and that only those pages that were actually modified by the
    caller are to be written to the section file on disk.

    Definitions for this flag can be found in the file SECDEF.H in
    SYS$STARLET_C.TLB for C and in $SECDEF in STARLET.MLB for macro.

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read_only
    mechanism:    by value
    The event flag to be set when the section file on disk is
    actually updated. The efn argument is a longword specifying the
    number of the event flag; however, this service only uses the
    low-order byte. If you do not specify the efn, event flag 0 is
    used.

    When you invoke $UPDSEC_64, the specified event flag or event
    flag 0 is cleared. When the update operation is complete, the
    event flag is set.

 iosa_64

    OpenVMS usage:io_status_area
    type:         IOSA structure
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The I/O status area to receive the final completion status of
    the updating operation. The iosa_64 argument is the 32- or 64-
    bit virtual address of the I/O status area. The I/O status area
    structure is 32 bytes in length.

    The I/O status area structure definition can be found in
    $IOSADEF in STARLET.MLB for macro and in the file IOSADEF.H in
    SYS$STARLET_C.TLB for C.

    When you call SYS$UPDSEC_64, the I/O status area is cleared.
    After the update operation is complete (that is, when all I/O
    to the disk is complete), the I/O status block is written as
    follows:

    o  isoa$l_status (offset 0)

       The first word contains the condition value return by SYS$QIO,
       indicating the final completion status.

       The first bit in the second word is set only if an error
       occurred during the I/O operation and the error was a hardware
       write error. The remaining bits of the second word are zeros.

    o  iosa$l_resd (offset 4)

       This field is reserved for future use by VSI. The value in this
       field is unpredictable.

    o  iosa$q_count_q (offset 8)

       This field is reserved for future use by VSI. The value in this
       field is unpredictable.

    o  iosa$ph_upsec_nowrt_va (offset 16)

       This field contains the virtual address of the first byte in
       the first disk block that was not written. In the case of an
       I/O error, this virtual address indicates the disk block for
       which the error occurred.

    o  iosa$q_resq (offset 24)

       This field is reserved for future use by VSI. The value in this
       field is unpredictable.

 return_va_64

    OpenVMS usage:address
    type:         quadword address
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The process virtual address of the first page that was actually
    queued for writing (in the first I/O request) back to the section
    file on the disk. The return_va_64 argument is the 32- or 64-bit
    virtual address of a naturally aligned quadword into which the
    service returns the virtual address.

 return_length_64

    OpenVMS usage:byte count
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference
    The length of the first I/O request to write modified pages back
    to the section file on disk. The return_length_64 argument is
    the 32- or 64-bit virtual address of a naturally aligned quadword
    into which the service returns the length of the virtual address
    range, in bytes, written by the first I/O request.

 astadr_64

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference
    The asynchronous system trap (AST) routine to be executed when
    the section file has been updated. The astadr_64 argument is
    the 32- or 64-bit address of this routine. If you specify the
    astadr_64 argument, the AST routine executes at the access mode
    from which the section file update was requested.

 astprm_64

    OpenVMS usage:user_arg
    type:         quadword
    access:       read only
    mechanism:    by value
    The AST parameter to be passed to the AST routine. The astprm_64
    argument is a quadword argument that is passed to the AST
    routine.

326  –  $UPDSEC 64W (Alpha and Integrity servers)

    On Alpha and Integrity server systems, writes all modified pages
    in an active private or global disk file section back into the
    section file on disk. Zero or more I/O requests are queued, based
    on the number of pages that have been modified.

    The $UPDSEC_64W service completes synchronously; that is, it
    returns to the caller after writing all updated pages.

    In all other respects, $UPDSEC_64W is identical to $UPDSEC_64.
    For additional information about the $UPDSEC_64W service, see the
    help for $UPDSEC_64.

    This service accepts 64-bit addresses.

    Format

      SYS$UPDSEC_64W  start_va_64 ,length_64 ,acmode ,updflg ,efn

                      ,iosa_64 ,return_va_64 ,return_length_64

                      [,astadr_64 [,astprm_64]]

    C Prototype

      int sys$updsec_64w  (void *start_va_64, unsigned __int64

                          length_64, unsigned int acmode, unsigned

                          int updflg, unsigned int efn, struct _iosa

                          *iosa_64, void *(*(return_va_64)), unsigned

                          __int64 *return_length_64,...);

327  –  $VERIFY PROXY

    Verifies that a proxy exists and returns a valid local user for
    the caller to use to create a local login.

    Format

      SYS$VERIFY_PROXY  rem_node ,rem_user ,[proposed_user]

                        ,local_user ,local_user_length ,[flags]

    C Prototype

      int sys$verify_proxy  (void *rem_node, void *rem_user, void

                            *proposed_user, void *local_user,

                            unsigned short int *local_user_len,

                            unsigned int flags);

327.1  –  Arguments

 rem_node

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Remote node name of the proxy to be verified. The rem_node
    argument is the address of a character-string descriptor pointing
    to the remote node name string.

    A remote node name consists of 1 to 1024 characters. No specific
    characters, format, or case are required for a remote node name
    string. All node names are converted to their DECnet for OpenVMS
    full name unless the PRX$M_BYPASS_EXPAND flag is set with the
    flags argument.

    Wildcards are not recognized. If you specify a wildcard character
    in the rem_node argument, it is ignored and assumed to be part of
    the requested node name.

 rem_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Remote user name of the proxy to be verified. The rem_user
    argument is the address of a character-string descriptor pointing
    to the user name string.

    A remote user name consists of 1 to 32 alphanumeric characters,
    including dollar signs ($),  underscores (_), and brackets
    ([ ]).  Any lowercase characters specified are automatically
    converted to uppercase.

    The rem_user argument can be specified in user identification
    code (UIC) format ([group, member]).  Brackets are allowed only
    if the remote user name string specifies a UIC. Group and member
    are character-string representations of octal numbers with no
    leading zeros.

    Wildcards are not allowed for the remote user specification. If
    wildcard characters are present in the string specified by the
    rem_user argument, the service returns SS$_BADPARAM.

 proposed_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Local user the caller suggests be used for the proxy login.
    The proposed_user argument is the address of a character-string
    descriptor pointing to the proposed local user name.

    The proposed local user consists of 1 to 32 alphanumeric
    characters, including dollar signs ($)  and underscores (_).
    Any lowercase characters specified are automatically converted to
    uppercase.

    See the $VERIFY_PROXY Description section in the VSI OpenVMS
    System Services Reference Manual for information about the
    interaction of this argument with the return value of the local_
    user argument.

 local_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Local user the caller must use for a proxy login. The local_user
    argument is the address of a 32-byte character-string descriptor
    pointer to receive the local user name the caller must use for a
    proxy login for the proxy with the remote node name specified by
    the rem_node argument and the remote user name specified by the
    rem_user argument.

    A local user name is a 32-character blank padded string of
    alphanumeric characters, including dollar signs ($)  and
    underscores (_).

 local_user_length

    OpenVMS usage:output length
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Length of the returned local user name in the local_user
    argument. The local_user_length argument is the address of an
    unsigned word to receive the length, in bytes, of the character
    string returned in the local_user argument.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Functional specification for the service and type of user the
    local_user argument represents. The flags argument is a longword
    bit mask wherein each bit corresponds to an option.

    Each flag option has a symbolic name. The $PRXDEF macro defines
    the following symbolic name:

    Symbolic Name      Description

    PRX$M_BYPASS_      The service should not convert the node name
    EXPAND             specified in the rem_node argument to its
                       corresponding DECnet for OpenVMS full name.
                       If this flag is set, it is the caller's
                       responsibility to ensure that the fully
                       expanded node name is passed into the service.

328  –  $WAIT

    The Wait service suspends image execution until an asynchronous
    record service completes. Upon completion of the service, RMS
    returns control to your program at the point following the Wait
    service call.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.

329  –  $WAITFR

    Tests a specific event flag and returns immediately if the flag
    is set; otherwise, the process is placed in a wait state until
    the event flag is set.

    Format

      SYS$WAITFR  efn

    C Prototype

      int sys$waitfr  (unsigned int efn);

329.1  –  Argument

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag for which to wait. The efn argument is a
    longword containing this number; however, $WAITFR uses only the
    low-order byte.

330  –  $WAKE

    Activates a process that has placed itself in a state of
    hibernation with the Hibernate ($HIBER) service.

    This service accepts 64-bit addresses.

    Format

      SYS$WAKE  [pidadr] ,[prcnam]

    C Prototype

      int sys$wake  (unsigned int *pidadr, void *prcnam);

330.1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       modify
    mechanism:    by 32- or 64-bit reference
    Process identification (PID) of the process to be activated. The
    pidadr argument is the 32- or 64-bit address of a longword that
    contains the PID. The pidadr argument can refer to a process
    running on the local node or a process running on another node in
    the cluster.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Process name of the process to be activated. The prcnam argument
    is the 32- or 64-bit address of a 32- or 64-bit character string
    descriptor pointing to the process name. A process running on the
    local node can be identified with a 1 to 15 character string.

    To identify a process on a particular node in a cluster, specify
    the full process name, which includes the node name as well as
    the process name. The full process name can contain up to 23
    characters.

    The process name is implicitly qualified by the UIC group number
    of the calling process. For this reason, you can use the prcnam
    argument only if the process to be activated is in the same UIC
    group as the calling process. To activate a process in another
    UIC group, you must specify the pidadr argument.

331  –  $WFLAND

    Allows a process to specify a set of event flags for which it
    wants to wait.

    Format

      SYS$WFLAND  efn ,mask

    C Prototype

      int sys$wfland  (unsigned int efn, unsigned int mask);

331.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of any event flag within the event flag cluster to be
    used. The efn argument is a longword containing this number;
    however, $WFLAND uses only the low-order byte. Specifying the
    number of an event flag within the cluster serves to identify the
    event flag cluster.

    There are two local event flag clusters: cluster 0 and cluster
    1. Cluster 0 contains event flag numbers 0 to 31, and cluster 1
    contains event flag numbers 32 to 63.

    There are two common event flag clusters: cluster 2 and cluster
    3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3
    contains event flag numbers 96 to 127.

 mask

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Event flags for which the process is to wait. The mask argument
    is a longword bit vector wherein a bit, when set, selects the
    corresponding event flag for which to wait.

332  –  $WFLOR

    Allows a process to specify a set of event flags for which it
    wants to wait.

    Format

      SYS$WFLOR  efn ,mask

    C Prototype

      int sys$wflor  (unsigned int efn, unsigned int mask);

332.1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of any event flag within the event flag cluster to be
    used. The efn argument is a longword containing this number;
    however, $WFLOR uses only the low-order byte. Specifying the
    number of an event flag within the cluster serves to identify the
    event flag cluster.

    There are two local event flag clusters: cluster 0 and cluster
    1. Cluster 0 contains event flag numbers 0 to 31, and cluster 1
    contains event flag numbers 32 to 63.

    There are two common event flag clusters: cluster 2 and cluster
    3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3
    contains event flag numbers 96 to 127.

 mask

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Event flags for which the process is to wait. The mask argument
    is a longword bit vector wherein a bit, when set, selects the
    corresponding event flag for which to wait.

333  –  $WRITE

    The Write service transfers a user-specified number of bytes
    (beginning on a block boundary) to an RMS file of any file
    organization.

    For additional information about this service, see the OpenVMS
    Record Management Services Reference Manual.
Close Help