# Compaq ACMS for OpenVMS
Systems Interface Programming

Previous | Contents | Index

# 5.7 ACMS$START_CALL

Submits an ACMS task. This service completes when the task has been submitted. It returns a call ID to the agent program.

Before using ACMS$START_CALL or ACMS$START_CALL_A, the agent program must use the ACMS$GET_PROCEDURE_INFO service to get the task procedure ID and the task I/O method. Because ACMS$START_CALL only starts the task, you must use it with the ACMS$WAIT_FOR_CALL_END service, which waits for the task to end.

If the task being called performs stream I/O, the agent program must create a stream using the ACMS$INIT_EXCHANGE_IO service before calling the task. This service creates the stream, connects to it, and returns a connect ID to the agent program. See Chapter 6 for details regarding stream creation.

An agent program must also call the ACMS$WAIT service when it uses the asynchronous service ACMS$START_CALL_A. See Chapter 2 for a complete explanation of the ACMS$WAIT service.

## Format

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

> ACMS$START_CALL_A ([submitter_id.rq.r],
> procedure _id.rq.r,
> call _id.wq.r,
> [arguments.rz.r],
> [tid.ro.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.

> ### procedure_id

> The identification of the procedure to call. The agent program obtains the procedure ID by calling the ACMS$GET_PROCEDURE_INFO service.

> ### call_id

> The identification that is produced by this service. The ACMS$WAIT_FOR_CALL_END and the ACMS$CANCEL_CALL services use this ID later.

> ### arguments

> The list of arguments to pass. (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 the 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 initializes the first task argument workspace defined in the TASK ARGUMENTS clause of the task definition. The fifth argument initializes 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$_ERRREADARG | Error | Error during task initialization; cannot read an argument in the argument list.
> 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$_INVCALLID | Error | The call ID was invalid.
> ACMS$_INVCANAST | Error | The cancel user routine was invalid.
> ACMS$_INVCMPSTS | Error | The completion status block was invalid.
> ACMS$_INVEFN | Error | The event flag was invalid.
> ACMS$_INVEXTCANSTS | Error | The extended cancel status was invalid.
> ACMS$_INVPROCID | Error | The procedure ID was invalid.
> ACMS$_INVSELSTR | Error | The selection string 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_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$_SRVDEAD | Error | The server died 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$_USERMODE | Error | This service must be called from user mode.

# 5.8 ACMS$WAIT_FOR_CALL_END

Waits for a task to complete. This service waits only for tasks that were started with ACMS$START_CALL. This service also reports access errors that occurred after the task was submitted.

When using the asynchronous ACMS$WAIT_FOR_CALL_END_A service, an agent program must also use the ACMS$WAIT service. See Chapter 2 for a complete explanation of the ACMS$WAIT service.

Note Access control list (ACL) checking for ACMS tasks is done after the task has been submitted. Access errors are reported in the completion status returned in the ACMS$WAIT_FOR_CALL_END service.

## Format

> ACMS$WAIT_FOR_CALL_END ([submitter_id.rq.r],
> call_id.rq.r )

> ACMS$WAIT_FOR_CALL_END_A ([submitter_id.rq.r],
> call _id.rq.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. This 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 discussions of this point.

> ### call_id

> The call ID for which this service is waiting. The ACMS$START_CALL service returns this ID.

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$_CANCELD | Informational | The task was cancelled.
> ACMS$_PENDING | Informational | Successful operation pending asynchronous completion. The final status is in the completion status block.
> ACMS$_WAIT_PROG | Warning | Wait-for-call-end is already in progress for this call.
> ACMS$_APPL_NOT_STARTED | Error | Cannot run task until application is started.
> ACMS$_CALL_CANCELLED | Error | Task was canceled by the task submitter.
> ACMS$_EXCPTN_STEPACTN | Error | Exception results from a step action in the task definition.
> ACMS$_INSUFPRM | Error | Not enough arguments were passed to this service.
> 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$_INVSUB | Error | The submitter ID was invalid.
> ACMS$_MAX_TASKS | Error | Error during task initialization; application maximum task instances exceeded.
> ACMS$_NEED_DEVICE | Error | Task requires a device; none provided.
> ACMS$_NEED_DEVORR | Error | Task requires a device name or RR server.
> ACMS$_NEED_IOID | Error | Task is defined with I/O.
> ACMS$_NTSNIN | Error | Submitter was not signed in.
> ACMS$_OBSCALLID | Error | The call ID is obsolete.
> ACMS$_OPR_CANCELED | Error | Task canceled by system operator.
> ACMS$_SECURITY_CHECK_FAILED | Error | Error during task initialization; security check failed.
> ACMS$_SIGNOUT_ACTIVE | Error | A sign-out is active.
> ACMS$_SRVDEAD | Error | The server stopped unexpectedly.
> ACMS$_SRVNOTFOUND | Error | The server was not found.
> ACMS$_SUB_CANCELED | Error | The submitter was canceled via an operator request.
> ACMS$_SYNASTLVL | Error | Synchronous services may not be called from AST level.
> ACMS$_TASK_ABORT | Error | The task completed abnormally.
> ACMS$_TASK_SP_DIED | Error | Cancel results from the server process dying.
> ACMS$_TRANSTIMEDOUT | Error | Transaction did not complete within specified time limit.
> ACMS$_TSS$_ILLDEVCHAR | Error | Cancel results from a TDMS error; illegal device characteristics.
> ACMS$_USERMODE | Error | This service must be called from user mode.

Previous | Next | Contents | Index