The CICS_EpiStartTran function
starts a new transaction from a terminal resource, or continues a
pseudoconversation.
- Starting a new transaction—do this after CICS_EpiAddTerminal, or after a CICS_EPI_EVENT_END_TRAN
event indicated
that the previous transaction did not specify a
transaction to process the next input from the terminal resource.
- Continuing a pseudoconversation—do this after a CICS_EPI_EVENT_END_TRAN
event that
indicated that the previous transaction specified did specify
a transaction to process the next input from the terminal resource.
If the call is successful, no further start requests
can be issued for this terminal resource until the transaction ends;
this is indicated by the CICS_EPI_EVENT_END_TRAN event.
Parameters
- TermIndex
- The
terminal index of the terminal resource that is to run the transaction.
The EPI uses this parameter only for input.
- TransId
- A
pointer to a string specifying the transaction to be run, or the null
pointer. If a new transaction is being started, and this input is
the null pointer, the name of the transaction is extracted from the
data stream supplied in the Data parameter. If
a pseudoconversation is being continued, and the pointer is not null,
the string must be the name of the transaction returned in the preceding
CICS_EPI_EVENT_END_TRAN event for
this terminal resource. If the pointer is not null, and the string
is shorter than CICS_EPI_TRANSID_MAX characters,
pad it with spaces to this length.
The EPI uses this parameter
only for input.
- Data
- A
pointer to the 3270 data stream to be associated with the transaction.
This parameter must not be a null pointer, because the data stream
must contain at least an AID byte.
If a new transaction is being
started, and the TransId parameter is the null
pointer, the data stream must be at least 4 bytes long, must contain
the name of the transaction to be started, and might contain data
to be supplied to the transaction on its first EXEC CICS RECEIVE
command.
If a new
transaction is being started, and the TransId parameter
is not the null pointer, the data stream might be only one byte (an
AID byte), or 3 bytes (an AID byte and a cursor address), or longer
than 3 bytes (an AID byte, a cursor address, and data and SBA commands).
In the last case, the data is supplied to the transaction program
on the first EXEC CICS RECEIVE
command.
If a pseudoconversation
is being continued, the data stream might be only one byte (an AID
byte), or 3 bytes (an AID byte and a cursor address), or longer than
3 bytes (an AID byte, a cursor address, and data and SBA commands).
In the last case the data is supplied to the transaction program on
the first EXEC CICS RECEIVE
command.
The details
of the format of 3270 data streams for CICS® are
described in 3270 data streams for the EPI.
The
length of the 3270 data stream must not exceed the value that was
returned in MaxData in CICS_EpiDetails_t when
the terminal resource was installed with CICS_EpiAddTerminal.
The
EPI uses this parameter only for input.
- Size
- The
size in bytes of the initial data to be passed to the transaction.
The EPI uses this parameter only for input.
Note: The application might expect a terminal resource
to be free to start a transaction and yet get an unexpected return
code of CICS_EPI_ERR_ATI_ACTIVE from
a call to CICS_EpiStartTran. If this happens, it
means that the EPI has started an ATI request against the terminal
resource and issued the corresponding CICS_EPI_EVENT_START_ATI event, but the application has
not yet retrieved the event by issuing a CICS_EpiGetEvent call.
Return codes
- CICS_EPI_ERR_ATI_ACTIVE
- An ATI transaction is active for this
terminal resource.
- CICS_EPI_ERR_BAD_INDEX
- The TermIndex value
is not a valid terminal index.
- CICS_EPI_ERR_FAILED
- The function failed for an unexpected
reason.
- CICS_EPI_ERR_NO_DATA
- No initial data was supplied.
- CICS_EPI_ERR_NOT_INIT
- CICS_EpiInitialize has
not been executed.
- CICS_EPI_ERR_TTI_ACTIVE
- A transaction started from the EPI
is already active for this terminal resource.
- CICS_EPI_ERR_IN_CALLBACK
- The function was called from a callback
routine.
- CICS_EPI_ERR_SERVER_DOWN
- The function failed because the server
was down.
- CICS_EPI_ERR_RESOURCE_SHORTAGE
- The CICS server
or CICS Transaction Gateway did
not have enough resources to complete the terminal installation.
- CICS_EPI_ERR_MAX_SESSIONS
- The maximum number of concurrent requests
handled by the Client daemon, as defined by the configuration parameter maxrequests in
the configuration file, has been reached.
- CICS_EPI_NORMAL
- The function completed successfully.