XCTL transfers control from one application program to another at the same logical level. The program from which control is transferred is released. If the program to which control is transferred is not already in main storage, it is loaded.
EXEC CICS XCTL PROGRAM(name) [ COmmarea ( ) [ Length ] ] [ INPUTMSG ( ) [ INPUTMSGLen( ) ] ] END-EXEC Example: EXEC CICS XCTL PROGRAM(‘PROG’) END-EXEC
Its shows how to request a transfer of control to an application program called PROG
Notes:
Description
XCTL transfers control from one application program to another at the same logical level. The program from which control is transferred is released. If the program to which control is transferred is not already in main storage, it is loaded.
Options
COMMAREA(data-area)
specifies a communication area to be made available to the invoked program. In this option the contents of the data-area are passed. In COBOL, you must give this data area the name DFHCOMMAREA in the receiving program.
INPUTMSG(data-area)
specifies data to be passed to the invoked program when it first issues a RECEIVE command. If the invoked program passes control to another program by a LINK command, a linked chain is created, as described under the INPUTMSG option of the LINK command. The INPUTMSG data remains available until a RECEIVE command is issued or until control returns to CICS.
INPUTMSGLEN(data-value)
LENGTH(data-value)
specifies the length (halfword binary data value) in bytes of the communication area.
PROGRAM(name)
specifies the identifier (1-8 alphanumeric characters) of the program to which control is to be passed unconditionally. The specified name must have been defined as a program to CICS, though if AUTOINSTALL is active a definition is autoinstalled.
START
START starts a task, on a local or remote system, at a specified time. EXEC CICS START TRansid ( )
[ Interval( +0000000 ) | TIme( ) | {AFter | AT } [ Hours( ) ] [Minutes( ) ] [ SEconds( ) ] ] [ FRom( ) [ Length( ) [ FMh ] ] ]
[ TErmid( ) | Userid( ) ] [ SYsid() ]
END-EXEC
Example:
EXEC CICS START TRANSID('TRNL') AFTER HOURS(1) END-EXEC
It shows how to start a specified task, not associated with a terminal, in one hour
Notes:
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. 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 C the default is AFTER HOURS(0) MINUTES(0) SECONDS(0). 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. One or more constraints have to be satisfied before the transaction to be executed can be started, as follows:
The specified interval must have elapsed or the specified expiration time must have been reached. (For more information.) 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.
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.
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.
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. This is done using the RDO options DATASTREAM and RECORDFORMAT. For CICS-CICS, these are always the default values. For CICS-IMS/VS, care should be taken to specify the correct values.
Execution of a START command naming a transaction in the local system cancels any outstanding POST commands executed by the starting task.
START commands can be queued by specifying the LOCALQ option on the RDO TRANSACTION resource definition.
Passing data by interval control: 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.
If you specify the FROM and not the REQID option, a default 'DF' prefix temporary storage queue is used. The same rules apply as above; only specify the PROTECT option if you define the 'DF' prefix temporary storage queues as recoverable.
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.
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).
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.
FMH
specifies that the user data to be passed to the started task contains function management headers. This is not valid for LUTYPE2 or LUTYPE3 terminals.
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 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 executed, 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.
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.
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. 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.
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. 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 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.
You cannot specify a REQID value that already exists for another start request that has not yet expired.
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.
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. When using the C language, you are recommended to use the AFTER/AT HOURS, MINUTES, and SECONDS options as C does not provide a packed decimal data type. You may 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 executed by a task started as the result of a START command. If SYSID is specified, and names a remote system, the transaction is assumed to be on that system irrespective of whether or not the transaction definition is defined as remote in the PCT. Otherwise the transaction definition is used to find out whether the transaction is on a local or a remote system.
USERID(data-value)
Specifies the userid 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 is referred to as userid1. If you omit both TERMID and USERID, CICS uses instead the userid under which the transaction that issues the START command is running. This is referred to as userid2.
By using either userid1 or userid2 CICS ensures that a started transaction always runs under a valid userid, 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. The surrogate check is not done here if USERID is omitted.