How Client virtual terminals are autoinstalled

Client virtual terminals are defined to CICS® Transaction Server for z/OS® as remote 3270 datastream devices.

Autoinstall models

The autoinstall model used to install a virtual terminal is determined using the following sequence:

  1. For EPI programs:
    From the DevType parameter of the CICS_EpiAddTerminal function, if specified by the Client EPI program. (For details of EPI calls, see the CICS Family: Client/Server Programming manual.)

    For the Client terminal emulator:
    From the /m parameter of the cicsterm command used to start the emulator, if specified by the workstation user. (For details of the cicsterm command, see the CICS Clients: Administration manual.)

    Note:
    Any autoinstall models specified by Clients must, of course, be defined to CICS. However, because VTAM® definitions are not required for Client virtual terminals, there is no need to create matching entries in the VTAM LOGMODE table.
  2. The CICS-supplied autoinstall model, DFHLU2.

The autoinstall control program cannot choose a different autoinstall model.

Terminal identifiers

The terminal identifier (TERMID) passed to the CICS autoinstall function at install of a virtual terminal is determined using the following sequence:

  1. For EPI programs:
    From the NetName parameter of the CICS_EpiAddTerminal function, if specified by the Client EPI program.

    For the Client terminal emulator:
    From the /n parameter of the cicsterm command used to start the emulator, if specified by the workstation user.

  2. A name generated automatically by CICS.

    TERMIDs generated by CICS for Client terminals consist of a 1-character prefix and a 3-character suffix. The default prefix is '\', but you can specify a different prefix using the VTPREFIX system initialization parameter. The suffix can have the values 'AAA' through '999'. That is, each character in the suffix can have the value 'A' through 'Z' or '0' through '9'. The first suffix generated by CICS has the value 'AAA'. This is followed by 'AAB', 'AAC', ... 'AAZ', 'AA0', 'AA1', and so on, up to '999'.

    Each time a Client virtual terminal is autoinstalled, CICS generates a 3-character suffix that it has not recorded as being in use.

    Note:
    By specifying a prefix, you can ensure that the TERMIDs of Client terminals autoinstalled on this system are unique in your transaction routing network. This prevents the conflicts that could occur if two or more regions ship definitions of virtual terminals to the same application-owning region (AOR).

    For details of the VTPREFIX system initialization parameter, see the CICS System Definition Guide.

For brevity, we shall refer to the name specified by the Client or the CICS-generated "VTPREFIX" name as the supplied name. The Client always knows the virtual terminal by the supplied name. However, your autoinstall control program can allocate an alias, by which the virtual terminal will be known to CICS.

If the CICS autoinstall function detects that the supplied name clashes with the name of a remote terminal or connection already installed on this region, it generates an alias TERMID. CICS generates alias TERMIDs for virtual terminals in the same way as it generates aliases for shipped terminals--see CICS-generated aliases.

Note:
If the supplied name clashes with the name of a local terminal or connection, the install of the virtual terminal is rejected, and the autoinstall control program is not invoked.

The autoinstall control program is invoked once for each virtual terminal definition to be installed. When it is invoked, field INSTALL_SHIPPED_TERMID_PTR of the communications area points to the supplied TERMID. Field SELECTED_SHIPPED_TERMID contains either the supplied TERMID, or a CICS-generated alias, depending on whether a clash of names has been detected.

Your control program can accept the TERMID passed in SELECTED_SHIPPED_TERMID, change it, or reject the installation of the virtual terminal.

Why override TERMIDs?

Why might you want to create an alias for the supplied TERMID (or, in the case of a clash of names, to override the alias generated by CICS)? You may not need to; it may depend on the way in which your server programs are written. By "server programs" we mean both the transaction programs started by Client EPI programs, and those started from the Client terminal emulator.

Overriding CICS-generated TERMIDs

If you are using CICS-generated TERMIDs (and have specified a different prefix, reserved for virtual terminals, on each region on which Client terminals can be installed), there should be no clash of names, either in the regions in which the virtual terminals are installed, or when different regions ship Client definitions to the same AOR. However, if you are using CICS-generated TERMIDs, your server programs must not rely on TERMIDs being allocated consistently to particular Client terminals.

A Client terminal can be deleted by a Client sending a CICS_EpiDelTerminal request, by an end user shutting down a Client terminal emulator or the Client itself, or if a connection failure occurs. 6   When it is reinstalled, CICS does not necessarily generate the same TERMID as it had previously. This could create problems if, for example:

If your server programs cannot be rewritten, it may be necessary for your autoinstall control program to create aliases for the CICS-generated TERMIDs. It could, for example, use a mapping file to relate particular aliases to particular Client workstations (identified by connection name).

If your server programs are located on a back-end AOR, the autoinstall control program is invoked in the AOR when a virtual terminal is shipped in, just as for any other shipped definition. It can, if necessary, allocate an alias terminal identifier to the shipped definition. (For details of writing a control program to install shipped definitions, see Writing a program to control autoinstall of shipped terminals.)

Overriding Client-specified TERMIDs

If TERMIDs are always nominated, in a consistent way, by your Client EPI programs, the problem of data mismatch due to server programs recording TERMIDs should not occur.

However, Client-specified TERMIDs could clash with non-Client remote TERMIDs; or, if several Clients are attached to the same CICS system, with each other. If this occurs in the region on which the CTIN transaction runs, for consistency your autoinstall control program may need to allocate alias TERMIDs, rather than relying on the aliases provided by CICS. (That is, it may need to relate particular TERMIDs to particular Client workstations, as previously described.)

If a name clash occurs in an AOR, the autoinstall control program is invoked in the AOR. It can resolve the conflict by allocating an alias terminal identifier to the shipped definition.

Related concepts
How bridge facility virtual terminals are autoinstalled
Related tasks
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Writing a program to control autoinstall of terminals
Writing a program to control autoinstall of consoles
Writing a program to control autoinstall of APPC connectionsWriting a program to control autoinstall of shipped terminals
Related reference
The autoinstall control program at INSTALL
The autoinstall control program at DELETE
Default actions of the sample programs

6.
Definitions of Client virtual terminals are not deleted by the CICS Transaction Server for z/OS, Version 3 Release 1 timeout delete mechanism that operates on shipped terminal definitions. That is, the timeout delete mechanism does not operate on the (remote) definitions of Client terminals on the CICS Transaction Server for z/OS, Version 3 Release 1 system on which the install Client terminal transaction (CTIN) runs. It does operate on Client definitions that are shipped to a back-end CICS/ESA 4.1 or later system.

[[ Contents Previous Page | Next Page Index ]]