cicslterm - Invoke the local CICS client 3270 terminal emulator

AIX® HP-UX Linux Sun Solaris Windows
X X X X X

Invokes the local CICS® client 3270 terminal emulator so that you can connect to a region on the local machine.

Note: cicslterm must be used for installation verification tests only. For all other purposes, the CICS Transaction Gateway supplied cicsterm is recommended.

Syntax

On Open Systems:

cicslterm [-r regionName] [-n netName] [-m modelId] [-t transId]

cicslterm -?

On Windows:

cicslterm [-s=serverName | -r=serverName] [-t=transId] [-k=keyFile] [-c=colorFile] [-m=modelId] [-n=netName] [-p=printCommand | -f=printFile] [-q | -w]

cicslterm -?

Note: cicslterm is not supported on Windows Vista.

Description

On Open Systems, if you do not specify a region with the -r option, a list of regions is displayed so that you can select one. Your selection is verified before you are connected to the region. When you use the -r option to specify a region, you are not shown the list and cicslterm connects you to the region that you specified.

After you are connected to the region, CICS leaves you with a blank screen that is running the IBM® 3270 Information Display System emulation. You can then enter the transaction identifier of the transaction that you want to run.

Alternatively, you can run a transaction immediately when cicslterm is initially invoked, by entering one of the following commands:

On Open Systems:
cicslterm -r=regionName -t=transId
On Windows:
cicslterm -t=transId

where transId is the transaction identifier and regionName is the region name.

The CICS 3270 Terminal Emulator is associated with a particular region for the lifetime of the cicslterm process. If the region terminates, the cicslterm process remains running, to wait for any current scheduled protected transactions for the given terminal when the region is restarted. Otherwise, the cicslterm process terminates.

On Windows, the name of the pipe that is to be used for communication with the region is determined from file cicslcli.ini in directory prodDir/bin. The file cicslcli.ini must contain a stanza of the form:
Server=serverName
  Protocol=LOCALCLI
  NamedPipeName=pipeName

where serverName is the name of the server that is specified on the cicslterm command, and pipeName is the 6-character name of the pipe that is to be used. The last two characters of the name of the pipe must be unique on the machine. The pipe name must match the attribute NamedPipeName (local Named Pipe name) of an entry that is in the Listener Definitions (LD) for the region. If you change the file cicslcli.ini, you must use the "Stop All Local Terminals" icon to stop all CICS local terminals and the cicslcli client before using cicslterm to restart a CICS local terminal to pick up the change.

On Open Systems, when cicslterm receives a user interrupt signal SIGINT, it terminates immediately. If a transaction is running, it is purged. The purge happens only at the start or end of an EXEC CICS call, so the transaction does not terminate if it is waiting for a resource, or if it is in a loop that does not involve EXEC CICS calls. If a transaction that is in this condition needs to terminate, the systems administrator must purge it. Refer to the FORCEPURGE parameter description that is given in CEMT INQ/SET TASK.

You can specify a particular terminal to install by using the -n option with the NetName of the terminal from its Terminal Definitions (WD). You can explicitly specify a model type to autoinstall by using the -m option, as described below. See Processing.

Options

-s=serverName or -r=serverName (Windows only)
Specifies the name of the CICS server that you want to use.
-r regionName (Open Systems only)
Specifies the name of the CICS region to which you want to attach. If you do not specify a regionName, CICS displays an interactive menu of regions that are available for you to select. If no regions are available, CICS displays an error message.
-t=transId
Specifies the identifier of the transaction that is to run after the terminal emulator has initialized.
-k=keyFile (Windows only)
Specifies the name of the keyboard mapping file that is to be used by the emulator. If this parameter is omitted, the environment variable CICSKEY is used to identify the key mapping file. If CICSKEY is not defined, it is assumed that a file called cicskey.ini that is in the current directory contains the keyboard mapping.
-c=colorFile (Windows only)
Specifies the name of a color mapping file that is to be used by the emulator. If this parameter is omitted, the environment variable CICSCOL is used to identify the color mapping file. If CICSCOL is not defined, it is assumed that a file called cicscol.ini that is in the current directory contains the color mapping.
-m=modelId
On Windows, specifies the name of a model terminal definition, defined in the region's Terminal Definitions (WD), that is to be used to define the characteristics of the window in which transactions are to be run. If neither of the -m or -n parameters is specified, any ModelTerm value from the client initialization file is used. If no ModelTerm value has been specified in the initialization file, or if the -m parameter is specified without a value, the server's default terminal definition is used.

