Tip 045: Introduction to Tracing - BareFoot PeopleSoft

PeopleTools | Tracing options available to a developer

A. A Massive Topic

When developing a PeopleSoft application, you inevitably have to use tracing at some point to troubleshoot code that isn’t functioning as expected. For this post, we will give ‘tracing’ a broad definition and include any mechanism designed to clarify what your code is really doing at run-time. We will also accept that tracing is a massive topic and it won’t be possible to cover everything in one go. With this in mind, I’ve decided to leave out the App Designer code debugger for the time being. This deserves a separate post of its own.

What follows then is a brief introduction to PeopleSoft tracing. We will not cover each option in extensive detail, but just provide enough information to make you more familiar with the functionality that does exist.

B. Trace Flags

Many of the trace options come with their own unique set of values, called ‘trace flags’. For instance, if you are doing SQL tracing, flag ‘1’ is used for ‘SQL Statements’, while flag ‘2’ is for ‘SQL Variables’. The list continues with other options, from 4 to 8 to 16 right up to 8192 (PeopleBooks will always provide you with the full list of the flag values). Once you’ve decided which tracing options you’d like to use, it’s then a case of adding up the flag values to arrive at a final sum. This sum is then passed as a parameter to the trace function.

This construct can be a little confusing if you’ve never come across it before, so here’s a quick example of trace flags in actions. Say you have the following trace options:

1: trace type A
2: trace type B
4: trace type C
8: trace type D
16: trace type E
32: trace type F

From this list, simply pick-and-choose the trace options you want, adding the applicable values together. So if we are interested in tracing types B, C and F, we would add together the individual values (2 + 4 + 32) to arrive at a final value of ‘38’. This value will then be passed to the trace functionality.

Finally, a word of warning about setting up a trace. Some of the trace options produce a huge amount of content, so much so that you could suddenly find yourself with a 200 MB file (and an angry systems administrator, wondering where all the disk space has gone). Therefore, always take a cautious approach when tracing, starting with fewer options and gradually building up over time. Be wary of just copying someone else’s trace flags (such as mine in the examples below), as you don’t exactly know what was being traced at the time. It could have been a tiny App Engine with one step, so a ‘wordy’ trace would be fine here.

C. MessageBox statements

Some developers might not even classify this approach as ‘tracing’. You are not actually asking the system to produce a trace on your behalf. Rather, you are inserting your own code directly into the programme. However, a ‘MessageBox’ statement is often a handy approach if you already have a good idea where the problem is occurring, and you just want to quickly check the flow of the program or what values certain objects are being set to. It also doesn’t require any server access or worrying about where trace files will end up.

MessageBox(0, " ", 0, 0, "Value of EMPLID = " | &emplid);

Refer to tips 001 and 041 for more details of using messages.

D. Custom Log Files

This again is another option that does not rely on dedicated trace functionality. At any point in the code you can create your own trace file, outputting whatever information you wish. Unlike ‘MessageBox’ – which is limited to a few messages since you have to click ‘OK’ after each message – a lot more information can be produced in a file. However, this approach usually requires access to the file server, and having an understanding of where temporary files are saved.

Refer to tips 008 and 014 for further details of creating temporary trace files.

E. SQL Trace

As any PeopleCode programme executes, it interacts with the database via the use of SQL statements. On many occasions, seeing the SQL statements can give you a clearer idea of what a programme is really doing. The SQL trace works on the basis of trace flags, as described at the start of this post. One common option for SQL tracing is ‘15’, which covers:

1 – SQL Statements
2 – SQL Variables
4 – SQL connect / disconnect / commit / rollback
8 – Row Fetch

Value ‘7’ is also another popular option, dropping ‘Row Fetch’ from the list above.

There are three ways to set up SQL tracing for an online programme:

(a) The Sign-On Option. If your system administrator has made the option available, you might already see a trace link on the normal sign-on page:

