4.8 ACMS$SIGN_OUT

Format

ACMS$SIGN_OUT (submitter_id.rq.r,
[cancel_flag.rlu.r])

ACMS$SIGN_OUT_A (submitter_id.rq.r,
[cancel_flag.rlu.r],
[comp_status.wq.r],
[efn.rbu.r],
[astadr.szem.r],
[astprm.rz.v])

Parameters

submitter_id

The identification of the task submitter signing out. This ID is assigned in the ACMS$SIGN_IN service.

cancel_flag

The address of the flag that specifies whether or not to cancel active calls. If the low bit of this flag is set, active calls are canceled and the sign-out routine completes successfully. If this flag is not set or is not passed and there are calls active, the sign-out routine fails.

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

Return Status

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

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$_ACTIVE_CALL	Error	Calls are still active for this submitter.
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$_INVCANFLG	Error	The cancel flag parameter was invalid.
ACMS$_INVCMPSTS	Error	The completion status block was invalid.
ACMS$_INVEFN	Error	The event flag was invalid.
ACMS$_INVSUB	Error	The submitter ID was invalid.
ACMS$_NODEVACC	Error	No access to specified device.
ACMS$_NTSNIN	Error	Submitter was not signed in.
ACMS$_SIGNOUT_ACTIVE	Error	A sign-out is active.
ACMS$_SYNASTLVL	Error	Synchronous services may not be called from AST level.
ACMS$_USERMODE	Error	This service must be called from user mode.

4.9 ACMS$TERM_EXCHANGE_IO

Format

ACMS$TERM_EXCHANGE_IO (exchange_io_id.rq.r)

ACMS$TERM_EXCHANGE_IO_A (exchange_io_id.rq.r,
[comp_status.wq.r],
[efn.rbu.r],
[astadr.szem.r],
[astprm.rz.v])

Parameters

exchange_io_id

The ID returned from an ACMS$INIT_EXCHANGE_IO call. You must supply this parameter.

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 this service. The return status codes indicating success or failure of the call are:

Status	Severity Level	Description
ACMS$_NORMAL	Success	Normal successful completion. (Synchronous calls only.)
ACMS$_PENDING	Informational	Successful operation pending asynchronous completion. The final status is in the completion status block.
ACMS$_USERMODE	Error	Invalid user mode.
ACMS$_INVEXCHIOID	Error	Invalid exchange I/O ID.
ACMS$_INVCMPSTS	Error	Invalid completion status.
ACMS$_INVEFN	Error	Invalid event flag number.
ACMS$_INVASTADR	Error	Invalid AST routine address.
ACMS$_SIGNOUT_ACTIVE	Error	Submitter is in process of sign-out.
ACMS$_INTERNAL	Error	Internal error.

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

• LIB$GET_VM
• $CLREF
• $DCLAST
• ACMS$CLOSE_RR_A
• ACMS$DELETE_STREAM_A
• ACMS$DISCONNECT_STREAM_A
• TSS$CLOSE
• FORMS$DISABLE

This chapter describes how an agent program calls the submitter services to submit ACMS tasks. The chapter also provides reference material for using these services. The calls are listed in alphabetical order in the reference section of the chapter.

Once a task submitter is signed in, an agent program can use the submitter services to call an ACMS task on behalf of the task submitter. The submitter services allow the agent program to:

• Find the information necessary to call a task
• Start a task
• Cancel a task, if necessary
• Wait for a task to complete

Figure 5-1 shows an agent program calling a task in ACMS. Using the submitter services to invoke the task, the agent program can work on behalf of one or more task submitters.

Figure 5-1 Calling a Task in ACMS

Table 5-1 lists the submitter services in the order in which you might use them and gives a brief description of each. (Reference material in this chapter lists these services in alphabetical order.)

Table 5-1 Submitter Services

