HP OpenVMS Systems Documentation

Content starts here HP OpenVMS System Services Reference Manual

HP OpenVMS System Services Reference Manual


September 2003

This manual describes a set of routines that the HP OPENVMS operating system uses to control resources, to allow process communication, to control I/O, and to perform other such operating system functions.

Revision/Update Information: This manual supersedes the
HP OpenVMS System Services Reference Manual, Version 7.3-1

Software Version: OpenVMS Version 7.3-2




Hewlett-Packard Company
Palo Alto, California


© Copyright 2003 Hewlett-Packard Development Company, L.P.

Microsoft®, MS-DOS®, Visual C++®, Windows®, and Windows NT® are U.S. registered trademarks of Microsoft Corporation.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation in the U.S. and other countries and are used under license. Pentium® is a U.S. registered trademark of Intel Corporation.

Motif and OSF/1 are trademarks of The Open Group in the U.S. and other countries. UNIX® is a registered trademark of The Open Group.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Proprietary computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

ZK4527

The HP OpenVMS documentation set is available on CD-ROM.

Contents Index


Preface

Intended Audience

This manual is intended for system and application programmers who want to call system services.

System Services Support for HP OpenVMS Alpha 64-bit Addressing

As of Version 7.0, the HP OpenVMS Alpha operating system provides support for 64-bit virtual memory addresses. This support makes the 64-bit virtual address space defined by the Alpha architecture available to the OpenVMS Alpha operating system and to application programs. In the 64-bit virtual address space, both process-private and system virtual address space extend beyond 2 GB. By using 64-bit address features, programmers can create images that map and access data beyond the previous limits of 32-bit virtual addresses.

New OpenVMS system services are available, and many existing services have been enhanced to manage 64-bit address space. The system services descriptions in this manual indicate the services that accept 64-bit addresses. A list of the OpenVMS system services that accept 64-bit addresses is available in the OpenVMS Programming Concepts Manual.

The following section briefly describes how 64-bit addressing support affects OpenVMS system services. For complete information about OpenVMS Alpha 64-bit addressing features, refer to the OpenVMS Programming Concepts Manual.

64-Bit System Services Terminology

32-Bit System Service

A 32-bit system service only supports 32-bit addresses on any of its arguments that specify addresses. If passed by value on OpenVMS Alpha, a 32-bit virtual address is actually a 64-bit address that is sign-extended from 32 bits.

64-Bit Friendly Interface

A 64-bit friendly interface can be called with all 64-bit addresses. A 32-bit system service interface is 64-bit friendly if, without a change in the interface, it needs no modification to handle 64-bit addresses. The internal code that implements the system service might need modification, but the system service interface will not.

64-Bit System Service

A 64-bit system service is defined to accept all address arguments as 64-bit addresses (not necessarily 32-bit sign-extended values). A 64-bit system service also uses the entire 64 bits of all virtual addresses passed to it.

Use of the _64 Suffix

The 64-bit system services include the _64 suffix for services that accept 64-bit addresses by reference. For promoted services, this suffix distinguishes the 64-bit capable version from its 32-bit counterpart. For new services, it is a visible reminder that a 64-bit-wide address cell will be read/written.

Sign-Extension Checking

The OpenVMS system services that do not support 64-bit addresses and all user-written system services that are not explicitly enhanced to accept 64-bit addresses receive sign-extension checking. Any argument passed to these services that is not properly sign-extended causes the error status SS$_ARG_GTR_32_BITS to be returned.

Related Documents

The OpenVMS Programming Concepts Manual contains useful information for anyone who wants to call system services.

High-level language programmers can find additional information about calling system services in the language reference manual and language user's guide provided with the OpenVMS language.

Application developers using XA-compliant or other resource managers should refer to the OpenVMS Programming Concepts Manual.

The following documents might also be useful:

  • OpenVMS Programming Concepts Manual
  • Guide to OpenVMS File Applications
  • HP OpenVMS Guide to System Security
  • DECnet-Plus for OpenVMS Introduction and User's Guide
  • OpenVMS Record Management Services Reference Manual
  • HP OpenVMS I/O User's Reference Manual
  • OpenVMS Alpha Guide to Upgrading Privileged-Code Applications

For additional information about HP OpenVMS products and services, visit the following World Wide Web address:


http://www.hp.com/products/openvms

Reader's Comments

HP welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet openvmsdoc@hp.com
Postal Mail Hewlett-Packard Company
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

For information about how to order additional documentation, visit the following World Wide Web address:


http://www.hp.com/go/openvms/doc/order

Conventions

The following conventions are used in this manual:

Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)

In the HTML version of this document, this convention appears as brackets, rather than a box.

... A horizontal ellipsis in examples indicates one of the following possibilities:
  • Additional optional arguments in a statement have been omitted.
  • The preceding item or items can be repeated one or more times.
  • Additional parameters, values, or other information can be entered.
.
.
.
A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( ) In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one.
[ ] In the HP OpenVMS System Services Reference Manual, brackets generally indicate default arguments. If an argument is optional, it is specified as such in the argument text.
| In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ } In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold type Bold type represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic type Italic type indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TYPE Uppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Example This typeface indicates code examples, command examples, and interactive screen displays. In text, this type also identifies URLs, UNIX commands and pathnames, PC-based commands and folders, and certain elements of the C programming language.
- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.


System Service Descriptions

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

Condition values returned by system services not only indicate whether the service completed successfully, but can also provide other information. While the usual condition value indicating success is SS$_NORMAL, other values are also defined. For example, the condition value SS$_BUFFEROVERF, which is returned when a character string returned by a service is longer than the buffer provided to receive it, is a success code, but it also provides additional information.

Warning returns and some error returns indicate that the service may have performed some, but not all, of the requested function.

The particular condition values that each service can return are described in the Condition Values Returned section of each individual service description.

Returns

OpenVMS usage:
type:
access:
mechanism:
cond_value
longword (unsigned)
write only
by value

Longword condition value. All system services (except $EXIT) return by immediate value a condition value in R0.


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


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 Table SYS-1. 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_NOWAIT Set this flag to indicate that the service should 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:
  • The completion status of the service, returned as a condition value. See the Condition Values Returned section.
  • 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 Table SYS-2:

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_BRANCH An unauthorized branch caused failure.
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$_SERIALIZATION A DECdtm transaction manager 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.

The following diagram shows the structure of the I/O status block:


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. The codes currently defined are listed in Table SYS-2.

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.


Description

The Abort Transaction service ends a transaction by aborting it.

The $ABORT_TRANS system service:

  • Initiates abort processing for the specified transaction, if it has not already been initiated.
    If abort processing has not already been initiated, the DECdtm transaction manager instructs the resource managers to abort (roll back) the transaction operations so that none of those operations ever take effect. It delivers an abort event to each RM participant in the transaction that is associated with an RMI that requested abort events.
  • Removes the specified branch from the specified transaction in this process.

Preconditions for the successful completion of $ABORT_TRANS include:

  • If the BID is zero, the calling process must have started the transaction.
  • If the BID is nonzero, the calling process must contain the specified branch of the specified transaction.
  • If the BID is nonzero, the tid argument must not be omitted. If you explicitly pass the BID, you must also explicitly pass the TID.

$ABORT_TRANS may fail for various reasons, including:

  • The preconditions were not met.
  • There has already been a call to $ABORT_TRANS, $END_TRANS, or $END_BRANCH for the specified branch.

Postconditions on successful completion of $ABORT_TRANS are listed in Table SYS-3:

Table SYS-3 Postconditions When$ABORT_TRANS Completes Successfully
Postcondition Meaning
The transaction is ended. If DDTM$M_NOWAIT is clear:
  • The TID of the transaction is invalid; calls to any DECdtm system services except $GETDTI and $SETDTI that pass the TID will fail, and calls to resource managers that pass the TID will fail.
  • The transaction no longer has any application or RM participants on the local node.
  • All communications about the transaction between the local DECdtm transaction manager and other DECdtm transaction managers are finished (including the final "cleanup" acknowledgment).
The outcome of the transaction is abort. None of the operations of the transaction will ever take effect.
DECdtm quotas are returned. If DDTM$M_NOWAIT is clear, all quotas allocated for the transaction by calls on the local node to DECdtm services are now returned.
The transaction is not the default transaction of the calling process. If DDTM$M_NOWAIT is clear, then, if the transaction was the default transaction of the calling process, it is now no longer the default.

$ABORT_TRANS will not complete successfully (that is, the event flag will not be set, the AST routine will not be called, and the I/O status block will not be filled in) until all branches on the local node have been removed from the transaction. Thus this call to $ABORT_TRANS cannot complete successfully until every authorized and synchronized branch on the local node has initiated a call to $END_TRANS, $END_BRANCH, or $ABORT_TRANS.

$ABORT_TRANS must deliver notification ASTs to resource managers participating in the transaction. Therefore it will not complete successfully while the calling process is either:

  • In an access mode that is more privileged than the DECdtm calls made by any resource manager participating in the transaction. RMS journaling calls DECdtm in executive mode. Oracle Rdb and Oracle CODASYL DBMS call DECdtm in user mode.
  • At AST level in the same access mode as the least privileged DECdtm calls made by any resource manager participating in the transaction.

For example, if Oracle Rdb is a participant in the transaction, $ABORT_TRANS will not complete successfully while the calling process is in supervisor, executive, or kernel mode, or while the calling process is at AST level.

Note that successful completion of $ABORT_TRANS is not indefinitely postponed by network failure.

Required Access or Privileges

None

Required Quotas

ASTLM

Related Services

$ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW, $SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW


Condition Values Returned

SS$_NORMAL If this was returned in R0, the request was successfully queued. If it was returned in the I/O status block, the service completed successfully.
SS$_SYNCH The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set).
SS$_ACCVIO An argument was not accessible by the caller.
SS$_BADPARAM The options flags were invalid or the tid argument was omitted and the bid argument was not zero.
SS$_BADREASON The abort reason code was invalid.
SS$_CURTIDCHANGE The tid argument was omitted and a call to change the default transaction of the calling process was in progress.
SS$_EXASTLM The process AST limit (ASTLM) was exceeded.
SS$_ILLEFC The event flag number was invalid.
SS$_INSFARGS A required argument was missing.
SS$_INSFMEM There was insufficient system dynamic memory for the operation.
SS$_NOCURTID An attempt was made to abort the default transaction (the tid argument was omitted), but the calling process did not have a default transaction.
SS$_NOLOG The local node did not have a transaction log.
SS$_NOSUCHBID The calling process did not contain the branch identified by the BID passed in the bid argument (possibly because there has already been a call to $ABORT_TRANS, $END_TRANS, or $END_BRANCH for that branch).

This error is returned only if the bid argument is not zero.

SS$_NOSUCHTID A transaction with the specified transaction identifier does not exist.
SS$_NOTORIGIN A bid of zero was specified and the calling process did not start the transaction.
SS$_TPDISABLED The TP_SERVER process was not running on the local node.
SS$_WRONGSTATE Commit processing for the transaction had already started. This can occur if bid is zero or the specified branch was unsynchronized.

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

Do not call $ABORT_TRANSW from AST level, or from an access mode that is more privileged than the DECdtm calls made by any resource manager participant in the transaction. If you do, the $ABORT_TRANSW service will wait indefinitely.


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


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


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-4 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-5 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:

  • Completed the commit processing for its transaction operations.
  • 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$_REMEMBER The RM participant requires that the DECdtm 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-6 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$_PREPARED Yes RM participant decided not to accept the 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-7 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$_PREPARED Yes 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. 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-8 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-9 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 Table SYS-10. The default value for this argument is DDTM$_VETOED.

Table SYS-10 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_BRANCH Transaction aborted because it had an unauthorized branch.
DDTM$_PART_SERIAL Transaction aborted because a resource manager serialization check failed.
DDTM$_PART_TIMEOUT Transaction aborted because a resource manager timeout expired.
DDTM$_SEG_FAIL Transaction aborted because a process or image terminated.
DDTM$_SERIALIZATION Transaction aborted because a 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.

Description

The $ACK_EVENT system service:
  • Acknowledges an event report delivered by the DECdtm transaction manager to an RM participant or RMI in the calling process.
    Every event report delivered by the DECdtm transaction manager to an RM participant or RMI must be acknowledged by a call to $ACK_EVENT specifying the identifier of the event report. This acknowledgment need not come from AST context. The caller of $ACK_EVENT must be in the same access mode as, or a more privileged access mode than, that in which the event handler AST was delivered.
    The DECdtm transaction manager may deliver multiple event reports to an RMI, but delivers only one event report at a time to an 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.
    After acknowledging the event report, the RMI or RM participant should no longer access the event report block.
  • Adds a new RM participant to a transaction, if the event being acknowledged is of type Transaction Started and the value of the report_reply argument is SS$_NORMAL.
    Note that the new RM participant cannot be the coordinator of the transaction.
  • Removes an RM participant from a transaction if the event being acknowledged is one of the events listed in the following table and the report_reply argument is as listed in this table:
    Event report_reply
    Abort SS$_FORGET
    Commit SS$_FORGET or SS$_REMEMBER
    Prepare SS$_FORGET or SS$_VETO
    One-phase commit SS$_NORMAL or SS$_VETO

Required Privileges

None

Required Quotas

None

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW, $SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW


Condition Values Returned

SS$_NORMAL The request was successful.
SS$_ACCVIO An argument was not accessible to the caller.
SS$_BADPARAM Either the options flags were invalid, or the reply passed in the report_reply argument was invalid for the type of event being acknowledged.
SS$_BADREASON The abort reason code passed in the reason argument was invalid.
SS$_EXASTLM The process AST limit (ASTLM) was exceeded.
SS$_ILLEFC The event flag number was invalid.
SS$_INSFARGS A required argument was missing.
SS$_INSFMEM There was insufficient system dynamic memory for the operation.
SS$_INVBUFLEN The string passed in the part_name argument was too long.
SS$_NOSUCHREPORT Either an event report with the specified report identifier had not been delivered to any RM participant or RMI in the calling process, or that event report had already been acknowledged.
SS$_WRONGACMODE The caller was in a less privileged access mode than that of the RMI whose event handler was used to deliver the event report that is being acknowledged by this call to $ACK_EVENT.

$ACM (Alpha Only)

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


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.

The following diagram depicts the overall format of an ACM communications buffer:

ACM Communications Buffer


The following table defines the ACM communications buffer header fields:

Descriptor Field Definition
ACMECB$Q_CONTEXT_ID A quadword containing a value used internally by $ACM to uniquely bind the ACM communications buffer to the associated request across iterative calls.
ACMECB$W_SIZE A word containing the size of the ACM communications structure.
ACMECB$W_REVISION_LEVEL A word containing a value that identifies the revision level of the ACM communications structure.
ACMECB$L_ACME_ID A longword containing the agent ID of the ACME agent that initiated this dialogue sequence.
ACMECB$L_ITEM_SET_COUNT A longword containing the number of item set entries in the item set.
ACMECB$PS_ITEM_SET A longword containing the 32-bit address of the item set. The item set is an array of item set entries that describes the information needed by $ACM to complete the particular request.

The following diagram depicts the format of an item set entry:


The following table defines the item set entry fields:

Descriptor Field Definition
ACMEIS$L_FLAGS A longword containing a mask of flags that indicates the interpretation of the ACMEIS$Q_DATA_1 and ACMEIS$Q_DATA_2 quadword-sized 32-bit descriptors and the method for processing.

Each flag has a symbolic name that the language support mechanisms specific to each programming language define. The following list describes the flags:

  • ACMEDLOGFLG$V_INPUT
    When clear:
    • ACMEIS$W_MSG_TYPE contains the message type associated with this output data.
    • ACMEIS$Q_DATA_1 and ACMEIS$Q_DATA_2 are 32-bit descriptors that specify text to be displayed to the caller.

      An address of 0 in either descriptor indicates the calling program should ignore that descriptor.

      A length of 0 with a nonzero address in either descriptor indicates the calling program should report a separation indication to the user if that is appropriate for the type of human interface involved. A line mode command interface, for instance, will display a blank line.


    When set:
    • ACMEIS$W_ITEM_CODE defines the item code to use when providing the requested information.
    • ACMEIS$Q_DATA_1 is a 32-bit descriptor that specifies prompt text.

      An address of 0 indicates no prompt text. A length of 0 with a nonzero address is reserved for future definition.

    • Interpretation of ACMEIS$Q_DATA_2 is determined by the state of the ACMEDLOGFLG$V_NOECHO flag.
  • ACMEDLOGFLG$V_NOECHO
    When clear:
    • ACMEIS$Q_DATA_2 is a 32-bit descriptor that specifies the "default" answer that will be assumed by $ACM if the caller responds to this item set entry with an item specifying a length of zero. $ACM provides this "default" answer to the calling program to allow for distinctive display appropriate to the type of interface being supported. For example, traditional line-mode interfaces in VMS will include such a default answer within square brackets when prompting, while a character cell screen interface might pre-fill a field.

    When set:
    • The associated input data is not to be echoed. This is typically used to visually protect sensitive data, such as password information.
    • ACMEIS$Q_DATA_2 is a 32-bit descriptor that specifies secondary prompt text for input verification processing.

      An address of 0 indicates no verification processing. A length of 0 with a nonzero address is reserved for future definition.

    The flag ACMEDLOGFLG$V_NOECHO is ignored when ACMEDLOGFLG$V_INPUT is clear.

ACMEIS$W_ITEM_CODE A word containing the item code that identifies the nature of information associated with the item set. This field defines the item code to use when specifying the requested information in the itmlst argument in the subsequent call to $ACM. A sequence of item set entries containing the same item code reflects a linked list of related information. An item set with the ACMEDLOGFLG$V_INPUT flag set or a different item code indicates the end of the related list.
ACMEIS$W_MAX_LENGTH When ACMEDLOGFLG$V_INPUT is set:

A word containing the maximum length (in bytes) of any input data being requested by this item set. For example, the maximum length of a principal name string. A value of 0 indicates that the only item the calling program can return to satisfy the item set entry is an item specifying zero length. When the calling program returns such a zero length item, it thereby indicates confirmation, as might be indicated by a prompt such as "Indicate when you have read that text".

ACMEIS$W_MSG_TYPE When ACMEDLOGFLG$V_INPUT is clear:

A word containing a value that categorizes the output messages described by 32-bit descriptors ACMEIS$Q_DATA_1 and ACMEIS$Q_DATA_2.

The language support mechanisms specific to each programming language define the following symbols for the standard message categories:

ACMEMC$K_DIALOGUE_ALERT---Text related to the immediately preceding input operation. The calling program should bring this text to the attention of a user prior to handling the renewed input item set entry that typically follows. This message category is used, for example, to indicate that a new password the user has specified does not conform to local security policy.
ACM$K_GENERAL---General text.
ACM$K_HEADER---Text displayed before a succession of Selections.
ACMEMC$K_MAIL_NOTICES---Text related to mail operations, typically an indication that new mail is waiting.
ACMEMC$K_PASSWORD_NOTICES---Text indicating that password expiration is imminent.
ACM$K_TRAILER---Text displayed after a succession of Selections.
ACM$K_SELECTION---Acceptable choices for responding to the subsequent prompt.
ACM$K_SYSTEM_IDENTIFICATION---System identification text.
ACM$K_SYSTEM_NOTICES---Text displayed to a user before authentication.
ACM$K_WELCOME_NOTICES---Text displayed to a user after authentication.
ACM$K_LOGON_NOTICES---Logon and logfail statistics.

In addition to those standard message categories, individual ACME agents may define their own categories, but the meanings of those categories are useful only to callers of $ACM that are specifically recognized by the ACME agent in question, since those are the only callers of $ACM to which the ACME agent will deliver such ACME-specific categories. Documentation of the ACME-specific codes used by the VMS ACME is shown in the VMS ACME-specific Output Message Categories section of this description.

Documentation of ACME-specific codes in general comes in the documentation from the vendor of each ACME agent.

For documentation of ACME-specific codes for the VMS ACME, see the VMS ACME-specific Item Codes section of this description.

