The autoinstall control program at INSTALL

The autoinstall control program is invoked at INSTALL for:

On each invocation, CICS® passes a parameter list to the control program by means of a communication area addressed by DFHEICAP. The parameter list passed at INSTALL of local terminals and APPC single-session connections initiated by CINIT is described in The communication area at INSTALL for terminals. The parameter list passed at INSTALL of MVS consoles is described in The autoinstall control program at INSTALL. The parameter list passed at INSTALL of local APPC connections initiated by BIND requests is described in The communication area at INSTALL for APPC connections. The parameter list passed at INSTALL of Client virtual terminals is described in The communications area at INSTALL for Client virtual terminals. This section describes only INSTALL of shipped terminals and connections.

The communications area at INSTALL for shipped terminals

The communications area is mapped by the DSECT for the assembler version of DFHZATDX, which is supplied in CICSTS31.CICS.SDFHMAC.

Figure 39. Autoinstall control program’s communications area at INSTALL. For shipped terminals and connections.
*--------------------------------------------------------------------------*
* 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 the CICS Resource Definition Guide.

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 CICS/ESA 4.1 or later 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 need to be deleted and reshipped because the terminal has been re-installed in the TOR. For further information about instance tokens, see the CICS Intercommunication Guide.

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.

Related concepts
Installing shipped terminals and connections
Related tasks
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Related reference
The autoinstall control program at DELETE
Default actions of the sample programs
[[ Contents Previous Page | Next Page Index ]]