If you don’t see this option, you can try amending the URL for the sign-on page by appending ‘&trace=Y’ to the entire URL string. In other words:

http://server.xx.yy:7001/psp/PSTST/?cmd=login&languageCd=ENG&trace=Y

If this works, you should see a link similar to the above. Clicking on the link will give you access to a huge number of tracing options. Under the ‘SQL Trace Settings’ option, click the check-boxes for the specific trace you are after. So if you want our ‘15’ option described earlier, this would involve ticking the first four options:

Note that the sign-on approach to tracing takes effect for the entire session. Therefore it may be a case of ‘too much information’ if you are only interested in tracing a specific page or process.

(b) Trace SQL Page. Once you’re logged into the system, go to PeopleTools -> Utilities -> Debug -> Trace SQL. This will set up a trace from the moment you click ‘Save’. The trace will end by either (i) returning to the page, unchecking the flags and clicking ‘Save’, or (ii) logging out of the session entirely. The options on the SQL Trace page are similar to the sign-on trace page:

While this option is more selective than sign-on tracing, it can still produce trace content that is unrelated to the issue you are trying to resolve. All SQL activity will be logged from the point of clicking ‘Save’. So you will end up seeing a lot of extraneous material, such as SQLs related to navigating around the portal menu.

(c) SetTraceSQL Function. If your desire is to only capture SQL statements relevant to a specific component or function (for example, the PeopleCode behind a push-button), your best option is the ‘SetTraceSQL’ function. This allows you to fine-tune your trace content right down to individual statements. You can start the trace at the exact moment you wish and then turn it off as soon as you are done:

/* Turn tracing on */
SetTraceSQL(15);

/* Turn tracing off */
SetTraceSQL(0);

In all three cases, the SQL trace files are stored in the ‘LOGS’ directory of your App Server, in a directory such as the following:

/u02/app/psft/ps_cfg/appserv/PSTST/LOGS

F. PeopleCode Trace

This works in a similar way to SQL tracing, except that it produces a trace of PeopleCode-related commands. Again, the trace comes with a raft of options, such as:

4 – Show Assignments to Variables
8 – Show Fetched Values
512 – Show Parameter Values
1024 – Show Return Parameter Values
2048 – Show Each (Statement)

Normally I start with the ‘Show Each’ trace (2048) on its own, before turning this off and considering some of the other options for a more targeted trace.

Setting the PeopleCode trace is similar to setting an SQL trace. So to avoid repeating ourselves, I will only mention functionality that is specific to PeopleCode tracing. Otherwise, refer to the ‘SQL Trace’ section above for more details of these three options.

(a) The Sign-On Option. Use the ‘Set Trace Flags’ option on the PeopleSoft sign-in page. On the trace options page, select the appropriate values as required:

(b) Trace PeopleCode Page. Once you’re logged into the system, go the ‘PeopleTools -> Utilities -> Debug -> Trace PeopleCode’ to set up a trace that starts from the moment you click the ‘Save’ button.

(c) SetTracePC Function. Use the ‘SetTracePC’ function within a PeopleCode programme to trace a specific part of the code:

/* Turn PeopleCode tracing on */
SetTracePC(2048);

/* Turn PeopleCode tracing off */
SetTracePC(0);

Similar to SQL tracing, the PeopleCode trace files end up in the ‘LOGS’ directory of your App Server:

/u02/app/psft/ps_cfg/appserv/PSTST/LOGS

G. App Server Log Files

Although the App Server log files can be a bit cryptic for the uninitiated, they occasionally provide some mildly useful information in regards to unusual system crashes. The main challenge is sifting through the irrelevant information (failed log-on attempts, certificate issues) just to come across something that might be related what you’re looking at.

The main App Server log files are again stored in the ‘LOGS’ directory of the App Server:

/u02/app/psft/ps_cfg/appserv/PSTST/LOGS

The App Server keeps a daily log. Each day has its own separate log file, with the date appended on the end, so after a week of activity, you should see seven log files like this:

APPSRV_0901.LOG
APPSRV_0902.LOG
…
APPSRV_0907.LOG

Depending on what other system processes are running on your site, you may also find web server logs (Tuxedo) and other monitoring logs within the same directory. There is also a ‘stdout’ and ‘stderr’ file that is used for any ‘standard output’ and ‘standard errors’ that cannot be saved to other files. If you’re getting desperate, you can try checking these files as well, but unfortunately, their content usually has very limited value.

H. App Engine Tracing

SQL and PeopleCode tracing as described above can also be set up for App Engines via the Process Definition. In addition, there a third type of tracing specific to App Engines, which includes information about timings and SQL calls. Because the trace information is set up for an individual Process, this makes all three options specific to one App Engine only.

Start by going to the following page in the system:

PeopleTools -> Process Scheduler -> Processes

Enter the name of your App Engine in the search record and then go to the ‘Override Options’ tab. Change the ‘Parameter List’ option to ‘Append’ and then enter your tracing requirement in the Parameters field. As mentioned above, you have three types of traces available:

TRACE (App Engine Tracing)
TOOLSTRACESQL (SQL Tracing)
TOOLSTRACEPC (PeopleCode tracing)

For each trace option, you will again need to calculate the total sum of the trace flags that you wish to use. The SQL Tracing and PeopleCode tracings use the same values as described earlier. For the App Engine trace, the most relevant options are the first three:

1: Perform STEP trace
2: Perform SQL trace
128: Perform timings trace

This means that ‘TRACE 131’ is a common option, such as in the example below:

You can perform multiple trace types by entering each item, separated by a space:

NOTE: The above settings could potentially produce an enormous trace, so take great care in its use.

Once you’ve finished with your trace, don’t forget to remove your trace options by setting the ‘Parameter List’ field back to ‘None’. If your Process Definition is migrated to another database, any trace information saved for the process will be migrated as well.

I. COBOL Tracing

COBOL tracing is nowhere near as extensive or as straightforward as tracing an App Engine. If you’re lucky, the COBOL programmer may have provided some additional trace options as part of the COBOL. The run control page might even allow you to specify the level of tracing that you’d like to see. But you do have to be lucky. This is not so common.

For COBOLs run as a process, it’s possible to set up a COBOL trace at the server level. If this option is used, ALL COBOLs are traced, not just the specific one you’re after. So this option must be used with extreme care. Start by going to the following page in the system:

PeopleTools -> Process Scheduler -> Process Types

Enter a Process Type of ‘COBOL SQL’ and then select the record depending on your operating system and database type (usually ‘Windows / Oracle’ or ‘UNIX / Oracle’):

One of the options on the page is ‘Parameter List’. Scroll right to the end of the field where you should see a piece of text ‘DBFLAG’:

Just before the DBFLAG text, you will see two forward slashes (//). Between the two slashes, enter a value of ‘255’ to set up a COBOL SQL trace:

As soon as you save the page, full COBOL tracing will be in operation. Once a process has completed, the trace files should be available in Process Monitor as normal. Don’t forget to remove the ‘255’ option once you are done with the tracing.

In fact, this point is so important, that I’ll say it again, take care when using the COBOL server trace option. If you really must use it, turn it on straightaway, immediately run your COBOL, and then turn it off again. Do not leave the setting on for extended amounts of time as this will seriously impact system performance, as well as draining disk space.

If the COBOL is being called as part of an online page (via the ‘RemoteCall’ PeopleCode command), you can also ask your system administrator to change one of the settings in the ‘psappsrv.cfg’ file (this file is located in the App Server home directory). Do a search for RCCBL, and then change the ‘RCCBL Redirect’ parameter from 0 to 1.

Unfortunately, this option can be a little hit-and-miss and you may not find any useful information returned by the trace. But if you’re really stuck, it might be worth a go.

<< Previous | Next >>