ACMEIS$Q_DATA_1 A quadword containing a 32-bit descriptor that describes information (prompt text or other data, as described under the prior entry for ACMEDLOGFLG$V_INPUT) applicable to determining an appropriate response.
ACMEIS$Q_DATA_2 A quadword containing a 32-bit descriptor that describes information (default answer, secondary prompt text or other data described under the prior entries for ACMEDLOGFLG$V_INPUT and ACMEDLOGFLG$V_NOECHO) applicable to determining an appropriate response.

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.

The following diagram depicts the 32-bit format of a single item descriptor:


The following table defines the item descriptor fields for 32-bit item list entries:

Descriptor Field Definition
Buffer length A word specifying the length of the buffer (in bytes); the buffer either supplies information to $ACM or receives information from $ACM. The required length of the buffer varies, depending on the item code specified, and is specified in the description of each item code.
Item code A word containing an item code, which identifies the nature of the information supplied to $ACM or which is received from $ACM. Each item code has a symbolic name; the language support mechanisms specific to each programming language define these symbolic names.
Buffer address A longword containing the 32-bit address of the buffer that specifies or receives the information.
Return length address A longword containing the 32-bit address of a word to receive the length (in bytes) of information returned by $ACM. If specified as 0, no length is returned. For input items the return length address is ignored.

The following diagram depicts the 64-bit format of a single item descriptor:


The following table defines the item descriptor fields for 64-bit item list entries:

Descriptor Field Definition
MBO A word that must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries.
Item code A word containing an item code, which identifies the nature of the information supplied to $ACM or that is received from $ACM.

Common item codes have symbolic names (beginning with the characters "ACME$_") defined by the language support mechanisms specific to each programming language. Individual ACME agents may also define additional item codes specific to the functions of those ACME agents.

MBMO A longword that must contain a -1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries.
Buffer length A quadword specifying the length of the buffer (in bytes); the buffer either supplies information to $ACM or receives information from $ACM. The required length of the buffer varies, depending on the item code, and is specified in the description of each item code.
Buffer address A quadword containing the 64-bit address of the buffer that specifies or receives the information.
Return length address A quadword containing the 64-bit address of a quadword to receive the length (in bytes) of information returned by $ACM. If specified as 0, no length is returned. For input items the return length address is ignored.

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

The following diagram depicts the structure of an ACM status block:


The following table defines the ACM status block fields:

Descriptor Field Definition
ACMESB$L_STATUS A longword containing the generalized completion status for the requested operation.
ACMESB$L_SECONDARY_STATUS A longword containing status that may indicate a more detailed description of a failure.
ACMESB$L_ACME_ID A longword containing the agent ID of the ACME agent that reported additional status. An agent ID of 0 indicates that no additional status was reported.
ACMESB$L_ACME_STATUS A longword containing additional status information. Aside from a few cases of item list errors described in the following text, the interpretation of this value is specific to the context of the reporting ACME agent.

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$_BADITMCOD Incorrect item code for the function
SS$_BADBUFLEN Incorrect length for the item code

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. Function Codes This section describes the various function codes supported by the $ACM service and lists the function modifiers and item codes relevant to each function:
Function Code Purpose
ACME$_FC_AUTHENTICATE_PRINCIPAL Perform authentication and provide credentials.
ACME$_FC_CHANGE_PASSWORD Select a new password.
ACME$_FC_EVENT Log an event to an ACME agent.
ACME$_FC_FREE_CONTEXT Abandon a dialogue mode Authentication or Password Change before it has completed.
ACME$_FC_QUERY Retrieve information from an ACME agent.
ACME$_FC_RELEASE_CREDENTIALS Give up some of the credentials from a persona.

See the Description section for information relating to the modes of operation and privilege requirements.

ACME$_FC_AUTHENTICATE_PRINCIPAL

The ACME$_FC_AUTHENTICATE_PRINCIPAL function requests authentication of a principal based on standard or site-specific authentication criteria and optionally requests credentials authorized for that principal.

You can specify the principal name using the ACME$_PRINCIPAL_NAME item code. If you do not specify it on the initial call to $ACM, the ACME agents supporting $ACM will try to use another method for determining the principal name. For example, traditional VMS autologin processing determines a principal name based on your terminal name. Of if your call to $ACM was in dialogue mode, the ACM communication buffer returned may prompt you to supply a principal name.

You can also guide how your request is to be processed by directing it toward a specific domain of interpretation (DOI) with either the ACME$_TARGET_DOI_NAME or ACME$_TARGET_DOI_ID item code. Using that technique ensures that your request will be handled by the ACME agents that support the specified domain of interpretation. If that domain of interpretation is not configured on the system at the time of your call, however, your request will fail. Leaving the domain of interpretation to be defaulted increases your chance of successful authentication, but does not guarantee any particular set of credentials beyond the normal VMS credentials.

When the domain of interpretation under which your request is handled is anything other than VMS, the ACME agents that support that domain of interpretation will indicate an OpenVMS user name to which the principal name should be mapped. In this case, the OpenVMS user name must correspond to a valid entry in the OpenVMS authorization database (SYSUAF.DAT) that has the UAF$V_EXTAUTH flag set. (When the IGNORE_EXTAUTH flag is set in system parameter SECURITY_POLICY, the UAF$V_EXTAUTH flag requirement does not apply.)

The VMS ACME agent uses that OpenVMS user name to provide supplemental authorization processing (for example, account disabled or expired, or model restrictions) and to provide security profile and quota information applicable after a successful authentication.

You can use the ACME$M_ACQUIRE_CREDENTIALS function modifier to specify that, if your authentication call is successful, you want credentials returned. $ACM will return those credentials via persona extensions attached to a persona whose handle is returned to a location specified by item code ACME$_PERSONA_HANDLE_OUT.

If you want that persona to be based on some persona you already have, specify the existing persona handle with the item code ACME$_PERSONA_HANDLE_IN and, in addition to the function modifier ACME$M_ACQUIRE_CREDENTIALS, specify one of the following two function modifiers:

  • ACME$M_MERGE_PERSONA---Requests that additional credentials you acquire be added into the existing persona
  • ACME$M_COPY_PERSONA---Requests that additional credentials you acquire be added into a copy of the existing persona

In either case, a handle to the resulting persona will be returned as specified by item code ACME$_PERSONA_HANDLE_OUT.

When a new persona is created, the ISS$_PRIMARY_EXTENSION designator indicates which persona extension representing the domain of interpretation was responsible for authenticating the user.

On a subsequent call $ACM will use that designator to guide processing of the ACME$M_DEFAULT_PRINCIPAL function modifier, for instance when there is an ACME$_FC_CHANGE_PASSWORD request.

ACME$_FC_CHANGE_PASSWORD

The ACME$_FC_CHANGE_PASSWORD function performs a password change operation. All aspects of the ACME$FC_CHANGE_PASSWORD function can also be performed as part of the ACME$_FC_AUTHENTICATE_PRINCIPAL function. Some degree of the ACME$_FC_AUTHENTICATE_PRINCIPAL function is also performed as part of ACME$_FC_CHANGE_PASSWORD to ensure the identity of the user changing the password. The primary and secondary passwords can be changed independently.

This function requires the ACME$_NEW_PASSWORD_FLAGS item code.

ACME$_FC_EVENT

The ACME$_FC_EVENT function provides a simple logging feature that can be used to generate certain events related to the policy of a domain of interpretation. To log an event, supply the desired "event type" item code followed by the appropriate "data" item codes pertaining to the "target" domain of interpretation.

To determine what event processing might be available, refer to the documentation provided by the vendors of the supporting ACME agents.

ACME$_FC_FREE_CONTEXT

The ACME$_FC_FREE_CONTEXT function is used to terminate iterative processing of a request. The address of the ACM communications buffer associated with the request must be specified using the context argument.

ACME$_FC_QUERY

The ACME$_FC_QUERY function provides a simple key-based query feature that can be used to obtain certain information related to the policy of a domain of interpretation. To look up an item of information, supply the desired "key" item code followed by the appropriate "data" item code.

To determine what query processing might be available, refer to the documentation provided by the vendors of the supporting ACME agents.

ACME$_FC_RELEASE_CREDENTIALS

The ACME$_FC_RELEASE_CREDENTIALS function removes credentials for a particular domain of interpretation from the specified persona. When the domain of interpretation is specified as "VMS", all non-native credentials are released and the persona is deleted. The "VMS" credentials cannot be removed from either the currently active or the process' natural persona. Thus, you cannot use the $ACM service to delete these personae.
Function Modifiers This section describes the various function modifiers for the function codes supported by the $ACM service.

Table SYS-11 indicates which Function Modifiers are applicable to the various Function Codes:

Table SYS-11 Function Codes and Function Modifiers
  Function Codes
Function Modifiers Authenticate Principal Change Password Event Free Context Query Release Credentials
ACME$M_ACQUIRE_CREDENTIALS IP          
ACME$M_COPY_PERSONA <>          
ACME$M_DEFAULT_PRINCIPAL <> <>        
ACME$M_FOREIGN_POLICY_HINTS SR          
ACME$M_MERGE_PERSONA <>          
ACME$M_NOAUDIT SR          
ACME$M_NOAUTHORIZATION SR          
ACME$M_OVERRIDE_MAPPING IR          
ACME$M_TIMEOUT            
ACME$M_UCS2_4 <> <> <>   <> <>

+Required
++Either ID or Name Required

Key to Codes
<> ---Permitted
IP---IMPERSONATE Privilege Required for the MAPPED _VMS _USERNAME to differ from the one current when the initial call to $ACM is made
IR---IMPERSONATE Privilege Required to override default values
SR---SECURITY Privilege Required

ACME$M_ACQUIRE_CREDENTIALS

The ACME$M_ACQUIRE_CREDENTIALS function modifier requests credentials be acquired during a successful authentication.

ACME$M_COPY_PERSONA

The ACME$M_COPY_PERSONA function modifier requests acquired credentials be attached to a copy of the persona specified with item code ACME$_PERSONA_HANDLE_IN.

ACME$M_DEFAULT_PRINCIPAL

The ACME$M_DEFAULT_PRINCIPAL specifies that the principal name and target domain of interpretation should be taken from the input persona, such as for changing the password of the logged-in user or reauthenticating the logged-in user.

ACME$M_FOREIGN_POLICY_HINTS

The ACME$M_FOREIGN_POLICY_HINTS function modifier indicates ACME agents should honor the ACME$M_NOAUDIT and ACME$M_NOAUTHORIZATION function modifiers for non-VMS domains of interpretation.

ACME$M_MERGE_PERSONA

The ACME$M_MERGE_PERSONA function modifier requests acquired credentials be attached to the persona specified with item code ACME$_PERSONA_HANDLE_IN.

ACME$M_NOAUDIT

The ACME$M_NOAUDIT function modifier indicates that auditing actions should not be performed. Unless the ACME$M_FOREIGN_POLICY_HINTS function modifier is also specified, this modifier applies only to the VMS domain of interpretation.

ACME$M_NOAUTHORIZATION

The ACME$M_NOAUTHORIZATION function modifier indicates authorization restrictions, such as the enforcement of modal constraints, should not apply. This provides a mechanism for performing pure authentication operations. Unless the ACME$M_FOREIGN_POLICY_HINTS function modifier is also specified, this modifier applies only to the VMS domain of interpretation.

ACME$M_OVERRIDE_MAPPING

The ACME$M_OVERRIDE_MAPPING function modifier allows for the acquisition of non-VMS credentials during a persona merge or copy operation. This occurs when an externally authorized principal name maps to an OpenVMS user name that differs from the user name associated with the native (VMS) credentials. By default, mixing credentials is prohibited.

ACME$M_TIMEOUT

The ACME$M_TIMEOUT modifier indicates that the caller requests timeout processing. The timeout interval is specified by the ACME$_TIMEOUT_INTERVAL item code.

Timeout processing is always enforced for non-privileged callers. Privileged callers (those running in exec mode or kernel mode or possessing SECURITY privilege) must explicitly specify ACME$M_TIMEOUT for timeout processing to be enforced.

ACME$M_UCS2_4

The ACME$M_UCS2_4 function modifier indicates item codes that specify string values use a 4-byte UCS-2 (Unicode) representation rather than 8-bit ASCII.

Item Code Encoding

Item codes are 16-bit unsigned values and are encoded as follows:


The item codes can be categorized in three different ways and are described as follows:

  • Common and ACME-specific Item Codes
    • Common item codes
      These item codes are defined for the $ACM system service itself and are available to all ACME agents.
    • ACME-specific item codes
      These item codes are defined separately for each ACME agent.
  • Input and Output Item Codes
    • Input item code
      Input item codes specify a buffer that contains information provided to $ACM. The buffer length and buffer address fields in the item descriptor must be nonzero; the return length field is ignored.
    • Output item code
      Output item codes specify a buffer in which $ACM is to return information. The buffer length and buffer address fields of the item descriptor must be nonzero; the return length field can be zero or nonzero.
  • Subject and Not Subject to Unicode Conversion
    • Subject to Unicode Conversion
      Text strings can be specified as Latin1 or 4-byte UCS-2 characters, depending on the setting of the ACME$M_UCS2_4 function modifier. An item code that is subject to Unicode conversion indicates it is a text item.
    • Not subject to Unicode Conversion
      Item codes that are not subject to Unicode conversion have a data format implied by the item code, and the nature of the data format must be explicitly understood by the programmer who calls $ACM.

See the Item Codes section for a description of the common item codes and their data formats.

Documentation of ACME-specific codes in general comes in the documentation from the vendor of each ACME agent.

For documentation of ACME-specific codes for the VMS ACME, see the VMS ACME-specific Item Codes section of this description. Common Item Codes This section describes the common item codes for the function codes supported by the $ACM service.

The item code space is partitioned into common items and ACME-specific items. ACME-specific items are used to request information that is unique to a particular domain of interpretation. The item codes described in this section fall into the common item code space.

Table SYS-12 indicates which Common Item Codes are applicable to the various Function Codes:

Table SYS-12 Function Codes and Common Item Codes
  Function Codes
Item Codes Authenticate Principal Change Password Event Free Context Query Release Credentials
ACME$_ACCESS_MODE <>          
ACME$_ACCESS_PORT (U) IR IR        
ACME$_AUTH_MECHANISM <>          
ACME$_AUTHENTICATING_DOI_ID (O) <> <>        
ACME$_AUTHENTICATING_DOI_NAME (U,O) <> <>        
ACME$_CHAIN <> <> <>   <> <>
ACME$_CHALLENGE_DATA IR          
ACME$_CONTEXT_ACME_ID (U) <> <>        
ACME$_CONTEXT_ACME_NAME <> <>        
ACME$_CREDENTIALS_NAME (U)           <>++
ACME$_CREDENTIALS_TYPE           <>++
ACME$_DIALOGUE_SUPPORT <> <>        
ACME$_EVENT_DATA_IN     <>      
ACME$_EVENT_DATA_OUT (O)     <>      
ACME$_EVENT_TYPE     <>      
ACME$_LOCALE (U) <> <>        
ACME$_LOGON_INFORMATION (O) <>          
ACME$_LOGON_TYPE IR          
ACME$_MAPPED_VMS_USERNAME (U,O) <> <>        
ACME$_MAPPING_ACME_ID (O) <> <>        
ACME$_MAPPING_ACME_NAME (U,O) <> <>        
ACME$_NEW_PASSWORD_1 (U) <> <>        
ACME$_NEW_PASSWORD_2 (U) <> <>        
ACME$_NEW_PASSWORD_FLAGS <> <>        
ACME$_NEW_PASSWORD_SYSTEM (U) SR SR        
ACME$_NULL <> <> <>   <> <>
ACME$_PASSWORD_1 (U) <> <>        
ACME$_PASSWORD_2 (U) <> <>        
ACME$_PASSWORD_SYSTEM (U) <> <>        
ACME$_PERSONA_HANDLE_IN <>          
ACME$_PERSONA_HANDLE_OUT (O) <>          
ACME$_PHASE_TRANSITION (O)            
ACME$_PRINCIPAL_NAME_IN (U) <> <>        
ACME$_PRINCIPAL_NAME_OUT (U,O) <> <>        
ACME$_QUERY_DATA (O)         <>+  
ACME$_QUERY_KEY_TYPE         <>+  
ACME$_QUERY_KEY_VALUE         <>+  
ACME$_QUERY_TYPE         <>+  
ACME$_REMOTE_HOST_ADDRESS IR IR        
ACME$_REMOTE_HOST_ADDRESS_TYPE IR IR        
ACME$_REMOTE_HOST_FULLNAME (U) IR IR        
ACME$_REMOTE_HOST_NAME (U) IR IR        
ACME$_REMOTE_USERNAME (U) IR IR        
ACME$_RESPONSE_DATA <>          
ACME$_SERVER_NAME_IN (U)       <>    
ACME$_SERVER_NAME_OUT (U,O)       <>    
ACME$_SERVICE_NAME (U) IR IR IR IR IR IR
ACME$_TARGET_DOI_ID <> <> <>++   <>++  
ACME$_TARGET_DOI_NAME (U) <> <> <>++   <>++  
ACME$_TIMEOUT_INTERVAL            

+Required
++Either ID or Name Required

Key to Codes
<> ---Permitted
IR---IMPERSONATE Privilege Required to override default values
SR---SECURITY Privilege Required
O---Output item code
U---Subject to Unicode Conversion

ACME$_ACCESS_MODE

The ACME$_ACCESS_MODE item code is an input item code. It specifies the access mode at which a new persona, resulting from credential acquisition processing, is to be created. The buffer must contain a longword value specifying the access mode.

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

PSL$C_KERNEL
PSL$C_EXEC
PSL$C_SUPER
PSL$C_USER

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 of the two access modes becomes the access mode at which the persona is created.

ACME$_ACCESS_PORT

The ACME$_ACCESS_PORT item code is an input item code. It specifies the name of local device (for example, a terminal) applicable to an authentication request. The buffer must contain a case-insensitive name string.

If not specified, $ACM passes the name string contained in the PCB$T_TERMINAL field of the process control block for the process, or, if that is empty, for the nearest ancestor process (if any) where the PCB$T_TERMINAL field is not empty.

ACME$_AUTH_MECHANISM

The ACME$_AUTH_MECHANISM item code is an input item code. It specifies the authentication mechanism applicable to an authentication request. The buffer must contain a longword value specifying the desired mechanism code. If not specified, the authenticating domain of interpretation applies its default mechanism.

The $ACMEDEF macro defines the following symbols for the standard mechanism types:

ACMEMECH$K_CHALLENGE_RESPONSE
ACMEMECH$K_PASSWORD

Individual ACME agents may define their own authentication mechanisms specific to their domain of interpretation.

ACME$_AUTHENTICATING_DOI_ID

The ACME$_AUTHENTICATING_DOI_ID item code is an output item code. It specifies the buffer to receive the agent ID of the domain of interpretation that successfully authenticated the principal.

ACME$_AUTHENTICATING_DOI_NAME

The ACME$_AUTHENTICATING_DOI_NAME item code is an output item code. It specifies the buffer to receive the name of the domain of interpretation that successfully authenticated the principal.

The maximum data returned for this item code is the number of characters represented by the symbol, ACME$K_MAXCHAR_DOI_NAME, so a caller's buffer should be at least that long, with the number of bytes allocated dependent on whether the ACME$M_UCS2_4 function code modifier was specified on the call to $ACM[W].

ACME$_CHAIN

The ACME$_CHAIN item code is an input item code. It specifies the address of the next item list segment to process immediately after processing the current list segment.

The buffer address field in the item descriptor specifies the address of the next item list segment to be processed. The ACME$_CHAIN item code must be last in the item list segment; $ACM treats this as the logical end of the current item list segment. Any item list entries following the ACME$_CHAIN item code are ignored.

On the Alpha platform, both 32-bit and 64-bit item lists can be chained together.

ACME$_CHALLENGE_DATA

The ACME$_CHALLENGE_DATA item code is an input item code. It specifies the challenge data that was used as the basis for generating the response data specified by the ACME$_RESPONSE_DATA item code. The meaning of this data is specific to the domain of interpretation for which it is used.

If this item code is specified, the ACME$_AUTH_MECHANISM and ACME$_RESPONSE_DATA item codes must also be specified. (The VMS domain of interpretation does not support this mechanism type.)

