Configuring Trace and Debug Settings

This chapter discusses how to:

Set up the PeopleCode Debugger.
Configure PeopleCode trace.
Configure SQL trace.

Setting Up the PeopleCode Debugger

This section discusses how to:

Debug for a two-tier connection.
Debug for a three-tier connection.
Use the PeopleCode Debugger.

Note. PeopleCode debugging is not supported on z/OS.

You can debug the PeopleCode program configurations of a two-tier connection to the database or a three-tier connection to the database.

Note. When you debug PeopleCode with an application server, PeopleSoft Application Designer should be run in three-tier mode. PeopleCode debugging by using a two-tier PSIDE and an application server is not supported on multi-homed (multiple Internet Protocol address) workstations.

Debugging for a Two-Tier Connection

Debugging in two-tier connections involves connecting directly to the database, not through the application server. Use this method to debug two-tier Windows applications.

Note. By default, the port number that the PeopleCode debugger uses is 9500. Unless this port number is being used by another application, you do not need to alter any environment settings, and after you sign on to the database, you are able to debug PeopleCode.

If you need to change the PeopleCode Debugger port settings, complete the following procedure.

To change the default PSDBGSRV listener port number:

Open PeopleSoft Configuration Manager.
Select the Trace tab.
Locate the PeopleCode Debugger section, and make sure that the default value for the Local PSDBGSRV Listener Port is suitable for the system.

For example, make sure that no other applications are configured to listen on the default port number (9500). If so, you must assign a port number that is not being used.

Note. If you're using a personal firewall, you must configure it to enable data packets to flow through the PSDBGSRV listener port. If you can't configure your firewall appropriately, you must shut it down while performing PeopleCode debugging.

Debugging for a Three-Tier Connection

Use three-tier debugging to debug three-tier Windows applications and PeopleSoft Internet Architecture (PIA) applications. For three-tier debugging, use PSADMIN to ensure that the following items are set:

The appropriate PSDBGSRV listener port is specified in the PeopleCode Debugger section of PSADMIN.
At least two PSAPPSRV processes are configured to boot in the domain with the service timeout parameter set to zero.
Enter y for yes at the Enable PSDBGSRV Server Process prompt at the end of the PSADMIN interface.

Debugging on a Multi-Homed System

If you're debugging on a multi-homed (multiple IP address) system, you must explicitly specify an IP address in the Workstation Listener section of the PSADMIN configuration, rather than %PS_MACH%. The address you specify must be one by which the application server identifies the machine on which you're doing the debugging. This ensures that the workstation listener monitors requests from the correct location.

See Workstation Listener Options.

Setting the PSDBGSRV Listener Port

In the PeopleCode Debugger section of PSADMIN make sure that the value that is assigned to the PSDBGSRV listener port is not already in use by another application or listener on the application server. The default value is 9500. If the default is not acceptable, assign a suitable value to the parameter. If it is acceptable, no changes are required.

For example,

Values for config section - PeopleCode Debugger
    PSDBGSRV Listener Port=9500

Do you want to change any values (y/n)? [n]:

Consider the following when debugging PeopleCode:

If multiple application server domains are running on a single, physical machine, each domain needs to use different debugging port numbers.

Otherwise, there is contention for the PSDBGSRV listener port value. This is the same principle that requires each application server domain on a server to have unique workstation listener port numbers.
When you are not debugging, turn off (set to 0) the Enable Debugging parameter.

The debugging mode results in an unavoidable amount of overhead, which can degrade performance.
Regarding performance, do not perform debugging on a production domain.

Debugging should be performed on a designated testing domain only.

Enabling Multiple PSAPPSRV Server Processes

The minimum requirements for PeopleCode debugging are:

Two PSAPPSRV server processes are configured to boot in the domain.
The Service Timeout value in the PSAPPSRV configuration section must be set to 0.

For the debugger to work, it has to run in parallel with the application that it's debugging. Suppose that the domain has only one PSAPPSRV server process running. In this case, the PSAPPSRV can process the requests of only one component at a time, and therefore debugging is not possible. Debugging involves two items, the debugger (PSDBGSRV) and the PSAPPSRV server process that is running the application PeopleCode.

Provided that you have two PSAPPSRV server processes configured; one PSAPPSRV handles the debugger program, while the other handles the application that you're stepping through with the debugger. In this case, the two programs run in parallel, which enables interactive debugging.

The configuration templates that PeopleSoft delivers all have at least two PSAPPSRV processes. However, if you are using a custom template, make sure that you configure the domain to start two PSAPPSRV processes prior to debugging. To do this, in PSADMIN set the Min Instances parameter in the PSAPPSRV section to 2.

You must set the Service Timeout parameter for PSAPPSRV to 0. Disabling service timeouts prevents the application server processes from timing out if you stop at a particular point in the program while debugging.

The following example shows a sample PSAPPSRV section properly configured for debugging PeopleCode:

Values for config section - PSAPPSRV
    Min Instances=2
    Max Instances=2
    Service Timeout=0
    Recycle Count=0
    Allowed Consec Service Failures=0
    Max Fetch Size=5000

Do you want to change any values (y/n)? [n]:

When configuring the PeopleCode debugger:

PeopleSoft recommends using the Developer configuration template because this template, by default, provides two PSAPPSRV server processes and has service timeout set to zero.
PeopleSoft recommends using a simple configuration where you are assured that the server that PeopleSoft Application Designer connects to is the same server that the application you are debugging is running on.

