Installing Client virtual terminals

If the EPI or the Client terminal emulator is to be used, the Client virtual terminals must be installed on CICS® on System/390®. Client virtual terminals are defined to CICS on System/390 as remote 3270 terminals.

Note the following:

Using static definitions

You can use CEDA DEFINE and INSTALL commands to create static definitions of Client terminals. When you use static definitions:

Figure 30 and Figure 31 are example TERMINAL and TYPETERM definitions for Client terminals.

Example Client terminal definition

Note that:

Figure 30. Example TERMINAL definition for statically defined Client virtual terminal
DEFINE TERMINAL(VT12) GROUP(CLEPIVT)
OVERTYPE TO MODIFY
 CEDA DEFine
  TErminal     ==> VT12
  Group        ==> CLEPIVT
  AUTINSTModel ==> No                 No|Yes|Only
  AUTINSTName  ==>
 TERMINAL IDENTIFIERS
  TYpeterm     ==> CLIVT
  NEtname      ==>
  CONSOle      ==> No                 No|0-99
  REMOTESystem ==> CLIA
  REMOTESYsnet ==>
  REMOTEName   ==>
 ASSOCIATED PRINTERS
  PRINTERCopy  ==> No                 No|Yes
  ALTPRINTCopy ==> No                 No|Yes
 PIPELINE PROPERTIES
  TAsklimit    ==> No                 No|1-32767
 OPERATOR DEFAULTS
  OPERPID      ==>
  OPERPriority ==> 000                0-255
  OPERRsl      ==> 0                  0-24,...
  OPERSecurity ==> 1                  1-64,...
 PRESET SECURITY
  Userid       ==>
 TERMINAL USAGES
  TErmpriority ==> 000                0-255
  Inservice    ==> Yes                Yes|No
 SESSION SECURITY
  ATtachsec    ==> Local              Local|Identify|Verify|
                                      Persistent|Mixidpe
  BINDPassword  ==>                   PASSWORD NOT SPECIFIED
  BINDSecurity  ==> No                No|Yes

Here is an example TYPETERM definition to accompany the preceding TERMINAL definition. It is based on the CICS-supplied TYPETERM, DFHLU2.

Figure 31. Example TYPETERM definition for statically defined Client virtual terminal
DEFINE TYPETERM(CLIVT) GROUP(CLEPIVT)
OVERTYPE TO MODIFY
CEDA DEFINE
  TYpeterm     ==> CLIVT
  Group        ==> CLEPIVT
 RESOURCE TYPE
  DEVice       ==> LUTYPE2
  TERmmodel    ==> 2
  SESsiontype  ==>
  LDclist      ==>
  SHippable    ==> Yes                 No|Yes
 MAPPING PROPERTIES
  PAGesize     ==> 024 , 080          0-999
  ALTPage      ==> 000 , 000          0-999
  ALTSUffix    ==>
  FMhparm      ==> No                 No|Yes
  OBOperid     ==> No                 No|Yes
 PAGING PROPERTIES
  AUTOPage     ==> No                 No|Yes
 DEVICE PROPERTIES
  DEFscreen    ==> 024 , 080          0-999
  AUDiblealarm ==> Yes                No|Yes
  EXtendedds   ==> Yes                No|Yes
  Query        ==> All                No|Cold|All
  SOsi         ==> No                 No|Yes
  BAcktrans    ==> No                 No|Yes
  CGcsgid      ==> 00000 , 00037      0-65535
 SESSION PROPERTIES
  AScii        ==> No                 No|7|8
  SENdsize     ==> 01536              0-30720
  RECEivesize  ==> 00256              0-30720
  BRacket      ==> Yes                Yes|No
  LOGMode      ==>
 DIAGNOSTIC DISPLAY
  ERRLastline  ==> Yes                No|Yes
  ERRIntensify ==> Yes                No|Yes
  ERRColor     ==> No                 No|Blue|Red|Pink|Green|
                                      Turquoise|Yellow|NEutral
  ERRHilight   ==> No                 No|Blink|Reverse|Underline
 OPERATIONAL PROPERTIES
  AUTOConnect  ==> No                 No|Yes|All
  ATi          ==> Yes                No|Yes
  CReatesess   ==> No                 No|Yes
  RELreq       ==> Yes                No|Yes
  DIscreq      ==> Yes                Yes|No
 MESSAGE RECEIVING PROPERTIES
  ROutedmsgs   ==> All                All|None|Specific
  LOGOnmsg     ==> Yes                No|Yes
 APPLICATION FEATURES
  BUildchain   ==> Yes                No|Yes
  USerarealen  ==> 000                0-255
  Ioarealen    ==> 00256 , 04000      0-32767
  UCtran       ==> Yes                No|Yes|Tranid

Using autoinstall

The preferred method of defining Client terminals is to use autoinstall, because it is more convenient when many terminals connect to a single server.

Autoinstall models

If you use autoinstall, you may need to create some model terminal definitions (that is, TERMINAL-TYPETERM pairs) for use with Client terminals, unless you have some existing ones that are suitable. The CICS-supplied autoinstall model DFHLU2 may be appropriate (it is the default if the Client does not specify a model name). Value 2 of the CGCSGID option of the TYPETERM definitions should specify the code page to be used by the CICS on System/390 server for data conversion.