ACME$_CONTEXT_ACME_ID

The ACME$_CONTEXT_ACME_ID item code is an input item code. It establishes the ACME agent context within which ACME-specific item codes are interpreted. This item code has an effect on the parsing of the list of ACME-specific item codes, and takes effect immediately. It is in effect until the next instance of code ACME$_CONTEXT_ACME_ID, code ACME$_CONTEXT_ACME_NAME, code ACME$_TARGET_DOI_ID, or code ACME$_TARGET_DOI_NAME. The buffer must contain a longword value specifying the agent ID of an ACME agent.

ACME$_CONTEXT_ACME_NAME

The ACME$_CONTEXT_ACME_NAME item code is an input item code. It establishes the ACME agent context within which ACME-specific item codes are interpreted. This item code has an effect on the parsing of the list of ACME-specific item codes, and takes effect immediately. It is in effect until the next instance of code ACME$_CONTEXT_ACME_ID, code ACME$_CONTEXT_ACME_NAME, code ACME_TARGET_DOI_ID, or code ACME$_TARGET_DOI_NAME. The buffer must contain the case-insensitive name string of an ACME agent.

ACME$_CREDENTIALS_NAME

The ACME$_CREDENTIALS_NAME item code is an input item code. It specifies the name of the persona extension holding the set of credentials upon which to operate. The buffer must contain the case-insensitive name string of a persona extension that has been registered on the system.

ACME$_CREDENTIALS_TYPE

The ACME$_CREDENTIALS_TYPE item code is an input item code. It specifies the extension ID of the persona extension holding the set of credentials upon which to operate. The buffer must contain a longword value specifying the extension ID of a persona extension that has been registered on the system.

ACME$_DIALOGUE_SUPPORT

The ACME$_DIALOGUE_SUPPORT item code is an input item code. It specifies which dialogue mode features are supported by the caller. The buffer must contain a longword bit vector of applicable flags.

The $ACMEDEF macros defines the following symbols for the valid flags:

ACMEDLOGFLG$V_INPUT---character string input/output capabilities
ACMEDLOGFLG$V_NOECHO---"no echo" input capabilities

These are the same as those for the ACMEIS$L_FLAGS field on an item set entry. See the description of the context argument for further information.

Specify the ACME$_DIALOGUE_SUPPORT item code to indicate the interactive capabilities of the user interface. If the caller is unable to support features necessary to complete a given request, the request ultimately fails. The caller receives a condition value ACME$_INSFDIALSUPPORT for insufficient dialogue support.

ACME$_EVENT_DATA_IN

The ACME$_EVENT_DATA_IN item code is an input item code. It specifies the buffer containing information applicable to an event operation.

The meaning of this data is specific to the domain of interpretation for which it is used.

ACME$_EVENT_DATA_OUT

The ACME$_EVENT_DATA_OUT item code is an output item code. It specifies the buffer to receive information returned from an event operation.

The meaning of this data is specific to the domain of interpretation for which it is used.

ACME$_EVENT_TYPE

The ACME$_EVENT_TYPE item code is an input item code. It specifies the type of event being reported. The buffer must contain a longword value. Interpretation of the value is specific to the domain of interpretation to which the event is being reported.

ACME$_LOCALE

The ACME$_LOCALE item code is an input item code. It specifies the collection of data and rules applicable to a language and culture. The buffer must contain a name string that reflects a locale supported by the system.

The buffer must contain a string in the following case-insensitive syntax:

language-country

language is a 2-letter language code (ISO 639)
country is a 2-letter country code (ISO 3166)

The default is EN-US, and cannot be overridden by the specified locale. Locale information may be interpreted by ACME agents to determine country and language requirements.

ACME$_LOGON_INFORMATION

The ACME$_LOGON_INFORMATION item code is an output item code. It specifies the buffer to receive an ACM logon information structure, which contains statistics pertaining to the authenticated principal name within the contexts of the authenticating and native (VMS) domains of interpretation.

The size of the buffer must be sufficient to handle data from whatever VMS versions are used, as described in the ACME$_LOGON_INFORMATION structure found in the OpenVMS Programming Concepts Manual.

The following diagram depicts the overall format of an ACM logon information structure:


The following table defines the ACM logon information structure header fields:

Descriptor Field Definition
ACMELI$PQ_LOGON_INFO_DOI64 In this situation, a quadword containing the 64-bit address of the structure segment containing logon information relating to the authenticating domain of interpretation.

When the ACM logon information structure resides in 32-bit address space, ACMELI$PQ_LOGON_INFO_DOI64 contains the sign-extended 32-bit address of the structure segment. The field can be referenced as a 32-bit signed pointer using ACMELI$PS_LOGON_INFO_DOI32.

ACMELI$W_SIZE A word containing the size of the ACM logon information structure.
ACMELI$W_REVISION_LEVEL A word containing a value that identifies the revision level of the ACM logon information structure.
ACMELI$L_LOGON_FLAGS Specifies the structure ACMELGIFLG$TYPE, used by LOGINOUT to populate the longword returned by the item code JPI$_LOGIN_FLAGS when calling the SYS$GETJPI[W] system service. This provides the client with information regarding what took place during authentication. The ACM Dispatcher manages this item, sending back to the client the merge of all the output it receives from ACMEs by calls to the ACME$CB_SET_LOGIN_FLAG. Refer to the OpenVMS Programming Concepts Manual for the information that is received.
ACMELI$PQ_LOGON_INFO_VMS64 In this situation, a quadword containing the 64-bit address of the structure segment containing logon information about the native (VMS) domain of interpretation.

When the ACM logon information structure resides in 32-bit address space, ACMELI$PQ_LOGON_INFO_VMS64 contains the sign-extended 32-bit address of the structure segment. The field can be referenced as a 32-bit signed pointer using ACMELI$PS_LOGON_INFO_VMS32.

The following diagram depicts the format of the ACM logon structure segment containing information about the VMS domain of interpretation:


The following table defines the fields for the ACM logon structure segment containing logon information about the native (VMS) domain of interpretation:

Descriptor Field Definition
ACMELIVMS$L_ACME_ID A longword containing the agent ID of the ACME agent that reported logon information for the native (VMS) domain of interpretation. If this field is zero, the rest of the structure segment is invalid.
ACMELIVMS$L_PHASE Indicates the ACME Execution Phase during which this value was provided. ACME Execution Phase numbers are subject to change, so this field is mainly for use by programmers to debug an ACME agent.
ACMELIVMS$W_SIZE A word containing the size of the ACM logon information structure segment.
ACMELIVMS$W_REVISION_LEVEL A word containing a value that identifies the revision level of the ACM logon information structure segment.
ACMELIVMS$L_LOGFAIL_COUNT A longword containing the number of failed logon attempts with respect to the VMS domain of interpretation.
ACMELIVMS$O_LOGON_INT An octaword containing the date and time in UTC format of the last interactive logon with respect to the VMS domain of interpretation. If the contents of the octaword are zero, no previous non-interactive logon with respect to the VMS domain of interpretation was recorded.
ACMELIVMS$O_LOGON_NONINT An octaword containing the date and time in UTC format of the last noninteractive logon with respect to the VMS domain of interpretation. If the contents of the octaword are zero, no previous non-interactive logon with respect to the VMS domain of interpretation was recorded.

The following diagram depicts the format of the ACM logon structure segment containing information about the authenticating domain of interpretation:


The following table defines the fields for the ACM logon structure segment containing logon information about the authenticating domain of interpretation:

Descriptor Field Definition
ACMELIDOI$L_ACME_ID A longword containing the agent ID of the ACME agent that reported logon information about the non-native authenticating domain of interpretation. If this field is zero, the rest of the structure segment is invalid.

If the contents of the longword are zero, the principal was authenticated for the VMS domain of interpretation.

ACMELIDOI$L_PHASE Indicates the ACME Execution Phase during which this value was provided. ACME Execution Phase numbers are subject to change, so this field is mainly for use by programmers to debug an ACME agent.
ACMELIDOI$W_SIZE A word containing the size of the ACM logon information structure segment.
ACMELIDOI$W_REVISION_LEVEL A word containing a value that identifies the revision level of the ACM logon information structure segment.
ACMELIDOI$L_LOGFAIL_COUNT A longword containing the number of failed logon attempts with respect to the non-native authenticating domain of interpretation.
ACMELIDOI$O_LOGON An octaword containing the date and time in UTC format of the last logon with respect to the non-native authenticating domain of interpretation.

If the contents of the octaword are zero, no previous logon with respect to the domain of interpretation was recorded.

ACMELIDOI$O_LOGON_INT An octaword containing the date and time in UTC format of the last interactive logon with respect to the non-native authenticating domain of interpretation.

If the contents of the octaword are zero, no previous interactive logon with respect to the domain of interpretation was recorded.

ACMELIDOI$O_LOGON_NONINT An octaword containing the date and time in UTC format of the last noninteractive logon with respect to the non-native authenticating domain of interpretation. If the contents of the octaword are zero, no previous non-interactive logon with respect to the domain of interpretation was recorded.
ACMELIDOI$O_LOGFAIL An octaword containing the date and time in UTC format of the last logon failure with respect to the non-native authenticating domain of interpretation.

If the contents of the octaword are zero, no previous logon failure with respect to the domain of interpretation was recorded.

ACMELIDOI$O_LOGFAIL_INT An octaword containing the date and time in UTC format of the last interactive logon failure with respect to the non-native authenticating domain of interpretation. If the contents of the octaword are zero, no previous interactive logon failure with respect to the domain of interpretation was recorded.
ACMELIDOI$O_LOGFAIL_NONINT An octaword containing the date and time in UTC format of the last noninteractive logon failure with respect to the non-native authenticating domain of interpretation. If the contents of the octaword are zero, no previous non-interactive logon failure with respect to the domain of interpretation was recorded.

ACME$_LOGON_TYPE

The ACME$_LOGON_TYPE item code is an input item code. It specifies the type of logon being performed. The buffer must contain a longword value specifying a valid type. If not specified, the value defaults to the logon type of the calling process.

The $ACMEDEF macro defines the following symbols for the valid logon types:

ACME$K_DIALUP
ACME$K_LOCAL
ACME$K_REMOTE
ACME$K_BATCH
ACME$K_NETWORK

The values ACME$K_BATCH and zero (0) for batch and detached processes, respectively, are reserved to LOGINOUT.EXE. If either of these values is defaulted or specified by non-LOGINOUT clients, the service returns ACME$_INVREQUEST.

ACME$_MAPPED_VMS_USERNAME

The ACME$_MAPPED_VMS_USERNAME item code is an output item code. It specifies the buffer to receive the name of the local OpenVMS user name to which the principal name was mapped.

The maximum data returned for this item code is the number of characters represented by the symbol, ACMEVMS$S_MAX_VMS_USERNAME, so a caller's buffer should be at least that long, with the number of bytes allocated dependent on whether the ACME$M_UCS2_4 function code modifier was specified on the call to $ACM[W].

ACME$_MAPPING_ACME_ID

The ACME$_MAPPING_ACME_ID item code is an output item code. It specifies the buffer to receive the agent ID of the ACME agent that successfully mapped the principal name to an OpenVMS user name. The buffer descriptor must specify a longword.

ACME$_MAPPING_ACME_NAME

The ACME$_MAPPING_ACME_NAME item code is an output item code. It specifies the buffer to receive the name of the ACME agent that successfully mapped the principal name to an OpenVMS user name.

Data returned for this item code is the number of characters represented by the symbol, ACME$K_MAXCHAR_DOI_NAME, so a caller's buffer should be at least that long, with the number of bytes allocated dependent on whether the ACME$M_UCS2_4 function code modifier was specified on the call to $ACM[W].

ACME$_NEW_PASSWORD_1

The ACME$_NEW_PASSWORD_1 item code is an input item code. It specifies the new primary password for a password change operation. The buffer must contain a password string. The case of this string will be preserved in delivery to ACME agents. Each ACME agent has its own policy regarding whether password strings are treated in a case sensitive or a case-insensitive manner.

This item code might be requested in a dialogue step.

ACME$_NEW_PASSWORD_2

The ACME$_NEW_PASSWORD_2 item code is an input item code. It specifies the new secondary password for a password change operation. The buffer must contain a password string. The case of this string will be preserved in delivery to ACME agents. Each ACME agent has its own policy regarding whether password strings are treated in a case sensitive or a case-insensitive manner.

This item code might be requested in a dialogue step.

ACME$_NEW_PASSWORD_FLAGS

The ACME$_NEW_PASSWORD_FLAGS item code is an input item code. It requests which passwords should be explicitly updated. The buffer must contain a longword bit vector of applicable flags.

The $ACMEDEF macros defines the following symbols for the valid flags:

ACMEPWDFLG$V_SYSTEM
ACMEPWDFLG$V_PASSWORD_1
ACMEPWDFLG$V_PASSWORD_2

ACME$_NEW_PASSWORD_SYSTEM

The ACME$_NEW_PASSWORD_SYSTEM item code is an input item code. It specifies the new system password for a password change operation. The buffer must contain a case-insensitive password string.

This item code might be requested in a dialogue step.

ACME$_NULL

The ACME$_NULL item code indicates that the current item list entry should be ignored.

ACME$_PASSWORD_1

The ACME$_PASSWORD_1 item code is an input item code. It specifies the primary password applicable to the requested operation. The buffer must contain a password string. The case of this string will be preserved in delivery to ACME agents. Each ACME agent has its own policy regarding whether password strings are treated in a case sensitive or a case-insensitive manner.

This item code might be requested in a dialogue step.

ACME$_PASSWORD_2

The ACME$_PASSWORD_2 item code is an input item code. It specifies the secondary password applicable to the requested operation. The buffer must contain a password string. The case of this string will be preserved in delivery to ACME agents. Each ACME agent has its own policy regarding whether password strings are treated in a case sensitive or a case-insensitive manner.

This item code might be requested in a dialogue step.

ACME$_PASSWORD_SYSTEM

The ACME$_PASSWORD_SYSTEM item code is an input item code. It specifies the system password applicable to the requested operation. The buffer must contain a case-insensitive password string.

This item code might be requested in a dialogue step.

ACME$_PERSONA_HANDLE_IN

The ACME$_PERSONA_HANDLE_IN item code is an input item code. It specifies the persona to use as the basis for credential acquisition processing. The buffer must contain a longword value specifying a persona ID of an existing persona.

ACME$_PERSONA_HANDLE_OUT

The ACME$_PERSONA_HANDLE_OUT item code is an output item code. It specifies a buffer to receive the persona ID of the persona created or acted upon by credential acquisition processing. The buffer descriptor must specify a longword.

If no ACME$_PERSONA_HANDLE_OUT item is specified but function modifier ACME$M_ACQUIRE_CREDENTIALS is specified, a persona that is created can be located with the $PERSONA_FIND system service.

ACME$_PHASE_TRANSITION

The ACME$_PHASE_TRANSITION is used by LOGINOUT to convey synchronization information to the VMS ACME for support of backward compatible interfaces for LGI-callouts and DECwindows login.

Use of this item code is reserved to HP.

ACME$_PRINCIPAL_NAME_IN

The ACME$_PRINCIPAL_NAME_IN item code is an input item code. It specifies the name of the entity that is subject to authentication within the domain of interpretation to which it belongs. The buffer must contain a name string.

This item code might be requested in a dialogue step.

ACME$_PRINCIPAL_NAME_OUT

The ACME$_PRINCIPAL_NAME_OUT item code is an output item code. It specifies the buffer to receive the name of the entity that was authenticated by the authenticating domain of interpretation. This item code is useful when the principal name is not explicitly provided, such as during autologon style processing during which an ACME agent provides the principal name.

The maximum data returned for this item code is the number of characters represented by the symbol, ACME$K_MAXCHAR_PRINCIPAL_NAME, so a caller's buffer should be at least that long, with the number of bytes allocated dependent on whether the ACME$M_UCS2_4 function code modifier was specified on the call to $ACM[W].

ACME$_QUERY_DATA

The ACME$_QUERY_DATA item code is an output item code. It specifies the buffer to receive the data returned from the query operation relating to the corresponding ACME$_QUERY_TYPE item code.

The ACME$_QUERY_DATA item code requires that an ACME$_QUERY_TYPE item code immediately precede it in the item list.

ACME$_QUERY_KEY_TYPE

The ACME$_QUERY_KEY_TYPE item code is an input item code. It specifies the key type for establishing the context of a query operation. The key format is specific to the ACME agent to which the call is directed.

An ACME$_QUERY_KEY_TYPE item requires an ACME$_QUERY_KEY_VALUE item immediately following it in the item list.

ACME$_QUERY_KEY_VALUE

The ACME$_QUERY_KEY_VALUE item code is an input item code. It specifies the key data for establishing the context of a query operation.

An ACME$_QUERY_KEY_VALUE item requires that an ACME$_QUERY_KEY_TYPE item immediately precede it in the item list.

ACME$_QUERY_TYPE

The ACME$_QUERY_TYPE item code is an input item code. It specifies the data to be returned in the buffer described by the corresponding ACME$_QUERY_DATA item code.

The ACME$_QUERY_TYPE item code requires that an ACME$_QUERY_DATA item code immediately follow it in the item list.

ACME$_REMOTE_HOST_ADDRESS

The ACME$_REMOTE_HOST_ADDRESS item code is an input item code. It specifies the network address of the system from which the request originated. The buffer must contain a network address using the representation consistent with ACME$_REMOTE_HOST_ADDRESS_TYPE item code is specified.

ACME$_REMOTE_HOST_ADDRESS_TYPE

The ACME$_REMOTE_HOST_ADDRESS_TYPE item code is an input item code that specifies the representation of the ACME$_REMOTE_HOST_ADDRESS item code. The buffer must contain a longword value specifying the address type.

The $ACMEDEF macro defines the following symbols for the standard address types:

Symbol Meaning
ACMEHAT$K_DECNET_IV DECnet Phase IV
ACMEHAT$K_DECNET_OSI DECnet OSI
ACMEHAT$K_IP_V4 Internet Protocol V4
ACMEHAT$K_IP_V6 Internet Protocol V6

ACME$_REMOTE_HOST_FULLNAME

The ACME$_REMOTE_HOST_FULLNAME item code is an input item code. It specifies the fully expanded name of the remote system from which the request originated. The buffer must contain a name string.

ACME$_REMOTE_HOST_NAME

The ACME$_REMOTE_HOST_NAME item code is an input item code. It specifies the name of the remote system from which the request originated. The buffer must contain a name string.

ACME$_REMOTE_USERNAME

The ACME$_REMOTE_USERNAME item code is an input item code. It specifies the name of the remote user on whose behalf the request is being initiated. The buffer must contain a name string.

ACME$_RESPONSE_DATA

The ACME$_RESPONSE_DATA item code is an input item code. It specifies the response data that was calculated using the challenge data.

Interpretation of this data is specific to a domain of interpretation. This item code may be requested in a dialogue step.

ACME$_SERVER_NAME_IN

Specifies the Event Server to which an Event should be directed. The meaning of this item is specific to the target domain of interpretation.

ACME$_SERVER_NAME_OUT

Reports the Event Server to which an Event was directed. The meaning of this item is specific to the target domain of interpretation.

ACME$_SERVICE_NAME

Indicates the client program making the call to $ACM. The buffer must contain the case-insensitive service name string. The default value is the current image name if the client program is an installed image.

Names beginning with x- are reserved for local use.

ACME$_TARGET_DOI_ID

Establishes the domain of interpretation within which nonquery operations are performed and the context within which ACME-specific items codes are interpreted.

This item code also has an effect on the parsing of the list of ACME-specific item codes and takes effect immediately. It is in effect until the next instance of code ACME$_CONTEXT_ACME_ID, code ACME$_CONTEXT_ACME_NAME, code ACME$_TARGET_DOI_ID, or code ACME$_TARGET_DOI_NAME. It also specifies which ACME is to be responsible for the authentication.

The buffer must contain a longword value specifying the agent ID of a domain of interpretation.

ACME$_TARGET_DOI_NAME

Establishes the domain of interpretation within which nonquery operations are performed and the context within which ACME-specific item codes are interpreted.

