START

Start a task at a specified time.

START

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

Note: For dynamic transaction routing: If a START is later canceled by another task, or if the started transaction uses RETRIEVE WAIT, inter-transaction affinities might be created that adversely affect the use of dynamic transaction routing. For more information, see Affinity.

Description

START starts a task, on a local or remote system, at a specified time. The time is specified by INTERVAL, AFTER, AT, or TIME. See the section about expiration times in Interval control.

The starting task can pass data to the started task. The starting task can also specify a terminal to be used by the started task as its principal facility.

The default is INTERVAL(0), but for C the default is AFTER HOURS(0) MINUTES(0) SECONDS(0).

CEDF is an exception to the START command and is not valid as a TRANSID name. Therefore, do not attempt to start CEDF in this way.

Important: There is a 6-hours rule, if the START gets triggered at any time within 6 hours after the time specified on the START, it executes immediately. This happens regardless of whether the previous 6 hours includes a midnight. To illustrate, here are some examples:

EXEC CICS START TIME(123000)
This command, issued at 05:00 or 07:00 on Monday, expires at 12:30 on the same day.
EXEC CICS START TIME(020000)
This command, issued at 05:00 or 07:00 on Monday expires immediately because the specified time is within the preceding 6 hours.

For more information, see Expiration times.

You can use the RTRANSID, RTERMID, and QUEUE options to pass further data to the started task. These options can contain arbitrary data values with meanings that depend on what is specified in the started and starting tasks. One possible way of using them is in the following situation. One task can start a second task, passing it a transaction name and a terminal name to be used when the second task starts a third task. The first task can also pass the name of a queue to be accessed by the second task.

If you are using an IPIC connection, the maximum length for the FROM data area is 32,500 bytes. This limit allows for the 32,500 byte FROM data area and space for headers.

START with TERMID specified does not propagate the origin data record (ODR), so tasks are always started at a new point of origin.

The following constraints must be satisfied before the transaction to be run can be started:

The specified interval must have elapsed or the specified expiration time must be reached. For more information, see Interval control. Specify the INTERVAL or AFTER options when a transaction is to be run on a remote system, to avoid complications when the local, and remote systems are in different time zones.
If you specify the TERMID option, the named terminal must exist and be available. If the named terminal does not exist when the time interval expires, the START is discarded.
If you specify the PROTECT option, the starting task must take a successful sync point. This option, coupled to extensions to system tables, reduces the exposure to lost or duplicated data caused by failure of a starting task.
If the transaction to be run is on a remote system, the format of the data must be declared to be the same as the data at the local system. Use the RDO options DATASTREAM and RECORDFORMAT. For CICS® to CICS, these options are always the default values. For CICS-to-IMS/VS, make sure that you specify the correct values.

Running a START command that names a transaction in the local system cancels any outstanding POST commands run by the starting task.

You can queue START commands by specifying the LOCALQ option on the RDO TRANSACTION resource definition, as described in TRANSACTION attributes.

Passing data by interval control

If data is to be passed by interval control (by using the FROM option), it is queued on a temporary storage queue. Use the REQID option to specify the name of the temporary storage queue to be used. This identifier might be recoverable (in temporary storage terms) or unrecoverable. For more information on how to define recoverable temporary storage queues, see TSMODEL resources.

If you also specify the PROTECT option, you must define the temporary storage queue identified by the REQID option as recoverable. If you do not specify the PROTECT option, do not define the temporary storage queue as recoverable. Unpredictable results can occur if you do not follow these rules. See Recovery of START requests.

If you specify the FROM and not the REQID option, a default DF prefix temporary storage queue is used. The same rules apply as previously listed; specify the PROTECT option only if you define the DF prefix temporary storage queues as recoverable.

A START command with REQID, issued from a task that was itself initiated by a START with the same REQID, returns an AEIQ abend (IOERR condition) if the FROM data for the task has not been read by a RETRIEVE.

You also receive this error if more than one START command with the same REQID is issued by a task or tasks in the same CICS system. CICS TS regions always reject with an IOERR any START commands that specify a duplicate REQID.

Started tasks without data run without a facility address. Started tasks with data run with a facility address of an ICE until the data is retrieved.

If an ICRX is used, it is saved across restarts. If the START request is subsequently canceled, the ICRX is deleted.

Error checking and performance considerations

