Library /sys$common/syshlp/helplib.hlb  —  System Services, $ACM  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 HP OpenVMS System Services
    Reference Manual.

    To view the format of an item set entry and descriptor table, see
    the HP 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 HP 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 HP 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 HP 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.
Close Help