This item code also has an effect on the parsing of the list of ACME-specific item codes, and takes effect immediately. It is in effect until the next instance of code ACME$_CONTEXT_ACME_ID, code ACME$_CONTEXT_ACME_NAME, code ACME$_TARGET_DOI_ID, or code ACME$_TARGET_DOI_NAME. It also specifies which ACME is to be responsible for the authentication.

The buffer must contain the case-insensitive name string of a domain of interpretation.

ACME$_TIMEOUT_INTERVAL

Specifies the number of seconds that must elapse before the current request times out. (See the ACME$M_TIMEOUT function modifier.)

Timeout interval values are specified in seconds and must be between 1 and 300 seconds. If an invalid value is specified, the service returns SS$_IVTIME.

The default timeout interval is 30 seconds. This value may be adjusted by defining the exec mode logical name ACME$TIMEOUT_DEFAULT in the LNM$SYSTEM_TABLE logical name table. This timeout is enforced for non-dialogue requests and for the first request in a sequence of dialogue calls. The default value for subsequent dialogue requests can be adjusted by defining the exec mode logical name ACME$DIALOGUE_TIMEOUT_DEFAULT in the LNM$SYSTEM_TABLE logical name table.

Unprivileged clients can specify only timeout interval values less than or equal to the default value. Values greater than the default are ignored. Output Message Categories This section describes the various output message categories supported by the $ACM service.

Message Types are 16-bit unsigned values, encoded as follows:


Function-Independent Common Output Message Categories

The following table lists the function-independent common output messages and their meanings:

Message Category Meaning
ACMEMC$K_GENERAL Specifies a general text message
ACMEMC$K_HEADER Specifies a header text message
ACMEMC$K_TRAILER Specifies a trailer text message
ACMEMC$K_SELECTION Specifies an acceptable choices message
ACMEMC$K_DIALOGUE_ALERT Specifies an advisory alert message

Authentication Common Output Message Categories

The following table lists the authentication common output message categories and their meanings:

Message Category Meaning
ACMEMC$K_SYSTEM_IDENTIFICATION Specifies system identification text messages
ACMEMC$K_SYSTEM_NOTICES Specifies system notices
ACMEMC$K_WELCOME_NOTICES Specifies welcome notices
ACMEMC$K_LOGON_NOTICES Specifies logon notices
ACMEMC$K_PASSWORD_NOTICES Specifies password notices
ACMEMC$K_MAIL_NOTICES Specifies MAIL notices

Description

The Authentication and Credential Management ($ACM) service presents a unified interface for performing authentication-related operations in a manner independent of applicable policy.

On a given OpenVMS system, multiple authentication policies may be applicable. The system may be configured to augment the native (local OpenVMS) policy with alternatives pertaining to external environments, such as LAN Manager. Each policy, together with the operating environment to which it pertains, constitutes a domain of interpretation. Within a given domain, any entity, such as a user, that is subject to the applicable authentication policy, is referred to as a principal.

The $ACM service can be used to authenticate a principal, initiate a password change request on behalf of a principal, query information about a particular domain, or report event data within a particular domain.

The $ACM service completes asynchronously; that is, it returns to the caller after queuing the request, without waiting for the operation to complete.

To synchronize completion of an operation, use the Authentication and Credential Management and Wait ($ACMW) service. The $ACMW service is identical to $ACM in every way except that $ACMW returns to the caller after the operation has completed.

Modes of Operation

The typical authentication policy employs the traditional reusable password; however, various alternative mechanisms exist for forming stronger policies. Some of these mechanisms, such as challenge-response, require interaction. The $ACM service is designed to accommodate these mechanisms.

The authentication and change_password functions are capable of operating in a dialogue (iterative) mode to support different types of interactive authentication mechanisms. The query, event, and free_context functions only support the nondialogue (noniterative) mode of operation.

Nondialogue (Noniterative) Mode

The default nature of the $ACM service is to operate in a noniterative mode. All information needed to complete the request must be provided in a single call; otherwise, the request ultimately fails. This requires the caller to know beforehand what information is required to complete the request.

The following list summarizes the control flow for a typical nondialogue mode authentication request. For simplicity, the scenario assumes a single domain of interpretation with a traditional user name and password policy. Also, error processing is ignored.

  1. The caller of $ACM prompts the user for the principal name and password, builds an item list specifying the principal name and password, and then calls $ACM specifying the authenticate principal function, the item list with the principal name and password, and a zero address for the context argument.
  2. $ACM processes the request and ultimately returns control to the caller with the final status for the operation.

Dialogue (Iterative) Mode

The caller can use the interactive capabilities of the $ACM service for authentication and password change operations by specifying the ACME$_DIALOGUE_SUPPORT item code and a valid context argument. In this mode, ACME agents can request additional information from the caller to complete the request. In effect, the $ACM service is called in an iterative fashion until all information required to complete the request has been provided. The sequence of calls are linked together by passing the context argument returned in one call back in the next call.

In this scenario, when an ACME agent requires additional information, it builds an item set that describes the nature of the information. The item set is passed back to the caller in the communications buffer (see the description for the context argument regarding the format of the communications buffer) and the service returns with the ACME$_OPINCOMPL status. The caller processes each item set entry, gathers the requested information, and then passes it back to the ACME agent using the itmlst argument in the next call. The sequence continues until the call returns with a status code other than ACME$_OPINCOMPL.

The following list summarizes the control flow for a typical dialogue-mode authentication sequence. For simplicity, the scenario assumes a single domain of interpretation with a traditional user name and password policy. Also, error processing is ignored.

  1. Make an initial call to $ACM specifying the authenticate principal function code, an item list that merely contains the ACME$_DIALOGUE_SUPPORT item code, and a context argument that has been initialized to -1.
  2. $ACM builds a communications buffer containing an item set in the buffer requesting the principal name (user name), sets the context argument to reference the buffer, and returns control to the caller with a status code of ACME$_OPINCOMPL.
  3. The caller processes the item set, prompts for the principal name, builds an item list specifying the principal name, and then calls $ACM again specifying the authenticate principal function as before, the item list with the principal name, and a context argument that contains the buffer address returned in the previous call.
  4. $ACM validates the context argument, processes the username then builds another communications buffer to contain an item set list requesting the password, sets the context argument to reference the buffer, and returns control to the caller again with a status code of ACME$_OPINCOMPL.
  5. The caller processes the item set, prompts for the password, builds an item list specifying the password, and then calls $ACM again specifying the authenticate principal functions as before, the item list with the password, and a context argument that contains the buffer address returned in the previous call.
  6. $ACM validates the context argument again, clears it, and then completes the processing of the request, now that it has all the necessary information, and ultimately returns control to the caller with the final status for the operation.

Unprivileged callers (those running in user mode and not possessing SECURITY privilege) are limited by the number of iterative requests they can make in a dialogue sequence of calls. The default is set at 26 dialogue requests. The default can be overridden by defining the exec mode logical name ACME$DIALOGUE_ITERATIVE_LIMIT in the LNM$SYSTEM_TABLE logical name table. Valid values are 1 through 100.

Determining an ACME Name Based on an ACME ID

The identity of the ACME that supplied the ACME$L_ACME_STATUS contents is indicated in the ACMEID$V_ACME_NUM subfield of the ACMESB$L_ACME_ID field. This value is consistent for the duration of one boot of the system, but may have a different value on the next boot. The name of a particular ACME agent can be determined from the ACME ID by calling $ACM with function code ACME$_FC_QUERY and the following item list entries:

  • Special ACM Dispatch query---ID value zero:
    ITMCOD = ACME$_TARGET_DOI_ID
    BUFSIZ = 4
    BUFADR = Address of longword containing 0
  • Query ACME name based on ACME ID:
    ITMCOD = ACME$_QUERY_KEY_TYPE
    BUFSIZ = 4
    BUFADR = Address of longword containing ACME$K_QUERY_ACME_ID
  • Specify ACME ID value:
    ITMCOD = ACME$_QUERY_KEY_VALUE
    BUFSIZ = 4
    BUFADR = Address of longword containing the ACME_ID
  • Specify ACME name for the return value:
    ITMCOD = ACME$_QUERY_TYPE
    BUFSIZ = 4
    BUFADR = Address of longword containing ACME$K_QUERY_ACME_NAME
  • Specify the output buffer:
    ITMCOD = ACME$_QUERY_DATA
    BUFSIZ = ACME$K_MAXCHAR_DOI_NAME or (ACME$K_MAXCHAR_DOI_NAME*4) depending on whether function modifier ACME$M_UCS2_4 has been specified
    BUFADR = Address of buffer large enough to hold ACME$K_MAXCHAR_DOI_NAME bytes or (ACME$K_MAXCHAR_DOI_NAME*4) depending on whether function modifier ACME$M_UCS2_4 has been specified

Privileges and Restrictions

The $ACM service constitutes a trusted interface. It restricts operations that override the security policy applicable to a given domain of interpretation to those callers who are suitably privileged. The status returned in the ACMESB$L_STATUS field of the ACM Status Block for a failed authentication operation is typically nonspecific, so as not to reveal sensitive information to untrusted callers.

If the caller has the SECURITY privilege, the ACMESB$L_SECONDARY_STATUS field of the ACM Status Block may contain a detailed status that more accurately reflects the actual nature of the failure.

To specify the following function modifiers, the caller must have the SECURITY privilege:

ACME$M_NOAUDIT
ACME$M_NOAUTHORIZATION
ACME$M_FOREIGN_POLICY_HINTS

To specify the following function modifier, the caller must have the IMPERSONATE privilege:

ACME$M_OVERRIDE_MAPPING

To specify the following item code, the caller must have the SECURITY privilege:

ACME$_NEW_PASSWORD_SYSTEM

To specify the following item codes, the caller must have the IMPERSONATE privilege:

ACME$_ACCESS_PORT
ACME$_CHALLENGE_DATA
ACME$_REMOTE_HOST_ADDRESS
ACME$_REMOTE_HOST_ADDRESS_TYPE
ACME$_REMOTE_HOST_FULLNAME
ACME$_REMOTE_HOST_NAME
ACME$_REMOTE_USERNAME
ACME$_SERVICE_NAME

Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The item list or an input buffer cannot be read in the access mode of the caller; or an output buffer, a return length buffer, or the I/O status block cannot be written in the access mode of the caller.
SS$_ARG_GTR_32_BITS A 64-bit address was passed in a context requiring a 32-bit address.
SS$_BADBUFADR The buffer address associated with an entry in the item list is inappropriate in the context of the call. The address may be invalid (for example, 0).
SS$_BADBUFLEN The buffer length associated with an entry in the item list is inappropriate in the context of the call. The length may be invalid (for example, 0) or outside the range of acceptable values.
SS$_BADCHAIN A chained item list is inaccessible, or the chain is circular.
SS$_BADCONTEXT The context argument does not specify a valid context buffer.
SS$_BADITMCOD A specified item code is invalid or out-of-range.
SS$_BADPARAM The item list contains an invalid item code.
SS$_BADRETLEN The return length address associated with an entry in the item list is inappropriate in the context of the call. The address may be invalid (for example, 0).
SS$_EXASTLM The astadr argument was specified and the process has exceeded its ASTLM quota.
SS$_EXQUOTA A process quota was exceeded.
SS$_ILLEFC The efn argument specifies an illegal event flag number.
SS$_ILLMODIFIER The func argument specifies function modifiers that are inappropriate in the context of the call.
SS$_INSFMEM Insufficient space exists for completing the request.
SS$_IVTIME An invalid value was specified for the ACME$_TIMEOUT_INTERVAL item code.
SS$_NOEXTAUTH External authentication is not available.
SS$_NOPRIV The caller does not have the necessary privileges to complete the requested operation.
SS$_TOOMUCHDATA The request size exceeds $ACM messaging constraints.
SS$_UNASEFC The efn argument specifies an unassociated event flag cluster.
SS$_UNSUPPORTED The func argument specifies an unsupported function.

Condition Values Returned in the ACM Status Block

ACME$_NORMAL The service completed successfully.
ACME$_ACCOUNTLOCK The account associated with specified principal name is disabled.
ACME$_AUTHFAILURE Authorization failed.
ACME$_BUFFEROVF An output item returned by the service is larger than the user buffer provided to receive the item; the item is truncated.
ACME$_DOIUNAVAILABLE The specified domain of interpretation is not processing requests.
ACME$_INCONSTATE The ACME server detected an internal consistency error.
ACME$_INSFDIALSUPPORT Caller dialogue capabilities specified with the ACME$DIALOGUE_SUPPORT item code are inadequate to meet the needs of one or more ACME agents.
ACME$_INTRUDER A record matching the request was found in the intrusion database.
ACME$_INVALIDCTX The context argument is not consistent with the itmlst argument.
ACME$_INVALIDPWD The specified password is invalid.
ACME$_INVITMSEQ The service encountered a query type or query key item code without a corresponding query data or query key value item code.
ACME$_INVMAPPING The OpenVMS user name to which the principal name was mapped is invalid.
ACME$_INVNEWPWD The new password provided during a change password request does not pass qualification checks.
ACME$_INVPERSONA The persona handle specified by the itmlst argument is invalid.
ACME$_INVREQUEST A parameter is invalid in the context of the request. This error code is returned when the caller either defaults or specifies ACME$_BATCH or the value zero (0) for ACME$_LOGON_TYPE.
ACME$_MAPCONFLICT An attempt was made to merge credentials for a principal name, which maps to an OpenVMS user name that differs from the one associated with existing credentials.
ACME$_NOACMECTX The service encountered an ACME-specific item code when no ACME context had been established.
ACME$_NOCREDENTIALS The ACME agent did not issue any credentials.
ACME$_NOEXTAUTH The specified principal name cannot be authenticated externally.
ACME$_NOPRIV The caller does not have the necessary privileges to complete the requested operation.
ACME$_NOSUCHDOI The specified domain of interpretation does not exist.
ACME$_NOSUCHUSER The specified principal name does not exist.
ACME$_NOTARGETCRED The persona does not contain credentials for the specified domain of interpretation.
ACME$_NOTAUTHORIZED Authorization failed due to account restrictions.
ACME$_OPINCOMPL Interaction is required to complete the request. The context buffer contains information describing how to proceed.
ACME$_PWDEXPIRED The password provided during an authentication request has expired and a new password is required to complete the request.
ACME$_TIMEOUT The server did not respond within the designated time-out interval.
ACME$_UNSUPPORTED The requested operation or an item code is not supported with the selected domain of interpretation.
Status Codes and Function Codes Table

Table SYS-13 lists status codes and their function codes:

Table SYS-13 Status Codes and Function Codes
  Function Codes
Status Codes Authenticate Principal Change Password Event Free Context Query Release Credentials
ACME$_ACCOUNTLOCK <> <>        
ACME$_AUTHFAILURE <> <>        
ACME$_BUFFEROVR <> <>        
ACME$_DOIUNAVAILABLE <> <> <> <>    
ACME$_INCONSTATE <> <> <> <> <> <>
ACME$_INSFDIALSUPPORT <> <>        
ACME$_INTRUDER <>          
ACME$_INVALIDCTX <> <> <>      
ACME$_INVALIDPWD <> <>        
ACME$_INVITMSEQ         <>  
ACME$_INVMAPPING <> <>        
ACME$_INVNEWPWD <> <>        
ACME$_INVPERSONA <>         <>
ACME$_INVREQUEST <> <> <> <>    
ACME$_MAPCONFLICT <> <>        
ACME$_NOACMECTX <> <> <> <> <> <>
ACME$_NOCREDENTIALS <>          
ACME$_NOEXTAUTH <> <>        
ACME$_NOPRIV <> <> <> <>   <>
ACME$_NORMAL <> <> <> <> <> <>
ACME$_NOSUCHDOI <> <> <> <>    
ACME$_NOSUCHUSER <> <>        
ACME$_NOTARGETCRED           <>
ACME$_NOTAUTHORIZED <>          
ACME$_OPINCOMPL <> <>        
ACME$_PWDEXPIRED <>          
ACME$_TIMEOUT <> <> <>   <>  
ACME$_UNSUPPORTED <> <> <>   <>  

+Required
++Either ID or Name Required

Key to Codes
<> ---Permitted

VMS ACME Use of Function Codes The VMS ACME use of the Event function is reserved to HP.

The VMS ACME does not support the Query function. VMS ACME-Specific Item Codes This section describes the $ACM item codes that are ACME-specific for the VMS ACME.

Table SYS-14 indicates which VMS ACME-specific Item Codes are applicable to the various Function Codes:

Table SYS-14 Function Codes and VMS Specific Item Codes
  Function Codes
Item Codes Authenticate Principal Change Password Event Free Context Query Release Credentials
ACMEVMS$_AUTOLOGIN_ALLOWED_FLAG <>          
ACMEVMS$_CLASS_DAYS (O) <>          
ACMEVMS$_CLASS_FLAGS (O) <>          
ACMEVMS$_CLASS_NUMBER (O) <>          
ACMEVMS$_CLASS_PRIMEDAY_LIMIT (O) <>          
ACMEVMS$_CLASS_SECONDARY_LIMIT (O) <>          
ACMEVMS$_CLASS_NAME (U,O) <>          
ACMEVMS$_CONFIRM_PASSWORD_1 (U) <> <>        
ACMEVMS$_CONFIRM_PASSWORD_2 (U) <> <>        
ACMEVMS$_CONFIRM_PASSWORD_SYS (U) <> <>        
ACMEVMS$_CREPRC_BASPRI (O) <>          
ACMEVMS$_CREPRC_IMAGE (O) <>          
ACMEVMS$_CREPRC_PRCNAM (O) <>          
ACMEVMS$_CREPRC_PRVADR (O) <>          
ACMEVMS$_CREPRC_QUOTA (O) <>          
ACMEVMS$_CREPRC_UIC (O) <>          
ACMEVMS$_GENPWD_COUNT <> <>        
ACMEVMS$_GENPWD_MANDATORY_FLAG <> <>        
ACMEVMS$_GENPWD_MAXLENGTH <> <>        
ACMEVMS$_GENPWD_MINLENGTH <> <>        
ACMEVMS$_OLD_CONNECTION_FLAG BC          
ACMEVMS$_OLD_DECWINDOWS_FLAG BC          
ACMEVMS$_OLD_HASHED_PASSWORD_1 BC          
ACMEVMS$_OLD_HASHED_PASSWORD_2 BC          
ACMEVMS$_OLD_LGI_PHASE BC          
ACMEVMS$_OLD_LGI_STATUS BC          
ACMEVMS$_OLD_PROCESS_NAME BC          
ACMEVMS$_UAI_* (O) <>          
ACMEVMS$_LOGINOUT_CLI_FLAG BC          
ACMEVMS$_LOGINOUT_CREPRC_FLAGS BC          
ACMEVMS$_NET_PROXY BC          
ACMEVMS$_PREAUTHENTICATION_FLAG IR          
ACMEVMS$_REQUESTOR_PID IR IR        
ACMEVMS$_REQUESTOR_UIC IR IR        
ACMEVMS$_REQUESTOR_USERNAME (U) IR IR        
ACMEVMS$_USES_SYSTEM_PASSWORD SR          

+Required
++Either ID or Name Required

Key to Codes
<> ---Permitted
IR---IMPERSONATE Privilege Required to override default values
SR---SECURITY Privilege Required
O---Output item code
U---Subject to Unicode Conversion
BC---Backward Compatibility---Reserved for HP support of historical interface

SYS$CREPRC-Ready Item Codes

For users that need to create a process based on quotas and privileges from System User Authorization (SYSUAF) data, the following item codes return data in a form ready to be used in a call to SYS$CREPRC:

Item Code Direction Size Data Provided
ACMEVMS$_CREPRC_BASPRI Output Longword Base priority
ACMEVMS$_CREPRC_IMAGE Output String 1 LOGINOUT
ACMEVMS$_CREPRC_PRCNAM Output String 1 Null
ACMEVMS$_CREPRC_PRVADR Output Quadword Privilege mask
ACMEVMS$_CREPRC_QUOTA Output Sequence-of-bytes Quotas
ACMEVMS$_CREPRC_UIC Output Longword UIC

