Digital

NAME

CALL TASK − Invokes an STDL task for immediate execution
 

SYNOPSIS

 [<label-name>:] CALL TASK <task-name>
 
                 [ WITH { DEPENDENT | INDEPENDENT } WORK ]
 
                 [ IN <task-group-name> [ AT <destination-name> ]]
 
                 [ USING { <workspace-name> } [ ,... ]] ;
 

PARAMETERS

       •label-name
 
An internal unqualified identifier associated with the statement, for use in flow control operations.

       •task-name
 
A qualified external identifier giving the name of the task to call. The task name specified in CALL TASK must match the name of a task interface defined in the called task’s task group specification.

       •task-group-name
 
An unqualified external identifier giving the name of a task group specification that contains the task interface specified for the task name in CALL TASK. The task group name is used when the task is compiled.
 
The task group name cannot exceed 17 characters. Characters beyond 17 are truncated. The total number of characters in the task group name, plus the number of digits in the major version number and the minor version number must not exceed 19 characters.
 
The task group specification that contains the TASK ARGUMENTS associated with the task definition must be available when you compile the task definition. Each task group name refers to a single task group specification at a destination name (the local node,  or as determined by the destination name parameter defined below).

       •destination-name
 
An operating system name giving a DCE namespace entry. For example:
 
  /.:/acmsxp/avertz_hq_profile
 
The namespace entry is a default profile name for the avertz_hq TPsystem.
 
If you specify the AT clause, you must supply the IN clause.
  You can use a shell environment variable to represent the destination name. For more information about namespace profiles and namespace entries, and representing them with shell environment variables, see ACMSxp Developing and Managing Applications. 

       •workspace-name
 
Either an unqualified internal identifier for the name of a private workspace or an unqualified external identifier for the name of a shared workspace used for data storage and for arguments passed in task calls. You must declare the workspaces in the task arguments of the task definition of the called task.
 
The workspace name of a private workspace must be unique within a task definition. The workspace name of a shared workspace must be unique within a task group specification. A workspace name cannot be used for both a private workspace and a shared workspace in the same task definition.

DESCRIPTION

If the CALL TASK is used in a noncomposable task, it must be inside a transaction block. 
 
The node or system on which the calling task executes is called the client node. The node on which the called task executes is the server node. The client node can be the same node as the server node or another node.
 
A called task can be within the same task group or in another task group. The task group that contains the called task can be in the same TP system or different TP systems. The TP systems can be on the same node or on different nodes.
 

Including a Called Task in a Transaction

 
A called task can be included in the transaction of the calling task. If the called task is composable, the called task participates in the same transaction as that of the caller and the default is WITH DEPENDENT WORK. Do not specify WITH INDEPENDENT WORK when calling a composable task.
 
If the called task is noncomposable, the called task does not participate in the same transaction as that of the caller and the default is WITH INDEPENDENT WORK. Do not specify WITH DEPENDENT WORK when calling a noncomposable task.
 
If a task call specifying WITH INDEPENDENT WORK calls a composable task, or if a task call specifying WITH DEPENDENT WORK calls a noncomposable task, the STDL compiler returns an error.
 

Using IN and AT to Specify the Location of a Called Task

 
The IN and AT keywords can appear in any order.
 
Specifying IN and AT in CALL TASK act as follows:

oIf the called task is in the same task group as the calling task, omit IN and AT. If you specify neither IN nor AT, the called task executes in the same task server as the calling task. The client does not need to use a destination to determine the server, because the server is the same as the client. 
 

oIf you use IN and omit AT, the client determines the location of the server from a default destination set by the environment name RPC_DEFAULT_ENTRY environment variable. 
 
The namespace entry within the destination that matches the server task group identification and has a compatible version determines the server. The UUID in the namespace uniquely identifies the task group.
 
Use ACMSxp system administration to define the value of RPC_DEFAULT_ENTRY in the environment variable attribute of the calling server. For more information about namespace entries and defining them in an environment variable attribute, see ACMSxp Developing and Managing Applications. 
 

oIf you specify AT, you must also specify IN. 
 
The calling server looks up the namespace entry (for example, a server, profile, or group entry) to determine the destination task server. ACMSxp software places no restrictions on the use of the namespace.

Specifying Arguments in USING

 
Workspaces are passed by reference.
 
The record layouts associated with the workspace names listed in the USING phrase arguments correspond in order to the data type definitions associated with the data type identifiers in the task group specification of the called task. The corresponding data type definitions must match in number, data types for fields, and lengths of fields within workspaces. See the task_argument man page.
 
The normal execution flow for a CALL TASK statement is:

     1.Calls the task, passing the INPUT or INOUT arguments defined in the task arguments of the calling task. 

