# Compaq ACMS for OpenVMS
Systems Interface Programming

Previous | Contents | Index

# Chapter 4
Agent Program Initialization and Exchange I/O Services

This chapter discusses the following topics:

- Authorizing an agent program
- Signing an agent program in to ACMS
- Initializing an agent program to perform specified exchange I/O
- Terminating exchange I/O
- Signing an agent program out of ACMS

This chapter also provides reference material in alphabetical order for calling SI services in agent programs.

Before an agent program can call any ACMS tasks, it must identify one or more task submitters to ACMS. The SI provides a service to sign the task submitter in to ACMS.

After the ACMS Central Controller (ACC) checks the identity of the task submitter, the agent program must indicate the types of exchange I/O to be performed. The SI provides a service that allows the agent program to declare the types of exchange I/O to be performed, setting up the necessary data structures to support the I/O methods selected. If TDMS exchange I/O is declared, the SI services open a TDMS channel.

When the submitter is finished performing exchange I/O, an agent program calls an SI service to finish any I/O that has been initialized, and frees any resources used by the task submitter.

After exchange I/O is terminated and the resources are freed, the agent program can then sign out one or more task submitters. The SI provides services to sign the task submitter out of ACMS. Figure 4-1 shows how an agent program interacts with ACMS components to sign a task submitter in to ACMS.

Figure 4-1 Signing In a Task Submitter to ACMS

The ACC verifies the user name and device name against the ACMSUDF.DAT user definition file, the ACMSDDF.DAT device definition file, and the SYSUAF.DAT file.

Table 4-1 shows the SI initialization services.

Table 4-1 SI Initialization Services
Service Name | Description
--- | ---
ACMS$SIGN_IN | Identifies a task submitter to ACMS and returns a SUBMITTER_ID.
ACMS$SIGN_OUT | Removes a task submitter from ACMS.

Only users authorized with the ACMS User Definition Utility (UDU) can gain access to ACMS. Also, if the task uses a terminal or other device for I/O, the terminal or device must be authorized with the ACMS Device Definition Utility (DDU). See Compaq ACMS for OpenVMS Managing Applications for more information about authorizing users and devices with UDU and DDU.

Table 4-2 shows the SI exchange I/O services. You must use these services for any task that uses DECforms (FORM I/O).

Table 4-2 SI Exchange I/O Services
Service Name | Description
--- | ---
ACMS$INIT_EXCHANGE_IO | Readies the agent program to perform various types of exchange I/O. Specifies the type of I/O to be performed and returns an exchange I/O ID.
ACMS$TERM_EXCHANGE_IO | Cleans up after the agent program is finished performing exchange I/O for tasks. Allows an agent program to finish any I/O initialized by the ACMS$INIT_EXCHANGE_IO services, freeing any resources being used by the submitter.

The exchange I/O services and reference material for calling them in agent programs are discussed in Section 4.3 and Section 4.4.

# 4.1 Authorizing an Agent Program in ACMS

An agent program can submit tasks under its own OpenVMS user name or under other user names:

- If the agent program submits tasks under its own user name, the agent program's OpenVMS user name does not need to be defined as a privileged ACMS agent program; no special qualifiers are necessary when authorizing a user with the ACMS User Definition Utility.
- If the agent program submits tasks under other user names, the system manager must define the user name under which the agent program executes as an authorized ACMS agent program. The system manager authorizes an agent program by using the /AGENT qualifier when running the ACMS User Definition Utility to add the agent program user name. For example:

      UDU> ADD user-name/AGENT

  The /AGENT qualifier marks this user name as an agent program. Authorizing a user name as an agent program is like using the OpenVMS DETACH privilege because it allows the agent program to use any OpenVMS user name.

ACMS assumes that privileged agent programs verify their task submitters and any devices they use. For example, an agent program might verify a terminal user by asking for a name and password and checking them against a database maintained by the agent program.

If the agent program submits tasks that use terminal I/O, the agent program must pass the terminal's device name to ACMS when it signs in the task submitter. Unless the agent program has been authorized with the OpenVMS SHARE privilege, ACMS also checks that the agent program owns the terminal.

If the agent program submits tasks that do no I/O or that do stream I/O, the agent program can either omit the device name parameter or pass the value NL: for the device name. If the agent program omits the device name, it defaults to NL:.

# 4.2 Signing In a Task Submitter to ACMS

An agent program uses the ACMS$SIGN_IN service to identify a task submitter's user name and device name (if I/O is to be performed on a terminal) to ACMS during sign-in. After ACMS verifies the user name and device, the agent program can submit tasks to ACMS.

The ACMS$SIGN_IN service assigns a submitter ID, which is passed to other SI services that the agent program calls for this task submitter. The sign-in service also provides an optional cancel routine that notifies the agent program if the submitter ID is forced out of the ACMS system because the system stopped or because an operator canceled the submitter.

