Start a task, passing it a channel.
START CHANNEL >>-START--TRANSID(name)--CHANNEL(name)--------------------------> >--+--------------------+--+-------------------+--------------->< +-TERMID(name)-------+ '-SYSID(systemname)-' '-USERID(data-value)-'
Conditions: CHANNELERR, INVREQ, ISCINVREQ, NOTAUTH, RESUNAVAIL, SYSIDERR, TERMIDERR, TRANSIDERR, USERIDERR
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 can be empty; see the description of the CHANNEL option). The starting task can also specify a terminal to be used by the started task as its principal facility.
- Use an ASSIGN CHANNEL command to discover the name of the channel that has been passed to it.
- Use STARTBROWSE CONTAINER CHANNEL and GETNEXT CONTAINER commands to browse the containers in the channel.
Use GET CONTAINER CHANNEL or GET64 CONTAINER commands to access the data in the containers.
- If you specify the TERMID option, 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.
START with TERMID specified does not propagate the origin data record (ODR), so tasks are always started at a new point of origin.
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 Routing transactions invoked by START commands.
START failures without exception conditions
- When the transaction or its initial program is unavailable 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 later, as occurs if the user logs off, your START request is discarded, and no TERMIDERR occurs.
These exposures result from the delay between running the START command and the time of task creation. Even on a START CHANNEL request, when the START is always 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 can become unavailable before task creation.
Options
- CHANNEL(name)
- Specifies 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 $ @ # ./-_ % & ? ! : | " = ¬ , ; < >. 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 set of allowed characters for channel names, as listed earlier, includes some characters that do not have the same representation in all EBCDIC code pages. Therefore, if channels are to be shipped between regions, it is advisable to restrict the characters used to name them to A-Z a-z 0-9 & : = , ; < > . - and _.
The program that issues the START command can do one of the following: - Create the channel before issuing the START command,
by using one or more PUT CONTAINER CHANNEL or PUT64 CONTAINER commands.
- Specify its current channel, by name.
- Name a channel that does not currently exist. A new empty channel is created.
The started task is given a copy of the channel's containers (and the data that they contain). The copy is made when the START command is issued.
- 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.
You must define the terminal identifier as either a local or a remote terminal on the system in which the START command is run.
The TERMID option is used in previous hop data that is collected. For more information, see Previous hop data characteristics.
Do not use the TERMID option if you are
using identity propagation. - 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 the SYSID, and name a remote system, the transaction is assumed to be on that system irrespective of whether the transaction is defined as remote. Otherwise, the transaction 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. The surrogate check is not done here if USERID is omitted.
Do not use the USERID option if you are using identity propagation.
Conditions
- 122 CHANNELERR
- RESP2 values:
- 1
- The channel specified on the CHANNEL option contains an incorrect character or combination of characters.
- 16 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.
- 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.
INVREQ also occurs (RESP2 not set) if the START command is not valid for processing by CICS.
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.
- 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 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 previous cases, the nature of the error is indicated by the second byte of the EIBRCODE.
The following errors are indicated by RESP2 values:- 1
- The dynamic routing program rejected the START request.
- 2
- The CHANNEL option was used and the START request was shipped
or routed to a remote system which does not support it. (MRO connections
only).
Default action: end the task abnormally.
- 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.
- 11 TERMIDERR
- The terminal identifier in a START command is not defined to CICS.
Default action: end the task abnormally.
- 28 TRANSIDERR
- The transaction identifier specified in a START command is not
defined to CICS.
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.
Default action: end the task abnormally.
