Debugging Your Application

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

• Access the PeopleCode debugger.

• Use PeopleCode debugger features.

• Use 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 application logging.

• Use the Find In feature.

• Use cross-reference reports.

Understanding the PeopleCode Debugger

The PeopleCode debugger is an integrated part of 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, breakpoints, logging, and so on are no longer executed.

Accessing the PeopleCode Debugger

Note. You can start a debugging session either before or after you start a PeopleSoft component.

1. Determine whether to run Application Designer in two-tier mode or three-tier mode.

   If you are debugging Application Engine or component interface PeopleCode, run Application Designer in two-tier mode, with a direct connection to the datatbase.

   If you are debugging an application in PeopleSoft Pure Internet Architecture (PIA), run Application Designer in three-tier mode, through the application server. You must be logged on to PIA and to Application Designer using the same user ID.

2. Access the debugger through Application Designer by selecting Debug, PeopleCode Debugger Mode.

   The Local Variables watch pane and the Call Stack pane open. PeopleCode programs that had breakpoints set from your previous debugging session are opened also, and the breakpoints are restored.

   If you did not have breakpoints set, open the PeopleCode program you want to debug and enter debug mode. The debugger will open with the current PeopleCode program and you can set your breakpoints.

   Note. If you have already opened the debugger and 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, and then try the Debug menu again.

   In PIA, navigate to the point where the breakpoint occurs. Your application pauses and the Application Designer icon flashes in the task bar. Switch to Application Designer to step through your program or continue running it.

   If the debugger does not engage, check that you used the same user ID to log into PIA and Application Designer, then check your application server configuration to verify that PeopleCode debugger is enabled.

Note. Your security administrator has options for allowing users to access different parts of Application Designer, including the PeopleCode debugger. If you are having problems accessing the debugger, you may need to contact your system administrator about your security access. You can access the PeopleCode debugger from outside a firewall.

Using 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

This example shows the current line indicator (green arrow displayed in left-hand gutter):

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 in function declarations, variable declarations, or 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 appears 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, only one instance of the PeopleCode debugger can occur per session. If more than one instance of Application Designer is running for a session, only one may be the active debugger at a given time.

From within a running instance of 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 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 Application Designer session is running, the Application Designer session that is used as a debugger is the first one to be started.

In debug mode, a PeopleCode Editor window opens 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, then only one window opens per item. For example, if you have a record that has PeopleCode in both the SearchSave and RowInit events, only one PeopleCode Editor window opens: first it contains the SearchSave PeopleCode program, and 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 open, one for each RowInit PeopleCode program.

Variables Panes

The four types of variables panes are:

• 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 example 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 is expanded. You can see the properties, such as ActiveRowCount and DBRecordName, that are part of the rowset.

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 to see their properties. In the following example, the first row of a rowset is expanded, as is the EMPL_CHECKLIST record:

Field Values

When you view a field object in the debugger, the value of the field is listed in 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 appear in the debugger are the fields that are actually in the Component Buffer. For example, suppose you have a derived work record, but you do not access all the fields in the work record. Only the fields that you access and that are in the Component Buffer actually appear in the debugger.

See Also

Record Fields and the Component Buffer

Call Stack Pane

The Call Stack pane appears by default when the PeopleCode debugger is started. To reopen it, select Debug, View Call Stack Window.

The Call Stack pane displays a stack of PeopleCode functions and methods that are currently active but not completed. You can use the Call Stack pane to observe the flow of an application as it executes a series of nested functions. When a function is called, it is pushed onto the top of the stack. When the function returns, it is popped off the stack.

The Call Stack pane displays the currently executing function at the top of the stack and older function calls below that, in reverse calling order. You can navigate to the source code of a function from the call stack window. The variables panes update to reflect values for the selected function.

The Call Stack pane is updated and usable when execution is stopped at a breakpoint.

Call Stack Indicators

The Call Stack displays a current line indicator and a selected function indicator in the gutter.

The current line indicator is a green arrow that shows where in the call stack the execution stopped. The current line indicator always appears in the call stack pane.

The selected function indicator is a yellow triangle that marks the current function being displayed by the Edit and Variables windows. The selected function indicator does not appear when the current function is at the execution point.

You can hover over a function name to see the full program path in a pop-up window, as shown in the following example.

The Call Stack pane is updated, when necessary, with each change of the debug state.

Go To Source Code

Right-click on a function to access a context menu with these options:

When the displayed source code is at the execution point, the execution pointer icon (green arrow) appears in the source window.

When the displayed source code is not at the execution point, the selected function icon (yellow triangle) appears in the source window.

Viewing source code for functions that are not at the top of the stack does not change the point of execution. Nor does it disable the ability to continue execution. For example, in the previous example, selecting Go would cause the program execution to continue at “FUNCLIB_PORTAL.PORTAL_GEN_FUNC.FieldFormula PortalOpen” and not at the function in the source code window.

