hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems

Jump to content

HP OpenVMS Programming Concepts Manual

HP OpenVMS Programming Concepts Manual

Previous Contents Index

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.1 SYS$ACM[W] Function Codes

When your ACM client program calls the SYS$ACM[W] system service, it must specify one of the following function codes to indicate which capability is to be invoked:

33.3.2 SYS$ACM[W] Function Modifiers

When your ACM client program calls the SYS$ACM[W] system service, it may specify a combination of the following function codes to request variations in the basic processing.

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. When the Return Status Indicates Failure

If the return status is the failure code ACME$_INVALIDCTX and your program was attempting to continue with an ongoing dialogue mode request, the possible causes of this failure are the following: 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:
Field Name Data Type Contents
ACMESB$L_STATUS VMS Status Code The primary status regarding the success of an operation.
ACMESB$L_SECONDARY_STATUS VMS Status Code An auxiliary status to further explain the primary status.
ACMESB$L_ACME_ID ACME ID Type The identity of the ACME agent that provided information for this status block.
ACMESB$L_ACME_STATUS ACME-specific A status using a format specific to the particular ACME agent.

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 ACMESB$L_SECONDARY_STATUS, 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 two fields. When the Primary Status Indicates an Item Code Failure

There is a special case when an error with an item code causes the SYS$ACM[W] system service to return one of the following values in the ACMESB$L_STATUS field:

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 is ACME$_OPINCOMPL

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.

33.3.4 Item Codes

Item codes provided to the SYS$ACM[W] system service can be characterized by particular bit patterns that indicate their type and purpose. Common vs. ACME-Specific Item Codes

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 ACME$_NOACMECTX. Distinguishing Between Input and Output Item Codes

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 dialogue mode calls to the SYS$ACM[W] system service. Text vs. Nontext Items

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. Single-Valued vs. Multivalued Item Semantics

It is mechanically possible for your program to put the same item code at two different places in a single item list. The following are the possible interpretations of such a circumstance:

The SYS$ACM[W] system service always honors the well-known items with single-valued semantics.

33.3.5 Item Lists

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. Item List Chains

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.

No ACME agent will ever send an ACME-specific message category to an ACM client program without knowing that the ACM client program is familiar with that message category.

Because there is no ACMEIS$W_MSG_TYPE field when flag ACMEDLOGFLG$V_INPUT 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.

33.3.8 Synchronization of Your System Service Calls

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.

33.4 Authentication Techniques

Your ACM client program can call the SYS$ACM[W] system service to change a password, and the effect is the same as if SET PASSWORD had made the call.

Your ACM client program can call the SYS$ACM[W] system service to authenticate a user. Your authentication is audited and break-in evasion is checked in the ACME server process, just as for LOGINOUT.

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, Looking Up DOI and ACME IDs, all use of the Event or Query function codes is specific to a DOI.

33.4.1 Nondialogue Mode Operation

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 ACME$_LOGON_TYPE of ACME$K_NETWORK, indicating that while they supply a password, no complex interaction is possible.

33.4.2 Dialogue Mode Operation

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:

If all of the itemset entries within the itemset were output itemset entries, your program should call the SYS$ACM[W] system service with an empty item list (containing just the terminator entry).

Dialogue mode operation applies only to the Authenticate Principal and Change Password functions. Calls to any other functions must be in nondialogue mode.

33.4.3 Login Categories and Classes

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:
Login Category Login Class
Interactive Local, Dialup, Remote
Noninteractive Batch, Network

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.

Specifying item ACME$_LOGON_TYPE requires the IMPERSONATE privilege. It is defaulted to match the login class of the process that called the SYS$ACM[W] system service.

The login type affects the degree of interaction required to call the SYS$ACM[W] system service, as shown in the following table:
Login Type Interaction Details
Batch No authentication is involved. This may mean that credentials are not provided for certain domains of interpretation that base their credential creation on presentation of a password.
Network Authentication is involved, but it operates in nondialogue mode unless an ACME agent (other than the VMS ACME agent) requires dialogue for authentication.
Local, Dialup, and Remote Authentication is involved and further dialogue may be encountered to change expiring passwords, and so on. The SYS$ACM[W] system service expects a person to be available to answer questions raised through dialogue.

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.

Previous Next Contents Index