Digital

NAME

SUBMIT TASK − statement in a task that enqueues a request for the delayed execution of another task

SYNOPSIS

 [<label-name>:]  SUBMIT TASK <task-name>
 
                  [ IN <task-group-name>] [AT <destination-name>]
                  [ { ID | IDENTIFIER } <identifier-field> ]
                  [ HOLD
                    { FOR { <delta-time> | OPERATOR } |
                      UNTIL <absolute-time>
                        [ OF { CLIENT | SUBMITTER } SYSTEM ]
                    }
                  ]
                  [ REPEATING EVERY <delta-time> ]
                  [ WITH { DEPENDENT | INDEPENDENT } WORK ]
                  [ USING <workspace-name> [ ,... ] ] ;

PARAMETERS

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

       •task-name
 
A qualified internal identifier giving the name of the task definition to submit. The task name specified in SUBMIT TASK must match the name of a task interface defined in the submitted task’s task group specification.

       •task-group-name
 
An unqualified internal identifier giving the name of a task group specification that contains the task interface specified for the task name in the SUBMIT TASK. The task group name can be up to 17 characters. If you do not specify IN and the task group name, the task group is one in which the calling task runs, and you cannot specify the AT clause.
 
The task group specification that contains the task arguments associated with the task definition must be available when you compile the task definition.

       •destination-name
 
An s-text workspace field or an operating system name literal giving a namespace profile (for example, a default TPsystem namespace profile) or a namespace entry for the server.
 
You can use an environment variable to represent the destination name. For more information about namespace profiles and namespace entries, and representing them with environment variables, see
 
If you specify AT, you must specify IN.

       •identifier-field
 
An array workspace field of 16 octets (ARRAY SIZE 16 OF OCTET). A submit identifier (or a request queue element ID in ACMSxp system management) uniquely identifies each request in the queue of submitted requests. When ACMSxp software enqueues the request, it generates a unique identifier, and stores the unique identifier value in the workspace field with id-workspace field format. The contents of the field are opaque and guaranteed to be unique within the TPsystem.
 
Use the contents of the id-workspace field in the CANCEL SUBMIT statement to uniquely identify the request to be removed for the request queue.

       •delta-time
 
An n-string literal or an s-text workspace field of 10 characters giving a time duration expressed as an offset from the current date and time. If the delta time is used in HOLD FOR, it specifies the amount of time for which the submit task is held in the request queue. If the delta time is used in REPEATING EVERY, it specifies the interval at which the submit task is repeated after successful completion of the first submit task operation.
 
An n-string literal is a string literal that can contain only the numeric characters 0 through 9 from the Simple Latin character set. An s-text workspace field is a workspace field of data type TEXT CHARACTER SET SIMPLE-LATIN. The format for delta time is:
 
 ddddhhmmss
 
where:
 
 dddd    Number of days from 0000 through 9999
 hh      Number of hours from 00 through 23
 mm      Number of minutes from 00 through 59
 ss      Number of seconds from 00 through 59

       •absolute-time
 
An n-string literal or an s-text workspace field of 14 characters giving a time value expressed as a specific date and time of day until which the request is held in the queue.
 
An n-string literal is a string literal which can contain only the numeric characters 0 through 9 from the Simple Latin character set. An s-text workspace field is a workspace field of data type TEXT CHARACTER SET SIMPLE-LATIN. The format for absolute time is:
 
 yyyymmddhhmmss
 
Where:
 
 yyyy      Year from 0000 through 9999
 mm        Month of the year from 01 through 12
 dd        Day of the month from 01 through 31
 hh        Hour of the day from 00 through 23
 mm        Minute of the hour from 00 through 59
 ss        Second of the minute from 00 through 59

       •workspace-name
 
Either an unqualified internal identifier giving the name of a private workspace or a unqualified external identifier giving the name of a shared workspace.
 
You must declare the workspace name in the task arguments of the task definition of the called task. Any task arguments must have the characteristic of INPUT. No arguments can be returned.
 
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.
 
The data type identifiers for the workspace names listed in USING must correspond in order to the data type identifiers listed in the USING clause of the task arguments in the submitted task’s task group specification. The corresponding data type definitions must match in number, data types for fields, and lengths of fields with workspaces.
 

DESCRIPTION

 
If SUBMIT TASK is used in a noncomposable task, it must be inside a transaction block.
 
The submitted task executes independently from the submitting task, and can be queued for delayed execution. The submitting task:

oSupplies the initial input data, if any, for the submitted task. 

oSpecifies whether the enqueue operation is done within the transaction of the submitting task. 

oSpecifies whether the dequeue operation is done within the transaction of the dequeuer task. 

oWaits for the enqueue operation to complete before continuing execution, but does not wait for the submitted task to complete before continuing execution. 

oDoes not receive any output or exceptions from the submitted task. 

