If autoinstall is operative, 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 MVS consoles is described in The autoinstall control program at INSTALL. 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 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. The parameter list passed at INSTALL of MVS consoles is described in Writing a program to control autoinstall of consoles. This section describes only INSTALL of local terminals (including APPC single-session connections initiated by a CINIT).
The control program is invoked at INSTALL for terminals when both:
The layout of the communication area is shown in Figure 28.
Fullword 1 Standard Header
Byte 1 Function Code (X'F0' for INSTALL)
Bytes 2 - 3 Component Code Always 'ZC'
Byte 4 Reserved Always X'00'
Fullword 2 Pointer to NETNAME_FIELD
Fullword 3 Pointer to MODELNAME_LIST
Fullword 4 Pointer to SELECTED_PARMS
Fullword 5 Pointer to CINIT_RU
The parameter list contains the following information:
CICS passes a list of eligible autoinstall models in the area addressed by fullword 3 of the parameter list.
If the model name is not supplied by MTS, the control program must select a model from this list that is suitable for the device logging on, and move the model name to the first 8 bytes of the area addressed by fullword 4 of the parameter list.
For example, if a 3270 printer attempts to autoinstall, the subset of matching models includes all the types in VTAM category 2 that you have defined as models. This subset could include any of the following:
The control program selects one model from this list, and CICS uses this model to build the TCTTE for the device. The default autoinstall control program, DFHZATDX, always selects the first model name in the list.
If you are not using MTS but need a printer ID or NETNAME (or an alternative printer ID or NETNAME) associated with this terminal, then your control program can supply this in the area addressed by fullword 4.
If you are using MTS, CICS passes the control program the printer and alternative printer NETNAMEs specified on the VTAM ASLTAB macro.
Before returning to CICS, the control program must supply a CICS terminal name for the device logging on, and must set the return code field to X'00' if the autoinstall request is to be allowed.
Figure 29 shows all of these fields in their required order.
If CICS finds an MTS model name (and the model is defined to CICS and is compatible with the VTAM information describing the resource), CICS puts the model name into the model name list (Autinstmodelname_1), and also into the model name field (Modelname) in the selection list addressed by fullword 4 of the parameter list.
If CICS is unable to find an MTS model name in the MTS Control Vector, or the named model does not exist or is invalid, it builds the list of autoinstall models by selecting from the complete list of terminal models those models that are compatible with the VTAM information describing the resource. The complete list of autoinstall models available to CICS at any time comprises all the definitions with AUTINSTMODEL(YES) and AUTINSTMODEL(ONLY) that have been installed, both by the GRPLIST at a CICS initial or cold start, and by INSTALL GROUP commands issued by CEDA. The CICS Resource Definition Guide describes the definition of models.
Table 48 gives you the information to work out which model types could be included in the subset of models passed to the autoinstall control program when a particular terminal attempts to install. The subset is determined by the VTAM characteristics of the device attempting to log on. The number in the right-hand column of the figure indicates the selection of the subset from the full list. When a terminal with a given combination of DEVICE, SESSIONTYPE, and TERMMODEL values attempts to logon, the subset of matching models passed to the control program includes all the models with DEVICE, SESSIONTYPE, and TERMMODEL values that have a corresponding VTAM category number in the right-hand column of the table.
If CICS finds no model that exactly matches the BIND, and if the return code in the area addressed by fullword 4 of the parameter list is nonzero, then CICS issues error message ‘DFHZC6987’. This message contains a "best failure" model name, which is provided for diagnostic purposes only. It is described in detail in CICS action on return from the control program, and in the CICS Messages and Codes.
At the INSTALL event, the autoinstall control program is responsible for allowing or denying the connection of a new terminal resource to the CICS system. 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 the INSTALL request is to proceed, the control program must do the following:
If the control program returns a model name not in the subset passed to it by CICS, CICS cannot guarantee what will happen when further processing takes place. It is the user’s responsibility to determine the effect of associating any particular logon request with a particular model name, because no interface is provided to the in-storage "model" objects.
DFHZATDX takes the last four nonblank characters of the NETNAME (addressed by fullword 2 of the parameter list) as the terminal name, so you must code your own autoinstall program if this does not match your installation’s naming conventions. See Setting the TERMINAL name for information on this.
Note that when processing an AUTOINSTALL request for an LU6.2 single session terminal the four byte terminal identifier returned by the user program is used to name a CONNECTION. It should therefore conform to the naming standards for a CONNECTION (rather than a TERMINAL) as defined in the CICS Resource Definition Guide. The user program could identify an LU6.2 AUTOINSTALL request in one of the following ways:
On entry to the autoinstall control program, the return code always has a nonzero value. If you do not change this, the autoinstall request is rejected.
If you are not using MTS, your control program can also supply or change any of the optional values, such as PRINTER and ALTPRINTER IDs or NETNAMEs, before returning to CICS. If you need information about the formats and acceptable character ranges for any of the return values, refer to the CICS Resource Definition Guide.
If you are using MTS, then VTAM supplies the PRINTER and ALTPRINTER NETNAMEs, if specified.
The printers need not be installed at this stage; however, they must be installed before you use Print Key support. PRINTER and ALTPRINTER IDs override PRINTER and ALTPRINTER NETNAMEs.
Note that TERMID, PRINTER, and ALTPRINTER 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 these sources:
If your control program decides to reject the INSTALL request, it should return to CICS with a nonzero value in the return code.
Having completed processing, the control program must return to CICS by issuing an EXEC CICS RETURN command.
If you are using model terminal support to supply the model name (and the named model exists and is valid), CICS passes the model name to your autoinstall control program--you do not need to make any further selection.
As a general rule, all the models in the list passed to your program match the VTAM data for the terminal. That is, a viable TCT entry usually results from the use of any of the models. (The exception to this rule involves the VTAM RUSIZE; if this value is incompatible, CICS issues an error message.) The default autoinstall control program merely picks the first model in the list. However, this model may not provide the attributes required in all cases. For instance, you do not want a 3270 display device definition for a 3270 printer. Your control program must be able to select the model that provides the characteristics you require for this terminal--for example, security characteristics.
To save on storage, you should try to minimize the number of different models available to the control program, and the number of different TYPETERM definitions referenced by those models. If you are migrating your definitions from DFHTCT macros, look carefully at them and eliminate those that are unnecessarily different from others. Use the QUERY function for all devices that can support it. For bisynchronous devices, which do not support QUERY, one approach is to make the definition as straightforward as possible, with no special features.
If you need special models for special cases, you can use a simple mapping of, for example, NETNAME (generic or specific) to AUTINSTNAME. Your control program could go through a table of special case NETNAMEs, choosing the specified model for each. The default model would be used for any terminal not in the table. (Note that the list of models presented to the control program is in alphabetical order with one exception which is described in the notes to Table 49.)
The TERMINAL name must be unique, and one through four characters long. For a list of the acceptable characters, see the CICS Resource Definition Guide. (The TERMINAL name is the identifier CICS uses for the terminal. The NETNAME is the identifier VTAM uses for the terminal.)
You may have transactions that depend on the terminals from which they are initiated, or to which they will be attached, having particular TERMINAL names. Some transactions are restricted to particular terminals and others behave in different ways, depending on the terminal. In some cases, the transaction may gather statistics about terminal use, using the TERMINAL name as a reference. The TERMINAL name may have meaning to those managing, using, or maintaining the network: it may, for instance, denote geographical location or departmental function.
The NETNAME is really more suitable for these purposes than the TERMINAL name, because it is eight characters in length. If you can use the NETNAME, the TERMINAL name can be randomly assigned by the autoinstall control program, and it does not matter if a terminal has a different TERMINAL name every time the user logs on. The control program is required, in this case, only to make the TERMINAL name unique within the system in which the terminal is to be autoinstalled. If the control program attempts to install a TCT entry for a TERMINAL name that already has a TCT entry, the installation is rejected, despite the fact that the terminal is eligible and a suitable model has been found. (By contrast, if the NETNAME already has a TCT entry, the terminal uses it and autoinstall can never be invoked.)
The default autoinstall control program creates the TERMINAL name from the last four nonblank characters of the NETNAME. 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.
However, you may be in a situation where you must continue to use unique and predictable TERMINAL names for your terminals. Your control program must be able to assign the right TERMINAL name to each terminal, every time the user logs on. Two possible approaches to this problem are:
Devising an algorithm avoids the disadvantages of using a table or a file, but it might be difficult to ensure both uniqueness and predictability. If some of the information in the NETNAME is not needed by CICS, it can be omitted from the TERMINAL name. An algorithm is probably most appropriate in this situation.
Using a table has two disadvantages, each of which loses you some of the benefits of autoinstall: it takes up storage and it must be maintained. You could create a table in main temporary storage, so that it is placed in extended storage, above 16MB. You could use a VSAM file rather than a table, to avoid the storage problem. However, this might be slower, because of the I/O associated with a file. The table or file can contain information such as PRINTER and ALTPRINTER, and you can add information such as AUTINSTNAME for devices that need particular autoinstall models. (See Selecting the autoinstall model.)
If a CICS region is using dynamic LU aliases (that is, LUAPFX=xx is specified on the VTAM APPL definition), selecting a unique TERMINAL name may be more complicated than otherwise. The following factors should be considered:
If this logic fails to create a termid for any reason it drops through to create the terminal id from the network name as usual. Note this code is enclosed within comments and is supplied only to illustrate how to extract the required information from the CINIT and BIND '0E' control vectors
When CICS receives control back from the autoinstall control program, it examines the return code field. If this is zero, and if the other required information supplied is satisfactory, CICS schedules the new resource for OPNDST in order to complete the logon request. If the installation process fails, then the control program is driven again, as though a DELETE had occurred. (See the section The autoinstall control program at DELETE for details.) This is necessary to allow the program to free any allocations (for example, terminal identifiers) made on the assumption that this INSTALL request would succeed.
If the return code is not zero, then CICS rejects the connection request in the same way as it rejects an attempt by an unknown terminal to log on to CICS when autoinstall is not enabled.
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 therefore check the output from CADL to find out why an autoinstall request failed.
If an autoinstall attempt fails for lack of an exact match, then details of the "best failure" match between a model and the BIND image are written to the CADL transient data destination.
The message takes the following form:
DFHZC6987 BEST FAILURE FOR NETNAME: nnnnnnnn,
WAS MODEL_NAME: mmmmmmmm,
CINIT BIND: cccccccc...,
MODEL BIND: bbbbbbbb...,
MISMATCH BITS: xxxxxxxx...
where
A suggested course of action is as follows:
More information about the meaning of the bits in a BIND image, and some more references, may be found in ACF/VTAM Version 3 Programming.