cicscli command reference

This section provides a reference guide for the cicscli command.

The dash (-) may be replaced with the forward slash (⁄) character. 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.

cicscli [[-s[=servername]]|[-x[=servername]]|[-i[=servername]]|[-j]|[-y] ]
[-l] 
[[-d[=nnn] [-b] [-m[=components]]]|-o] 
[-n|-e]
[-c=servername [-u[=userid]] [-p[=password]]]
[-r [-a<parameter1> [-a<parameter2>...]][-w|-q]
[-v]
[-y|-j]
The options are:
-b
Uses memory mapped trace. This improves performance significantly compared with standard file I/O. This option is valid only if specified when tracing is switched on, and requires wrapping trace to be enabled. See Starting client tracing for more details.
-c=servername
Identifies the name of the server to which security information in the form of a user ID and password is to be associated. Some CICS® servers require the user to provide security information to the server before interacting with the server. The Client daemon prompts the user at the workstation for a user ID and password, unless you provide them by using the -u and -p options.
-d=[nnn]
Starts debug tracing for the Client daemon. If tracing is required while the Client daemon 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 value is 512 bytes. If you are producing a trace for your support organization, set -d to at least 1000 to ensure that all relevant data is included.

The Client daemon writes trace entries to the cicscli.bin file in the <install_path>\bin subdirectory. New trace entries overwrite any existing entries in the trace file. If required, make a backup copy of the old trace file before you start tracing.

Use the cicsftrc utility to format the trace file. The resulting file, cicscli.trc, is an ASCII file that you can read with a text editor. For more information see Formatting the binary trace file.

-e
Enables the display of Client daemon error and security messages in pop-up windows.
-i
Shuts down the Client daemon immediately. The Client daemon does not wait for outstanding units of work to complete. Stopping the Client daemon in this way can result in a loss of data at connected servers. To stop the Client daemon normally, use the -x option.
-j
Shuts down the Client daemon immediately and then restarts it.

A restart involves shutting down the Client daemon, waiting for it to shut down, and then starting it again. cicscli -j is equivalent to cicscli -i followed by cicscli -s. Server connections are not re-established when the Client daemon is restarted.

The Client daemon does not wait for units of work to complete. This might result in loss of data. To restart the Client daemon normally, use the -y option.

-l
Displays a list of all connected servers. For each server, the netname of the server as it is known to the Client daemon is also displayed, as well as the state of the connection to the server and the connection protocol.
-m=[components]
Specifies a comma-separated list of identifiers for components that will be traced when tracing starts. You can specify any of the following components:
ALL
All components. Use it if performance allows, and consider using the binary formatting tool to filter information. See Formatting the binary trace file for details.
API.1
The client API layer (level 1). This traces the boundary between the Client application and the Client daemon.
API.2
The client API layer (level 1 and 2). This gives level 1 plus additional parameter tracing.
API
Synonymous with API.1.
CCL
The Client daemon.
CPP
The C++ class libraries.
CLI
The cicscli command interface.
DEF
The default components, that is the API, CCL, and DRV.1 components.
DRV
Synonymous with DRV.1.
DRV.1
Protocol driver tracing level 1. This traces data sent and received and provides supplementary information about failures.
DRV.2
Protocol driver tracing level 2. This traces internal flows through the protocol drivers and interactions with other software components. It is currently supported only by the CCLTCP62 protocol driver.
EMU
cicsterm and cicsprnt emulators.
LMG
The Workload Manager.
SER
When SER is included in the trace component list for CICS Universal Client the SER trace component will not be activated, it will be ignored and treated as an invalid component.
TRN
The TRN component traces the internal interprocess transport between Client processes. Use it if entries in the Client log refer to functions such as FaarqGetMsg, FaarqPutMsg, or FaarqStart. TRN is the most verbose tracing component.
  • If you are not sure whether a problem is inside the Client daemon, and you want to minimize the impact on performance, specify the DRV.1 and API components. You can also specify these components to help to determine which product is causing the system to lock up.
  • Specify the API and CCL components if you believe that the problem is within the Client daemon.
  • If you want to diagnose an application error, and are not interested in the Client daemon, specify only the API.2 and CPP tracepoints. The trace contains less information, and is easier to understand.
The -m option does not start tracing in the Client daemon; it simply specifies the components to trace. You cannot use -m while the Client daemon is not running, so in this case you must specify the -s option as well. Consider using wrapping trace (-b) for improved performance:
cicscli -m=component_list -b

If you specify -m with no parameters, a list of the possible component identifiers is displayed, with an 'x' beside each component that it is currently enabled for tracing.

You can also specify settings for trace components using the Configuration Tool (see Trace settings in the Configuration chapter for details). Any component tracing specified using cicscli overrides that specified using the Configuration Tool. If component tracing is not specified either by the cicscli command or by using the Configuration Tool, a default set of components is traced, namely: DRV.1, CCL, and API. Any component tracing specified using the Configuration Tool overrides the default set of components.

Note that the cicscli -d=nnn command is used to set the maximum size of the data areas to be traced. The trace data might be truncated if you set nnn lower than the size of data expected.

-n
Disables the display of Client daemon error and security messages in pop-up windows.

Any messages that would have been logged are still logged.

-o
Stops tracing if it is already active.
-p=password
Sets the current password to be used when accessing the server specified by the -c option. (Or by the -s option.) This password is used if the server requires a password (and user ID) before running transactions on the client’s behalf.

For ECI applications, any user ID and password specified in the ECI parameter block override values set by 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 produced by the cicscli command.
-s
Starts the Client daemon. No attempt is made to initiate communication with a server unless -s=servername is specified. In this case, the Client daemon also connects to the server using information specified in the configuration file. The servername must correspond to an entry in the configuration file.
-u=userid
Sets the current user ID to be used when accessing the server specified by the -c option. (Or by the -s option.) This user ID is used if the server requires a user ID (and password) before running transactions for the Client daemon.

For ECI applications, any user ID and password specified in the ECI parameter block override values set by the cicscli command.

Specifying -u or -u= (that is, no user ID is specified) resets the associated user ID to a null value.

-v
Displays information about the version and build level of the Client daemon.
-w
Prompts the user, before the command completes, to press the Enter key, to confirm that information and error messages output to the screen have been read.
-x
Shuts down the Client daemon normally. If -x=servername is specified, the connection to the server is terminated when all outstanding units of work on the specified server have completed. If other server connections are active, these remain unchanged.

If -x is specified without a server name, the Client daemon 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 daemon.

-y
Restarts the Client daemon normally.

A restart involves shutting down the Client daemon, waiting for it to shut down, and then starting it up again. cicscli -y is equivalent to cicscli -x followed by cicscli -s. Server connections are not reestablished when the Client daemon is restarted.

Using -y is the preferred way of restarting the Client daemon.

-?
Causes the command syntax to be displayed.