CICS_EpiStartTran

Purpose

CICS_EpiStartTran

TermIndex
TransId
Data
Size

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, it should be padded 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, in CICS Transaction Gateway: Programming Guide.

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 install.
CICS_EPI_ERR_MAX_SESSIONS
There were not enough communication resources to satisfy this request.
CICS_EPI_NORMAL
The function completed successfully.