During debugging it is easier to go back to the previous code event from the call stack window as compared to trying to keep track of where the control was transferred and then finding the right opened PeopleCode window in Application Designer. This can be useful when trying to understand the component design and PeopleCode flow.

Setting Values for Variables and Properties

Setting the value of a variable or property in the debugger gives you the flexibility to try out changes and see the results in real time or to recover from a logic error and continue.

You can change the value of variables or properties in the Local Variables, Component Variables, Function Parameters, and Component Buffers panes. Only variables or properties with conventional data types (Any, Boolean, Date, DateTime, Float, Integer, Number, String, Time) can by changed. You cannot assign a new object to an object variable. Values that are not editable appear on a gray background.

While the debugger is running and halted at a breakpoint, select a field in the value column, such as the Local Value column in the example, and revise the value.

The debugger performs data type checking to prevent entry of incorrect data type values. For example, character strings are not allowed for integer data types, and so on. However, data integrity is not verified, so be aware that changing variable values at runtime can corrupt program execution as well as program data. For example, setting an integer value higher than what is permitted in the function could cause a crash when execution continues. It is the developer’s responsibility to enter an appropriate value.

Modifying a variable in a debugger pane changes the value in memory only. The change does not trigger any PeopleCode events and does not cause any PeopleCode flags to be set.

General Debugging Tips

The following are general tips for debugging your application:

• If you are 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.

• Using the debugger is resource intensive and will impact overall system performance. Oracle recommends that you do not run debugger on your production system unless the issue you are trying to debug cannot be replicated in any other environment. If that is the case, debug when there is the least activity on the system. As an alternative you can try PeopleCode tracing.

• 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 example shows the Find In dialog box:

DoModal Considerations

If you set the PeopleCode debugger to break at start and you are using the DoModal PeopleCode function, the DoModal window may appear behind the PeopleCode debugger window. The debugger may appear to have stopped, but it has not. Be sure to check that other windows have not opened while you are debugging the code.

Using PeopleCode Debugger Options

While 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 Application Designer, you automatically exit debug mode.
Abort Running Program	Stops the PeopleCode program that is currently running.
Execution Location Properties	Displays the location of the running code in a dialog box. This display 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 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 start a component with Break at Start selected and then you 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, and then pauses.
Step Instruction	Processes low-level, pseudo-machine code instructions internal to PeopleCode. This option is used in conjunction with Log Options.
View Call Stack Window	Opens a separate window for viewing the call stack. The Call Stack window displays a stack of PeopleCode functions and methods that are currently active but not completed. You can use the Call Stack window to observe the flow of an application as it executes a series of nested functions.
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. The previous five windows update continuously 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 do not have to configure a local domain to do this. You also do not 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:

To compile all PeopleCode programs:

1. Open Application Designer while accessing 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 specified a log file in the debugger log options, then 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 step 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 Application Designer.

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

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

When you close the 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

This table describes the data trace options:

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 are running PeopleTools.

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

If you do not exit 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 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 information useful 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. It also enables you to write to the PeopleTools log using the WriteToLog built-in function.

Note. This is an application log fence, and it is distinct from the PeopleTools 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 Tools log file, this mechanism is also an aid in debugging. For example, you could interleave PeopleCode, SQL, and application level tracing in the same log file to easily correlate application and PeopleTools actions.

See Also

WriteToLog

%ApplicationLogFence

Setting the Application Log Fence in the Configuration File

The application log fence default is %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 its value is changed in the file, then the new value will be used. As the following example illustrates, the AppLogFence setting 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 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.

• Only freeform stylesheets.

• SQL injection in PeopleCode.

The following example shows the Find In dialog:

You can further refine your search by specific project. If you are 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 statement, HTML definitions, or freeform stylesheets listed. You also can insert selected definitions into a project from the output window. Then, if you need to search those definitions 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:

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

   The Find In dialog box appears.

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, HTML definitions, or freeform stylesheets..

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 a subset of items.

   Note. When you select a Find Type of Text String in HTML the Search check box list is empty. The search is conducted against all HTML definitions.
   
   Similarly, when you select a Find Type of Text String in Freeform Stylesheets the Search check box list is empty. The search is conducted against all freeform stylesheets.

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 Application Designer Find In output window.

   This option is not available when searching SQL, HTML, or freeform stylesheets.

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 tab on the 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 example shows the Find In tab of an output window:

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

To save definitions 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 definitions and select Insert Into Project.

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

4. Save your project.

The following example shows the Insert Into Project option:

The next time 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. Opportunities for SQL injection are usually created when developers use string-building techniques to generate SQL that is subsequently executed.

Search PeopleCode for SQL injection vulnerabilities.

See Also

Searching PeopleCode for SQL Injection

Using Cross-Reference Reports

If a field value changes and you do not know how it changed, you can find all references to a field using:

• The Find References option in Application Designer.

• Cross-reference reports.

See Working With Projects.

PeopleTools is delivered with these PeopleCode cross-reference reports:

• XRFFLPC.

  Reports on all fields in the system referenced by other PeopleCode programs. The report sorts by record names and 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, and 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