oCan receive an exception from the enqueue operation on the request queue database. 

 
With the following restrictions, the syntax elements can appear in any order:

oThe SUBMIT TASK must be first. 

oIf the WITH clause is specified, it must follow the other syntax elements and precede the USING clause, if specified. 

oUSING, if specified, must be last. 
 

Enqueue and Dequeue Transactional Semantics

 
You have the following options regarding submitted tasks and the transactions of the the enqueue and dequeue operations.

oEnqueue the task transactionally and dequeue it transactionally (DEPENDENT submit of a composable task). 

oEnqueue the task transactionally and dequeue it nontransactionally (DEPENDENT submit of a noncomposable task). 

oEnqueue the task nontransactionally and dequeue it nontransactionally (INDEPENDENT submit of a noncomposable task). 

oEnqueue the task nontransactionally and dequeue it transactionally (INDEPENDENT submit of a composable task). 

 
Running under each TPsystem that processes the submitted task, an ACMSxp system server (called the request queue server) acts as the submitted task enqueuer and dequeuer.
 

Enqueuing the Submitted Task Transactionally or Nontransactionally

 
Using either WITH INDEPENDENT WORK or WITH DEPENDENT WORK, you specify that a submission of a task to a queue be independent of or dependent on the submitting task transaction:

oWITH DEPENDENT WORK specifies that the enqueue operation of the task named in the SUBMIT TASK is in the same transaction as the submitting task. That is, if the submitting task transaction rolls back, the enqueue operation rolls back. Likewise, if the enqueue operation fails, the submitting task rolls back its transaction. 
 
If the enqueue operation is done within the transaction of the submitting task, the submission request is available for forwarding or calling by another task when and if the transaction of the submitting task commits.
 
The default for a restartable task is WITH DEPENDENT WORK.

oWITH INDEPENDENT WORK specifies that the enqueue operation of the task named in the SUBMIT TASK is not in the same transaction as the submitting task. The submitting task continues to execute regardless of the success of the enqueue operation. The request is available for initiation or forwarding when the enqueue operation completes even if the submitting task rolls back its transaction. 
 
The default for a nonrestartable task is WITH INDEPENDENT WORK.
 
                            Note
 
        Compare the difference between a submitted task and a
        called task, which if called WITH INDEPENDENT WORK
        must be noncomposable, and which if called WITH
        DEPENDENT WORK must be composable. See the call_task
        man page.

 
Be aware of limitations on the integrity of a submitted task, if it contains multiple transactions. For example, if a restartable submitting task restarts and resubmits a two-transaction task in which the first transaction previously committed and the second transaction previously rolled back, the first transaction could execute twice.
 

Dequeuing the Submitted Task Transactionally or Nontransactionally

 
You can submit either a composable task or a noncomposable task. The composability of the submitted task determines whether the execution of the submitted task participates in the transaction of the dequeuer task (started by the ACMSxp request queue server).

oSubmitting a composable task
 
The ACMSxp system dequeues the composable task transactionally. The execution of the submitted task occurs within the transaction of the dequeuer task. The submitted task is not deleted from the queue until the submitted task succeeds. If the submitted task does not complete successfully, it can automatically be retried.

oSubmitting a noncomposable task
 
The ACMSxp system dequeues the noncomposable task nontransactionally. The execution of the submitted task and the dequeue operation are not related. The submitted task is dequeued nontransactionally with respect to the execution of the submitted task. The submitted task is deleted from the queue when the dequeue operation succeeds regardless of whether the submitted task succeeds. The submitted task cannot be automatically retried.
 

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

 
A task can submit a task to execute on its own or on another TP system. However, you can submit a composable task only to the local TP system, and you can submit a noncomposable task to the local or a remote TP system.
 
The TP system of the submitting task uses the destination name to map the submission request to the appropriate TP system. IN and AT with a SUBMIT TASK act as follows:

oIf the submitted task is in the same task group as the submitting task, you do not need IN and AT. 
 
If you use neither IN nor AT, the local TP system initiates the submitted task on the same node as the submitting task.

oIf you use IN (and not AT), the submitting TP system at the submitting node determines the location of the information needed for task submission from the default destination set by the environment variable RPC_ DEFAULT_ENTRY. The task group namespace entry within the destination that matches the server task group identification and has a compatible version determines the client TP system. The UUID identifies the task group specification. 

oIf you specify AT and the destination name, you must also specify IN. 
 
The submitting TP system uses the specified destination name to determine whether to forward the request. If the destination name is a namespace profile entry, the TP system attempts forwarding. Forward operations are done without transaction control.

 
The ACMSxp software automatically provides entries in a TPsystem default namespace profile that you can use for forwarding. If you want requests forwarded to another TPsystem, specify the namespace name of that TPsystem default namespace profile as the destination. The destination profile must contain:

oThe namespace entry for the target server

