Adding a zoom using the CUSTOM

library
We can use the CUSTOM library to add or modify functionality without
making code changes to the standard form. All of the standard forms have
calls to the custom library from specific events that occur at runtime. We
can add code to the CUSTOM library to capture the events (such
as WHEN-NEW-FORM-INSTANCE, ZOOM, and so on) and then add code
to perform additional functionality. If you need to see which events are fired
on any particular form you can navigate to Help | Diagnostics | Custom
Code | Show Custom Events from the menu and you will see a message
appear each time an event is triggered (you may be prompted for
the apps password when you do this). The message will show the event
that was triggered.

The CUSTOM library is shipped with e-Business Suite and can be found in
the$AU_TOP/resource directory. It is recommended that you do not put all of
your code in the CUSTOM library. It is a good practice to create a sub
library per form and put your code in there. Then just write the call to the
sub library in the CUSTOM library. The sub library must be attached to the
CUSTOM library. The reason this is done is that there may well be several
developers working on the CUSTOM library all at once. If this model is
followed then developers can develop their code in isolation and it is easier
to maintain. This will become clearer when we go through the recipe.

What we are going to do in this recipe is create a zoom to our custom form.
We want to zoom from the People screen. We are going to pass in
the P_PERSON_ID parameter so that the record is automatically queried when
the form is opened. If you remember, we created this parameter inChapter
2, Oracle Forms. To create the zoom we must perform a number of tasks
as follows:

 Finding the short name of the form we want to zoom from

 Finding the name of a block
 Enabling a zoom
 Creating an object-specific library
 Attaching a library to the CUSTOM library
 Coding an event in the CUSTOM library
  Compiling libraries on the application server
 Adding a function to a menu
 Test the zoom

Finding the short name of the form we want

to zoom from
We will use the Help | About feature in Oracle constantly as a developer to
gain information about the name and version of the form we are in. In this
instance, we are going to determine the name of the form that we want to
enable a zoom from by using the Help | About menu item.

HOW TO DO IT...
To find out the item names from within EBS, perform the following steps:

1. Log in to Oracle with the UK HRMS Administrator responsibility.

2. Navigate to People | Enter and Maintain and the People window
will open.
3. Click the New button to exit the query find window.
4. Select Help | About Oracle Applications from the menu.
5. Scroll down to the Current Form section and you will see the form
name and the version, as shown in the following screenshot:
HOW IT WORKS...
You will often need to determine details about a form when we are
extending EBS. If you are ever dealing with Oracle Support they may well
ask for the form and version if you are experiencing a problem with a
professional form and this is where you will get the information from.

Finding the name of a block

We need to find the block name of the form we want to enable the zoom in.
To do this we need to open the form and navigate to the block we need to
enable the zoom in. We will do this by navigating to
the Help | Diagnostics menu item. Remember we may need
the apps password to be able to access this feature, but as a developer it
is essential to have access to this menu item.

HOW TO DO IT...
To find the name of the block, perform the following:

1. Log in to Oracle with the UK HRMS Administrator responsibility.

 2. Navigate to People | Enter and Maintain and the People window
will open.
3. Click the New button to exit the query find window.
4. From the menu toolbar select Help | Diagnostics | Examine as
shown in the following screenshot:

5. If prompted for the apps password then enter the apps password
and click OK.
6. The details of the block, field, and value are displayed as shown in
the following screenshot:

7. The name of the block we need to zoom from is called PERSON.

HOW IT WORKS...
We have been able to determine the block name that we want to zoom
from, that is, the PERSONblock.

Enabling a zoom
In the custom library, there is a procedure that will enable the zoom button
in the toolbar. We need to add code to enable the zoom.

HOW TO DO IT...
To enable the zoom button using the CUSTOM library, perform the
following:

1. In Forms Developer open the CUSTOM.pll library.

2. Navigate to PL/SQL Libraries | CUSTOM | Program
Units | CUSTOM (Package Body).
3. In the PL/SQL Editor, scroll down to the zoom_available procedure
and edit the code to add the form name as PERWSHRG and block
name as PERSON, as shown in the following screenshot:

Most of the code is already commented in the library already you

can copy and paste it and amend it as necessary.

Note: When we code in libraries we cannot reference items in a

