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.