Learning Oracle Forms 4.

5
Chapter 8: Libraries

Previous versions of Oracle's Forms Designer tools, SQL*Forms, had two ways of
sharing procedural code with multiple applications:

• User Exits let designers write procedures in a programming language (C,

COBOL, Fortran, etc.) and link the compiled executable directly into the
Runform module.
• Copy/Reference allowed designers to define procedures in forms that were
saved to the database; new forms could include the procedures by either
copying or referencing them.

These two methods are still available, but Oracle Forms provides a third. Designers of
applications can create libraries of procedures which can be attached to any form or
menu module. Calls within those forms can reference any procedure in an attached
library as if the procedure were in the active form. Procedures are written in PL/SQL
and compiled into a runtime module.

There are two file extensions used by the library facility:

• .PLL files are the binary library modules. This file is portable across systems
(but be aware of the inclusion or exclusion of path information that may make
the module unportable - see a discussion of this later in the chapter). The file is
created when you save the library in the Designer.
• .PLD files are the text form of the binary module. They can be used for source
control. They are created with the command line option script=yes when you
generate the form module using f45gen.

You'll create a library to handle messages that are produced when the form is run. The
library will provide an alternate format for error messages and informative messages,
printing some messages in a customized format and suppressing some completely.
The object is to give all operators the same messages in the same format across all
forms in the application.

Creating a Library

1. Create a new library module using one of these methods:

 • Double-Click on the Libraries node of the Object Navigator.
• Select the Libraries node, then click on the Create icon on the Object Navigator
toolbar.
• Choose File, New, Library.

As with other objects you create, any of these methods will work.

The new Library is shown on the Object Navigator. It has the usual default name of
the object type and a sequence number (your number may be different).

2. Expand the new Library node and select the Program Units node.

3. Choose Navigator, Create, or click on the Create icon.

The New Program Unit dialog box opens.

4. Type message_handler in the Name entry field.

Leave the Type as Procedure.

5. Click on OK.

The new Program Unit is shown on the Object Navigator. The PL/SQL Editor opens
with the skeleton of a PL/SQL procedure shown.
6. Type the following in the text entry area between the
keywords BEGIN and END (resize the window so you can see the whole procedure)

The procedure header has two parameters that are passed into the procedure.
First, message_number is the five digit code assigned by Oracle to the message. It's
usedto decide if the message is to be suppressed or changed in format.
Second, is_error is a variable of type boolean. This means that it takes only the
values TRUE or FALSE (without single quotes as in the if statement eight lines from
the bottom). The values are not character strings (which need single quotes around
them). Their values are decoded when Oracle Forms and PL/SQL find the TRUE or
FALSE for a boolean parameter.

Both parameters are marked as in, meaning that their values are passed into the
procedure, but not out to the calling form. (There are also out and in out types.) The
calling form will have triggers written to call the procedure and set up the values to be
passed to it. You'll do that later in this chapter.

The procedure starts with the statement begin. The first command starts an if

test that continues through the entire procedure, ending at the next to last line. Once
the first if is stated, the statement proceeds with a series of elsif tests that extend
the if tests without having to end and restart them.
The next line is a comment. Two dashes (--) in a PL/SQL procedure identify a
comment. (You can also use /* to begin and */ to end a comment.) The first comment
informs you that messages telling the operator that the last row of the query has been
retrieved will be suppressed completely. The action taken is to raise
form_trigger_failure, meaning that the trigger is aborted at that point, with no
alternate message displayed.

The next set of tests changes the wording of certain messages. The idea is to shelter
the operator from Oracle Forms' standard message output and provide the same
messages in all forms.

The next section of code uses the boolean variable is_error. If the variable is TRUE,
it's an error message. You'll pass the value through the ON-ERROR trigger in the
calling form. The message then includes the word ERROR: to let the operator know
that something serious is happening. If the boolean value is FALSE, it's an
informative message. It will be passed through the ON-MESSAGE trigger. In either
case, the format of the message is changed from the standard to a customized format.

The if statement and the procedure are ended in the last two lines.

7. Click on Compile.

The messages Not Modified and Successfully Compiled should be shown on the
bottom line of the editor window.

8. Choose File, Save As...

Make sure the Library module is selected on the Object Navigator. If you choose File,
Save, the library will be saved with the default name.

The Filter opens.

9. Make sure File System and Libraries are checked.

10. Click on OK.

The Save As dialog box opens.

11. Change the file name to msghndlr.pll.

12. Click on OK.

The name of the saved library is shown on the Object Navigator, replacing the default
name.