form using the : (colon) notation. The two built-in
functions NAME_IN and COPY are used.NAME_IN is effectively getting
the value that is stored in the variable passed in. The COPY built-in
function copies the variable from one variable to another, for
example, COPY (NAME_IN (source) , destination);
4. Compile the code.
5. Save the library.
HOW IT WORKS...
The standard code in a form makes calls to the CUSTOM library when
certain triggers are executed at runtime. We need to add code to the
CUSTOM library to capture the form and the block that we want to perform
an action on.

Creating an object-specific library

We want to now create sub custom library. We will do this to limit the code
in the custom library so this step is really just good practice. You can create
a sub library that stores all of the module-specific custom code or to be
even more granular, create a sub library specific to the form. We are going
to create one sub library specific to the module.

The library XXHRCUST.pll and CUSTOM.pll are both available in the download bundle
if you cannot get your library to compile or you want to refer to them.

HOW TO DO IT...
To create a sub CUSTOM library, perform the following:

1. Open forms developer and click on PL/SQL Libraries in the

navigator.
2. Click the + icon from the left hand toolbar to add a new library.
3. Forms developer will generate a new library and give it a name
(such as LIB_001 for example).
4. The CUSTOM library has an attached library called FNDSQF. We will
be using functions from theFNDSQF library so we must also attach
this library to our XXHRCUST custom library.
5. Click the + icon from the left hand toolbar to attach
the FNDSQF library.
6. In the Attach Library window, select the FNDSQF library.
7. Click the Attach button.
8. When prompted to remove the path click Yes.

This is important as we do not want the full path referenced in the

attachment. The library will be transferred to the application tier and
recompiled. If the path is referenced there will be compilation errors.
9. Save the library.
10. Navigate to PL/SQL Libraries | XXHRCUST | Program Units.
11. Click the + icon on the left hand toolbar to create a new
package.
12. Set the name to XXPERWSHRG and select Package
Spec from the list of types as shown in the following screenshot:

13. In the PL/SQL Editor add a new procedure called event as

shown in the following screenshot:
14. Compile the package specification.
15. Close the PL/SQL Editor.
16. Navigate to PL/SQL Libraries | XXHRCUST | Program Units.
17. Click the + icon on the left hand toolbar to create a new
package body.
18. Set the name to XXPERWSHRG and select Package
Body from the list.
19. In the PL/SQL Editor, type the following code:

Note: The OTHER_PARAMS parameter that is passed in the call

tofnd_function.execute is surrounded by double quotes. If we were
hard-coding the parameter, the line would look like the following:
 OTHER_PARAMS=>'P_PERSON_ID="1234"');

20. Compile the program unit.

21. Save the library.
HOW IT WORKS...
We have created our own CUSTOM library for zooming from
the Person screen. This will allow us to modularize the code. It can be as
granular as required. For example, if there is a small development team we
can create a sub-custom library that is module-specific, that is, HR, PAY. If
the development team is large with lots of extensions then it's probably
better to have a sub-custom library per form.

Attaching a library to the CUSTOM library

We now want to attach our sub-custom library to the CUSTOM.pll.

HOW TO DO IT...
To add the XXHRCUST library to the CUSTOM library, perform the
following:

1. In Forms Developer open the CUSTOM.pll library.

2. Navigate to PL/SQL Libraries | CUSTOM | Attached Libraries.
3. Click the + icon on the left-hand toolbar to attach a library.
4. Select XXHRCUST.pll from the Attach Library pop-up and click
the Attach button.
5. When prompted to remove the path select Yes.
6. Save the library.

The navigator will now look like the following:

HOW IT WORKS...
We need to attach our sub-custom library to the CUSTOM.pll as it will call the
program unit for the zoom that we have created.

Coding an event in the CUSTOM library

In the CUSTOM library, there is a procedure that will enable the zoom
button in the toolbar. We need to add code to enable the zoom.

HOW TO DO IT...
To enable the zoom button using the CUSTOM library, perform the
following:

1. In Forms Developer open the CUSTOM.pll library.

2. Navigate to PL/SQL Libraries | CUSTOM | Program
Units | CUSTOM (Package Body).
3. In the PL/SQL Editor scroll down to the zoom_available procedure
and add the code as shown in the following screenshot (most of
the code is already commented in the library — you can copy and
paste it and amend it as necessary):
 4. Compile the code.
