CICS_EpiStartTran

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.