# Compaq ACMS for OpenVMS
Systems Interface Programming

Previous | Contents | Index

# 5.3 Canceling a Task

An agent program can use the ACMS$CANCEL_CALL service to cancel tasks. The ACMS$CANCEL_CALL service can be used only to cancel tasks that are started with the ACMS$START_CALL service. ACMS$START_CALL returns a call ID that can be used with the ACMS$CANCEL_CALL service to stop a task prematurely.

For example, use ACMS$CANCEL_CALL to cancel tasks when a terminal user presses `[Ctrl/Y]`. ACMS expects a task to be canceled when the terminal user presses `[Ctrl/Y]` (or `[Ctrl/C]`, if the server is not running a task that enables a `[Ctrl/C]` handler). If an agent program does not use ACMS$CANCEL_CALL to cancel any active tasks when a user presses `[Ctrl/Y]`, then `[Ctrl/Y]` cancels are ignored and the tasks will run to completion.

You can use the ACMS$CANCEL_CALL service to send multiple cancel requests to a single task instance. For example, consider the case where an agent program starts a menu task for a user. During the day, the user selects tasks from the menu task to perform the user's business transactions. Because the user might need to press `[Ctrl/C]` to cancel more than one task called by the menu task, ACMS allows the agent program to call the ACMS$CANCEL_CALL service many times. See Compaq ACMS for OpenVMS Writing Applications for more information on how ACMS processes task cancellation requests for tasks called by other tasks.

# 5.4 ACMS$CALL

Submits an ACMS task. This service completes when the task ends. If you use the asynchronous ACMS$CALL_A service, it is also necessary to call the ACMS$WAIT service. See Chapter 2 for an explanation of the ACMS$WAIT service.

If application reprocessing is required, the agent program must use the ACMS$GET_PROCEDURE_INFO service before calling ACMS$CALL.

## Format

> ACMS$CALL ([submitter_id.rq.r],
> procedure_id.rq.r,
> [arguments.rz.r],
> [tid.ro.r])

