Document 130374.

30/03/15 10:55

PowerView is Off
Dashboard

Knowledge

Service Requests

Javier (Available)

(0)

Contact Us

Help

Patches & Updates

Give Feedback...

Using PYUPIP in Oracle HRMS (Doc ID 130374.1)

Document Details

APPLIES TO:
Oracle Human Resources
Information in this document applies to any platform.

PURPOSE
This reference note has been written to help customers understand and create PYUPIP traces that can be used in debugging
HRMS issues.
The information in this document has been reviewed and is current as of 25-Apr-2006.

DETAILS

Type:
Status:
Last Major
Update:
Last Update:

REFERENCE
PUBLISHED
10-Jan-2014
10-Jan-2014

Related Products
Oracle Human Resources
Information Centers

Using PYUPIP - Oracle HRMS

Instructions for the reader: This document does not contain bugs/patches as these topics are addressed in the Current
Issues and Patch articles referenced at the bottom of this document.
HRMS Trace Options
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

To Bottom

Overview
When to use
How to add the PYUPIP tool to your menu
Running PYUPIP for a forms issue
Running PYUPIP in Self Service Applications (.jsp)
Running PYUPIP on Concurrent Process, Report
Running PYUPIP on SQL scripts
PYUPIP on System Extract
Reading a PYUPIP trace with an error
PYUPIP on External Process Archive
Breakpoints
PYUPIP trace for APIs directly into DBMS_OUTPUT

Trace Option Details

1. Overview
PYUPIP is a utility, unique to the Oracle HRMS Suite, and is used for tracing the flow of HRMS PL/SQL code. The
database trace pipe allows the user to record the flow of HRMS PL/SQL code and displays the sequence of events
within a process. The PL/SQL code can reside in a script or in a package. PYUPIP displays all the different
breakpoints (markers) that are encountered when the code is executed. This utility is used exclusively by HRMS
developers, so it is not used outside this product group.
The breakpoints (markers) are set by the developer in the PL/SQL code itself. However, additional breakpoints
(markers) 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.
NOTE: In this scenario, Oracle Support Services and Oracle Development may need to request multiple PYUPIP
traces to be run to capture this data.

PYUPIP can be launched in multiple ways:

From Within The Professional User Interface (PUI)
From Unix session
From Self Service Applications

Information Center: Oracle EBusiness Suite HRMS / HCM

[1099813.2]
Information Center: EBS Core
HR 11i to R12.2 [1322119.2]
Information Center: EBS Core
HR 11i to R12.2 [1337752.2]

Document References
Setup & Instructions to Run PYUPIP HR Trace in the
Applications (Trace File and
DBMS_PIPE) and PYUPIP
Against Packages [301343.1]
Demonstration of Running
PYUPIP [339169.1]
How to Run PYUPIP Trace for
Payroll Archiver? [242207.1]
Generating PYUPIP
Information from a Self
Service Type Page (.jsp)
[281071.1]
How To Perform Forms
Runtime Diagnostics (FRD)
Tracing in Applications 11i
[167635.1]
Show More
Recently Viewed
Using PYUPIP in Oracle HRMS
[130374.1]
CREATE_GB_PERSONAL_PAY_METHOD
API Fails with ORA-20001: FLEX-ID
DOES NOT EXIST [392343.1]
Troubleshooting Guide for HRMS API
Errors - ORA-20001 and APP Errors
[152259.1]
How To Add The Additional Job Details
Descriptive Flexfield In SSHR ?
[458422.1]
ORA-20001: Flex-Context not Found
Error Running Create and Maintain
Company Cost Center Organizations
Process [437187.1]
Show More

[top]
https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=2344&id=130374.1&_afrWindowMode=0&_adf.ctrl-state=1aes8d6ldv_4#q7

Pgina 1 de 8

Document 130374.1

30/03/15 10:55

