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 shipped terminals and connections is described in The communications area at INSTALL for shipped terminals. 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 local APPC connections initiated by BIND requests.

The communication area at INSTALL for APPC connections

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

Figure 37. Autoinstall control program’s communications area at INSTALL. For APPC connections initiated by BIND requests.
*---------------------------------------------------------------------*
* APPC Install parameter list - Functions 2, 3, and 4                 *
*---------------------------------------------------------------------*
INSTALL_APPC_COMMAREA       DSECT       Install Parameter List
*
INSTALL_APPC_STANDARD       DS  F       Standard field
                            ORG INSTALL_APPC_STANDARD
INSTALL_APPC_EXIT_FUNCTION  DS  XL1     Install request type
INSTALL_APPC_PS_CINIT       EQU X'F2'   Install PS via CINIT
INSTALL_APPC_PS_BIND        EQU X'F3'   Install PS via BIND
INSTALL_APPC_SS_BIND        EQU X'F4'   Install SS via BIND
INSTALL_APPC_EXIT_COMPONENT DS  CL2     Component ID 'ZC'
                            DS  XL1     Reserved
*
                            ORG ,
INSTALL_APPC_NETNAME_PTR    DS  A       -> NETNAME          Input
INSTALL_APPC_CINIT_PTR      DS  0A      -> CINIT_RU         Input
INSTALL_APPC_BIND_PTR       DS  A       -> BIND             Input
INSTALL_APPC_SELECTED_PTR   DS  A       -> Return fields    Output
INSTALL_APPC_SYNCLEVEL_PTR  DS  A       -> Sync level       Input
*
INSTALL_APPC_TEMPLATE_NETNAME_PTR DS A  -> Template NETNAME I/O
INSTALL_APPC_TEMPLATE_SYSID_PTR DS A    -> Template SYSID   Output
INSTALL_APPC_SYSID_PTR      DS A        -> New SYSID        Output
INSTALL_APPC_NETNAME2_PTR   DS A        -> Generic or       Input
*                                          member NETNAME
INSTALL_APPC_NETID_PTR      DS A        -> Network ID of    Input
*                                          incoming bind
INSTALL_APPC_TYPE_PTR       DS A        -> Generic          Input
                                           resource type
 
*
TEMPLATE_NETNAME            DS CL8      Put netname of template here
TEMPLATE_SYSID              DS CL4      Put sysid of template here
SYSID                       DS CL4      Put name of new connection here
SYNCLEVEL                   DS XL2      Synclevel of new connection
APPC_NETID                  DS CL8      NETID of incoming bind
APPC_GR_TYPE                DS CL1      G = NETNAME is generic resource name
                                        M = NETNAME is member name
                                        blank = This CICS is not a generic
                                            resource or the partner is not a
                                            generic resource.
APPC_NETNAME2_FIELD         DSECT
APPC_NETNAME2_LENGTH        DS XL2      Length of NETNAME
APPC_NETNAME2               DS 0X       Generic or member NETNAME
 
INSTALL_APPC_STANDARD header
A fullword input field comprising the following information:
INSTALL_APPC_EXIT_FUNCTION
A 1-byte field that defines the install request type. The equated values are:
INSTALL_APPC_PS_CINIT
X'F2' represents an install request for an APPC parallel-session connection from a secondary node via a CINIT request.
Note:
These requests cannot be received by CICS Transaction Server for z/OS®, Version 3 Release 1.
INSTALL_APPC_PS_BIND
X'F3' represents an install request for an APPC parallel-session connection via a BIND.
INSTALL_APPC_SS_BIND
X'F4' represents an install request for an APPC single-session connection via a BIND.
Note:
The values X'F0' and X'F1' represent, respectively, install and delete requests for terminals (including APPC single-session devices). See Writing a program to control autoinstall of terminals.
INSTALL_APPC_EXIT_COMPONENT
A 2-byte component code, which is set to ‘ZC’.
INSTALL_APPC_NETNAME_PTR
A fullword pointer to a 2-byte length field, followed by the NETNAME to be installed (input field).

For connections to CICS TORs where the partner is a generic resource, NETNAME can be the partner’s generic resource name, or its member name, depending on the setting of APPC_GR_TYPE. (For introductory information about generic resources, see the CICS Intercommunication Guide.)

