|
Administration
![[Help]](../help.gif)
This topic describes the commands for controlling
CICS clients, their terminal emulation, and printer support.
There is a detailed reference section for each command.
You can use the following commands to provide control
of client operation:
These commands are the basis of icons supplied with
all CICS clients apart from CICS Client for DOS.
The CICS clients start automatically when any of their
functions (EPI, ECI, or 3270 terminal emulation) are invoked at
the workstation.
It is not necessary to first use the CICSCLI command to start the
client; you can simply run CICSTERM and CICSPRNT or
double-click on their icons and the client is started with the
necessary server connections.
Note: This does not apply for CICS Client for DOS, which you must always start
using the CICSDOSC command.
For CICS Client for Macintosh the CICSCLI command is simulated by the CICS Client for Macintosh Administration Utility
(see "The CICS Client for Macintosh Administration Utility").
You enter the CICSCLI, CICSTERM,
CICSPRNT, and CICSTERP commands at the DOS command prompt.
You can also include these commands with your required
command options in batch files.
For CICS Client for DOS, you must enter CICSDOSC before entering any CICSCLI
commands at the DOS prompt.
This automatically loads CICSCTSR and starts CICS Client for DOS with the /s and /q
options.
You can also specify up to nine additional CICSCLI options when you
enter CICSDOSC at the DOS prompt.
The CICS Client for OS/2 folder
(see Figure 26)
contains icons for controlling client operation (see "CICS clients icons").
These icons are based on the CICSCLI, CICSTERM, and CICSPRNT
commands, which you enter at the
OS/2 command prompt.
Figure 26. CICS Client for OS/2 folder
The CICS Client for Windows group window
(see Figure 27)
contains icons for controlling client operation
(see "CICS clients icons").
These icons are based on the CICSCLI, CICSTERM, and CICSPRNT
commands, which you enter via the Run... option in
the Program Manager File menu.
Figure 27. CICS Client for Windows group window
When you click the Start button and select
Programs, you will see that
the CICS Client for Windows 95 folder contains icons for controlling client operation
(see "CICS clients icons").
These icons are based on the CICSCLI, CICSTERM, and CICSPRNT
commands, which you enter via the Run... command in
the Start menu.
The CICS Client for Windows NT group window
(see Figure 28)
contains icons for controlling client operation
(see "CICS clients icons").
These icons are based on the CICSCLI, CICSTERM, and CICSPRNT
commands, which you enter via the Run... option in
the Program Manager File menu, or at the MS-DOS command prompt.
Figure 28. CICS Client for Windows NT group window
You can run CICS Client for Windows NT as a Windows NT service, if you select to
register it as a service during installation.
Running CICS Client for Windows NT as a Windows NT service has several
advantages:
- You can have the CICS Client for Windows NT service
started automatically at Windows NT startup, without having to log on
to the computer.
- You can log off from Windows NT and keep CICS Client for Windows NT running, thereby
avoiding restarting the Client and its connection to CICS when you log
on to Windows NT again.
- Relevant messages associated with running CICS Client for Windows NT as a service
are recorded in the Application log and System log of the Windows NT
Event Viewer when the service is started and stopped.
CICS Client for Windows NT is registered as a
Windows NT services during installation.
After installation, the Services dialog box
in the Control Panel contains
the IBM CICS Client service.
To start the IBM CICS Client service, select the service in the
Services dialog box, and select Start.
A message is displayed
and the service is started.
To stop the IBM CICS Client service, select the service in the
Services dialog box, and
select Stop.
A message is displayed
and the service is stopped.
You may choose to start the CICS Client for Windows NT
service automatically at Windows NT startup.
To specify automatic startup, select Startup in the
Services dialog box.
The Service panel is then displayed:
Note: You must have Administrator authority to configure service
startup.
Select the Automatic radio button, and make sure that
the System Account radio button is selected.
The Service panel also allows you to specify a Manual startup for
the service, and to disable the service.
For more information on services and their configuration, refer to
the Windows NT documentation.
The CICS Client for Macintosh bin folder shown
in Figure 29
contains icons for controlling client operation,
(see "CICS clients icons").
Figure 29. CICS Client for Macintosh bin folder
These icons include the CICS Client for Macintosh Administration Utility, which provides radio button and menu
options with the same functions as the CICSCLI command of other CICS
clients
(see "The CICS Client for Macintosh Administration Utility").
You can create options files for the CICS Terminal and CICS Printer icons so
that these functions are invoked with the options that you require.
(See "Creating options files for CICS Client for Macintosh" for information on creating options files.)
The CICS Client for Macintosh Administration Utility provides the same functions as the CICSCLI command
of other CICS clients, that is, it is used to start and stop the
client process, check the availability of servers, and set other
options (see "The CICSCLI command").
Figure 30. CICS Client for Macintosh Administration Utility
You can start the utility directly by double-clicking on its
icon, in which case a dialog is invoked.
Alternatively,
you can start the utility
indirectly by double-clicking
on a text file containing CICSCLI command options - an options file.
(see "Creating options files for CICS Client for Macintosh").
The utility is then started with the command options in the options
file.
There are several supplied options files in the bin folder, and you
can also create your own using any standard text file editor.
To create your own, copy one of the supplied files, rename, it and
then edit it to include the CICSCLI options you require.
The options file must have
file type 'TEXT' and creator type 'CICX'
(See "Creating options files for CICS Client for Macintosh").
The CICS Client for Macintosh Administration Utility panel contains radio buttons with functions
as follows:
Button
| Function
| Start
| Starts the client control process (CICSCLI /s).
| Stop
| Stops the client control process (CICSCLI /x).
| Stop Now
| Stops the client control process immediately (CICSCLI /i).
| List
| Lists connected servers (CICSCLI /l).
| Trace On
| Enables client trace (CICSCLI /d).
If you select this button before the client is started,
it has no effect until you select the Start button.
You use the Trace Size scroll box to set the
maximum size of the data areas to be traced.
(This is equivalent to the CICSCLI /d=nnn command.)
| Trace Off
| Disables client trace (CICSCLI /o).
If you select this button before the client is started,
it has no effect until you select the Start button.
| Pop-ups On
| Enables display of pop-up messages (CICSCLI /e).
If you select this button before the client is started,
it has no effect until you select the Start button.
| Pop-ups Off
| Disables display of pop-up messages (CICSCLI /n).
If you select this button before the client is started,
it has no effect until you select the Start button.
|
When you enter a server name in the Server
Name field,
the action of the Start, Stop, and
Stop Now is altered to the equivalent of the
/s=servername,
/i=servername, and /x=servername options of
CICSCLI.
The File menu for the CICS Client for Macintosh Administration Utility contains the following
options:
Choose Initialization File
| Allows you to specify the name of the client initialization file (CICSCLI /f).
The name of the client initialization file is stored in a text file in the Preferences
folder and is displayed on the CICS Client for Macintosh Administration Utility panel.
You must stop the client before changing the client initialization file.
The new file is then used when you start the client again.
| Security
| Allows you to set up the security options for a connection to a
CICS server.
In the dialog box you can enter:
- Server Name (CICSCLI /c option)
- Userid (CICSCLI /u option)
- Password (CICSCLI /p option)
You select the security options by selecting OK.
|
You can create plain-text ASCII files containing
options for the CICS Client for Macintosh Administration Utility, CICS Terminal, and CICS Printer icons.
(These options correspond to the command options of the CICSCLI,
CICSTERM, and CICSPRNT commands respectively, see
"The CICSCLI command", "The CICSTERM command" and
"The CICSPRNT command".)
You can drag and drop the icon for such an options file onto the
CICS Client for Macintosh Administration Utility, CICS Terminal, and CICS Printer icons in the bin folder, to invoke
these programs with your chosen options.
If the options file is created with the file type 'TEXT'
and the appropriate creator type, you can double-click on the icon for
the file to launch the associated program:
Creator
| Program
| CICE
| CICS Terminal
| CICP
| CICS Printer
| CICX
| CICS Client for Macintosh Administration Utility
|
You can create as many options files as you
need using a text editor such as Simple Text or Teach Text.
Each options files should contain just one command line, with all the
options you require.
For example, an options file to start a 3270 terminal
emulation session (see "Using CICSTERM") might contain:
/s=CICSOS2 /t=CESN /k=mykeys.ini /c=mycols.ini /n=cicsv123 /q
To create your own options file:
- Make a copy of a supplied options file,
and rename it using Finder.
- Open the options file using Simple Text or another plain-text
editor.
- Change the command options as required.
- Ensure that the file has the file type 'TEXT' and the
appropriate creator type.
- Save the options file.
All CICS clients (apart from CICS Client for DOS) are supplied with the following
icons:
Start Client
| Starts the client according to the definitions in the
client initialization file.
This is equivalent to the command CICSCLI /s.
| Stop Client
| Stops the client.
This is equivalent to the command CICSCLI /x.
| CICS Terminal
| Starts a 3270 terminal emulation session according to definitions
in the client initialization file.
This is equivalent to the command CICSTERM.
| CICS Printer
| Starts a CICS print terminal session according to
definitions in the client initialization file.
This is equivalent to the command CICSPRNT.
| Client Status
| Lists connected servers.
This is equivalent to the command CICSCLI /l.
|
You can tailor the properties of these icons, and add new icons
according to the command variations you require for
your client (see "Customizing the command icons for CICS Client for OS/2 and CICS Client for Windows Family").
You can customize your CICS clients installation to ensure that the
command functions you use most frequently are associated with icons.
For example, you might want to create an icon for:
CICSCLI /s=servername /q /d=nnn /f=mycli.ini
to start a connection to a server used for testing applications.
To create a new command icon for CICS Client for OS/2:
- Select a command icon that issues a command similar to
the one you wish to create.
- Enter the name for the new command icon in the
Copy
dialog window and select the Copy push button.
- Open the settings dialog for the newly copied icon and edit the
list of command options in the Parameters field to create
the option
sequence that you require
(see Figure 31).
Figure 31. Creating a command icon for CICS Client for OS/2
- Change the title in the General page of the settings notebook.
- Close the settings dialog.
To create a command icon for CICS Client for Windows and CICS Client for Windows NT, you can copy a program item and
tailor it to your requirements, or simply create a new program item with the
appropriate command options in the Command Line entry
field.
(See Figure 32.)
Figure 32. Creating a command icon for CICS Client for Windows and CICS Client for Windows NT
Note: If you are running CICS Client for Windows NT under Windows NT Version 4.0, the procedure
is as described in "Creating command icons for CICS Client for Windows 95".
To create a command icon for CICS Client for Windows 95, you can copy an
existing program item and change its properties:
- Open the CICS Client for Windows 95 folder.
- Copy a program item similar to the one you require, and rename it.
- Select the new program item.
- Select Properties from the File menu, and
enter the required settings for the new icon in the Shortcut page.
You use the CICSCLI command to:
- Start the client control process, and start communication with
CICS servers (/s parameter)
- Stop the client control process (/i and /x parameters)
- Specify the client initialization file to use (/f parameter)
- Turn client trace on (/d parameter)
- Turn client trace to memory on (/t parameter)
- Dump the client trace in memory to a file (/z parameter)
- Turn client trace off (/o parameter)
- Set up security (/c, /u, and /p parameters)
- List connected CICS servers (/l parameters)
- Enable the display of pop-up messages (/e parameter)
- Disable the display of pop-up messages (/n parameter)
The following sections provide examples of using the
CICSCLI command.
Full details of the command syntax are given in "CICSCLI command reference".
To start the client control process, enter:
CICSCLI /s
To start the client control process and start communication with a
CICS server, enter:
CICSCLI /s=servername
where servername is the name of a CICS server.
Note: For CICS Client for OS/2 and CICS Client for Windows Family, you can start the CICS client
by double-clicking on the Start Client icon.
For CICS Client for DOS, you must enter CICSDOSC before entering any CICSCLI
commands at the DOS prompt.
This automatically loads CICSCTSR and starts CICS Client for DOS with the /s and /q
options.
You can also specify up to nine additional CICSCLI options when you
enter CICSDOSC at the DOS prompt.
You can start connections to servers when the CICS client is already
running.
When the CICS client has been started using the /s option, or
when connections to additional servers are to be started, enter:
CICSCLI /s=servername
where servername is the name of a CICS server.
This section describes the different ways in which you can stop
the client control process with the CICSCLI command.
To stop the client control process for all connected servers after all
outstanding units of work have completed, enter:
CICSCLI /x
To terminate the session with a particular server, enter:
CICSCLI /x=servername
where servername is the name of a CICS server.
This only stops the session with the named server, it does not stop
the client control process.
Note: For CICS Client for OS/2 and CICS Client for Windows Family, you can stop the CICS Client
by double-clicking on the Stop Client icon.
To stop the client control process for all connected servers without
completing outstanding units of work, enter:
CICSCLI /i
To terminate the session with a particular server, enter:
CICSCLI /i=servername
where servername is the name of a CICS server.
This only stops the session with the named server, it does not stop
the client control process.
To use a client initialization file other than the default
CICSCLI.INI, enter:
CICSCLI /s /f=filename
where filename is the name of the file.
The /f parameter can be used only with the /s parameter, and
only if the client is not already started.
To turn on the trace for a client, enter, for example:
CICSCLI /d=nnn
where nnn is the maximum size of the data areas to be
traced.
If you need to trace the client from the startup sequence, you
can specify the /s and /d parameters together.
The trace is written to the file specified by the TraceFile parameter in the
client initialization file (CICSCLI.LOG by default).
To turn on the trace to memory for a client, enter, for example:
CICSCLI /t=nnn
where nnn is the maximum size in bytes of the data areas to be
traced (the default is 64).
If you need to trace the client from the startup sequence, you
can specify the /s and /t parameters together.
To write the client trace in memory to a file, enter:
CICSCLI /z
This writes the internal memory buffer to the file specified by the DumpFile
parameter in the
client initialization file (CICSCLI.DMP by default).
To turn off the trace for a client,
including the trace to memory, enter:
CICSCLI /o
Some servers require that a userid and password be provided
by the client before they permit either ECI or EPI activity to be
performed.
For example, a CICS for MVS/ESA server may require that a userid and
password is provided before any ECI action is performed.
The client application
may provide a userid and password via the ECI parameter block.
If this is
not provided, and the client does not have a current user and
password to be used for communication with this specific server,
you are prompted to provide the details.
The values you enter are saved for future ECI
invocations.
As an alternative, you can supply or change the
userid and password using the CICSCLI command.
If the userid and password used to communicate with the server
are incorrect, and were not explicitly specified in the ECI
parameter
block, you are prompted again for a new pair of values when the
application or emulator runs.
You can cancel the request, in which case the ECI call fails with
an error return code.
Note: CICSCLI /n suppresses prompting for userid and password, and
returns security errors to the application.
For terminal emulators and EPI, the situation is similar
to that described for ECI.
The client holds only a single userid and
password for each server.
Therefore, if values have already
been set as a result of ECI activity, you are not prompted for
the information when a terminal is installed at the server, or
when EPI is used.
To identify a server to which security information is to be
associated, enter:
CICSCLI /c=servername
where servername is the name of a CICS server.
To set a userid to be used when accessing this server, enter:
CICSCLI /c=servername /u=userid
where userid is the userid.
To set a password to be used when accessing this server, enter:
CICSCLI /c=servername /p=password
where password is the password.
You can enter the /u and /p parameters together.
The UpperCaseSecurity parameter of the client initialization file
determines whether userids and passwords are converted to uppercase.
If this parameter
is set to Y, you can enter userids and passwords in either uppercase
or lowercase.
Note: Userids and passwords must not contain DBCS characters.
To list all the servers connected to a client and their status,
enter:
CICSCLI /l
A list like the following is displayed:
CCL8001I CICSCLI - CICS Client Control Program
CCL0002I (C) Copyright IBM Corporation 1994,1996. All rights reserved.
CCL8041I The CICS client is using the following servers:
CCL8042I Server 'CICSOS2' (using 'TCP/IP' to 'CICSOS2') is available
CCL8043I Server 'CICSNT' (using 'NETBIOS' to 'CICSNT') is unavailable
|
Note: For CICS Client for OS/2 and CICS Client for Windows Family, you can list the connected servers
by double-clicking on the Client Status icon.
To disable the display of all messages output with the command,
enter, for example:
CICSCLI /s /q
There may be times when you do not want messages (client error
and security) to
appear in p
op-up windows.
(These pop-up messages include those not
associated with the client control process.)
For example, if you leave CICS clients running unattended (overnight
perhaps), you would not
want messages appear
ing when the pop-up window cannot be closed.
To disable the display of pop-up messages, enter:
CICSCLI /n
To enable the display of pop-up messages again, enter:
CICSCLI /e
You can specify the /n parameter together with the /s parameter.
The display of pop-up messages is enabled by default.
To display the parameters of the CICSCLI command, enter:
CICSCLI /?
The following is displayed:
CCL8001I CICSCLI - CICS Client Control Program
CCL0002I (C) Copyright IBM Corporation 1994, 1996. All rights reserved.
CCL8002I Command options are:
CCL8003I /S[=server] - To start the client [and connect to a server]
CCL8004I /X[=server] - To close the client [or connection to a server]
CCL8005I /I[=server] - To abort the client [or connection to a server]
CCL8006I /L - To list active server connections
CCL8007I /D[=size] - To enable service tracing [and set a size limit]
CCL8008I /O - To disable all service tracing
CCL8009I /C=server - To specify the name of server for security changes
CCL8010I /C must be specified with one or both of /U and /P
CCL8011I /U[=userid] - To set the userid to be used with a server
CCL8012I /P[=password] - To set the password to be used with a server
CCL8013I /N - To suppress the client error and security pop-ups
CCL8014I /E - To activate the client error and security pop-ups
CCL8015I /F=inifile - To specify a client initialization file
CCL8016I /W - To wait for confirmation before completing
CCL8017I /Q - To inhibit all output messages
CCL8018I /T[=size] - To enable service tracing to memory
CCL8019I /Z - To dump service trace in memory to file
CCL8022I CICSCLI performed no action
All client control commands have options
identified by a leading slash (/).
To conform with other popular syntax conventions, this slash character
may be replaced with a minus sign (-).
The commands and options are not case-sensitive.
All options of the form /x=variable may
contain spaces in the variable part, if it is enclosed in double
quotes.
Double quotes within variables must be entered as \" , that is
with a backslash preceding the double quote.
For an explanation of syntax diagrams, see "Command syntax".