oThe namespace entry for the request queue server for the TPsystem to which the submitted request is to be forwarded

 
For the details on specifying destinations and how ACMSxp software sets up the namespace for forward operations, see ACMSxp Developing and Managing Applications
 

Repeating a Task Submission

 
Use REPEATING EVERY syntax to repeat the SUBMIT TASK after the specified interval. The trigger that you specify in HOLD determines the time of the first initiation for the submitted task.

oFOR OPERATOR means that the enqueued request for the task is placed on hold. An ACMSxp system administration directive must release the request for it to be initiated. 

oFOR <delta-time> means that the enqueued request is placed on hold until time duration specified expires.  When the time period is over, the ACMSxp system releases and initiates the request. 

oUNTIL <absolute-time> means that the enqueued request is placed on hold until a specific date and time of day is reached. When that date and time of day arrive, the ACMSxp system releases and initiates the request. 

 
The triggers do not affect forwarding. After the submitted task is initiated and successfully completes, the request is deleted from the queue.
 
The ACMSxp TPsystem uses the time specified in the REPEATING EVERY clause to resubmit a new request to execute the task. The REPEATING EVERY clause does not affect forwarding operations. The repeated request still contains the repeat information. After every successful initiation, the request repeats itself while the repeat information is still in effect. A system administration directive can change the repeat information.
 

ACMSxp System Actions in Task Submission

 
The submitting task can submit a task to be executed on the same TPsystem or on another TPsystem, either on the same node or different node in the network. Regardless, the submitted task is enqueued on the request queue of the TPsystem under which the submitting task runs.
 
The client TPsystem converts the submitted request to a task call. The server (or target) TPsystem contains the called task. The called task can be on the same system as the client TPsystem or on a different TPsystem.
 
If the submitting TP system and the client TP system are the same TP system, the submitting TP system dequeues the submitted request from the request queue and initiates the task. If the submitting TP system and the client TP system are not the same TP system, the submitting TP system can forward the submitted request to the specified client TP system, where it is placed on that TP system request queue and initiated there.
 
A forwarded task submission request occurs outside of a transaction. Both the submitting TP system and the client TP system must process all exceptions:

oThe submitting TP system retries the forward operation (up to the retry limit for that request queue) for the following exceptions:
 
 ENV-EXECUTION-ERROR
 ENV-INVOCATION-ERROR
 TXN-FAILURE-ERROR
 TXN-TIMEOUT-ERROR
 
For other exceptions (or if the retry limit is exceeded), the submitting TP system writes the exception to the event log and places a hold on the queued request. Use ACMSxp system administration software to release or delete the request queue element related to the request.

oThe client TP system retries the task call (or initiate) operation (up to the retry limit for that request queue) for the following exceptions:
 
 ENV-EXECUTION-ERROR
 ENV-INVOCATION-ERROR
 REQUEST-TIMEOUT-ERROR
 TXN-FAILURE-ERROR
 TXN-INCOMPLETE-ERROR
 TXN-TIMEOUT-ERROR
 
For other exceptions (or if the retry limit is exceeded), the client TP system writes the exception to the event log and places a hold on the queued request. Use ACMSxp system administration software to release or delete the request queue element related to the request.

 
The limit on retries and the interval at which retries are attempted are both settable by system administration directives. See ACMSxp Developing and Managing Applications for details of configuring queued request retry operations. 
 

Execution Flow for SUBMIT TASK

 
The normal execution flow for SUBMIT TASK is:

     1.Enqueue the submitted task with the arguments defined in the task arguments of the submitting task. 

     2.If IDENTIFIER is specified, return the identifier of the queued request to the identifier-field field. 

     3.Complete with default flow control. The submitting task does not wait for the submitted task to complete before continuing execution. 

 
If an exception occurs, the SUBMIT TASK completes with the exception associated with the condition.
 

EXCEPTIONS

 
SUBMIT TASK can generate the exception classes described in the following sections. The sections describe the conditions leading to the exception class and suggest actions to take.
 

AP-EXECUTION-FAULT

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

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 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 SUBMIT TASK. The task group specification that was used when compiling the submitting task definition is incompatible with the task group specification that was used when compiling the submitted task definition.
 

ENV-EXECUTION-FAULT

 
The ENV-EXECUTION-FAULT exception class indicates that the submitting TP system encountered a problem storing the submitted task on the request queue.
 

ENV-INVOCATION-ERROR

 
The ENV-INVOCATION-ERROR exception class indicates that the request queue is disabled or that the enqueue operation on the request queue is disabled. Retry the submit.
 

ENV-INVOCATION-FAULT

 
The ENV-INVOCATION-FAULT exception class indicates that the destination specified by the value of destination name is not defined within the environment information of the submitting TP system.
 

RELATED INFORMATION

Syntax: call_task(1), task_argument(1), task_definition(1), transaction_block(1)

acmsxp_introduction(1)