1The caller must create a descriptor for this item returned as a string to pass it to SYS$CREPRC.

To receive results of these item codes without authentication requires you to use the ACMEVMS$_PREAUTHENTICATION_FLAG, which in turn requires the IMPERSONATE privilege. No additional privilege for these item codes is required.

ACMEVMS$_CREPRC_BASPRI

This output item code requests UAI data in a format suitable for passing to SYS$CREPRC.

This output item code request UAI data in a format suitable for passing to SYS$CREPRC.

ACMEVMS$_CREPRC_IMAGE

This output item code requests UAI data in a format suitable for passing to SYS$CREPRC. The $ACM[W] client is responsible for creating a descriptor for this string.

ACMEVMS$_CREPRC_PRCNAM

This output item code requests UAI data in a format suitable for passing to SYS$CREPRC. The $ACM[W] client is responsible for creating a descriptor for this string.

ACMEVMS$_CREPRC_PRVADR

This output item code requests UAI data in a format suitable for passing to SYS$CREPRC.

ACMEVMS$_CREPRC_QUOTA

This output item code requests UAI data in a format suitable for passing to SYS$CREPRC, regardless of what quota might be handled by this service in the future.

ACMEVMS$_CREPRC_UIC

This output item code requests UAI data in a format suitable for passing to SYS$CREPRC.

Generated Password Item Codes

Any generated password list is returned in the ACM Communications Buffer, which is accessed by the context parameter. The following item codes are used to affect this password list:

Item Code Direction Size Data Provided
ACMEVMS$_GENPWD_COUNT Input Longword Unsigned
ACMEVMS$_GENPWD_MANDATORY_FLAG Input Longword Boolean
ACMEVMS$_GENPWD_MAXLENGTH Input Longword Unsigned
ACMEVMS$_GENPWD_MINLENGTH Input Longword Unsigned

ACMEVMS$_GENPWD_COUNT

The value of this item code indicates the number of any passwords that are generated, regardless of whether generation is due to the UAI$V_GENPWD bit or the presence of the ACMEVMS$_GENPWD_MANDATORY_FLAG input item code.

ACMEVMS$_GENPWD_MANDATORY_FLAG

The caller of SYS$AMCW requests password generation if this item code is present. A value whose low bit is set indicates the caller wants to force the use of the generated passwords, with the VMS ACME rejecting any provided passwords that do not match a password on the list. A value whose low bit is clear indicates that the generated password list is just advisory, with no enforcement by the VMS ACME. However, VMS ACME might actually enforce generated passwords anyway, depending on the setting of the UAI$V_GENPWD bit within the UAI_FLAGS longword bit mask.

ACMEVMS$_GENPWD_MAXLENGTH

The value of this item code indicates the maximum length of any passwords that are generated, regardless of whether generation is due to the UAI$V_GENPWD bit or the presence of the ACMEVMS$_GENPWD_MANDATORY_FLAG input item code.

ACMEVMS$_GENPWD_MINLENGTH

The value of this item code indicates the minimum length of any passwords that are generated, regardless of whether generation is due to the UAI$V_GENPWD bit or the presence of the ACMEVMS$_GENPWD_MANDATORY_FLAG input item code.

Backward Compatibility Item Codes

The ACME-specific item codes that provide backward compatibility are listed in the following table:

Item Code Direction Size Data Provided
ACMEVMS$_LOGINOUT_CLI_FLAGS Input Longword Boolean
ACMEVMS$_LOGINOUT_CREPRC_FLAGS Input Longword Bit mask
ACMEVMS$_OLD_CONNECTION_FLAG Input Longword Boolean
ACMEVMS$_OLD_DECWINDOWS_FLAG Input Longword Boolean
ACMEVMS$_OLD_HASHED_PASSWORD_1 Input Variable String
ACMEVMS$_OLD_HASHED_PASSWORD_2 Input Variable String
ACMEVMS$_OLD_LGI_PHASE Input Longword Code value
ACMEVMS$_OLD_LGI_STATUS Input Longword Message code
ACMEVMS$_OLD_PROCESS_NAME Input Variable String

ACMEVMS$_LOGINOUT_CLI_FLAGS

This input item code supplies the traditional LOGINOUT qualifiers to the VMS ACME, including particularly the /LOCAL_PASSWORD and /CONNECT qualifiers. This item is never provided on an initial call. It is only provided in response to a dialogue step.

Use of this item code is reserved to LOGINOUT, and is enforced by the VMS ACME to prevent spoofing.

ACMEVMS$_LOGINOUT_CREPRC_FLAGS

This input item code provides the CTL$GL_CREPRC_FLAGS longword corresponding to the FLAGS argument used for process creation. The use of this item code is reserved to LOGINOUT and is enforced by the VMS ACME to prevent spoofing.

ACMEVMS$_OLD_CONNECTION_FLAG

This input item code is used by LOGINOUT to indicate to the VMS ACME that a terminal user logging in has chosen to connect to a disconnected process rather than proceed with a new process.

Use of this item code is reserved to LOGINOUT, and is enforced by the VMS ACME to prevent spoofing.

ACMEVMS$_OLD_DECWINDOWS_FLAG

This input item code indicates the old DECwindows callout interface is being used. Use of this item code is reserved to LOGINOUT, and is enforced by the VMS ACME to prevent spoofing.

ACMEVMS$_OLD_HASHED_PASSWORD_1

This input item code specifies a primary password in an alternate form. You can only use this item code when specifying a value of ACMEVMS$_ARGUS for ACME$_AUTH_MECHANISM.

To use this item code, you need the IMPERSONATE privilege.

ACMEVMS$_OLD_HASHED_PASSWORD_2

This input item code specifies a secondary password in an alternate form. You can only use this item code when specifying a value of ACMEVMS$_ARGUS for ACME$_AUTH_MECHANISM.

To use this item code, you need the IMPERSONATE privilege.

ACMEVMS$_OLD_LGI_PHASE

This input item code specifies the phase of the latest LGI-callout. It is used to provide processing equivalent so that when authentication is performed inside LOGINOUT, the following actions occur:
  • Allows LGI$_SKIPRELATED from an LGI-callout routine to be honored by ACMEs.
  • Allows the VMS ACME to update UAF$W_LOGFAILS and possibly UAF$V_DISACNT even for a failure declared by an LGI-callout routine.

Use of this item code is reserved to LOGINOUT and is enforced by the VMS ACME to prevent LGI$_SKIPRELATED spoofing. If you want to perform a similar function, you should write an ACME.

ACMEVMS$_OLD_LGI_STATUS

This input item code specifies the status returned from the latest LGI-callout. It is used to provide processing equivalent so that when authentication is performed inside LOGINOUT, the following actions occur.
  • Allows LGI$_SKIPRELATED from an LGI-callout routine to be honored by ACMEs.
  • Allows the VMS ACME to update UAF$W_LOGFAILS and possibly UAF$V_DISACNT even for a failure declared by an LGI-callout routine.

Use of this item code is reserved to LOGINOUT, enforced by the VMS ACME to prevent LGI$_SKIPRELATED spoofing. If you want to perform a similar function, you should write an ACME.

ACMEVMS$_OLD_PROCESS_NAME

This input item code is used by LOGINOUT to indicate to the VMS ACME the process name after it has attempted to change the process name to match the username.

Use of this item code is reserved to LOGINOUT, and is enforced by the VMS ACME to prevent spoofing.

User Authorization Information (UAI) Item Codes

The VMS ACME supports the UAI codes that return SYSUAF values. SYSUAF contents are required for authorization, initialization, and auditing. The UAI codes are transmitted to the VMS ACME as ACME-specific codes. For the definition of these item codes, refer to the SYS$GETUAI system service in the HP OpenVMS System Services Reference Manual: GETUTC--Z.

When in dialogue mode and when you ask for the value in the fields, the VMS ACME returns the value from that of the previous login, that is, the login before the current login.

The following ACME UAI item codes are supported:

ACMEVMS$_UAI_ACCOUNTS ACMEVMS$_UAI_NETWORK_ACCESS_P
ACMEVMS$_UAI_ACCOUNT_LIM ACMEVMS$_UAI_NETWORK_ACCESS_S
ACMEVMS$_UAI_ASTLM ACMEVMS$_UAI_OWNER
ACMEVMS$_UAI_AUDIT_FLAGS (*) ACMEVMS$_UAI_PARENT_ID
ACMEVMS$_UAI_BATCH_ACCESS_P ACMEVMS$_UAI_PASSWORD (*)
ACMEVMS$_UAI_BATCH_ACCESS_S ACMEVMS$_UAI_PASSWORD2 (*)
ACMEVMS$_UAI_BIOLM ACMEVMS$_UAI_PBYTLM
ACMEVMS$_UAI_BYTLM ACMEVMS$_UAI_PGFLQUOTA
ACMEVMS$_UAI_CLITABLES ACMEVMS$_UAI_PRCCNT
ACMEVMS$_UAI_CPUTIM ACMEVMS$_UAI_PRI
ACMEVMS$_UAI_DEF_CLASS ACMEVMS$_UAI_PRIMEDAYS
ACMEVMS$_UAI_DEFCLI ACMEVMS$_UAI_PRIV
ACMEVMS$_UAI_DEFDEV ACMEVMS$_UAI_PROXYIES
ACMEVMS$_UAI_DEFDIR ACMEVMS$_UAI_PROXY_LIM
ACMEVMS$_UAI_DEF_PRIV ACMEVMS$_UAI_PWD
ACMEVMS$_UAI_DFWSCNT ACMEVMS$_UAI_PWD2
ACMEVMS$_UAI_DIOLM ACMEVMS$_UAI_PWD_DATE
ACMEVMS$_UAI_DIALUP_ACCESS_P ACMEVMS$_UAI_PWD2_DATE
ACMEVMS$_UAI_DIALUP_ACCESS_S ACMEVMS$_UAI_PWD_LENGTH
ACMEVMS$_UAI_ENCRYPT ACMEVMS$_UAI_PWD_LIFETIME
ACMEVMS$_UAI_ENCRYPT2 ACMEVMS$_UAI_QUEPRI
ACMEVMS$_UAI_ENQLM ACMEVMS$_UAI_REMOTE_ACCESS_P
ACMEVMS$_UAI_EXPIRATION ACMEVMS$_UAI_REMOTE_ACCESS_S
ACMEVMS$_UAI_FILLM ACMEVMS$_UAI_RTYPE
ACMEVMS$_UAI_FLAGS ACMEVMS$_UAI_SALT
ACMEVMS$_UAI_GRP ACMEVMS$_UAI_SHRFILLM
ACMEVMS$_UAI_JTQUOTA ACMEVMS$_UAI_SUB_ID
ACMEVMS$_UAI_LASTLOGIN_I ACMEVMS$_UAI_TQCNT
ACMEVMS$_UAI_LASTLOGIN_N ACMEVMS$_UAI_UIC
ACMEVMS$_UAI_LGICMD ACMEVMS$_UAI_USER_DATA
ACMEVMS$_UAI_LOCAL_ACCESS_P ACMEVMS$_UAI_USRDATOFF
ACMEVMS$_UAI_LOCAL_ACCESS_S ACMEVMS$_UAI_USERNAME
ACMEVMS$_UAI_LOGFAILS ACMEVMS$_UAI_USERNAME_TAG
ACMEVMS$_UAI_MAXACCTJOBS ACMEVMS$_UAI_JSVERSION
ACMEVMS$_UAI_MAX_CLASS ACMEVMS$_UAI_WSQUOTA
ACMEVMS$_UAI_MAXDETACH  
ACMEVMS$_UAI_MAXJOBS  
ACMEVMS$_UAI_MEM  
ACMEVMS$_UAI_MIN_CLASS  

* These items are defined for the following numeric calculations purposes because the base for the ACME-specific UAI item codes is ACMEVMS$K_UAI_BASE. ACMEVMS$K_UAI_BASE can be added to a UAI$_* code to produce the corresponding ACMEVMS$_UAI_* code.

Class Scheduling Item Codes

The following table lists class scheduling item codes:

Item Code Direction Size Data Provided
ACMEVMS$_CLASS_DAYS Output Byte Bit-mask
ACMEVMS$_CLASS_FLAGS Output Longword Bit-mask
ACMEVMS$_CLASS_NAME Output Variable String
ACMEVMS$_CLASS_NUMBER Output Word Integer
ACMEVMS$_CLASS_PRIMEDAY_LIMIT Output 24 bytes Integer Array
ACMEVMS$_CLASS_SECONDAY_LIMIT Output 24 bytes Integer Array

ACMEVMS$_CLASS_DAYS

This item returns a 7-bit array, one for each day of the week starting with Monday as the low-order bit.

If a given bit is set, it means the corresponding day of the week is to be treated as a Secondary Day for purposes of class scheduling. If a given bit is clear, the corresponding day of the week is to be treated as a Primary Day for purposes of class scheduling. These designations are overridden if the $GETSYI item code SYI$_DAY_OVERRIDE is set.

This data is intended primarily for LOGINOUT in setting up any class scheduling required for a new process, although other callers of $ACM are free to request it for their own purposes.

Data returned for this item code is 1 byte long, so a caller's buffer should be at least that long.

ACMEVMS$_CLASS_FLAGS

This item code returns a 32-bit mask of flags used for class scheduling.

This data is intended primarily for LOGINOUT in setting up any class scheduling required for a new process, although other callers of $ACM are free to request it for their own purposes.

Data returned for this item code is 4 bytes long, so a caller's buffer should be at least that long.

ACMEVMS$_CLASS_NAME

This item code returns a string indicating the Class Name for class scheduling the VMS Username just authenticated.

This data is intended primarily for LOGINOUT in setting up any class scheduling required for a new process, although other callers of $ACM are free to request it for their own purposes.

Data returned for this item code is up to 16 characters long, so a caller's buffer should be at least that long, with the number of bytes allocated dependent on whether the ACME$M_UCS2_4 function code modifier was specified on the call to $ACM[W].

ACMEVMS$_CLASS_NUMBER

This item code returns the Class Number for class scheduling the VMS Username just authenticated. A Class Number of zero means no Class applies to this VMS Username.

This data is intended primarily for LOGINOUT in setting up any class scheduling required for a new process, although other callers of $ACM are free to request it for their own purposes.

Data returned for this item code is 2 bytes long, so a caller's buffer should be at least that long.

ACMEVMS$_CLASS_PRIMEDAY_LIMIT

This item code returns an array of 24 bytes, one for each hour of a Primary Day, each containing a number from 1 to 100 indicating the percentage of the overall system CPU time reserved for members of that class.

This data is intended primarily for LOGINOUT in setting up any class scheduling required for a new process, although other callers of $ACM are free to request it for their own purposes.

Data returned for this item code is 24 bytes long, so a caller's buffer should be at least that long.

ACMEVMS$_CLASS_SECONDAY_LIMIT

This item code returns an array of 24 bytes, one for each hour of a Secondary Day, each containing a number from 1 to 100 indicating the percentage of the overall system CPU time reserved for members of that class.

This data is intended primarily for LOGINOUT in setting up any class scheduling required for a new process, although other callers of $ACM are free to request it for their own purposes.

Data returned for this item code is 24 bytes long, so a caller's buffer should be at least that long.

Miscellaneous Item Codes

The following ACME-specific item codes cannot be classified into any of the previous categories:

Item Code Direction Size Data Provided
ACMEVMS$_AUTOLOGIN_ALLOWED_FLAG Input Longword Boolean
ACMEVMS$_CONFIRM_PASSWORD_1 Input Variable String
ACMEVMS$_CONFIRM_PASSWORD_2 Input Variable String
ACMEVMS$_CONFIRM_PASSWORD_SYS Input Variable String
ACMEVMS$_NET_PROXY Input Variable String
ACMEVMS$_PREAUTHENTICATION_FLAG Input Longword Boolean
ACMEVMS$_REQUESTOR_PID Input Longword Hexadecimal
ACMEVMS$_REQUESTOR_UIC Input Longword Hexadecimal
ACMEVMS$_REQUESTOR_USERNAME Input Variable String
ACMEVMS$_USES_SYSTEM_PASSWORD Input Longword Boolean

ACMEVMS$_AUTOLOGIN_ALLOWED_FLAG

This input item code specifies that a particular access port is of a type eligible for VMS Autologin. If the port is not specified in the Autologin file read by the VMS ACME, then this item code has no effect.

ACMEVMS$_CONFIRM_PASSWORD_1

The VMS ACME uses this input item code as a separate verification prompt when a new primary password is being specified. Use of a separate dialogue step rather than the verification method built into the Item Set definition allows some initial checking to be done for acceptability of the proposed password before the user is asked to type the password in again.

Some networked ACME agents are tied to network protocols that do not allow independent checking of the acceptability of a proposed password, so even when an item set with this item code is returned, the proposed password could be rejected later.

This item code might be requested in a dialogue step.

ACMEVMS$_CONFIRM_PASSWORD_2

The VMS ACME uses this input item code as a separate verification prompt when a new secondary password is being specified. Use of a separate dialogue step rather than the verification method built into the Item Set definition allows some initial checking to be done for acceptability of the proposed password before the user is asked to type the password again.

Some networked ACME agents are tied to network protocols that do not allow independent checking of the acceptability of a proposed password, so even when an item set with this item code is returned, the proposed password could be rejected later. Most networked ACME agents do not support secondary passwords, so after an item set with this item code has been returned, rejection later is unlikely, though possible.

This item code might be requested in a dialogue step.

ACMEVMS$_CONFIRM_PASSWORD_SYS

The VMS ACME uses this input item code as a separate verification prompt when a new system password is being specified. Use of a separate dialogue step rather than the verification method built into the Item Set definition allows full initial checking to be done for acceptability of the proposed system password before the user is asked to type the entire password in again.

This item code might be requested in a dialogue step.

ACMEVMS$_NET_PROXY

This input item code specifies the proxy user name for which a network login is to be processed, without authentication information, just as for a batch login or preauthenticated network login.

This item code requires the IMPERSONATE privilege.

ACMEVMS$_PREAUTHENTICATION_FLAG

This input item code specifies a login that is to be processed without authentication information, such as for a batch login. When first received by the VMS ACME, this item code causes the setting of the WQE_PREAUTHENTICATED flag in the Work Queue Entry Context, which is honored by all ACMEs.

To use this item code, you need the IMPERSONATE privilege.

ACMEVMS$_REQUESTOR_PID

This input item code specifies the Requestor Processor ID for use by the VMS ACME in auditing and breakin detection. Combined with the codes ACMEVMS$_REQUESTOR_UIC and ACMEVMS$_REQUESTOR_USERNAME, it is used when the process calling $ACM is not actually the process to which the authentication should be attributed. When first received by the VMS ACME, the value of this item is stored in the REQUESTOR_PID longword in the Request Context for later use. This item code is available to support LGI-callout operations and other callers to LGI$AUTHENTICATE_USER.

To use this item code, you need the IMPERSONATE privilege to guard against spoofing.

ACMEVMS$_REQUESTOR_UIC

This input item code specifies the Requestor UIC for use by the VMS ACME in auditing and breakin detection. When first received by the VMS ACME, the value of this item is stored in the REQUESTOR_UIC longword in the Request Context for later use. This item code is available to support LGI-callout operations and other callers of LGI$AUTHENTICATE_USER.

This item allows the caller of $ACM to provide an accurate value because a call to SYS$GETJPI, based on the ACMEVMS$_REQUESTOR_PID ACME-specific item code value, might produce inaccurate results due to a subsequent assumption of a different persona in the requestor process.

To use this item code, you need the IMPERSONATE privilege to guard against spoofing.

ACMEVMS$_REQUESTOR_USERNAME

This input item code specifies the Requestor Username for use by the VMS ACME in auditing and breakin detection. When first received by the VMS ACME, the value of this item is stored in the OWNER_USERNAME varying string descriptor in the Request Context for later use. This item code supports LGI-callout operations and other callers of LGI$AUTHENTICATE_USER.

This item allows the caller of $ACM to provide an accurate value because a call to SYS$GETJPI, based on the ACMEVMS$_REQUESTOR_PID item code value, might produce inaccurate results due to a subsequent assumption of a different persona in the requestor process.