The NOCHECK option specifies that no response (to running of the START command) is expected by the starting transaction. For START commands that name tasks to be started on a local system, error conditions are returned; error conditions are not returned for tasks to be started on a remote system. The NOCHECK option allows CICS to improve performance when the START command must 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.

Starting tasks without terminals

If the task to be started is not associated with a terminal, each START command starts a separate task, regardless of whether data is passed to the started task. The following examples show how to start a specified task, not associated with a terminal, in one hour:

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 the terminal is available.

The following examples show how to request initiation of a task associated with a terminal. Because no request identifier is specified in these examples, CICS assigns one and returns it to the application program in the EIBREQID field of the EXEC interface block.

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 by using 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.

Running of the first START command ultimately causes the new task to be started and allows it to retrieve the data specified on the command. The new task is also able to retrieve data specified on subsequent START commands that expire before the new task is ended. If the transaction has been defined as restartable (by defining the transaction as using the RDO option RESTART(YES)) and such data has not been retrieved before the new task is ended, another new task is started and can retrieve the outstanding data.

If the transaction abends and has not been defined as restartable, no new task is initiated and the data is discarded.

The following examples show how to start a task associated with a terminal and to 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)
⋮

When you use the C language, use the AFTER/AT HOURS, MINUTES, and SECONDS options because C does not provide a packed decimal data type. You can use INTERVAL or TIME, but if the value specified is not an integer constant, the application is responsible for ensuring that the value passed to CICS is in packed decimal format.

Routed transactions started by START commands

Some transactions started by a subset of START commands can be dynamically routed to a remote region. For general information about dynamic transaction routing, and specific information about which transactions started by START commands are eligible for dynamic routing, see Routing transactions invoked by START commands.

For a deferred START request, if the user transaction to be started is eligible for dynamic routing, an interval control element (ICE) is created and kept in the requesting region with a transaction ID of CDFS. When the ICE expires, CDFS will run and start the user transaction. The request will be routed based on the state of the transaction definition and the sysplex at that moment. Ensure that security for CDFS is correctly configured.

When security is active, the user ID associated with the transaction in the remote region is set according to the value specified in the ATTACHSEC parameter of the connection definition in the remote region. For more information about security checking done in the AOR, follow the link below based on the communication method in use:

Note: You cannot use identity propagation with a START command that is shipped to a remote region across a LU61 or LU62 connection. For this type of connection, the ICRX will not be shipped and the identity information is lost. Identity propagation is also not available for delayed dynamically routed START commands.

START failures without exception conditions

In the following circumstances, a START command runs without error, but the started task never takes place:

When the transaction or its initial program is unavailable at the time CICS attempts to create the task.
When the START specifies a terminal and an expiration time, and the terminal is not defined (and cannot be located by the XICTENF or XALTENF exits) at expiration time.
When the START specifies a terminal that is not defined (and cannot be located by the XICTENF or XALTENF exits) at the time CICS attempts to create the task.
For a deferred START, when the security check for system transaction CDFS fails.

These exposures result from the delay between the running of the START command and the time of task creation. Even when the START is immediate, CICS can delay creating the task, either because the required terminal is not free or because of other system constraints.

You can use INQUIRE commands to ensure that the transaction and program are enabled at the time of the START command, but either might become unavailable before task creation.

You get a TERMIDERR condition if the requested terminal does not exist at the time of the START, but if it is deleted later, as occurs if the user logs off, your START request is discarded with the terminal definition.

Application context propagation

Application context propagation is a process that passes application context data from a task that issues a START command to a task that runs the started transaction. The data is used for monitoring and measuring application resource usage. Both the initial and current application contexts are passed between applications. Application context data is not propagated with the following START commands:

A local EXEC CICS START command generated from a transient data (TD) trigger.
A local asynchronous EXEC CICS START command received from an event processing (EP) adapter.
An EXEC CICS START command that specifies a TERMID or a USERID parameter value.

For more information, see Application context.

Options

AFTER

Specifies the interval of time that is to elapse before the new task is started.

Enter the time under AFTER and AT in two ways:

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

AT

Specifies the time at which the new task is to be started. For the ways to enter the time, see the AFTER option.

FMH

Specifies that the user data to be passed to the started task contains function management headers. FMH is not valid for LUTYPE2 or LUTYPE3 terminals.

FROM(data-area)

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

HOURS(data-value)

