Debugging Your Application

This chapter provides an overview of the PeopleCode debugger and discusses how to:

• Access the PeopleCode debugger.

• Understand PeopleCode debugger features.

• Understand PeopleCode debugger options.

• Set up the debugging environment.

• Compile PeopleCode programs at once.

• Set PeopleCode debugger log options.

• Interpret the PeopleCode debugger log file.

• Use the Find In feature.

• Use cross-reference reports.

Understanding the PeopleCode Debugger

The PeopleCode debugger is an integrated part of PeopleSoft Application Designer. The interface to the debugger has a visual indicator of breakpoints, an arrow indicating the current line, and the ability to step through code. You can inspect the value of a variable by holding the cursor over it and reading the pop-up bubble help. The debugger also provides variable inspection windows for global variables, local variables, function parameters, and component-scoped variables. It also enables PeopleCode objects to be expanded, so you can inspect their component parts.

Note. The PeopleCode debugger does not work on Microsoft Windows 95 or Windows 98.

Do not try to use the PeopleCode Debugger with the SwitchUser function. Only the first user is logged into the PeopleCode Debugger. Once the switch occurs, any breakpoints, logging, and so on, are no longer executed.

Accessing the PeopleCode Debugger

You access the debugger through PeopleSoft Application Designer. You can start a debugging session either before or after you start a PeopleSoft component.

To start the PeopleCode debugger:

1. Open PeopleSoft Application Designer.

2. Select Debug, PeopleCode Debugger Mode.

   The Local Variables watch window opens. PeopleCode programs that had breakpoints set from your previous debugging session are opened also, and the breakpoints are restored.

   Note. If you have already opened the debugger, then closed it, the menu may not change correctly to enable you to access the debugger a second time. If this occurs, click the Local Variables window, then try the Debug menu again.

   You must make some adjustments to the system to run the debugger in PeopleSoft Pure Internet Architecture.

Note. Your security administrator has options for allowing users to access different parts of PeopleSoft Application Designer, including the PeopleCode debugger. If you’re having problems accessing the debugger, you may need to contact your system administrator concerning your security access. It is possible to access the PeopleCode debugger from outside a firewall.

Understanding the PeopleCode Debugger Features

This section discusses:

• Visible current line of execution.

• Visible breakpoints.

• Hover inspect.

• Single debugger.

• Variable panes.

• General debugging tips.

Visible Current Line of Execution

The current line indicator (green arrow displayed in left-hand gutter) is shown in the following illustration:

Visible Breakpoints

The PeopleCode debugger supports visual indicators that signify breakpoint locations. In the following example, the current line indicator (green arrow) is shown at the first line, and the breakpoint (red dot displayed in left-hand gutter) is on line 8:

All breakpoints are saved when Exit Debug Mode is selected.

Note. You cannot set breakpoints on function declarations, variable declarations, or in comments.

Hover Inspect

If the program is already running, you can see the actual values for the variables by holding the cursor over them. The current value is displayed in a pop-up window, as shown in the following example:

Hover inspect is implemented only for simple variables and fields.

Hover inspect is not implemented for object expressions (for example, rowset assignments and array assignments).

Single Debugger

Each PeopleSoft session you run on a machine can have its own debugging session. However, there can only be one instance of the PeopleCode debugger per session. If more than one instance of PeopleSoft Application Designer is running for a session, only one may be the active debugger at a given time.

From within a running instance of PeopleSoft Application Designer, any component in the same session is also placed into debug mode.

After the session is in debug mode, any component that is started and that belongs to that session automatically goes into debug mode.

Similarly, Application Engine PeopleCode and component interface PeopleCode can be debugged.

After you exit debug mode by selecting Debug, Exit Debug Mode or by exiting PeopleSoft Application Designer, all components in that session go out of debug mode.

If you exit a component, debugging continues with any remaining open and running components.

If more than one PeopleSoft Application Designer session is running, the Application Designer session that is used as a debugger is the first one to be started.