Service Name	Description
ACMS$GET_PROCEDURE_INFO	Finds the procedure ID, the I/O method, and the number of workspaces for the task.
ACMS$CALL	Calls a task and ends when the task completes.
ACMS$START_CALL	Calls a task and returns when the task has been submitted to ACMS. Use this service with ACMS$WAIT_FOR_CALL_END. This service returns a CALL_ID, which you use with ACMS$CANCEL_CALL and ACMS$WAIT_FOR CALL_END to identify the task instance.
ACMS$CANCEL_CALL	Cancels a task before the end of the task. This service cancels tasks started with ACMS$START_CALL.
ACMS$WAIT_FOR_CALL_END	Waits for a task to complete. Use this service to wait for tasks started with ACMS$START_CALL.

5.1 Preparing to Call a Task

The first time an agent program calls a task, the agent program must use the ACMS$GET_PROCEDURE_INFO service to get the procedure ID for that task. An agent program also must use ACMS$GET_PROCEDURE_INFO to get the new procedure ID for an active task whose procedure ID has changed. A procedure ID can change when:

• An application stops and restarts, or is reprocessed
  An agent program must call ACMS$GET_PROCEDURE_INFO to get the information associated with the new application.
• All task submitters that have selected tasks in the application have signed out
  The agent program only keeps track of applications that its submitters are currently using.

If a call to ACMS$START_CALL or ACMS$CALL returns ACMS$_NOSUCH_PKG or ACMS$_INVPROCID, then the application has been stopped or reprocessed since the call to ACMS$GET_PROCEDURE_INFO was performed. In this case, it is necessary to call ACMS$GET_PROCEDURE_INFO again to attempt to get a new, valid procedure ID. If this call fails with ACMS$_NOSUCH_PKG, then the application has been stopped.

In addition, an agent can pass a DECdtm distributed transaction ID (TID) to a task by using one of the services that accept a TID: ACMS$CALL, ACMS$CALL_A, ACMS$START_CALL, and ACMS$START_CALL_A.

An agent program can supply a selection string, extended status,and I/O information. If a task is written to accept task workspace arguments passed when the task begins, the agent program can supply the list of workspace arguments the agent program passes to the ACMS task. This information is passed in an argument list when the agent program starts the task by calling the ACMS$CALL or ACMS$START_CALL services.

The arguments are passed in the following order:

1. Selection string
   You pass data to the ACMS$SELECTION_STRING system workspace in a task using the selection string argument. The selection string argument is optional.
2. Extended status
   You can provide an extended status argument in which ACMS can return a status message when the task completes. The extended status argument is optional. This string is filled in with the translation of the task's status when the task completes.
3. I/O argument
   You use this parameter to pass the exchange I/O ID returned from ACMS$INIT_EXCHANGE_IO.
   If a task does not perform I/O, the task I/O parameter is optional. If the task I/O parameter is supplied and the task does not perform I/O, the task I/O parameter will be ignored.
4. List of workspace arguments
   You supply workspaces to tasks in the fourth and subsequent arguments of the argument list. The fourth argument is used to initialize the first task argument workspace defined in the task definition. The fifth argument is used to initialize the second workspace defined as a task argument, and so on. Workspace arguments are optional. If a task is written to accept workspaces, the agent program can pass them in the argument list.

Figure 5-2 shows an argument list for an agent program that supplies all of the arguments. This figure assumes that the agent program supplies two task workspace arguments.

Figure 5-2 Arguments Passed for a Task Using a Full Task Argument List

Figure 5-3 is an example of an argument list for a task that does not perform I/O and supplies two task argument workspaces to a task.

Figure 5-3 Arguments Passed for a Task Doing No I/O

Detailed information about the ACMS$CALL, ACMS$START_CALL, ACMS$GET_PROCEDURE_INFO services, and their parameters is available in the reference sections in this chapter, which begin with Section 5.4.

5.2 Calling a Task