13. Click on Close.

Attaching a Library

The library must be attached to the active form. When you saved the library module,
Oracle Forms created the binary .PLL file.

14. Expand the ORDENTRY nodes so you can see the node Attached Libraries.

15. Select Attached Libraries.

16. Click on the Create icon, or choose Navigator, Create, or double-click on the
Attached Library node.

The Attach Library dialog box opens.

17. Click on Find...

The PL/SQL Library File dialog box opens.

18. Select the correct drive and directory for the library you just saved.

19. Select msghndlr.pll.

20. Click on OK.

The name and path of the file are transferred to the Attach Library dialog box.

21. Click on Attach.

A path to the file was included when you selected the library file name. To make the
form and the attached library portable across platforms, you should strip the path from
the library specification. Oracle Forms will find the library file on other platforms by
first searching the current directory, then the directories pointed to by the
environmental variables FORMS45_PATH and ORACLE_PATH. When moving a
library to another platform make sure it's in a directory pointed to by one of those
variables (or in what would be the current directory). If the library won't be in one of
those directories, don't strip the path from the file specification, or you'll be greeted by
the error message 40034: Cannot attach library when you run the form.

22. Click on Yes to strip the path (or on No to leave it).

The library is attached to the ORDENTRY form. It appears on the Object Navigator.

Adding Triggers to Use the Library

In order to make use of the program units in the library, triggers in your form must
call them. Two triggers will reference MESSAGE_HANDLER in your form. Both
trap Oracle Forms events that display messages.

1. Expand the Triggers node at the Forms level of the Object Navigator.

2. Click on the Create icon on the Object Navigator.

The Triggers LOV opens

3. Select the trigger ON-MESSAGE.

This trigger tells Oracle Forms what to do when it has a message to output to the
operator of the form. (Without it, Oracle Forms uses its default logic to display
messages.)

The Designer status line tells

you how many choices of triggers there were when the LOV opened. If you use the
Find feature, it will tell you how many selections you received from the the criterion
you entered in the Find entry field. In this case, after selecting the ON-MESSAGE
trigger, it tells you that there's one choice in the list, and 120 choices in the full list of
trigger types.

4. Click on OK.

The PL/SQL Editor opens.

This is a Form level trigger whose name is ON-MESSAGE, as shown on the
specification area of the editor.

5. Type in the PL/SQL Editor entry area:

--Call the message handler; pass FALSE to IS_ERROR

message_handler(error_code, FALSE);

You're passing two parameters to the procedure: the message number and theFALSE
boolean value to tell the procedure that this isn't an error.

6. Click on Compile.
7. Click on New...

The Triggers LOV opens.

8. Select the ON-ERROR trigger.

This trigger tells Oracle Forms how to output any error messages it has to show to the
operator.

9. Click on OK.

10. Type the following in the entry area of the PL/SQL Editor:

--Call the message handler; pass TRUE to IS_ERROR

message_handler(error_code, TRUE);

11. Click on Compile.

12. Click on Close.

Testing the Library Procedure

13. Choose File, Save. Make sure the form is selected.

14. Click on Run. (You may have to log on before the form generates.)

15. Click on Execute Query.

16. Press the up arrow as if you were moving to a previous record.

The message on the message line should read At first record. without any message
number, as you defined it in the procedure.

17. Click on Save.

The message on the message line should read ERROR: No changes to save. (FRM-
40401). Since this is an error, the logic for displaying an error message is executed,
putting the word error before the message text, and the error number at the end.

Try other operations that produce messages. The display should show the text in the
format you specified in MESSAGE_HANDLER, with the message number at the end,
and the word ERROR at the beginning if it's an error.

You can add other messages to the procedure as you find the need. The library can be
opened and edited as a separate module (even while a form module is open).

When you're done, choose File, Save to regenerate the library.

Maintaining a Library

Once a library is defined, you can add or remove procedures from it.

1. Select the library you want to modify on the Object Navigator under the Libraries
node (not the Attached Libraries node under a form definition).

2. Choose Tools, PL/SQL Editor...

3. Make any changes you want to the procedure(s) in the library.

You can add or delete procedures, functions, and so forth, or modify ones already in
the library.

4. Choose File, Save to regenerate the .PLL file.

The changes are applied to each module (form or menu) to which the library is
attached when you save it.

Stripping Source Code from the .PLL File

You can strip the source code to make the library module smaller. This process leaves
just the pcode in the .PLL file. A module of this sort is not portable, but is smaller.
Specify STRIP_SOURCE=YES on the f45gen command line to produce this type of
file.