To use this item code, you need the IMPERSONATE privilege to guard against spoofing.

ACMEVMS$_USES_SYSTEM_PASSWORD

This input item code specifies that a particular access port is enabled for use of the System Password. Other conditions, such as not having a System Password defined, may mean that no Item Set requesting a System Password is actually returned to the client. When first received by the VMS ACME, the value of this item is stored in the USES_SYSTEM_PASSWORD_FLAG boolean in the Request Context for later use.

To use this item code, you need the SECURITY privilege to guard against password guessing.

VMS ACME-Specific---Output Message Categories

The following table lists the output message categories specific to the VMS ACME and their meanings:

Message Category Meaning
ACMEVMS$K_OLD_AUTH_FLAGS Password requirement flags
ACMEVMS$K_OLD_DECW_PWD_EXP_1 Binary expiration warning
ACMEVMS$K_OLD_DECW_PWD_EXP_2 Binary expiration warning
ACMEVMS$K_OLD_DECW_PWD_QUALITY Binary password quality status
ACMEVMS$K_OLD_SYSUAF_070 Authorization record
ACMEVMS$K_OLD_TERMINAL_CONNECT Advance notice of authentication

These categories appear in output item set entries and are specially interpreted by LOGINOUT.

These categories are restricted to the LOGINOUT client since they exist only for supporting the old style DECwindows and LGI-callouts.

ACMEVMS$K_OLD_AUTH_FLAGS

This output message category provides a series of flags that are used to construct the Authentication Flags indicating what passwords are required for the mapped user name.

These flags are used directly for DECwindows V1.2-4 and earlier in LGI$AUTHENTICATE_USER, and for calculations that are passed to LGI-callouts in cell ICR_PWDCOUNT by INTERACT/INTERACITVE_VALIDATION. It provides data abstraction from the specific SYSUAF fields.

The following table lists the flags, their bit number, and meaning:

Name Bit Number Meaning
OPENACCT 0 No password
PASSWORD_1 1 Primary password exists
PASSWORD_2 2 Secondary password exists
GENPWD 3 Passwords are not generated

This data is only supplied to LOGINOUT to support previous LGI-callout and DECwindows callout models. Other clients should follow the ACME model for user interaction.

This output item category provides a buffer that is to be filled with ACMEVMS$K_OLD_AUTH_FLAGS output message category data.

ACMEVMS$K_OLD_DECW_PWD_EXP_1

This output message category is a binary quadword indicating future password expiration.

It is provided only for compatibility with older versions of DECwindows. Its use is restricted to LOGINOUT, which is enforced by the VMS ACME.

ACMEVMS$K_OLD_DECW_PWD_EXP_2

This output message category is a binary quadword indicating future password expiration.

This data is provided only for compatibility with older versions of DECwindows. Its use is restricted to LOGINOUT, which is enforced by the VMS ACME.

ACMEVMS$K_OLD_DECW_PWD_QUALITY Output Message Category

This output message category is a binary longword indicating the failure category on password change.

This data is provided only for compatibility with older versions of DECwindows. Its use is restricted to LOGINOUT, which is enforced by the VMS ACME.

ACMEVMS$K_SYSUAF_070

This output message category provides a buffer that is to be filled with UAF070$ data. LOGINOUT now uses the $ACMW service, relying exclusively on UAI$_information rather than the direct manipulation of SYSUAF records. This output message category provides the same information as various UAI$_xxxx codes, but in the format of the OpenVMS V7.0 SYSUAF record. This item code allows LOGINOUT to continue supporting the LGI-callout interface. Your new software should use UAI$_xxxx item codes and avoid the ACMEVMS$K_SYSUAF_070 output message category.

This data is only supplied to LOGINOUT to support previous LGI-callout and DECwindows callout models. Other clients should follow the ACME model for user interaction.

ACMEVMS$K_OLD_TERMINAL_CONNECT

This output message category is passed from the VMS ACME to LOGINOUT to allow for changing the process name prior to auditing and to give an opportunity for the users to reconnect to any disconnected job they may have.

This data is provided only for compatibility with the historic behavior of LOGINOUT. Its use is restricted to LOGINOUT, which is enforced by the VMS ACME.

VMS ACME-Specific Authentication Mechanisms

ACMEVMS$K_AUTH_MECH_ARGUS

This authentication mechanism is used by the TNT Server component used for system management from Intel machines. Its use is restricted to that client, enforced by the VMS ACME.

$ACMW (Alpha Only)

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


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


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.

Description

This service is used to acquire ownership of an OpenVMS Galaxy lock. If the lock is free, the caller becomes the owner and control returns immediately. If the lock is owned, based on the input flags and the timeout value, either the caller will wait or an error will be returned.

The default behavior when an attempt is made to acquire a lock that is owned, is to spin for 10 microseconds and then to wait. If a wait timeout value was specified in the call, it is used. Otherwise the timeout value set in the lock by $CREATE_GALAXY_LOCK will be used. This behavior can be changed with the input flags.

If just GLOCK$C_NOSPIN is specified and the lock is owned, no spin will be done.

If just GLOCK$C_NOWAIT is specified and the lock is owned, the caller will only spin on the lock. If a timeout value is specified in the call, it is used as the spin time. Otherwise, the caller will spin for 10 microseconds. If the lock does not become available during the spin, the lock is not acquired and SS$_NOWAIT is returned.

If both GLOCK$C_NOSPIN and GLOCK$C_NOWAIT are specified and the lock is owned, control returns immediately. The lock is not acquired and SS$_NOWAIT is returned.

Due to system events such an OpenVMS Galaxy instance shutting down, a lock may become owned by a non-existent entity. If this occurs, the default behavior of $ACQUIRE_GALAXY_LOCK is to break the old lock ownership. The caller becomes the new owner and the service returns SS$_BROKEN. If GLOCK$C_NOBREAK is specified, $ACQUIRE_GALAXY_LOCK will not break the lock ownership and returns SS$_NOBREAK.

Required Access or Privileges

Write access to OpenVMS Galaxy lock table contains lock to acquire.

Required Quota

None

Related Services

$CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK


Condition Values Returned

SS$_NORMAL Normal completion.
SS$_BADPARAM Bad parameter value.
SS$_BROKEN Lock acquired after lock ownership was broken.
SS$_IVLOCKID Invalid lock id.
SS$_IVLOCKOP Invalid lock operation.
SS$_IVLOCKTBL Invalid lock table.
SS$_LOCK_TIMEOUT Failed to acquire lock; request has timed out.
SS$_NOBREAK Failed to acquire lock; lock ownership is broken.
SS$_NOWAIT Failed to acquire lock; NOWAIT was specified.

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


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 Table SYS-15. All undefined bits must be 0. If this argument is omitted, no flags are used.

Table SYS-15 $ADD_BRANCH 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. See the Condition Values Returned section.

The following diagram shows 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

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.

Description

The $ADD_BRANCH system service:
  • Authorizes a new branch to be added to the specified transaction.
  • Checks, if the tm_name argument specifies a remote node, that there is a communications link between the DECdtm transaction manager on that node and the DECdtm transaction manager on the local node.

The precondition for the successful completion of $ADD_BRANCH is that the calling process must contain at least one branch of the specified transaction.

$ADD_BRANCH may fail for several reasons, including:

  • The precondition was not satisfied.
  • An abort event has occurred for the transaction.
  • A call to $END_TRANS to end the transaction is in progress and it is now too late to authorize a new branch for the transaction.
  • The node specified by the tm_name argument was a remote node and a failure was detected by the IPC mechanism.

Postconditions on successful completion of $ADD_BRANCH are described in Table SYS-16:

Table SYS-16 Postconditions When$ADD_BRANCH Completes Successfully
Postcondition Meaning
A new branch is authorized for the transaction and its identifier is returned. The identifier (BID) of the new branch is returned in the octaword to which the bid argument points. $ADD_BRANCH uses the $CREATE_UID system service to generate the BID. No other call to $ADD_BRANCH or $CREATE_UID on any node ever returns the same BID value.
The transaction cannot commit until the new branch has been added to the transaction by a matching call to $START_BRANCH. See the description of $START_BRANCH for the definition of a "matching" call to $START_BRANCH.

There is also a wait form of the service, $ADD_BRANCHW.

Required Privileges

None

Required Quotas

BYTLM, ASTLM

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW, $SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW


Condition Values Returned

SS$_NORMAL If returned in R0, the request was successfully queued. If returned in the I/O status block, the service completed successfully.
SS$_SYNCH The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set).
SS$_ACCVIO An argument was not accessible to the caller.
SS$_BADPARAM The options flags were invalid.
SS$_EXASTLM The process AST limit (ASTLM) was exceeded.
SS$_EXQUOTA The job buffered I/O byte limit quota (BYTLM) was exceeded.
SS$_ILLEFC The event flag number was invalid.
SS$_INSFARGS A required argument was missing.
SS$_INSFMEM There was insufficient system dynamic memory for the operation.
SS$_INVBUFLEN The string passed in the tm_name argument was longer than 256 characters.
SS$_NOSUCHTID The calling process did not contain any branches in the transaction.
SS$_WRONGSTATE The transaction was in the wrong state for the attempted operation because either an abort event has occurred for the transaction, or a call to $END_TRANS to end the transaction is in progress and it is now too late to authorize new branches for the transaction.
Any IPC status An error has occurred while attempting to communicate with the node specified by the tm_name argument. The set of IPC statuses includes the set of DECnet errors.

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


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


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.

Description

The Add Holder Record to Rights Database service registers the specified user as a holder of the specified identifier with the rights database.

Required Access or Privileges

Write access to the rights database is required.

Required Quota

None

Related Services

$ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The holder argument cannot be read by the caller.
SS$_BADPARAM The specified attributes contain invalid attribute flags.
SS$_DUPIDENT The specified holder already exists in the rights database for this identifier.
SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT The specified identifier or holder is of an invalid format, the specified holder is 0, or the specified identifier and holder are equal.
SS$_NORIGHTSDB The rights database does not exist.
SS$_NOSUCHID The specified identifier does not exist in the rights database, or the specified holder identifier does not exist in the rights database.
RMS$_PRV The user does not have write access to the rights database.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.


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


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.

Description

The Add Identifier to Rights Database service adds the specified identifier to the rights database.

Required Access or Privileges

Write access to the rights database is required.

Required Quota

None

Related Services

$ADD_HOLDER, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The name argument cannot be read by the caller, or the resid argument cannot be written by the caller.
SS$_BADPARAM The specified attributes contain invalid attribute flags.
SS$_DUPIDENT The specified identifier already exists in the rights database.
SS$_DUPLNAM The specified identifier name already exists in the rights database.
SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT The format of the specified identifier is invalid.
SS$_NORIGHTSDB The rights database does not exist.
RMS$_PRV The user does not have write access to the rights database.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.


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


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_EXPAND The service should not convert the node name 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_RETURN The service should not wait for a return status from the security server. No return status from the server's function will be returned to the caller.

Description

The Add Proxy service adds a new proxy to, or modifies an existing proxy in, the proxy database.

Required Access or Privileges

The caller must have either SYSPRV privilege or a UIC group less than or equal to the MAXSYSGRP system parameter.

Required Quota

None

Related Services

$DELETE_PROXY, $DISPLAY_PROXY, $VERIFY_PROXY


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The rem_node, rem_user, local_user, or flags argument cannot be read by the service.
SS$_BADPARAM An invalid flag was specified in the flags argument.
SS$_BADBUFLEN The length of the rem_node, rem_user, or local_user argument was out of range.
SS$_NOSYSPRV The caller does not have access to the proxy database.
   
This service can also return any of the following messages passed from the security server, or any OpenVMS RMS error message encountered during operations on the proxy database:
SECSRV$_BADLOCALUSERLEN The local user name length is out of range.
SECSRV$_BADNODENAMELEN The node name length is out of range.
SECSRV$_BADREMUSERLEN The remote user name length is out of range.
SECSRV$_DUPLICATEUSER The user name specified by the local_user argument already exists in the proxy record's local user list.
SECSRV$_PROXYNOTACTIVE Proxy processing is currently stopped. Try the request again later.
SECSRV$_SERVERNOTACTIVE The security server is not currently active. Try the request again later.
SECSRV$_TOOMANYUSERS The specified proxy already has 16 local users and cannot accommodate any more.

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


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.

For additional information about the various combinations of values for adjust and newadr, see the Description section.

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.

For additional information about the various combinations of values for adjust and newadr, see the Description section.


Description

The Adjust Outer Mode Stack Pointer service 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.

Combinations of zero and nonzero values for the adjust and newadr arguments provide the following results:

If the adjust
argument
specifies:
And the value
specified by
newadr is:
The stack
pointer is:
0 0 Not changed
0 An address Loaded with the address specified
A value 0 Adjusted by the specified value
A value An address Loaded with the specified address, adjusted by the specified value

In all cases, the updated stack pointer value is written into the value specified by the newadr argument.

Required Access or Privileges

None

Required Quota

None

Related Services

$ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The value specified by newadr or a portion of the new stack segment cannot be written by the caller.
SS$_NOPRIV The specified access mode is equal to or more privileged than the calling access mode.

$ADJWSL

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

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


Format

SYS$ADJWSL [pagcnt] ,[wsetlm]


C Prototype

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


Arguments

pagcnt


OpenVMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value

Signed adjustment value specifying the number of pages (on VAX systems) or pagelets (on Alpha systems) 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 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 (Alpha)
mechanism: by 32-bit reference (VAX)

Value of the working set limit, in pages (on VAX systems) or pagelets (on Alpha systems), returned by $ADJWSL. The wsetlm argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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.

Description

The Adjust Working Set Limit service adjusts a process's current working set limit by the specified number of pages (on VAX systems) or pagelets (rounded up or down to a whole page count on Alpha systems) and returns the new value to the caller. The working set limit specifies the maximum number of process pages that can be resident in physical memory.

If a program attempts to adjust the working set limit beyond the system-defined upper and lower limits, no error condition is returned; instead, the working set limit is adjusted to the maximum or minimum size allowed.

Required Access or Privileges

None

Required Quota

The initial value of a process's working set limit is controlled by the working set default (WSDEFAULT) quota. The maximum value to which it can be increased is controlled by the working set extent (WSEXTENT) quota; the minimum value to which it can be decreased is limited by the system parameter MINWSCNT.

Related Services

$ADJSTK, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The longword specified by wsetlm cannot be written by the caller.

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


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  

Description

The Allocate Device service 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.

When a process calls the Assign I/O Channel ($ASSIGN) service to assign a channel to a nonshareable, nonspooled device, such as a terminal or line printer, the device is implicitly allocated to the process.

You can use this service only to allocate devices that either exist on the host system or are made available to the host system in an OpenVMS Cluster environment.

Required Access or Privileges

Read, write, or control access to the device is required.

Required Quota

None

Related Services

$ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_BUFFEROVF The service completed successfully. The physical name returned overflowed the buffer provided, and was truncated.
SS$_DEVALRALLOC The service completed successfully. The device was already allocated to the calling process.
SS$_ACCVIO The device name string, string descriptor, or physical name buffer descriptor cannot be read by the caller, or the physical name buffer cannot be written by the caller.
SS$_DEVALLOC The device is already allocated to another process, or an attempt to allocate an unmounted shareable device failed because other processes had channels assigned to the device.
SS$_DEVMOUNT The specified device is currently mounted and cannot be allocated, or the device is a mailbox.
SS$_DEVOFFLINE The specified device is marked off line.
SS$_IVDEVNAM The device name string contains invalid characters, or no device name string was specified.
SS$_IVLOGNAM The device name string has a length of 0 or has more than 63 characters.
SS$_IVSTSFLG The bits set in the longword of status flags are invalid.
SS$_NODEVAVL The specified device in a generic search exists but is allocated to another user.
SS$_NONLOCAL The device is on a remote node.
SS$_NOPRIV The requesting process attempted to allocate a spooled device and does not have the required privilege, or the device protection or access control list (or both) denies access.
SS$_NOSUCHDEV The specified device does not exist in the host system. This error is usually the result of a typographical error.
SS$_TEMPLATEDEV The process attempted to allocate a template device; a template device cannot be allocated.

The $ALLOC service can also return any condition value returned by $ENQ. For a list of these condition values, see the description of $ENQ.


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


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


Description

The Associate Common Event Flag Cluster service associates a named common event flag cluster with a process for the execution of the current image and to assign it a process-local cluster number for use with other event flag services. A process needs associate access to call the $ASCEFC service.

When a process associates with a common event flag cluster, that cluster's reference count is increased by 1. The reference count is decreased when a process disassociates from the cluster, whether explicitly with the Disassociate Common Event Flag Cluster ($DACEFC) service or implicitly at image exit.

Temporary clusters are automatically deleted when their reference count goes to 0; you must explicitly mark permanent clusters for deletion with the Delete Common Event Flag Cluster ($DLCEFC) service.

When a new cluster is created, a security profile is created with the process UIC as the owner of the common event flag cluster; the remaining characteristics are taken from the COMMON_EVENT_CLUSTER.DEFAULT template profile.

Because the $ASCEFC service automatically creates the common event flag cluster if it does not already exist, cooperating processes need not be concerned with which process executes first to create the cluster. The first process to call $ASCEFC creates the cluster and the others associate with it regardless of the order in which they call the service.

The initial state for all event flags in a newly created common event flag cluster is 0.

If a process has already associated a cluster number with a named common event flag cluster and then issues another call to $ASCEFC with the same cluster number, the service disassociates the number from its first assignment before associating it with its second.

If you previously called any system service that will set an event flag (and the event flag is contained within the cluster being reassigned), the event flag will be set in the newly associated named cluster, not in the previously associated named cluster.

Required Access or Privileges

The calling process must have PRMCEB privilege to create a permanent common event flag cluster.

Required Quota

Creation of temporary common event flag clusters uses the quota of the process for timer queue entries (TQELM); the creation of a permanent cluster does not affect the quota. The quota is restored to the creator of the cluster when all processes associated with the cluster have disassociated.

Related Services

$CLREF, $DACEFC, $DLCEFC, $READEF, $SETEF, $WAITFR, $WFLAND, $WFLOR


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The cluster name string or string descriptor cannot be read by the caller.
SS$_EXPORTQUOTA The process has exceeded the number of event flag clusters with which processes on this port of the multiport (shared) memory can associate.
SS$_EXQUOTA The process has exceeded its timer queue entry quota; this quota controls the creation of temporary common event flag clusters.
SS$_INSFMEM The system dynamic memory is insufficient for completing the service.
SS$_ILLEFC You specified an illegal event flag number. The cluster number must be in the range of event flags 64 through 127.
SS$_INTERLOCK The bit map lock for allocating common event flag clusters from the specified shared memory is locked by another process.
SS$_IVLOGNAM The cluster name string has a length of 0 or has more than 15 characters.
SS$_NOPRIV The process does not have the privilege to create a permanent cluster; the process does not have the privilege to create a common event flag cluster in memory shared by multiple processors; or the protection applied to an existing cluster by its creator prohibits association.
SS$_NOSHMBLOCK The common event flag cluster has no shared memory control block available.
SS$_SHMNOTCNT+ The shared memory named in the name argument is not known to the system. This error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.

+VAX specific


$ASCTIM

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

On Alpha 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);


Arguments

timlen


OpenVMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)

Length (in bytes) of the ASCII string returned by $ASCTIM. The timlen argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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 (Alpha)
mechanism: by 32-bit descriptor (VAX)

Buffer into which $ASCTIM writes the ASCII string. The timbuf argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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 (Alpha)
mechanism: by 32-bit reference (VAX)

Time value that $ASCTIM is to convert. The timadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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.

Description

The Convert Binary Time to ASCII String service converts an absolute or delta time from 64-bit system time format to an ASCII string. The service executes at the access mode of the caller and does not check whether address arguments are accessible before it executes. Therefore, an access violation causes an exception condition if the input time value cannot be read or the output buffer or buffer length cannot be written.

This service returns the SS$_INSFARG (insufficient arguments) condition value if one or both of the required arguments are not supplied.

The ASCII strings returned have the following formats:

  • Absolute Time: dd-mmm-yyyy hh:mm:ss.cc
  • Delta Time: dddd hh:mm:ss.cc

