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

2  $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,...);
 

3  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 HP
   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,...);
 

2  $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  Arguments
 

flags

   OpenVMS usage:mask_longword
   type:         longword (unsigned)
   access:       read only
   mechanism:    by value
   Reserved to HP. 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 HP.
 

afttime

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

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

2  $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);
 

3  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 HP OpenVMS System Services
   Reference Manual.
 

   To view the format of an item set entry and descriptor table, see
   the HP 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 HP 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 HP 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 HP 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.
 

2  $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);
 

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

2  $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 HP 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);
 

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

2  $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]);
 

3  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 HP 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
   HP 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.
 

2  $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]);
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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)));
 

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

2  $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);
 

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

2  $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);
 

3  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
 

2  $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);
 

3  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 HP 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.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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,...);
 

3  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 HP 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 HP 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 HP OpenVMS I/O User's Reference
   Manual.
 

2  $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);
 

3  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 HP.

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

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

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

2  $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);
 

2  $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);
 

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

2  $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);
 

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

2  $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]);
 

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

2  $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);
 

3  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 HP 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.
 

2  $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);
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  Arguments
 

reqidt

   OpenVMS usage:user_arg
   type:         longword (unsigned)
   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 longword 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.
 

2  $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);
 

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

2  $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);
 

3  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 HP 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.
 

2  $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);
 

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

2  $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);
 

3  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
                      HP.
   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 HP.
 

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

2  $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);
 

2  $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);
 

3  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 HP 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 HP.
 

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.
 

2  $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);
 

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

2  $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);
 

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

2  $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.
 

2  $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
 

3  Arguments
   None.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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.
 

2  $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);
 

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

2  $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 HP 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);
 

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

2  $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 HP 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);
 

2  $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.
 

2  $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);
 

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

2  $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 HP 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);
 

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

2  $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 HP 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);
 

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

2  $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,...);
 

3  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 HP 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 HP 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.
 

2  $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,...);
 

3  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 HP 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.
 

2  $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);
 

3  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 HP 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 HP and should be specified as 0. The condition value
   SS$_IVSECFLG is returned if any undefined bits are set.
 

2  $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);
 

3  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 HP 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 HP 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.
 

2  $CREATE_RDB
   Initializes a rights database.

   Format

     SYS$CREATE_RDB  [sysid]

   C Prototype

     int sys$create_rdb  (struct _generic_64 *sysid);
 

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

2  $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,...);
 

3  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 HP. 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.
 

2  $CREATE_UID
   Generates a universally unique identifier (UID).

   Format

     SYS$CREATE_UID  uid

   C Prototype

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

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

2  $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);
 

3  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 HP 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 HP 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 HP.

   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.
 

2  $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);
 

3  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 HP OpenVMS System Services Reference Manual to view
   the item code diagrams and descriptor fields tables.
 

2  $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);
 

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

2  $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,...);
 

3  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 HP 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 HP.
 

2  $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,...);
 

3  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 HP 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 HP 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 HP 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 HP 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 HP.
 

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

2  $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);
 

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

2  $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);
 

3  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 HP 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.
 

2  $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);
 

3  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 HP 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 HP 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 HP 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 HP 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.
 

2  $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,...);
 

3  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 HP 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.
 

2  $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,...);
 

3  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 HP 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.

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

2  $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,...);
 

3  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 HP 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.
 

2  $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,...);
 

3  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 HP 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 HP 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.
 

2  $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,...);
 

3  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 HP 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 HP 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.
 

2  $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,...);
 

3  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 HP 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.
 

2  $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);
 

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

2  $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);
 

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

2  $DALLOC
   Deallocates a previously allocated device.

   Format

     SYS$DALLOC  [devnam] ,[acmode]

   C Prototype

     int sys$dalloc  (void *devnam, unsigned int acmode);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $DCLEXH
   Declares an exit handling routine that receives control when an
   image exits.

   Format

     SYS$DCLEXH  desblk

   C Prototype

     int sys$dclexh  (void *desblk);
 

3  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 HP OpenVMS System
   Services Reference Manual.
 

2  $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),... ;
 