An agent program can call ACMS tasks using either the ACMS$CALL or the ACMS$START_CALL service. If the agent program may need to cancel the task (for example, if a terminal user types [Ctrl/C]), the agent program should use the ACMS$START_CALL service. Both of these services accept the passing of a transaction ID (TID). See Section 5.2.1.

If you do not foresee any reason for an agent program to cancel a task, then the agent program can use the ACMS$CALL service. This service calls a task and completes when the task completes; the ACMS task causes the service to end.

Do not use ACMS$WAIT if the agent uses stream I/O. If an agent program creates a stream and associates it with a submitter, the agent program must call ACMS$WAIT_FOR_STREAM_IO for all tasks, whether or not the called task performs stream I/O.

The ACMS$START_CALL service calls a task and returns a call ID. Because this service completes as soon as the task is submitted to ACMS, the agent program must use the ACMS$WAIT_FOR_CALL_END service to wait for the task to complete.

The ACMS$WAIT_FOR_CALL_END service waits for the task to complete and returns any errors in its completion status block.

An agent program must also use the ACMS$WAIT service when it calls the ACMS$CALL_A, ACMS$START_CALL_A, or ACMS$WAIT_FOR_CALL_END_A asynchronous submitter services. See Chapter 2 for an explanation of the ACMS$WAIT service.

If application reprocessing is necessary, precede all calls to ACMS$CALL with ACMS$GET_PROCEDURE_INFO.

5.2.1 Passing a Transaction ID (TID)

To participate in a distributed transaction, the agent program must call the $START_TRANS service before starting a task. The $START_TRANS service starts a distributed transaction and obtains a TID. The agent program then does that task call by calling one of the following:

• ACMS$START_CALL and ACMS$WAIT_FOR_CALL_END
• ACMS$CALL

Both ACMS$START_CALL and ACMS$CALL accept the passing of a TID. By default, the task joins the distributed transaction established by the $START_TRANS service if a TID is not passed.

When an agent program passes a TID to one of these services, ACMS attempts to pass the TID on to the task. A TID can be passed to a task only if the task is composable. Chapter 2 discusses passing a TID to a composable task in more detail.

5.2.2 Supplying Workspaces to a Task

An agent program can supply workspaces to and receive workspaces from an ACMS task. An agent program can supply workspaces to a task when it calls the task using either the ACMS$CALL or ACMS$START_CALL service. The task can use the data in the workspace supplied by the agent program. When the task completes with a successful status, ACMS returns the contents of all MODIFY and WRITE access workspaces to the agent program.

If a task fails, the contents of all WRITE access workspaces are considered to be undefined.

The agent program supplies workspaces as arguments in an argument list in the ACMS$CALL or ACMS$START_CALL services. The agent program defines one argument for each workspace it intends to pass to the ACMS task. The agent program must supply the arguments to the task in the same order that they are listed in the TASK ARGUMENTS clause in the ACMS task definition.

5.2.3 Supplying the Correct Number of Task Argument Workspaces

The ACMS task definition defines the number of task argument workspaces the task expects to receive and the order in which the agent program must supply them to the task. Although the ACMS task definition specifies the workspace names and the order of the task workspace arguments that the agent program can supply, the agent program has the option of omitting one or more of the workspaces defined as TASK ARGUMENTS in the ACMS task definition.

If the agent program does not supply all the workspaces, ACMS initializes each missing workspace with the default value defined for it in the task group database (.TDB). (Default values are defined with the CDD INITIAL CONTENTS clause and included in the .TDB when you build the task group database.) If there is no default value defined, ACMS fills the workspace with zeros.

If an agent program attempts to supply more workspace arguments to a task than there are task argument workspaces defined for that task, then the ACMS$CALL and ACMS$START_CALL services complete and return the following error status:

%ACMS-F-ERRREADARG, Error during task initialization: cannot read an argument in argument list

If the agent program also calls the ACMS$SIGNAL service (see Chapter 2), it returns the following additional information:

%ACMSPKG-E-ARGNUMMATCH, Argument number mismatch between received data and expected data