The following table lists the length (in bytes), contents, and range of values for each field in the absolute time and delta time formats:

Field Length
(Bytes)
Contents Range of Values
dd 2 Day of month 1--31
-- 1 Hyphen Required syntax
mmm 3 Month JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC
-- 1 Hyphen Required syntax
yyyy 4 Year 1858--9999
blank n Blank Required syntax
hh 2 Hour 00--23
: 1 Colon Required syntax
mm 2 Minutes 00--59
: 1 Colon Required syntax
ss 2 Seconds 00--59
. 1 Period Required syntax
cc 2 Hundredths-of-second 00--99
dddd 4 Number of days (in 24-hr units) 000--9999

Month abbreviations must be uppercase.

The hundredths-of-second field now represents a true fraction. For example, the string .1 represents ten-hundredths of a second (one-tenth of a second), and the string .01 represents one-hundredth of a second.

Also, you can add a third digit to the hundredths-of-second field; this thousandths-of-second digit is used to round the hundredths-of-second value. Digits beyond the thousandths-of-second digits are ignored.

The results of specifying some possible combinations for the values of the cvtflg and timbuf arguments are as follows:

Time Value Buffer Length
Specified
CVTFLG
Argument
Information
Returned
Absolute 23 0 Date and time
Absolute 12 0 Date
Absolute 11 1 Time
Delta 16 0 Days and time
Delta 11 1 Time

Required Access or Privileges

None

Required Quota

None

Related Services

$BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIME, $SETIMR


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_BUFFEROVF The buffer length specified in the timbuf argument is too small.
SS$_INSFARG Required argument is missing.
SS$_IVTIME The specified delta time is equal to or greater than 10,000 days.

$ASCTOID

Translates the specified identifier name into its binary identifier value.

On Alpha 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);


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 (Alpha)
mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Identifier name translated when $ASCTOID completes execution. The name argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) 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 (Alpha)
mechanism: by 32-bit reference (VAX)

Identifier value resulting when $ASCTOID completes execution. The id argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) 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 (Alpha)
mechanism: by 32-bit reference (VAX)

Attributes associated with the identifier returned in id when $ASCTOID completes execution. The attrib argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) 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.

Description

The Translate Identifier Name to Identifier service converts the specified identifier name to its binary identifier value.

Required Access or Privileges

None, unless the id is KGB$V_NAME_HIDDEN, in which case you must hold the id or have access to the rights database.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The name argument cannot be read by the caller, or the id or attrib arguments cannot be written by the caller.
SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT The format of the specified identifier is invalid.
SS$_NOSUCHID The specified identifier name does not exist in the rights database, or the identifier is hidden and you do not have access to the rights database.
SS$_NORIGHTSDB The rights database does not exist.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.


$ASCUTC

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

On Alpha 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);


Arguments

timlen


OpenVMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)

Length (in bytes) of the ASCII string returned by $ASCUTC. The timlen argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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 (Alpha)
mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Buffer into which $ASCUTC writes the ASCII string. The timbuf argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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 (Alpha)
mechanism: by 32-bit reference (VAX)

Time value that $ASCUTC is to convert. The timadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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.

Description

The Convert UTC to ASCII service converts an absolute time from 128-bit UTC format to an ASCII string. The service executes at the access mode of the caller and does not check whether address arguments are accessible before it executes; therefore, an access violation causes an exception condition if the input time value cannot be read or the output buffer or buffer length cannot be written.

The $ASCUTC service uses the time zone differential factor encoded in the 128-bit UTC to convert the UTC to an ASCII string.

This service does not check the length of the argument list, and therefore cannot return the SS$_INSFARG condition value.

The ASCII strings returned have the following format:

  • Absolute Time: dd-mmm-yyyy hh:mm:ss.cc

The following table lists the length (in bytes), contents, and range of values for each field in the absolute time format:

Field Length
(Bytes)
Contents Range of Values
dd 2 Day of month 1--31
-- 1 Hyphen Required syntax
mmm 3 Month JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC
-- 1 Hyphen Required syntax
yyyy 4 Year 1858--9999
blank n Blank Required syntax
hh 2 Hour 00--23
: 1 Colon Required syntax
mm 2 Minutes 00--59
: 1 Colon Required syntax
ss 2 Seconds 00--59
. 1 Period Required syntax
cc 2 Hundredths-of-second 00--99

The results of specifying some possible combinations for the values of the cvtflg and timbuf arguments are as follows:

Time Value Buffer Length
Specified
CVTFLG
Argument
Information
Returned
Absolute 23 0 Date and time
Absolute 12 0 Date
Absolute 11 1 Time

Required Access or Privileges

None

Required Quota

None

Related Services

$BINUTC, $GETUTC, $NUMUTC, $TIMCON


Condition Values Returned

SS_$NORMAL The service completed successfully.
SS_$BUFFEROVF The buffer length specified in the timbuf argument is too small.
SS_$INVTIME The UTC time supplied is too small to be represented as a Smithsonian Time, or the UTC time is not valid.

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


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 (Alpha)
mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Name of the device to which $ASSIGN is to assign a channel. The devnam argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) 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 (Alpha)
mechanism: by 32-bit reference (VAX)

Number of the channel that is assigned. The chan argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) 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, refer to the section on access modes in the 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 (Alpha)
mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Logical name of the mailbox to be associated with the device. The mbxnam argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) 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, refer to 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, refer to the HP OpenVMS I/O User's Reference Manual.


Description

The Assign I/O Channel service provides a process with an I/O channel so input/output operations can be performed on a device. This service also establishes a logical link with a remote node on a network.

Channels remain assigned until they are explicitly deassigned with the Deassign I/O Channel ($DASSGN) service or, if they are user-mode channels, until the image that assigned the channel exits.

The $ASSIGN service establishes a path to a device but does not check whether the caller can actually perform input/output operations to the device. Privilege and protection restrictions can be applied by the device drivers.

Required Access or Privileges

The calling process must have NETMBX privilege to perform network operations, and system dynamic memory is required if the target device is on a remote system.

Note that you should use the SHARE privilege with caution. Applications, application protocols, and device drivers coded to expect only exclusive access can encounter unexpected and errant behavior when access to the device is unexpectedly shared. Unless the SHARE privilege is explicitly supported by the application, the application protocol, and the device driver, its use is generally discouraged. Refer to the OpenVMS Programming Concepts Manual for additional information.

Required Quota

If the target of the assignment is on a remote node, the process needs sufficient buffer quota to allocate a network control block.

Related Services

$ALLOC, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_REMOTE The service completed successfully. A logical link is established with the target on a remote node.
SS$_ABORT A physical line went down during a network connect operation.
SS$_ACCVIO The device or mailbox name string or string descriptor cannot be read by the caller, or the channel number cannot be written by the caller.
SS$_CONNECFAIL For network operations, the connection to a network object timed out or failed.
SS$_DEVACTIVE You specified a mailbox name, but a mailbox is already associated with the device.
SS$_DEVALLOC The device is allocated to another process.
SS$_DEVNOTMBX You specified a logical name for the associated mailbox, but the logical name refers to a device that is not a mailbox.
SS$_DEVOFFLINE For network operations, the physical link is shutting down.
SS$_EXBYTLM The process has exceeded the byte count quota.
SS$_EXQUOTA The target of the assignment is on a remote node and the process has insufficient buffer quota to allocate a network control block.
SS$_FILALRACC For network operations, a logical link already exists on the channel.
SS$_INSFMEM The target of the assignment is on a remote node and there is insufficient system dynamic memory to complete the request.
SS$_INVLOGIN For network operations, the access control information was found to be invalid at the remote node.
SS$_IVDEVNAM No device name was specified, the logical name translation failed, or the device or mailbox name string contains invalid characters. If the device name is a target on a remote node, this status code indicates that the network connect block has an invalid format.
SS$_IVLOGNAM The device or mailbox name string has a length of 0 or has more than 63 characters.
SS$_LINKEXIT For network operations, the network partner task was started, but exited before confirming the logical link (that is, $ASSIGN to SYS$NET).
SS$_NOIOCHAN No I/O channel is available for assignment.
SS$_NOLINKS For network operations, no logical links are available. The maximum number of logical links as set for the Network Control Program (NCP) executor MAXIMUM LINKS parameter was exceeded.
SS$_NOPRIV For network operations, the issuing task does not have the required privilege to perform network operations or to confirm the specified logical link.
SS$_NOSUCHDEV The specified device or mailbox does not exist, or, for DECnet for OpenVMS operations, the network device driver is not loaded (for example, the DECnet for OpenVMS software is not currently running on the local node).
SS$_NOSUCHNODE The specified network node is nonexistent or unavailable.
SS$_NOSUCHOBJ For network operations, the network object number is unknown at the remote node; for a TASK= connect, the named DCL command procedure file cannot be found at the remote node.
SS$_NOSUCHUSER For network operations, the remote node could not recognize the login information supplied with the connection request.
SS$_PROTOCOL For network operations, a network protocol error occurred, most likely because of a network software error.
SS$_REJECT The network connect was rejected by the network software or by the partner at the remote node, or the target image exited before the connect confirm could be issued.
SS$_REMRSRC For network operations, the link could not be established because system resources at the remote node were insufficient.
SS$_SHUT For network operations, the local or remote node is no longer accepting connections.
SS$_THIRDPARTY For network operations, the logical link connection was terminated by a third party (for example, the system manager).
SS$_TOOMUCHDATA For network operations, the task specified too much optional or interrupt data.
SS$_UNREACHABLE For network operations, the remote node is currently unreachable.

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


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:

  • NSA$_EVENT_TYPE (see Table SYS-17)
  • NSA$_EVENT_SUBTYPE (see Table SYS-17)
  • At least one of the NSA$_ALARM_NAME item code or the NSA$_AUDIT_NAME item code.
  • 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.
  • 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.
  • 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.
  • 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. The following diagram depicts the general structure of an item descriptor:


The following table defines the item descriptor fields:

Descriptor Field Definition
Buffer length A word specifying the length (in bytes) of the buffer; the buffer supplies information to be used by $AUDIT_EVENT. The required length of the buffer varies, depending on the item code specified; each item code description specifies the required length.
Item code A word containing a symbolic code describing the nature of the information currently in the buffer. The location of the buffer is pointed to by the buffer address field. Each item code has a symbolic name. This section provides a detailed description of item codes following the description of arguments.
Buffer address A longword containing the address of the buffer that specifies the information.
Return length address Not currently used; this field is reserved to HP. You must specify 0.

See the Item Codes section for a description of the $AUDIT_EVENT item codes.

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. Item Codes This section provides a list of item codes that can be used to affect auditing.

NSA$_ALARM_NAME

NSA$_ALARM_NAME is a string of 1 to 32 characters specifying an alarm journal name to receive the record. To direct an event to the system alarm journal (that is, all enabled security operator terminals), use the string SECURITY.

NSA$_AUDIT_NAME

NSA$_AUDIT_NAME is a string of 1 to 65 characters specifying the journal file to receive the audit record. To direct an event to the system audit journal, use the string SECURITY.

NSA$_CHAIN

NSA$_CHAIN is a longword value specifying the item list to process immediately after the current one. The buffer address field in the item descriptor specifies the address of the next item list to be processed. Anything after NSA$_CHAIN is ignored.

NSA$_EVENT_FACILITY

NSA$_EVENT_FACILITY is a word value specifying the facility generating the event. All operating system events are audited as facility zero.

NSA$_EVENT_SUBTYPE

NSA$_EVENT_SUBTYPE is a longword value specifying an event message subtype. See Table SYS-17 for a list of valid event subtypes.

NSA$_EVENT_TYPE

NSA$_EVENT_TYPE is a longword value specifying an event message type. See Table SYS-17 for a list of valid event types.

Table SYS-17 Description of$AUDIT_EVENT Types and Subtypes
Symbol of Event Type Meaning
NSA$C_MSG_AUDIT Systemwide change to auditing
Subtype and Meaning
NSA$C_AUDIT_DISABLED
NSA$C_AUDIT_ENABLED
NSA$C_AUDIT_INITIATE
NSA$C_AUDIT_TERMINATE
NSA$C_AUDIT_LOG_FINAL
NSA$C_AUDIT_LOG_FIRST

Audit events disabled
Audit events enabled
Audit server startup
Audit server shutdown
Final entry in audit log (forward link)
First entry in audit log (backward link)
   
NSA$C_MSG_BREAKIN Break-in attempt detected
Subtype and Meaning
NSA$C_DETACHED
NSA$C_DIALUP
NSA$C_LOCAL
NSA$C_NETWORK
NSA$C_REMOTE

Detached process
Dialup interactive process
Local interactive process
Network server process
Interactive process from another network node
   
NSA$C_MSG_CONNECTION Logical link connection or termination
Subtype and Meaning
NSA$C_CNX_ABORT
NSA$C_CNX_ACCEPT
NSA$C_CNX_DECNET_CREATE
NSA$C_CNX_DECNET_DELETE
NSA$C_CNX_DISCONNECT
NSA$C_CNX_IPC_CLOSE
NSA$C_CNX_IPC_OPEN
NSA$C_CNX_REJECT
NSA$C_CNX_REQUEST
NSA$C_CNX_INC_REQUEST
NSA$C_CNX_INC_ACCEPT
NSA$C_CNX_INC_REJECT
NSA$C_CNX_INC_DISCONNECT
NSA$C_CNX_INC_ABORT

Connection aborted
Connection accepted
DECnet for OpenVMS logical link created
DECnet for OpenVMS logical link disconnected
Connection disconnected
Interprocess communication association closed
Interprocess communication association opened
Connection rejected
Connection requested
Incoming connection requested
Incoming connection accepted
Incoming connection rejected
Incoming connection disconnected
Incoming connection aborted
   
NSA$C_MSG_INSTALL Use of the Install utility (INSTALL)
Subtype and Meaning
NSA$C_INSTALL_ADD
NSA$C_INSTALL_REMOVE

Known image installed
Known image deleted
   
NSA$C_MSG_LOGFAIL Login failure
Subtype and Meaning
NSA$C_BATCH
NSA$C_DETACHED
NSA$C_DIALUP
NSA$C_LOCAL
NSA$C_NETWORK
NSA$C_REMOTE
NSA$C_SUBPROCESS

Batch process
Detached process
Dialup interactive process
Local interactive process
Network server process
Interactive process from another network node
Subprocess
   
NSA$C_MSG_LOGIN Successful login
Subtype and Meaning
See subtypes for NSA$C_MSG_
LOGFAIL
 
   
NSA$C_MSG_LOGOUT Successful logout
Subtype and Meaning
See subtypes for NSA$C_MSG_
LOGFAIL
 
   
NSA$C_MSG_MOUNT Volume mount or dismount
Subtype and Meaning
NSA$C_VOL_DISMOUNT
NSA$C_VOL_MOUNT

Volume dismount
Volume mount
   
NSA$C_MSG_NCP Modification to network configuration database
Subtype and Meaning
NSA$C_NCP_COMMAND

Network Control Program (NCP) command issued
   
NSA$C_MSG_NETPROXY Modification to network proxy database
Subtype and Meaning
NSA$C_NETPROXY_ADD
NSA$C_NETPROXY_DELETE
NSA$C_NETPROXY_MODIFY

Record added to network proxy database
Record removed from network proxy database
Record modified in network proxy database
   
NSA$C_MSG_OBJ_ACCESS Object access attempted
Subtype and Meaning
NSA$C_OBJ_ACCESS

Object access attempted
   
NSA$C_MSG_OBJ_CREATE Object created
Subtype and Meaning
NSA$C_OBJ_CREATE

Object created
   
NSA$C_MSG_OBJ_DEACCESS Object deaccessed
Subtype and Meaning
NSA$C_OBJ_DEACCESS

Object deaccessed
   
NSA$C_MSG_OBJ_DELETE Object deleted
Subtype and Meaning
NSA$C_OBJ_DELETE

Object deleted
   
NSA$C_MSG_PROCESS Process control system service issued
Subtype and Meaning
NSA$C_PRC_CANWAK
NSA$C_PRC_CREPRC
NSA$C_PRC_DELPRC
NSA$C_PRC_FORCEX
NSA$C_PRC_GETJPI
NSA$C_PRC_GRANTID
NSA$C_PRC_RESUME
NSA$C_PRC_REVOKID
NSA$C_PRC_SCHDWK
NSA$C_PRC_SETPRI
NSA$C_PRC_SIGPRC
NSA$C_PRC_SUSPND
NSA$C_PRC_WAKE
NSA$C_PRC_PRCTERM

Process wakeup canceled
Process created
Process deleted
Process exit forced
Process information gathered
Process identifier granted
Process resumed
Process identifier revoked
Process wakeup scheduled
Process priority altered
Process exception issued
Process suspended
Process wakeup issued
Process termination notification requested
   
NSA$C_MSG_PRVAUD Attempt to use privilege
Subtype and Meaning
NSA$C_PRVAUD_FAILURE
NSA$C_PRVAUD_SUCCESS

Unsuccessful use of privilege
Successful use of privilege
   
NSA$C_MSG_RIGHTSDB Modification to rights database
Subtype and Meaning
NSA$C_RDB_ADD_ID
NSA$C_RDB_CREATE
NSA$C_RDB_GRANT_ID
NSA$C_RDB_MOD_HOLDER
NSA$C_RDB_MOD_ID
NSA$C_RDB_REM_ID
NSA$C_RDB_REVOKE_ID

Identifier added to rights database
Rights database created
Identifier given to user
List of identifier holders modified
Identifier name or attributes modified
Identifier removed from rights database
Identifier revoked from user
   
NSA$C_MSG_SYSGEN Modification of a system parameter using the System Generation utility (SYSGEN)
Subtype and Meaning
NSA$C_SYSGEN_SET

System parameter modified
   
NSA$C_MSG_SYSTIME Modification to system time
Subtype and Meaning
NSA$C_SYSTIM_SET
NSA$C_SYSTIM_CAL

System time set
System time calibrated
   
NSA$C_MSG_SYSUAF Modification to system user authorization file (SYSUAF)
Subtype and Meaning
NSA$C_SYSUAF_ADD
NSA$C_SYSUAF_COPY
NSA$C_SYSUAF_DELETE
NSA$C_SYSUAF_MODIFY
NSA$C_SYSUAF_RENAME

Record added to SYSUAF
Record copied in SYSUAF
Record deleted from SYSUAF
Record modified in SYSUAF
Record renamed in SYSUAF

NSA$_FIELD_NAME

NSA$_FIELD_NAME is a string of 1 to 256 characters specifying the name of the field being modified. This is used in combination with NSA$_ORIGINAL_DATA and NSA$_NEW_DATA.

NSA$_MESSAGE

NSA$_MESSAGE specifies a system message code. The $FORMAT_AUDIT service will use the $GETMSG service to translate the message into text. The resulting text is inserted into the formatted audit message, with the "Event information:" prefix. For example, the operating system uses this item code to supply the privilege audit text associated with privilege audit events; this keeps the audit records small. By default, the $GETMSG service can only translate resident system messages. You can use the NSA$_MSGFILNAM item code to specify the name of an application or site-specific message file.

NSA$_MSGFILNAM

NSA$_MSGFILNAM is a string of 1 to 255 characters specifying the message file containing the translation for the message code in NSA$_MESSAGE. The default file specification is SYS$MESSAGE:.EXE. By default, $FORMAT_AUDIT uses the resident system message file.

NSA$_NEW_DATA

NSA$_NEW_DATA is a string of 1 to n characters specifying the contents of the field named in NSA$_FIELD_NAME after the event occurred. NSA$_ORIGINAL_DATA contains the field contents prior to the event.

NSA$_NOP

NSA$_NOP specifies that the item list entry should be ignored. This item code allows you to build a static item list and then remove those entries that do not apply to the current event.

NSA$_ORIGINAL_DATA

NSA$_ORIGINAL_DATA is a string of 1 to n characters specifying the contents of the field named in NSA$_FIELD_NAME before the event occurred. NSA$_NEW_DATA contains the field contents following the event.

NSA$_SENSITIVE_FIELD_NAME