On Open Systems, specifies the name of the model device type (DevType) to use for autoinstallation. See Processing.

-n=netName
On Windows, specifies the name of a particular terminal definition as defined in the region's Terminal Definitions (WD).

On Open Systems, specifies the netName to use for installation. To install as a particular terminal, specify the netName of the required terminal. If you omit the netName, cicslterm autoinstalls, and a unique netName is generated in the region.

-p=printCommand (Windows only)
specifies a Windows command that is used to process the temporary print file that is generated when requests are received by the terminal emulator. The temporary print file is processed by executing the command that is obtained by appending the name of the file to the specified command. CICS does not delete the temporary print file. The command that is executed is responsible for deleting the temporary print file, if that is appropriate.

If the command contains embedded blanks, it must be surrounded by double quotation marks ("). Any double quotation marks that are in the command must be entered as backslash double quote (\").

If neither of the -f or -p parameters is specified, the PrintCommand or PrintFile parameter in the client initialization file defines the command or file that is to be used for print requests.

-f=printFile (Windows only)
Specifies the name of a file to which the output of print requests is appended. If the name of the file contains embedded blanks, it must be enclosed in double quotation marks ("). Any double quotation marks that are in the name of the file must be entered as backslash double quote (\").

If neither of the -f or -p parameters is specified, the PrintCommand or PrintFile parameter that is in the client initialization file defines the command or file that is to be used for print requests.

-q (Windows only)
(quiet) Suppresses the display of any messages that are generated by the command.
-w (Windows only)
(wait) Prompts the user to press the Enter key before the command completes, to confirm that messages that were generated by the command have been read.
-?
Causes the usage message to be displayed.

Examples

On Windows:

  1. To log on to the server server1 and run transaction CEMT:
        cicslterm -s=server1 -t=CEMT
  2. To display the syntax for accessing CICS:
    cicslterm -?
On Open Systems:
  1. To display the syntax for accessing CICS:
    cicslterm -?
  2. To access CICS and log on to the region region1:
    cicslterm -r region1
  3. To start a terminal by using the definition for a high function terminal with multibyte character support on a region region1:
     cicslterm -m hft-mb -r region1
  4. To start a terminal with the NetName BlueTerm in its Terminal Definitions on region region1:
    cicslterm -n BlueTerm -r region1
  5. To log on to a different user ID after you have started cicslterm:
    cicslterm -r region1 -t CESN

Processing

The following notes apply on Open systems.

Suggested Setup: Instead of running cicslterm interactively at the command line, you can set up cicslterm to run as part of the /etc/passwd configuration for a particular user authentication or from a profile or shell script. This is helpful when you always connect to the same region, and you always invoke the same transaction when you are connected to it.

Selecting Suitable Autoinstall Models: The autoinstall program is passed a number of model entries in the Terminal Definitions (WD). The models that are selected are:
  1. The models with a DevType that matches the model parameter that is specified in the -m option. For example, when -m hft is specified, the definitions in the WD stanza that has DevType=hft are used.
  2. If the -m option is not specified, the models selected are those with a DevType that matches the environment variable CICSLTERM.
  3. If CICSLTERM is not set, the models selected are those with a DevType that matches the environment variable TERM. The default autoinstall program selects the first of the models that are passed to it.

How cicslterm selects the Locale: cicslterm uses the locale that is held in the environment variable LANG. The value of LANG is passed from cicslterm to the region. Therefore, definitions for the locale that is specified in LANG must exist in the system on which the region resides.