Sample autoinstall user programs for IPIC connections (IPCONN)

Functions and default actions of the sample program

The role of the autoinstall user program in installing IPCONNs is to choose the IPCONN template to be used and to supply the name of the new connection. Optionally, the program can modify the values of the APPLID, HOST, and PORT attributes of the new connection from those supplied on the connect flow. All other attributes of the new IPCONN are taken from the template or the CICS-supplied default values and cannot be modified by the user program.

At INSTALL

When the supplied version of the user program is invoked to install an IPCONN definition, if the connection request is accepted, the value of the autoinstalled IPCONN and the APPLID that the definition specifies are dynamically generated based on the partner APPLID followed by a unique integer suffix. The suffix is generated from the value of a count that the sample user replaceable module maintains for each template IPCONN. The current value of the count is recorded in a CICS temporary storage element. For example, if the APPLID supplied is seven characters long (for example CTGSYST), a one-character count is appended to provide the full eight character IPCONN name (CTGSYST1). In this way, a maximum of nine clients are allowed to connect from the same partner.

The supplied version of the user program takes the following actions:

1. Specify a name for the new connection by setting the isaic_ipconn field equal to the last 4 non-blank characters of the connecting system's applid in the isaic_applid field.

   If the isaic_applid field is blank, set its value, and the connection name, to the suggested applid in the isaic_suggested_applid field.

2. Leave all other connection attributes to assume their default values, and return.

Connection requests are rejected in the following circumstances:

• The network ID of the partner does not match the name of an installed IPCONN template.
• The APPLID of the partner is a different length to the APPLID value supplied in the IPCONN template.
• The APPLID of the partner does not match the APPLID characters that are supplied in the IPCONN template.
• The IP address of the partner does not match the HOST value, if it is defined in the IPCONN template.
• The maximum number of autoinstalled IPCONN names, which are composed of the partner APPLID followed by the count suffix, is exceeded.

At DELETE

When invoked to delete an IPCONN definition, the supplied version of the user program takes no action and returns immediately.

Where the sample programs and copybooks are supplied

The default user program for autoinstall of IPCONNs is an assembler-language program called DFHISAIP. The corresponding copybook that defines its communications area is DFHISAIC. The source is supplied in the SDFHSAMP library. The code is supplied in assembler as module DFH$ISAI and COBOL as module DFH0ISAI. The executable load modules are supplied in the CICSTS SDFHLOAD library.

The source code of the default program, and the copybook of its communications area, are supplied in assembler-language, COBOL, PL/I, and C® versions. The supplied programs and copybooks, and the libraries in which they can be found, are summarized in Table 1.

Where you see nn, the nn indicates the CICS version and library is the library name. For example, CICSTS63.CICS.SDFHLOAD.

You can write your own IPCONN autoinstall user program in COBOL, PL/I, C, or assembler language, based on the supplied programs and copybooks.

Resource definitions

CICS supplies a resource definition group called DFHISCIP that defines the supplied, default, autoinstall program, DFHISAIP. This is included in the default CICS startup grouplist, DFHLIST. If you use a different CICS startup grouplist, ensure that you append the DFHISCIP group to it.

If you customize DFHISAIP, you may need to create your own resource definitions. When you do, ensure that you append your resource definition group to your CICS startup grouplist.