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

Number of the event flag that is set when the service completes. If this argument is omitted, event flag 0 is used.

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

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

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.

AST parameter that is passed to the AST routine specified by the astadr argument.

Identifier of the transaction to be aborted.

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

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 2. The default value for this argument is DDTM$_ABORTED.

bid

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.

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

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

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

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

Reserved to OpenVMS. This argument must be zero.

The identifier of the event report being acknowledged by this call to $ACK_EVENT.

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

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.

Reserved to OpenVMS.

Reserved to OpenVMS.

The name of the new RM participant that is added to the transaction by this call to $ACK_EVENT. This argument is ignored unless the event being acknowledged is of type Transaction Started and the value of the report_reply argument is SS$_NORMAL.

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

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

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

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.

Reserved to OpenVMS.

Description

The $ACK_EVENT system service:

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

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

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.

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.

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.

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 diagram depicts the format of an item set entry:

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:

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

acmsb

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:

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.

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.

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.

AST parameter to be passed to the AST service routine specified by the astprm argument. The astprm argument is the longword parameter.

Function Codes

See the section called “Description” 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:

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

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:

See the section called “Common Item Codes” 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 section called “VMS ACME-Specific Item Codes”.

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.

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

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 Alpha and Integrity servers platforms, both 32- 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.

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 VSI OpenVMS Programming Concepts Manual.

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

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

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

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

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

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.

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

Authentication Common Output Message Categories

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.

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.

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:

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.

Condition Values Returned

Condition Values Returned in the ACM Status Block

Status Codes and Function Codes Table

VMS ACME Use of Function Codes

The VMS ACME use of the Event function is reserved to OpenVMS.

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.

SYS$CREPRC-Ready Item Codes

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

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 SYS$CREPRC 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 SYS$CREPRC 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 SYS$CREPRC 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 SYS$CREPRC bit or the presence of the ACMEVMS$_GENPWD_MANDATORY_FLAG input item code.

Backward Compatibility Item Codes

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:

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.

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

he 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, see the SYS$GETUAI system service in the VSI 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.

* 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

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

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 Request or 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 Request or 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 request or 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

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.

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.

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

Description

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

These changes are the following:

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

The 64-bit lock handle that identifies the lock to be acquired. This value is returned by SYS$CREATE_GALAXY_LOCK.

The 32-bit wait or spin timeout specified in 10 microsecond units. If not specified, defaults to 10 microseconds.

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

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

Number of the event flag that is set when the service completes. If this argument is omitted, event flag 0 is used.

The I/O status block in which the completion status of the service is returned as a condition value. See the section called “Condition Values Returned”.

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

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.

The AST parameter that is passed to the AST routine specified by the astadr argument.

The identifier (TID) of the transaction for which a new branch is to be authorized.

The name of the node on which the new branch is running. Note that this cannot be a cluster alias.

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

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:

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:

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

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

Format

SYS$ADD_HOLDER id ,holder ,[attrib]

C Prototype

int sys$add_holder
   (unsigned int id, struct _generic_64 *holder, unsigned int attrib);

Arguments

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

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.

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

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 VSI OpenVMS Record Management Services Reference Manual.

Format

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

Prototype

int sys$add_ident
   (void *name, unsigned int id, unsigned int attrib, unsigned int *resid);

Arguments

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.

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.

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.

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

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 VSI OpenVMS Record Management Services Reference Manual.

Format

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

Prototype

int sys$add_proxy
   (void *rem_node, void *rem_user, void  *local_user,
    unsigned int flags);

Arguments

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.

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

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.

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

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:

Format

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

C Prototype

int sys$adjstk (unsigned int acmode, short int adjust, void  *(*(newadr)));

Arguments

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.

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 section called “Description”.

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 section called “Description”.

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.

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

Format

SYS$ADJWSL [pagcnt] ,[wsetlm]

C Prototype

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

Arguments

Signed adjustment value specifying the number of pagelets to add to (if positive) or subtract from (if negative) the current working set limit. The pagcnt argument is this signed longword value.

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

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

Value of the working set limit, in pagelets , returned by $ADJWSL. The wsetlm argument is the 32- or 64-bit address of this longword value. The wsetlm argument receives the newly adjusted value if pagcnt is specified, and it receives the prior, unadjusted value if pagcnt is not specified.

Description

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

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

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

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.

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.

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.

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.

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.