Specifies a fullword binary value in the range 0 - 99. HOURS is a suboption of the AFTER and AT options. For its use and meaning, see the AFTER option.

INTERVAL(hhmmss)

Specifies the expiration time as an interval of time that is to elapse from the time at which the START command is issued. The mm and ss are each in the range 0 - 59. The time specified is added to the current clock time by CICS when the command is run, to calculate the expiration time.

LENGTH(data-value)

Specifies a halfword binary data value that is the length of the data to be stored for the new task. See LENGTH options in CICS commands for guidance on limits when setting the LENGTH option.

MINUTES(data-value)

Specifies as a fullword binary value the number of minutes for use 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 5999 otherwise. MINUTES is a suboption of the AFTER and AT options. For its use and meaning, see the AFTER option.

NOCHECK

Specifies that, for a remote system, CICS improves performance of the START command 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 started until the starting task has taken a sync point. If the starting task abends before the sync point is taken, the request to start the new task is canceled. If the REQID option is also specified, the request identifier must be a name 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 sync point. For more information about the PROTECT option with remote transactions, see Improving performance of intersystem START requests.

QUEUE(name)

Specifies a name (1 - 8 characters) that is passed to the started task. If this name represents a temporary storage queue, the queue must be local to the started task. The contents of the queue are not passed.

If you are also specifying REQID, make sure that the name of the REQID and the name of the QUEUE are not the same.

REQID(name)

Specifies a name (1 - 8 characters), which must be unique, to identify a command. You can use this option when another task is to be provided with the capability of canceling an unexpired command.

If you omit this option, CICS generates a unique request identifier in the EIBREQID field of the EXEC interface block, unless you specify the NOCHECK option, in which case field EIBREQID is set to nulls and cannot be used later to cancel the START command.

If you include any of the data options (FROM, RTERMID, RTRANSID, or QUEUE), the data is stored in a TS queue by using the REQID name specified (or CICS generated) as the identifier. The queue record thus identified must be local to the CICS system where the START command is processed. The START command is processed on the system identified by the SYSID option or, if the SYSID option is omitted, on the system associated with the TRANSID option.

RTERMID(name)

Specifies a value (1 - 4 characters), for example a terminal name, that can be retrieved when the transaction, specified in the TRANSID option in the START command, is started.

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

RTRANSID(name)

Specifies a value (1 - 4 characters), for example a transaction name, that can be retrieved when the transaction, specified in the TRANSID option in the START command, is started.

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

SECONDS(data-value)

Specifies a fullword binary value in the range 0 - 59, when HOURS or MINUTES are also specified, or 0 - 359999 when SECONDS is the only option specified. SECONDS is a suboption of the AFTER and AT options. For its use and meaning, see the AFTER option.

SYSID(systemname)

Specifies the name of the system to which the request is directed.

TERMID(name)

Specifies the symbolic identifier (1 - 4 alphanumeric characters) of the principal facility associated with a transaction to be started as a result of a START command. This principal facility can be either a terminal (the usual case) or an APPC session. Where an APPC session is specified, the connection (or modeset) name is used instead of a terminal identifier. This option is required when the transaction to be started must communicate with a terminal; it should be omitted otherwise.

Define the terminal identifier as either a local or a remote terminal on the system in which the START command is run when the start of the transaction takes effect.

The TERMID option is used in previous hop data that is collected. For more information about using the TERMID option with previous hop data, see Previous hop data characteristics.

Do not use the TERMID option if you are using identity propagation.

TIME(hhmmss)

Specifies the time when a new task is started.

When using the C language, use the AFTER/AT HOURS, MINUTES, and SECONDS options because C does not provide a packed decimal data type. You can use TIME, but if the value specified is not an integer constant, the application is responsible for ensuring that the value passed to CICS is in packed decimal format.

TRANSID(name)

Specifies the symbolic identifier (1 - 4 characters) of the transaction to be run by a task started as the result of a START command.

If you specify SYSID and name a remote system, the transaction is assumed to be on that system whether the transaction is defined as remote. Otherwise, the transaction resource definition is used to find out whether the transaction is on a local or a remote system.

The TRANSID option is used in previous hop data that is collected. For more information, see Previous hop data characteristics.

USERID(data-value)

Specifies the user ID under whose authority the started transaction is to run, if the started transaction is not associated with a terminal (that is, when TERMID is not specified). This user ID is referred to as userid1.

