The CICS_EpiAddTerminal function installs
a new terminal resource, or reserves an existing terminal resource,
for the application.
It provides a terminal index, which is
used to identify the terminal resource on all further EPI calls. It
also provides the information defined in the CICS_EpiDetails_t data
structure.
The number of terminals that you can add with this
operation is limited; the maximum varies according to the resources
available on the client system.
The CICS_EpiAddTerminal function
adds terminal resources that have sign-on capability that depends
on the server in which the terminal resource is installed; for example,
they cannot sign on to CICS® Transaction Server for z/OS® servers.
Parameters
- NameSpace
- A pointer reserved for future use. Ensure that it 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 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 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:
- 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.
- 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,
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.)
- 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.
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 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.