To avoid receiving these errors, the agent program can use the ACMS$GET_PROCEDURE_INFO service to determine the number of task argument workspaces defined for a task. See the discussion of the ACMS$GET_PROCEDURE_INFO service in Section 5.1 and in the reference section for more information.

The agent program can also receive the %ACMSPKG-E-ARGNUMMATCH error if you increase the number of task argument workspaces defined in the task definition and rebuild the task group, but you do not rebuild the application definition. ACMS stores the number of task argument workspaces in the application database (.ADB) as well as the task group database (.TDB).

If you increase the number of task argument workspaces from three to four and rebuild the task group, then the .TDB file describes the correct number of task workspace arguments. However, unless you also rebuild the application to produce a new .ADB file, the old version still describes the task as having only three task workspace arguments. ACMS uses the .ADB file when formatting the message that it sends from the agent program to the application to start the task.

5.2.4 Accessing Task Workspaces

ACMS allows the task to accept workspace arguments into task workspaces. The task can use and modify the data in these workspaces. The task cannot accept the arguments into group workspaces, user workspaces, or system workspaces. When the task completes successfully, ACMS returns the contents of all workspaces with modify or write access to the agent program. You specify the modify, read, or write access method in the TASK ARGUMENTS clause of the task definition:

• Modify access
  Modify is the default access method for the TASK ARGUMENTS clause. You define a task workspace with modify access if the ACMS task needs to update one or more fields in that workspace. A workspace argument defined with modify access is initialized with data supplied by the agent program.
  If the workspace data is not supplied by the agent program, the workspace is initialized with data supplied on the task call (default values are defined with the CDD INITIAL CONTENTS clause and included in the .TDB when you build the task group database). If there is no default value defined, ACMS fills the workspace with zeros. The task can modify the contents of this workspace during execution, and ACMS returns the modifications to the agent program when the task completes.
• Read access
  You define a task workspace with read access if the ACMS task does not need to return any data in the fields of the workspace back to the agent program. A workspace argument defined for read access is initialized with the data supplied by the agent program.
  If the workspace data is not supplied by the agent program, the workspace is initialized with data supplied on the task call (default values are defined with the CDD INITIAL CONTENTS clause and included in the .TDB when you build the task group database). If data is not supplied on the task call, the workspace is initialized with zeros. The task can modify the contents of the workspace during execution, but the modifications are lost when the task ends.
• Write access
  You define a task workspace with write access if the task needs to return data in one or more fields of the workspace back to the agent program. A workspace argument defined with write access is initialized with the default contents defined in the .TDB. (Default values are defined with the CDD INITIAL CONTENTS clause and included in the .TDB when you build the task group database.)
  If there is no default value defined, ACMS fills the workspace with zeros. The task can modify the contents of this workspace, and ACMS returns the modifications to the agent program when the task completes executing.

You can optimize the performance of ACMS and the agent program by specifying the read and write access instead of modify access whenever possible. Specifying read access for the task workspace can provide performance gains if ACMS does not need to return updated data to the agent program when the task completes. Specifying write access for the task workspace provides performance gains if the agent program does not need to send data from the agent program to the task in the application.

The modify access type is the default for the TASK ARGUMENTS clause. Although modify access is less efficient in terms of performance when passing large records, it may be the best option if you are passing small workspaces and are interested in ease of use. Defining the task workspace with modify access allows data to be passed back and forth in a single workspace. In general, using modify access is more efficient for small database records; as record size increases, performance decreases.

The ACMS$CALL and ACMS$START_CALL services pass workspaces by descriptor. The application execution controller checks the length of the workspace when starting the task.

See Compaq ACMS for OpenVMS Writing Applications and Compaq ACMS for OpenVMS ADU Reference Manual for more information on defining tasks that can accept workspace arguments from an agent program. See the syntax for the ACMS$CALL and ACMS$START_CALL services later in this chapter for information on providing argument lists to tasks in an ACMS application.