2. When to use
PYUPIP can be used under different scenarios where it may be necessary to monitor the execution of PL/SQL (any
operation that calls PL/SQL).
Typical examples:
Forms - Errors or unexpected results on a form.
SQL scripts - Debugging patch script failures, or problems with API's
Concurrent processes and reports - Errors or unexpected results.
There are different methodologies depending on what you want to monitor.
[top]
3. How to add the PYUPIP tool to your menu
In order to have the ability to run a PYUPIP trace, you must have a certain function added to your Navigator menu.
It is possible this step has already been performed, so you should first check to see if it has already been enabled before
moving forward with the instructions below.
Within the Oracle application :
1) Check to see if HR TRACE is an option off the Toolbar
Tools> HR Trace
If this function is not there, please continue with implementing the set up steps in this section.
If this function is there, skip follow the set up steps below, and you may move forward to the 'Running a PYUPIP trace on
a forms issue' section.
Create a function with a name of HR_DEBUG_TOOLS.
As System Administrator > Application / Function
Navigate to the Description Tab
Add the following:
Function................HR_DEBUG_TOOLS
User Function Name......HR_DEBUG_TOOLS
Type....................SUBFUNCTION
Add nothing to the other Tabs - Form, Web HTML, Web Host, Region
2) Add the above function to your navigator menu. As System Administrator > Application / Menu
Query the menu that is tied to the responsibility you are using R11.5 Seeded responsibility and associated menu
Responsibility..........Menu............User Menu Name
US Super HRMS Manager...US_SHRMS_NAV....US HRMS Navigator
US HR Manager...........US_HR_NAV.......US HR Navigator
Look in the column called Function for HR_DEBUG_TOOLS.
If the Function HR_DEBUG_TOOLS is not already there, insert a new line and add this function.
Navigate to the bottom of the form and insert a new record - Green + icon
Click in the Function box and then click on the LOV
Choose the Function (HR_DEBUG_TOOLS) that you created in step 1 above.
Do not specify a Navigator prompt for this entry.
Save your changes
You now have the ability to run a PYUPIP trace on a form in the application.
[top]
4. Running PYUPIP for a forms issue
This 11 minute online viewlet demonstrates Running PYUPIP trace on a form.
Review Metalink Note 339169.1 - Demonstration of Running PYUPIP for the demonstration
https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=2344&id=130374.1&_afrWindowMode=0&_adf.ctrl-state=1aes8d6ldv_4#q7

Pgina 2 de 8

Document 130374.1

30/03/15 10:55

Review Metalink Note 339169.1 - Demonstration of Running PYUPIP for the demonstration
Review Metalink Note 160470.1 - Release 11.0.x PYUPIP on a Form
Review Metalink Note 160469.1 - Release 11.5.x PYUPIP on a Form
[top]
5. Running PYUPIP in Self Service Applications (.jsp)
HRMS Self Service
As .jsp pages become more integrated to the HRMS suite, it becomes necessary to generate trace information
from those pages.
Review Metalink Note 281071.1 - Generating PYUPIP Information from a Self Service Type Pages (.jsp)
Specific to Oracle Advanced Benefits:
In FP.J new functionality has been added to allow tracing of self-service benefits functions. If you experience
enrollment problems during system testing, or while in production, you can generate a trace file for an individual
user to track the source of the problem. Set the profile option OAB: Enable Self-Service Benefits Trace to select the
module that you want to trace.
There are (4) specific modules in Benefits that can be traced in this manner:
BENACTBR (Activity Base Rate): This profile option enables a trace when the user changes a coverage
amount.
BENDISRT (Distribute Rates): This profile option enables a trace when the user changes enterable rates
that calculate other dependent rates, such as parent/child rates or annual-to-communicated rates.
BENELINF (Election Information): This profile option enables a trace when the user changes any election
information on the Benefits Selections Page and clicks Next.
BENOLLET (On-Line Life Event): This profile option traces the Participation Process for a single user when
the user clicks Next on the Dependents and Beneficiaries page.
Review Metalink Note 360312.1 - How to Do a PYUPIP Trace in SSBEN from HR_PF.J Onwards for detailed
instructions.
[top]
6. Running PYUPIP on Concurrent Process, Report
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.
First step Find name of the pl/sql package:
SYSADMIN: Concurrent > Process > Definition > query name of process to trace
Query executable from Definition: Concurrent > Executable > find package name
Note: this will only work for those concurrent processes that are defined as a pl/sql package

