Using vwtool to troubleshoot FileNet P8 Process Engine issues

The vwtool options that are often used in troubleshooting are config, count, loadstatus and its complementary resetloadstatus option, schemastatus, wobquery, and trace.

The config option
This option displays configuration information for the selected isolated region. This information consists of the following:

• Information about the latest workspace.
• Process Engine-wide flag settings.
• Statistics snapshot interval.

You can use the config option to map a queue's logical name (the user-defined name of the queue) to its physical database table name (the unique, system-defined name of the database table that contains the queue). For example, open a command prompt window on the Content Platform Engine server and enter:

vwtool
vwtool:1 > hardcopy C:\fnsw_loc\tmp\IR100.config.out
vwtool:1 > config
vwtool:1 > quit

The count option
This option returns a count of the number of work items in a specified queue or roster in the current isolated region. Alternatively, using the asterisk (*) parameter, you can get a count of all work items in all queues and in all rosters. For example, open a command prompt on the Content Platform Engine server and enter:

vwtool
vwtool:1 > hardcopy C:\fnsw_loc\tmp\IR100.counts.out
vwtool:1 > count <queue_or_roster_name>
vwtool:1 > count *
vwtool:1 > quit

The loadstatus and reseloadstatus options
These options provide statistics regarding the load being placed on the server for all isolated regions. Process Engine processing requests can result in errors when adequate system resources are not available. The requests are automatically retried, but these retries can result in a loss of performance or other issues. Use loadstatus periodically to understand the rate at which requests or errors normally occur on your system.

Once you have determined this rate, run loadstatus when response time is slow to determine if any of the error counters are increasing at a rapid rate. The rate of processing, type of processing, and any errors that have occurred indicate the system resources that might need additional allocations.

Use the resetloadstatus option to reset the loadstatus counts to zero. For example, open a command prompt on the Content Platform Engine server and enter:

vwtool
vwtool:1 > hardcopy C:\fnsw_loc\tmp\IR100.loadstats.out
vwtool:1 > loadstatus
vwtool:1 > resetloadstatus
vwtool:1 > quit

The schemastatus option
This option indicates whether any activity that modifies the workflow database (such as initialization or transfer) is in progress in the current/selected isolated region. If any such activity is in progress, schemastatus displays the following information for each activity:

• Type of activity
• Who started the activity
• IP address of start location
• Elapsed time

For example, open a command prompt on the Content Platform Engine server and enter:

vwtool
vwtool:1 > hardcopy C:\fnsw_loc\tmp\IR100.schemastats.out
vwtool:1 > schemastatus
vwtool:1 > quit

The wobquery option
This option outputs the attributes of work items in a specified queue or roster in the current isolated region, and is useful for obtaining the work object number or queue name for use in subsequent vwtool commands. When troubleshooting, it is particularly useful for capturing information on a specific problematic work item.

The syntax and optional parameters vary depending on whether you query a queue or roster, and whether your query is selective or not. For example, to run a non-selective query on a queue or roster, open a command prompt window on the Content Platform Engine server and enter:

vwtool
vwtool:1 > hardcopy C:\fnsw_loc\tmp\IR100.wobquery.out
vwtool:1 > wobquery <queue_or_roster_name> n display size verbose
vwtool:1 > quit

The trace option
The trace option allows you to display and set the tracing options within Process Engine and is mainly intended for IBM Engineering use. Process Engine traces provide information on server processing including Remote Procedure Calls (RPCs), DBI timings, DBI database access, Object Service usage, network connections, application functions, vwisi processes, and log manager processes. If a Process Engine issue is reproducible, trace data is very useful to Engineering while troubleshooting an issue if you can enable the appropriate PE traces and then recreate the issue.

The tracing process does impact server performance, so be sure to use it only when troubleshooting a specific issue. The trace file can also grow quickly and must be monitored to ensure sufficient disk space remains available. Once the issue has been captured in a trace, the tracing should be stopped as described in the example below.

The trace option does require some advance setup in anticipation of capturing information regarding the issue under investigation. This setup includes specifying the types of activity that should be captured. For example, open a command prompt on the Content Platform Engine server and enter:

vwtool
<vwtool:1> trace
Trace saved via: LogFile=F, Memory=F
Trace content options: External=F, Internal=F, Object Service=F,
Database access=F, Database time=F, ISI=F, Log=F,
Network=F, Notification=F, Application=F, Java calls=F,
SEC calls=F, WorkFlow Termination=F, Transfer=F,
StartStop=F, Rules=F

Change tracing options? (y/CR=n): y

Enter new save options (^C to exit):
Save via log file? (y/CR=n): y
Trace data will be appended to file C:\fnsw_loc\tmp\vwtrace'
Save via memory? (y/CR=n):

Enter new content options:
Trace external RPCs? (y/CR=n):
Trace internal RPCs? (y/CR=n):
Trace Object Service RPCs? (y/CR=n):
Trace database access? (y/CR=n):
Trace database timings? (y/CR=n):
Trace Instruction Sheet Interpreter? (y/CR=n):
Trace Log Manager? (y/CR=n):
Trace network connections? (y/CR=n):
Trace email notification? (y/CR=n):
Trace application functions? (y/CR=n):
Trace Java calls via VWJs? (y/CR=n):
Trace SEC calls? (y/CR=n):
Trace Workflow termination? (y/CR=n):
Trace Transfer? (y/CR=n):
Trace StartStop? (y/CR=n):
Trace Rules? (y/CR=n):
<vwtool:1> quit

By selecting the appropriate options, detailed output is generated, documenting the specified activity. The tracing continues until it is stopped. To stop the trace, open a command prompt and enter:

vwtool

From the vwtool prompt enter trace:

<vwtool:1> trace
Trace saved via: LogFile=T, Memory=F
Trace content options: External=F, Internal=F, Object Service=F,
Database access=F, Database time=F, ISI=F, Log=F,
Network=F, Notification=F, Application=F, Java calls=T,
SEC calls=F, WorkFlow Termination=F, Transfer=F,
StartStop=F, Rules=F

Change tracing options? (y/CR=n): y

Enter new save options (^C to exit):
Save via log file? (y/CR=n): n
Save via memory? (y/CR=n): n
<vwtool:1> quit


Data to collect if uploading to an IBM Support PMR: All trace files (ex: \fnsw_loc\tmp\vwtrace) and/or the hardcopy file you specified with the other options. Also provide the PE elog (\fnsw_loc\logs\elogs\elog<yyyymmdd>) and any core files that may have been produced. For Windows servers, include the Application and System Event Logs. Include a description of any known circumstances leading up to the issue and document the time of the occurrence.

For more information: https://www.ibm.com/docs/en/filenet-p8-platform/5.5.x?topic=tools-vwtool