Note. If you do not set the settings for PSAPPSRV correctly (at least two PSAPPSRV processes with the Service Timeout value set to 0), PSADMIN automatically sets these values to comply with the minimum requirements when you enable PeopleCode Debugging (as discussed in the next section).

Requesting a PSDBGSRV Server Process

After you specify the settings by using PSADMIN, the system prompts you with a series of options, such as setting up messaging server processes, enabling BEA JOLT, and so on.

When you're prompted to enable the PSDBGSRV, enter y. Y appears in the Developer template by default.

Using the PeopleCode Debugger

After the system is configured properly, using the PeopleCode debugger is just a matter of signing on to the PeopleSoft system and entering the PeopleCode Debugger mode in PeopleSoft Application Designer.

Note. You must use a unique user ID when you're performing PeopleCode debugging, as opposed to using a shared user ID, such as those that PeopleSoft delivers, for example QEDMO, PS, or VP1. Shared IDs are likely to be used by others that are connecting to the same test database, which can affect debugging.

Configuring PeopleCode Trace

Select PeopleTools, Utilities, Debug, Trace PeopleCode to access the Trace PeopleCode page.

You use this page to change the PeopleCode tracing options while online. This page does not affect trace options that are set in PeopleSoft Configuration Manager. Use Trace PeopleCode to create a file displaying information about PeopleCode programs processed from the time that you start the trace.

Trace Evaluator Instructions

Select to show a line-by-line trace of the program

List Evaluator Program

Select to show the code of the PeopleCode program.

Show Assignments to Variables

Select to show variable assignments.

Show Fetched Values

Select to show values that are from PeopleCode Fetch call.

Show Stack

Select to display the PeopleCode evaluator's stack after each PeopleCode (internal) instruction.

Trace Start of Programs

Select to show the starting and ending points of the program.

Trace External Function Calls

Select to show calls to application written functions.

Trace Internal Function Calls

Select to show the calls to PeopleTools built-in function calls.

Show Parameter Values

Select to show function parameter values.

Show Return Parameter Values

Select to show function return parameter values.

Show Each

Select to trace each statement in the program.

Note. The Trace PeopleCode Utility decreases system performance because of the overhead that occurs during the monitoring and recording of all PeopleCode actions.

The check boxes on this page correspond to the options on the Trace tab in Configuration Manager. However, the selections that appear on this page do not necessarily reflect those that are made in Configuration Manager. While the Configuration Manager settings are stored in the Windows registry and used at each signon, the settings in the Utilities page only apply to the current online session, and, once set, they override the Configuration Manager's settings.

The benefit of using this page to control PeopleCode tracing is that you can turn it on and off without having to restart PeopleTools, and without resetting the Configuration Manager settings. Keep in mind, though, your selections are not enabled until you save the page.

To enable/disable PeopleCode tracing while on line

Select PeopleTools, Utilities, Debug, Trace PeopleCode.

The Trace PeopleCode page appears.
Select/deselect the desired Options.
Save the page.

If you selected any of the check boxes, the system starts writing to the trace file.

Configuring SQL Trace

Select PeopleTools, Utilities, Debug, Trace SQL to access the Trace SQL page.

You use this page to change the SQL tracing options while you're online. Your Configuration Manager settings are not affected:

Trace SQL Statement

Select to show the SQL statement.

Trace SQL Bind

Select to show bind values for SQL statements that have parameter markers.

Trace SQL Cursor

Select to show connect, disconnect, commit and rollback calls.

Trace SQL Fetch

Select to show fetch call for Select Statement.

Trace SQL API

Select to show other API calls (Execute, Describe, and so on.)

Trace SQL Set Select Buffer

Select to show Binds for Select columns.

Trace SQL -- Database Level

Select to specify low-level tracing at the database API (ODBC, ct-lib, and so on.)

Trace SQL -- Manager Level

Select to show calls for Cache calls.

The check boxes on the Trace SQL page correspond to options on the Trace tab in the Configuration Manager. However, the selections that appear on this page do not necessarily reflect those that are made in the Configuration Manager. The displayed page selections are not enabled until you save the page.

To enable or disable SQL tracing while online:

Select or deselect the desired trace options.
Save the page.

If you select any of the check boxes, the system starts writing to the trace file.

Trace Evaluator Instructions	Select to show a line-by-line trace of the program
List Evaluator Program	Select to show the code of the PeopleCode program.
Show Assignments to Variables	Select to show variable assignments.
Show Fetched Values	Select to show values that are from PeopleCode Fetch call.
Show Stack	Select to display the PeopleCode evaluator's stack after each PeopleCode (internal) instruction.
Trace Start of Programs	Select to show the starting and ending points of the program.
Trace External Function Calls	Select to show calls to application written functions.
Trace Internal Function Calls	Select to show the calls to PeopleTools built-in function calls.
Show Parameter Values	Select to show function parameter values.
Show Return Parameter Values	Select to show function return parameter values.
Show Each	Select to trace each statement in the program.

Trace SQL Statement	Select to show the SQL statement.
Trace SQL Bind	Select to show bind values for SQL statements that have parameter markers.
Trace SQL Cursor	Select to show connect, disconnect, commit and rollback calls.
Trace SQL Fetch	Select to show fetch call for Select Statement.
Trace SQL API	Select to show other API calls (Execute, Describe, and so on.)
Trace SQL Set Select Buffer	Select to show Binds for Select columns.
Trace SQL -- Database Level	Select to specify low-level tracing at the database API (ODBC, ct-lib, and so on.)
Trace SQL -- Manager Level	Select to show calls for Cache calls.