The communications area at INSTALL for shipped terminals
*--------------------------------------------------------------------------*
* Remote install parameter list - Shipped definition functions 7 & 8 *
*--------------------------------------------------------------------------*
INSTALL_SHIPPED_COMMAREA DSECT Install Parameter List
*
INSTALL_SHIPPED_STANDARD DS F Standard field
ORG INSTALL_SHIPPED_STANDARD
INSTALL_SHIPPED_EXIT_FUNCTION DS XL1 Install type
INSTALL_SHIPPED_TERM EQU X'F7' Install terminal
INSTALL_SHIPPED_RSE EQU X'F8' Install remote system entry
INSTALL_SHIPPED_EXIT_COMPONENT DS CL2 Component ID 'ZC'
INSTALL_SHIPPED_CLASH DS CL1 Install clash Y/N
ORG ,
INSTALL_SHIPPED_NETNAME_PTR DS A Pointer to netname
INSTALL_SHIPPED_SELECTED_PTR DS A Pointer to return fields
INSTALL_SHIPPED_TERMID_PTR DS A Pointer to incoming TERMID
INSTALL_SHIPPED_APPLID_PTR DS A Pointer to applid of TOR
INSTALL_SHIPPED_SYSID_PTR DS A Pointer to sysid
INSTALL_SHIPPED_CORRID_PTR DS A Pointer to correlation ID
INSTALL_SHIPPED_SELECTED_PARMS DSECT ,
DS CL8 Reserved
SELECTED_SHIPPED_TERMID DS CL4 Selected TERMID
SELECTED_SHIPPED_RETURN_CODE DS CL1 Selected return code
RETURN_OK EQU X'00' Accept request
REJECT EQU X'01' Reject request
*
- INSTALL_SHIPPED_STANDARD
- A fullword input field containing the following information:
- INSTALL_SHIPPED_EXIT_FUNCTION
- A 1-byte field that indicates the type of resource being installed. For
install of remote terminals and connections the equated values are:
- INSTALL_SHIPPED_TERM (X'F7')
- A shipped terminal
- INSTALL_SHIPPED_RSE (X'F8')
- A shipped connection (remote system entry).
- INSTALL_SHIPPED_EXIT_COMPONENT
- A 2-byte component code, which is set to ‘ZC’.
- INSTALL_SHIPPED_CLASH
- A 1-character input field that indicates whether the TERMID of the shipped
definition is already in use in the AOR.
- Y
- The name by which the terminal or connection is known in the TOR (the value of the TERMINAL or CONNECTION attribute on the shipped definition) is already in use in the AOR to identify an installed remote terminal or connection.
- N
- The name by which the terminal or connection is known in the TOR is not in use in the AOR to identify a remote terminal or connection.
- INSTALLED_SHIPPED_NETNAME_PTR
- A fullword pointer to an 8-character input field containing the netname of the terminal or connection to be installed.
- INSTALL_SHIPPED_SELECTED_PTR
- A fullword pointer to the return fields. The output fields, for use by
your program, are:
- SELECTED_SHIPPED_TERMID
- A 4-character field used to specify the name by which the remote terminal
or connection is to be known to this system. If the name is less than 4 characters
long, it must be padded with trailing blanks. For a list of the characters
you can use in terminal names, see TERMINAL attributes.
On invocation, if INSTALL_SHIPPED_CLASH is set to 'N' (indicating no conflict of terminal names), SELECTED_SHIPPED_TERMID contains the same value as the field pointed to by INSTALL_SHIPPED_TERMID_PTR (the value of the TERMINAL or CONNECTION attribute on the shipped definition). If INSTALL_SHIPPED_CLASH is set to 'Y', SELECTED_SHIPPED_TERMID contains a CICS-generated alias.
Your user program can use this field to override a CICS-generated alias. For advice on choosing terminal and connection names, see Resetting the terminal identifier.
- SELECTED_SHIPPED_RETURN_CODE
- The 1-character return code field. The equated values are:
- RETURN_OK (X'00')
- Install the remote terminal or connection. Your user program must return this value if the resource is to be autoinstalled.
- REJECT (X'01')
- Do not install the remote terminal or connection. This is the default value.
- INSTALL_SHIPPED_TERMID_PTR
- A fullword pointer to a 4-character input field containing the name by which the terminal or connection is known in the TOR. (This is the value of the TERMINAL or CONNECTION attribute on the shipped definition.)
- INSTALL_SHIPPED_APPLID_PTR
- A fullword pointer to an 8-character input field containing the netname (applid) of the TOR.
- INSTALL_SHIPPED_SYSID_PTR
- A fullword pointer to a 4-character input field containing the name (sysid) of the connection to the TOR.
- INSTALL_SHIPPED_CORRID_PTR
- A fullword pointer to an 8-character input field containing the shipped
definition’s correlation identifier. A correlation identifier
is a unique “instance token” that is created when a terminal or connection
definition is installed and stored within the definition. Thus, if the definition
is shipped to another region, the value of the token is shipped too. The correlation
ID is used by CICS® during
attach processing, to check whether existing shipped definitions in an AOR
are up-to-date, or whether they have to be deleted and reshipped because the
terminal has been re-installed in the TOR. For further information about instance
tokens, see Efficient deletion of shipped terminal definitions.
If your control program maps TOR-allocated TERMIDs to the aliases that it assigns in the AOR, by recording correlation IDs it could check whether a terminal has been re-installed in the TOR. If the terminal has been re-installed, it is possible that the TOR-allocated TERMID relates to a different physical device from that last installed under this TERMID.