The options are:
/c=servername
| Identifies the name of the server to which security
information in the form of a userid and password is to be
associated.
Some CICS servers require that the user provide security
information
to the server
before interacting with the server.
The CICS client prompts the user at the workstation for a userid
and password, unless these have already been provided
via CICSCLI (see the descriptions of the
/u and /p options).
| /d
| Turns the debug trace on for the client.
If tracing is required while the
client is starting up, this option may be specified along
with the /s
option.
nnn is the maximum size of data areas to be traced in
bytes.
The range is 1 through 32 767 bytes, and the default is 64
bytes.
Output from the trace option is directed to the file
specified by the TraceFile
parameter in the client initialization file (CICSCLI.LOG by default).
The trace file is
generated as an ASCII file, ready to read with a text editor.
| /e
| Enables the display of client error and security messages in
pop-up windows.
| /f=inifile
| Specifies the name of the client initialization file.
The default is CICSCLI.INI.
If the file is not in the CICSCLI\BIN directory, you must
specify
the full path name.
Note: If the file resides on a redirected network drive then problems
may occur if the network drive is later detached.
| /i
| Stops the client immediately.
The options /i=servername and /i operate as for /x=servername and /x
respectively but the client does not wait for
outstanding
units of work to complete.
Stopping the client in this way may result
in a loss of data at connected servers.
| /l
| Causes a list of all connected servers to be displayed.
For each server, the netname of the server as it is known to the
client is also displayed, as well as the state of the connection
to the server and the connection protocol.
For CICS Client for DOS and CICS Client for OS/2, one line per server is displayed.
For CICS Client for Windows Family and CICS Client for Macintosh,
the data is displayed in a window.
| /n
| Disables the display of client error and security messages in
pop-up windows.
Any messages that would have been logged are still logged.
| /o
| Turns off trace (including trace to memory) if it is already active.
| /p=password
| Sets the current password to be used when accessing
the server specified by the /c parameter.
This password is used
if the server requires a password (and userid) before running
transactions on the client's behalf.
For ECI applications, any userid
and password specified in the ECI parameter block overrides
values set via the CICSCLI command.
Specifying /p or /p= (that is, no password is specified)
resets
the associated password to a null value.
| /q
| Disables the display of all messages output with the CICSCLI command.
| /s
| Starts the client control process.
No attempt is made to
initiate communication with a server unless /s=servername
is specified.
In this case, the control process also connects to the server
using information specified in the client initialization file.
The servername must exist in the client initialization file.
| /t
| Turns the trace to memory on for the client.
If tracing to memory is required while the
client is starting up, this option may be specified along
with the /s
option.
nnn is the maximum size of data areas to be traced in
bytes.
The range is 1 through 32 767 bytes, and the default is 64
bytes.
The client trace to memory writes trace records to an internal buffer
that is dumped to a file using the CICSCLI /z command, and also if the
CICS Client for OS/2 terminates abnormally.
| /u=userid
| Sets the current userid to be used when accessing
the server specified by the /c parameter.
This userid is used
if the server requires a userid (and password) before running
transactions on the client's behalf.
For ECI applications, any userid
and password specified in the ECI parameter block overrides
values set via the CICSCLI command.
Specifying /u or /u= (that is, no userid is specified) resets
the
associated userid to a null value.
| /w
| Prompts the user, before the command completes,
to press the Enter key, to confirm that
messages
output to the screen (both informational and error) have been
read.
Note: This option applies only to CICS Client for DOS and CICS Client for Windows Family.
| /x
| Stops the client in a controlled manner.
If /x=servername is specified, then when all outstanding units
of work
on the specified server have completed, the connection to the
server is
terminated.
If other server connections are active, these remain
unchanged.
If /x is specified without a servername, the client waits
for all outstanding units
of work to complete, terminates all connections to servers, and
ends the control process.
Using /x or /x=servername is the preferred way of stopping
the client.
| z
| If client trace to memory is enabled, writes the records in the
internal buffer to the file
specified by the DumpFile parameter in the client initialization file (CICSCLI.DMP by default).
The buffer is cleared after dumping, and tracing continues.
The trace records are appended to the file, if it already exists.
The dump file is
generated as an ASCII file, ready to read with a text editor.
The trace records in the memory buffer are also dumped to the file
if the CICS Client for OS/2 terminates abnormally.
| /?
| Causes the command syntax to be displayed.
|
The CICSTERM command is used to control 3270 terminal emulation.
You can start emulator sessions, specify terminal emulator
characteristics, and the names
of the keyboard mapping and color mapping files.
You can have multiple terminal emulation sessions running simultaneously.
For CICS Client for DOS, CICS Client for OS/2, and CICS Client for Windows Family, the CICSTERM command detects
whether the hardware on which the
client is running is enabled for double-byte character set (DBCS)
display.
If it is, the emulator can display DBCS characters.
Note: Some uses of servers and protocols require a model terminal
definition for the emulator that explicitly specifies that the client
wants to display DBCS.
You use the CICSTERM command to:
- Start a 3270 terminal emulator (/s or /r parameter)
- Specify the initial transaction (/t parameter)
- Specify the name of the keyboard mapping file (/k parameter)
- Specify the name of the color mapping file (/c parameter)
- Define the 3270 terminal emulator characteristics (/n and /m
parameters)
- Determine the print file processing (/p parameter)
- Specify a file to which print files are appended (/f parameter)
You issue the CICSTERM command once with all the
parameters you require.
The following is an example of a CICSTERM command:
CICSTERM /s=CICSOS2 /t=CESN /k=mykeys.ini /c=mycols.ini
/n=cicsv123 /f=clprint.txt /q
In this example:
- /s=CICSOS2
- Specifies that a 3270 terminal emulator is started for the server
CICSOS2.
- /t=CESN
- Specifies that the initial transaction is CESN.
- /k=mykeys.ini
- Specifies that the keyboard mapping file is named as MYKEYS.INI.
- /c=mycols.ini
- Specifies that the color mapping file is named as MYCOLS.INI.
- /n=cicsv123
- Specifies that the 3270 terminal emulator characteristics are
defined by the terminal definition cicsv123.
- /f=clprint.txt
- Specifies that the print file will be appended to the file
CLPRINT.TXT.
- /q
- Specifies that the display of messages output by the command is
disabled.
All parameters of CICSTERM are optional.
That is, you can enter the CICSTERM command without any parameters,
and defaults are taken from the client initialization file.
(This is equivalent to double-clicking on the CICS Terminal icon.)
Full details of the parameters are given in "CICSTERM command reference".
For CICS Client for Macintosh you can create a flat ASCII file containing the
required CICSTERM command parameters.
When you drag and drop this options file onto the CICSTERM emulator
icon,
CICSTERM runs with your chosen parameters.
If you create this options file with file type 'TEXT' and
creator type 'CICE', the file will have an appropriate icon,
and will allow double-clicking to launch CICSTERM.
To stop a terminal emulator, enter the string
specified by TerminalExit in the client initialization file.
This is EXIT by default.
For an explanation of syntax diagrams, see "Command syntax".

