Customizing Oracle Applications with the
CUSTOM Library
The CUSTOM library
allows extension of Oracle Applications without modification of
Oracle Applications
code. You can use the CUSTOM library for customizations such as Zoom (such as
moving to another form and querying up specific records), enforcing business
rules (for example, vendor name must be in uppercase letters), and disabling fields
that do not apply for your site.
You write code in the
CUSTOM library, within the procedure shells that are provided.
All logic must branch
based on the form and block for which you want it to run. Oracle Applications
sends events to the CUSTOM library. Your custom code can take effect based on
these events.
Important:
The
CUSTOM library is provided for the exclusive use of Oracle Applications
customers. The Oracle Applications products do not supply any predefined logic
in the CUSTOM library other than the procedure shells described here.
Writing Code for the CUSTOM Library
The CUSTOM library is
an Oracle Forms Developer PL/SQL library. It allows you to take full advantage
of all the capabilities of Oracle Forms Developer, and integrate your code directly
with Oracle Applications without making changes to Oracle Applications code.
The as-shipped CUSTOM
library is located in the AU_TOP/resource directory (or platform equivalent).
Place the CUSTOM library you modify in the AU_TOP/resource directory in order
for your code to take effect.
After you write code
in the CUSTOM procedures, compile and generate the library using Oracle Forms.
Then place this library into $AU_TOP/resource directory (or platform
equivalent). Subsequent invocations of Oracle Applications will then run this
new code.
Warning:
If
there is a .plx (compiled code only) for a library, Oracle Forms Developer
always uses the .plx over the .pll. Therefore, either delete the .plx file (so
your code runs directly from the .pll file) or create your own .plx file using
the Oracle Forms compiler. Using the .plx file will provide better preformance
than using the .pll file. Depending on your operating system, a .plx may not be
created when you compile and save using the Oracle Forms Developer. Form
Builder. In this case, you must generate the library using the Oracle Forms
Developer compiler from the command line (using the parameter COMPILE_ALL set
to Yes).
The specification of
the CUSTOM package in the CUSTOM library cannot be changed in any way. You may
add your own packages to the CUSTOM library, but any packages you add to this
library must be sequenced after the CUSTOM package. To ensure that your
packages remain sequenced after the CUSTOM package even after a conversion from
a .pld file, when program units are alphabetized, we recommend you name your
packages with characters that come after C (for example, we recommend you name
your own packages with names that begin with USER_).
Note:
Custom
packages must explicitly indicate 'AUTHID DEFINER' in the package header. Even
though 'AUTHID DEFINER' is the default, it must be specified in a custom
package header.
Coding
Considerations and Restrictions
Be aware of the open
form environment in which Oracle Applications operate. Also, each running form
has its own database connection.
The following
considerations and restrictions apply to the CUSTOM library and any libraries you attach to CUSTOM:
•
You
cannot use any SQL in the library. However, you can use a record group to issue
SELECT statements, and you can use calls to stored procedures for any other DML
operations such as updates, inserts, or deletes.
•
Oracle
Forms global variables in your code are visible to all running forms.
Attaching
Other Libraries to the CUSTOM Library
You may attach other
libraries to the CUSTOM library. However, you cannot attach the
APPCORE library to
CUSTOM because it would cause a recursion problem (because
CUSTOM is attached to
APPCORE). You may attach the APPCORE2 library to CUSTOM. The APPCORE2 library
duplicates most APPCORE routines with the following packages:
•
APP_ITEM_PROPERTY2
•
APP_DATE2
•
APP_SPECIAL2
These packages contain
the same routines as the corresponding APPCORE packages. Follow the
documentation for the corresponding APPCORE routines, but add a 2 to the
package names. For example, where you would have a call to the APPCORE routine
APP_ITEM_PROPERTY.SET_PROPERTY in a form, you can have a corresponding call to
the APPCORE2 routine APP_ITEM_PROPERTY2.SET_PROPERTY in the CUSTOM library.
The CUSTOM library
comes with the FNDSQF library already attached. FNDSQF provides Oracle
Applications routines for function security (for opening forms), flexfields,
and other utility routines.
Altering
Oracle Applications Code
Frequently you need to
know the names of blocks and items within Oracle Applications forms for your
CUSTOM logic. You should use the Examine feature available on the
Help->Diagnostics menu while running the form of interest; it will give you
easy access to all object names. You should not open Oracle Applications forms
in the Oracle Forms Developer to learn this information.
You should exercise
caution when changing any properties or values of items in the form from which
CUSTOM logic is invoked. The CUSTOM library is intended to be a mechanism to
augment Oracle code with your own. Using the CUSTOM library to alter Oracle
code at runtime may bypass important validation logic and may jeopardize the
integrity of your data. You should thoroughly test all logic you add to the
CUSTOM library before using it in a production environment.
Following
Coding Standards in the CUSTOM library
Within the CUSTOM
library, you are free to write almost any code supported by Oracle Forms
Developer, so long as you follow all Oracle Applications coding standards.
Where you would
normally use Oracle Applications routines in the APPCORE library, you should
use the corresponding routine in the APPCORE2 library (which you would attach
to your copy of the CUSTOM library).
If you use Zoom or the
CUSTOM library to invoke forms that you have developed, those forms must adhere
completely to all of the Oracle Applications coding standards.
Important:
To
invoke another form, use the function security routines in the FND_FUNCTION
package. Do not use the CALL_FORM built-in since the Oracle Applications
libraries do not support it.
Events Passed to the CUSTOM Library
The CUSTOM library
receives two different kind of events, generic and product-specific. Generic
events are common to all the forms in Oracle Applications. These events are:
•
WHEN-FORM-NAVIGATE
•
WHEN-NEW-FORM-INSTANCE
•
WHEN-NEW-BLOCK-INSTANCE
•
WHEN-NEW-RECORD-INSTANCE
•
WHEN-NEW-ITEM-INSTANCE
•
WHEN-VALIDATE-RECORD
•
SPECIALn
(where n is a number between 1 and 45)
•
ZOOM
•
EXPORT
•
KEY-Fn
(where n is a number between 1 and 8)
Logic you code for
WHEN-FORM-NAVIGATE, WHEN-NEW- BLOCK-INSTANCE, WHEN-NEW-RECORD-INSTANCE, or
WHEN-NEW-ITEM-INSTANCE fires after any existing logic in those triggers for the
form, block or item.
Logic you code for
WHEN-NEW-FORM-INSTANCE fires during the call to APP_STANDARD.EVENT. That call
may be anywhere within existing WHEN-NEW-FORM-INSTANCE logic in the form.
Logic you code for
WHEN-VALIDATE-RECORD fires during the call to
APP_STANDARD.EVENT or
FND_FLEX.EVENT. One of those calls may be within existing WHEN-VALIDATE-RECORD
logic in the form or block, depending on how the form was originally coded.
Logic you code for
SPECIALn, where n is a number, fires before any logic in the existing SPECIALn
trigger (if there is one).
The ZOOM event occurs
when the user invokes Zoom from the menu (View->Zoom) or the toolbar. The
EXPORT event occurs after an export operation is complete (File->Export).
Logic you code for
KEY-Fn events, where n is a number between 1 and 8, fires when the user presses
the corresponding function key or key combination. Use the
Help->Keyboard menu
choice to determine the actual key combination corresponding to the appropriate
function (F1-F8). Oracle Applications does not currently provide any logic
associated with these KEY-Fn events.
The CUSTOM library
also receives some product-specific events associated with the business rules
of that product (for example, the NAVIGATE event in Oracle Human Resources).
Please refer to the Open Interfaces
Manual for your Oracle Applications product to see what product-specific
events, if any, are passed to CUSTOM.
When to Use the CUSTOM Library
There are several main
cases for which you can code logic using the CUSTOM library. Each of these
cases must be coded differently.
•
Zoom
- The addition of user-invoked logic on a per-block basis. A Zoom typically
consists of opening another form and (optionally) passing parameter values to
the opened form through the Zoom logic.
•
Logic
for generic events - Augment Oracle Applications logic for certain generic form
events such as WHEN-NEW-FORM-INSTANCE or
WHEN-VALIDATE-RECORD.
You can use generic events to change field prompts and other properties, hide
fields, add validation, and more.
•
Logic
for product-specific events - Augment or replace Oracle Applications logic for
certain product-specific events that enforce business rules.
•
Setting
visual attributes - Use the CUSTOM library to change the visual attributes of
Oracle Applications
fields at runtime. Use the Oracle Forms built-in
SET_VA_PROPERTY to set
the properties of the CUSTOM1-CUSTOM5 visual attributes, and then use
APP_ITEM_PROPERTY2.SET_PROPERTY to apply the visual attribute to an item at
runtime.
Coding Zoom
Zoom allows the
addition of user-invoked logic on a per-block basis. For example, you may want
to allow access to the Vendors form from within the Enter Purchase Order form
while the user is in the PO Header block of that form. You can enable Zoom for
just that block, and when the user invokes it, you can open the Vendors form.
Only Oracle
Applications customers use the Zoom feature; Oracle Applications products do
not ship any predefined Zoom logic.
Zoom behaves as
follows:
•
Oracle
Applications provides a menu entry and a button on the toolbar for the user to
invoke Zoom when available. The button and the menu entry are disabled unless
Zoom logic has been defined in the CUSTOM library for that form and block.
•
Whenever
the cursor changes blocks in the form, the form calls the
ZOOM_AVAILABLE
function in the CUSTOM library. If this function returns
TRUE, then the Zoom
entries on the menu and toolbar are enabled; if it returns FALSE, then they are
disabled.
•
If
the Zoom entries are enabled, then when the user invokes Zoom the form calls
the ZOOM event code in the CUSTOM library. You write code for this event that
branches based on the current form and block.
To
code Zooms into the CUSTOM library
Follow these steps to
code Zooms into the CUSTOM library:
1.
Add a branch to the CUSTOM.ZOOM_AVAILABLE function that
specifies the form and block where you want a user to be able to invoke Zoom.
2.
Add a branch to the CUSTOM.EVENT procedure for the ZOOM
event.
Inside that branch,
specify the form and block where you want a user to be able to invoke Zoom. Add
the logic you want to occur when the user invokes Zoom.
Supporting
Multiple Zoom Events for a Block
Oracle Applications
provides a referenced list of values (LOV) and corresponding referenced
parameter for Zooms in all forms built using the TEMPLATE form (including
custom forms). They are the following:
•
List
of values: APPCORE_ZOOM
•
Parameter:
APPCORE_ZOOM_VALUE
Use the LOV and
parameter to provide users with an LOV where you have more than one Zoom from a
particular block.
To
code the Zoom LOV into the CUSTOM library:
In the CUSTOM library
(within your ZOOM event code):
1.
Create a record group and populate it with names and
values of available Zooms for the block.
2.
Attach the record group to the APPCORE_ZOOM list of
values (LOV).
3.
Call show_lov to display the LOV to the user.
4.
If user picks a Zoom, the value is returned into the
APPCORE_ZOOM_VALUE parameter in the form.
5.
Retrieve the parameter value and branch your Zoom code
accordingly.
Example Code
The following example
sets up a Zoom LOV that contains three choices.
procedure event(event_name
varchar2) is form_name varchar2(30)
:=
name_in('system.current_form');
block_name varchar2(30) :=
name_in('system.cursor_block');
zoom_value varchar2(30); group_id recordgroup; col_id
groupcolumn; begin IF (event_name = 'ZOOM') then if (form_name = 'FNDSCAUS' and block_name = 'USER') then
-- set up the record group group_id := find_group('my_zooms'); if id_null(group_id) then group_id := create_group('my_zooms'); col_id :=
add_group_column(group_id,
'NAME', char_column, 30);
col_id := add_group_column(group_id, 'VALUE', char_column,
30);
set_lov_property('APPCORE_ZOOM',
GROUP_NAME, 'my_zooms');
else
Delete_Group_Row( group_id, ALL_ROWS
); end if;
Add_Group_Row( group_id, 1);
Set_Group_Char_Cell('my_zooms.NAME', 1,
'Personal Profiles Form');
Set_Group_Char_Cell('my_zooms.VALUE', 1,
'FNDPOMSV');
Add_Group_Row( group_id, 2);
Set_Group_Char_Cell('my_zooms.NAME', 2,
'System Profiles Form');
Set_Group_Char_Cell('my_zooms.VALUE', 2,
'FNDPOMPV'); Add_Group_Row( group_id, 3);
Set_Group_Char_Cell('my_zooms.NAME', 3,
'Responsibilities Form');
Set_Group_Char_Cell('my_zooms.VALUE', 3,
'FNDSCRSP');
-- test the LOV results and open
different forms
if show_lov('APPCORE_ZOOM') then zoom_value := name_in(
'parameter.APPCORE_ZOOM_VALUE');
if zoom_value = 'FNDPOMPV' then fnd_function.execute(
FUNCTION_NAME=>'FND_FNDPOMPV',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y'); elsif zoom_value = 'FNDSCRSP' then
fnd_function.execute(
FUNCTION_NAME=>'FND_FNDSCRSP',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y'); elsif zoom_value = 'FNDPOMSV' then
fnd_function.execute(
FUNCTION_NAME=>'FND_FNDPOMSV',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y');
end if; end if;
end if; -- end of form branches within Zoom event
branch
END IF; -- end of branches on EVENT_NAME
end event;
----------------------------------------------------------
Coding Generic Form Events
You can code logic
that fires for a particular form and block at a particular form event. You can
code logic for the following events:
•
WHEN-FORM-NAVIGATE
•
WHEN-NEW-FORM-INSTANCE
•
WHEN-NEW-BLOCK-INSTANCE
•
WHEN-NEW-RECORD-INSTANCE
•
WHEN-NEW-ITEM-INSTANCE
•
WHEN-VALIDATE-RECORD
•
SPECIALn
(where n is a number between 1 and 45)
•
ZOOM
•
EXPORT
•
KEY-Fn
(where n is a number between 1 and 8)
Some Oracle
Applications forms, such as most Oracle Human Resources forms, may provide
additional events that call the CUSTOM library. These additional events are
listed in the documentation for the product that owns the form. You can code
logic in the CUSTOM library for such events the same way you would code logic
for generic form events.
To
code logic for generic form events into the CUSTOM library:
Add a branch to the
CUSTOM.EVENT procedure for the particular event you want. I nside that branch,
specify the form and block where you want your logic to occur. Add the logic
you want to occur when that event fires for the form and block you specify.
Example Code
The
following example changes various field properties and prompts. This example
also sets up and applies a custom visual attribute (CUSTOM1), and prevents
inserts and updates to a block. procedure event(event_name varchar2) is
form_name varchar2(30) :=
name_in('system.current_form');
block_name varchar2(30) :=
name_in('system.cursor_block');
begin if (event_name = 'WHEN-NEW-FORM-INSTANCE') then if (form_name =
'FNDSCAUS') then
--
-- Hide the Fax field, force the E-mail
-- field to be uppercase,
-- make the description field required,
-- change the person field
-- color to magenta, change the
Supplier -- field prompt.
--
app_item_property2.set_property('user.fax',
DISPLAYED, PROPERTY_OFF); app_item_property2.set_property(
'user.email_address',
CASE_RESTRICTION, UPPERCASE);
app_item_property2.set_property('user.description',
REQUIRED,
PROPERTY_ON);
app_item_property2.set_property('user.employee_name',
BACKGROUND_COLOR,
'r255g0b255');
app_item_property2.set_property(
'user.supplier_name',
PROMPT_TEXT, 'Vendor Name');
- -- Set up CUSTOM1 visual attribute as
bright yellow.
--
set_va_property('CUSTOM1',
BACKGROUND_COLOR,
'r255g255b0');
-- apply CUSTOM1 visual
attribute to fields
-- (color will override
-- gray of disabled fields, but will not
-- override pale yellow
-- of required fields)
--
app_item_property2.set_property('user.supplier_name',
VISUAL_ATTRIBUTE, 'CUSTOM1');
app_item_property2.set_property('user.email_address', VISUAL_ATTRIBUTE, 'CUSTOM1');
ELSIF (event_name =
'WHEN-NEW-BLOCK-INSTANCE') then
IF (form_name = 'FNDSCAUS' and block_name = 'USER_RESP') THEN
-- prevent users from adding
-- responsibilities
set_block_property(block_name,
insert_allowed,
property_false);
set_block_property(block_name,
update_allowed,
property_false); END IF;
END IF; -- end of branches on EVENT_NAME
end event;
----------------------------------------------------------
Coding Product-Specific Events
Please refer to the Open Interfaces Manual or User's Guide for your Oracle
Applications product to see what product-specific events, if any, are passed to
CUSTOM. For product-specific events passed by Oracle Application Object
Library, see: Product-Specific Events in Oracle Application Object Library,
page 28-11.
To
code logic for product-specific events into the CUSTOM library:
1.
Add a branch to the CUSTOM.EVENT procedure for the
particular product– specific event you want.
Within that branch,
add logic for that specific business function
2.
If custom execution styles are supported for this
product–specific event (many product–specific events do not support custom
execution styles), add a branch to the CUSTOM.STYLE function that specifies the
execution style (before, after, override, or standard) you want for your
product–specific event logic. You can only specify one of the styles supported
for that particular product–specific event.
Support and Upgrading
To manage your
customizations and handle upgrade considerations follow these guidelines:
Trouble
with Forms Operating with the CUSTOM Library
If a form is operating
incorrectly, and you have coded CUSTOM library or Zoom logic
for it, use the menu
to disable the CUSTOM library code temporarily
(Help->Diagnostics->Custom
Code->Off) so you can determine whether the problem comes from the
customizations or Oracle Applications code.
Upgrading
An Oracle Applications
upgrade will typically create a new directory structure that includes the
default (as-shipped) version of the CUSTOM library, so you must keep a backup
copy of CUSTOM with the changes you make. Place your custom version of the
CUSTOM library in the new AU_TOP/resource directory after the upgrade. You may
need to upgrade and/or regenerate the CUSTOM.plx file as part of the upgrade.
An Oracle Applications
patch will never include a new CUSTOM library.
Remember, form and
block names may change after an upgrade or patch to Oracle Applications. You
should test any custom logic that you have defined to confirm that it still
operates as intended before using it in a production environment.
Product-Specific Events in Oracle Application
Object Library
Oracle Application
Object Library provides product-specific events that you can access using the
CUSTOM library.
WHEN-LOGON-CHANGED Event
Use the
WHEN-LOGON-CHANGED event to incorporate custom validation or auditing that
fires immediately after a user uses the "File->Log On as a Different
User" choice on the default menu to log on as a different user (after the
user has signed on as the new user and pressed the Connect button or the Return
key). This routine is applicable only to Oracle Forms Developer-based forms.
This routine is not applicable to HTML- or Java-based forms (Oracle
Self-Service Web Applications).
You can access the new
user name and other profile values using the
FND_PROFILE.GET
procedure. You cannot access the username or information from the signon
session the user was leaving.
If for some reason
your code raises form_trigger_failure for this event, the user would be
returned to the signon screen as if the user had typed an incorrect username or
password.
This product-specific
event does not support custom execution styles.
See: Implementing User
Profiles, page 13-3
WHEN-RESPONSIBILITY-CHANGED Event
Use the
WHEN-RESPONSIBILITY-CHANGED event to incorporate custom validation or auditing
that fires immediately after a user uses the "File->Switch
Responsibility" choice on the default menu to switch responsibilities.
This routine is applicable only to Oracle Forms Developer-based forms. This
routine is not applicable to HTML- or Java-based forms (Oracle Self-Service Web
Applications).
You can access the new
responsibility name and other profile values using the FND_PROFILE.GET
procedure. You cannot access the responsibility or information from the
responsibility session the user was leaving.
If for some reason
your code raises form_trigger_failure for this event, the user would be
returned to the responsibility list of values as if the user had chosen an
invalid responsibility.
This product-specific
event does not support custom execution styles.
See: Implementing User
Profiles, page 13-3
CUSTOM Package
The CUSTOM package
contains the following functions and procedure:
•
CUSTOM.ZOOM_AVAILABLE
•
CUSTOM.STYLE
•
CUSTOM.EVENT
CUSTOM.ZOOM_AVAILABLE
Summary
|
function
custom.zoom_available return BOOLEAN;
|
Description
|
If
Zoom is available for this block, then return TRUE; otherwise return FALSE.
Always test for the form and block name. Refer to the SYSTEM variables for
form name and block name in your code and branch accordingly. The module name
of your form must match the form file name.
|
By default this
routine must return FALSE.
Example
Code
The following example
enables Zooms in the following places:
Form: FNDSCAUS, Block
USER and
Form: FNDCPMCP, Block
PROCESS
FUNCTION zoom_available
RETURN BOOLEAN IS
form_name
VARCHAR2(30) := NAME_IN('system.current_form'); block_name VARCHAR2(30) :=
NAME_IN('system.cursor_block');
BEGIN
IF (form_name = 'FNDSCAUS' AND block_name =
'USER') OR
(form_name = 'FNDCPMCP' AND block_name =
'PROCESS')THEN
RETURN TRUE;
ELSE
RETURN FALSE;
END IF;
END zoom_available;
CUSTOM.STYLE
Summary
|
function
custom.style(event_name varchar2)
return
integer;
|
Description
|
This function allows you to determine the
execution style
|
for a product–specific
event if custom execution styles are supported for that product–specific event
(many product– specific events do not support custom execution styles).
You can choose to have
your code execute before, after, or in place of the code provided in Oracle
Applications. See the User's Guide
for your Oracle Applications product for a list of events that are available
through this interface. Note that some product-specific events may not support
all execution styles. CUSTOM.STYLE does not affect generic form events or Zoom.
Any event that returns
a style other than custom.standard must have corresponding code in custom.event
which will be executed at the time specified.
The following package
variables should be used as return values:
•
custom.before
•
custom.after
•
custom.override
•
custom.standard
By default this
routine must return custom.standard (which means that there is no custom
execution style code).
Important:
Oracle
reserves the right to pass additional values for event_name to this routine, so
all code must be written to branch on the specific event_name passed.
Example Code
The following example
sets up the MY_PRICING_EVENT event to have the Override execution style.
begin
if event_name = 'MY_PRICING_EVENT'
then
return custom.override;
else
return custom.standard;
end if;
end style;
CUSTOM.EVENT
Important:
Oracle
reserves the right to pass additional values for event_name to this routine, so
all code must be written to branch on the specific event_name passed.
Summary
|
procedure
custom.event(event_name varchar2);
|
Description
|
This
procedure allows you to execute your code at specific events. Always test for
event name, then for form and block name within that event. Refer to the
SYSTEM variables for form name and block name in your code and branch
accordingly. The module name of your form must match the form file name.
|
By default, this
routine must perform "null;".
Example Code
The following example
contains logic for a Zoom, a product-specific event, and a generic form event.
The Zoom
event opens a new session of a form and passes parameter values to the new
session. The parameters already exist in the form being opened, and the form
function has already been defined and added to the menu (without a prompt, so
it does not appear in the Navigator). procedure event(event_name varchar2)
is
form_name varchar2(30) :=
name_in('system.current_form');
block_name varchar2(30) := name_in('system.cursor_block');
param_to_pass1 varchar2(255); param_to_pass2 varchar2(255);
begin
if (event_name = 'ZOOM')
then
if (form_name = 'DEMXXEOR' and block_name
= 'ORDERS') then /* The Zoom
event opens a new session of a form and
passes parameter values to the new session. The
parameters already exist in the form being opened:*/ param_to_pass1 :=
name_in('ORDERS.order_id');
param_to_pass2 := name_in('ORDERS.customer_name');
fnd_function.execute(FUNCTION_NAME=>'DEM_DEMXXEOR',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y',
OTHER_PARAMS=>'ORDER_ID="'||
param_to_pass1||
'"
CUSTOMER_NAME="'|| param_to_pass2||'"');
/* all the extra single and double
quotes account for any spaces
that might be in the passed values */
end if;
elsif (event_name =
'MY_PRICING_EVENT') then
/*For the product-specific event
MY_PRICING_EVENT, call a
custom pricing routine */
get_custom_pricing('ORDERS.item_id',
'ORDERS.price');
elsif (event_name =
'WHEN-VALIDATE-RECORD') then
if (form_name = 'APXVENDR' and block_name
= 'VENDOR') then /* In the
WHEN-VALIDATE-RECORD event, force the value of a Vendor Name field to be in
uppercase letters */ copy(upper(name_in('VENDOR.NAME')),
'VENDOR.NAME'); end if;
else null; end if;
end event; end custom;
Always use
FND_FUNCTION.EXECUTE to open a new session of a form. Do not use
CALL_FORM or
OPEN_FORM. The form function must already be defined with Oracle Application
Object Library and added to the menu (without a prompt, if you do not want it
to appear in the Navigator).
Example of Implementing Zoom Using the CUSTOM
Library
Here is an example of
a simple customization you can do with the Zoom feature (in the CUSTOM
library).
Note:
This
Zoom demo/example is based on the training class form DEMXXEOR used in the
class "Extend Oracle Applications" (available through Oracle
University).
The DEMXXEOR form is a
very simple form for entering orders. In this example, we add two parameters (ORDER_ID
and CUSTOMER_NAME) to the form that can be accepted from Zoom upon form
startup. The form then fires an automatic query based on the parameters if one
of the parameters has a value.
For the Zoom itself,
we make Zoom available from the first block of the same form. The user can have
a value in one or both of the Order Number and Customer Name fields. When the
user clicks on the Zoom button, Zoom opens another session of the same form and
automatically queries up any existing orders fitting the criteria.
Once you understand
how this Zoom works and is implemented, you should be able to take the same
approach with other forms (not necessarily zooming to another session of the
same form).
Modify the Form
Using the Oracle Forms
Designer, modify the Demo Orders form (DEMXXEOR.fmb) so it is able to receive
parameter(s) from the Zoom code.
Note:
The
DEMXXEOR form used in the class "Extend Oracle Applications" already
has these modifications.
1.
Create parameter ORDER_ID (Char, size 255, no default
value).
2.
Create parameter CUSTOMER_NAME (Char, size 255, no
default value).
In theory, the
parameter should match both the field the value comes from and the field it
goes to, but it depends on the purpose of the parameter. In this case, having
Char instead of number allows wildcards for the automatic query, as does having
the parameter longer than the actual field (standard query length for most
items is 255, and these parameters will only be used for queries).
3.
Modify the default WHERE clause of the target block (ORDERS)
to use parameter values as query criteria if they are not null:
WHERE (:parameter.order_id is
null or
dem_orders_v.order_id like
:parameter.order_id)
AND (:parameter.customer_name is null or
dem_orders_v.customer_name like
:parameter.customer_name)
4.
In the WHEN-NEW-FORM-INSTANCE trigger, add to the end of
the existing code:
/* fire automatic query if a
parameter has a value from Zoom */
if (:parameter.order_id is not null) or
(:parameter.customer_name is not null) then
GO_BLOCK('ORDERS'); do_key('EXECUTE_QUERY');
/* clear the parameters after
the query so they don't remain
criteria for future queries */ :parameter.order_id := null;
:parameter.customer_name := null;
end if;
5.
Compile and generate the form, and put the .fmx file in
the appropriate directory (assumes you have a custom application set up from
the class).
6.
Register the form, define a function for it
(DEM_DEMXXEOR), and put the form function on a menu so you can access it.
Verify that the form works properly from the Navigator before you modify the
CUSTOM library.
Modify the CUSTOM Library
Follow these steps for
modifying the CUSTOM library.
1.
Open CUSTOM.pll in Oracle Forms Developer.
2.
Modify the text of the CUSTOM package body as follows
(the CUSTOM library comes with extensive comments that explain each section.
You modify the actual code sections):
PACKAGE BODY custom IS
--
-- Customize this package to provide specific
responses to -- events within Oracle
Applications forms.
--
-- Do not change the specification of the
CUSTOM package -- in any way.
--
------------------------------------------------------------
function zoom_available return BOOLEAN is
--
-- This function allows you to specify if
zooms exist for the
-- current context. If zooms are available
for this block, then -- return TRUE;
else return FALSE.
--
-- This routine is called on a per-block
basis within every
-- Applications form. Therefore, any code
that will enable
-- Zoom must test the current -- form and block from which the call is
being made.
--
-- By default this routine must return FALSE.
form_name varchar2(30) :=
name_in('system.current_form');
block_name varchar2(30) := name_in('system.cursor_block');
begin
if (form_name = 'DEMXXEOR' and
block_name = 'ORDERS') then
return TRUE; else return FALSE; end if;
end zoom_available;
-------------------------------------------------------------- function style(event_name varchar2) return
integer is
--
--
This Zoom example does not do anything to the STYLE function
begin
return custom.standard;
end style;
---------------------------------------------------------------
procedure event(event_name varchar2) is
--
-- This procedure allows you to execute your
code at specific
-- events. 'ZOOM' or product-specific events
will be passed
-- in event_name. See the Applications
Technical Reference
-- manuals for a list of events that are
available through
-- this interface.
form_name varchar2(30) :=
name_in('system.current_form');
block_name varchar2(30) := name_in('system.cursor_block');
param_to_pass1 varchar2(255); param_to_pass2 varchar2(255); BEGIN if
(event_name = 'ZOOM') then if (form_name
= 'DEMXXEOR' and block_name = 'ORDERS')
then
param_to_pass1 :=
name_in('ORDERS.order_id');
param_to_pass2 := name_in('ORDERS.customer_name');
/* use fnd_function.execute
instead of open_form */
FND_FUNCTION.EXECUTE(FUNCTION_NAME=>'DEM_DEMXXEOR',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y',
OTHER_PARAMS=>
'ORDER_ID="'||param_to_pass1||
'"
CUSTOMER_NAME="'|| param_to_pass2||'"'); /* all the extra single and double quotes
account for any spaces that might be
in the passed values */ end if; else
null; end if; end event;
END custom;
------------------------------------------------------------------
3.
Compile All and save your changes. Exit from Oracle Forms
Developer.
4.
Use the Oracle Forms Compiler program to generate a new
.plx file for the CUSTOM library.
5.
Verify that your file generated successfully. If you
leave out the pathname for the output file, the file will be generated in
c:\orawin\bin (or platform equivalent). Move it to AU_TOP/resource.
6.
Make sure that the function you call in your Zoom
(DEM_DEMXXEOR) is somewhere on the menu in your responsibility. It does not
need to be accessible from the menu in the Navigator (do this by adding it to
the menu but leaving the prompt blank). Otherwise, the Zoom button will be
enabled but the user will get a message saying that function is not available.
7.
Try it out from the Oracle Applications Navigator.