If an agent program attempts to sign a user in to ACMS when the ACMS system is not started, two results can occur:

- If the agent program signs in a user name that is different from the user name of the agent process, the ACMS$SIGN_IN service fails and returns the message:

      ACMS$_NOSYSTEM, The ACMS system was not available

- If the agent program signs in under its own user name or without passing a user name, the ACMS$SIGN_IN service completes successfully and returns the message:

      ACMS$_SIGNIN_NOAUTH, Sign in completed successfully without
      authentication.

  Although this user name is signed in to ACMS, the user cannot select tasks from any ACMS application until the ACMS system is started.

The following pseudocode shows how an agent program can handle both situations:

    Signin_status = ACMS$SIGN_IN

    if signin_status eql ACMS$_SIGNIN_NOAUTH
    then
         sign_out the submitter

    if signin_status eql ACMS$_SIGNIN_NOAUTH or ACMS$_NOSYSTEM
    then
         [exit the agent
                   or
          retry "n" times]

Note An agent program must sign a user in to ACMS with a "username" argument to ACMS$SIGN_IN in capital letters.

If a user-generated character string descriptor is used, the length field of the string must be exactly the same as the length of the character string that describes the user name. If either of these conditions is not met, the ACMS$SIGN_IN service returns the following message:

    ACMS$_BADUSER - The user is either not in the user definition
                    file or not in SYSUAF.

# 4.3 Specifying the Type of I/O

The agent program calls ACMS$INIT_EXCHANGE_IO to specify the type of I/O to be performed. The service returns an exchange I/O ID. This ID keeps track of the types of I/O the submitter can perform. The exchange I/O ID is passed to the call or start call service as the third argument in the task argument list.

You must supply the exchange I/O parameter. This value is returned upon successful completion of the call.

Exchange I/O for a task is performed by either the application execution controller or the ACMS code running in the agent program. Exchange I/O takes place in the agent process for:

- All tasks that use DECforms in exchange steps
- All tasks that perform stream I/O in exchange steps
- All tasks on remote nodes that use TDMS in exchange steps

The Application Execution Controller (EXC) performs exchange I/O for local TDMS tasks only.

To perform terminal I/O from a DCL or a procedure server, call ACMS$INIT_EXCHANGE_IO. ACMS$SIGN_IN provides the device name. That device name is passed to the DCL or procedure server.

# 4.4 Terminating Exchange I/O

The ACMS$TERM_EXCHANGE_IO service allows an agent program to finish any I/O initialized with ACMS$INIT_EXCHANGE_IO. ACMS$TERM_EXCHANGE_IO frees any resources being used by the submitter. For example, DECforms sessions or TDMS channels are freed by ACMS$TERM_EXCHANGE_IO.

# 4.5 Signing Out a Task Submitter from ACMS

The agent program uses the ACMS$SIGN_OUT service to remove a task submitter from ACMS. The sign-out service identifies the task submitter by its submitter ID. The sign-out service provides an optional parameter to cancel all calls still active when the sign-out service executes. If this parameter is omitted and calls are still active, the sign-out service fails and returns a status code to the agent program indicating there are still active calls for this submitter.

The rest of this chapter contains reference material for using ACMS$INIT_EXCHANGE_IO, ACMS$SIGN_IN, ACMS$SIGN_OUT, and ACMS$TERM_EXCHANGE_IO in an agent program.

# 4.6 ACMS$INIT_EXCHANGE_IO

Specifies the type of I/O the agent program or device can perform. ACMS$INIT_EXCHANGE_IO is called by the agent program and returns an exchange I/O ID.

For submitters that enable TDMS, a call to ACMS$INIT_EXCHANGE_IO opens a TDMS channel.

Note If an agent program enables stream I/O and associates it with a submitter, the agent program must call ACMS$WAIT_FOR_STREAM_IO for all tasks (except tasks that do no terminal I/O), whether or not the task performs stream I/O.

## Format

> ACMS$INIT_EXCHANGE_IO
> (submitter_id.rq.r,
> exchange_io_id.wq.r,
> [io_enable_flags.rl.r],
> [item_list.rx.r],
> [io_capabilities_flags.wl.r])

> ACMS$INIT_EXCHANGE_IO_A
> _id.rq.r,
> _io_id.wq.r,
> [io_enable_flags.rl.r],
> [item_list.rx.r],
> [io_capabilities_flags.wl.r],
> [comp_status.wq.r],
> [efn.rbu.r],
> [astadr.szem.r],
> [astprm.rz.v])

## Parameters

> ### submitter_id

> The submitter ID corresponding to a signed-in submitter (user). This ID is returned by the ACMS$SIGN_IN service. No default submitter ID is allowed.

> ### exchange_io_id

> This ID keeps track of the type of I/O the submitter is performing. This ID is passed to the call or start call service as the third argument in the task argument list.

