xcli command syntax

You must be the TWS_user to run the command.

Syntax

xcli

-snap <snap_file>
   { -p <program> | -s <segment> }
   [ -descr <description> ]
   [ -clean ]
   [ -P <product> ]

   -format <snap_file>
   -d <symbols_database>
   [ -full ]
   [ -noHeader ]
   [ -standard [ -source ] | -xml | -csv ]

   -query [ -p <program> | -s <segment> ] [-P <product> ]

-active { y | n }
   { -p <program> | -s <segment> | -all }
   [ -P <product> ]

   -level <level>
   { -p <program> | -s <segment> | -all }
   [ -P <product> ]

   -filter <filter_file>
   { -p <program> | -s <segment> }
   [ -P <product> ]

   -createFilter <filter_file> -d<symbols_database>
   [ -add_all |
   -add_comp <component> | -remove_comp <component> |
   -add_func <function_name> | -remove_func <function_name> |
   -add_func_id <function_ID> | -remove_func_id <function_ID> |
   -add_func_id_range <from> <to> | -remove_func_id_range <from> <to> |
   -add_filter <filter_file> | -remove_filter <filter_file> ] ...

   -modifyFilter<filter_file> -d<symbols_database>
   [ -add_all | -remove_all
   -add_comp <component> | -remove_comp <component> |
   -add_func <function_name> | -remove_func <function_name> |
   -add_func_id <function_ID> | -remove_func_id <function_ID> |
   -add_func_id_range <from> <to> | -remove_func_id_range <from> <to> |
   -add_filter <filter_file> | -remove_filter <filter_file> ] ...

-clean

   -config [<config_file> ]

Arguments

-snap <snap_file>

Saves a snapshot of part of the shared memory to the indicated file. For the snapshot, you can use the following parameters:

{ -p <program> | -s <segment> }

Define if the snapshot is for either a program or a segment. If it is made for a program which shares a segment with other programs, the whole segment is snapped, but the header information shows which program it was snapped for. See also Selecting programs, segments, and products.

[ -descr <description> ]

Supply a description for the snapshot. Surround it with double quotation marks if it contains spaces.

[ -clean ]

Optionally clear the entire segment memory after taking the snapshot. If any process is still using the memory, the clean operation cannot be performed and a warning message is given.

Note: If your snapshot is of a program, this option clears the memory for all traces in the segment for which the program is configured, including those of any other programs that have been configured to write to it.

[ -P <product >]

See Selecting programs, segments, and products.

The snap file header information is as follows:

	"Snap information:
   "  Product:         <product>
   "  Description:     <description>
   "  Snap platform:   <platform>
   "  Snap time (GMT): <time>
   "  Snap program:    <program>
   "  Snap segment:    <segment>
   "     Segment size: <size>(Kb)
   "     Segment use:  <percent_used>											

-format <snap_file>

Formats the supplied snapshot file for the standard output. The formatting options are:

-d <symbols_database>

Supply the name of the symbols database to use for the formatting. The database must be either the same version as the instance of IBM Workload Scheduler from which the snap was captured (ideally), or a later version. The default symbols database is xdb.dat.

[ -full ]

If the snap was taken of a single program in a multi-program segment, use this option to send the full set of traces (all programs) to the standard output, rather than that of the single program as determined by the header information in the snap file.

[ -noHeader ]

Use this to suppress the output of the header information. The standard output then just consists of trace messages, which is more acceptable as input to an analysis program.

[ -standard [ -source ] | -xml | -csv ]

Define the formatting of the traces. If you have selected -standard, use the optional parameter -source to add information about the source file and line number. This source information is automatically included in the -xml and -csv options. If you supply none of these, the format defaults to -standard.

-query

Outputs the enablement or activation state of a program or segment. Without parameters, this option displays information about the entire configuration to the standard output. The parameters are:

[ -p <program> | -s <segment> ]

Optionally define whether the query is for a specific program or a specific segment. See also Selecting programs, segments, and products.

[ -P <product> ]

See Selecting programs, segments, and products.

-active { y | n }

Activates (y) or deactivates (n) a program or segment in memory, or all programs and segments. The parameters are as follows:

{ -p <program> | -s <segment> | -all }

Activate either a specific program or a specific segment, or all programs and segments. See also Selecting programs, segments, and products.

[ -P <product> ]

See Selecting programs, segments, and products.

-level <level>

Sets the tracing level for a program or segment in memory. Specify one of the following level codes:

Level	Description
10	Unrecoverable
20	Error
30	Warning
40	Informational
50	Debug minimum
60	Debug medium
70	Debug maximum
80	Function entry and exit