If you’re in debug mode, a PeopleCode Editor window is opened for every item (for example, record, component, or page) that has PeopleCode in it when that PeopleCode is executed. If a component has more than one event with a PeopleCode program, only one window is opened per item.

For example, if you have a record that has PeopleCode in both the SearchSave and RowInit events, only one PeopleCode Editor window is opened: first it contains the SearchSave PeopleCode program, then the RowInit program. If you have PeopleCode in the RowInit event for two different records that are part of the same component, two PeopleCode Editor windows are opened, one for each RowInit PeopleCode program.

Variables Panes

There are four types of variables panes:

• Local

• Global

• Component

• Parameter

The Local, Global, and Component variable panes show local, global, and component variables, respectively. The Parameter variable pane shows the value of parameters passed in function declarations.

From the variables pane, you can check the value of the variables you have in the program. These values are updated as the code runs. The following illustration shows the variables pane:

In addition, you can expand any of the objects to see its properties by clicking the plus sign next to the variable name. In the following example, a level one rowset has been expanded. You can see the properties that are part of the rowset (such as ActiveRowCount or DBRecordName).

In addition, some objects contain other objects: a rowset contains rows, rows contain records or child rowsets, and records contain fields. You can expand these secondary objects also, to see their properties. In the following example, the first row of a rowset has been expanded, as has the EMPL_CHECKLIST record:

Field Values

When you view a field object in the debugger, the value of the field is listed under the Value column. Therefore, you do not have to navigate to the Value property to see the value of a field.

The following example shows the PERSONAL_DATA record and the values of the fields:

In addition, the only fields that are displayed in the debugger are the fields that are actually in the Component Buffer. For example, suppose you have a derived work record, but don't access all the fields in the work record. Only the fields that you access, and that are in the Component Buffer, are actually displayed in the debugger.

See Also

Record Fields and the Component Buffer

General Debugging Tips

The following are general tips for debugging your application:

• If you’re having problems determining if the correct data is being loaded into the component buffers, use the View Component Buffers view window to see all the values currently in the component buffer.

  This is equivalent to putting a GetLevel0 function at the start of a program.

  Use the &LEVEL0 variable to navigate through all the levels of the rowset object, see the row, records, fields, and so on. This shows you everything that has been loaded into the component buffers for that component.

• While at a breakpoint, if you lose track of the window, or the location within the window, that is displaying the green execution location arrow, you can use the Execution Location Properties menu item’s ViewCode button to find your current execution location again.

• Objects remain expanded in the variable windows as you move through PeopleCode.

  This enables quick inspection of the state of an object as you step through the PeopleCode. However, there is a performance cost for using this feature. If you are finished examining an object, you may want to collapse it to improve the response speed.

• If a database transaction has been started (either for you by PeopleTools, or by you in PeopleCode) other users of that database are blocked from accessing that database until the transaction is complete.

  If you are stepping through PeopleCode while this transaction is open, you could potentially block other users for an extended period of time. You may want to use a private database for debugging to avoid blocking other users.

• To create a file that contains all the PeopleCode for a project (or database), use the Find In feature and search for ;.

  Be sure to select Save PeopleCode to File.

The following illustration shows the Find In dialog box:

DoModal Considerations

If you have set the PeopleCode debugger to break at start, and you’re using the DoModal PeopleCode function, the DoModal window may appear behind the PeopleCode debugger window. This makes it appear as though the debugger has stopped, when it actually has not. Be sure to check that other windows have not opened while you’re debugging the code.

PeopleCode Debugger Options

After the debugger is running, you can use the Debug menu to select other options:

Exit Debug Mode	Exits debug mode. When you exit debug mode, all breakpoints are automatically saved. If you close PeopleSoft Application Designer, you automatically exit debug mode.
Abort Running Program	Stops running the PeopleCode program that is currently running.
Execution Location Properties	Displays the location of the running code in a dialog box. This includes the record name, field name, event name, and line number of the code. It also indicates if the code is executing on the client or server. You can also view the exact code by clicking View Code.

