HP OpenVMS Systems Documentation
HP OpenVMS Programming Concepts Manual
33.3 SYS$ACM[W] Call Mechanics
The HP OpenVMS System Services Reference Manual: A--GETUAI provides a comprehensive reference to various values
and structures used to call the SYS$ACM[W] system service.
This section describes just some of those.
33.3.2 SYS$ACM[W] Function Modifiers
The first function modifier is equally applicable to all function codes:
The second set of function modifiers consists of those particularly intended for the Authenticate Principal and Change Password function codes:
33.3.3 Status Returned by the SYS$ACM[W] System Service
The SYS$ACM[W] system service follows the standard pattern of returning a 32-bit
status value, but that return status indicates only
whether the call was accepted for transmission to the ACME server process.
188.8.131.52 When the Return Status Indicates Success
In cases where the return status indicates success, your program can determine the overall resultant effect of a call to the SYS$ACM[W] system service by examining the contents of fields within the ACMESB structure it provided via the ACMSB argument. The following table describes the fields and their contents:
If no special value is appropriate for the ACMESB$L_SECONDARY_STATUS field, it contains the same value as the ACMESB$L_STATUS. Thus, your program should check to see if the two are equal rather than reporting them both as separate status values.
The values in fields ACMESB$L_STATUS and ACMESB$L_SECONDARY_STATUS,
along with the value in ACMESB$L_ACME_STATUS if provided, all
indicate the same success. For ACMESB$L_STATUS and
that means that the low-order bits will either both be set (success) or
both be cleared (failure). Because ACMESB$L_ACME_STATUS syntax is
determined on an ACME-specific basis, the success or failure semantics
of that value provided in that longword will match that for the other
In those cases, the field ACMESB$L_ACME_STATUS contains the item code
for the item
on which the problem was encountered.
When the primary status contains ACME$_OPINCOMPL,
your program must make at least one more call to the SYS$ACM[W] system service,
based on the data in the ACM communications buffer, as discussed
in Section 33.3.6.
Item codes provided to the SYS$ACM[W] system service can be characterized by
particular bit patterns that indicate their type and purpose.
Item codes provided to the SYS$ACM[W] system service have a theoretical range from 1 to 65535 and are divided into the following groups:
Another way of making that distinction is to say that bit 15 of the item code indicates whether the item code is ACME-specific.
While the common item codes are defined once for all ACME agents, the ACME-specific item codes are defined separately by each ACME agent, as shown in Figure 33-2, Item List Chain. When the SYS$ACM[W] system service encounters an ACME-specific item code, it attributes it to whichever ACME agent was most recently mentioned with one of the following item codes:
If none of those item codes have been specified before the first
ACME-specific item code, the SYS$ACM[W] system service returns a primary status of
Bit 14 of the item code indicates whether the item code is for an output item. If the bit is clear, it is for an input item.
The SYS$ACM[W] system service does not return data for output items until the
final successful completion of an operation. For Authenticate Principal
and Change Password operations, that could be after many intervening
calls to the SYS$ACM[W] system service.
Bit 13 of the item code indicates whether the item code is a text item, and thus susceptible to Unicode translation. Your program can call the SYS$ACM[W] system service either with or without the ACME$M_UCS2_4 function modifier. If that function modifier is present, it means your program is supplying unicode character set (UCS) data for item codes that have bit 13 set. If the function modifier is missing, your program is supplying Latin-1 (similar to ASCII) characters for those item codes. The SYS$ACM[W] system service uses the encoding of the function code to determine which input items it should translate from Latin-1 to UCS for input items, and in the reverse direction for output items.
The setting of bit 13 in an item code gives another important
indication for dialogue mode operations. For an ACME agent
to ask for input from an arbitrary ACM client program, it must be clear
that the ACM client program is capable of handling the data format to
be used for input. At the present time, character-string data is the
only such input that is understood by all ACM client programs.
An ACME agent can only ask for dialogue items that
have bit 13 set.
The SYS$ACM[W] system service always honors the well-known items
Even in dialogue mode, your first call to
the SYS$ACM[W] system service must specify all required input items and desired
output items except for those input items that the SYS$ACM[W] system service will
specify with a subsequent input itemset entry
in the ACM communications buffer.
The item list you pass to the SYS$ACM[W] system service can be built from as many as 32 different item list segments, each of which can be composed of traditional 32-bit ILE3 items or 64-bit ILEB_64 items. All items in a single item list segment must be of the same type. Figure 33-2 illustrates an item list chain.
Figure 33-2 Item List Chain
33.3.6 The ACM Communications Buffer and Itemset
For dialogue mode calls using Authenticate Principal or Change Password function codes, the SYS$ACM[W] system service may return a primary status of ACME$_OPINCOMPL, indicating more data is needed. In that case, a description of the data needed is provided within the ACM communications buffer pointed to from the ACM context argument longword you supplied.
Field ACMECB$L_ITEM_SET_COUNT indicates how many entries are in the itemset, while field ACMECB$PS_ITEM_SET points to an array of itemset entries, as shown in Figure 33-3.
Figure 33-3 Itemset Layout
33.3.7 Itemset Entries
Within a single itemset entry, when the flag ACMEDLOGFLG$V_INPUT is set in field ACMEIS$L_FLAGS, the third field is called ACMEIS$W_MAX_LENGTH and indicates the maximum acceptable length in bytes for the input requested.
When the flag ACMEDLOGFLG$V_INPUT is clear, however, the third field is called ACMEIS$W_MSG_TYPE and indicates the message category of the output text. That category can be used to decide placement or presentation of output text for a user. Bit 14 of that code, like bit 13 of an item code, indicates that the data in question (output data in this case) is textual in nature and your program can handle it using methods appropriate for text.
Because there is no ACMEIS$W_MSG_TYPE field when flag
is set, the SYS$ACM[W] system service performs Unicode conversion
of prompting information based on whether or not the resulting input
data is eligible for Unicode conversion. Thus, it is not possible to
have multiple text formats in prompts with the corresponding input.
As with many other system services, you have your choice of the SYS$ACM
or SYS$ACMW interface. Choose one or the other
based on whether your program will be doing other work
(authentication-related or otherwise) while the authentication
operation is underway. This choice has only to do with synchronization
within your program; it is unrelated to your choice of dialogue mode
or nondialogue mode.
Your program can call the SYS$ACM[W] system service to log an event or to query
for information specific to a particular domain of interpretation (DOI).
With the exception of the general ACM information described in
Section 184.108.40.206, Looking Up DOI and ACME IDs, all use of the Event or Query function codes is
specific to a DOI.
The simplest form of call to the SYS$ACM[W] system service is the nondialogue mode call, illustrated in Figure 33-4. It resembles many other system services, except that the item list contains a wider variety of both input and output items.
Figure 33-4 Nondialogue Mode Operation
Use nondialogue mode
when only a limited amout of interaction is possible, such as when an
existing network protocol like FAL or FTP does not allow an arbitrary
authentication exchange. Typically, such programs should specify an
of ACME$K_NETWORK, indicating that while they supply
a password, no complex interaction is possible.
Use dialogue mode when your ACM client program is flexible enough to respond to password change notification, to allow the user to answer arbitrary questions, such as the charge code for a session, and so on.
In dialogue mode, the SYS$ACM[W] system service uses the longword you provide by the ACM context argument parameter to store a pointer to an ACM communications buffer. Figure 33-5 illustrates dialogue mode operation.
Figure 33-5 Dialogue Mode
As with nondialogue mode, your ACM client program must provide on the initial call to the SYS$ACM[W] system service all output items and all input items that are not going to be the subject of an itemset entry.
On intermediate returns, where the SYS$ACM[W] system service provides the primary status ACME$_OPINCOMPL in ACMESB$L_STATUS, it also creates an itemset within the ACM communications buffer indicating what further information exchange is required. The action your program should take depends upon the nature of each itemset entry within the itemset as follows:
Dialogue mode operation applies only to the Authenticate
Principal and Change Password functions. Calls to any other functions
must be in nondialogue mode.
The OpenVMS Guide to System Security outlines the following login categories and login classes that are of interest for calling the SYS$ACM[W] system service:
Those login classes correspond to the values used in the ACME$_LOGON_TYPE item for the SYS$ACM[W] system service. Each may have specific policy requirements, and may be authenticated differently. Batch jobs, for example, start without specification of a password or other authentication information.
This choice can also influence authorization decisions, such as the VMS day and time restrictions.
Thus in the case of the local, dialup, or remote values for ACME$_LOGON_TYPE, you must provide an ACM context argument argument on all calls to the SYS$ACM[W] system service (and you must provide item ACME$_DIALOGUE_SUPPORT on the initial call to indicate support for input dialogue). With the network value for ACME$_LOGON_TYPE, those elements might be required with certain add-on ACME agents.