Default action: Terminate the task abnormally.
NOTOPEN
RESP2 values:
8
The spool file indicated by the TOKEN option is not open when the
SPOOLWRITE is issued.
Default action: Terminate the task abnormally.
SPOLERR
occurs if an I/O error has been detected by the OS/400 data management modules, preventing successful completion of the request.
Default action: Terminate the task abnormally.
START
Start task at a specified time.
INTERVAL
START TRANSID (
name
)
(
0
)
INTERVAL
TIME (
(
hhmmss hhmmss
)
) REQID (
name
)
AFTER
AT
HOURS
MINUTES
(
SECONDS
(
data-value data-value
)
(
data-value
)
)
HOURS
MINUTES
(
SECONDS
(
data-value data-value
)
(
data-value
)
)
FROM (
data-area
) LENGTH (
data-value
) TERMID (
name
)
SYSID (
systemname
) RTRANSID (
name
) RTERMID (
name
)
QUEUE (
name
) NOCHECK PROTECT
Conditions:
INVREQ, IOERR, ISCINVREQ, LENGERR, NOTAUTH, SYSIDERR, TERMIDERR, TRANSIDERR
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.
The starting task may pass data to the started task. This data must not contain any pointers. The starting task may also specify a terminal to be used by the started task as its principal facility.
The default is INTERVAL(0), but for ILE C the default is AFTER HOURS(0)
MINUTES(0) SECONDS(0).
Chapter 32. Application programming commands - reference
445
Note that
CEDF
is an exception to the START command and is not valid as a
TRANSID name. You should therefore not attempt to start CEDF in this way.
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 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 may also pass the name of a queue to be accessed by the second task. If you choose to 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 you specified in REQID, if used.
One or more constraints have to be satisfied before the transaction to be executed can be started, as follows: v
The specified interval must have elapsed or the specified expiration time must
have been reached. (For more information, see Chapter 18, “Interval control,” on page 193.) The INTERVAL or AFTER options should be specified when a
transaction is to be executed on a remote system; this avoids complications arising when the local and remote systems are in different time zones. v
If the TERMID option is specified, the named terminal must exist and be available. If the named terminal does not exist when the time interval expires, the START is discarded. v
If the PROTECT option is specified, the starting task must have taken a successful syncpoint. This option, coupled to extensions to system tables, reduces the exposure to lost or duplicated data caused by failure of a starting task. v
If the transaction to be executed is on a remote system, the format of the data must be declared to be the same as that at the local system. the RDO options
DATASTREAM and RECORDFORMAT, or DATASTR and RECFM on the terminal control table TYPE=SYSTEM.
Execution of a START command naming a transaction in the local system cancels any outstanding POST commands executed by the starting task.
START commands are queued by means of the transaction definition created using the ADDCICSPCT CL command, as described in the
CICS for iSeries Administration and Operations Guide
.
If data is to be passed by interval control (using the FROM option), it is queued on a temporary storage queue. The REQID option allows you to specify the name of the temporary storage queue to be used. This identifier may be recoverable (in temporary storage terms) or nonrecoverable.
If you also specify the PROTECT option, the temporary storage queue identified by the REQID option should be defined as recoverable. If you do not specify the
PROTECT option, the temporary storage queue should not be defined as recoverable. Unpredictable results can occur if these rules are not followed.
The NOCHECK option specifies that no response (to execution of the START command) is expected by the starting transaction. For START commands naming 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 has to be
446
CICS for iSeries Application Programming Guide V5
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.
When a START command is issued against an existing but idle CICS/400 shell, if the terminal is a 5250 the keyboard locks until the transaction is complete.
However, if the terminal is a 3270, the keyboard does not lock. You should not enter anything until the transaction has finished running.
Examples
Starting tasks without terminals
If the task to be started is not associated with a terminal, each START command results in a separate task being started. This happens regardless of whether or not 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)
EXEC CICS START
TRANSID(’TRNL’)
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. When this happens the error message AEG0815 will appear on the job log.
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)
EXEC CICS START
TRANSID(’TRN1’)
AT HOURS(18) MINUTES(50)
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.
Chapter 32. Application programming commands - reference
447
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 specified on the command. The new task is also able to retrieve data specified on subsequently executed START commands that expire before the new task is terminated. If such data has not been retrieved before the new task is terminated, another new task is started and is able to retrieve the outstanding data. If this second new task fails to retrieve the outstanding data, a third task is started, and so on, up to a maximum of 5 times, after which the data is lost.
The following examples show how to start a task associated with a terminal and pass data to it:
EXEC CICS START
TRANSID(’TRN2’)
TIME(173000)
TERMID(’STA3’)
REQID(DATAREC)
FROM(DATAFLD)
EXEC CICS START
TRANSID(’TRN2’)
AT HOURS(17) MINUTES(30)
TERMID(’STA3’)
REQID(DATAREC)
FROM(DATAFLD)
ILE C supports the packed-decimal argument type and, consequently, the use if the
INTERVAL and TIME options. It is recommended, however, that you use the
AFTER and AT options for portability of applications between CICS platforms.
START failures with out exception conditions
There are some circumstances in which a START command is executed without error, but the started task never takes place: v
When the transaction or its initial program is disabled at the time CICS attempts to create the task. v
When the START specifies a terminal and an expiration time, and the terminal is not defined at expiration time. v
When the START specifies a terminal that is not defined at the time CICS attempts to create the task.
These exposures result from the delay between the execution of the START and the time of task creation. Even when the START is immediate, CICS may 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 may become disabled before task creation.
448
CICS for iSeries Application Programming Guide V5
You get a TERMIDERR condition if the requested terminal does not exist at the time of the START, but if it is deleted subsequently, as occurs if the user logs off, your START request is discarded with the terminal definition.
Refer to Chapter 18, “Interval control,” on page 193 for further information about
Interval Control.
Options
AFTER
specifies the interval of time that is to elapse before the new task is started.
There are two ways to enter the time under AFTER and AT.
1. A combination of at least two of HOURS(0–99), MINUTES(0–59), and
SECONDS(0–59). HOURS(1) SECONDS(3) would mean one hour and three seconds (the minutes default to zero).
2.
As one of HOURS(0–99), MINUTES(0–5999), or SECONDS(0–359 999).
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.
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. This 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 specified interval is added to the current clock time by CICS to calculate the expiration time. See
Chapter 18, “Interval control,” on page 193 for an explanation of how
expiration times are used within interval control.
INTERVAL(0) is the default. The maximum permitted INTERVAL value is
995959.
For compatibility between CICS platforms, it is recommended that the
INTERVAL option is not used in ILE C programs. You should use the AFTER option instead.
LENGTH(
data-value
)
specifies a halfword binary data value that is the length of the data to be stored for the new task.
MINUTES(
data-value
)
specifies as a fullword 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 5999 otherwise. This 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 should improve performance of the
START command by providing less error checking and slightly less function.
Chapter 32. Application programming commands - reference
449
For more information, see the section about improving the performance of intersystem START requests in the
CICS for iSeries Intercommunication
book.
PROTECT
specifies that the new task is not started 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. The PROTECT option also causes the start request entry to be held on the TS/TD recoverable file. If the REQID option is also specified, the request identifier should 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 syncpoint. For more information about the PROTECT option with remote transactions, see the
CICS for iSeries Intercommunication
book name defined as recoverable to temporary storage.
QUEUE(
name
)
specifies the name (1–8 characters) of a temporary storage queue that may be used by the started transaction.
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. This option can be used when another task is to be provided with the capability of canceling an unexpired command.
If this option is omitted, CICS generates a unique request identifier in the
EIBREQID field of the EXEC interface block, unless the NOCHECK option is specified, in which case field EIBREQID is set to nulls and cannot be used subsequently 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 using the REQID name specified (or
CICS generated) as the identifier. The temporary storage queue must be a local queue on the CICS system where the command is processed, and if the start is protected (using the PROTECT option), it should be defined as recoverable in the TST on that system. 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. If the same REQID name is specified on multiple START commands (that is, it is not unique) there may be unexpected consequences such as: v
Multiple commands are established which can only be canceled in ‘time expiry’ order, each requiring a separate CANCEL command. v
The data (if any) from each START command is added to the same temporary storage queue in the order that the START commands are issued rather than in ‘time expiry’ order, possibly resulting in a mismatch between the START command and its data.
RTERMID(
name
)
specifies a value (1–4 characters), for example a terminal name, that may be retrieved when the transaction, specified in the TRANSID option in the START command, is started.
When retrieved, the value may be used in the TERMID option of a subsequent
START command.
450
CICS for iSeries Application Programming Guide V5
RTRANSID(
name
)
specifies a value (1–4 characters), for example a transaction name, that may be retrieved when the transaction, specified in the TRANSID option in the START command, is started.
When retrieved, the value may 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–359 999 when SECONDS is the only option specified. This 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.
The terminal identifier must be defined as either a local or a remote terminal on the system in which the START command is executed,
when the start of the transaction takes effect.
TIME(
hhmmss
)
specifies the time when a new task should be started.
For compatibility between CICS platforms, it is recommended that the
INTERVAL option is not used in ILE C programs. You should use the AFTER option instead.
TRANSID(
name
)
specifies the symbolic identifier of the transaction to be executed by a task started as the result of a START command. The name can be up to 4 characters long and must have been defined in the program control table (PCT) unless the
SYSID option specifies a remote system.
If a nonlocal SYSID is specified, the transaction is assumed to be on a remote system irrespective of whether the name is defined in the local PCT. Otherwise, the PCT entry is used to determine whether the transaction is on a local or a remote system.
Exception Conditions
INVREQ
RESP2 values:
4
5
6
Hours out of range.
Minutes out of range.
Seconds out of range.
also occurs (RESP2 not set) in any of the following situations: v
The START command is not valid for processing by CICS.
Chapter 32. Application programming commands - reference
451