> The exchange_io_id parameter must be supplied. This value is returned upon successful completion of the call.

> ### io_enable_flags

> These flags indicate which type of I/O the agent program wishes to perform. If this flag is not supplied, the agent program can call a task that performs DECforms and TDMS I/O, but it cannot use the Request Interface.

> To use TDMS, the default value of the io_enable_flags argument initializes the agent program. If it is certain that tasks will never use TDMS I/O, disable TDMS to conserve resources. If the ACMS$V_IO_DISABLE_TDMS flag is set on the call to ACMS$INIT_EXCHANGE_IO, TDMS is disabled for the agent process. Because TDMS is completely disabled in the agent process, if a task that uses TDMS for I/O is selected, it is canceled.

> To use DECforms, the default value of the io_enable_flags argument initializes the agent program. If you are certain that you will never use DECforms, it is advisable to disable DECforms in order to conserve resources. If the ACMS$V_IO_DISABLE_DECFORMS flag is set on the call to ACMS$INIT_EXCHANGE_IO, DECforms is disabled for the agent process. Because DECforms is completely disabled in the agent process, if a task that uses DECforms for I/O is selected, it is canceled.

> To use the Request Interface (RI), you must set the ACMS$V_IO_ENABLE_SYNC_RI flag on the call to ACMS$INIT_EXCHANGE_IO. In some cases, it may be desirable to disable DECforms and TDMS. For example, if the device is not supported by DECforms or TDMS, disabling DECforms and TDMS can conserve resources. Further information regarding the RI is in Compaq ACMS for OpenVMS Writing Applications.

> Stream I/O is implicitly enabled by passing a connect ID in the item list.

> ### item_list

> This is the address of an item list describing the information requested. An item list is an OpenVMS data type that is used to pass information to and from a service. Item lists are made up of one or more item descriptors. The list of item descriptors must be terminated by an item code of 0. Detailed information regarding item lists is in OpenVMS Programming Interfaces: Calling a System Routine.

> Possible item codes are:

> - ACMS$K_TDMS_CHANNEL
>   To obtain TDMS channel codes, set up an item list with an entry whose item code is ACMS$K_TDMS_CHANNEL. The buffer is a longword that receives the channel number.
> - ACMS$K_CONNECT_ID
>   If you wish to use stream I/O in the agent program, you need to provide an entry in the item list. The buffer is a quadword that receives the connect ID. The connect ID returned by the service is used to wait for and reply to stream I/O operations. See Chapter 6 for further details regarding stream I/O.

> ### io_capabilities_flags

> This flag is a longword containing bits indicating which I/O methods are successfully initialized. The following bits are defined:
> - ACMS$V_DECFORMS_AVAILABLE
>   This bit is set if DECforms is successfully initialized. If DECforms is not installed on the system, or was disabled, the bit is clear.
> - ACMS$V_TDMS_AVAILABLE
>   This bit is set if TDMS is successfully initialized. If TDMS is not installed on the system, or was disabled, the bit is clear.

> - ACMS$V_STREAM_AVAILABLE
>   This bit is set if the stream services are successfully initialized.
> - ACMS$V_RI_AVAILABLE
>   This bit is set if ACMS has successfully enabled the RI.

The parameters comp_status.wq.r, efn.rbu.r, astadr.szem.r, and astprm.rz.v are asynchronous service arguments. See Chapter 2 for a discussion of these parameters.

## Return Status

> The following list summarizes each error returned by ACMS$INIT_EXCHANGE_IO.

> The return status codes indicating success or failure of the call follow:

> Status | Severity Level | Description
> --- | --- | ---
> ACMS$_NORMAL | Success | Normal successful completion.
> ACMS$_SOME_IO_NOT_AVAILABLE | Success | Some of the requested I/O methods have not been initialized.
> ACMS$_PENDING | Informational | Successful operation pending asynchronous completion. The final status is in the completion status block.
> ACMS$_USERMODE | Error | The user mode was invalid.
> ACMS$_INVSUB | Error | The submitter ID was invalid.
> ACMS$_NTSNIN | Error | The submitter was not signed in.
> ACMS$_INVEXCHIOID | Error | The exchange I/O ID was invalid.
> ACMS$_INVDEV | Error | The device name was invalid.
> ACMS$_INVFLAGS | Error | Invalid flags word.
> ACMS$_INVENBRI | Error | Invalid ENABLE RI flags.
> ACMS$_INVITEMDESC | Error | Invalid item list.
> ACMS$_INVITEMCODE | Error | Invalid item code.
> ACMS$_INVBUFSIZ | Error | Invalid buffer size.
> ACMS$_INVBUFADR | Error | Invalid buffer address.
> ACMS$_INVRETLEN | Error | Invalid return length.
> ACMS$_INVIOCAPFLAG | Error | Invalid I/O capabilities flag.
> ACMS$_INVCMPSTS | Error | Invalid completion status.
> ACMS$_INVEFN | Error | Invalid event flag number.
> ACMS$_INVASTADR | Error | Invalid AST routine address.
> ACMS$_INV_SIGNOUT_ACTIVE | Error | Submitter is in process of sign-out.
> ACMS$_INTERNAL | Error | ACMS internal error.