HOW IT WORKS...
In the event procedure in the CUSTOM library, we need to make a call to
our procedure to capture the ZOOM event. Whenever the user clicks on the
zoom button in the Person screen the Societies form will open, passing in
the PERSON_ID as a parameter. The form will automatically query back the
employee in the Person screen we zoomed from.

Compiling libraries on the application

server
We now need to transfer the two libraries to the application server and
compile them. All libraries are in the $AU_TOP/resource directory. Oracle will
first attempt to find the .plx file (the executable) and then will look for
the .pll file. The command for compiling libraries is similar to that of forms.

HOW TO DO IT...
To test the zoom, perform the following:

1. Open WinSCP and connect to the application tier.

2. Navigate to the $AU_TOP/resource directory and rename the
existing CUSTOM.pll (to back it up).
 3. Transfer the XXHRCUST.pll and CUSTOM.pll libraries to
the $AU_TOP/resource directory.
4. Open Putty and change directory to $AU_TOP/resource.
5. Compile XXHRCUST.pll with the following command (for
the userid parameter you need to enter the apps password for
your environment by replacing <apps pwd>):
6. frmcmp_batchmodule_type=library
module=$AU_TOP/resource/XXHRCUST.pll userid=apps/<appspwd>
output_file=$AU_TOP/resource/XXHRCUST.plx
compile_all=special
7.

8. Compile CUSTOM.pll with the following command:

9. frmcmp_batchmodule_type=library
module=$AU_TOP/resource/CUSTOM.pll userid=apps/<appspwd>
output_file=$AU_TOP/resource/CUSTOM.plx compile_all=special
10.

HOW IT WORKS...
We have compiled the two libraries. As the XXHRCUST library is a
dependent of the CUSTOM library we must compile the XXHRCUST library
first.

Adding a function to a menu

The form function needs to be added to the menu that we are zooming into.
Therefore in this case, we need to add our custom form
function XXHR_EMP_SOCIETY to the menu that is used by the UK HRMS
Manger responsibility. If the function is not assigned to the menu that the
responsibility uses the user will get the following error message when
attempting to zoom:

HOW TO DO IT...
To add a function to the menu that is used by the UK HRMS
Manager responsibility, perform the following:

1. Log in to Oracle with the System Administrator responsibility.

2. Navigate to Security | Responsibility | Define and
the Responsibilities window will open.
3. Press F11 to enter a query.
4. Enter UK HRMS Manager in the Responsibility Name field and
press Ctrl + F11.
5. Copy the value that is in the Menu field (in this case it is UK
HRMS Navigator).
6. Close the form.
7. Navigate to Application | Menu and the Menus window will open.
8. Press F11 to enter a query.
9. Enter UK HRMS Navigator in the User Menu Name field and
press Ctrl + F11.
10. In the detail block enter a new record with the following details:
Seq Prompt Submenu Function
800 Employee Clubs and Societies

11.
12. Save the form.

Note that we have not entered any data in the Prompt field. This is
because we do not want the Societies form available from the main
menu. If we did then we would put a Prompt value in here and the
form would open with the query find window as no parameter would
be passed in.
HOW IT WORKS...
We have added the function to the menu used by the UK HRMS
Manager responsibility. You will notice that there is no text in
the Prompt field, which means that the user can zoom to
the Societies form from this menu, but the Societies form is not available
to the user from the navigator.

Testing the zoom

Now we can test how the zoom works. When we zoom to
the Societies form we are passing the parameter P_PERSON_ID. Therefore,
we would not expect to see the query find window as we coded this into the
form in Chapter 2, Oracle Forms. The employee record should
automatically query the employee that was in the People form that we
zoomed from.

HOW TO DO IT...
To test the zoom, perform the following:

1. Log in to Oracle with the UK HRMS Manager responsibility.

2. Navigate to People | Enter and Maintain and the People window
will open.
3. Query back an employee record.
4. Click on the zoom button which will now be enabled.

5. The Employee Societies Form will open and the employee

record will be automatically queried back as shown in the following
screenshot:
HOW IT WORKS...
We have tested that the user can now zoom from the Person screen when
using the UK HRMS Manager responsibility. The record has automatically
queried back data of the employee from the Person screen that we
zoomed from.