START

Schedules a task in a local or a remote system.

Syntax


START

>>-START--+------------------------------------+---------------->
          +-INTERVAL(hhmmss)-------------------+   
          +-TIME(hhmmss)-----------------------+   
          |        .-------------------------. |   
          |        V                         | |   
          +-AFTER----+-HOURS(data-value)---+-+-+   
          |          +-MINUTES(data-value)-+   |   
          |          '-SECONDS(data-value)-'   |   
          |     .-------------------------.    |   
          |     V                         |    |   
          '-AT----+-HOURS(data-value)---+-+----'   
                  +-MINUTES(data-value)-+          
                  '-SECONDS(data-value)-'          

>--TRANSID(name)--+-------------+------------------------------->
                  '-REQID(name)-'   

>--+-------------------------------------+--+--------------+---->
   '-FROM(data-area)--LENGTH(data-value)-'  '-TERMID(name)-'   

>--+-------------------+--+----------------+-------------------->
   '-SYSID(data-value)-'  '-RTRANSID(name)-'   

>--+---------------+--+-------------+--+---------+-------------->
   '-RTERMID(name)-'  '-QUEUE(name)-'  '-NOCHECK-'   

>--+---------+-------------------------------------------------><
   '-PROTECT-'

Conditions: INVREQ, IOERR, ISCINVREQ, LENGERR, NOTAUTH, SYSIDERR, TERMIDERR, TRANSIDERR

Note: hhmmss not supported for C or C++ programs.

Description

START starts a task, on a local or a remote system, at a specified time. The starting task can pass data to the started task and can also specify a terminal that is to be used by the started task as its principal facility.

The START command is processed on the system that is identified by the SYSID option.

You can use the RTRANSID, RTERMID, and QUEUE options to pass further data to the started task. These options can contain arbitrary data values whose meanings depend on what you have specified in the started and starting tasks. One possible way of using them is in the following condition. One task can start a second task, passing it a transaction name and a terminal name that is to be used when the second task starts a third task. The first task can also pass the name of a queue that is to be accessed by the second task. If you use QUEUE to pass the name of a temporary storage queue on which to store data to a started transaction, it must not be the same as the name that you specified in REQID, if used.

If data is to be passed by interval control (using the FROM option), it is queued on a temporary storage queue whose name you specified in the REQID option, if one is provided. This identifier should be recoverable (in temporary-storage terms) if the PROTECT option is also specified, or unrecoverable if PROTECT is not specified; otherwise, unpredictable results can occur. Such problems cannot occur if REQID is not used.

The NOCHECK option specifies that no response (to execution of the START command) is expected by the starting transaction. For START commands that name tasks that are to be started on a local system, error conditions are returned, whereas those for tasks that are to be started on a remote system are not returned. The NOCHECK option allows CICS® to improve performance when the START command has to be shipped to a remote system; it is also a prerequisite if the shipping of the START command is queued pending the establishing of links to the remote system.

If a START NOCHECK request has been locally queued, then it can be removed after the purge delay period, if the request has not been transmitted. Specifying the PROTECT option has no effect on purging of requests.

Transactions that are to be dispatched by using START commands are dispatched in accordance with the usual summation of transaction, terminal, and user priorities.

One or more constraints must be satisfied before the transaction that is to be executed can be started, as follows:

The specified interval must have elapsed or the specified expiration time must have been reached.
The INTERVAL or AFTER option should be specified when a transaction is to be executed on a remote system; this avoids complications occurring when the local and remote systems are in different time zones.
If the TERMID option is specified, the named terminal must be available.
If the PROTECT option is specified, the starting task must have taken a successful syncpoint.

This option, coupled to extensions to resource definitions, reduces the exposure to lost or duplicated data that is caused by failure of a starting task.

You can use the AFTER and AT options to enter the interval or time value in two ways:

