Start of change

START CHANNEL

Start a task, passing it a channel.

Start of change
Read syntax diagramSkip visual syntax diagram
START CHANNEL

>>-START--TRANSID(name)--CHANNEL(name)-------------------------->

>--+--------------------+--+-------------------+---------------><
   +-TERMID(name)-------+  '-SYSID(systemname)-'   
   '-USERID(data-value)-'                          

Conditions: Start of changeCHANNELERR, End of changeINVREQ, ISCINVREQ, NOTAUTH, RESUNAVAIL, SYSIDERR, TERMIDERR, TRANSIDERR, USERIDERR

End of change

Description

START CHANNEL starts a task, on a local or remote system, passing it a channel.

Typically, the starting task uses the channel to pass data to the started task (although in some circumstances the channel may be empty—see the description of the CHANNEL option). The starting task may also specify a terminal to be used by the started task as its principal facility.

The started task can, for example:
  1. Use an ASSIGN CHANNEL command to discover the name of the channel it's been passed
  2. Use STARTBROWSE CONTAINER CHANNEL and GETNEXT CONTAINER commands to browse the containers in the channel
  3. Use GET CONTAINER CHANNEL commands to access the data in the containers
Some constraints have to be satisfied before the transaction to be executed can be started, as follows:
  • If the TERMID option is specified, the named terminal must exist and be available. If the named terminal does not exist, the START is discarded.
  • START CHANNEL does not support IMS—that is, you cannot use START CHANNEL to start a transaction on a remote IMS system.

Each START CHANNEL command results in a separate task being started.

Dynamically 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 the CICS® Intercommunication Guide.

START failures without exception conditions

There are some circumstances in which a START command is executed without error, but the started task never takes place:
  • When the transaction or its initial program is disabled at the time CICS attempts to create the task.
  • 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.
  • You get a TERMIDERR condition if the requested terminal does not exist at the time of the START. However, if the terminal becomes unavailable subsequently, as occurs if the user logs off, your START request is discarded and no TERMIDERR occurs.

These exposures result from the delay between the execution of the START and the time of task creation. Even on a START CHANNEL request, when the START is always 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.

Options

Start of changeCHANNEL(name)End of change
Start of changespecifies the name (1–16 characters) of a channel that is to be made available to the started task. The acceptable characters are A-Z a-z 0-9 $ @ # / % & ? ! : | " = ¬ , ; < > . - and _. Leading and embedded blank characters are not permitted. If the name supplied is less than 16 characters, it is padded with trailing blanks up to 16 characters.

Channel names are always in EBCDIC. The allowable set of characters for channel names, listed above, includes some characters that do not have the same representation in all EBCDIC code pages. We therefore recommend that, if channels are to be shipped between regions, the characters used in naming them should be restricted to A-Z Start of changea-zEnd of change 0-9 & : = , ; < > . - and _.

The program that issues the START command may:
  • Have created the channel by means of one or more PUT CONTAINER CHANNEL commands
  • Specify its current channel, by name
  • Name a non-existent channel, in which case a new, empty, channel is created

The started task is given a copy of the channel's containers (and the data they contain). The copy is made when the START command is issued.

End of change
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.

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.

Conditions

Start of changeCHANNELERREnd of change
Start of changeRESP2 values:
1
The channel specified on the CHANNEL option contains an illegal character or combination of characters.
End of change
INVREQ
RESP2 values:
9
The options specified on the command are incompatible.
17
The STARTed transaction 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.

Also occurs (RESP2 not set) if the START command is not valid for processing by CICS.

Default action: terminate the task abnormally.

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

Default action: terminate the task abnormally.

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: terminate the task abnormally.

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 executed 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.

SYSIDERR
occurs in all of the following cases:
  • The SYSID option specifies a name that is neither the local system nor a remote system (made known to CICS by defining a CONNECTION).
  • The link to the remote system is known but unavailable.

In all the above cases, the nature of the error is indicated by the second byte of the EIBRCODE.

The following errors are indicated by RESP2 values:
Start of change1End of change
Start of changeThe dynamic routing program rejected the START request.End of change
Start of change2End of change
Start of changeThe CHANNEL option was used and the START request was shipped or routed to a remote system which doesn't support it. (MRO connections only)

Default action: terminate the task abnormally.

End of change
20
The CHANNEL option is specified and the START request is to be shipped over an LUTYPE61 connection. START CHANNEL requests cannot be shipped over LUTYPE61 connections.

The SYSIDERR condition may not be raised if the user exit XISLCLQ is enabled (see the CICS Customization Guide for programming information).

TERMIDERR
occurs if the terminal identifier in a START command cannot be found in the terminal control table.

Default action: terminate the task abnormally.

TRANSIDERR
occurs if the transaction identifier specified in a START command cannot be found in the program control table.

Default action: terminate the task abnormally.

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.

Default action: terminate the task abnormally.

End of change