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);
1 – Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag that is set when the $ACM request
completes. The efn argument is a longword containing this number;
however, $ACM uses only the low-order byte.
When the request is queued, $ACM clears the specified event flag.
Then, when the request completes, the specified event flag is
set.
func
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by value
Function code and modifiers specifying the operation that $ACM
is to perform. The func argument is a longword containing the
function code, logically 'OR'ed together with the modifiers.
For some programming languages this may be defined as a record
structure.
Function codes have symbolic names of the following format:
ACME$_FC_code
Function modifiers have symbolic names of the following format:
ACME$M_modifier
The language support mechanisms specific to each programming
language define the names of each function code and modifier.
Only one function code can be specified across a dialogue
sequence of related calls to $ACM.
Most function codes require or allow additional information to
be passed in the call. This information is passed using the
itmlst argument, which specifies a list of one or more item
descriptors. Each item descriptor in turn specifies an item code,
which either controls the action to be performed, or requests
specific information to be returned.
context
OpenVMS usage:context
type: longword pointer (signed)
access: modify
mechanism: by 32- or 64-bit reference
Address of a longword to receive the 32-bit address of an ACM
communications buffer.
$ACM uses the ACM communications buffer for dialogue functions
(ACME$_FC_AUTHENTICATE_PRINCIPAL and ACME$_FC_CHANGE_PASSWORD)
to request that the caller provide additional information in a
subsequent call.
The context argument on a continuation call must contain the
same ACM communications buffer address returned by $ACM on the
previous call. The itmlst provided on a continuation call must
contain entries to fulfill each of the input item set entries in
the ACM communications buffer returned by $ACM on the previous
call.
The longword specified must contain a -1 on the first call in a
dialogue sequence of related calls. If additional information is
required to complete the request, $ACM returns a pointer in the
context argument to an ACM communications buffer that describes
the information. To continue with the particular operation call,
$ACM again specifying the function argument previously provided.
The ACM communications buffer is user readable, but not user
writable. It consists of a structure header, an item set, and
a string buffer segment. The item set is an array of item set
entries, each describing an item of information that is needed
to complete the request or information that can be reported to a
human user.
$ACM presents the item set entries in the logical presentation
order for a sequential interface, so calling programs that
give a sequential view to the user should process the item set
entries in that $ACM order. More advanced GUI programs may use
simultaneous presentation with distinctive placement for various
message types.
To view the diagram of the overall format of an ACM
communications buffer, see the VSI OpenVMS System Services
Reference Manual.
To view the format of an item set entry and descriptor table, see
the VSI OpenVMS System Services Reference Manual.
itmlst
OpenVMS usage:32-bit item_list_3 or 64-bit item_list_64b
type: longword (unsigned) for 32-bit; quadword (unsigned)
for 64-bit
access: read only
mechanism: by 32- or 64-bit reference
Item list specifying information to be used in performing
the function and requesting information to be returned. The
itmlst argument is the 32- or 64-bit address of a list of item
descriptors, describing an item of information. An item list in
32-bit format is terminated by a longword of 0; an item list in
64-bit format is terminated by a quadword of 0.
The item list can be composed of up to 32 segments, connected by
a chain item (using item code ACME$_CHAIN) at the end of all but
the last segment pointing to the start of the next segment. All
item descriptors in a single segment must be of the same format
(32-bit or 64-bit), but a single item list can contain a mixture
of segments composed of 32-bit item descriptors and segments
composed of 64-bit item descriptors.
To view the 32-bit and 64-bit item code diagrams and descriptor
fields tables, see the VSI OpenVMS System Services Reference
Manual.
In an item list, no ACME-specific item codes can be included in
an item list until the ACME Context has been set with one of the
following codes:
ACME$_CONTEXT_ACME_ID
ACME$_CONTEXT_ACME_NAME
You can also implicitly set the ACME Context with one of the
following codes:
ACME$_TARGET_DOI_ID
ACME$_TARGET_DOI_NAME
These codes are described in the VSI OpenVMS Programming Concepts
Manual.
acmsb
OpenVMS usage:acm_status_block
type: octaword array of 4 longwords
access: write only
mechanism: by 32- or 64-bit reference
ACM status block that is to receive the final completion status.
The acmsb argument is the 32- or 64-bit address of the ACM status
block.
To view the structure of an ACM status block and descriptor field
definitions, see the VSI OpenVMS System Services Reference Manual.
Upon request initiation, $ACM sets the value of all fields
within the ACM status block to 0. When the requested operation
completes. The $ACM service writes condition values into the
ACMESB$L_STATUS and ACMESB$L_SECONDARY_STATUS fields.
If the status in the ACMESB$L_STATUS field is ACME$_AUTHFAILURE,
that is the only result that should be displayed or otherwise
made known to a user. The status in ACMESB$L_SECONDARY_STATUS
(when the caller has the SECURITY privilege, or is calling from
kernel or executive mode) contains the detailed reason for the
failure, which may be used for purposes that do not disclose the
code to the user, such as the process termination code supplied
to $DELPRC (but not the image exit code supplied to $EXIT).
Otherwise, the status in ACMESB$L_SECONDARY_STATUS should be
considered as subsidiary to that in ACMESB$L_STATUS and used to
form a chained message, unless the two cells contain identical
values.
In either case, the caller of $ACM[W] can rely on the success bit
(bit 0) of the ACMESB$L_STATUS and the ACMESB$L_SECONDARY_STATUS
field having the same setting. Either both low-order bits will be
set (success) or both will be clear (failure).
The ACMESB$L_ACME_STATUS field is valid only when the contents
of the ACMESB$L_ACME_ID field are nonzero, indicating which ACME
agent supplied the (possibly zero) value in ACMESB$L_ACME_STATUS.
There is one special format for such data in ACMESB$L_ACME_
STATUS. If $ACM rejects the request because of a bad entry in
the item list, then ACMESB$L_STATUS contains one of the following
codes:
SS$_BADPARAM Incorrect contents for the item code
SS$_ Incorrect item code for the function
BADITMCOD
SS$_ Incorrect length for the item code
BADBUFLEN
If ACMESB$L_STATUS contains one of the listed returns, then
ACME$L_ACME_STATUS contains the item code from the incorrect
item, which is an aid to debugging.
In all other cases, the value delivered in ACME$L_ACME_STATUS is
specific to the ACME agent that failed the request. An ACME agent
can return a longword value that indicates additional information
about the operation. $ACM writes this value in the ACMESB$L_ACME_
STATUS field of the ACM status block.
In these cases, you can expect the success of a valid value (one
where ACMESB$L_ACME_ID is not zero) in field ACMESB$L_ACME_STATUS
to match the "success" bits (bit 0) in fields ACMESB$L_STATUS and
ACMESB$L_SECONDARY_STATUS, although what constitutes a "success"
value in ACMESB$L_ACME_STATUS is subject to that interpretation
specified for the ACME agent that set the value. In particular,
the values in the ACMESB$L_ACME_STATUS field from certain ACME
Agents might not be a VMS-style message code.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference
AST service routine to be executed when $ACM completes. The
astadr argument is the 32- or 64-bit address of this routine.
The AST routine executes at the same access mode as the caller of
the $ACM service.
astprm
OpenVMS usage:user_arg
type: quadword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST service routine specified
by the astprm argument. The astprm argument is the longword
parameter.