Here are the steps after you retreive the package name:
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. Start a UNIX session. Make sure that you are in the directory that you have write privileges to, and there is plenty of
disk space.
From the command line enter:
$PAY_TOP/bin/PYUPIP username/password ORACLE > PYUPIP.txt
3. Run whatever process executes this package, does not have to be concurrent process, but this is the most common
https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=2344&id=130374.1&_afrWindowMode=0&_adf.ctrl-state=1aes8d6ldv_4#q7

Pgina 3 de 8

Document 130374.1

30/03/15 10:55

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

Note: To run PYUPIP trace for a single-user within a specific package see Appendix (for advanced users only) in Note
301343.1
Review Metalink NOTE:301343.1 - Setup & Instructions to Run - PYUPIP HR Trace in the Applications (Trace File and
DBMS_PIPE) and PYUPIP Against Packages
[top]
7. Running PYUPIP on SQL Script
Use this method when debugging patch script failures, problems with API's or fast formulas/functions by
adding trace statements to package, SQL script or formula/function.
Basically, PYUPIP may be used to trace any SQL script that calls a package as well as the package itself.
SQL SCRIPTS - from SQL PROMPT
1. Start a UNIX session (we will call it window 1) and log into SQL*Plus as /.
Get the SQL*Plus session id by executing the following SQL statement:
SELECT userenv('sessionid')
FROM dual;
It will return something like: (take note of 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 returned from window 1, enter the following at the UNIX prompt:
$PAY_TOP/bin/PYUPIP pwd>@<oracle sid> <sessionid> | tee -a 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 -C (that is control key) C.
Your trace is now recorded in the file PYUPIP.txt
https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=2344&id=130374.1&_afrWindowMode=0&_adf.ctrl-state=1aes8d6ldv_4#q7

Pgina 4 de 8

Document 130374.1

30/03/15 10:55

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 don't 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
$PAY_TOP/bin/PYUPIP username/password ORACLE > PYUPIP.txt
3. Open another UNIX session and restart your patch.

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.

[top]
8. PYUPIP on System Extract

Review Metalink Note 302046.1 - How To Run a PYUPIP Trace on System Extract

[top]
9: Reading PYUPIP Trace Output
When running a PYUPIP trace where an error occurs, the trace will capture the package and procedure where the error
occurs.
Typically if an error is captured, it will appear at the end of the trace output.
Reviewing PYUPIP trace files for issues where an error is not encountered, becomes a bit more difficult. An example
would be where there is no error encountered, but the results on the form are not what was expected. (Ex. rates do not
calculate correctly)

Example update and error in the HRMS application:

You Are Updating An Employee Marital Status, and receive the following error on the form:
Error :BEN_92113_NOPTUBGPPET
PYUPIP OUTPUT:
------------------------person sys type EMP
156
type and count 0R
151
ben_assignment_internal.copy_empasg_to_benasg Spouse Fammem:
155
l_pet_spt: ben_assignment_internal.copy_empasg_to_benasg
185
https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=2344&id=130374.1&_afrWindowMode=0&_adf.ctrl-state=1aes8d6ldv_4#q7

Pgina 5 de 8

Document 130374.1

30/03/15 10:55

l_pet_spt: ben_assignment_internal.copy_empasg_to_benasg
l_bgp_id: 1 ben_assignment _internal.copy_empasg_to_benasg

185
185 < Status:0

Identifying The Package/Procedure

ben_assignment_internal.copy_empasg_to_benasg
The actual Package where the trace is failing is ben_assignment_internal
The actual Procedure where the trace is failing is copy_empasg_to_benasg
Breakpoints (markers)
Breakpoints in the plsql code, also referred to as markers, mark sections of the code so that they are easily identified.
When the code fails at a certain breakpoint, you can identify the package and procedure where the failure occurs.
Additionally, you can place trace statements in the code of that specific package and identify data or lack of data related
to the issue.
In the example above, the failure occurs at breakpoint 185.
l_bgp_id: 1 ben_assignment _internal.copy_empasg_to_benasg

185 <

Identify File Containing This Package

Support Services will typically request the file name and version of the package that is failing in the output
of the PYUPIP trace. Once this information is obtained, versions are reviewed and compared to current
and potentially higher versions of the package.
Support services and/or development may insert additional debug statements into the failing package to
retrieve more details necessary to troubleshooting the issue. If so, an additional request for a PYUPIP will
be necessary to initiate the debug statements.
At a sqlplus prompt execute:
Select Text
From All_Source
Where Name = Upper('ben_assignment_internal')
And Line = 2;
SQL output displayed:
beasgbsi.pkh and beasgbsi.pkb

[top]
10: PYUPIP Trace for External Process Archive

Metalink Note 242207.1 - How to Run PYUPIP Trace for External Process Archive
[top]
11: Breakpoints
The markers or 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 trace output file. This gives the user a
clear picture of what the code is doing and hopefully the information necessary to remedy the issue.

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)
https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=2344&id=130374.1&_afrWindowMode=0&_adf.ctrl-state=1aes8d6ldv_4#q7