For example, to trace only unrecoverable failures and errors, supply "20".

The parameters are as follows:

{ -p<program> | -s<segment> | -all }

Set the level for either a specific program or a specific segment, or all programs and segments. See also Selecting programs, segments, and products.

[ -P<product> ]

See Selecting programs, segments, and products.

-filter <filter_file>

Applies a new filter file for a program or segment in shared memory. The parameters are as follows:

{ -p <program> | -s <segment> }

Determine the filter file to be used for either a program or a segment. See also Selecting programs, segments, and products.

[ -P <product> ]

See Selecting programs, segments, and products.

default

The filter file is created using the -createFilter option. In this option (and the associated -modifyFilter option) you specify any components and functions you want to include or exclude from the tracing (see below for more details). This information is written in the filter file as a list of all functions in the symbols database (by ID) with a bit set to indicate whether they are to be included or excluded. The default symbols database is xdb.dat.

Any filter files defined in the configuration file are loaded into shared memory at initialization. If you use this option, the shared memory area is overwritten with the new contents. If the new filter file has been created using a different symbols database than the original file, a warning is given, because it is advisable to use the same symbols database when creating the new filter file.

The default filter file supplied with the product is set to not trace the 5% most-used routines, on the basis that the most-used routines are less likely to create problems because they are well tried and tested.

-createFilter <filter_file>

Creates the filter file named in the parameter. The file must not already exist. There is no facility to view a filter file, so use meaningful names and maintain your own documentation of the contents of each filter file.

To populate the file supply one or more of the following parameters. If you add an item, its traces will be saved; if you remove an item, its traces will not be saved. By default, all components and functions are removed.

-d <symbols_database>

Identify the symbols database to use to verify the component names, and the function names and IDs.

-add_all

Add all components and functions to the filter file. Use this with one of the -remove options to create an exclusive "all except ..." filter.

-add_comp <component> | -remove_comp <component>

Add a component to the file or remove one that has already been added. For example, you could add all components using -add_all and then remove just one, which would be easier than adding all of the required components individually. Discover component names by viewing a formatted snapshot.

-add_func <function_name> | -remove_func <function_name>

Add a function to the file or remove one that has already been added. For example, you could add a component using -add_comp and then remove one of its functions, which would be easier than adding all of the required functions individually. Discover function names by viewing a formatted snapshot.

-add_func_id <function_ID> | -remove_func_id <function_ID>

Adds a function to the file by ID, or removes one that has already been added. For example, you could add a component using -add_comp and then remove one of its functions, which would be easier than adding all of the required functions individually. A function ID is a sequential number allocated to a function when the product was built, and stored in the symbols database. Discover function IDs by viewing a formatted snapshot.

-add_func_id_range <from> <to> | -remove_func_id_range <from> <to> |

Adds a range of functions to the file by ID or removes a range of functions that have been already added. Discover function IDs by viewing a formatted snapshot.

-add_filter <filter_file> | -remove_filter <filter_file>

Adds or removes the contents of an existing (different) filter file, as follows:

Adding a filter file

If you add a filter file, the items in that filter file which are set to be filtered (traced) are added to whatever other filter criteria you might have set.

Removing a filter file

If you remove a filter file, the items in the filter file which are set to be filtered (traced) are removed from whatever other filter criteria you might have set.

For example, you might create a filter file that configures the tracing of the communications functions. You could then add this set of functions to your filter set in one command, or remove them, depending on whether you think the communications are part of the problem you are trying to solve.

The add and remove actions are processed in the order you submit them. Thus if you add a function ID, and then remove a range that includes that ID it is removed from the criteria. But if you remove the range, and then add the ID, it is added to the criteria.

-modifyFilter <filter_file>

Modifies the existing filter file named in the parameter.

This subcommand takes all of the parameters used in the -addFilter subcommand in the same way, with the addition of the following action:

-remove_all

Removes all components and functions from the filter file. Use this with one of the -add options to create an inclusive "all of the following" filter.

-clean

On UNIX™ operating systems only, use this to delete the shared memory segments after you have modified and saved the configuration file, and stopped the product. If a segment is in use, it is marked for deletion and will be automatically deleted when no longer in use.

-config [<config_file> ]

This initializes the memory. It is run automatically when the IBM Workload Scheduler engine is restarted, using the default configuration file ./xtrace.ini. In normal circumstances, you never need to run this manually. If you believe that the shared memory is corrupted, it is better to restart the product, which automatically re-initializes the memory.