NSA$_SENSITIVE_FIELD_NAME is a string of 1 to 256 characters specifying the name of the field being modified. This is used in combination with NSA$_SENSITIVE_ORIG_DATA and NSA$_SENSITIVE_NEW_DATA. Use NSA$_SENSITIVE_FIELD_NAME to prevent sensitive information, such as passwords, from being displayed in an alarm message. Sensitive information is written to the audit log.

NSA$_SENSITIVE_NEW_DATA

NSA$_SENSITIVE_NEW_DATA is a string of 1 to n characters specifying the contents of the field named in NSA$_SENSITIVE_FIELD_NAME after the event occurred. NSA$_SENSITIVE_ORIG_DATA contains the field contents prior to the event. Use NSA$_SENSITIVE_NEW_DATA to prevent sensitive information from being displayed in an alarm message. Sensitive information is written to the audit log.

NSA$_SENSITIVE_ORIG_DATA

NSA$_SENSITIVE_ORIG_DATA is a string of 1 to n characters specifying the contents of the field named in NSA$_SENSITIVE_FIELD_NAME before the event occurred. NSA$_SENSITIVE_NEW_DATA contains the field contents following the event. Use NSA$_SENSITIVE_FIELD_NAME to prevent sensitive information from being displayed in an alarm message. Sensitive information is written to the audit log.

NSA$_SUPPRESS

NSA$_SUPPRESS is a longword bit mask directing $AUDIT_EVENT to ignore the defaults for the following values and either omit the information from the event record or use the value provided in another parameter. The bits in the mask inhibit the use of default values for the following item codes:
NSA$V_ACCOUNT_NAME NAS$V_PROCESS_NAME
NSA$V_FINAL_STATUS NSA$V_SUBJECT_CLASS
NSA$V_IMAGE_NAME NSA$V_SUBJECT_OWNER
NSA$V_PARENT_ID NSA$V_SYSTEM_ID
NSA$V_PARENT_NAME NSA$V_SYSTEM_OWNER
NSA$V_PARENT_OWNER NSA$V_TERMINAL
NSA$V_PARENT_USERNAME NSA$V_TIME_STAMP
NSA$V_PROCESS_ID NSA$V_USERNAME

Use NSA$_SUPPRESS, for example, when auditing events from server processes when the default values for many of these items need to explicitly reference the client context rather than be defaulted from the environment of the server.

The following section provides a list of additional item codes that are valid as an item descriptor in the itmlst argument.

NSA$_ACCESS_DESIRED

NSA$_ACCESS_DESIRED is a longword value specifying the access request mask as defined in $ARMDEF.

NSA$_ACCESS_MODE

NSA$_ACCESS_MODE is a byte value specifying an access mode associated with the event.

NSA$_ACCOUNT

NSA$_ACCOUNT is a string of 1 to 32 characters specifying the account name associated with the event.

NSA$_ASSOCIATION_NAME

NSA$_ASSOCIATION_NAME is a string of 1 to 256 characters specifying an association name.

NSA$_COMMAND_LINE

NSA$_COMMAND_LINE is a string of 1 to 2048 characters specifying a command line.

NSA$_CONNECTION_ID

NSA$_CONNECTION_ID is a longword value specifying a connection identification.

NSA$_DECNET_LINK_ID

NSA$_DECNET_LINK_ID is a longword value specifying a DECnet for OpenVMS logical link identification.

NSA$_DECNET_OBJECT_NAME

NSA$_DECNET_OBJECT_NAME is a string of 1 to 16 characters specifying a DECnet for OpenVMS object name.

NSA$_DECNET_OBJECT_NUMBER

NSA$_DECNET_OBJECT_NUMBER is a longword value specifying a DECnet for OpenVMS object number.

NSA$_DEFAULT_USERNAME

NSA$_DEFAULT_USERNAME is a string of 1 to 32 characters specifying a default local user name for incoming network proxy requests.

NSA$_DEVICE_NAME

NSA$_DEVICE_NAME is a string of 1 to 64 characters specifying the name of the device where the volume resides.

NSA$_DIRECTORY_ENTRY

NSA$_DIRECTORY_ENTRY is a string of 1 to 256 characters specifying the name of the directory entry associated with an XQP operation.

NSA$_DIRECTORY_ID

NSA$_DIRECTORY_ID is an array of three words specifying the directory file identification.

NSA$_DISMOUNT_FLAGS

NSA$_DISMOUNT_FLAGS is a longword value specifying the dismount flags that are defined by the $DMTDEF macro in STARLET.

NSA$_EFC_NAME

NSA$_EFC_NAME is a string of 1 to 16 characters specifying the event flag cluster name.

NSA$_FILE_ID

NSA$_FILE_ID is an array of three words specifying the file identification.

NSA$_FINAL_STATUS

NSA$_FINAL_STATUS is a longword value specifying the successful or unsuccessful status that caused the auditing facility to be invoked.

NSA$_HOLDER_NAME

NSA$_HOLDER_NAME is a string of 1 to 32 characters specifying the name of the user holding the identifier.

NSA$_HOLDER_OWNER

NSA$_HOLDER_OWNER is a longword value specifying the owner (UIC) of the holder.

NSA$_ID_ATTRIBUTES

NSA$_ID_ATTRIBUTES is a longword value specifying the attributes of the identifier, which are defined by the $KGBDEF macro in STARLET.

NSA$_IDENTIFIERS_USED

NSA$_IDENTIFIERS_USED is an array of longwords specifying the identifiers (from the access control entry [ACE] granting access) that were used to gain access to the object.

NSA$_ID_NAME

NSA$_ID_NAME is a string of 1 to 32 characters specifying the name of the identifier.

NSA$_ID_NEW_ATTRIBUTES

NSA$_ID_NEW_ATTRIBUTES is a longword value specifying the new attributes of the identifier, which are defined by the $KGBDEF macro in STARLET.

NSA$_ID_NEW_NAME

NSA$_ID_NEW_NAME is a string of 1 to 32 characters specifying the new name of the identifier.

NSA$_ID_NEW_VALUE

NSA$_ID_NEW_VALUE is a longword value specifying the new value of the identifier.

NSA$_ID_VALUE

NSA$_ID_VALUE is a longword value specifying the value of the identifier.

NSA$_ID_VALUE_ASCII

NSA$_ID_VALUE_ASCII is a longword specifying the value of the identifier.

NSA$_IMAGE_NAME

NSA$_IMAGE_NAME is a string of 1 to 1024 characters specifying the name of the image being executed when the event took place.

NSA$_INSTALL_FILE

NSA$_INSTALL_FILE is a string of 1 to 255 characters specifying the name of the installed file.

NSA$_INSTALL_FLAGS

NSA$_INSTALL_FLAGS is a longword value specifying the INSTALL flags. They correspond to qualifiers for the Install utility; for example, NSA$M_INS_EXECUTE_ONLY.

NSA$_LNM_PARENT_NAME

NSA$_LNM_PARENT_NAME is a string of 1 to 31 characters specifying the name of the parent logical name table.

NSA$_LNM_TABLE_NAME

NSA$_LNM_TABLE_NAME is a string of 1 to 31 characters specifying the name of the logical name table.

NSA$_LOCAL_USERNAME

NSA$_LOCAL_USERNAME is a string of 1 to 32 characters specifying user names of the accounts available for incoming network proxy requests.

NSA$_LOGICAL_NAME

NSA$_LOGICAL_NAME is a string of 1 to 255 characters specifying the logical name associated with the device.

NSA$_MAILBOX_UNIT

NSA$_MAILBOX_UNIT is a longword value specifying the mailbox unit number.

NSA$_MATCHING_ACE

NSA$_MATCHING_ACE is an array of bytes specifying the ACE granting or denying access.

NSA$_MOUNT_FLAGS

NSA$_MOUNT_FLAGS is a quadword value specifying mount flags that are defined by the $MNTDEF macro in STARLET.

NSA$_NEW_IMAGE_NAME

NSA$_NEW_IMAGE_NAME is a string of 1 to 1024 characters specifying the name of the new image.

NSA$_NEW_OWNER

NSA$_NEW_OWNER is a longword value specifying the new process owner (UIC).

NSA$_NEW_PRIORITY

NSA$_NEW_PRIORITY is a longword value specifying the new process priority.

NSA$_NEW_PRIVILEGES

NSA$_NEW_PRIVILEGES is a quadword privilege mask specifying the new privileges. The $PRVDEF macro defines the list of available privileges.

NSA$_NEW_PROCESS_ID

NSA$_NEW_PROCESS_ID is a longword value specifying the new process identification.

NSA$_NEW_PROCESS_NAME

NSA$_NEW_PROCESS_NAME is a string of 1 to 15 characters specifying the name of the new process.

NSA$_NEW_PROCESS_OWNER

NSA$_NEW_PROCESS_OWNER is a longword value specifying the owner (UIC) of the new process.

NSA$_NEW_USERNAME

NSA$_NEW_USERNAME is a string of 1 to 32 characters specifying the new user name.

NSA$_OBJECT_CLASS

NSA$_OBJECT_CLASS is a string of 1 to 23 characters specifying the security object class associated with the event; for example, FILE.

NSA$_OBJECT_ID

NSA$_OBJECT_ID is an array of three words specifying the unique object identification code, which is currently applicable only to files; therefore, it is the file identification.

NSA$_OBJECT_MAX_CLASS

NSA$_OBJECT_MAX_CLASS is a 20-byte record specifying the maximum access classification of the object.

NSA$_OBJECT_MIN_CLASS

NSA$_OBJECT_MIN_CLASS is a 20-byte record specifying the minimum access classification of the object.

NSA$_OBJECT_NAME

NSA$_OBJECT_NAME is a string of 1 to 255 characters specifying an object's name.

NSA$_OBJECT_NAME_2

NSA$_OBJECT_NAME_2 is a string of 1 to 255 characters specifying an alternate object name; currently it applies to file-backed global sections where the alternate name of a global section is the file name.

NSA$_OBJECT_OWNER

NSA$_OBJECT_OWNER is a longword value specifying the UIC or general identifier of the process causing the auditable event.

NSA$_OBJECT_PROTECTION

NSA$_OBJECT_PROTECTION is a word, or an array of four longwords, specifying the UIC-based protection of the object.

NSA$_OLD_PRIORITY

NSA$_OLD_PRIORITY is a longword value specifying the former process priority.

NSA$_OLD_PRIVILEGES

NSA$_OLD_PRIVILEGES is a quadword privilege mask specifying the former privileges. The $PRVDEF macro defines the list of available privileges.

NSA$_PARAMS_INUSE

NSA$_PARAMS_INUSE is a string of 1 to 255 characters specifying the name of the parameter file given to the SYSGEN command USE.

NSA$_PARAMS_WRITE

NSA$_PARAMS_WRITE is a string of 1 to 255 characters specifying the file name for the SYSGEN command WRITE.

NSA$_PARENT_ID

NSA$_PARENT_ID is a longword value specifying the process identification (PID) of the parent process. It is used only when auditing events pertaining to a subprocess.

NSA$_PARENT_NAME

NSA$_PARENT_NAME is a string of 1 to 15 characters specifying the parent's process name. It is used only when auditing events pertaining to a subprocess.

NSA$_PARENT_OWNER

NSA$_PARENT_OWNER is longword value specifying the owner (UIC) of the parent process. It is used only when auditing events pertaining to a subprocess.

NSA$_PARENT_USERNAME

NSA$_PARENT_USERNAME is a string of 1 to 32 characters specifying the user name associated with the parent process. It is used only when auditing events pertaining to a subprocess.

NSA$_PASSWORD

NSA$_PASSWORD is a string of 1 to 32 characters specifying the password used in an unsuccessful break-in attempt. By default, system security alarms do not include break-in passwords.

NSA$_PRIVILEGES

NSA$_PRIVILEGES is a quadword privilege mask specifying the privileges used to gain access. The $PRVDEF macro defines the list of available privileges.

NSA$_PRIVS_MISSING

NSA$_PRIVS_MISSING is a longword or a quadword privilege mask specifying the privileges that are needed. The privileges are defined by a macro in STARLET; see the $CHPDEF macro for definition as a longword mask, and see the $PRVDEF macro for definition as a quadword privilege mask.

NSA$_PRIVS_USED

NSA$_PRIVS_USED is a longword or a quadword privilege mask specifying the privileges used to gain access to the object. The privileges are defined by a macro in STARLET; see the $CHPDEF macro for definition as a longword mask and see the $PRVDEF macro for definition as a quadword privilege mask.

NSA$_PROCESS_ID

NSA$_PROCESS_ID is a longword value specifying the PID of the process causing the auditable event.

NSA$_PROCESS_NAME

NSA$_PROCESS_NAME is a string of 1 to 15 characters specifying the process name that caused the auditable event.

NSA$_REM_ASSOCIATION_NAME

NSA$_REM_ASSOCIATION_NAME is a string of 1 to 256 characters specifying the interprocess communication (IPC) remote association name.

NSA$_REMOTE_LINK_ID

NSA$_REMOTE_LINK_ID is a longword value specifying the remote logical link ID.

NSA$_REMOTE_NODE_FULLNAME

NSA$_REMOTE_NODE_FULLNAME is a string of 1 to 255 characters specifying the fully expanded DECnet for OpenVMS node name of the remote process.

NSA$_REMOTE_NODE_ID

NSA$_REMOTE_NODE_ID is a string of 4 to 24 characters specifying the DECnet for OpenVMS node address of the remote process. A value 4 bytes in length is a DECnet Phase IV node address. A value with length greater than 4 bytes is a DECnet/OSI NSAP address.

NSA$_REMOTE_NODENAME

NSA$_REMOTE_NODENAME is a string of 1 to 6 characters specifying the DECnet for OpenVMS node name of the remote process.

NSA$_REMOTE_USERNAME

NSA$_REMOTE_USERNAME is a string of 1 to 32 characters specifying the user name of the remote process.

NSA$_REQUEST_NUMBER

NSA$_REQUEST_NUMBER is a longword value specifying the request number associated with the system service call.

NSA$_RESOURCE_NAME

NSA$_RESOURCE_NAME is a string of 1 to 32 characters specifying the lock resource name.

NSA$_SECTION_NAME

NSA$_SECTION_NAME is a string of 1 to 42 characters specifying the global section name.

NSA$_SNAPSHOT_BOOTFILE

NSA$_SNAPSHOT_BOOTFILE is a string of 1 to 255 characters specifying the name of the snapshot boot file, the saved system image file from which the system just booted.

NSA$_SNAPSHOT_SAVE_FILNAM

NSA$_SNAPSHOT_SAVE_FILNAM is a string of 1 to 255 characters specifying the name of the snapshot save file, which is the original location of the snapshot file at the time that the system was saved.

NSA$_SNAPSHOT_TIME

NSA$_SNAPSHOT_TIME is a quadword value specifying the time the picture of the configuration was taken and saved in the snapshot boot file.

NSA$_SOURCE_PROCESS_ID

NSA$_SOURCE_PROCESS_ID is a longword value specifying the process identification of the process originating the request.

NSA$_SUBJECT_CLASS

NSA$_SUBJECT_CLASS is a 20-byte record specifying the current access class of the process causing the auditable event.

NSA$_SUBJECT_OWNER

NSA$_SUBJECT_OWNER is a longword value specifying the owner (UIC) of the process causing the event.

NSA$_SYSTEM_ID

NSA$_SYSTEM_ID is a longword value specifying the SCS identification of the cluster node where the event took place (system parameter SCSSYSTEMID).

NSA$_SYSTEM_NAME

NSA$_SYSTEM_NAME is a string of 1 to 6 characters specifying the System Communications Services (SCS) node name where the event took place (system parameter SCSNODE).

NSA$_SYSTEM_SERVICE_NAME

NSA$_SYSTEM_SERVICE_NAME is a string of 1 to 256 characters specifying the name of the system service associated with the event.

NSA$_SYSTIM_NEW

NSA$_SYSTIM_NEW is a quadword value specifying the new system time.

NSA$_SYSTIM_OLD

NSA$_SYSTIM_OLD is a quadword value specifying the old system time.

NSA$_TARGET_DEVICE_NAME

NSA$_TARGET_DEVICE_NAME is a string of 1 to 64 characters specifying the target device name.

NSA$_TARGET_PROCESS_CLASS

NSA$_TARGET_PROCESS_CLASS is a 20-byte record specifying the target process classification.

NSA$_TARGET_PROCESS_ID

NSA$_TARGET_PROCESS_ID is a longword value specifying the target process identifier (PID).

NSA$_TARGET_PROCESS_NAME

NSA$_TARGET_PROCESS_NAME is a string of 1 to 64 characters specifying the target process name.

NSA$_TARGET_PROCESS_OWNER

NSA$_TARGET_PROCESS_OWNER is a longword value specifying the target owner (UIC).

NSA$_TARGET_USERNAME

NSA$_TARGET_USERNAME is a string of 1 to 32 characters specifying the target process user name.

NSA$_TERMINAL

NSA$_TERMINAL is a string of 1 to 256 characters specifying the name of the terminal to which the process was connected when the auditable event occurred.

NSA$_TIME_STAMP

NSA$_TIME_STAMP is a quadword value specifying the time when the event occurred.

NSA$_TRANSPORT_NAME

NSA$_TRANSPORT_NAME is a string of 1 to 256 characters specifying the name of the transport: interprocess communication, DECnet for OpenVMS, or System Management Integrator (SMI), which handles requests from SYSMAN (ASCII string).

NSA$_UAF_ADD

NSA$_UAF_ADD is a string of 1 to 32 characters specifying the name of the authorization record being added.

NSA$_UAF_COPY

NSA$_UAF_COPY is a string of 1 to 32 characters specifying the new name of the authorization record being copied from NSA$_UAF_SOURCE.

NSA$_UAF_DELETE

NSA$_UAF_DELETE is a string of 1 to 32 characters specifying the name of the authorization record being removed.

NSA$_UAF_MODIFY

NSA$_UAF_MODIFY is a string of 1 to 32 characters specifying the name of the authorization record being modified.

NSA$_UAF_RENAME

NSA$_UAF_RENAME is a string of 1 to 32 characters specifying the name of the authorization record being renamed.

NSA$_UAF_SOURCE

NSA$_UAF_SOURCE is a string of 1 to 32 characters specifying the user name of the source record for an Authorize utility (AUTHORIZE) copy operation.

NSA$_USERNAME

NSA$_USERNAME is a string of 1 to 32 characters specifying the user name of the process causing the auditable event.

NSA$_VOLUME_NAME

NSA$_VOLUME_NAME is a string of 1 to 15 characters specifying a volume name.

NSA$_VOLUME_SET_NAME

NSA$_VOLUME_SET_NAME is a string of 1 to 15 characters specifying a volume set name.

Description

The Audit Event service can be called by any program that enforces a security policy to append an event message to the audit log file or send an alarm to an operator terminal. For example, AUTHORIZE calls $AUDIT_EVENT whenever a UAF record is altered, and LOGINOUT calls the service whenever a user logs in.

$AUDIT_EVENT takes the event message, checks the auditing database to determine whether a class of event is being audited, and, if the event class is enabled, creates an alarm or audit record.

$AUDIT_EVENT completes asynchronously; that is, it does not wait for final status. For synchronous completion, use the $AUDIT_EVENTW service.

Required Access or Privileges

AUDIT

Required Quota

None

Related Services

$CHECK_ACCESS, $CHECK_PRIVILEGE, $CHKPRO


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO A parameter is not accessible.
SS$_BADBUFADR The buffer address is invalid or not readable.
SS$_BADBUFLEN The specified buffer length is invalid or out of range.
SS$_BADCHAIN The address of the next item list to be processed, as identified in the buffer address field, is either not readable or points to itself.
SS$_BADITMCOD The specified item code is invalid or out of range.
SS$_EVTNOTENAB The event is not enabled.
SS$_INSFARG A required item code or parameter is missing.
SS$_INVAJLNAM The alarm or audit journal name is invalid.
SS$_IVSTSFLG The specified system service flags are invalid.
SS$_NOAUDIT The caller does not have the required privilege to perform the audit.
SS$_OVRMAXAUD There is insufficient memory to perform the audit.
SS$_SYNCH An audit was not required.


Next Contents Index