Break at Start	Pauses execution of the component on the first line of every PeopleCode program that executes in the component. If you've started a component with Break at Start selected, and then start a second component, the PeopleCode associated with the second component is stopped at the first line of the first PeopleCode program as well, as part of the same debugging session.
Toggle Break at Cursor	Removes the breakpoint if the line the cursor is currently on has a breakpoint. Adds a breakpoint if the line the cursor is currently on does not have a breakpoint.
Edit Breakpoints	Opens a dialog box that displays the lines that have breakpoints. From this dialog box, you can display the code that contains the breakpoint by clicking View Code. You can also remove one or all breakpoints.

Go	Continues processing until the next breakpoint. If Break At Start is enabled, processing pauses at the next PeopleCode program.
Step	Executes the current line of the PeopleCode program, stepping into functions.
Step Over	Steps through each line of the PeopleCode program, one line at a time, but steps over the functions; the functions are executed, but not stepped into.
Run to Return	Processes past the return of the current function, then pauses.
Step Instruction	Processes low-level pseudo-machine code instructions internal to PeopleCode. This option is used in conjunction with Log Options.
View Global Variables	Opens a separate window for watching global variables.
View Component Variables	Opens a separate window for watching component variables.
View Local Variables	Opens a separate window for watching local variables.
View Function Parameters	Opens a separate window for watching user-specified parameters in function calls.
View Component Buffers	Opens a separate window for viewing the current component buffers. This is equivalent to getting a level zero rowset for the component.

Note. These five windows are continuously updated as the program executes.

The General Options dialog box enables you to specify conditions of the view windows. The default is for both of these options to be selected.

Additional Features

See Also

Setting PeopleCode Debugger Log Options

Setting Up the Debugging Environment

You can use the PeopleCode debugger for two-tier and three-tier debugging. The database and application can reside on remote servers; they do not need to reside on the local machine.

Two-tier debugging works out of the box. Setting up three-tier debugging requires you to make a few modifications in PSADMIN (PSAPPSRV.CFG) to enable debugging.

You can connect to a Microsoft Windows NT server domain that is not on your local machine. You don't have to configure a local domain to do this. You also don't have to have PeopleTools software installed locally for three-tier debugging.

See Also

Setting Up the PeopleCode Debugger

Compiling All PeopleCode Programs at Once

In addition to checking individual programs, you can compile all PeopleCode programs either in a database or in a project to check for errors. This option opens and compiles every PeopleCode program. This process can be run on an as-needed basis to check for corruption in your programs. Run this option after an upgrade to verify that all the programs were upgraded correctly. You run this option from the Tools menu, as shown in the following illustration:

To compile all PeopleCode programs:

1. Open PeopleSoft Application Designer while accessed to the database that contains the PeopleCode that you want to check.

2. Select the compile option to use.

   Select Tools, Compile All PeopleCode or Tools, Compile Project PeopleCode.

3. Click Compile in the Compile All PeopleCode dialog box.

   Errors appear in the PeopleCode log display window.

   Note. If you've specified a log file in the debugger log options, all errors are written to the log file as well.

Setting PeopleCode Debugger Log Options

Use the PeopleCode debugger to view PeopleCode that is executed while you’re stepping through your application. Select Debug, Log Options to access the PeopleCode Log Options dialog box.

All log information appears in the PeopleCode log window, at the bottom of PeopleSoft Application Designer.

You can also record what you see in a log file. You can tailor the log results to record a variety of online information.

If you exit debug mode, but do not close PeopleSoft Application Designer, all the log options that you specified are still there when you start debug mode again.

When you close the PeopleSoft Application Designer, all log options are clear. The next time you enter debugging mode, you must reselect debug log options.

See Interpreting the PeopleCode Debugger Log File.

All the options available in the Log Options dialog box are also available in PeopleSoft Configuration Manager, on the Trace tab, in the PeopleCode Trace section.

Execution Trace Options

Execution trace is set to trace each PeopleCode statement. You can also trace the start of each program or each program instruction.

Data Trace Options

The data trace options are:

Call Trace Options

The call trace options, described in the following table, enable you to record the values of external calls, internal calls, returns, and function parameters.

Log To File

When you select this option, you must specify the name of a file, or you receive an error and logging to file is disabled.

If you do not specify a directory location, the file is placed in the same directory from which you’re running PeopleTools.

If you specify the name of an existing file, a warning message appears, asking you whether to overwrite the file. At this point, you must go back into the Log Options dialog box and specify a different file name, or else the log file is overwritten.

If you do not exit PeopleSoft Application Designer before running a different application, each trace is appended to the specified log file.

See Also

Specifying Trace Settings

Interpreting the PeopleCode Debugger Log File

You can produce a trace log using any of the following methods:

• Using the Log File option in the PeopleCode debugger.

• With the PeopleSoft Configuration Manager Trace tab.

• Using the SetTracePC and SetTraceSQL built-in functions.

• With PeopleTools utilities (included for backward compatibility purposes only and should not be used).

All trace files except those produced using the Log File option contain timing information, such as when each line started processing and how long it took to execute.

The Log File option writes to a file that you specify. The log file produced by the other options is specified by the PeopleTools Trace File option in PeopleSoft Configuration Manager. All of these options write to the same file.

Trace files are also produced by PeopleSoft Application Engine. These logs may contain more information.

This section discusses:

• Log file contents.

• Other items in the log file.

See Also

Using Debug Utilities

Log File Contents

The log file contains useful information for debugging PeopleCode.

You can view the log using any editor that displays ASCII text, such as Notepad. the log file has the following components.

Other Items in the Log File

The following table describes other items that can appear in a debugging trace:

Using Application Logging

Application logging enables you to do error logging using an independent application log fence mechanism, as well as being able to write to the PeopleTools log using the WriteToLog built-in function.

Note. This is an application log fence, and is distinct from the PeopleTool's LogFence setting.

In PeopleTools, a log fence is a type of “barrier.” Application error messages are only written to the PeopleTools log if the log fence setting that the messages are written to the log with (using WriteToLog) is less than or equal to the current application log fence setting (AppLogFence) in the application server configuration file (PSAPPSRV.CFG .)

For example if the AppLogFence setting is 2, only messages written using the WriteToLog function with a log fence value less than or equal to 2 will be written. This allows you to have application logging code written in your application that will only be in effect if the log fence setting permits.

The application log fence setting is available through the system variable %ApplicationLogFence.

Apart from the obvious use of allowing the application to write to the Tool's log file, this mechanism is also an aid in debugging. For example, you could interleave PeopleCode, SQL, and application level tracing in the same logfile to easily correlate application and PeopleTools actions.

See Also

WriteToLog

%ApplicationLogFence

Setting the Application Log Fence in the Configuration File

The Application log fence defaults to %ApplicationLogFence_Level1 (3). If you want to use this setting, you need to place it in the application server configuration file (PSAPPSRV.CFG.) The setting is dynamic change enabled (that is, if it’s value is changed in the file then the new value will be used). As the example below illustrates, the AppLogFence seting must be in the PSTOOLS section. If you add this setting, your configuration file can look like this:

[PSTOOLS]
;======================================================================
; General settings for PSTOOLS
;======================================================================
AppLogFence=1

See Also

PSAPPSRV Options

Using the Log Fence with PeopleSoft Analytic Calculation Engine

If you set the application log fence to 3 or above, all the detailed messages created on the analytic server to be sent back to the application server are also logged in the analytic server log file.

In addition, if you set the application log fence to 4 or above, all tracing information is logged to the analytic server log file.

Using the Find In Feature

Use the Find In feature of PeopleSoft Application Designer to search for strings, either in PeopleCode programs or in SQL definitions. This feature searches:

• All PeopleCode programs and all SQL statements.

• Only PeopleCode programs.

• Only SQL statements.

• Only HTML definitions.

• SQL injection in PeopleCode.

The following illustration shows the Find In dialog box:

You can further refine your search by specific project. If you're searching PeopleCode programs and SQL statements, you can specify if you want record PeopleCode, page PeopleCode, menu PeopleCode, and so on.

All output from the search is placed in an output window. You can save these results to a file, copy them, clear them, or print them.

From the output window, you can immediately open any of the PeopleCode programs, SQL statements listed, or HTML.

Also, from the output window, you can insert selected records into a project. Then, if you need to search those records again, you can search by project.

Note. To create a file that contains all the PeopleCode for a project (or database) you can use the Find In feature and search for ;. Be sure to select Save PeopleCode to File.

To find a text string in PeopleCode or SQL:

1. In PeopleSoft Application Designer, select Edit, Find in.

   This displays the Find In dialog box.

2. Type the string that you want to find in the Find What edit box.

   If you want only those items that match the case of what you entered, select the Match Case check box at the bottom of the dialog box.

3. Specify with the Find Type edit box whether you are searching in PeopleCode and SQL, just PeopleCode, just SQL, or HTML.

4. Select the project to search.

   You can search the entire database or any existing project.

5. (Optional) Select the view to search.

   If you decide to not search the entire database, you can specify if you want to search the Development view or the Upgrade view. The default is the Development view.

6. Select the items to search.

   You can search all items that contain either PeopleCode or SQL, or just a subset of items.

   Note. The Search check box list for HTML is empty. The search is conducted against all HTML definitions.

7. (Optional) Save the search results to a file.

   You can save the results of a PeopleCode search to a text file, which you can view or print using a text editor or word processor. The text file contains the entire PeopleCode program that contained the string.

   To save your results to a file, select the Save PeopleCode to File check box at the bottom of the dialog box. The results are saved to the file, and appear in the PeopleSoft Application Designer Find In output window.

8. Click the Find button to start the search.

   As the Find In feature searches the database, it displays a counter at the bottom of the Find In dialog box indicating the number of PeopleCode programs searched.

   You can click the Cancel button to stop the process.

9. Check the Find in Output window for results.

   The results of the search appear in the Find In tab of the output window. Each line shows where the string was found. You can open any of the programs listed by double-clicking a line in the output window.

The following illustration shows the Find In tab of an output window:

To save records, you select them in the output window, as shown in the following illustration:

To save records in a project:

1. Use the Find In feature to search for a string.

2. Press the Shift key while selecting the references to save in the output window.

3. Right-click the highlighted records and select Insert Into Project.

   All the selected records are inserted into the current open project.

4. Save your project.

The following illustration shows the Insert Into Project option:

The next time that you search, you can search only your project (select a project in the Find In dialog box) instead of searching the entire database.

Searching for SQL Injection

SQL injection is a technique that enables users to pass SQL to an application that was not intended by the developer. SQL injection is usually caused by developers who use string-building techniques to generate SQL that is subsequently executed.

Search PeopleCode for SQL injection vulnerabilities.

See Also

Searching PeopleCode for SQL Injection

Cross-Reference Reports

If a field value changes, and you do not know how it changed, there are two ways of finding all references to a field:

• The Find References option in PeopleSoft Application Designer.

• Cross-reference reports.

See Working With Projects.

PeopleTools is delivered with three PeopleCode cross-reference reports:

• XRFFLPC.

  Reports on all fields in the system referenced by other PeopleCode programs. The report sorts by record names, then field names. XRFFLPC shows the records, fields, and PeopleCode program types that reference each field.

• XRFPCFL.

  Reports on the fields that each program references. It sorts the report by record definition, field name, then PeopleCode type. It shows the records and fields referenced for each program. This report and XRFFLPC complement each other by using converse approaches to reporting the cross references.

• XRFPNPC.

  Reports on pages with PeopleCode. This report shows pages containing fields with PeopleCode attached to them.

You can run these reports using PeopleSoft Query and either view the reports online or print them. You can also download them to a Microsoft Excel spreadsheet. The following example shows an XRFPNPC report:

See Also

PeopleSoft Query Preface

Running PeopleTools Cross-Reference Reports