> ACMS$CALL_A ([submitter_id.rq.r],
> procedure _id.rq.r,
> [arguments.rz.r],
> [tid.ro.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. The submitter ID is returned on the ACMS$SIGN_IN service.

> This parameter is optional for agent programs that do not use ACMS$SIGN_IN. Use of the default submitter feature, however, is not recommended for new development. See Section 2.1.6 and Section 2.1.7 for a discussion of this point.

> ### procedure_id

> The procedure ID of the task to call. You obtain this procedure ID by calling the ACMS$GET_PROCEDURE_INFO service.

> ### arguments

> The list of arguments to pass, if any. (See Section 5.1 for more information about using the argument list.)

> This is a standard OpenVMS argument list that contains:

> - selection_string.rt.dx
>   An agent program passes data to the ACMS$SELECTION_STRING system workspace in a task using the selection string argument. Initialize the selection string argument in the argument list with the address of an OpenVMS string descriptor that references the selection string data.
>   The selection string argument is optional. If the agent program does not pass any information to the ACMS$SELECTION_STRING workspace, the agent program must set this argument to zero. When an agent program does not supply a selection string argument, ACMS initializes the ACMS$SELECTION_STRING workspaces with spaces.
> - extended_status.wt.dx
>   When ACMS ends a task, it returns the message text associated with the task's final completion status back to the agent program. To access the message text after a task has completed, initialize the extended status argument with the address of an OpenVMS string descriptor into which ACMS can store the data.
>   The extended status argument is optional. If the agent program does not need to access the task's completion status message text, set this argument to zero. If you do not supply the address of a string descriptor in this argument, ACMS does not return the message text from the application to the agent program.

>   Note The extended status string cannot be filled if the application execution controller (EXC) cannot start a task (for example, if the EXC terminates abnormally, if a DECnet link terminates, or if EXC runs out of virtual memory). The extended status string also cannot be filled if the submitter services detect an error --- for example, if the submitter services receive an invalid procedure argument list, there is an internal error, or a task ends because the EXC terminated abnormally before completing the task.

> - I/O argument
>   There are several ways to pass I/O information to a task. The preferred method is to pass the exchange I/O ID as the I/O argument. ACMS supports the use of the other methods for compatibility with previously-developed agent programs.
>   The methods of passing I/O information to the task are:
>   - exchange_io_id.rq.r
>     The I/O argument can be an exchange I/O ID returned from the ACMS$INIT_EXCHANGE_IO service.
>   - terminal_name.rt.dx
>     The I/O argument can also be a terminal specification for tasks that perform request I/O or terminal I/O.
>   - stream_id.rq.r
>     For stream I/O tasks, you can initialize this argument with the address of the stream ID.
>   - For tasks that do not perform I/O, you can set this argument to zero. If the agent program does not pass any workspaces to the task, it can omit this argument.
> - workspaces
>   You supply workspaces to tasks in the fourth and successive arguments of the task's argument list. The workspace supplied in the fourth argument is used to initialize the first task argument workspace defined in the TASK ARGUMENTS clause in the task definition. The fifth argument is used to initialize the second workspace defined as a task argument in the TASK ARGUMENTS clause, and so on. Workspaces are passed to the task by descriptor. Therefore, initialize each workspace argument with the address of an OpenVMS string descriptor that references the workspace data. The read, write, or modify access to each workspace is determined by the TASK ARGUMENTS clause in the task:
>   - workspace_n.rt.dx
>   - workspace_n.wt.dx
>   - workspace_n.mt.dx
>   Workspace arguments are optional. If you do not want to supply one or more workspaces to a task, initialize the corresponding arguments in the task's argument list to zero. If you do not supply data to a workspace defined in a task as a TASK ARGUMENT, ACMS initializes that workspace with the default contents from the .TDB or with zeros.
>   See Section 5.1 and Section 5.2 for detailed information on how to pass a workspace to a task. See the VR_AGENT.C program and the VR_FAST_CHECKIN_TASK.TDF task definition in the ACMS$EXAMPLES directory for an example of an agent program calling a task.

> ### tid

> The transaction ID (TID) that the $START_TRANS service returns.

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.

## Note

> 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 "%ACMS-F-ERRREADARG, Error during task initialization: cannot read an argument in argument list" error. The agent program can use the ACMS$GET_PROCEDURE _INFO service to determine the correct number of TASK ARGUMENT workspaces defined for the task.

## Return Status

> The return status codes indicating 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$_CALL_CANCELLED | Error | Task was cancelled by task submitter.
> ACMS$_ERRREADARG | Error | Error during task initialization; cannot read an argument in the argument list.
> ACMS$_EXCPTN_STEPACTN | Error | Exception results from a step action in the task definition.
> ACMS$_NEED_DEVICE | Error | Task requires a device; none provided.
> ACMS$_NEED_DEVORRR | Error | Task requires a device name or RR server.
> ACMS$_NEED_IOID | Error | Task is defined with I/O.
> ACMS$_INSUFPRM | Error | Not enough arguments were passed to this service.
> ACMS$_INTERNAL | Error | Internal error.
> ACMS$_INVARGLST | Error | The argument list is invalid.
> ACMS$_INVASTADR | Error | The AST address was invalid.
> ACMS$_INVCMPSTS | Error | The completion status block was invalid.
> ACMS$_INVEFN | Error | The event flag was invalid.
> ACMS$_INVPROCID | Error | The procedure ID was invalid.
> ACMS$_INVSUB | Error | The submitter ID was invalid.
> ACMS$_INVTID | Error | Returned if ACMS does not have access to the Transaction ID (TID). The symbol is not defined as a universal symbol and will result in a link error if declared and accessed as a global symbol. This symbol has not been defined since ACMS Version 3.3b.
> ACMS$_NOSUCH_PROC | Error | There is no such procedure in the package.
> ACMS$_NOSUCH_PKG | Error | There is no such application defined.
> ACMS$_NOTAVAIL | Error | The feature is not yet available.
> ACMS$_NOTRANSADB | Error | No transaction support in the application database file (.ADB).
> ACMS$_NOTRANSNODE | Error | ACMS does not support transactions on the application node.
> ACMS$_NTSNIN | Error | Submitter was not signed in.
> ACMS$_OPR_CANCELLED | Error | Task canceled by system operator.
> ACMS$_SRVDEAD | Error | The server or EXC stopped unexpectedly.
> ACMS$_SRVNOTFOUND | Error | The server was not found.
> ACMS$_SIGNOUT_ACTIVE | Error | A sign-out is active.
> ACMS$_SYNASTLVL | Error | Synchronous services may not be called from AST level.
> ACMS$_TASKNOTCOMP | Error | Task is not composable.
> ACMS$_TRANSTIMEDOUT | Error | Transaction did not complete within specified time limit.
> ACMS$_USERMODE | Error | This service must be called from user mode.

# 5.5 ACMS$CANCEL_CALL

Cancels a task that was started by the task submitting agent program. This service only cancels tasks that were started with ACMS$START_CALL. The agent program must also use the ACMS$WAIT_FOR_CALL_END service with this service to get notification of the call canceling.

Use ACMS$CANCEL_CALL to cancel tasks when a terminal user presses `[Ctrl/Y]`. ACMS expects a task to be canceled when the terminal user presses `[Ctrl/Y]` (or `[Ctrl/C]`, if the server is not running a task that enables a `[Ctrl/C]` handler). If an agent program does not cancel any active tasks when `[Ctrl/Y]` is pressed, then `[Ctrl/Y]` cancels are disabled and the tasks run to completion.

Note The effect of this call might not be immediate or successful, due to the asynchronous nature of ACMS.

## Format

> ACMS$CANCEL_CALL ([submitter_id.rq.r],
> call_id.rq.r,
> [reason_code.rlu.r])

> ACMS$CANCEL_CALL_A ([submitter_id.rq.r],
> call _id.rq.r,
> [reason_code.rlu.r],
> [comp_status.wq.r],
> [efn.rbu.r],
> [astadr.szem.r],
> [astprm.rz.v])

## Parameters

> ### submitter_id

> The identification of the task submitter calling the task. The ACMS$SIGN_IN service returns this ID. This parameter is optional for agent programs that do not use ACMS$SIGN_IN. Use of the default submitter feature, however, is not recommended for new development. See Section 2.1.6 and Section 2.1.7 for discussions of this point.

> ### call_id

> The identification returned by ACMS$START_CALL. The call must be started by the same submitter as the one using the ACMS$CANCEL_CALL service.

> ### reason_code

> The reason code contains the reason for the cancel request. The parameter is passed to the application execution controller. The default is the following:

>     ACMS$_CALL_CANCELLED: the task was canceled by the task
>     submitter.

> The reason code is the extended status of the call and the completion status returned on the ACMS$WAIT_FOR_CALL_END service.

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 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$_INSUFPRM | Error | Not enough arguments were passed to this service.
> ACMS$_INTERNAL | Error | Internal error.
> ACMS$_INVASTADR | Error | The AST address was invalid.
> ACMS$_INVCALLID | Error | The call ID was invalid.
> ACMS$_INVCMPSTS | Error | The completion status block was invalid.
> ACMS$_INVEFN | Error | The event flag was invalid.
> ACMS$_INVREACOD | Error | The reason code parameter was invalid.
> ACMS$_INVSUB | Error | The submitter ID was invalid.
> ACMS$_NTSNIN | Error | Submitter was not signed in.
> ACMS$_OBSCALLID | Error | The call ID is obsolete.
> 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.

# 5.6 ACMS$GET_PROCEDURE_INFO

Finds and returns the procedure ID for the task, the number of workspace arguments the agent program can pass to a task in an ACMS application, and the I/O method (forms, terminal, request, stream, or none).

If application reprocessing is necessary, use ACMS$GET_PROCEDURE_INFO before using ACMS$CALL, ACMS$CALL_A, ACMS$START_CALL, or ACMS$START_CALL_A.

## Format

> ACMS$GET_PROCEDURE_INFO ([submitter_id.rq.r],
> procedure.rt.dx,
> package.rt.dx,
> item_list.rx.r)

> ACMS$GET_PROCEDURE_INFO_A ([submitter_id.rq.r],
> procedure.rt.dx,
> package.rt.dx,
> item _list.rx.r,
> [comp_status.wq.r],
> [efn.rbu.r],
> [astadr.szem.r],
> [astprm.rz.v])

## Parameters

> ### submitter_id

> The identification of the task submitter that the ACMS$SIGN_IN service returns.

> This parameter is optional for agent programs that do not use ACMS$SIGN_IN. Use of the default submitter feature, however, is not recommended for new development. See Section 2.1.6 and Section 2.1.7 for discussions of this point.

> ### procedure

> The name of the task for which you want to find information. The name passed must be in capital letters, but can include trailing blanks.

> ### package

> The name of the application from which you want to select the task. The name passed must be in capital letters, but can include trailing blanks. However, if the package parameter is a logical name, then the equivalence name or names cannot contain trailing blanks.

> ### item_list

> The list of one or more item descriptors that describe the task I/O method, WAIT/DELAY information, or procedure ID. An item descriptor has the following format:

Item descriptors have the following characteristics:

- Buffer length
  The length of the buffer pointed to by the buffer address.
- Item code
  The symbolic name defining the requested information.
- Buffer address
  The address of a buffer to receive the requested information.
- Return length address
  The address of the word to receive the length of the information returned. If you specify this address as zero, no length is returned.

The possible item codes are:

- ACMS$K_PROC_PROCEDURE_ID
  The quadword procedure ID associated with the input task name and application name. The buffer to receive the information returned by ACMS$K_PROCEDURE_ID is equal in length to ACMS$S_PROCEDURE_ID, eight bytes. The agent program uses the procedure ID to identify a task when the agent program calls the task using the ACMS$CALL or ACMS$START_CALL service. The procedure ID becomes invalid when either the application stops or all the task submitters who selected tasks in the application sign out.
  If the ACMS$CALL or ACMS$START_CALL services use a procedure ID that has changed, they receive the ACMS$_NOSUCH_PKG error message. When an agent program receives this error, it can call the ACMS$GET_PROCEDURE_INFO service to get the new procedure ID for the task.
- ACMS$K_PROC_IO_METHOD
  The I/O method used by the task. ACMS$K_PROC_IO_METHOD returns a longword. This value can be one of the following symbols:
  - ACMS$K_IO_TERMINAL
    The task uses the terminal directly. The task cannot be selected remotely.
  - ACMS$K_IO_DECFORMS
    The task performs DECforms request I/O in exchange steps. The task can be selected remotely.
  - ACMS$K_IO_REQUEST
    The task either performs TDMS request I/O in exchange steps or uses the RI. The task can be selected remotely.
  - ACMS$K_IO_STREAM
    The task uses ACMS stream I/O. The agent program may have to do I/O work for this task. The task can be selected remotely.
  - ACMS$K_IO_NONE
    The task does not do any I/O. The agent program does not do I/O work for this task. The task can be selected remotely.
- ACMS$K_PROC_WAIT_DELAY_ACTION
  The wait/delay action defined for this task. ACMS$K_PROC_WAIT_DELAY_ACTION returns a longword. The value can be one of the following symbols:
  - ACMS$K_WAIT
    The WAIT clause controls whether or not ACMS displays a message prompting users to press `[Return]`. (Pressing `[Return]` clears the terminal screen and displays the previous ACMS menu.)
  - ACMS$K_DELAY
    The DELAY clause controls whether or not ACMS pauses after a task finishes running before clearing the screen and displaying the ACMS menu.
  - ACMS$K_NO_ACTION
- ACMS$K_PROC_WORKSPACE_COUNT
  The number of workspaces the agent program passes when it calls a task in an ACMS application. ACMS$K_PROC_WORKSPACE_COUNT returns a longword.

You must end the list with an item descriptor that has an item code of zero.

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 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$_INSUFPRM | Error | Not enough arguments were passed to this service.
> ACMS$_INTERNAL | Error | Internal error.
> ACMS$_INVASTADR | Error | The AST address was invalid.
> ACMS$_INVBUFADR | Error | The buffer address in an item descriptor was invalid.
> ACMS$_INVCMPSTS | Error | The completion status block was invalid.
> ACMS$_INVEFN | Error | The event flag was invalid.
> ACMS$_INVITEMCODE | Error | The item code in an item descriptor was invalid.
> ACMS$_INVITEMDESC | Error | An item descriptor in the item list was invalid.
> ACMS$_INVITEMLIST | Error | The item list was invalid.
> ACMS$_INVPACKAGE | Error | The application name was invalid.
> ACMS$_INVPROCEDURE | Error | The procedure name was invalid.
> ACMS$_INVRETLEN | Error | The return length in an item descriptor was invalid.
> ACMS$_INVSUB | Error | The submitter ID was invalid.
> ACMS$_NOSUCH_PKG | Error | There is no such application defined.
> ACMS$_NOSUCH_PROC | Error | There is no such procedure defined.
> 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.

Previous | Next | Contents | Index