Pgina 6 de 8

Document 130374.1

30/03/15 10:55

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 additional 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

20

successfully found formula id

Formula_id = 12333
pyusddwp.insert_formula

30

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

Reference: Original White Paper: CR: 276027

[top]
12: PYUPIP trace for APIs directly into DBMS_OUTPUT

Review Metalink Note 1528262.1 - How to get the PYUPIP trace for APIs directly into DBMS_OUTPUT

[top]

Copyright 2003 Oracle Corporation. All rights reserved. Oracle is a registered trademark of Oracle Corporation. Various
product and service names referenced herein may be trademarks of Oracle Corporation. All other product and service names
mentioned may be trademarks of their respective owners.
Disclaimer: This document is provided for information purposes only and the contents hereof are subject to change without
notice. Oracle Corporation does not warrant that this document is error-free, nor does it provide any other warranties or
conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness
for a particular purpose. Oracle Corporation specifically disclaims any liability with respect to this document and no contractual
obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any
form or by any means, electronic or mechanical, for any purpose, without the prior written permission of Oracle Corporation.

REFERENCES
https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=2344&id=130374.1&_afrWindowMode=0&_adf.ctrl-state=1aes8d6ldv_4#q7

Pgina 7 de 8

Document 130374.1

NOTE:301343.1 Against Packages

NOTE:339169.1 NOTE:242207.1 NOTE:281071.1 NOTE:167635.1 NOTE:302046.1 NOTE:360312.1 -

30/03/15 10:55

Setup & Instructions to Run - PYUPIP HR Trace in the Applications (Trace File and DBMS_PIPE) and PYUPIP
Demonstration of Running PYUPIP
How to Run PYUPIP Trace for Payroll Archiver?
Generating PYUPIP Information from a Self Service Type Page (.jsp)
How To Perform Forms Runtime Diagnostics (FRD) Tracing in Applications 11i
How To Run a PYUPIP Trace on System Extract?
How to Do a PYUPIP Trace in SSBEN from HR_PF.J Onwards

NOTE:142586.1 - How to Use Parameter Remove_Act

NOTE:160469.1 - How to Setup and Run PYUPIP on a Form
NOTE:160470.1 - R11.0/R12.0 How to Setup and Run PYUPIP on a Form
NOTE:1528262.1 - How to get the PYUPIP trace for APIs directly into DBMS_OUTPUT?

Attachments
PYUPIP (25.96 KB)

Related
Products
Oracle E-Business Suite > Human Capital Management > Human Resources > Oracle Human Resources

Keywords
DEBUGGING; PYUPIP; TRACE; TRACING OPTIONS; TROUBLESHOOT
Back to Top
Copyright (c) 2015, Oracle. All rights reserved.

Legal Notices and Terms of Use

Privacy Statement

https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=2344&id=130374.1&_afrWindowMode=0&_adf.ctrl-state=1aes8d6ldv_4#q7

Pgina 8 de 8