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 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 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. This section describes only parameters passed at INSTALL of Client virtual terminals, in The communications area at INSTALL for Client virtual terminals, and of bridge facilities in The communications area at INSTALL for bridge facility virtual terminals.

The communications area at INSTALL for Client virtual terminals

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

Note:
The communications area for INSTALL of virtual terminals is the same as that for INSTALL of shipped terminals and connections--that is why the field names contain the word "SHIPPED".
Figure 41. Autoinstall control program’s communications area at INSTALL. For Client virtual terminals.
*--------------------------------------------------------------------------*
* Remote install parameter list - Client virtual terminal function   9     *
*--------------------------------------------------------------------------*
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'F9'      Install virtual terminal
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 of Client
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 Client
INSTALL_SHIPPED_SYSID_PTR          DS  A          Pointer to sysid of Client
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
                                   DS  CL4        Reserved
                                   DS  CL4        Reserved
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 Client virtual terminals the equated value is INSTALL_SHIPPED_TERM (X'F7').
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 supplied TERMID is already in use in this region.
Y
The name passed to the CICS autoinstall function is already in use in this region to identify an installed remote terminal or connection.
N
The name passed to the CICS autoinstall function is not already in use in this region to identify a remote terminal or connection.
INSTALL_SHIPPED_NETNAME_PTR
A fullword pointer to an 8-character field containing the netname of the Client workstation. This field contains the same value as the field pointed to by INSTALL_SHIPPED_APPLID_PTR.
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 virtual terminal will be known to CICS. 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 supplied name). If INSTALL_SHIPPED_CLASH is set to 'Y', SELECTED_SHIPPED_TERMID contains a CICS-generated alias.

Your user program can override the suggested name.

SELECTED_SHIPPED_RETURN_CODE
The 1-character return code field. The equated values are:
RETURN_OK (X'00')
Install the virtual terminal. This is the default value. Your user program must return this value if the resource is to be autoinstalled.
REJECT (X'01')
Do not install the virtual terminal.
INSTALL_SHIPPED_TERMID_PTR
A fullword pointer to a 4-character input field containing the TERMID passed to the CICS autoinstall function (that is, the supplied name).
INSTALL_SHIPPED_APPLID_PTR
A fullword pointer to an 8-character input field containing the netname (applid) of the Client workstation.
INSTALL_SHIPPED_SYSID_PTR
A fullword pointer to a 4-character input field containing the name (sysid) of the connection to the Client workstation.
INSTALL_SHIPPED_CORRID_PTR
A fullword pointer to an 8-character input field that is not used for install of virtual terminals.

The communications area at INSTALL for bridge facility virtual terminals

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

Figure 42. Autoinstall control program’s communications area at INSTALL. For bridge facilities.
 -----------------------------------------------------------------------
* Install Bridge Facility                        - Function 15 & 17          
*---------------------------------------------------------------------* 
INSTALL_BRFAC_COMMAREA       DSECT       Install Parameter List     
INSTALL_BRFAC_STANDARD       DS  F       Standard field             
                             ORG INSTALL_BRFAC_STANDARD           
INSTALL_BRFAC_EXIT_FUNCTION  DS  XL1     Install type                 
INSTALL_LINK_BRFAC            EQU X'0F' Install Link Brfacility  
INSTALL_START_BRFAC           EQU X'11' Install Start Brfacility 
INSTALL_BRFAC_EXIT_COMPONENT DS CL2      Component ID 'BR'            
                             DS  CL1     Reserved                     
                             ORG ,                                  
INSTALL_BRFAC_NETNAME_PTR    DS  A       Pointer to input netname           
INSTALL_BRFAC_SELECTED_PTR   DS  A       Pointer to return fields     
INSTALL_BRFAC_TERMID_PTR     DS  A       Pointer to input termid   
                             DS  A       Reserved                     
                             DS  A       Reserved                     
                             DS  A       Reserved                     
INSTALL_BRFAC_SELECTED_PARMS DSECT ,                               
                             DS  CL8     Reserved                     
SELECTED_BRFAC_TERMID        DS  CL4     Selected termid              
SELECTED_BRFAC_RETURN_CODE   DS  B       Selected return              
SELECTED_BRFAC_NETNAME  DS  CL8     Selected netname             
*                                                                       
*-----------------------------------------------------------------------* 
INSTALL_BRFAC_STANDARD
A fullword input field containing the following information:
INSTALL_BRFAC_EXIT_FUNCTION
A 1-byte field that indicates the type of resource being installed. For install of bridge facility virtual terminals. The equated values are:
INSTALL_LINK_BRFAC (X'0F')
The autoinstall program was called during installation of a bridge facility to be used by the Link3270 bridge.
INSTALL_START_BRFAC (X'11')
The autoinstall program was called during installation of a bridge facility to be used by the START bridge.
INSTALL_BRFAC_EXIT_COMPONENT
A 2-byte component code, which is set to ‘BR’.
INSTALL_BRFAC_NETNAME_PTR
A fullword pointer to an 8-character field containing the netname of the bridge facility. This is either the value specified by the client or the value generated by CICS if the client specifies BRIHNN-DEFAULT (the default value).
INSTALL_BRFAC_SELECTED_PTR
A fullword pointer to the return fields. The output fields, for use by your program, are:
SELECTED_BRFAC_TERMID
A 4-character field used to specify the name by which the virtual terminal will be known to CICS. 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. You can copy the name in INSTALL_BRFAC_TERMID_PTR, or set a new value.
SELECTED_BRFAC_RETURN_CODE
The 1-character return code field. The equated values are:
RETURN_OK (X'00')
Install the virtual terminal. This is the default value. Your user program must return this value if the resource is to be autoinstalled.
REJECT (X'01')
Do not install the virtual terminal.
SELECTED_BRFAC_NETNAME
An 8-character field used to specify the netname of the bridge facility. If the name is less than 8 characters long, it must be padded with trailing blanks. You can copy the name in INSTALL_BRFAC_NETNAME_PTR, or set a new value.
INSTALL_BRFAC_TERMID_PTR
A fullword pointer to a 4-character input field containing the TERMID passed to the CICS autoinstall function (that is, the supplied name).

Related concepts
How Client virtual terminals are autoinstalled
How bridge facility virtual terminals are autoinstalled
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 ]]