3  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 HP 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
   HP 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
   HP 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.
 

2  $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),...);
 

2  $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.
 

2  $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);
 

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

2  $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 HP OpenVMS Alpha Partitioning and Galaxy Guide.

   Format

     SYS$DELETE_GALAXY_LOCK  handle

   C Prototype

     int sys$delete_galaxy_lock  (unsigned __int64 lock_handle);
 

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

2  $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 HP 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);
 

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

2  $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);
 

3  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 HP 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.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $DELMBX
   Marks a permanent mailbox for deletion.

   Format

     SYS$DELMBX  chan

   C Prototype

     int sys$delmbx  (unsigned short int chan);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP 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 HP.
 

2  $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);
 

3  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 HP 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.
 

2  $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);
 

3  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 HP 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.
 

2  $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.
 

2  $DISMOU
   Dismounts a mounted volume or volume sets.

   Format

     SYS$DISMOU  devnam ,[flags]

   C Prototype

     int sys$dismou  (void *devnam, unsigned int flags);
 

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

2  $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.
 

2  $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);
 

3  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 HP 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
   HP 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 HP 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.
 

2  $DLCEFC
   Marks a permanent common event flag cluster for deletion.

   Format

     SYS$DLCEFC  name

   C Prototype

     int sys$dlcefc  (void *name);
 

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

2  $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]);
 

3  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 HP 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.
 

2  $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]);
 

2  $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,...);
 

3  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 HP 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.
 

2  $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,...);
 

2  $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,...);
 

3  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 HP 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 HP 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 HP.
 

2  $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,...);
 

2  $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.
 

2  $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);
 

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

2  $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.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP
   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.
 

2  $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.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP 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.
 

2  $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.
 

2  $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);
 

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

2  $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);
 

3  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 HP
                   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.
 

2  $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);
 

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

2  $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.
 

2  $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);
 

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

2  $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);
 

3  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 HP 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.
 

2  $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);
 

2  $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));
 

3  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 HP 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 HP.
 

2  $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);
 

3  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 HP 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.
 

2  $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.
 

2  $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);
 

3  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 HP and must be 0.
 

2  $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.
 

2  $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);
 

3  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 HP 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
   HP 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 HP 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 HP 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.
 

2  $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);
 

2  $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, HP 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,
      HP 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,...);
 

3  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).

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

   Though this argument is optional, HP 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 HP.
 

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.
 

2  $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. HP 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,...);
 

2  $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);
 

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

2  $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 HP 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);
 

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

2  $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 HP 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);
 

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

2  $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);
 

3  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).

   HP 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 HP 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 HP 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, HP 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.
 

2  $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. HP 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);
 

2  $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);
 

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

   HP 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 HP 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 HP 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, HP 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 HP.
 

2  $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);
 

2  $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]);
 

3  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
 

2  $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);
 

3  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).

   HP 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 HP 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 HP 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 HP 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, HP 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.
 

2  $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);
 

2  $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);
 

3  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 HP.
 

nullarg

   OpenVMS usage:null_arg
   type:         longword (unsigned)
   access:       read only
   mechanism:    by value
   Placeholding argument reserved to HP.
 

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

2  $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);
 

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

   HP 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 HP 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 HP 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, HP 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.
 

2  $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.
 

2  $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,...);
 

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

2  $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);
 

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

2  $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);
 

3  Arguments
 

nullarg

   OpenVMS usage:null_arg
   type:         longword (unsigned)
   access:       read only
   mechanism:    by value
   Placeholding argument reserved to HP.
 

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 HP OpenVMS System Services Reference Manual.
 

nullarg

   OpenVMS usage:nullarg
   type:         quadword (unsigned)
   access:       write only
   mechanism:    by reference
   Placeholding argument reserved to HP.
 

nullarg

   OpenVMS usage:nullarg
   type:         procedure entry mask
   access:       call without stack unwinding
   mechanism:    by reference
   Placeholding argument reserved to HP.
 

nullarg

   OpenVMS usage:nullarg
   type:         longword (unsigned)
   access:       read only
   mechanism:    by value
   Placeholding argument reserved to HP.
 

