Autoinstalling IPIC connections; preliminary considerations

The IPCONN autoinstall user program is similar to the APPC autoinstall user program. Like the APPC autoinstall user program, the IPCONN autoinstall user program can choose an installed connection to use as a template for the new connection. The main differences are that the template is an IPCONN definition rather than a CONNECTION definition, and that the use of the template is optional.

If IPCONN autoinstall is active, CICS® installs the new IPIC connection using this information:
  • The information in the connect flow
  • The IPCONN template, optionally selected by the IPCONN autoinstall user program
  • Values returned by the user program in its communications area
  • CICS-supplied values

Autoinstall templates for IPCONN resources

Unlike autoinstall for other resources, autoinstall for IPCONN resources does not require model definitions, although they are recommended. However, unlike the model definitions used to autoinstall terminals, those used to autoinstall IPCONN resources do not have to be defined explicitly as models. Instead, CICS can use any previously installed IPCONN definition as a template for a new definition.

The purpose of a template is to provide CICS with a definition that can be used for all connections with the same properties. You customize the supplied autoinstall user program to select an appropriate template for each new connection, depending on the information it receives from CICS.

You can use any installed IPCONN definition as a template but, for performance reasons, use an installed definition that you do not use as an appropriate template. The definition is locked while CICS is copying it, and, if you have a large number of IPCONNs being autoinstalled at one time, the delay might be noticeable.

Requirements for autoinstall

IPCONN autoinstall is active if these conditions are met:
  1. The receiving region must have installed at least one TCPIPSERVICE that specifies PROTOCOL(IPIC).
  2. The name of the IPCONN autoinstall user program must be specified on the URM option of the installed TCPIPSERVICE definition.
    Note: This requirement differs from autoinstall of APPC connections, where the name of the autoinstall user program is specified on the AIEXIT system initialization parameter. IPCONN autoinstall has no equivalent system initialization parameter. Instead, the name of the autoinstall user program is specified on the TCPIPSERVICE definition.

As with APPC, putting the template IPCONNs out-of-service disables the autoinstall function.

When the user program is called

The user program is called when both the following conditions are met:
  1. A TCPIPSERVICE resource that is defined with PROTOCOL(IPIC) receives either a connect flow containing a NETWORKID and APPLID combination for which there is no installed IPCONN definition, or a connect flow with a null APPLID. If HOST(ANY) is specified in the TCPIPSERVICE definition of the receiving CICS system instead of a specific IPv6 address, the IPCONN uses the default IPv4 address so that communication is guaranteed.
  2. The URM attribute of the receiving TCPIPSERVICE resource specifies the name of an autoinstall user program. If the URM attribute contains NO, the autoinstall request is rejected.

The autoinstall user program for IPCONN resources

The purpose of the autoinstall user program is to provide CICS with any extra information it needs to complete an autoinstall request. For IPIC connections, the user program provides a name for the new connection. Optionally, it can select an in-service IPCONN definition to use as a template, and modify the values of the APPLID, HOST, and PORT attributes of the new connection from those supplied on the connect flow.

The RECEIVECOUNT attribute on the autoinstalled IPCONN resource is set to the value requested on the connect flow from the client, or the minimum of this value and the RECEIVECOUNT value from the template, if a template is specified.

The SENDCOUNT attribute on the autoinstalled IPCONN resource is set to the same value as RECEIVECOUNT, or the SENDCOUNT value from the template, if a template is specified.

All other attributes of the new IPCONN definition are taken from the template, or from CICS-supplied values if no template is specified, and cannot be modified by the user program.

If the selected template is usable, CICS makes a copy of the definition in it and attempts to install the new IPCONN definition. If the installation is not successful, a message is issued.

The default autoinstall user program, DFHISAIP, is an assembler-language program. A key difference between APPC and IPIC autoinstall is that DFHISAIP is the default value of the URM option on a TCPIPSERVICE where IPIC is the specified protocol. Therefore, IPIC connections will be autoinstalled by default. To disable autoinstall, specify URM=NO in the TCPIPSERVICE resource definition. DFHISAIP creates an 8-character IPCONN identifier, so, if you are using IPIC connections for CICS-to-CICS communication, ensure that you specify a 4-character IPCONN name with four trailing spaces, because the REMOTESYSTEM attribute in the terminal-owning region reads the first four characters only of the IPCONN.

If the default user program is not adequate for your purposes, you can write a customized version of the default program, or create your own program to provide enhanced function. CICS supplies the source code of the default program in several programming languages; see Sample autoinstall user programs for IPIC connections (IPCONN).

Recovery and restart

Autoinstalled IPCONN resources are cataloged by CICS, for recovery at an emergency restart only. They are not recovered at a warm restart.