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:
- 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 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.)
- 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.