2  $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]);
 

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

2  $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);
 

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

2  $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 HP OpenVMS Calling Standard.

   Format

     SYS$GET_ARITH_EXCEPTION  sigarg ,mcharg ,buffer

   C Prototype

     int sys$get_arith_exception  (void *sigarg, void *mcharg, void

                                  *buffer);
 

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

2  $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]);
 

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

2  $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 HP 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);
 

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

2  $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 HP 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);
 

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

2  $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);
 

3  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 HP 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 HP.
 

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.
 

2  $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);
 

3  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 HP 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. HP recommends that this argument be omitted
   (passed as zero).
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP and must be 0.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP 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.
 

2  $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);
 

3  Arguments
   None.
 

2  $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);
 

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

2  $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);
 

3  Arguments
 

assoc_handle

   OpenVMS usage:association_id
   type:         longword (unsigned)
   access:       read only
   mechanism:    by value
   The handle of the association to be closed.
 

2  $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);
 

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

2  $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);
 

2  $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);
 

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

2  $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);
 

2  $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);
 

3  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 HP
   OpenVMS System Manager's Manual.
 

2  $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);
 

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

2  $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);
 

2  $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);
 

3  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
 

2  $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);
 

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

2  $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);
 

2  $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);
 

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

2  $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);
 

2  $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);
 

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

2  $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);
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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); ,
 

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

2  $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);
 

3  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 HP 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.
 

2  $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);
 

3  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:

   ! " % ' ( ) * + , - . / : ; < = >

   HP 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 HP OpenVMS System Services Reference Manual.
 

2  $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);
 

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

2  $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, ...) ;)
 

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

2  $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, ...) ;)
 

2  $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);
 

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

2  $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);
 

2  $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);
 

3  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 HP 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.
 

2  $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,...);
 

3  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 HP 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
   HP 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 HP.
 

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.
 

2  $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,...);
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP 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 HP 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.
 

2  $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,...);
 

3  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 HP 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 HP 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.
 

2  $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,...);
 

3  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 HP 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 HP 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.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP OpenVMS System Services Reference Manual.
 

2  $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);
 

3  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
 

2  $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);
 

3  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 HP 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).
 

2  $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]);
 

3  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 HP 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.
 

2  $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.
 

2  $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.
 

2  $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.
 

2  $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));
 

3  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 HP.
 

2  $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);
 

3  Arguments
   None.
 

2  $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);
 

3  Arguments
   None.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP 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.
 

2  $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);
 

3  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 HP OpenVMS System Services Reference Manual to view
   the item code diagram and descriptor fields table.
 

2  $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);
 

3  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 HP OpenVMS System Services Reference Manual to view
   the item code diagram and descriptor fields table.
 

2  $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);
 

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

2  $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;
 

3  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).
 

2  $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,...);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP OpenVMS System Services Reference Manual to view
   the item code diagrams and descriptor fields tables.
 

2  $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);
 

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

2  $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);
 

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

2  $PUT
   The Put service inserts a record into a file.

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

2  $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);
 

3  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 HP 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.
 

2  $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);
 

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

2  $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, Digital
   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);
 

2  $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.
 

2  $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);
 

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

2  $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, ...);
 

3  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 HP 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 HP 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, HP 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.
 

2  $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, ...);
 

2  $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.
 

2  $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 HP OpenVMS Alpha Partitioning and Galaxy Guide.

   Format

     SYS$RELEASE_GALAXY_LOCK  handle

   C Prototype

     int sys$release_galaxy_lock  (unsigned __int64 lock_handle);
 

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

2  $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.
 

2  $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);
 

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

2  $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);
 

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

2  $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.
 

2  $RESCHED
   Requests reschedule of a process.

   Format

     SYS$RESCHED

   C Prototype

     int sys$resched  (void);
 

3  Arguments
   None.
 

2  $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);
 

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

2  $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);
 

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

2  $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.
 

2  $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);
 

3  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).
 

2  $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  ();
 

2  $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);
 

3  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 HP 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.
 

2  $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);
 

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

2  $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);
 

3  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 HP
   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.
 

