Note: Image quality in this sample chapter has degraded as a result of the HTML conversion process. Each volume of Learning Oracle contains clear and sharp images.
|
|
|
|
Previous versions of Oracle's Forms Designer tools, SQL*Forms, had two ways of sharing procedural code with multiple applications:
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:
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.
1. Create a new library module using one of these methods:
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.
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.
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.
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.