If you omit both TERMID and USERID, CICS uses instead the user ID under which the transaction that issues the START command is running. This user ID is referred to as userid2.

By using either userid1 or userid2, CICS ensures that a started transaction always runs under a valid user ID, which must be authorized to all the resources referenced by the started transaction.

CICS performs a surrogate security check against userid2 to verify that this user is authorized to userid1. If userid2 is not authorized, CICS returns a NOTAUTH condition.

If you are using identity propagation, and your task has a distributed user ID associated with its security context, this information is not propagated to tasks that are started with the USERID option.

Conditions

16 INVREQ

RESP2 values:

4: The value specified in HOURS, for AFTER or AT options, or the hh value specified for INTERVAL, is out of range.
5: The value specified in MINUTES, for AFTER or AT options, or the mm value specified for INTERVAL, is out of range.
6: The value specified in SECONDS, for AFTER or AT options, or the ss value specified for INTERVAL, is out of range.
17: The transaction that has been started by the START operation is not shutdown-enabled, and the CICS region is in the process of shutting down.
18: A USERID is specified and the CICS external security manager interface is not initialized.
200: The START command was issued by a distributed program link (DPL) server program and used the TERMID option, the value of which matched the ID of the intersystem session. Where TERMID is equal to EIBTRMID (that is, where the issuing task's principal facility is a session rather than a terminal), START TERMID is not in the permitted subset of commands available to DPL server programs.
400: The START command has been rejected because the threshold for an AID system rule has been exceeded.

INVREQ also occurs (RESP2 not set) in any of the following situations:

The START command is not valid for processing by CICS.
Values specified in the INTERVAL option are out of range.

Default action: end the task abnormally.

17 IOERR

Occurs in any of the following situations:

An input/output error occurred during a START operation.
A START operation attempts to write to a temporary storage queue when the DFHTEMP data set is full.
A START operation uses a REQID name that exists. This condition occurs only when the FROM option is also used.

Default action: end the task abnormally.

54 ISCINVREQ

Occurs when the remote system indicates a failure that does not correspond to a known condition.

Default action: end the task abnormally.

22 LENGERR

Occurs if LENGTH is not greater than zero.

Default action: end the task abnormally.

70 NOTAUTH

RESP2 values:

7: A resource security check fails on TRANSID (name).
9: A surrogate user security check fails on USERID (name).
The security access capabilities of the transaction that issued the command do not allow the command to be performed with the value specified in the USERID option. The security access capabilities of the transaction have been established by the external security manager according to user security, and whether link security or the execution diagnostic facility (EDF) have been in use.

Default action: end the task abnormally.

121 RESUNAVAIL

RESP2 values:

121

A resource required by the transaction to be started is unavailable on the target region. The RESUNAVAIL condition applies only to dynamically-routed, non-terminal-related EXEC CICS START requests.

RESUNAVAIL is returned on the EXEC CICS START command run by the mirror in the target region, if an XICERES global user exit program indicates that a required resource is unavailable on the target region. It is not returned to the application.

Default action: reinvoke the distributed routing program for route selection failure.

53 SYSIDERR

Occurs when the SYSID option specifies a name that is neither the local system nor a remote system (made known to CICS by defining a CONNECTION). SYSIDERR also occurs when the link to the remote system is known but unavailable.

The following error is indicated by a RESP2 value:

1: The dynamic routing program rejected the START request.

Default action: end the task abnormally.

11 TERMIDERR

Occurs if the terminal identifier in a START command is not defined to CICS. This condition can be produced if you specify the name of a connection that is not an ISC or MRO connection.

Default action: end the task abnormally.

28 TRANSIDERR

Occurs if the transaction identifier specified in a START command is not defined to CICS.

This condition can also occur if the transaction is defined as DYNAMIC(YES) and the value specified in the REMOTESYSTEM attribute of the transaction definition is not the local SYSID. A TRANSIDERR occurs when an attempt to dynamically route the start request returns the local SYSID, which conflicts with the REMOTESYSTEM value of the definition.

Default action: end the task abnormally.

69 USERIDERR

RESP2 values:

8: The specified USERID is not known to the external security manager.
10: The external security manager is in a state such that CICS cannot determine whether a specified USERID is valid.
19: The specified USERID is revoked.

Default action: end the task abnormally.

Note: RESP2 values are not returned to the client for conditions occurring in a DPL server program.