2  $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.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP 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 HP 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
 

3  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 HP OpenVMS
                      System Manager's Manual, for information on
                      defining node names.
   DTI$T_PART_LOG_ID  Reserved by HP.
   DTI$T_TID          A 16-byte field containing the transaction
                      identifier.
 

2  $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);
 

2  $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);
 

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

2  $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)));
 

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

2  $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);
 

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

2  $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
 

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

3  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
 

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.
 

2  $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);
 

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

2  $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);
 

3  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:         longword (unsigned)
   access:       read only
   mechanism:    by value
   Identification of the timer request. The reqidt argument is a
   longword 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.
 

2  $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);
 

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

2  $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);
 

3  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 HP OpenVMS System Services Reference
   Manual.
 

nullarg

   OpenVMS usage:null_arg
   type:         longword (unsigned)
   access:       read only
   mechanism:    by value
   Placeholding argument reserved to HP.
 

2  $SETPRN
   Allows a process to establish or to change its own process name.

   Format

     SYS$SETPRN  [prcnam]

   C Prototype

     int sys$setprn  (void *prcnam);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

3  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 HP
   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
 

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.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  Arguments
 

nullarg

   OpenVMS usage:null_arg
   type:         longword (unsigned)
   access:       read only
   mechanism:    by value
   Placeholding argument reserved to HP.
 

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 HP OpenVMS System Services Reference Manual.
 

nullarg

   OpenVMS usage:nullarg
   type:         quadword (unsigned)
   access:       write only
   mechanism:    by reference
   Placeholding argument reserved to HP.
 

nullarg

   OpenVMS usage:nullarg
   type:         procedure entry mask
   access:       call without stack unwinding
   mechanism:    by reference
   Placeholding argument reserved to HP.
 

nullarg

   OpenVMS usage:nullarg
   type:         longword (unsigned)
   access:       read only
   mechanism:    by value
   Placeholding argument reserved to HP.
 

2  $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);
 

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

2  $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,...);
 

3  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 HP 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.
 

2  $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,...);
 

2  $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);
 

3  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 HP 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 HP and should be zero.
 

2  $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);
 

2  $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);
 

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

2  $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,...);
 

3  Arguments
 

mbz1

   type:
   access:
   mechanism:    0
   Reserved for future use by HP. 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 agairundown. 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 HP.

   PPROP$C_MEDDLE_       Reserved for use by HP.
   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 HP 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 HP 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 HP 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.
 

2  $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);
 

3  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 HP 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 HP. 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.
 

2  $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);
 

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

2  $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);
 

3  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 HP 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.

   HP recommends that this argument be omitted (passed as zero).
 

2  $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);
 

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

2  $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);
 

3  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).
 

2  $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);
 

3  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 HP 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 HP
   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 HP 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.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP.
 

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 HP 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, HP 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.
 

2  $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);
 

2  $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);
 

3  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 HP 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.
 

2  $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.
 

2  $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);
 

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

2  $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],...);
 

3  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 HP 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
   HP 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 HP.
 

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.
 

2  $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],...);
 

2  $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,...);
 

3  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 HP 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.
 

2  $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.
 

2  $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);
 

3  Arguments
   None.
 

2  $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);
 

3  Arguments
   None.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

3  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 HP. 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 HP 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 HP OpenVMS System Services Reference Manual.
 

2  $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, )
 

2  $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);
 

3  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 HP OpenVMS System Services Reference Manual.
 

2  $TRUNCATE
   The Truncate service shortens a sequential file.

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $UNWIND
   Unwinds the procedure call stack.

   Format

     SYS$UNWIND  [depadr] ,[newpc]

   C Prototype

     int sys$unwind  (unsigned int *depadr, void *newpc);
 

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

2  $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);
 

3  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, HP 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.
 

2  $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);
 

2  $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,...);
 

3  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 HP. The value in this
      field is unpredictable.

   o  iosa$q_count_q (offset 8)

      This field is reserved for future use by HP. 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 HP. 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.
 

2  $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,...);
 

2  $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);
 

3  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 HP 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.
 

2  $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.
 

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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);
 

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

2  $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.