The options are:
(Ref #5.)
/c=colorfile
| Identifies the name of a color mapping file (see "Customizing the screen colors") to be used with the emulator.
If this
parameter is
omitted, the environment
variable
CICSCOL is assumed to identify the color mapping file.
If CICSCOL is not defined, a filename of
CICSCOL.INI
in the current directory is assumed.
Note: For CICS Client for Macintosh, you can identify a color mapping file by using an options
file (see "Options files for CICSTERM").
If the parameter is specified as /c=, (that is, the color
mapping filename
is omitted), the emulator runs without any color
definitions.
| /f=printfile
| 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 surrounded by double quotes (").
Any double quotes within
the name of the file must be entered as backslash double
quote (\").
If neither of the /f or /p parameters is provided,
the PrintCommand or PrintFile
parameter in the client initialization file
defines the command, file, or default action to take with
print requests.
(Ref #6.)
| /k=keyfile
| Identifies the name of a keyboard mapping file (see "Keyboard mapping file syntax")
to be used with the emulator.
If this parameter is omitted, the environment variable
CICSKEY is assumed to identify the key mapping file.
If CICSKEY is not defined, a filename of CICSKEY.INI
in the current directory is assumed.
Note: For CICS Client for Macintosh, you can identify a keyboard mapping file by using an
options file (see "Options files for CICSTERM").
| /m=modelname
| Specifies the name of a model terminal definition, as known
at the server to which the emulator is to connect, to be used to
define the terminal characteristics.
If neither this parameter nor
/n=netname is specified, any ModelTerm value from the
client initialization file is used.
If no ModelTerm value
has been specified in the initialization file,
the server's default terminal definition is assumed.
If the parameter is specified as /m= (that is, the modelname
is omitted), any ModelTerm value specified in the initialization
file is ignored, and the server's default terminal definition
is assumed.
This option is case-sensitive.
| /n=netname
| Specifies the name of a particular terminal definition at the
server that this emulator is to be installed as.
The precise
interpretation of netname varies between servers, for example, on
CICS for OS/2 it references a termid defined in the CICS tables, on
CICS for AIX it is a netname.
This option is case-sensitive.
| /p=printcmd
| Specifies an operating system command used to process the
temporary print file generated when print requests are received by the
terminal emulator.
If the command contains embedded blanks, then
the command must be surrounded by double quotes (").
Any double quotes within
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, file, or default action to take with
print requests.
The temporary print
file is post-processed by appending
the
filename to the command, and executing the resultant command.
Thus print output may simply be copied to a local printer, copied into
a permanent file, processed further for inclusion into a document,
and so on.
If the temporary file is to be processed by a print command, the
command is responsible for deleting the temporary file.
Note: This option does not apply to CICS Client for Macintosh, because this client
does not support
print commands.
| /q
| Disables the display of all messages output by the command.
| /s=servername or /r=servername
| Specifies the name of the server that the terminal emulator is to
be connected to.
This servername must correspond to an entry in the
client initialization file.
You can specify /s, or /r, but not both.
If neither parameter is specified, the first server entry
in the initialization file is used.
If the parameter is specified as /s or /r (that is, no
servername is provided) then, if the initialization file
identifies more than one potential server to which the client can
connect, the user is prompted to select from a list
of available servers.
These prompts are generated even if the /q parameter is
specified.
If there is only one potential server identified in the
initialization
file, that server is used and the user is not prompted.
| /t=initialtransid
| Identifies the initial transaction to be invoked for this
terminal.
If this option is omitted, any initial transaction specified
in the client initialization file is run.
The string may be up to 128 characters long, specifying both a
transaction name, and parameters to be passed to the transaction.
The transaction name is the first four characters or the characters
up to the first blank in the string.
The rest of the string is the parameter data.
If the parameter is specified as /t= (that is, the
initialtransid is omitted), any initial transaction specified in
the initialization file is ignored.
This option is case-sensitive.
Note: Be careful that transactions that you specify either here or in the
client initialization file do not require terminal input to complete.
| /w
| Prompts the user, before the command completes,
to press the Enter key, to confirm that
messages
output to the screen (both informational and error) have been
read.
Note: This option is ignored for CICS Client for Windows Family and CICS Client for Macintosh.
| /?
| Causes the parameter syntax to be listed; any other options
specified are ignored.
|
The CICSPRNT command is used to control 3270 printer terminal
emulation.
Applications running on the server can direct output to a
printer in one of two ways:
-
An application running from a terminal
can initiate printing by sending a map or data with the PRINT
indicator
set
- The user can
start at the client a 3270 Print Terminal Emulator using the
CICSPRNT command.
A 3270 Print Terminal Emulator
must be started for a netname or model terminal definition (or termid
in the case of CICS for OS/2)
predefined in the server's terminal tables.
Output is directed to
such a device by starting a transaction against the printer
device.
Note: At client workstations you can use the PrintScreen key (as
defined by the keyboard mapping file).
Note however, that any lines that contain only null characters are not
printed.
For a 'blank' line to be printed, it must contain at least one
space character.
You use the CICSPRNT command to:
- Start a 3270 print terminal emulator (/s or /r parameter)
- Specify the initial transaction (/t parameter)
- Define the 3270 printer terminal emulator characteristics (/n
and /m parameters)
- Determine the print file processing (/p parameter)
- Specify a file to which print files are appended (/f parameter)
You issue the CICSPRNT command once with all the
parameters you require.
The following is an example of a CICSPRNT command:
CICSPRNT /s=CICSOS2 /n=P123 /t=XPRT /f=clprint.txt /q
In this example:
- /s=CICSOS2
- Specifies that a 3270 print terminal emulator is started for the server
CICSOS2.
- /n=P123
- Specifies that the 3270 print terminal emulator characteristics are
defined by the terminal definition v123
(in the terminal control table for CICS for OS/2 in this case.)
- /t=XPRT
- Specifies that the initial transaction is XPRT.
- /f=clprint.txt
- Specifies that the print file to which print requests are appended
is CLPRINT.TXT.
- /q
- Specifies that the display of messages output by the command is
disabled.
All parameters of CICSPRNT are optional, except that you must
specify either
/n=netname or /m=modelname.
That is, you can enter the CICSPRNT command with just the /n or the
/m parameter, or both,
and defaults for other parameters are taken from the client initialization file.
Full details of the parameters are given in "CICSPRNT command reference".
If the system upon which the client is executing supports DBCS,
it is assumed that the printer attached to the
processor also supports DBCS.
Conversely, if the system does not
support DBCS, the client will not send DBCS data to the printer.
Note: CICS Client for Macintosh does not support DBCS.
For CICS Client for OS/2, when you double-click on the CICS Printer
icon, the Specify Parameters dialog box is displayed.
This allows you to enter the required parameters for CICSPRNT.
For all CICS clients, you should edit the settings for the icon to
change the parameters
according to your usage.
The CICSPRNT process runs as a minimized window, and the window can be
enlarged to view the current status of the printer.
You can use an action available from a pulldown menu
to terminate the print function.
On CICS Client for DOS systems, you are
presented with a panel while the
program is running, from which the program can be terminated.
For CICS Client for Macintosh you can create a flat ASCII file containing the
required CICSPRNT command parameters.
When you drag and drop this options file onto the CICSPRNT emulator
icon,
CICSPRNT runs with your chosen parameters.
If you create this options file with file type 'TEXT' and
creator type 'CICP', the file will have an appropriate icon,
and will allow double-clicking to launch CICSPRNT.
For an explanation of syntax diagrams, see "Command syntax".

The options are:
/f=printfile
| 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 surrounded by double quotes (").
Any double quotes within
the name of the file must be entered as backslash double
quote (\").
If neither of the /f or /p parameters is provided,
the PrintCommand or PrintFile
parameter in the client initialization file
defines the command, file, or default action to take with
print requests.
| /m=modelname
| Specifies the name of a model terminal definition, as known
at the server to which the 3270 Print Terminal emulator is to connect,
to be used to
define the terminal characteristics.
If this parameter
is not specified, any ModelTerm value from the
client initialization file is used.
If no ModelTerm value
has been specified in the initialization file,
the server's default terminal definition is assumed.
You must specify either the /m or the /n option, or both.
This option is case-sensitive
| /n=netname
| Specifies the name of a particular terminal definition at the
server that this 3270 Print Terminal emulator is to be installed
as.
The precise
interpretation of netname varies between servers.
For example, on
CICS for OS/2 it references a termid defined in the terminal control table (TCT),
on CICS for AIX it is a netname.
You must specify either the /m or the /n option, or both.
This option is case-sensitive.
| /p=printcmd
| Specifies a command used to process the temporary
print file generated when print requests are received by the
terminal
emulator.
If the command contains embedded blanks, then
the command must be surrounded by double quotes (").
Any double quotes within
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, file, or default action to take with
print requests.
The temporary print
file is post-processed by appending
the filename to the command, and executing the resultant command.
Thus
print output may simply be copied to a local printer, copied into
a permanent file, processed further for inclusion into a document, and
so on.
If the temporary file is to be processed by a print command, the
command is responsible for deleting the temporary file.
Note: This option does not apply to CICS Client for Macintosh, because this client
does not support
print commands.
| /q
| Disables the display of all messages output by the command.
| /s=servername or /r=servername
| Specifies the name of the server that the printer is to be
connected to.
This servername must correspond to an entry in the
client initialization file.
You can specify /s, or /r, but not both.
If neither parameter is specified, the first server entry
in the initialization file is used.
If the parameter is specified as /s or /r (that is, no
servername
is provided) then, if the initialization file
identifies more than one potential server to which the client can
connect, the user is prompted to select from a list
of available servers.
These prompts are generated even if the /q parameter is
specified.
If there is only one potential server identified in the
initialization
file, that server is used and the user is not prompted.
| /t=initialtransid
| Identifies the initial transaction to be invoked for this
printer.
If this option is omitted, any initial transaction specified
in the
initialization file is run.
The string may be up to 128 characters long, specifying both a
transaction name, and parameters to be passed to the transaction.
The transaction name is the first four characters or the characters
up to the first blank in the string.
The rest of the string is the parameter data.
If the parameter is specified as /t= (that is, the
initialtransid
is omitted), any initial transaction specified in the
initialization
file is ignored.
Note: Be careful that transactions that you specify either here or in the
client initialization file do not require terminal input to complete.
This option is case-sensitive.
| /w
| Prompts the user, before the command completes,
to press the Enter key, to confirm that
messages output to the screen (both informational and error) have been
read.
Note: This option is ignored for CICS Client for Windows Family and CICS Client for Macintosh.
| /?
| Causes the parameter syntax to be listed; any other options
specified are ignored.
|
When using CICSPRNT to start a 3270 print terminal emulator for
CICS for OS/2 Version 2.0.1, some special configuration is required.
In this case, the CICS for OS/2 user exit 21
(TCS autoinstall)
is required to guarantee that the Remote System name does not vary
during client autoinstall.
Note: This is not required in CICS for OS/2 Version 3.0, as you can
use
CICSPRNT with both the /m= and /n parameters to
autoinstall a
specific printer-name.
Within user exit 21 of CICS for OS/2 you define the RemoteApplid you
expect to receive from a CICS clients autoinstall request, and the
corresponding RemoteSystemID you want the client to use.
The following is an example in the C language:
User Exit 21 Assignment |
---|
if (strnicmp(pParms->Exp21RemoteApplid,"Prt1TCP",7) == 0)
{
strcpy(pParms ->Exp21RemoteSystemId,"P1IP");
|
Notes:
- RemoteApplid must match the Client=applid
parameter in the client initialization file.
The applid in this example
is Prt1TCP.
- RemoteSystemId must match the Remote
System
defined in the CICS for OS/2 TCT.
In this example, P1IP is used.
For more information about user exit 21, refer to the
CICS for OS/2 Customization
book.
Figure 33
shows the TCT definition required on
the CICS for OS/2 Version 2.0.1 server.
Figure 33. Client printer TCT definition: CICS for OS/2 Version 2.0.1
+--------------------------------------------------------------------------------+
| Update Add View
Delete Exit Help |
| |
|FAATCT2 Terminal Control Table-1 |
| More : + |
|Terminal Name. . . . . . . . : T1IP |
|Group Name . . . . . . . . . : ALSKIX |
|Network Name . . . . . . . . : CICSV123 |
| |
|Terminal Type. . . . . . . . : P (V=3270 terminal, J=3270J terminal |
| P=3270 printer, Q=3270J printer |
| S=Sequential, A=3270 3151-PC) |
| |
|Model. . . . . . . . . . . . : N (Y or N) |
| |
|Associated Printer . . . . . : |
| |
|Printer Close Mode . . . . . : (T=end of task |
| F=end of file, or space) |
| |
|Initial Transaction Required : N (Y or N) |
|Remote System. . . . . . . . : P1IP |
|Remote Terminal Name . . . . : |
|Description. . . . . . . . . : Client Printer via User Exit 21 |
| |
|Enter F1=Help F3=Exit F8=Fwd F10=Actions F12=Cancel |
+--------------------------------------------------------------------------------+
Where:
Terminal Name
| Must match the name on the CICSPRNT /n=xxxx command
| Terminal Type
| Set to P for printer (Q for a DBCS printer)
| Remote System
| Must match the RemoteSystemID parameter in user exit 21
| Remote Terminal Name
| If left blank, this field assumes the Terminal Name entry.
(in this example, T1IP).
| Autoconnect
| On page 2 of the TCT you must specify Autoconnect=No.
|
For more information about resource definition in CICS for OS/2, refer to
the
CICS for OS/2 Customization
book.
In the client initialization file,
the applid on the Client parameter
must match the RemoteApplid specified in user exit 21.
For example:
Client = Prt1TCP
To start the printer emulator for the example configuration
defined in this section, you would enter the following command:
CICSPRNT /s=CICSOS2 /n=T1IP /f=c:\print.fil
Where:
s=CICSOS2 | The name of the server
| n=T1IP | Matches the terminal name as defined in
the TCT (see Figure 33).
| f=print.fil
| Specifies print.fil as the file to which print requests
are appended.
|
The following table summarizes the printer definitions that must
match.
Table 18. Matching definitions: CICS 3270 Client printer emulator
CICSCLI.INI
| User Exit 21
| CICS for OS/2
| CICSPRNT
| Example
|
Client=applid
| RemoteApplid
|
|
| Prt1TCP
|
| RemoteSystemID
| Remote System
|
| P1IP
|
|
| Terminal Name
| Netname
| T1IP
|
For multiple printers on a CICS for OS/2 server, you must have one
CICS for OS/2 TCT definition for each
printer you want to install.
However, you may want to have multiple client
printers, but do not want to define multiple TCT entries.
For this purpose,
you can use user exit 22
(Terminal Definition Autoinstall).
By specifying a modelname rather
than a netname on the CICSPRNT command, you can select a model within
user exit 22 to match a model
on the CICS for OS/2 server.
Therefore you can
predefine the remote terminal name and the remote system name of the
printer.
For more information, refer to
the
CICS for OS/2 Customization
book.
The CICSTERP command of CICS Client for DOS
provides a dual 3270 screen terminal emulator
and 3270 printer terminal emulator.
CICSTERP combines the functions provided by the CICSTERM and CICSPRNT
commands, which are available separately.
You can start an emulator session, specify terminal emulator
characteristics, and the names
of the keyboard mapping and color mapping files.
The CICSTERP command detects
whether the hardware on which the
client is running is enabled for double-byte character set (DBCS)
display.
If it is, the emulator can display DBCS characters.
Note: Some uses of servers and protocols require a model terminal
definition for the emulator that explicitly specifies that the client
wants to display DBCS.
You use the CICSTERP command to:
- Start a 3270 terminal and print terminal emulator (/s or /r
parameter)
- Specify the initial transaction (/t parameter)
- Specify the name of the keyboard mapping file (/k parameter)
- Specify the name of the color mapping file (/c parameter)
- Define the 3270 terminal emulator characteristics (/n and /m
parameters)
- Define the 3270 printer emulator characteristics (/l and /o
parameters)
- Determine the print file processing (/p parameter)
- Specify a file to which print files are appended (/f parameter)
You issue the CICSTERP command once with all the
parameters you require.
The following is an example of a CICSTERP command:
CICSTERP /s=CICSOS2 /t=CESN /k=mykeys.ini /c=mycols.ini
/n=cicsv123 /f=clprint.txt /q
In this example:
- /s=CICSOS2
- Specifies that a 3270 terminal emulator is started for the server
CICSOS2.
- /t=CESN
- Specifies that the initial transaction is CESN.
- /k=mykeys.ini
- Specifies that the keyboard mapping file is named as MYKEYS.INI.
- /c=mycols.ini
- Specifies that the color mapping file is named as MYCOLS.INI.
- /n=cicsv123
- Specifies that the 3270 terminal emulator characteristics are
defined by the terminal definition cicsv123.
- /f=clprint.txt
- Specifies that the print file will be appended to the file
CLPRINT.TXT.
- /q
- Specifies that the display of messages output by the command is
disabled.
All parameters of CICSTERP are optional.
That is, you can enter the CICSTERP command without any parameters,
and defaults are taken from the client initialization file.
Full details of the parameters are given in "CICSTERP command reference".
To stop a terminal emulator, enter the string
specified by TerminalExit in the client initialization file.
This is EXIT by default.
For an explanation of syntax diagrams, see "Command syntax".

The options are:
/c=colorfile
| Identifies the name of a color mapping file (see "Customizing the screen colors") to be used with the emulator.
If this parameter is omitted, the environment variable CICSCOL is
assumed to identify the color mapping file.
If CICSCOL is not defined, a filename of CICSCOL.INI in the current
directory is assumed.
If the parameter is specified as /c=, (that is, the color
mapping filename is omitted), the emulator runs without any color
definitions.
| /f=printfile
| 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 surrounded by double quotes (").
Any double quotes within the name of the file must be entered as
backslash double quote (\").
If neither of the /f or /p parameters is provided,
the PrintCommand or PrintFile
parameter in the client initialization file defines the command, file, or default action
to take with print requests.
| /k=keyfile
| Identifies the name of a keyboard mapping file (see "Keyboard mapping file syntax")
to be used with the emulator.
If this parameter is omitted, the environment variable
CICSKEY is assumed to identify the key mapping file.
If CICSKEY is not defined, a filename of CICSKEY.INI
in the current directory is assumed.
| /m=modelname
| Specifies the name of a model terminal definition, as known
at the server to which the screen terminal emulator is to connect, to be used to
define the terminal characteristics.
If neither this parameter nor
/n=netname is specified, any ModelTerm value from the
client initialization file is used.
If no ModelTerm value
has been specified in the initialization file,
the server's default terminal definition is assumed.
If the parameter is specified as /m= (that is, the modelname
is omitted), any ModelTerm value specified in the initialization
file is ignored, and the server's default terminal definition
is assumed.
This option is case-sensitive.
| /n=netname
| Specifies the name of a particular terminal definition at the
server that this screen terminal emulator is to be installed as.
The precise
interpretation of netname varies between servers, for example, on
CICS for OS/2 it references a termid defined in the CICS tables, on
CICS for AIX it is a netname.
This option is case-sensitive.
| /l=modelname
| Specifies the name of a model terminal definition, as known
at the server to which the printer terminal emulator is to connect, to be used to
define the terminal characteristics.
This option is case-sensitive.
| /o=netname
| Specifies the name of a particular terminal definition at the
server that this printer terminal emulator is to be installed as.
The precise
interpretation of netname varies between servers, for example, on
CICS for OS/2 it references a termid defined in the CICS tables, on
CICS for AIX it is a netname.
This option is case-sensitive.
| /p=printcmd
| Specifies an operating system command used to process the
temporary print file generated when print requests are received by the
terminal emulator.
If the command contains embedded blanks, then
the command must be surrounded by double quotes (").
Any double quotes within
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, file, or default action to take with
print requests.
The temporary print
file is post-processed by appending
the
filename to the command, and executing the resultant command.
Thus print output may simply be copied to a local printer, copied into
a permanent file, processed further for inclusion into a document,
and so on.
If the temporary file is to be processed by a print command, the
command is responsible for deleting the temporary file.
| /q
| Disables the display of all messages output by the command.
| /s=servername or /r=servername
| Specifies the name of the server that the terminal emulator is to
be connected to.
This servername must correspond to an entry in the
client initialization file.
You can specify /s, or /r, but not both.
If neither parameter is specified, the first server entry
in the initialization file is used.
If the parameter is specified as /s or /r (that is, no
servername is provided) then, if the initialization file
identifies more than one potential server to which the client can
connect, the user is prompted to select from a list
of available servers.
These prompts are generated even if the /q parameter is
specified.
If there is only one potential server identified in the
initialization
file, that server is used and the user is not prompted.
| /t=initialtransid
| Identifies the initial transaction to be invoked for this
terminal.
If this option is omitted, any initial transaction specified
in the client initialization file is run (this applies to screen terminal emulators only).
The string may be up to 128 characters long, specifying both a
transaction name, and parameters to be passed to the transaction.
The transaction name is the first four characters or the characters
up to the first blank in the string.
The rest of the string is the parameter data.
If the parameter is specified as /t= (that is, the
initialtransid is omitted), any initial transaction specified in
the initialization file is ignored.
This option is case-sensitive.
Note: Be careful that transactions that you specify either here or in the
client initialization file do not require terminal input to complete.
| /w
| Prompts the user, before the command completes,
to press the Enter key, to confirm that
messages
output to the screen (both informational and error) have been
read.
| /?
| Causes the parameter syntax to be listed; any other options
specified are ignored.
|
For CICSTERP,
the emulator status line contains the following:
1B ssss tttt
where ssss is the screen terminal termid and
tttt is the printer terminal termid.
If DOS is unable to write to the print output device and displays a
message with the options Abort, Retry, Ignore, Fail you should
correct the fault and select Retry, or select Fail.
If you select Abort,
CICSTERP terminates and the system is left in an undefined state.
In this case, you may need to restart the CICS client machine.
CICS Client for Windows, CICS Client for Windows 95, and CICS Client for Windows NT
provide a means of selecting and sizing fonts on their
terminal emulators.
The terminal emulators provide a menu bar with File and
Settings menus.
The commands on the File menu are:
Print
|
Prints the emulator screen.
This has the same effect as pressing
the Print Screen key.
| Exit
| Stops the terminal emulator.
|
The commands on the Settings menu are:
Font
|
Opens a standard Windows dialog box that allows you to select any of the
fixed-pitch fonts installed on your system.
Select a font, font style, and size, and then select OK.
The terminal window is then resized according to your font selection.
| Autosize
|
Specifies that the size of TrueType fonts is adjusted according to the
size of the terminal window.
That is, when you maximize, minimize, or drag the
borders to resize the window, the font is resized to match the new window
size.
This command has no effect if the current font is not a TrueType font.
| Save on Exit
|
Specifies that the current font and terminal window position are
saved when you close the terminal window.
When you select Save on Exit
the settings are saved in the CICSTERM.INI file, in the
following directory:
Client platform
| Directory
| Windows NT
| c:\winnt35
| Windows 95
| c:\windows
| WIN-OS2
| c:\os2\mdos\winos2
| Windows 3.1
| c:\windows
|
The CICSTERM.INI file is not erased when you delete a CICS Client
installation.
Therefore, when you re-install the Client, the settings from the old
CICSTERM.INI file are used by the emulator.
CICSTERM.INI is initially installed in the \cicscli\bin
directory
|
![[Help]](../help.gif)
[
IBM home page |
(C) |
(TM)
]
© IBM Corporation 1994, 1997. All Rights Reserved
|