Note:
Because Client virtual terminals are not "seen" by VTAM, there is no need to create matching entries for the autoinstall models in the VTAM LOGMODE table.

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 Transaction Gateway: Programming Reference manual.)

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

  2. The CICS-supplied autoinstall model, DFHLU2.

The autoinstall user 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.

    Note that the terminal names passed by Clients are case-sensitive--that is, if they contain lowercase letters, these are not translated into uppercase by CICS.

  2. A name generated automatically by CICS. TERMIDs generated by CICS for autoinstalled Client terminals consist of a 1-character prefix and a 3-character suffix. The default prefix is '\'. 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.

    You can use the VTPREFIX system initialization parameter to override the default prefix assigned to CICS-generated TERMIDs. Use VTPREFIX to specify a different prefix, reserved for virtual terminals, on each TOR on which Client virtual terminals are to be installed. This ensures that the TERMIDs of Client terminals autoinstalled on each system are unique in your transaction routing network. This in turn prevents the conflicts that could occur if two or more terminal-owning regions ship definitions of Client virtual terminals to the same application-owning region.

    If such a naming conflict does occur--that is, if a Client virtual terminal is shipped to an AOR on which a remote terminal of the same name is already installed--the autoinstall user program is invoked in the AOR. Your user program can resolve the conflict by allocating an alias terminal identifier to the shipped definition. (For details of writing an autoinstall user program to install shipped definitions, see your CICS on System/390 Customization Guide.)

    Notes:
    1. You can specify VTPREFIX as a system initialization override, or by coding an entry in the system initialization table (SIT).
    2. When specifying a prefix, ensure that TERMIDs generated by CICS for Client terminals do not conflict with those generated by your autoinstall user program for user terminals, or with the names of any other terminals or connections.
    3. Client terminal definitions are not recovered after a restart. Immediately after a restart, no Client terminals are in use, and so when CICS generates TERMIDs it begins again at the start of its sequence. This means that CICS does not always generate the same TERMID for any given Client terminal. This in turn means that server applications cannot assume that a particular CICS-generated TERMID always equates to a particular Client terminal.
      CICS TS for OS/390 and CICS TS for z/OS only

      If your server programs do make this assumption, you can use your autoinstall user program to allocate alias TERMIDs, by which the virtual terminals will be known to CICS, in a consistent manner. For further details, see Writing EPI server programs.

    For definitive information about the VTPREFIX system initialization parameter, see your CICS on System/390 System Definition Guide.

CICS TS for OS/390 and CICS TS for z/OS only

The autoinstall user program:

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

One reason for using your autoinstall program to assign aliases to Client terminals might be to ensure that particular identifiers relate consistently to particular Client terminals. Whether this consistency is required depends on how your server applications are coded--see Writing EPI server programs.

Your autoinstall user program cannot change the autoinstall model.

For further information about writing a user program to control the installation of Client virtual terminals, see your CICS on System/390 Customization Guide.

How CICS installs Client terminals

When an EPI program issues a CICS_EpiAddTerminal call, or the workstation user uses the cicsterm command to start an emulator session, the Client invokes the CTIN transaction to install or reserve the terminal definition on CICS on System/390.

Table 43 relates the parameters passed by the Client to the way in which CICS installs the Client terminal.

Table 43. How CICS installs definitions of Client virtual terminals
CICS_EpiAddTerminal parameters or cicsterm specified CICS actions
NetName DevType or Model-
name
Static definition exists? Result TERMID Autoinstall model
Yes No Yes Use static definition 10 Client- specified -
Yes No No Call fails - -
Yes Yes No Autoinstall Client- supplied 11 Client- specified
Start of changeYesEnd of change Start of changeYesEnd of change Start of changeYesEnd of change Start of changeUse static definition 10 End of change Start of changeClient- specifiedEnd of change Start of change-End of change
No No - Autoinstall CICS- supplied 11 DFHLU2
No Yes - Autoinstall CICS- supplied 11 Client- specified
Note:
Definitions of Client virtual terminals are not deleted by the CICS on System/390 timeout delete mechanism that operates on shipped terminal definitions. 12

Related tasks
Installing the DFHCLNT and DFHIPECI resource groups
Defining the CSCC and CIEO transient data queues
Installing connections to Clients
Defining a Client-attached printer
Setting up security

10.
A static definition is used only if its REMOTESYSTEM attribute points to a connection to the correct Client, and it is not currently in use. If the definition points to an incorrect Client, or is in use, the call fails.
11.
In CICS Transaction Server for OS/390® and CICS Transaction Server for z/OS®, the autoinstall user program may allocate an alias by which the terminal will be known to CICS. The Client knows the terminal by the supplied name.
12.
That is, the timeout delete mechanism does not operate on the remote definitions of Client terminals installed on the CICS on System/390 system on which the CTIN transaction runs. It does operate on Client definitions that are shipped to a back-end CICS Transaction Server for OS/390, CICS Transaction Server for z/OS, or CICS Transaction Server for VSE/ESA system.

[[ Contents Previous Page | Next Page Index ]]