USING PYUPIP ORACLE HRMS

An Oracle White Paper April 2000

USING PYUPIP - ORACLE HRMS

OVERVIEW
PYUPIP is a utility used to monitor the database trace pipe. The database trace pipe allows the user to record the flow of HRMS PL/SQL code. The PL/SQL code can reside in a script or in a package. PYUPIP displays all the different breakpoints that are encountered when the code is executed. This utility is used extensively by HRMS developers, so dont expect it to work on PL/SQL developed outside this product group. The breakpoints are set by the developer in the PL/SQL code itself. However, additional breakpoints can be temporarily added to the code for debugging purposes. For example, you can label where you are in a procedure, or display values of relevant local variables. As the process runs, the breakpoints, labels and values of variables are written to a file. This gives the user a clear picture of what the code is doing and hopefully the information necessary to remedy the issue.

IMPORTANT: NEVER MODIFY DELIVERED CODE - MAKE A BACKUP. AFTER THE TRACE IS COMPLETE, YOU MUST RETURN THE ORIGINAL MODULE TO THE DATABASE OR FILE SYSTEM. FAILURE TO DO SO CAN CAUSE SERIOUS COMPLICATIONS WHEN USING ORACLE APPLICATIONS If you run a script with trace statements, and fail to run PYUPIP first, your script, driver or concurrent process will hang, and eventually error with the following: ORA-20001: HR_51356_UTILITY_PIPE_TIMEOUT: You must remove the trace statements once tracing is complete.

Examples of Breakpoints/labels in the PL/SQL code

Typical breakpoints in a PL/SQL code would look like this: hr_utility.set_location('pyusddwp.insert_deduction_template', 20) hr_utility.set_location('pyusddwp.insert_formula', 30) The data that will be written to a file corresponding to these breakpoints will look like: connected: monitoring pipe PID25 1 2 pyusddwp.insert_deduction_template pyusddwp.insert_formula

20 30

This tells the user the last place the code processed, (pyusddwp.insert_formula, 30). To obtain addition information about what is taking place in the code, in our example what formula is being inserted, we can add code to display the value of the formula id. This will only work if formula id is represented by a local variable, that has been initialized with a value, in the PL/SQL we are tracing. We can code statements to display the content of this variable as follows: hr_utility.trace(' Formula_id = ' || l_f_id ); Where l_f_id is a local variable. For clarity we can also code a literal. For example: hr_utility.trace ( 'successfully found formula id' ); The file would now contain: connected: monitoring pipe PID25 1 2 pyusddwp.insert_deduction_template successfully found formula id Formula_id = 12333 pyusddwp.insert_formula 30 20

This would tell the user what formula was being inserted at the time of the failure.

When should PYUPIP be used:

It can be used under different scenarios that need to monitor the execution of PL/SQL (any operation that calls PL/SQL code that has the breakpoints coded can be monitored). Typical examples are: SQL scripts Concurrent processes Forms The basic steps for running PYUPIP are: Get the session Id Start the monitor Execute the code to be monitored. There are different methodologies depending on what you want to monitor.

Steps for monitoring the pipe using PYUPIP SQL SCRIPTS from SQL PROMPT
This method works well when debugging patch script failures, or problems with APIs. Basically, any SQL script that calls a package. 1. Start a UNIX session (we will call it window 1) and log into SQL*Plus as <apps user>/<apps password>. Get the SQL*Plus session id by executing the following SQL statement: SELECT FROM userenv('sessionid') dual;

It will return something like: (note the session id) USERENV('SESSIONID') -------------------------------131894

2. Start another UNIX session (we will call it window 2). Make sure that you are in a directory that you have write privileges to, and there is plenty of disk space. Using the <sessionid> returned from window 1, enter the following at the UNIX prompt:
$PAY_TOP/bin/PYUPIP <apps user>/<apps password> <sessionid> > PYUPIP.txt

PYUPIP.txt can be named anything you want it to be. This is the file that will contain the trace file of the PL/SQL execution. 3. To turn the trace on , from window 1, execute the following command: exec hr_utility.trace_on; 4. Run the SQL script in window 1 that you are trying to produce a trace for. As the script runs, data will be outputted to PYUPIP.txt. After executing the command to run the SQL script, you will not see anything on this screen immediately. Since everything is being written to PYUPIP.txt, there will be no screen output. So please be patient and wait for the SQL*Plus session to return back to the SQL> prompt. 5. After the script has finished running, execute the following command in window 2: Break the trace by entering <CNTL>-C that is (control key) C. Your trace is now recorded in the file PYUPIP.txt ALTERNATE METHOD Scripts not run from the SQL prompt. If you are not running the script manually from the SQL prompt, for example you are restarting a patch using ADPATCH, you can embed the trace utility in the SQL script.