ACMS$INIT_EXCHANGE_IO can also return invalid status messages associated with the following services, among others:

- LIB$GET_VM
- $CLREF
- $DCLAST
- ACMS$OPEN_RR_A
- ACMS$CREATE_STREAM_A
- ACMS$CONNECT_STREAM_A
- TSS$OPEN

# 4.7 ACMS$SIGN_IN

Signs a task submitter in to ACMS.

## Format

> ACMS$SIGN_IN (submitter_id.wq.r,
> [username.rt.dx],
> [device.rt.dx],
> [cancel_routine.zem.r],
> [cancel_param.rz.v])

> ACMS$SIGN_IN_A (submitter_id.wq.r,
> [username.rt.dx],
> [device.rt.dx],
> [cancel_routine.zem.r],
> [cancel_param.rz.v],
> [comp_status.wq.r],
> [efn.rbu.r],
> [astadr.szem.r],
> [astprm.rz.v])

## Parameters

> ### submitter_id

> The submitter identification that is output by the ACMS$SIGN_IN service.

> ### username

> The OpenVMS user name of the submitter signing in. The default is the agent program's user name. The ACMS Central Controller (ACC) makes sure that the user name exists in ACMSUDF.DAT. If the user name specified is different from the agent program's user name, ACC verifies that the agent program's user name is privileged by checking the agent program definition in the ACMSUDF.DAT database file.

> Note An agent program must sign a user in to ACMS with a capitalized "username" argument to ACMS$SIGN_IN.

> If a user-generated character string descriptor is used, the length field of the string must be exactly the same as the length of the character string that describes the user name.

> ### device

> The terminal device name that you supply if the task performs I/O to the terminal. The device name can be a physical device name or a logical name. The default is NL:. ACC makes sure that the device name exists in the ACMSDDU.DAT database file.

> ### cancel_routine

> The routine called (at AST level) when the submitter is canceled. If this parameter is omitted, the agent program receives no notification when the submitter is canceled. Any further operations by this submitter fail. When this parameter is used, the agent program receives notification when the submitter is canceled, after which the following parameters are passed to the cancel routine:
> - cancel_param
>   The cancel user parameter that was passed with ACMS$SIGN_IN. This is passed by value, rather than by reference.
> - submitter_id
>   The address of the two-longword identification of the submitter being canceled. This is the address of the submitter_id passed by ACMS$SIGN_IN.
> - reason
>   The longword indicating the reason for the user cancellation. The possible reasons are:
>   - ACMS$_ACMS_GONE---the ACMS system has stopped
>   - ACMS$_SUB_CANCELED---the submitter was canceled by an operator request
>     This is passed by value, rather than by reference.

> ### cancel_param

> The value to be passed to the cancel routine.

The parameters comp_status.wq.r, efn.rbu.r, astadr.szem.r, and astprm.rz.v are asynchronous service arguments. See Chapter 2 for a discussion of these parameters.

## Return Status

> The return status codes indicating the success or failure of the call are:

> Status | Severity Level | Description
> --- | --- | ---
> ACMS$_NORMAL | Success | Normal successful completion
> ACMS$_PENDING | Informational | Successful operation pending asynchronous completion. The final status is in the completion status block.
> ACMS$_BADAGENT | Error | The agent is not a valid ACMS agent program.
> ACMS$_BADDEVICE | Error | The device is not defined in the device definition file.
> ACMS$_BADUSER | Error | The user is either not in the user definition file or not in SYSUAF.
> ACMS$_INSUFPRM | Error | Not enough arguments were passed to this service.
> ACMS$_INTERNAL | Error | Internal error.
> ACMS$_INVASTADR | Error | The AST address was invalid.
> ACMS$_INVCANAST | Error | The cancel user routine was invalid.
> ACMS$_INVCMPSTS | Error | The completion status block was invalid.
> ACMS$_INVDEV | Error | The device name was invalid.
> ACMS$_INVEFN | Error | The event flag was invalid.
> ACMS$_INVLOGIN | Error | Invalid login attempt.
> ACMS$_INVSUB | Error | The submitter ID was invalid.
> ACMS$_INVUSER | Error | The user name was invalid.
> ACMS$_NODEVACC | Error | No access to specified device.
> ACMS$_SYNASTLVL | Error | Synchronous services may not be called from AST level.
> ACMS$_USERMODE | Error | This service must be called from user mode.

Previous | Next | Contents | Index