Document-ID: 38255.1
Subject: Tips on using the OG package
Author: DKLEIN
Last Modified: 12 Jul 96
The OG package is documented in chapter 8 of the Forms Advanced Techniques
Manual. The following notes are intended to supplement the manual with tips
on possible pitfalls in using OG procedures and functions, indeed it can be
used as a checklist when you encounter problems.
See the manual for syntax and parameter definitions etc.
1. The OG Environment
1.1. FORMS45_PATH and ORAPLSQLLOADPATH
If the OG.PLL package is in your FORMS45_PATH and ORAPLSQLLOADPATH you will
not need to reference the full path to this package in your form.
FORMS45_PATH is used by the Forms runtime to locate OG.PLL, ORAPLSQLLOADPATH is
used by the Forms Designer.
1.2. GRAPHICS25_PATH and the location of your OGD file
Set GRAPHICS25_PATH to include the location your OGD file so you do not
have to specify the full path of your graphic as the display parameter to OG
commands (but make sure there are not two files of that name in the
GRAPHCS25_PATH). If you are likely to be changing the name (or location) of
your OGD file, consider creating a forms parameter whose default value specifies
your OGD file, and then referencing this parameter as the display argument to
all your OG commands. Then if you rename your OGD file you need only make one
change to the form.
1.3. Do not stint on memory
16 meg is the recommended minimum memory for a PC on which a single
Developer 2000 1.2 designer is running. Allow an additional 4 meg for each
additional designer. So if you are developing forms with embedded graphics
you would be advised to have at least 20 meg. Insufficient memory can
cause aberrant behaviour and GPFs. Quite how much memory is sufficient for
your needs, depends on your application and set-up.
1.4 Make sure your graphic is compiled under the same version of Developer 2000
as your form.
2. OG.CLOSE
2.1. OG.CLOSE closes a display, it does not quit the Orabatch session.
Orabatch is the Oracle Batch process which controls and holds a copy of
graphics embedded in forms or report.
2.2. If you are quitting Orabatch do not first call OG.CLOSE.
In the following code, the call to OG.CLOSE is unnecessary and causes
additional processing:
OG.CLOSE('mychart.ogd','gra_block.chartitem');
OG.INTERPRET('mychart.ogd','gra_block.chartitem','OG_QUIT;');
The call to the Graphics built-in OG_QUIT through OG.INTERPRET quits the
Oracle Batch session including the image of any graphic it has loaded. If a
display referenced by OG.INTERPRET is not open, it is automatically loaded
before executing the PL/SQL string which is the procedure's third
parameter. Hence in the above code, OG.INTERPRET will reopen mychart.ogd
which was just closed by the previous line.
2.3 OG.CLOSE does not call Close triggers on the display
(unlike OG.OPEN - see 5.1).
3. OG.GETCHARPARAM and OG.GETNUMPARAM
3.1. Ensure your working directory is writeable.
This is necessary for Forms and Graphics to communicate with one another via
these commands.
4. OG.INTERPRET
OG.INTERPRET is used for dynamic modification of an Oracle graphic embedded in
a form.
4.1. OG.INTERPRET only works with *.OGD files not *.OGRs
This is bug 299661. If you want to hide graphics' program units from users
you can put them in stripped source libraries. If you are using
OG.INTERPRET, ensure that ALL references to the display file by OG procedures
make explicit the .OGD extension.
4.2. Case sensitivity in passing parameters.
Make sure that you maintain consistency when passing parameters from forms to
graphics. If in forms you add a data parameter "Query0" to a parameter list,
make sure that the query to which it corresponds on the graph is "Query0" and
not "query0".
4.3. OG.INTERPRET PL/SQL strings must be terminated by a semi-colon.
4.4. Ensure your form is referencing the latest version of your graphic.
If you are developing a form and its embedded graphic together, it is very
easy to find that the Oracle batch program which controls embedded graphs
has loaded an earlier version of your display. This can occur because if a
Graphics display is opened in a form using OG.OPEN, the display is not
automatically closed when the form is exited. Ogbatch keeps running in the
background. When the form is run again, the display is not re-read from the
file, hence changes to the file will not be picked up (see enhancement
request 277447). Quitting Ogbatch, ensures the latest version of the *.OGD
file is picked up when the form is run again. However, repeated quitting of
Ogbatch can cause memory leaks.
4.5. Datatype of passed parameters
Ensure the datatype of parameters you pass is the same in forms and
graphics; you will not get a helpful error message if these are
inconsistent. There have been problems with passing non-CHAR
parameters. If you suspect that NUMBER or DATE parameters are not being
passed correctly, consider TO_CHARing them in the form, passing them as
CHARs and then TO_NUMBERing or TO_DATEing them in the graphic.
4.6. Using single quotes in passing CHAR and DATE parameters to procedures
called by OG.INTERPRET
If you call a procedure on your graphic which takes char or date
parameters, you have to escape the single quotes with two single
quotes. For example, say you have a procedure on your graphic declared as
follows:
graph_proc(obj_name IN VARCHAR);
you might call it from forms using OG.INTERPRET
OG.INTERPRET('mychart.ogd','gra_block.chartitem',
'graph_proc(''Literal value''); ');
However, it is more likely that you will be passing a value in a forms item to
the graphic. Your call would look something as follows,
OG.INTERPRET('mychart.ogd','gra_block.chartitem',
'graph_proc('' ' || :block1.obj || ' ''); ';
It is easy to make mistakes in writing such lines of code. You might consider
building up your command to be executed on the graphic in a local VARCHAR2
variable which is then passed to OG, for example,
my_og_command := 'graph_proc('' ' || :block1.obj || ' '');' ;
MESSAGE(my_og_command);
OG.INTERPRET('mychart.ogd','gra_block.chartitem',my_og_command);
4.7. Debugging the Graphic
You cannot run the graphics debugger on an embedded graphic. There are ways
around this however.
4.7.1. Create dummy text items on the graphic to display parameters sent by
forms.
Use the graphics built-in OG_SET_STR to set these dummy test items to these
parameters, e.g.
OG_SET_STR(OG_GET_OBJECT('dummy_text'),:PARAM_SET_BY_FORMS);
4.7.2. Create dummy objects with 'button' procedures on the graphic
You can use the forms debugger - or just a MESSAGE line as above - to
determine the command executed on a graphic. In graphics, put the command in a
procedure on an object. Then run the graphic standalone with the graphics
debugger and fire the procedure.
5. OG.OPEN
5.1. OG.OPEN will fire both open and close triggers on your graphic.
There is an enhancement request on this (314672). It would probably be better
not to have a close trigger on an embedded graph, instead create a procedure to
perform your closure processing and call this though OG.INTERPRET.
6. OG.REFRESH
OG.REFRESH simply refreshes a display, putting the picture of the graph as
held in Orabatch back in the form. It does not cause any queries to fire or
any graphics processing to take place. For dynamically controlling your graph
use OG.INTERPRET.