CICS_EpiAddTerminal

The CICS_EpiAddTerminal function installs a new terminal resource, or reserves an existing terminal resource, for the application's use.

CICS_EpiAddTerminal

NameSpace
System
NetName
DevType
NotifyFn
Details
TermIndex

Purpose

It provides a terminal index, which should be used to identify the terminal resource on all further EPI calls. It also provides the information defined in the CICS_EpiDetails_t data structure.

There is a limit on the number of terminals you can add with this operation: The maximum varies according to the resources available on the client system.

Note: The CICS_EpiAddTerminal function adds terminal resources whose sign-on capability is dependant upon the server in which the terminal resource is installed, for example, they would be sign-on incapable on CICS® Transaction Server for z/OS® servers.

Parameters

NameSpace
A pointer reserved for future use. Ensure that this is a null pointer.
System
A pointer to a null-terminated string that specifies the name of the server in which the terminal resource is to be installed or reserved. If the name is shorter than CICS_EPI_SYSTEM_MAX characters, it must be padded with nulls to a length of CICS_EPI_SYSTEM_MAX + 1.

If the string is all nulls, the default server is selected by the EPI. To determine the name of the server chosen, use CICS_EpiInquireSystem.

The EPI uses this parameter only for input.

NetName
A pointer to a null-terminated string that specifies the name of the terminal resource to be installed or reserved, or null. The interpretation of this name is server-dependent.

If a string is supplied that is shorter than CICS_EPI_NETNAME_MAX, it must be padded with nulls to a length of CICS_EPI_NETNAME_MAX + 1.

The string is transmitted to the server without conversion to uppercase.

The characters used are translated from the client’s code page to an EBCDIC code page before transmission. If the server uses an ASCII code page, they will be retranslated. The only characters guaranteed to be invariant under these translations are the uppercase characters A to Z, and the numeric characters 0 to 9. Some EBCDIC servers (Katakana and Hebrew character set A) do not use the standard representations of the lowercase alphabetic characters; use them with care when communicating with such servers.

The use of NetName is as follows:
  1. If a name is supplied using the NetName, and it matches the name of an existing terminal resource in the server, the server attempts to reserve that terminal resource.
  2. If a name is supplied, but it does not match the name of an existing terminal resource in the server, the server installs a terminal resource using the model terminal definition specified by the DevType parameter described below, and gives it the input name. (If DevType is a null pointer, CICS_EPI_ERR_TERMID_INVALID is returned for CICS_EPI_VERSION_200 or later, otherwise CICS_EPI_ERR_FAILED is returned.)
  3. If NetName is a null pointer, a terminal resource is installed using the model terminal definition specified in DevType. If DevType is a null pointer, the selected terminal type is not predictable, so you are advised to use DevType to ensure consistent results. The name of the terminal resource is returned in the NetName field of the CICS_EpiDetails_t structure.

The EPI uses this parameter only for input.

DevType
A pointer to a null-terminated string that is used in the server to select a model terminal definition from which a terminal resource definition is generated, or a null pointer.

If a string is supplied that is shorter than CICS_EPI_DEVTYPE_MAX characters, it should be padded with nulls to a length of CICS_EPI_DEVTYPE_MAX + 1.

The string is transmitted to the server without conversion to uppercase.

The characters used are translated from the client’s code page to an EBCDIC code page before transmission. If the server uses an ASCII code page, they will be retranslated. The only characters guaranteed to be invariant under these translations are the uppercase characters A to Z, and the numeric characters 0 to 9. Some EBCDIC servers (Katakana and Hebrew character set A) do not use the standard representations of the lowercase alphabetic characters; use them with care when communicating with such servers.

The EPI uses this parameter only for input.

NotifyFn
A pointer to a callback routine that is called whenever an event occurs for the terminal resource, such as the arrival of an ATI request. If a callback routine is not required, this parameter should be set to null. Start of changeNot supported in COBOL applications.End of change

The EPI uses this parameter only for input.

Details
A pointer to the CICS_EpiDetails_t structure that on return contains various details about the terminal resource that was installed or reserved.

The EPI uses the fields in this structure only for output.

TermIndex
A pointer to a terminal index for the terminal resource just installed or reserved. The returned terminal index must be used as input to all further EPI function calls to identify the terminal resource to which the function is directed. The terminal index supplied is the first available integer starting from 0.

The EPI uses this parameter only for output.

Return codes

CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_SYSTEM
The specified server is not known to the client.
CICS_EPI_ERR_SECURITY
The server rejected the attempt for security reasons.
CICS_EPI_ERR_NULL_PARM
TermIndex was a null pointer.
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_TERMID_INVALID
The function failed because an invalid TermId was supplied.
CICS_EPI_ERR_MODELID_INVALID
The function failed because an invalid Model terminal definition was supplied.
CICS_EPI_ERR_NOT_3270_DEVICE
The function failed because the device type supplied was not for a 3270 device.
CICS_EPI_ERR_ALREADY_INSTALLED
The function failed because the terminal was already installed.
CICS_EPI_ERR_SERVER_BUSY
The function failed because the server was busy.
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
The MAXREQUESTS limit has been exceeded.
CICS_EPI_ERR_MAX_SYSTEMS
An attempt was made to start connections to more servers than your configuration allows.
CICS_EPI_NORMAL
The function completed successfully.