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:

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