The autoinstall control program at INSTALL

If autoinstall is operative, you can specify that CICS® is to invoke the autoinstall control program for MVS™ consoles, in addition to those devices listed in topic The autoinstall control program at INSTALL. To enable CICS to invoke the autoinstall control program for consoles, specify AICONS=YES as a system initialization parameter, or issue a SET AUTOINSTALL CONSOLES(PROGAUTO) command.

On each invocation of the autoinstall control program, CICS passes a parameter list to the control program by means of a communication area addressed by DFHEICAP. This topic describes only the install function of console definitions.

The control program is invoked at INSTALL for a console when:

The communication area at INSTALL for consoles

The layout of the communication area is shown in Figure 34.

Figure 34. Autoinstall control program’s communication area at INSTALL for consoles
 
    Fullword 1       Standard Header
      Byte  1        Function Code           (X'FD' for INSTALL)
      Bytes 2 - 3    Component Code          Always 'ZC'
      Byte  4        Reserved                Always X'00'
    Fullword 2       Pointer to CONSOLENAME_FIELD
    Fullword 3       Pointer to MODELNAME_LIST
    Fullword 4       Pointer to SELECTED_PARMS
    Fullword 5       Reserved

The parameter list contains the following information:

  1. A standard header. Byte 1 indicates the request type (this is hexadecimal character X'FD' for INSTALL), and bytes 2 to 3 contain the component code, which is always ZC for consoles. (Byte 4 is reserved.)
  2. Start of changeA pointer to a 2-byte length field, followed by the console name of the console which sent the message.End of change
  3. A pointer to an array of names of eligible autoinstall models. The array is preceded by a 2-byte field containing the number of 8-byte name elements in the array. If there are no elements in the array, the number field is set to zero.
  4. A pointer to the area of storage that you use to return information to CICS.

CICS passes a list of eligible autoinstall models in the area addressed by fullword 3 of the parameter list. From this list, the control program must select a model that is suitable for the console device, and move the model name to the first 8 bytes of the area addressed by fullword 4 of the parameter list. Before returning to CICS, the control program must supply a CICS 4-character terminal ID for the console being logged on, and set the return code field to X'00' if the autoinstall request is to be allowed. Your program can also set the delay period that is to follow the last use of a console before it is automatically deleted by CICS. On entry to your autoinstall control program, this value is set to a default value of 60 minutes. Override this by storing your own delay period, in minutes, as a fullword binary value. Setting this field to zero (0) means that CICS never deletes the console.

Figure 35 shows all of these fields in their required order.

Figure 35. Autoinstall control program’s parameter list at INSTALL
 The picture shows, in graphical format, the communication area described in the preceding pages. The communication area consists of five fullwords, as follows:   Standard Header. Byte 1 indicates the request type (this is hexadecimal character X'FD' for INSTALL). Bytes 2 and 3 contain the CICS component code, 'ZC'. Byte 4 is reserved. Pointer to a 2-byte length field, followed by the name of the console to be installed. Pointer to an array of names of eligible autoinstall models. The array is preceded by a 2-byte field describing the number of 8-byte name elements in the array. Pointer to the area of storage that you use to return information to CICS. This storage area contains the following fields:   Modelname 8-byte output field.  Terminal ID 4-byte output field.  Reserved 4-byte reserved field.  Reserved 4-byte reserved field.  Return code 1-byte input/output field.  Reserved 8-byte reserved field.  Reserved 8-byte reserved field.  Reserved 3-byte reserved field.  Delete delay 4-byte input/output field.   Reserved.

How CICS builds the list of autoinstall models

CICS builds the list of autoinstall models by selecting from its complete list of terminal models those models that define console devices. The complete list of autoinstall models available to CICS at any time comprises all the definitions with AUTINSTMODEL(YES) and AUTINSTMODEL(ONLY) that are installed, and which reference a TYPETERM definition that specifies DEVICE(CONSOLE). If CICS cannot find a model for consoles, it issues message DFHZC6902. If the return code in the area addressed by fullword 4 of the parameter list is nonzero, CICS issues error message DFHZC6987. You can obtain a list of autoinstall model definitions using the CEMT (or EXEC CICS) INQUIRE AUTINSTMODEL command.

Returning information to CICS

At the INSTALL event, the autoinstall control program is responsible for allowing or denying the installation of a new console resource in the CICS region. This decision can be based on a number of installation-dependent factors, such as security, or the total number of connected terminals. CICS takes no part in any such checking. You decide whether any such checking takes place, and how it is done.

If you want an INSTALL request to proceed, perform these steps in your autoinstall control program:

Note that these are the only attributes of the TERMINAL definition that can be set by the autoinstall control program; all other attributes must come from one of the following sources:

If your control program decides to reject the INSTALL request, it should return to CICS with a non-zero value in the return code. Having completed processing, the control program must return to CICS by issuing an EXEC CICS RETURN command.

Selecting the autoinstall model

All the models in the list passed to your program are for consoles. That is to say, a viable TCT entry usually results from the use of any one of them. The default autoinstall control program simply picks the first model in the list. However, this model may not provide the attributes required in all cases. Your control program must be able to select the model that provides the characteristics you require for the console--for example, one that has the required security characteristics.

Setting the TERMINAL name

The TERMINAL name must be unique, and be one- through four-characters long. The TERMINAL name is the identifier CICS uses for the console. The CONSNAME value is the identifier MVS uses for the console.

If the control program attempts to install a TCT entry for a TERMINAL name that already has a TCT entry, the installation is rejected, even if the terminal is eligible and a suitable model has been found. On the other hand, if a MODIFY command is received from an MVS console for which CICS already has an entry in the TCT with a matching CONSNAME, CICS uses that entry and does not invoke your autoinstall control program.

The default autoinstall control program creates the TERMINAL name from the last four non-blank characters of the CONSNAME. This may not satisfy the requirement for uniqueness. One way of overcoming this problem is to use the EXEC CICS INQUIRE command from the control program, to determine whether the TERMINAL name is already in use. If it is, modify the last character and check again.

CICS action on return from the control program

When CICS receives control back from the autoinstall control program, it examines the return code field:

For all autoinstall activity, messages are written to the transient data destination CADL. If an INSTALL fails, a message is sent to CADL, with a reason code. You can check the output from CADL to find out why an autoinstall request failed.

Related concepts
Autoinstalling consoles--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 programs for consoles
[[ Contents Previous Page | Next Page Index ]]