Document-ID: 33237.1
Subject: (V4/V45) LINKING A FORM TO A MENU
Author: Unknown
Last Modified: 29 Jan 96
Linking a Form to a Menu
Introduction
============
While creating a menu in Oracle Forms is a fairly straightforward process,
linking that menu to a form is relatively subtle -- some customers are unsure
of how to do it, and the ones who succeed often get tripped up by one of
several common pitfalls. This bulletin outlines what happens when a form
calls up a menu, provides step-by-step instructions for setting this up, and
also covers some common problems which may occur.
Overview
========
While most resources of a form -- alerts, LOVs, canvas-views -- are
contained in the form definition, the menu of a form is encapsulated in
a separate module altogether. This eases sharing of the menu across several
forms. Thus, a form with a custom menu involves two modules.
When the application is generated, two compiled files are produced: the
FMX for the form and the MMX for the menu. When the FMX is executed, it
must locate the MMX in the file system, then load it into memory. The process
of linking a form and a menu is basically telling the form which MMX to
load, and where to find that MMX file.
Finding the MMX File
====================
The form needs two crucial pieces of information to load the menu --
the name of the MMX file, and the location of that file on the file system.
There are three ways to convey this information to Oracle Forms: database
lookup, explicit file specification, and variable lookup.
In database lookup, the name and location of the MMX file is stored
with the menu module. The form is provided with the name of the menu
module as saved to the database. When the form is invoked, it queries the
database for MMX name and location.
In explicit file specification, the name and location of the MMX file
is stored in the form. The form is provided with the path and name of the
MMX file, and when invoked simply goes directly to that location to load up
the MMX.
In variable lookup, the name of the MMX file is stored in the form, but
its location is specified using OS environment variables. The form is given
the name of the MMX file. When invoked, it examines the environment variables
for possible directories where the file may be located, then looks for the MMX
in those locations.
Most application engineers prefer to use variable lookup, because if the
location of the menu modules change, only the environment variable needs to
be reset -- no modules have to be touched. Also, both variable lookup and
explicit file specification avoid the need to query for the MMX location which
database lookup incurs.
How to Specify MMX Name and Location
====================================
All these assume that the menu module has already been generated. (V4.0
users: with the menu module active in the designer, select Menu -> Module.
Click OK on the Menu Editor if open. With the Menu Module property sheet
active, select File -> Generate. V4.5 users: Highlight the menu module in the
Object Navigator, and select File -> Administration -> Generate)
How to Set Up Database Lookup
-----------------------------
1. Set the Directory and Name properies of the menu module to
the path and name of the MMX file. (V4.0 users: change these in the
Menu Module property sheet and click OK. V4.5 users: use the property
palette)
2. Save the menu module to the database.
3. Open the form which will link to the menu.
4. Bring up the form module properties. (V4.0 users: select Form -> Module.
V4.5 users: highlight the form module in the Object Navigator, and its
properties will be displayed in the property palette)
5. Set the Menu Module property of the form to the name of the menu
module -- this is the name that the module was saved to in step 3.
6. Set the Use File property to false (unchecked). V4.0 users should then
click OK.
7. Generate and run the form.
Explicit File Specification
---------------------------
1. Open the form which will link to the menu.
2. Bring up the form module properties. (see above)
3. Set the Menu Module property to the full path and name of the .MMX file
4. Set the Use File property to true (checked). V4.0 users: click OK.
5. Generate and run the form.
Variable Lookup
---------------
1. Open the form which will link to the menu.
2. Bring up the form module properties. (see above)
3. Set the Menu Module property to the name of the menu module -- do not
include a path or an .MMX extension. Remember that UNIX systems are
case-sensitive.
4. Set the Use File property to true (checked). V4.0 users: click OK.
5. Set environment variables to point to the location of the MMX files
(see chart in Troubleshooting section for which environment variable
to set for your platform)
6. Generate and run the form.
Troubleshooting
===============
The form should now display your custom menu when run. If you get an
error, the following troubleshooting guide should resolve most problems.
Q. When I try to run a menu, I get FRM-10089: Menus cannot be run from the
Designer.
A. Oracle recommends that menus should not be run standalone. Instead,
you should run a form which connects to the menu. The User's Guide
(called the Developer's Guide for V4.5 users) has information on how to
set up a form to connect to a menu.
Q. What is the purpose of the USE FILE checkbox?
A. When Oracle Forms runs a form which connects to a menu, there are two
methods it can use to locate the .MMX file. One option, database lookup,
has Oracle Forms querying the database for the menu definition. That
menu definition then tells Oracle Forms where the .MMX is located (this
is the File property of the menu application). The other option, USE FILE,
does not query the database -- it simply checks several places in the
file system for the menu. (See FRM-10221, below)
Q. When I try to run a form which attaches to a menu, I get the error
FRM-10256: User is not authorized to run Oracle Forms Menu.
A. Either the Oracle Forms base tables are not installed, or, if installed,
the user does not have privileges to them. For instructions on installing
the base tables, see bulletin 108797.032 "How to Install Base Tables for
CDE Tools" and 108383.767 "Install Base Tables for Developer 2000 Tools".
Note that this error indicates that Oracle Forms is using database
lookup to locate the menu. In most cases, the customer actually means
to use file lookup (see Use File section, above). In those cases,
simply change the Use File property of the form to checked or True.
(In V4.0, select Form -> Module. In V4.5, select the form module in the
object navigator, and set the property in the Property Palette).
Another possible cause of this error when your application uses
Oracle Forms role security is that the ORACLE username trying to run the
menu does not belong to any roles.
Q. When I try to run a form which attaches to a menu, I get the error
FRM-10249: No Authorization to Run Application <myapp>
A. There are two ways to resolve this error condition, depending on whether
the application uses Oracle Forms role security or not. If your menu
application does NOT use security, then most likely the Use File
property of the form is set to False (unchecked). As explained above,
when Use File is set to false, Oracle Forms queries the database for
the .MMX file location. Most customers do not make use of this menu
file setup, preferring instead to work straight from the file system.
Thus, in most cases where security is not being used, setting the
Use File property of the form to True (checked) will resolve this error.
If, on the other hand, your menu application DOES use security, then
this error indicates that the user trying to use the form does not
belong to a role which has access to the main menu. For more information
on assigning roles to menu items, refer to the Oracle Forms User's Guide
(called the Developer's Guide for V4.5 users).
Q. When I try to run a form which attaches to a menu, I get the error
FRM-10221: Cannot Open File
A. Oracle Forms cannot find the .MMX file for the menu. Here is a checklist
of steps to go through. Even if you are relatively certain of the results
of these tests, go through them anyway to double-check.
* Make sure that the .MMX file exists somewhere. Go out to the
UNIX command line, MS Windows File Manager, or Mac Finder and
make sure that the .MMX file is on the file system and readable.
If the .MMX file does not exist, then re-generate the menu.
V4.0 users should bring up the menu editor, and select
File -> Generate. V4.5 users must select File -> Administration ->
Generate while over the menu module in the Object Navigator.
* Now check the value of the Menu Module property of the form.
V4.0 users will find this on the property sheet of the form
(select Form -> Module) and V4.5 users will find this in the
Property Palette when the form module is selected in the Object
Navigator.
* Have you specified the full pathname for the menu module? If so,
then make sure that the .MMX is in that location. If not, make sure
that only the .MMX name -- no extension -- is filled in here.
* UNIX is case-sensitive. When running on UNIX, make sure that the
name of the menu application, as entered in the form property sheet,
is exactly the same with respect to case as the .MMX file.
* If you did not specify a full pathname for the menu module, check
the search path for .MMX files. The search path is the current
directory, followed by the path variable. The following table
defines current directory and path variable for each platform:
Platform Current Directory Path Variable
-------- ----------------------------- ----------------------------
Windows Working directory of runform FORMS40_PATH in ORACLE.INI
In Program Manager, click
the runform icon and select
File -> Properties. The
Working Directory is listed.
UNIX The directory from which you ORACLE_PATH (environment var)
invoke the designer or runform
Mac The folder for runform. FORMS40_PATH
* As the final debugging step, regenerate the menu, move the .MMX
to the current directory, eliminate the full pathname from the
Menu Module property, and try it. If that fails, contact Oracle
Support.