As one of either HOURS(0 through 99), MINUTES(0 through 5999), or SECONDS(0 through 359999). For example, HOURS(1) means one hour; MINUTES(62) means one hour and two minutes; and SECONDS(3723) means one hour, two minutes, and three seconds.
A combination of at least two of HOURS(0 through 99), MINUTES(0 through 59), and SECONDS(0 through 59). For example, HOURS(1) SECONDS(3) means one hour and three seconds (the minutes default to zero).

Related Information

Starting tasks without terminals

If the task that is to be started is not associated with a terminal, each START command results in a separate task being started. This happens regardless of whether data is passed to the started task.

The following examples show how to start, in one hour, a specified task that is not associated with a terminal:

EXEC CICS START
          TRANSID('TRNL')
          INTERVAL(10000)
          REQID('NONGL')

EXEC CICS START
          TRANSID('TRNL')
          AFTER HOURS(1)
          REQID('NONGL')

Starting tasks with terminals but without data

Only one task is started if several START commands, each specifying the same transaction and terminal, expire at the same time or before terminal availability.

The following examples show how to request initiation of a task that is associated with a terminal. Because no request identifier is specified in this example, CICS assigns one and returns it to the application program in the EIBREQID field of the EXEC Interface Block (EIB).

EXEC CICS START
          TRANSID('TRN1')
          TIME(185000)
          TERMID('STA5')

EXEC CICS START
          TRANSID('TRN1')
          AT HOURS(18) MINUTES(50)
          TERMID('STA5')

Starting tasks with terminals and data

Data is passed to a started task if one or more of the FROM, RTRANSID, RTERMID, and QUEUE options is specified. Such data is accessed by the started task through execution of a RETRIEVE command.

It is possible to pass many data records to a new task by issuing several START commands, each specifying the same transaction and terminal.

Execution of the first START command ultimately causes the new task to be started and allows it to retrieve the data that is specified on the command. The new task can also retrieve data that is specified on subsequently executed START commands that expire before the new task is terminated and that have the same TRANSID and TERMID as does the retrieving task.

The following examples show how to start a task that is associated with a terminal and pass data to it:

EXEC CICS START
          TRANSID('TRN2')
          TIME(173000)
          TERMID('STA3')
          REQID(DATAREC)
          FROM(DATAFLD)
          LENGTH(100)

EXEC CICS START
          TRANSID('TRN2')
          AT HOURS(17) MINUTES(30)
          TERMID('STA3')
          REQID(DATAREC)
          FROM(DATAFLD)
          LENGTH(100)

Start failures without conditions

If the transaction or terminal that is named in a START command is disabled, no condition occurs; the START command executes without error, but no task is actually started. You can use INQUIRE commands to ensure that the transaction, its associated programs, and the terminal are all enabled at the time of the START, but any of these might become disabled before task creation.

Options

AFTER

Together with one or more of the HOURS, MINUTES, and SECONDS options, specifies the interval of time that is to elapse before the new task is started.

This option must be used instead of INTERVAL in C or C++ programs. AFTER HOURS(0) is the default.

AT

Specifies the time at which the new task is to be started.

This option must be used instead of TIME in C or C++ programs.

FROM(data-area)

Specifies the data that is to be stored for a task that is to be started at some future time.

HOURS(data-value)

Specifies, as a 32-bit binary value, the number of hours for use in conjunction with AFTER or AT. The value must be in the range 0 through 99.

INTERVAL(hhmmss)

(This option is for COBOL only.) This option specifies the interval of time that is to elapse from the time at which the START command is issued until the new task is started. The specified interval is added to the current clock time by CICS to calculate the new task start time.

The INTERVAL option is not supported for C or C++ programs, which should use the corresponding AFTER option instead.

INTERVAL(0) is the default. The maximum permitted INTERVAL value is 995959.

LENGTH(data-value)

Specifies, as a 16-bit binary value, the length of the data that is to be stored for the new task. For more information about using this option, see LENGTH.

MINUTES(data-value)

Specifies, as a 32-bit binary value, the number of minutes for use in conjunction with AFTER or AT. The value must be in the range 0 through 59 if HOURS or SECONDS is also specified, or in the range 0 through 5959 otherwise.

