HP OpenVMS Systems Documentation
Compaq ACMS for OpenVMS
Special situations exist if an agent program attempts to sign a submitter in when the ACMS system is not started. See Section 4.2 for guidelines on handling these situations.
Removes a task submitter from the ACMS system.
submitter_idThe identification of the task submitter signing out. This ID is assigned in the ACMS$SIGN_IN service.
cancel_flagThe 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.
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.
Terminates any I/O initialized during the ACMS$INIT_EXCHANGE_IO
services. ACMS$TERM_EXCHANGE_IO frees any resources being used by the
submitter, for example, DECforms sessions or TDMS channels.
exchange_io_idThe 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.
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:
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:
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.)
|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.|
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.|
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:
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.
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:
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:
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.
The TID parameter does not exist in versions prior to ACMS Version 3.2. In versions of ACMS prior to Version 3.2, the position of the TID parameter was reserved to Compaq. If you used this parameter for customer code in the past, the code behaves unpredictably with ACMS Versions 3.2 and higher.
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
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:
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.