CICS_EpiAddExTerminal

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

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

Some attributes, for example the character set and encoding scheme to be used for 3270 data and the sign-on capability, can be determined by the application. These attributes are specified in the CCSID and SignonCapability fields in the CICS_EpiAttributes_t structure.

Parameters

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 CICS 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 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 pad it 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 set this parameter to null. Not supported in COBOL applications.

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. For asynchronous calls set the Details parameter to NULL. If the pointer is not set to nulls, the details are added to the structure when the request to install the terminal resource has completed. For asynchronous calls this is done when the CICS_EPI_EVENT_ADD_TERM event occurs.

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.

Attributes
A pointer to the CICS_EpiAttributes_t structure that specifies attributes definable by the client application for the terminal resource that is to be installed The structure must be set to nulls before use.

Default attributes are assumed if the pointer is set to null.

The EPI uses this parameter only for input.

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 CICS Transaction Gateway.
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_RESPONSE_TIMEOUT
No response was received from the server within the specified interval.
CICS_EPI_ERR_SIGNON_NOT_POSS
The server does not allow terminal resources to be installed as sign-on capable.
CICS_EPI_ERR_SERVER_DOWN
The function failed because the server was down.
CICS_EPI_ERR_PASSWORD_INVALID
The length of the password exceeds CICS_EPI_PASSWORD_MAX.
CICS_EPI_ERR_ADDTYPE_INVALID
The value assigned to the EpiAddType field in the CICS_EpiAttributes_t structure is neither CICS_EPI_ADD_ASYNC nor CICS_EPI_ADD_SYNC.
CICS_EPI_ERR_SIGNONCAP_INVALID
The value assigned to the SignonCapability field in the CICS_EpiAttributes_t structure is neither CICS_EPI_SIGNON_CAPABLE nor CICS_EPI_SIGNON_INCAPABLE.
CICS_EPI_ERR_USERID_INVALID
The length of the user ID exceeds CICS_EPI_USERID_MAX.
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_CCSID_INVALID
The function failed because an invalid CCSID was supplied.

For details on the CCSID values for various character sets, see Supported conversions.

CICS_EPI_ERR_SERVER_BUSY
The function failed because the server was busy.
CICS_EPI_ERR_VERSION
The function is not supported for the version at which the EPI was initialized.
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_ERR_MAX_SYSTEMS
An attempt was made to start connections to more servers than your configuration allows.
CICS_EPI_NORMAL
The function completed successfully.

Reference Reference

Feedback


Timestamp icon Last updated: Tuesday, 19 November 2013


https://ut-ilnx-r4.hursley.ibm.com/tg_latest/help/topic/com.ibm.cics.tg.doc//proref/cclnam0062.html