INSTALL_APPC_CINIT_PTR
A fullword pointer to an input field containing the incoming CINIT, if the incoming session is a secondary.
Note:
Not applicable to CICS Transaction Server for z/OS, Version 3 Release 1.
INSTALL_APPC_BIND_PTR
A fullword pointer to a 2-byte length field, followed by an input field containing the incoming BIND.
INSTALL_APPC_SELECTED_PTR
A fullword pointer to the return fields. These are in the same format as those for autoinstall of terminals.

Note that for APPC autoinstall (functions X'F3' and X'F4') only the return code is used. You return other information for APPC in other fields defined in the communications area.

INSTALL_APPC_SYNCLEVEL_PTR
A fullword pointer to a 2-byte input field specifying the syncpoint level for the connection, which is extracted from the BIND. The possible values are:
X'0000'
Synclevel 0
X'0001'
Synclevel 1
X'0002'
Synclevel 2.
INSTALL_APPC_TEMPLATE_NETNAME_PTR
A fullword pointer to an 8-byte input/output area (TEMPLATE_NETNAME). On invocation, TEMPLATE_NETNAME normally contains blanks. However, if both the partner and the local CICS are registered as generic resources, it contains the NETNAME of the generic resource name connection, if one is present. (Generic resource name connections are described in the CICS Intercommunication Guide.)

Your control program can use the TEMPLATE_NETNAME field to specify the NETNAME of the template. For connections between generic resources, your program can accept the suggested template passed by CICS, or specify a different one--either in this field or by overwriting the suggested template with blanks and putting a value in the TEMPLATE_SYSID field.

If the specified name is less than 8 bytes, it must be padded with trailing blanks. If, as an alternative to specifying the NETNAME of the template, your program specifies its CONNECTION name in TEMPLATE_SYSID, it should fill TEMPLATE_NETNAME with blanks.

INSTALL_APPC_TEMPLATE_SYSID_PTR
A fullword pointer to a 4-byte output area (TEMPLATE_SYSID) that your control program can use to specify the SYSID (connection name) of the template. If the name is less than 4 bytes, it must be padded with trailing blanks. If, as an alternative to specifying the SYSID of the template, your program specifies its NETNAME in TEMPLATE_NETNAME, it should fill TEMPLATE_SYSID with zeros.
INSTALL_APPC_SYSID_PTR
A fullword pointer to a 4-byte output area in which your program must put the SYSID for the new autoinstalled connection. The name you supply must be unique. You can use the same or similar logic to create it that you use for creating a terminal ID. If the name is less than 4 bytes, it must be padded with trailing blanks.

If you are using recoverable resources, the SYSID chosen for a connection after a restart must be the same as that chosen in the previous CICS run.

INSTALL_APPC_NETNAME2_PTR
A fullword pointer to a 2-byte length field, followed by an 8-byte input field (APPC_NETNAME2).

If both the partner and the local CICS are generic resources, APPC_NETNAME2 is the partner’s generic resource name or member name, depending on the setting of APPC_GR_TYPE.

If the partner is not a generic resource, APPC_NETNAME2 contains the same value as NETNAME.

If the local CICS is not a generic resource, the value of APPC_NETNAME2 is meaningless.

INSTALL_APPC_NETID_PTR
A fullword pointer to an 8-byte input field containing the Network ID of the partner. This field is set whenever the local CICS is registered as a generic resource. At all other times it has a value of 0.
INSTALL_APPC_GR_TYPE_PTR
A fullword pointer to a 1-byte input field indicating whether this is a connection between generic resources and, if so, whether the NETNAME passed on the BIND is the partner’s generic resource name or its member name. The equated values are:
G
NETNAME is the partner’s generic resource name and APPC_NETNAME2 is its member name (applid).
M
NETNAME is the partner’s member name (applid) and APPC_NETNAME2 is its generic resource name.
Blank
This CICS is not registered as a generic resource or the partner is not registered.

Related concepts
Autoinstalling APPC connections--preliminary considerations
Related tasks
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Related reference
The autoinstall control program at DELETE
The sample autoinstall control program for APPC connections
[[ Contents Previous Page | Next Page Index ]]