NOCHECK

Specifies that, for a remote system, CICS should optimize the execution of the START command to improve performance by providing less error checking and slightly less function. For more information, see Improving performance of intersystem START requests.

PROTECT

Specifies that the new task is not to start until the starting task has taken a syncpoint. If the starting task abends before the syncpoint is taken, the request to start the new task is canceled. If the REQID option is also specified, the request identifier should be a name that is defined as recoverable to temporary storage. If the started transaction is remote, PROTECT specifies that it must not be scheduled until the local transaction has successfully completed a syncpoint. For more information about the PROTECT option with remote transactions, see Timer services.

QUEUE(name)

Specifies the name of a temporary storage queue that can be used by the started transaction. The name must be eight bytes long.

REQID(name)

Specifies a name that uniquely identifies the START command. This name is used as a temporary storage identifier. The temporary storage queue thus identified must be defined as a local queue on the CICS region in which the START command is processed.

When you write applications in COBOL, the name can be up to eight characters long, each of which can contain any bit pattern; and it must be unique within the CICS system. Do not use X'FA' through X'FF' as the first character of the name; these characters are reserved for CICS use.

The same rules apply when using C or C++, C, except that the name must be a full eight characters in length. Names that are less than eight characters should not be used.

The same rules apply when using PL/I, except that the name must be a full eight characters in length. Names that are less than eight characters should not be used.

If you include the FROM option, the data that is supplied in the FROM option is stored in temporary storage, using the specified REQID name as the name of the temporary storage queue.

This option can be used when another task is to be provided with the capability of canceling an unexpired START command.

If this option is omitted, CICS generates a unique request identifier in the EIBREQID field of the EXEC Interface Block (EIB), unless the NOCHECK option is specified, in which case EIBREQID is set to blanks and cannot be used subsequently to cancel the START command.

RTERMID(name)

Specifies a value such as a terminal name that can be retrieved when the transaction that is specified in the TRANSID option of the START command is started. The name can be up to four characters long.

When retrieved, the value can be used in the TERMID option of a subsequent START command.

RTRANSID(name)

Specifies a value such as a transaction name that can be retrieved when the transaction that is specified in the TRANSID option of the START command is started. The name can be up to four characters long.

When retrieved, the value can be used in the TRANSID option of a subsequent START command.

SECONDS(data-value)

Specifies, as a 32-bit binary value, the number of seconds for use in conjunction with AFTER or AT. The value must be in the range 0 through 59 if HOURS or MINUTES is also specified, or in the range 0 through 359999 otherwise.

SYSID(name)

Specifies on which CICS region the START is to run. The SYSID name has from one to four characters. For a full description of the SYSID option, see SYSID.

If the SYSID option is not specified, it defaults to the value that is in the RemoteSysId attribute of the Transactions Definitions (TD) entry for the transaction that is requested in the TRANSID option. A SYSID cannot be used instead of a TERMID.

TERMID(name)

Specifies the symbolic identifier of the terminal that is associated with a transaction that is to be started as a result of a START command. This option is required when the transaction that is to be started must communicate with a terminal; it should be omitted otherwise. The name must be alphanumeric and up to four characters long.

The terminal identifier must be defined as either a local or a remote terminal in the Terminal Definitions (WD) on the system in which the START command is executed, when the start of the transaction takes effect.

TIME(hhmmss)

(This option is for COBOL only.) This option specifies the time at which the new task is to be started. See Time arguments.

The TIME option is not supported for C or C++ programs, which should use the corresponding AT option instead.

TRANSID(name)

Specifies the transaction that is to be started. The TRANSID name has from one to four characters. If the SYSID option is not used to specify a remote SYSID, this transaction must have an entry in the Transactions Definitions (TD)

Conditions

INVREQ

Occurs for the following conditions, depending on the options that are specified on the START command:

Hours are out of range.
Minutes are out of range.
Seconds are out of range.
The function-shipped START command specifies a REQID name that already exists.