oIf DEPENDENT WORK is in effect, the called task participates in the same transaction as the calling task. 
 

oIf INDEPENDENT WORK is in effect, the called task does not participate in the same transaction as the calling task. 

     2.When the called task completes, returns the arguments defined as OUTPUT or INOUT to the corresponding workspaces. 
 

     3.Completes with default flow control. 

The execution flow differs from the sequence described above when:

oOne of the conditions listed in the Exceptions section occurs. The called task completes with the exception and the values of the workspaces corresponding to the arguments defined as OUTPUT or INOUT are no longer valid. 
 

oIf the called task modifies any arguments passed as INPUT, the results are no longer valid. 

EXCEPTIONS

 
The CALL TASK statement can generate the exception classes described in the following sections. The sections describe the conditions leading to the exception class and can suggest actions to take.
 
The called task can raise and return any exception class to the calling task.
 

AP-EXECUTION-FAULT

 
The AP-EXECUTION-FAULT exception class indicates one of the following error conditions:

oNoncomposable task was called to execute within the client task transaction. 
 

oComposable task was called to execute independently from the client task transaction. 
 

oThe subscript used to refer to an element in a fixed-length array is invalid (referring to A(n) where n is less than one or n is greater than the maximum size of the array). 
 

oThe subscript used to refer to an element in a variable-length array is invalid (referring to A(n) where n is less than one or n is greater than the value of the DEPENDING ON field). 
 

oThe value of the DEPENDING ON field used when referring to an element of a variable-length array is invalid (the value of the DEPENDING ON field is less than the minimum size of the array or the value of the DEPENDING ON field is greater than the maximum size of array). 
 

oThe value of the DEPENDING ON field was invalid when referring to a workspace name or workspace field containing a variable-length array. 

AP-INVOCATION-FAULT

 
The AP-INVOCATION-FAULT exception class indicates that a specification mismatch occurred on a CALL TASK. The task group specification that was used when compiling and linking the calling task definition into an executable server is incompatible with the task group specification that was used when compiling and linking the called task definition into an executable server.
 

AP-RESPONSE-FAULT

 
The AP-RESPONSE-FAULT exception class indicates that the results of the CALL TASK could not be returned to the calling task because of a syntax error.
 

ENV-EXECUTION-ERROR

 
The ENV-EXECUTION-ERROR exception class indicates one of the following error conditions:

oThe task specified by the task name in the CALL TASK could not complete because of a system failure on the server TP system. 
 

oThe task specified by the task name in the CALL TASK could not complete and return results of the call because of a communications failure between the client TP system and the remote server TP system. 

ENV-INVOCATION-ERROR

 
The ENV-INVOCATION-ERROR exception class indicates one of the following error conditions:

oThe task specified by the task name in the CALL TASK could not be started because the task instance high- water mark was exceeded on the server TP system. 
 

oThe task specified by the task name in the CALL TASK is disabled. 
 

oThe task specified by the task name in the CALL TASK could not be started because the server TP system was not available as a result of not being started or because of a system failure. 
 

oThe task specified by the task name in the CALL TASK is not available because of a system failure. 
 

oThe task specified by the task name in the CALL TASK is not available because of a communications failure. 

ENV-INVOCATION-FAULT

 
The ENV-INVOCATION-FAULT exception class indicates one of the following error conditions:

oThe task group specified by the IN task group name is not defined within the server environment information. 
 

oThe task specified by the task name in the CALL TASK could not be started because access to the called task is being denied. 
 

oThe destination specified by the value of the AT destination name is not defined within the environment information of the TP system in which the calling task is executing. 
 

oIf the destination was not explicitly specified in the CALL TASK, the destination specified by the IN task group name is not defined within the environment information of the TP system in which the calling task is executing. 
 

The task specified by the task name in the CALL TASK could not be started because the client TP system is executing a task call on the same dialogue as a previous task call to a server TP system that accepts only a single task call per dialogue. 
 

oThe UUID in the task group specification used by the client program is not equal to the UUID used by the server task. 
 

oThe major version number used by the client program is not equal to the major version number used by the server task. 
 

oThe major version number used by the client program is equal to the major version number used by the server task, but the minor version number used by the client program is greater than the minor version number used by the server task. 

ENV-UNSPECIFIED-FAULT

 
The ENV-UNSPECIFIED-FAULT exception class indicates that the called task did not complete because of an unknown error condition in the RTI protocol.
 

RELATED INFORMATION

Syntax: exception_handler(1), statement(1), task_argument(1), task_definition(1), transaction_block(1)

acmsxp_introduction(1)