1. Make a backup of the script that calls the package we want to debug. Edit the script. Since we dont know the SESSION_ID, we have to pass the trace utility something to recognize our job. Just after the BEGIN for the call to the PL/SQL that we want to trace, add the following: BEGIN hr_utility.trace_on (null, 'ORACLE'); 2. Open a UNIX session and perform step 2 above using ORACLE in place of the <sessionid> 3. Open another UNIX session and restart your patch.

FORMS From the Application

We can trace the PL/SQL packages invoked by a form. Since it identifies packages that contain breakpoints accessed by the form, it is especially useful when trying to compare module versions. This information will help diagnose forms/package mis-match problems. It is also useful for diagnosing data problems because you can identify what piece of code is failing.

1. You must create a user function called HR_DEBUG_TOOLS, this will allow us to get the Process ID. We will use the process ID in place of the session ID in the PYUPIP command. This section need only be done once Log into the application using the System Administrator responsibility.

Navigate to: -Application/Function

Create a function with a name of HR_DEBUG_TOOLS. This function will not be based on a form so leave the 'Form' field blank. Specify a user function name HR_DEBUG_TOOLS. Add the above function to your navigator menu. Do not specify a Navigator prompt for this entry.

Navigate to: -Application/Menu

Query your navigator menu, for example: User Menu Name: F4 US HRMS Navigator Add a new sequence and select HR_DEBUG_TOOLS in the Function field.

<SAVE>

2. Obtain the process ID (PID). It works like the session ID above and tells PYUPIP what to trace. Enter the form you are working with and from the 'Special' menu select the HR Trace option. Select the 'On' button and note the PIDxx displayed. Exit the Trace form.

3. Start a UNIX session. Make sure that you are in a directory that you have write privileges to, and there is plenty of disk space. Using the PIDxx returned from step 2, type in the following at the UNIX prompt:
$PAY_TOP/bin/PYUPIP <apps user>/<apps password> PIDxx > PYUPIP.txt

The > PYUPIP.txt signifies that the output should be directed into a file called PYUPIP.txt. The file name can be anything you want it to be. Please note that the > sign is needed for re-directing the output to a file. This file will contain the trace file of the PL/SQL execution.

4. From the form to be traced, perform the necessary operations to capture the trace. When you are finished you will have to break the trace by entering <CNTL>-C that is (control key) C in your UNIX session where you started the trace.

CONCURRENT PROCESSES
The only way to perform this type of trace on a concurrent process is if the concurrent process to be run makes a call to a PL/SQL package that has the break points coded. To start the trace we must temporarily code the trace_on statements in the package body. The package body would then need to be compiled. IMPORTANT: After the tracing is complete, the original, without the trace_on statement MUST be compiled back to the database. If Its not compiled, then any process that calls this package without executing PYUPIP will hang, and eventually error with the following: ORA-20001: HR_51356_UTILITY_PIPE_TIMEOUT:

1. Make a backup of the package you want to trace. On a new line after the BEGIN of the procedure you are calling, add the following line: hr_utility.trace_on (null, 'ORACLE'); Compile the package. 2. Make sure that you are in a directory that you have write privileges to, and there is plenty of disk space. From the command line enter:
$PAY_TOP/bin/PYUPIP <apps user>/<apps password> ORACLE >PYUPIP.txt

3. Run what ever process executes this package, does not have to be concurrent process, but this is most common use. 4. After the process completes or errors, break the trace by entering <CNTL>C that is (control key) C in your UNIX session where you started the trace. 5. RECOMPILE TO ORIGINAL PACKAGE BACK TO THE DATABASE

White Paper Title April 2000 Contributing Authors: Peter Lewis, June Mukherjee, Nancy Snider Copyright Oracle Corporation 1995 All Rights Reserved Printed in the U.S.A. This document is provided for informational purposes only and the information herein is subject to change without notice. Please report any errors herein to Oracle Corporation. Oracle Corporation does not provide any warranties covering and specifically disclaims any liability in connection with this document. Oracle is a registered trademark and Enabling the Information Age, are trademarks of Oracle Corporation.

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: 415.506.7000 Fax 415.506.7200 Copyright Oracle Corporation 1995 All Rights Reserved