Documentation roadmap

Graphics Builder includes a comprehensive online help system that provides information on a variety of conceptual, reference, and instructional topics.

To get started and become proficient with Graphics Builder:

1	Review the Quick Tours for a brief overview of each component:

•	Choose Help [image] Quick Tour.

2	Step through the Cue Cards to learn how to perform the most common tasks:

•	Choose Help [image] Cue Cards.

3	Access the online/hardcopy manuals:

•	Choose Help [image] Manuals.

4	Locate help topics:

•	For the table of contents and index, choose Help [image] Help Topics.

•	For context-sensitive help, press [Help] (this is usually the F1 key on most platforms).

•	For Form Builder key commands, choose Help [image] Keyboard Help, or press [Show Keys] (this is usually Control-K on most platforms).


Creating arc objects

To create an arc object:

1	Select the Arc tool from the tool palette.

2	Select-and-drag diagonally on the layout to define the desired arc, then release.

To draw the arc of a circle, hold down the Shift key while dragging.


Creating ellipse objects

To create an ellipse object:

1	Select the Ellipse tool from the tool palette.

2	Select-and-drag diagonally on the layout to define the desired ellipse, then release.

To draw a circle, hold down the Shift key while dragging.


Creating freehand objects

To create a freehand object:

1	Select the Freehand tool from the tool palette.

2	Select-and-drag on the layout to define the desired freehand shape, then release.

The Freehand tool cannot be constrained.


Creating line objects

To create a line object:

1	Select the Line tool from the tool palette.

2	Select the desired start point, drag to the desired end point, then release.

To draw a horizontal, vertical, or 45 degree line, hold down the Shift key while dragging in the desired direction.


Creating polygon objects

To create a polygon object:

1	Select the Polygon tool from the tool palette.

2	Select the desired location of the first vertex, then select the next vertex, etc.  To finish drawing the polygon, double-click at the final vertex.

A line is drawn connecting the first and last vertices.

To draw a horizontal, vertical, or 45 degree segment, hold down the Shift key while defining a vertex. Constraining one vertex does not affect subsequent vertices.


Creating polyline objects

To create a polyline object:

1	Select the Polyline tool from the tool palette.

2	Select the desired location of the first vertex, then select the next vertex, etc.  To finish drawing the polyline, double-click at the final vertex.

Unless you manually connect the first and last vertex, no line is created connecting them as with the polygon object.

To draw a horizontal, vertical, or 45 degree segment, hold down the Shift key while defining a vertex.


Creating rectangle objects

To create a rectangle object:

1	Select the Rectangle tool from the tool palette.

2	Select-and-drag diagonally on the layout to define the desired rectangle, then release.

To draw a square, hold down the Shift key while dragging.


Creating rounded rectangle objects

To create a rounded rectangle object:

1	Select the Rounded Rectangle tool from the tool palette.

2	Select-and-drag diagonally on the layout to define the desired rounded rectangle, then release.

To draw a rounded square, hold down the Shift key while dragging.


Creating shapes programmatically

  Related Topics

To create shapes programmatically:

  Use the Graphics Builder PL/SQL built-ins.

The following example creates a large, colored rectangle to be used as a background for other objects and charts:

PROCEDURE create_background IS
  the_back   OG_OBJECT;
  rect_pos   OG_POINT;
  rect_ht    NUMBER;
  rect_wi    NUMBER;
BEGIN
/*Set the start position of the rectangle*/
  rect_pos.x:=.5*OG_INCH;
  rect_pos.y:=.5*OG_INCH;
/*Set the rectangle's height and width*/
  rect_ht:=6*OG_INCH;
  rect_wi:=4*OG_INCH;
/*Make the rounded rectangle object*/
  the_back:=OG_MAKE_RRECT(rect_pos, rect_ht, rect_wi);
/*Set the object's foreground fill color and pattern*/
  OG_SET_FFCOLOR(the_back, 'color 25');
  OG_SET_FILLPAT(the_back, 'gray50');
END;


About symbols

You can use symbols as decorative artwork elements on the layout, or you can specify symbols to be used as the plot type in a chart field template.


Selecting symbols from the Symbol palette

To select a symbol from the Symbol palette:

1	Open the Symbol palette by selecting its icon in the tool palette.

The palette opens to show the symbols available.

2	Select the symbol you want to use.

The palette closes and the symbol appears in the Symbol palette icon.  The symbol is applied to any currently selected symbol object and new symbol objects you place on the layout using the Symbol tool.  The selection remains in effect for the current display until you change it again.

You cannot change the available symbols.


Placing symbols in the layout

To place a symbol in the layout:

1	Select the Symbol tool from the tool palette.

2	Select where you want the symbol to appear.

The currently selected symbol in the Symbol palette appears on the layout.


Creating symbols programmatically

  Related Topics

To create symbols programmatically:

  Use the Graphics Build property built-in OG_MAKE_SYMBOL.

For example:

PROCEDURE make_sym IS
  place  OG_POINT;
BEGIN
  place.x:=1*OG_INCH;
  place.y:=2*OG_INCH;
  OG_MAKE_SYMBOL(place, 5, OG_MEDIUM_SYMSIZE);
END;


About text and text fields

  Related Topics

Graphics Builder provides two objects for adding text to a display:  text objects and text field objects. You can perform the following actions with these objects:

•	Create text objects

•	Create text objects programmatically

•	Edit text objects

•	Create text field objects

•	Set properties for the whole text object or text field

•	Set properties for a partial text object or default text field text

•	You can use text objects to provide titles, label artwork elements, or communicate instructions to end-users. Use text field objects to provide input areas in which end-users can type text at runtime.


Creating text objects manually

To create a text object:

1	Select the Text tool from the tool palette.

2	Do one of the following to create a bounding box containing the text cursor in the layout:

Select where you want the text object to start.  The text will word wrap to the next line only when you press Return.

Drag out a specific region for the text object to occupy.  The text will word wrap to fit within the horizontal boundaries of the box.  If necessary, the box will grow vertically to accommodate the text you type.

3	Type the text.  Use the Return key to force a line break.

4	When you're finished, select outside the text object to exit text mode.

Note that if you create a text object without typing any text, the object is automatically deleted.  To create an empty text object, first create it with some text, then edit it and delete the text.  You can create an empty text object only if it has a fixed bounding box.


Creating text objects programmatically

  Example	  Related Topics

To create text objects programmatically:

1	Create the text object.

2	Create and insert a compound text element into the main text object.

•	A compound text element represents a line of text within the text object.  The compound text element can contain one or more strings of text (simple text elements).

•	The first compound text element is inserted at the index point zero (0) of the text object unless otherwise specified.

3	Create one a simple text elements to be inserted in the previously created compound text object.

A simple text element is an actual string of text that will be inserted in the line created by the compound text element.

4	Insert the simple text element into the compound text element.  Insert simple text elements one at a time, each at a specified index point within the compound text element.

5	Repeat steps 3 and 4 until you have populated the text object with the desired text.

You can set size, font, and spacing properties individually for each simple text element, or for the entire text object as a whole.


Example:  Creating text objects programmatically

The following example creates a text object at point (1", 1") on the layout, and contains two compound text objects (lines of text).  The first compound text object contains one simple text element(string), the second compound text object contains two simple text elements.  These two lines of text will be in a 12-point Times font as follows:

This is line 1.

And now line 2.

PROCEDURE make_text IS
   text_obj   OG_OBJECT;
   text_pos   OG_POINT;
   smp_rec    OG_SMPTEXT_ATTR;
 BEGIN
/* Set text object's origin properties */
   text_pos.x:=OG_INCH;
   text_pos.y:=OG_INCH;

/* Make the text object */
   text_obj:=OG_MAKE_TEXT(text_pos);

 /* Insert a new compound text element into the text
      object at index 0 */
    OG_INSERT_CMPTEXT(text_obj, 0);

/* Set simple text record for desired text string*/
    smp_rec.str:='This is line 1.';
    smp_rec.mask:=OG_STR_SMPTEXTA;

/* Insert a new simple text element at index 0
      in text object's compound text element at
      index 0, using defined simple text record */
    OG_INSERT_SMPTEXT(text_obj, smp_rec, 0, 0);

/* Insert a new compound text element into the text
     object at index 1 */
    OG_INSERT_CMPTEXT(text_obj, 1);

/* Change the simple text record's text string */
    smp_rec.str:='And now';

/* Insert a new simple text element at index 0
      in text object's compound text element at
      index 1, using defined simple text record */
    OG_INSERT_SMPTEXT(text_obj, smp_rec, 1, 0);

/* Change the simple text record's text string */
    smp_rec.str:=' line 2.';

/* Insert a new simple text element at index 1
      in text object's compound text element at
      index 1, using defined simple text record */
    OG_INSERT_SMPTEXT(text_obj, smp_rec, 1, 1);

/*Set font size and typeface for text object*/
   OG_SET_FONT_PTSIZE(text_obj, '12');
   OG_SET_FONT_TYPEFACE(text_obj, 'Times');
END;


Creating text field objects

To create a text field object:

1	Select the Text Field tool from the tool palette.

2	Select-and-drag on the layout to define a rectangular bounding box, then release.

   To create a square text field, hold down the Shift key while dragging.

  To enter default text in the text field:

3	Select the Text tool from the tool palette.

4	Select the text field object.  A text cursor appears where you clicked.

5	Type the text.

6	When you're finished, select outside the text field object to exit text mode.

At runtime, the default text will appear in the text field.  Users can change this text.


Importing a drawing

To import a drawing:

1	Choose Edit [image] Import [image] Drawing to display the Import dialog.

2	Indicate the data source for the file by selecting either the Database or File System radio button.

3	Type the file/module name in the corresponding field, or select Browse to display your operating system file dialog or the Database dialog where you can select the file/module.

4	Select the drawing format type from the Format drop-down list.

5	Select OK to import the drawing file.

The imported artwork appears on the layout.

Note:  If you have grouped objects in a file and then converted the file to CGM format, those objects will no longer be grouped.

Graphics Builder accepts drawing files saved in the CGM format or artwork files from other Oracle applications saved in Oracle Format.  Graphics Builder imports the drawing into the active layer unless otherwise specified.


Importing an image

To import an image:

1	Choose Edit [image] Import [image] Image to display the Import dialog.

2	Indicate the data source for the file by selecting either the Database or File System radio button.

3	Type the file/module name in the corresponding field, or select Browse to display your operating system file dialog, or the Database dialog where you can select the file/module.

4	Select the image format type from the Format drop-down list.

5	Select OK  to import the image file.

The imported artwork appears on the layout.


Importing artwork using PL/SQL

  Related Topics

To import artwork using PL/SQL:

  Use the Graphics Builder built-in OG_IMPORT_IMAGE.

The following example imports an image onto the active layer in the active window:

PROCEDURE import_the_image IS
   the_image   OG_OBJECT;
   the_layer   OG_LAYER;
BEGIN
  the_layer:=OG_GET_LAYER('layer1');
  OG_ACTIVATE_LAYER(the_layer);
  the_image:=OG_IMPORT_IMAGE('my_image',OG_FILESYSTEM,
    OG_TIFF_IFORMAT);
END;


About sounds

Sounds are useful for alerting end-users to specific events at runtime.  For example, you may want to record an alarm to be sounded when data in a chart falls below a certain threshold value.  Playing sounds at runtime must be done programmatically, using PL/SQL.


Recording sounds

To record a sound:

1	In the Object Navigator, select the Sounds subnode and choose the Create button or Navigator [image] Create.  If no sounds exist in the current display, double-click on the Sounds node in the Navigator to display a new sound in the Sound Player dialog box.

A new sound (initially named soundx) is created and the Sound Player dialog box appears.

2	To record the new sound, select Record.

3	When you are done recording, select Stop.

4	Select OK to accept the sound and close the dialog.

The sound is added to your display.  You can access the sound through the PL/SQL built-in procedure OG_PLAY_SOUND.


Recording sounds programmatically

  Related Topics

To record a sound programmatically:

  Use the Graphics Builder built-in OG_RECORD_SOUND.

The following example shows the sound dialog box in the Runtime display, and allows the user to record a new sound:

PROCEDURE record_warning IS
   warn_sound   OG_SOUND;
BEGIN
   warn_sound:=OG_GET_SOUND('warning');
   IF NOT OG_ISNULL(warn_sound) THEN
      OG_RECORD_SOUND(warn_sound);
   END IF;
END;


Importing sounds

To import sounds:

1	Choose Edit [image] Import [image] Sound to display the Import Sound dialog.

2	Select either the File System or Database radio button to indicate the source of the file.

3	Type the name of the file in the File field, or select Browse to display a list of files to choose from.

4	Select the appropriate sound file format from the Format drop-down list.

5	Select OK to accept the dialog and import the sound.

The sound is added to your display.  You can access the sound through the PL/SQL built-in procedure OG_PLAY_SOUND.

You can import an existing sound file from either the file system or the database.


Importing displays

To import a display:

1	Choose Edit [image] Import [image] Display to display the Import Display dialog.

2	Specify the name and location of the display, whether or not you want the active layers from each display merged or not, and how to resolve naming conflicts.

3	Select Import to accept the dialog and import the display.

You can import a display that is stored on the file system or in a database into your current display.  This is a way to copy the contents of one display into another existing display and effectively combine the two displays.


About layers

You can perform all actions on layers through the Layer Settings dialog.  To display this dialog at any time, choose Tools [image] Layers from the menu.  Many actions can also be performed using the Object Navigator.  Possible actions include:

•	creating new layers

•	renaming layers

•	activating layers

•	activating a layer using PL/SQL

•	hiding and showing layers

•	hiding and showing layers using PL/SQL

•	re-ordering layers

•	deleting layers

The active layer is your working layer, and is always showing.  However, you can create multiple layers to show along with the active layer, and you can also hide multiple layers.  When you create a new display, it contains one layer called layer0.  Since this is the only layer, it's the active layer by default.

PL/SQL, you can manipulate existing layers at runtime.  The active layer is the only layer that end-users can interact with, but you can change the active layer using PL/SQL, depending on where you want user input.  You can also hide, show, and change the stacking order of layers, to wholly or partially obscure individual objects.

For example, your layout may appear as a single surface.

But it may actually be composed of multiple layers.

You can set any number of layers to be showing or hidden at any one time.  The active layer must always be showing.


Creating new layers

To create a new layer:

1	Select the layer object in the Object Navigator.

2	Choose the Create button, or choose Navigator [image] Create to display the Layer Settings dialog.

Alternatively, you can choose Tools [image] Layers from the menu.

3	Select New.  In the Existing Layers list, a new layer appears called layerx, where x is an instance number that increments by one each time a new layer is created.  It also becomes the active layer.

4	Select OK to confirm the changes and close the Layer Settings dialog.

If the layout is divided into multiple views, the new layer is added in all views.  However, it becomes the active layer only in the active view.


About displays

An application created with Graphics Builder is referred to as a display.  A display can contain several components, including data queried from a data source, graphical elements, and behavior such as drill-down capability or continuous updating.

Graphics Builder displays (as viewed in the Builder) have the following components:

charts

graphic objects

imported artwork

sounds

layers

page breaks

copyright information


Charts

Charts are graphic diagrams you can create in a display to visually represent data.


Graphic objects

Objects are the visual elements on your layout.  Graphic objects are visual elements you either create using Graphics Builder drawing tools, or import into your displays.


Imported artwork

In addition to creating artwork within Graphics Builder, you can import drawing and image files from third party applications.


Sounds

If your system supports sound, you can make audio recordings to use in your displays.


Layers

Every display's layout is composed of one or more distinct surfaces called layers.  Layers are useful for hiding objects you want to show only under certain conditions.  For example, you can place a button on one layer that a user can select to display an object on another layer.  Similarly, you may want to hide a layer so that you can display its objects in a window other than the Main Layout window.


Page breaks

Page breaks are solid dark lines that appear on the layout, each one representing a boundary of a printed page.  The page size is determined by the settings in the Print Setup dialog.

Page breaks appear in the Builder only, and are not visible when the display is run or printed.


Copyright information

You may want to add copyright information such as your name and the last date of update to a display you have created.  This information is useful to other users who may only receive the runtime display but wish to know more about the display, such as who created it and when.


About creating displays

Every time you invoke the Builder, a new display initially named Disp1 appears automatically.  This new display is created for your convenience.

To specify that no initial display is created when you start Graphics Builder, choose Tools [image] Tools Options to display the Tools Options property sheet.  Choose the Preferences tab.  In the Startup block, select No Display from the Open drop-down list.  Select Save to save this setting to your preferences file.


Creating a new display

To create a new display:

  In the Object Navigator, select the Displays node, then select the Create button in the toolbar

A new display appears in its own Layout Editor.  The default name is Dispx, where x is an instance number that increments by one, each time a new display is created during the current session.

If no displays are currently open, double-click on the Displays node in the Navigator to create a new display.


About charts

A chart appears on the layout as a single object, but actually consists of three main components:

•	Query

•	Chart region

•	Chart template

You can create chart components in the Layout Editor by specifying a query and chart template to use and defining the chart’s region on the layout.  Alternatively, you can create chart components programmatically using PL/SQL.

For example, you can programmatically define a query, select a chart template, make a field into a button, or "explode" a field by setting it apart from the rest of the chart.  You can also use PL/SQL to define the graphic properties of fields by setting their pattern, color, or line style.  Then you can set up a condition, such as a specific threshold value for a data category, under which an property should be applied.  At runtime, Graphics Builder will apply the properties to the specified fields depending on the data categories or conditions present.


About queries

A query is a SQL SELECT statement or file that Graphics Builder needs in order to retrieve data for a chart.  A chart can be associated with only one query at a time.  When you draw the chart, Graphics Builder uses the data from the current query, unless you specify a different one.


About chart templates

A chart template defines the format of a chart and its various properties.  A chart can be associated with only one chart template at a time.  However, you can perform the following actions on an individual chart template and then use that template to apply the properties to multiple charts.

•	Specify axis frame properties

•	Specify discrete, continuous, and date axis properties

•	Move the legend

•	Define reference lines

•	Specify number and date formats

•	Specify text and line properties

•	Specify colors and patterns

Each chart template can be associated with one or more field templates, which define the properties of the individual fields, such as bars, columns, pie slices, or lines.


About chart types

The following list describes the available types of charts you can create, and their suggested usage:

Column	Use this chart type to compare sets of data ranges vertically.  For example, use a column chart to show the quarterly sales revenue generated by each sales representative.
Pie	Use this chart type to compare the ratios or percentages of parts of a whole.  For example, use a pie chart to compare annual revenue by department or quarter.
Bar	Use this chart type to compare sets of data ranges horizontally.  For example, use a bar chart to compare monthly revenues.
Table	Use this chart type to show data in a table format.  For example, use a table chart to show an employee organization chart.
Line	Use this chart type to show vertical changes for a specific set of data.  For example, use a line chart to gauge daily or hourly changes in a stock's value.
Scatter	Use this chart type to show data along two value axes.  Scatter charts are well suited for showing standard deviations.  For example, use a scatter chart to plot the ages and salaries for your employees.  If there is a correlation between the two sets of data, the points will be grouped together fairly closely.  One or more points well outside the group could indicate a salary disparity.
Mixed	Combines multiple plot types such as column and line.  For example, use a mixed chart to show daily sales revenue, with a line plot type to provide a summary view of the data.
High-low	Use this chart type to show values fields that correspond to high, low, and close (i.e. stock prices).  For each row in your query, a high-low range is plotted on the chart.
Double-Y	This chart type provides two independent Y-axes on which to plot data.  Each Y-axis can show a different range of values.  For example, you could use one axis to represent revenue, the second to represent income, and plot both over a course of time.
Gantt	Use this chart type to show sets of project data over a given amount of time.  Gantt charts are generally used to show project milestone timelines.


About axis charts

  Example

Most of the charts you can create in Graphics Builder are axis charts.  An axis chart is a chart in which the data is plotted according to where it lies along the edges of the chart, called axes.  Column, Bar, and Line charts are all Axis charts.  An axis chart may contain two or three axes, each of which may be one of the following types:

•	discrete

•	continuous

•	date

Usage Notes: If you are creating axis charts, the X and Y axis labels are derived from the column names assigned to the table in your query.  You can either customize those axis labels using the Axis property sheet, or you can specify a column name alias in your query. If you plan to use chart templates, it's a good idea to assign customized axis labels in your query.


Example:  Assigning customized axis labels in queries

/*The following example demonstrates how you can
**customize axis labels by specifying a column
**name alias in your query.
*/

select warehouse_id "Warehouse ID",
amount_in_stock "Inventory Levels"
from s_inventory


About discrete axes

A discrete axis is one that plots distinct values at fixed intervals.  These values are not mathematically related.  Category (independent) data is usually plotted along this axis, also called the category axis.

For example, employee names may be plotted along a discrete axis.  However, their salaries cannot (since monetary values are related by one being mathematically greater than another).


About continuous axes

A continuous axis is one that plots mathematically related values.  The axis begins at one value, and continues until it reaches another value.  The plotting interval depends on where the data values fall between the lower and upper limits of the axis.  Value (dependent) data is usually plotted along this axis, also called the value axis.

For example, employee salaries may be plotted along a continuous axis.  However, employee names cannot.


About date axes

A date axis is one that plots date values.  The axis begins at one date, and continues until it reaches another date.  (In this respect, a date axis resembles a continuous axis; however, Graphics Builder treats them very differently.)  The plotting interval depends on where the data values fall between the lower and upper limits of the axis.

For example, employees' hire dates may be plotted along a date axis.


Creating a chart from a new query in the Layout Editor

To create a chart:

1	Choose File [image] Connect to connect to a database if you are not already connected.

2	Select the Chart tool in the Tool palette and either select in the layout or drag out a region for the chart.

Alternatively, you can choose Chart [image] Create Chart from the menu.

If you do not drag out a region for the chart, Graphics Builder will use a default size.

If you have existing queries in your display, the Chart Genie dialog appears.  If you have no existing queries, the New Query dialog appears.

To create a query:

3	If the Chart Genie appears, select the New Query radio button; then select OK to show the New Query dialog.

4	Type a SQL SELECT statement in the SQL Statement field, or select an alternative query type.

5	Select Execute to execute the query.

You can view the data returned in the Data property page.

To specify chart properties:

6	Select OK to close the New Query property sheet and show the Chart property sheet.

7	(Optional)  Enter a name and title for your chart.

8	Select a Chart Type and Subtype.

9	Select OK to create the chart.

The chart is drawn in the Layout Editor.  The chart object appears in the Object Navigator.  The chart region is the area covered by the chart.  The tick labels and legend may extend beyond this.

You can now manipulate the chart object (select, move, resize, delete, etc.) as you would other object on the layout, or modify its properties.


Creating a chart from an existing query

To create a chart from an existing query:

1	In the Layout Editor, select the Chart tool in the Tool palette and either select the layout or drag out a region for the chart.

Alternatively, you can choose Chart [image] Create Chart from the menu.

If you do not drag out a region for the chart, Graphics Builder will use a default size.

The Chart Genie dialog appears.

2	Select an existing query from the Existing Query drop-down list.

3	Select OK to accept the dialog and show the Chart property sheet.

4	(Optional)  Enter a name and title for your chart.

5	Select a Chart Type and Subtype.

6	Select OK to create the chart.

The chart is drawn in the Layout Editor.  The chart object appears in the Object Navigator.  The chart region is the area covered by the chart.  The tick labels and legend may extend beyond this.

You can now manipulate the chart object (select, move, resize, delete, etc.) as you would other object on the layout, or modify its properties.


Creating a chart programmatically

To create a chart programmatically:

1	If necessary, define the template you wish to use.

2	Create the query you wish to use.

3	Create the PL/SQL program unit.  Example


Example:  Creating a chart programmatically

/* The following example assumes that the template
**and query have already been defined. It executes
**the specified query and stores the results
**internally.
*/

PROCEDURE create_chart IS
/* Declare the variables */
   the_chart      OG_OBJECT;
   ch_pos         OG_POINT;
   ch_hy          NUMBER;
   ch_wi          NUMBER;
   the_query      OG_QUERY;
   the_template   OG_TEMPLATE;
   indep_field    OG_FIELD;
   dep_field      OG_FIELD;
BEGIN
/* Get the template and query that have already been
      defined in the Builder */                               the_template:=OG_GET_TEMPLATE('template0');
   the_query:=OG_GET_QUERY('query0');
/*Set the position of the chart in X/Y coordinates*/
  ch_pos.x:=0*OG_INCH;
  ch_pos.y:=0*OG_INCH;
/*Set the height and width of the chart */
  ch_ht:=3*OG_INCH;
  ch_wi:=3*OG_INCH;
/* Make the chart */
  the_chart:=OG_MAKE_CHART(chpos, ch_ht, ch_wi,
the_template, the_query);
/* Define a field for ENAME */
  indep_field.field_type:=OG_INDEPENDENT;
  indep_field.colname:='ENAME';
/* Insert it into the chart in the 0th position */
  OG_INSERT_FIELD(the_chart, indep_field, 0);
/* Define a field for SAL */
  dep_field.field_type:=OG_DEPENDENT;
  dep_field.colname:='SAL';
  dep_field.ftname:='column';
/* Insert it into the chart in the second position */
  OG_INSERT_FIELD(the_chart, dep_field, 1);
/* Define as field for COMM */
  dep_field.field_type:=OG_DEPENDENT;
  dep_field.colname:='COMM';
  dep_field.ftname:='column';
/* Insert it into the chart in the last position */
  OG_INSERT_FIELD(the_chart, dep_field, OG_LAST);
/* Execute the query for the first time*/
  OG_EXECUTE_QUERY(the_query);
/* Update the chart so the new field and query
      information takes effect */
  OG_UPDATE_CHART(the_chart, OG_ALL_CHUPDA);
END;


Creating a query during chart creation

  Related Topics

To create a query during chart creation:

1	Choose Chart [image] Create Chart.

Alternatively, you can select the Chart tool in the Layout Editor Tool palette and either select the display area, or drag out a region for the chart.

If you have no existing queries, the New Query dialog appears.  If you have existing queries, the Chart Genie appears.

2	If the Chart Genie appears, select the New Query radio button and select OK to show the New Query property sheet.

3	Type a SQL SELECT statement in the SQL Statement field, or select an alternative query type.

4	Select Execute to execute the query.

You can view the data returned in the Data property page.

5	Select OK to close the New Query property sheet and show the Chart property sheet.

Select your chart options and then select OK to create the chart.

Creating queries at chart creation time combines two actions into one process so you can quickly create a chart without having to define your query separately.  After you create the new query with your chart, both objects are listed in the Object Navigator.


About specifying chart data

Each column in the query contains either category or value data.  You need to map that data to elements in your chart to create a meaningful representation of data.  To do so, keep in mind the following considerations:

•	Data classification

•	Field mapping

•	Data filtering


About data classification

Data from your query’s columns can be classified in one of two ways:

•	Category

•	Value

The type of data determines how it may be displayed in a chart.


About categories

A category is a piece of data that has a value associated with it.  For example, if you are interested in knowing the salaries of various employees, the employee name would be the category.  Then you could chart the salary for each employee (i.e., the value for each category).

Columns in a query that contain categories are often called independent because the category does not depend on any other piece of data.  Using the above example, the employee name does not depend on any other piece of data.

Categories are usually plotted along a discrete or date axis, which may then also be called a "category axis."


About values

A value is a piece of data that is associated with a category.  For example, a quantity of 5000 must be associated with a specific product (the product is the category).

Columns in a query that contain values are often called dependent because the value depends on another piece of data.  Using the above example, knowing the quantity of 5000 is meaningless unless you also know the product that that quantity refers to.  The quantity value depends on a specific product.

Values are usually plotted along a continuous axis, which may then also be called a "value axis."


About field mapping

Field mapping is the process by which you specify which columns in the query to include in the chart, how the columns will be represented as chart fields, and the order in which the fields are plotted.  Field mapping also involves associating Value (dependent) data fields with field templates such as column, or bar.

When you first create a chart, Graphics Builder does the field mapping automatically, based on the way and order that columns appear in the query property’s Data page, and the current field template.  You can change the defaults, by selecting the chart, opening its property sheet, and modifying the settings in the Values and Categories pages.

When you first create a chart, Graphics Builder maps the query columns to the categories and values plotted in the chart.  However, you need to change the category and value columns whenever you change information the chart is currently using—specifically, when you do any of the following:

•	add or remove a data field from the chart

•	change the order in which data fields are plotted

•	change column names by adding aliases in the query

•	delete a column from the query

•	add a sub-category to the chart

•	rename or delete a field template

•	add a field template to be used


Assigning category and value columns

To assign category and value columns:

1	Double-click on the chart to show the Chart property sheet.

2	Select the Categories tab to show the Categories property page, or select the Values tab to show the Values property page.

3	Change options as follows:

•	To add to the list of chart categories or values, select a column from the Query Columns list and then select Insert.

•	To change the order in which chart categories and values are plotted, select the category or value column and then select either Top (to the top of the list), Bottom (to the bottom of the list), Up (up one item), or Down (down one item).

•	To delete a category or value column from its respective list, select the column and then select Delete.  Deleting a category or value column from the list does not delete the column from the query.

•	To associate a chart value column with a field template, select the value column from the list and then choose a field template from the Field template drop-down list.

4	Select OK to apply the changes and close the Chart property sheet.


Creating a break chart

To create a break chart:

1	Create a column or bar chart or open the Chart property sheet for an existing column or bar chart.

2	Choose the Categories tab to show the Categories property page.

3	Make sure only one category is listed in the Category list.

4	Select a sub-category from the Sub-category drop-down list.

5	Select OK to apply the change and close the Chart property sheet, or select Apply to apply the changes without closing the Chart property sheet.


About drill-down relationships

Using Graphics Builder, you can establish drill-down relationships between "master" and "detail" charts in a display. To establish a drill-down relationship between charts, do the following:

At runtime, users can select on an element within the master chart to "drill down" to detailed information about that element.  For example, in a pie chart showing company expenses for each department, you could select a pie slice to show detailed information about that department.

Drill-down relationships are based on parameters.  The master chart sets the parameter value, and the detail chart uses this value in its query.  When the user selects a chart element in the master chart, Graphics Builder does the following:

•	determines the data value represented by the chart element

•	assigns the value to a parameter

•	executes the detail query that references the parameter

•	updates the detail chart

You can modify drill-down relationships.  For example, you may wish to specify a different query to be executed, or set the parameter value to a different column.  Just as there is no direct programming involved in creating a drill-down relationship between two charts, there is no programming involved in modifying a drill-down relationship either.


Creating a drill-down relationship between two charts

To create a drill-down relationship between two charts:

1	Select the master chart.  This is the chart that will "drive" the drill-down action.

2	Select the chart element that you want to use to determine the value of the parameter.  This can be a tick label, a pie slice, etc.

Remember, the parameter represented by the chart element will be used in the query for the detail chart.  The parameter establishes the master-detail relationship.

3	Open the property sheet of the chart element you have selected.  (Double-click on a selected chart element or choose Properties from the pop-up menu, or choose Tools [image] Properties).

4	Choose the Drill-down tab to show the Drill-down property page.

5	Select New to create a new parameter.

The Parameters dialog appears.

6	Accept the default parameter name, PARAMn, or type a new name in the Name field.

7	From the Type drop-down list, select a data type (CHAR, NUMBER, or DATE).

The datatype you select for the parameter should match the datatype of the column the parameter will represent.

8	(Optional)  Type an initial value for the parameter in the Initial Value field.

9	Select OK to accept the new parameter.

The Parameters dialog closes and you return to the Object property sheet.

10	From the To Value Of drop-down list, select the column name that represents the chart element you selected to be the value source for the parameter.

11	From the Execute Query drop-down list, select the query that will update the drill-down detail chart.

12	Select Edit so you can add the parameter to the query.

The Query property sheet appears.

13	Edit the query to include the parameter you have created. Example

14	Select OK to accept the edits to the query and return to the Object property sheet.

15	Select OK to accept the drill-down procedure.

16	Save and run the display to test the procedure.  Try selecting on the chart element in your master chart and watch the result as the detail chart is updated with the resulting query data.

Notice that the above procedure did not involve any PL/SQL code.  You can use the Object property sheet to create a drill-down event for any object in your display.


Example:  Adding a parameter to a query

/*To edit a query to include a parameter you have created, you might add a
**WHERE clause to the existing query as follows:
*/

WHERE column1 := :PARAM0


Modifying a drill-down relationship

To modify a drill-down relationship:

1	Open the Object property sheet for the chart element that drives the drill-down procedure.

2	Select the Drill-down tab to show the Drill-down property page.

3	Select your new options.

4	Select OK to accept the new drill-down relationship and close the Object property sheet.

If you wish to modify the parameter itself, you can either access it through the Object property page by selecting Edit to show the Parameters dialog, or through the Object Navigator.


About the Interpreter

  Related Topics

Graphics Builder uses Procedure Builder features and functionality -- namely, the Interpreter -- to allow you to debug the PL/SQL program units used in your displays.

You can perform Procedure Builder operations either using menus, editors, and command dialog boxes, or by typing commands on the Interpreter command line.

The Interpreter is the central debugging workspace of Procedure Builder.  It is a paned window that enables you to define, display, and debug your PL/SQL program units using a command line.

Depending on the context in which Procedure Builder is invoked, the Interpreter can be presented in two ways:

•	modal

•	modeless

While entering commands on the command line, you can use the New Prompt command from the pop-up menu to abandon the command and show a new PL/SQL prompt in the Interpreter pane.

You can record all Interpreter input and output to a log file if you wish to retain a record of your debugging session.


About Interpreter components

The Interpreter has five main components:

menu bar (modeless only)

control bar

Source pane

Navigator pane

Interpreter pane

Both types of Interpreters have identical functions.  However, since menus are not accessible in modal windows, the modal Interpreter contains additional buttons for accessing functions that are available via menus in the modeless Interpreter.

Pop-up menus containing many common commands are available in the different panes.

For a more detailed description of the Interpreter, see the "Working with the Interpreter" chapter in the Procedure Builder Developer's Guide.


Menu bar (modeless only)

Shows the menu commands to perform most tasks.


Control bar

Contains buttons you can use as accelerators for most common tasks.


Source pane

Allows you to show a program unit's source and define debug actions.


Navigator pane

Shows the object hierarchy for the current session (debugging nodes only in the modal interpreter).

In the modeless Interpreter, the Navigator can be hidden.


Interpreter pane

Provides a command line where you can enter  any PL/SQL constructs and Procedure Builder commands.


Displaying the modal Interpreter

To display the modal interpreter:

  The modal Interpreter is presented automatically by Graphics Builder while executing an application (e.g., during runtime simulation of a display, Graphics Builder encounters a breakpoint you have set in a program unit).  When the modal Interpreter is opened, execution of both the application and its PL/SQL is suspended until you close the modal Interpreter window.


Displaying the modeless Interpreter

To display the modeless Interpreter:

  Choose Tools [image] PL/SQL Interpreter.

The modeless Interpreter appears.  By default, the modeless Interpreter does not contain the Navigator pane.  Any debugging actions you take in the modeless Interpreter can be accessed through objects in the Graphics Builder Object Navigator.

Alternatively, you can insert the Navigator pane at any time by choosing View [image] Navigator Pane from the menu.

You can invoke the modeless Interpreter at any time, either in the Builder, or during runtime simulation.


About debugging displays

  Related Topics

Based on the error and the conditions under which it occurred, you can usually track down the source of the error.  If you have nested program units, use the first program unit in the sequence to trace the error down to the source.

For example, you have a button procedure A that calls program unit B that calls program unit C.  An error is encountered during execution of one of these program units and a PL/SQL exception is raised.  In this case, you would select program unit A to trace the source of the error.

If it is not immediately apparent how to fix an error, you may wish to set a debug action to help you locate the source of the problem.  For example, the offending program unit may contain calls to subprograms, loops, or other control expressions that make it difficult to locate the exact source of the problem.

Debug actions enable you to monitor and/or interrupt the execution of PL/SQL program units.  There are two types of debug actions:

•	breakpoints

•	debug triggers

In addition, you can use the DEBUG package to specify debugging tasks such as setting a breakpoint, suspending execution of the program unit and returning control to the Interpreter, retrieving and setting variable and parameter values, or interpreting PL/SQL commands.

You can set debug actions either in the Builder or in the debugger.  Where you decide to set the debug actions depends on the complexity of your program units and the display itself.


About testing your display in runtime simulation

  Related Topics

The simplest way to test your display is to use the Graphics Builder runtime simulation mode (also called the debugger).  From the Builder, you can run your display and test it in a separate debugging window.  This allows you to quickly test and debug your display, and return to the Builder to perform any necessary fixes.

When you test a display in runtime simulation, Graphics Builder minimizes all other currently open windows except for the Object Navigator.


About setting debug actions in Graphics Builder

If you set debug actions in the Builder and then run your display, the modal Interpreter will automatically appear when a debug action such as a debug trigger is reached.  When the modal Interpreter appears, execution of your display and its PL/SQL is suspended until you close the Interpreter.

Some considerations for setting debug actions in the Builder include the following:

•	you want to set a debug action on an Open Display trigger that is fired as soon as the display is run

•	you want to retain the debug action for future use

If you set a debug action in the Builder and then make modifications to the program unit and recompile it, you may need to modify the debug action to change its source location.  Debug actions are associated with line numbers in the program unit source.


About setting debug actions in the debugger

Setting debug actions in the debugger allows you to debug on-the-fly in the modeless Interpreter.

Once you close the display in the debugger, all debug actions you have set in program units will be lost.  If your debug actions consist only of breakpoints and simple debug triggers, this may not be a consideration to you.

If you debug your program units directly in the debugger, your changes are not reflected in the Builder.


About using breakpoints

The most common type of debug action is the breakpoint.  Breakpoints are handy for incrementally monitoring execution of program units.

Graphics Builder suspends execution of the program unit just before reaching the line on which the breakpoint is specified.  At this point, you can use Procedure Builder's features to inspect and/or modify the program state (i.e. variable values).  Once satisfied, you can resume execution with the GO or STEP commands, or you can abort execution using the RESET command.

For example, suppose you have a procedure that contains a counting loop.  The loop calls a function and increments the value of a local variable.  To ensure that the variable is assigned the correct value for each cycle of the loop, you could place a breakpoint on the line directly after the variable assignment.  When the breakpoint is reached and the procedure is interrupted, you can examine the call stack trace in the Navigator to check the variable value, then use the STEP command to cycle to the next breakpoint.


About using debug triggers

  Related Topics

Debug triggers are a more general form of debug action.  A debug trigger associates a block of PL/SQL code with a specific source line within a program unit.

Graphics Builder executes a debug trigger just before reaching the line on which the debug trigger is specified.  You can assign a debug trigger to fire at any of the following locations:

•	upon reaching a single line in a program unit (e.g., the current source location, line 5, line 23, etc.)

•	every time the Interpreter takes control (i.e., whenever it suspends program execution due to a breakpoint, program stepping, etc.)

•	every PL/SQL source line being executed

Debug triggers are especially handy for setting conditional breakpoints.  You can raise the exception DEBUG.BREAK from within the trigger body.  For example, the debug trigger shown below establishes a conditional breakpoint on line 10 of my_proc, which will be reached only if the local NUMBER variable my_sal exceeds 5000:

PL/SQL> .trigger proc my_proc line 10 is
     +> IF DEBUG.GETN('my_sal') > 5000 THEN
     +>   RAISE DEBUG.BREAK;
     +> END IF;


About using debug levels

  Related Topics

When a debug action interrupts program execution, the Interpreter takes control and establishes what is known as a debug level.  At a debug level, you can enter commands and PL/SQL statements to inspect and modify the state of the interrupted program unit, as well as resume execution.

Since any PL/SQL code interactively entered at a debug level may itself be interrupted (for example, by encountering another breakpoint), it is possible for debug levels to nest.  To facilitate distinguishing one debug level from another, the levels are numbered.  The most deeply nested level is assigned the highest number.  Numbering starts at zero with the outermost level.

The 0th or outermost level is commonly referred to as top level  .  The top level has no associated program state since it is the outermost level at which program units are originally invoked.  When code invoked from the top level is interrupted, debug level 1 is established.  Similarly, interrupting code invoked from debug level 1 establishes debug level 2, and so on.

The Interpreter command prompt reflects the current debug level.  When the Interpreter enters levels below the top level, the prompt includes a prefix containing the current debug level number.  For example, the Interpreter command prompt at debug level 1 appears as shown below:

(debug 1)PL/SQL>

You can use the RESET command to return control to an outer debug level without continuing execution in the current debug level.


About controlling program unit execution

Once you have inspected and/or modified the program state following a debug action, you can control execution of the program unit as follows:

stepping through the program unit

resuming execution

cancelling program unit execution


About logging Interpreter input and output

Procedure Builder enables you to keep a record of Interpreter input and output when you are debugging program units.  After you enable logging, commands typed in the Interpreter — and any resulting Interpreter output messages -- are appended or written to a log file until you disable or terminate logging.


About command line options for logging

You can control logging by entering one of the following commands in the Interpreter:

•	LOG

•	DISABLE (Logging)

•	ENABLE (Logging)

For more information on these and other Procedure Builder commands, select the Interpreter Command Reference from the Help Contents.


About correcting errors

  Related Topics

You can correct errors either in the debugger, or in the Builder.  If you correct and recompile program units in the debugger, your changes will not automatically be reflected in the Builder.  If you make multiple changes to program units in the debugger, you should synchronize the program units in the debugger with those in the Builder.  If you make your changes in the Builder, remember to save and run your display again to make sure your changes have fixed the error.


About synchronizing program units

If you corrected your PL/SQL errors in the debugger, you should synchronize the contents of the corrected program units in the debugger with the contents of the program units in the Builder.  The synchronize operation replaces the program units in the Builder with those from the debugger.


About dealing with unhandled exceptions

If Graphics Builder encounter any errors during runtime simulation, it provides an error message alert with an error message number.  Make sure you note the error message number and under what conditions it occurred.  Was it upon opening the display?  After you attempted to drill-down on a chart or selected on a button?

See the Troubleshooting section for more information on Graphics Builder error messages.

An error message OG-00637 indicates that an unhandled PL/SQL exception has been encountered.  Note the exception number listed in the error message as this will determine where you can track down the exception error text that explains the possible cause of the error.

Graphics Builder provides a number of built-in PL/SQL exceptions for errors encountered with any Graphics Builder built-in procedures, functions, or datatypes.  Graphics Builder built-in exceptions are documented in the Graphics Builder Reference Manual both by number and by name.


Testing your display in runtime simulation

  Related Topics

To test your display in runtime simulation:

1	Select the Run tool in either the Object Navigator or the Layout Editor, or choose File [image] Run to run the active display.

If multiple displays are open, select the display object in the Navigator for the display you wish to run, then select the Run tool.

If the display has not recently been saved, Graphics Builder creates a temporary file of the current state of the display and runs that.  If you have not saved the display at all, you will be prompted to do so before Graphics Builder runs it.

If no displays are currently open in the Builder, you will be prompted to select one.

The runtime version of the selected display is opened in a separate Graphics Builder Debugger window.

2	Test any drill-down relationships or button procedures to make sure they behave correctly.  If you have any active timers, make sure they are operating and producing the correct results.

If your display works in runtime simulation, you can now safely generate your display.  However, if you make any other changes to your display before generating it, it is a good idea to run the display again to test your changes.


Tracing errors

  Related Topics

To trace errors:

1	Expand the display_name<debug> node in the Object Navigator.

2	Double-click on the program unit to show the program unit in the Program Unit editor.

If you are searching for an error in a sequence of nested program units, open the first program unit in the sequence.  For example, if the error occurred as a result of selecting a button, open the associated button procedure.

The compilation errors associated with that program unit are shown in the pane below the program unit source.  If you are dealing with nested program units, the last program unit to be called before the error was encountered appears at the top of the error stack.


Setting breakpoints

To set a breakpoint:

1	Choose Tools [image] PL/SQL Interpreter to show the PL/SQL Interpreter.

2	In the Navigator, select the program unit you wish to debug.

The program unit appears in the Interpreter's Source pane.  Each line is numbered.

3	Double-click on the line on which you want to set the breakpoint.  The breakpoint is inserted.

You can also define a "break trigger" for a breakpoint.  A break trigger is a PL/SQL block that executes each time the breakpoint is reached.  This block might contain a Procedure Builder command that should be performed each time the breakpoint is reached.

You can use the BREAK command in the Interpreter pane to insert a breakpoint at a specified source line.


Setting debug triggers

To set a debug trigger:

1	Choose Tools [image] PL/SQL Interpreter to show the PL/SQL Interpreter.

2	In the Navigator, select the program unit you wish to debug.

The program unit appears in the Interpreter's Source pane.  Each line is numbered.

3	Select the line where you wish to place the debug trigger.

4	Choose Trigger from the pop-up menu, or choose Debug [image] Trigger to show the PL/SQL Trigger dialog.

5	Type the body of the trigger in the Trigger Body field.

6	Select OK to accept the trigger and close the dialog.

For more information about creating debug triggers, see the Procedure Builder online help.


Stepping through the program unit

To step through the program unit:

  Use the STEP command to incrementally step through your interrupted program unit.  Control returns to the Interpreter after the specified set of statements have been executed.  There are four variations of the STEP command for  temporarily resuming execution of an interrupted program.

You can invoke the STEP command either by choosing one of the  buttons from the control bar, or by entering it on the Interpreter command line.


Resuming program unit execution

To resume program unit execution

  Use the GO command to resume execution of a program indefinitely -- that is, until either the currently executing thread of execution terminates or is interrupted again due to a debug action.  You can invoke the GO command either by choosing the Go button from the control bar or by entering it on the Interpreter command line.


Cancelling program unit execution

To cancel program unit execution:

  Use the RESET command to return control to an outer debug level without continuing execution in the current debug level.  Thus, RESET effectively aborts execution at the current (and possibly higher) debug levels.

You can invoke the RESET command either by choosing the Reset button in the control bar, or by entering it on the command line in the Interpreter.


Enabling a log file

To enable a log file:

1	Choose Debug [image] Log to show the Log Interpreter dialog.

2	Type a directory path and log file name in the File field, or select Find to open your operating system file dialog where you can select an existing log file.

3	If you wish to append the current log to an existing log file, select the Append check box.

4	Select OK to accept your changes and close the dialog.


Disabling a log file

To disable a log file:

1	Choose Debug [image] Log to show the Log Interpreter dialog.

2	Select the Disabled check box.

3	Select OK to accept your changes and close the dialog.


Viewing a log file

To view the contents of an existing log file:

  Choose Debug [image] Interpreter Log to show the Interpreter Log browser.

or

1	Choose Debug [image] Log to show the Log Interpreter dialog.

2	Select the Show Log check box.

3	Select OK to accept your changes and close the dialog.

The Interpreter Log browser appears.


Synchronizing program units

To synchronize program units:

  Choose Edit [image] Synchronize Program Units from the menu.


Procedure Builder packages

  Related Topics

In addition to the Graphics Builder built-in PL/SQL datatypes, functions, and procedures, Procedure Builder provides the following built-in PL/SQL packages that contain many PL/SQL constructs you can reference while debugging your program units:

DDE	ORA_PROF
DEBUG	TEXT_IO
LIST	TOOL_ENV
OLE2	TOOL_ERR
ORA_FFI	TOOL_RES
ORA_NLS


DDE

Provides Dynamic Data Exchange support.


DEBUG

Provides procedures, functions, and exceptions for debugging PL/SQL program units.


LIST

Provides procedures, functions, and exceptions you can use to create and maintain lists of character strings (VARCHAR2).  This provides a means of creating arrays in PL/SQL Version 1.


OLE2

Provides a PL/SQL API for creating, manipulating and accessing attributes of OLE2 Automation Objects.


ORA-FFI

Provides a public interface for calling out to foreign(C) functions from PL/SQL.


ORA-NLS

Enables you to extract high-level information about your current language environment.


ORA-PROF

Provides procedures, functions, and exceptions you can use for tuning your PL/SQL program units (i.e. examining how much time a specific piece of code takes to run).


TEXT-IO

Provides constructs that allow you to read and write information from and to files.


TOOL-ENV

Allows you to interact with environment variables.


TOOL-ERR

Allows you to access and manipulate the error stack created by other built-in packages such as DEBUG.


TOOL-RES

Provides you with a means of extracting string resources from a resource file with the goal of making PL/SQL code more portable by isolating all textual data in the resource file.


About the components of the Layout Editor

The Layout Editor is the main work area in Graphics Builder.  It is where you design the layout of your display, by creating and modifying graphical objects (lines, polygons, rectangles, text, etc.).

Every display contains exactly one layout, and every layout belongs to exactly one display.

The Layout Editor has the following components:

layout

toolbar

objects

rulers

grid

views

tool palette

status line


About the layout

The layout is where you can create, modify, or delete objects.  The appearance of objects on the layout represents exactly how those objects will appear when the display is run.  In the Layout Editor, you can change the size, shape, color, and other graphical properties of objects, and see the results immediately.


About the toolbar

The toolbar runs horizontally across the top of the Layout Editor and provides buttons that perform common menu commands such as Save, Run, Cut, Copy, and Paste.

To show the name of a tool in the toolbar, move the mouse over a button.  The name of the tool appears as a pop-up message, and a short description of the tool appears in the status line.


About graphic objects

The graphical objects that you can create and modify on the layout include arcs, charts, images, lines, polygons, rectangles, rounded rectangles, symbols, and text objects.


About rulers

Rulers are located around the left and top edges of the layout, and can be used as a reference when sizing or positioning objects.  To show or hide the rulers, choose View [image] Rulers.  Rulers are shown by default.

Ruler markers are lines that appear in both rulers, and that move to follow the horizontal and vertical position of the cursor.  This makes it easier to position the cursor more precisely, by using the ruler markers as a reference.

A ruler guide is a dashed line on the layout that is parallel to a ruler, and can be used as a point of reference when sizing or positioning objects.  Ruler guides appear on the layout in the Builder only, and are not visible when the display is run or printed.

To show or hide ruler guides, choose View [image] Ruler Guides.  Ruler guides are shown by default.


About the layout grid

The layout grid is a series of equidistant horizontal and vertical dashed lines that you can use as a reference when sizing or positioning objects.  You can set the interval at which grid lines appear, based on the rulers' unit of measurement.  Grid lines appear on the layout in the Builder only, and are not visible when the display is run or printed.

To show or hide the grid, choose View [image] Grid.  The grid is shown by default.

Grid snap is a feature that forces the cursor to align itself with the grid whenever you move it close to a grid line.  This provides greater accuracy and control when sizing or positioning objects.  You can set the number of "snap points" between each pair of grid lines that the cursor will snap to.

To activate or deactivate grid snap, choose View [image] Grid Snap.  Grid snap is deactivated by default.


About views

A view is a part of the layout that is focused on one small section of your display.  Each layout is initially shown with one large view, but you can create up to four views, each of which can focus on a different object, part of an object, or layer.  In addition, each view can have its own layer, ruler, grid, and magnification settings.

Each view is independent and has its own settings, such as rulers units, grid visibility, magnification, etc.  Each view can also scroll the layout independently.

The view that you are currently working in is called the "active" view.  You can recognize the active view by its scroll bars being enabled; the scroll bars of the inactive view(s) will be disabled.

Any changes you make to ruler, grid, and other settings will be applied only to the active view.  Any changes you make to objects that appear on the layout will be reflected in all views focusing on that part of the layout.


About the tool palette

The tools you use for drawing and modifying objects on the layout appear as separate icons in the Tool palette.  To use a tool, you need to activate it, using one of the following methods:

•	for a single operation, select its icon.  After you perform the operation, the default tool becomes active again.

•	for multiple operations, double-click on its icon.  The entire icon is highlighted and the tool remains active until you activate another tool.

Only one tool can be active at a time.  The Select tool is the default tool.

To show the name of a tool in the Tool palette, move the mouse over a button.  The name of the tool appears as a pop-up message, and a short description of the tool appears in the status line.


About the status line

The status line shows the following information:

•	absolute mouse position (in the currently selected ruler unit)

•	mouse drag distance (in the currently selected ruler unit)

•	rotation angle

•	zoom level

The information that appears on the status line varies based on the tool being used and the action being performed.  The following table shows what is shown on the status line under different circumstances:

Tool	Action	Status Information

Every tool	moving mouse	x, y coordinates of cursor; zoom level
Arc, Ellipse, Rectangle, Rounded Rectangle	creating object	x, y coordinates of cursor starting position; object width and height; zoom level
Freehand	creating object	x, y coordinates of cursor; zoom level
Line	creating object	x, y coordinates of cursor; line length; rotation angle (from horizontal); zoom level
Magnify	selecting mouse	zoom level
Polygon, Polyline	creating object	x, y coordinates of cursor; rotation angle (from horizontal); zoom level
Rotate	moving object	horizontal and vertical distance from original position; zoom level
Rotate	rotating object	rotation angle from original position; zoom level
Select	moving object	horizontal and vertical distance from original position; zoom level


Setting preferences

To set preferences:

1	Choose Tools [image] Tools Options to display the Tools Options property sheet.

2	Specify the desired preferences such as your sound output device, image compression algorithm, page size, etc.

3	You can apply the options for either the current session, or the current and all subsequent sessions:

•	To set preferences for the current session only, select OK.  Settings remain in effect until you end the current session.  Some settings take effect immediately, and others the next time you create or open a display.

•	To set preferences for the current and all subsequent sessions, select Save.  Settings are saved in your Graphics Builder preferences file, and remain in effect for subsequent sessions.

You can customize the layout to make it easier to create and manipulate objects.  The preferences you set are saved in a local preferences file on the file system.


Specifying a layout size

To specify a layout size:

1	Choose View [image] View Options [image] Layout to show the Layout Settings dialog.

2	Specify the desired layout size and page direction settings.

3	Select OK to confirm the settings and close the Layout Settings dialog.

Settings remain in effect for the current Builder session only.


Showing the entire layout

To show the entire layout:

  Choose View [image] Fit to Window.

Magnification is decreased so that the entire layout is visible.


Increasing magnification

To increase magnification:

1	Select the Magnify tool from the Tool palette.

2	Select the layout where you want to increase magnification.

Magnification is increased by a factor of two (objects appear twice as large).  To double the magnification again, repeat the above steps.  The maximum possible magnification is 16 times.

While the objects may appear to be larger, their actual size does not change.


Decreasing magnification

To decrease magnification:

1	Select the Magnify tool from the Tool palette.

2	Hold down the Shift key and select the layout where you want to decrease magnification.

Magnification is decreased by a factor of one half (objects appear half as large).  To decrease the magnification by one half again, repeat the above steps.  You've reached the maximum possible reduction when the entire layout is visible.

While the objects may appear to be smaller, their actual size does not change.


Zooming in to the center of the layout

To zoom in to the center of the layout:

  Choose View [image] Zoom In.

This zooms the view by a factor of two.


Zooming out from the center of the layout

To zoom out from the center of the layout:

  Choose View [image] Zoom Out.

This zooms the view out by a factor of two.


Returning magnification to normal

To return magnification to normal:

  Choose View [image] Normal Size.

Magnification is returned to normal and objects appear as their actual sizes.


Specifying ruler and grid settings

To specify ruler and grid settings:

1	Choose View [image] View Options [image] Ruler to show the Ruler Settings dialog.

2	Specify the desired ruler and grid settings such as which unit of measurement to use, grid spacing, etc.

3	Select OK to confirm the settings and close the Ruler Settings dialog.

Settings remain in effect for the current Builder session only.  Rulers and grids are not visible at runtime.

When you change the rulers' unit of measurement, they are updated to reflect the change.  In addition, when you magnify or scroll to a new area of the layout, the rulers are updated accordingly.


Using ruler guides

To use ruler guides:

  Select the horizontal or vertical ruler and drag the ruler guide to the desired position.  Release the mouse button when the guide is positioned where you want it.


Moving ruler guides

To move the ruler guide:

  Select and drag the guide back to its original ruler.

Once positioned, you can move the ruler guide by dragging it to a new location.  You may place as many ruler guides on the layout as you wish.


Using grid snap

To use grid snap:

  Choose View [image] Grid Snap.

Grid snap toggles on or off, depending on the prior setting.  Settings remain in effect for the current Builder session only.  When you turn grid snap on, new objects you create, move, or resize will align with the grid snap points defined in the Ruler Settings dialog box.


Creating views

To create views:

  Use the split bars that are initially located to the right of the horizontal scroll bar and below the vertical scroll bar.

To see a splitbar, click here.

Views appear on the layout in the Builder only, and are not visible when you run or print the display.

To divide the layout into multiple views:

  Use the horizontal or vertical split bars on the scroll bar to create two, three, or four views:

  To create two views, drag the horizontal or vertical split bar to a new position.  This creates two views on one axis, each having a its own split bar on the alternate axis.

  To create three views, create two views, then split one of the views using its split bar on the alternate axis.

  To create four views, create two views, then split both views using their split bars on the alternate axis.

Views remain in effect for the current Builder session only, and are not visible at runtime.


Activating views

To activate a view:

  Select it.  The view is highlighted.

To work with a view, you need to activate it.  Only one view can be active at a time.


Resizing views

To resize a view:

  Drag its horizontal or vertical split bar to a new position.


Removing views

To remove a view:

  Drag its split bars back to their original positions on the scroll bars.


Specifying drawing options

To specify drawing options:

1	Choose Format [image] Drawing Options, and then choose one of the following:  General, Arc, Text, Rounded Rectangle, or Image.

A dialog box appears for the option you selected.

2	Specify the desired options.

Selections remain in effect for the current display until you change them again.

You can specify default options for certain objects to a be applied automatically when you draw them on the layout.  For example, options for text include alignment, scalable bounding box, scalable fonts, and wraparound.


About the components of the Object Navigator

The Object Navigator provides a hierarchical view all open displays and all the object in them and referenced by them.

The Object Navigator has the following components:

nodes display area

toolbar

location indicator

find field


About the nodes display area

The Nodes display area is the main component of the Object Navigator.  This is the area where all objects currently available to you are organized hierarchically.


About the toolbar

The Toolbar contains common commands also available from the Navigator or File menu, such as Save, Run, Create, Delete, Expand, and Collapse.


About the location indicator

The location indicator reveals the name of the currently selected object in the nodes display area.


About the find field

The Find field allows you to search for an object in the Navigator by typing in a partial or full name of the object.


About object hierarchy

Most objects in the Navigator hierarchy are automatically assigned one or more default subobjects, depending on the type of object.  There are two basic types of these default subobjects:

•	assignment

•	reference

For example, each graphic object contains assignment subobjects for a button procedure, an execute query trigger, and a set parameter function.  Each program unit contains reference subobjects for references contained in the program unit, and references to the program unit itself.

The following table shows the default subobjects for the first layer of objects in the Display node:

Node	Object	Default Subobjects

Layout	layerx	Button Procedure: None (or name) Execute Query: None (or name) Set Parameter: None (or name)
Templates	templatex	Referenced By
Queries	queryx	Custom Exec Trigger: None (or name) Post Exec Trigger: None (or name) Timer: None (or name) Referenced By
Parameters	PARAMx	Referenced By
Timers	timerx	Timer Procedure: None (or name) Referenced By
Program Units	name	Specification References Referenced By
These default subobjects are designed to help you track the cross references between objects in your display.  Specifically, between objects and program units, charts and templates, parameters and the objects that assign their values, etc.

For example, if you define a drill-down procedure on a graphic object to set the value of PARAM0, the Set Parameter node for the graphic object will be set to PARAM0.  Similarly, the Reference By node of PARAM0 would be set to object_name.


Expanding nodes

To expand a node and show its first layer of subobjects:

1	Select a node containing subobjects.

2	Select Expand or choose Navigator [image] Expand to show the node's first layer of subobjects.

Alternatively, you can simply select the node's highlighted plus sign to expand the first layer of subobjects.

To expand a node and show all of its subobjects:

1	Select a collapsed node.

2	Select Expand All or choose Navigator [image] Expand All to show all of the node's subobjects.


Collapsing nodes

To collapse a node:

1	Select the expanded node.

2	Select Collapse or choose Navigator [image] Collapse.  The node's subobjects are hidden.

The collapsed node is prefaced with a highlighted plus sign.

Alternatively, you can simply select the node's highlighted minus sign to collapse the first layer of subobjects.

To collapse a node and hide all of its subobjects:

1	Select an expanded node.

2	Select Collapse All or choose Navigator [image] Collapse All to hide all of the subobjects.


Searching for objects

To search for objects:

1	Type the name, full or partial, of the object you wish to find in the Find field.

As soon as you begin typing, Graphics Builder begins an incremental forward search from the top of the Object Navigator.  The incremental search continues until you stop typing.

Graphics Builder expands nodes as necessary to reveal its current location during the search.

2	Select either Search Forward or Search Backward to find the next or previous occurrence of the search criteria in the Object Navigator.

Wild cards are not currently supported in the Find field.


About preparing a display for embedding

Before you can embed your Graphics Builder display in an application built using a different tool, you should prepare your environment and your display so the tools can work together in an optimal fashion.  Listed below are some of the issues to take into consideration:

•	locating modules

•	populating query columns using an external source

•	sizing the display

•	executing the display

•	receiving text parameters

•	receiving data

•	building the layout


About populating query columns using an external source

When you include a Graphics Builder chart in another Oracle product such as Form Builder or Report Builder (included with Reports Developer), the chart will use the data from the calling product's query as long as the query columns used to create the chart and the columns used in the calling product's query match.

If the chart you are building will only be called by another Oracle product, you can use a custom query to create an "empty" chart.  This chart will be populated with data when it is invoked by the calling product.  Use the custom query Schema property page to create columns with the same names as the query used by the calling product.  Then define the chart's properties as you normally would, assigning category and value data, etc.

The chart will appear in the layout with no data in it.

When the Graphics Builder display is called by the other product, the calling product's query is substituted for the custom query, and because the column names are the same, the chart is drawn to your specifications.


About locating modules

When Graphics Builder is called upon to execute an embedded display, it must be able to find the display.  Graphics Builder searches for files in the following order:

1	The directory path prefixed to the file name, if any.

2	Your "current" or "working" directory, as determined by your operating system.

3	The path specified by the GRAPHICS30_PATH environment variable.

4	The path specified by the ORACLE_PATH environment variable.

Ensure that you either explicitly specify the location of your display, or that your path variables are correctly set and one of them marks the location of your display.


About sizing the display

The size of a display as it appears in an application is not necessarily the size of the display in Graphics Builder.  When embedding a display, you need to determine whether you want to clip it, scale it, or create a display of the exact dimensions required to fit in the layout of the embedding application.

Because Oracle components use the same graphic definition system, you can instruct Form Builder to scale or clip the display to fit into the designated display region.  Report Builder (included with Reports Developer) automatically scales the display to fit in the display region.

Scaling and clipping each have special considerations.  Scaled displays can sometimes appear distorted.  In the case of clipped displays, their sizes are calculated beginning in the upper left corner of the display area (coordinates 0,0).  This means that if your display objects are displaced from the top and left borders of the Graphics Builder Layout editor, that "empty" space is included in the clipped version of the display.

To avoid distorted displays or unnecessary empty space, you can take the following precautions:

•	Move the contents of the display to the upper left corner of the Layout editor.

•	Use View [image] View Options [image] Layout to show the Layout Settings dialog where you can specify the size of the display.


About executing the display

Other Oracle products can invoke either the Graphics Builder Runtime or Batch executables.


About receiving text parameters

  Related Topics

A product that invokes a Graphics Builder display can pass initial values to parameters defined in the display.  These parameter values are always passed as datatype CHAR.

When you create a parameter in Graphics Builder, specify a datatype for it in the Parameters dialog.  Graphics Builder implicitly converts the incoming CHAR parameter value to the datatype specified for the parameter.

If you want to pass a date from the invoking product to Graphics Builder, you must specify the incoming date format in the Display property sheet.  For example, if you wish to send a value of 04-JUL-92 to Graphics Builder, make sure the date format DD-MON-YY is specified in the Parameter Date Format field of the Display property sheet.


About receiving data

  Related Topics

When you embed a Graphics Builder display in another Oracle product, Graphics Builder can use data from that product in place of its own.

When you create the chart in Graphics Builder, check Update Chart on Query Execution in the Data property page of the Chart property sheet.  The chart will be updated with the new data when the query is executed against the calling product.

Make sure that the query used by the calling product contains the same column names as the query used to create the chart so that Graphics Builder knows what to do with the data it's sent.  For example, suppose your display contains a chart that lists ENAME as a category and SAL as a value.

If Form Builder substitutes data that has columns named EMPLOYEE and SALARY, the chart will not be able to find the columns it is expecting.

If you assigned aliases in your Graphics Builder query, you may want to remove them for clarity.  Assign custom Axis labels via the Axis property sheet.


About building the layout

After invoking Graphics Builder, Report Builder (included with Reports Developer) always receives the contents of the layout following display execution.  After invoking Graphics Builder, Form Builder receives the contents of the layout specified in the OG.OPEN procedure.


About embedding displays in forms

  Related Topics

There are two methods for embedding displays in forms:

•	via the Form Builder Chart Wizard

•	via PL/SQL built-ins

To embed a new chart in a form, use the Form Builder Chart Wizard.  The Chart Wizard leads you step-by-step through the creation of a simple chart.

To embed an existing or complex display, build your chart item manually, and attach the OG.PLL library to the item.  The OG.PLL library is a collection of built-in PL/SQL routines designed specifically for passing data between forms and displays.  It contains procedures and functions for passing data, mouse events, and PL/SQL commands, as well as for initiating and disconnecting embedded displays at runtime.  You can incorporate the OG.PLL built-ins in forms triggers that send information and commands to the embedded display when they are activated by events taking place in the form.


Using the Chart Wizard to create charts in forms

  Related Topics

To use the Chart Wizard to create charts in forms:

1	In the Form Builder layout, choose Tools [image] Chart Wizard or select the Chart Wizard button in the toolbar.

2	Select and drag out a rectangle on the layout.  The size of the rectangle you create determines the size of the chart object that is created.

3	In the New Chart Object dialog box, select Use the Chart Wizard.

4	On the Chart Wizard Welcome page, select Next, then follow the wizard to create your chart.


Building chart objects manually in Form Builder

  Related Topics

To build a chart manually in a form:

1	In the Form Builder layout, select the Chart Item tool in the tool palette.

2	Select and drag out a rectangle on the layout.  The size of the rectangle you create determines the size of the chart object that is created.

3	In the New Chart Object dialog box, select Build a New Chart Manually.


Embedding existing displays in forms

  Related Topics

To embed an existing display in a form:

1	Build a chart object manually.

2	Attach the OG.PLL library to the form module.

3	Create one or more form triggers that use the OG.OPEN procedure from the OG.PLL library to load the existing display.

4	(Optional)  Use the OG.PLL library of built-ins to automate the display as desired.


About using PL/SQL to integrate a display in a form

  Related Topics

To integrate a display in a form, use the packaged procedure OG.OPEN, included in the OG.PLL library.

You can include the OG.OPEN procedure in a number of different triggers; for example, the When-New-Form-Instance trigger will load the display at the successful creation of the form, or the When-Button-Pressed trigger will load the display when the user selects the appropriate button.  If the display is located in a block that is not active when the trigger including OG.OPEN fires, the display will be loaded, but that block will not receive focus, and the display will be shown immediately.

Once Form Builder has invoked the appropriate Graphics Builder executable and loaded the display, it remains in memory until explicitly closed. Graphics Builder will not reload an open display.  If you change the chart object  and want to test your changes, you must first close the display by calling the OG.CLOSE built-in in a trigger.  (OG.CLOSE is included in the OG.PLL library.)

To exit Graphics Builder, use the OG_QUIT built-in procedure in another trigger, such as a Post-Block or Post-Form trigger.  OG_QUIT differs from OG.OPEN and OG.CLOSE in that it is not part of the OG.PLL library included with Form Builder, but instead is a Graphics Builder built-in subprogram, and as such must be passed to Graphics Builder to interpret.  OG.PLL includes OG.INTERPRET for that purpose.  Use OG.INTERPRET to pass any valid PL/SQL string to Graphics Builder to execute.


About the OG.PLL library

The level of integration between a form and a chart depends on the level of communication you establish between Graphics Builder and Form Builder.  To get Form Builder to "talk" to Graphics Builder, use the OG.PLL library.

Form Builder includes this library, a package that includes several procedures and functions you can use to communicate with a display.

Generally, to communicate between Form Builder and Graphics Builder, you will include one or more of the OG.PLL procedures and functions in one or more form triggers, so that actions taking place in the form send information and commands to the embedded display.


About activating the display

You can make your display sensitive to user action.  The simplest method is to use the OG.MOUSEDOWN and OG.MOUSEUP packaged subprograms provided by the OG.PLL library to notify a display of a mouse event.

When the user takes the action for which you've created a trigger, the trigger passes the information directly to Graphics Builder, which responds just as it would if the mouse event had occurred in Graphics Builder runtime.

This trigger need not be attached to a mouse event.  If you want users to reach a drill-down display by pressing a button, create the button in the Form Builder layout and attach a When-Button-Pressed trigger that includes the appropriate procedure.

Both OG.MOUSEUP and OG.MOUSEDOWN give you complete control over the information sent from the form to the display.  For example, if you want the user to press a button in the form instead of using a mouse, you can still pass all necessary information to the display -- including coordinates, single- or double-click, button one or button two -- and Graphics Builder will treat it like an actual mouse event.

The default for all arguments denoting mouse actions is the actual information sent by the mouse.


About sending PL/SQL to the display

When you include a Graphics Builder display in a Form Builder application, you can use the OG.INTERPRET procedure to instruct the display to execute a specific piece of PL/SQL code.  This PL/SQL can range from a Graphics Builder built-in to a user-created function or procedure to a simple, one-line command, but it must be sent as a character string.  Enclose all such strings in quotes, and include trailing semicolons as required.

Using OG.INTERPRET, you can execute Graphics Builder program units from the form.  Beyond simply changing the data upon which a chart is based, this allows you to use PL/SQL program units in the display to perform dynamic operations such as change a chart bar's color or move an object.


About exchanging data between the form and the display

  Related Topics

In addition to sending mouse actions or PL/SQL to an embedded display, you can pass information either from the form to the display, or from the display to the form.  Use OG.GETCHARPARAM, a function included in the OG.PLL library,  which also provides OG.GETNUMPARAM for parameters whose values are numbers.

There are two types of parameters you can use to pass data:

•	Text parameters

•	Data parameters

The display can then use the information during updates.


About text parameters

Text parameters contain values that come from variables or constants.  They refer to pre-defined system parameters, user-defined parameters, bind variables, or lexical variables.  Each text parameter has a key, or name, and a value.

Pre-defined system parameters have fixed names, or keys, and are usually specified in the command line that calls the tool.  For example, PRINT is a parameter key, and ‘yes’ is one possible value; USERID is a key, and `scott/tiger@t:london:payroll' is a valid value.

User-defined parameters are generally defined during the design phase of an application, and give users more control over the actions of the modules to which they apply.  For more information about creating parameters in a form, see your Form Builder documentation.

User-defined parameters passed between products are first converted to the CHAR datatype.  However, the invoked product may either implicitly convert the values to the desired datatype, or allow you to treat them as values of another type (e.g., by using PL/SQL conversion functions such as TO_DATE, TO_NUMBER, etc.).

For more information about converting datatypes with a conversion function, see the PL/SQL User's Guide and Reference.


About data parameters

Data parameters are record groups you can pass from Form Builder to Graphics Builder in a tabular format.  You may want to do this for the following reasons:

•	If the display dynamically builds and executes a query based on a user action in the form, you can provide Graphics Builder with the result of that user action.

•	If the display uses data that Form Builder has already retrieved, you can prevent that product from having to retrieve the data again.

•	If the form has created an uncommitted record group you want to display.

As with text parameters, every data parameter has a key and a value.  The value of a data parameter specifies the name of the Form Builder query passed to the display.  The key of a data parameter specifies the query name with which it is equated in the invoked product.

When you are passing data from Form Builder to Graphics Builder, make sure you first execute the query in Form Builder.


About creating and populating parameter lists

  Related Topics

Form Builder passes information to a display using a parameter list.  A parameter list is a series of parameter key and value pairs.  (Even a single parameter must be assigned to a parameter list.)  Each piece of information you want to pass must be defined as a parameter, then added to a parameter list.  The type of parameter you create depends on the information you want to pass.  Parameter lists are always passed as string literals.

To enable you to create and manipulate parameter lists and the parameters they hold, Form Builder provides several built-in functions and procedures with self-explanatory names:

•	CREATE_PARAMETER_LIST (function)

•	GET_PARAMETER_LIST (function)

•	DESTROY_PARAMETER_LIST (function)

•	ADD_PARAMETER (procedure)

•	SET_PARAMETER_ATTR (procedure)

•	GET_PARAMETER_ATTR (procedure)

•	DELETE_PARAMETER (procedure)

For Graphics Builder, these functions and procedures are part of the TOOL_INT package.  When using them, preface their names with TOOL_INT.; e.g., TOOL_INT.GET_PARAMETER_LIST.


About invoking Graphics Builder from a form

After you have created and populated the parameter list, invoke Graphics Builder and send the parameter list to it using any one of the following procedures included with OG.PLL:

•	OG.OPEN

•	OG.INTERPRET

•	OG.MOUSEDOWN

•	OG.MOUSEUP

•	OG.REFRESH


Using Graphics Builder to create displays for use in forms

  Related Topics

To create a Graphics Builder display for use in forms:

  Create a Graphics Builder display as you normally would.

To create a drill-down down Graphics Builder display for use in forms:

  Create a drill-down display as you normally would.


Drawing a chart area

To draw a chart area:

  Select the Chart Item tool from the Form Builder tool palette and draw out a region in the form layout.  Either rename the chart area in the Properties window or keep the default name.


Creating triggers to open and close the display

  Examples

To create triggers to open and close the display:

1	Attach the OG.PLL library to your form.  This library contains the OG package, made up of the subpackages you'll use to communicate between Form Builder and Graphics Builder.

For more information about attaching libraries in Form Builder, see your Form Builder documentation.

2	Create a trigger that uses the OG.OPEN procedure to load the Graphics Builder display.

3	If necessary, create a trigger that uses the OG.CLOSE procedure to close the display.  Alternatively, use OG.INTERPRET to sent an exit command to Graphics Builder.

For more information about creating triggers in Form Builder, see your Form Builder documentation.


Examples: Opening and closing displays

Example: OG.OPEN

The following When-New-Form-Instance trigger opens the display inv_disp.ogd in the chart area `CHART_AREA1', scales the display to fit the space allotted to it in the Form Builder layout, and automatically refreshes the display (REFRESH=TRUE is the default).  No parameter list is passed.

OG.OPEN('inv_disp.ogd', 'CHART_AREA1', clip=FALSE);

Example: OG.CLOSE

The following Post-Form trigger closes the display inv_disp.ogd in the chart area 'CHART_AREA1'.  It takes only two parameters:  display_name and chart_item_name.

OG.CLOSE('inv_disp.ogd', 'CHART_AREA1');

Once again, you are not required to use the Post-Form trigger.  Select the trigger best-suited to close the display when and where you want it to close.

Example: OG.INTERPRET

The following Post-Form trigger uses the Graphics Builder built-in OG_QUIT to exit Graphics Builder:

OG.INTERPRET('inv_disp.ogd', 'CHART_AREA1', 'og_quit;');

Notice the semicolon immediately following "og_quit".  When passing PL/SQL via OG.INTERPRET, you must include the trailing semicolon.  Once again, you are not required to use the Post-Form trigger.  Select the trigger best-suited to exit Graphics Builder when you want to exit.


Creating trigger(s) to pass mouse events

  Examples

To create triggers to pass mouse events:

  Create a trigger in Form Builder that includes either the OG.MOUSEDOWN or OG.MOUSEUP packaged subprogram from the OG.PLL library.


Example: Creating a trigger to pass a mouse event

Example:  OG.MOUSEDOWN

The following When-Mouse-Click trigger activates the display inv_disp.ogd:

OG.MOUSEDOWN('inv_disp.ogd', 'CHART_AREA1');

The procedure in the example above used only two arguments:  display_name and chart_area_name.  Both procedures take several other arguments, including the supposed x and y coordinates of the mouse selection, which mouse button was selected, how many times it was selected, a parameter list, etc.


Creating trigger(s) to pass PL/SQL

  Examples

To create triggers to pass PL/SQL:

  When you use the OG.INTERPRET packaged subprogram to invoke a Graphics Builder program unit from Form Builder, you must pass the program unit and any necessary arguments as a string value.  In other words, the program unit you are executing must be enclosed in single quotes.


Examples:  Creating triggers to pass PL/SQL

Example:  Using OG.INTERPRET to invoke a procedure

The following, included in a When-Button-Pressed trigger, invokes the 'set_timers' procedure:

OG.INTERPRET('inv_disp.ogd', 'CHART_AREA1',
'set_timers;');

Note the inclusion of the trailing semicolon.

Example 2:  Using OG.INTERPRET to build a string

If the program unit you are invoking in Graphics Builder requires that arguments be passed by Form Builder, use the concatenation operator to create the necessary string value.  The following simple example instructs Graphics Builder to execute the program unit "set_param" with an argument supplied from one of the text fields in the form:

OG.INTERPRET ('inv_disp.ogd', 'CHART_AREA1', 'set_param('|| TO_CHAR(:BLOCK1.category_cbox) || ');');

Example 3:  Using OG.INTERPRET to build a string – advanced case

A slightly more intricate example of building a string using the concatenation operator:

OG.INTERPRET('inv_disp.ogd', 'CHART_AREA1',
'set_timer(' ||
 TO_NUM(:BLOCK2.values_plist) ||
 ','  ||
 TO_NUM(:BLOCK3.more_cbox) ||
 ');');

Breaking the above subprogram call into separate parts (each divided by a concatenation operator), you can see the following:

'set_timer('	Contains the procedure name and opening parentheses, enclosed 	in single quotes.

TO_NUM(:BLOCK2.	Contains the parameter from Form Builder, converted to the NUMBER

values_plist)	datatype.  This is an argument required by the set_timer 	procedure.

','	Contains the comma that separates the two supplied arguments.

TO_NUM(:BLOCK3.	Contains the parameter from Form Builder, converted to the NUMBER

more_cbox)	datatype.  This is the second argument to the set_timer 	procedure.

');'	Contains the procedure's closing parentheses and semicolon, 	enclosed in single quotes.

Graphics Builder sees the resulting string:

set_timer(x,y);

where the x and y arguments are the numbers sent from the form and converted to the NUMBER datatype.


Creating trigger(s) to pass data

  Examples

To create triggers to pass data:

  When passing data between a form and a display, remember that the form can both extract parameter values from the display and pass text and data parameters to the display.  However, the form can only extract a single parameter value per inquiry, while it can only pass parameter lists.


Examples:  Creating triggers to pass data

Example 1:  Getting a parameter value

The following function in a When-Button-Pressed trigger retrieves the value of the Graphics Builder display parameter param1 and assigns it to the text field 'TEXT_ITEM1' in the form:

:BLOCK1.TEXT_ITEM1 := OG.GETCHARPARAM

('inv_disp.ogd', 'CHART_AREA1', 'param1');

Example 2:  Passing a parameter

Below is the text of a block-level Post-Query trigger that might be used to pass a department number to Graphics Builder for use in constructing the sal_chart display.

PROCEDURE pass_param IS
pl   ParamList  /*Parameter list datatype*/
BEGIN

/*Create the parameter list, named "my param list".*/
pl := Create_Parameter_List('my_param_list');

/*Add a text parameter to the list to supply a value for

**the 'dept_num' parameter that Graphics Builder is expecting*/
Add_Parameter(pl, 'dept_num', TEXT_PARAMETER,
TO_CHAR(:dept.deptno));

/*Call Graphics Builder to populate the chart item*/
OG.REFRESH('sal_chart', 'dept.chart_item', pl);

/*Destroy the parameter list */
Destroy_Parameter_List(pl);

END

Example 3:  Passing record groups

The following is the text of a block-level Post-Query trigger used to pass data to Graphics Builder.  In this example, Form Builder issues a query and stores the resulting data in a record group.  A data parameter is used to pass the record group to Graphics Builder, which uses the data to construct the sal_chart display.

Procedure pass_data is
pl_id  PARAMLIST;
rg_id  RECORDGROUP := Find_Group('chart_data');
qry    VARCHAR(2000);
stat   NUMBER;

BEGIN
/*Prepare a query in a string based on the last
**WHERE clause issued.*/
qry := 'SELECT ename, sal FROM emp '||
   substr(:system.last_query,instr(:system.last_query,
'WHERE'))||' order by empno';

/*Check to see if the record group already exists;
**if not, create it.*/
IF Id_Null(rg_id) THEN
rg_id := CREATE_GROUP_FROM_QUERY('chart_data', qry);
END IF;

/*As the record group may have already existed with old
**data, clear it out and repopulate it based on the new
**query*/
DELETE_GROUP_ROW(rg_id, all_rows);
stat := POPULATE_GROUP_WITH_QUERY(rg_id, qry);

/*Now create a parameter list*/
pl_id := CREATE_PARAMETER_LIST('pl_chart_data');

/*Add a data parameter with the same name asthe query in **the display*/
Add_Parameter(pl_id,'query0',DATA_PARAMETER,'chart_data');

/*Refresh an already-opened display with the new data*/
OG.REFRESH('sal_chart','dept.chart_item',pl_id);

*/Destroy the parameter list*/
DESTROY_PARAMETER_LIST

END


Creating and populating parameter lists

  Related Topics

To create a parameter list:

1	Decide what information you will pass.

2	Create the parameter list using the built-in appropriate to your tool.

3	Add items to the list.  This procedure requires the following arguments:

   The name of your parameter list

  The name of the parameter you want to add

  The type of the parameter you want to add (text or data)

  The value of the parameter you want to add

If you are passing command line or executable options, make sure you specify the command line option keyword as the parameter name.  See the documentation for the product you are invoking for all valid executable options.


Running the form

To run the form:

  Make sure any triggers you've created compile correctly, and select File [image] Run.


About embedding displays in reports

  Related Topics

There are two methods for embedding displays in reports.  You can build your display:

•	via the Report Builder Chart Wizard (included with Reports Developer)

•	manually

To create a new chart in a report, use the Report Builder Chart Wizard (included with Reports Developer).  The Chart Wizard leads you step-by-step through the creation of a simple chart.

To embed an existing or complex display in a report, create a chart object in the report layout, and use the chart object’s Property Palette to set display properties.

You can set a display to receive data directly from the report in which it is embedded rather than from a database.  This feature allows you to embed displays that reflect filtered or summary data from reports.


Type Caption for New Topic Right Here
A complex display is a display that is interactive, contains multiple queries, or that includes objects as well as charts.


Using the Chart Wizard to create a new chart in a report

  Related Topics

To use the Chart Wizard to create a chart from within a report:

1	In the Report Builder Live Previewer or Layout Model view (included with Reports Developer), choose Tools [image] Chart Wizard or select the Chart Wizard button on the toolbar.

2	Follow the wizard to create your chart.


Embedding an existing display in a report

  Related Topics

To embed an existing display in a report:

1	In the Report Builder Layout Model view (included with Reports Developer), select the Chart tool in the tool palette.

2	Select and drag a rectangle to create a chart object.  The size of the rectangle you create determines the size of the chart object that is created.

3	Double-click the new chart object to display its Property Palette.

4	Under the Chart node, set the Chart Filename property to the name of the file containing the display.

5	If you want to pass parameters from the report to the display, map report columns or parameters to the chart object's parameters.

6	If the display uses multiple queries, or if you want to pass data values directly from the report to the display, map the chart object's column properties to the report.


Passing parameters from a report to an embedded display

  Related Topics

To pass parameters from a report to a display:

1	Double-click the embedded chart object to display its Property Palette.

2	On the Property Palette, under the Chart node, select the Parameters and Columns field to display the Parameters and Columns property  pages.

3	Select the Parameters tab.

4	In the Report Column list, select the report columns or parameters that match  parameters in the display.  Selecting a report column or parameter means that there is a corresponding parameter in the display and that the parameter will take its value from the correct instance of the selected report column.

5	In the Chart Parameter field, type the name of the chart parameter the report column or parameter maps to.

6	Select OK.


Passing data values from a report to an embedded display

  Related Topics

To pass data values from a report to a display:

1	Double-click the embedded chart object to display its Property Palette.

2	On the Property Palette, under the Chart node, select the Parameters and Columns field to display parameter and column properties.

3	Select the Column tab.

4	In the Chart Query field, type the name of the display query.  If you want the display to reflect filtered report data or summaries, be sure to select a query that has a data source (SQL or file) that returns data columns that correspond to the columns or parameters you want to pass from the report.

5	In the Report Group field, choose from the drop-down list the report group that contains the data and parameters used by the query you specified in the Chart Query field.

6	In the Report Column list, select to specify the report columns that map to columns in the display.  The report columns you select will provide values for the corresponding display columns.  Type the names of the corresponding display columns in the Chart Column field.

7	Select OK.


Creating a hyperlink destination for a display embedded in a report

To add a hyperlink destination to a display embedded in a report:

1	In the Live Previewer or Layout Model view in Report Builder (included with Reports Developer), double-click the chart object to display its Property Palette.

2	Under the Chart Link node, set the Chart Hyperlink destination to an identifier for the chart object.


Sizing displays for OLE container applications

To size a display for an OLE container application:

1	Move the objects in your display to the upper left corner of the Layout Editor, allowing adequate blank space so that the display is legible.

2	Choose View [image] View Options [image] Layout to display the Layout Settings dialog.

3	Enter a horizontal and vertical size for the layout.

4	Select OK to accept the layout size and close the dialog.

The layout size will be restricted to the dimensions you have defined.  Make sure the region you designate in your OLE container application is large enough to accommodate the size of the display.

When you embed a Graphics Builder display in an OLE container application, you are really including an image of the display.  Because OLE server applications do not use the same graphic definition system as Graphics Builder does, they are unable to scale the image of a Graphics Builder display to fit into a defined region.


Embedding a display in an OLE container

To embed a display in an OLE container application:

1	Create the display in Graphics Builder.

2	Draw a chart area in your OLE container application.

3	Set the appropriate properties for the included display.

See the documentation for the OLE container application for instructions on how to include an OLE server object.


About exporting displays as images

You can export Graphics Builder objects (single or group) to a variety of image formats, including GIF, JPEG, BMP, TIFF and PICT. There are three methods of exporting objects as images:

•	via the Graphics Builder Export Image menu item, when you are exporting static images of displays for use in web pages, Word documents, presentations, etc.

•	via the OG_EXPORT_IMAGE PL/SQL built-in, when you are exporting interactive displays for use in web applications

•	via the Graphics Builder command line, when you are batch-generating displays from shell scripts


Exporting an image via the Export Image menu item

To export an image via the Export Image menu item:

1	Select the object or group object you want to export, either by selecting it within the Layout Editor, or by selecting it from the Object Navigator.

2	Choose Edit [image] Export [image] Image to display the Export Image dialog.

3	Select the Database or File radio button to indicate whether you want to export your image to a file or a database. If you are exporting to a file, type the path name for the file you are exporting to, or select Browse to select a file.

4	From the Format drop-down list, select the image format for the export file.

5	From the Data Type drop-down list, select the data type for the image.

6	In the Compression drop-down list, Graphics Builder specifies the acceptable compression types for the image format type you selected in the Format drop-down window.  Accept the default compression type that Graphics Builder specifies, or select another type from the drop-down window.  Although the default compression type for some image formats is “none,” you must specify a format type from the pull-down window if you are exporting a non-image object or a group of objects. For more information about specifying compression for each format type, see the PL/SQL Built-in Reference.

7	If you are exporting to JPEG format, select a quality specification from the Quality drop-down window.

8	Select OK.


Exporting an image via PL/SQL

  Example

To export an image via PL/SQL:

  Use the OG_EXPORT_IMAGE  built-in.


Example:  og_export_image

 /* Suppose you want to export a complex display as a GIF
**for publication on a World Wide Web page. The following
**procedure exports the currently open display as the image,
**“test.gif.”
*/

PROCEDURE
BEGIN
   og_export_image('c:\test.gif', OG_FILESYSTEM,
OG_GIF_IFORMAT,og_root_object,
OG_LZWHDIFF_ICOMPRESSION);
END


Exporting an image via the Graphics Builder command line

  Example

To export an image via the Graphics Builder command line:

  Run the display to export as an image using G30Run, and specify the image name as an argument to the exportimage parameter.


Example:  Exporting an image via the Graphics Builder command line

 /*This example provides a sample export-to-image command
*line argument.  It runs the display test.ogd and exports it
*to the image “test.gif.”
*/

G30run openfile=C:\test.ogd userid=scott/tiger exportimage=C:\test.gif
Quit=yes


About the TOOL_INT package

  Related Topics

Preparing to invoke other Oracle products from a Graphics Builder display is quite similar to preparing to invoke a display from another product.  However, instead of using, for example, the packaged procedures Form Builder provides in the OG.PLL library, you use the built-in package TOOL_INT.

With this package you can pass information to another product and invoke the other product from your display.


About synchronous communication

When Graphics Builder invokes another product synchronously, the execution of the Graphics Builder display is suspended until the invoked product has finished executing.

To pass data to another product, you must invoke that product synchronously.

You may want to invoke another product in this way for the following reasons:

•	To require the user to enter values in Form Builder before continuing.

•	To pass query data to Report Builder (included with Reports Developer) and run a report based on that query data.


About asynchronous communication

When Graphics Builder invokes another product asynchronously, the execution of the Graphics Builder display continues normally, following the PL/SQL procedure call that invokes the other product.  Thus, Graphics Builder and the called product run concurrently.

You cannot pass data to another product if you invoke it asynchronously.

You may want to invoke another product in this way for the following reasons:

•	To generate a Report Builder report to another device, such as a printer.

•	To allow the user to view an Oracle Book document during the display execution.

If you want to pass a data parameter from Graphics Builder to another product, you must invoke that product in the synchronous communication mode.


About execution modes

There are two execution modes in which Graphics Builder can invoke another Oracle product:

•	runtime

•	batch

The behavior in each of these execution modes differs for each product invoked by Graphics Builder.  In addition, some Oracle products may not support a particular execution mode.  For more information, see the documentation for the product you wish to invoke.


Passing information to other products

  Examples

To pass information to other products:

  Use text and data parameters, as covered in Exchanging Data Between the Form and the Display.


Example:  Passing information to other products from Graphics Builder

Suppose you want a Graphics Builder display to invoke Report Builder (included with Reports Developer) with the following parameters:

Name	Value

USERID	scott/tiger
DESTYPE	printer
COPIES	2
my_param	67
In addition, you want Report Builder to base its report on data provided by Graphics Builder.  Assume the query defined in your report is named 'Q_1' and the query defined in your Graphics Builder display is named 'query0'.

The following procedure creates a parameter list named `my_plist' and adds the above parameters to it:

PROCEDURE create_plist IS
   the_list   tool_int.paramlist;

BEGIN
   the_list:=TOOL_INT.CREATE_PARAMETER_LIST('my_plist');
   TOOL_INT.ADD_PARAMETER(the_list, 'userid',
         TOOL_INT.TEXT_PARAMETER, 'scott/tiger');
   TOOL_INT.ADD_PARAMETER(the_list, 'destype',
         TOOL_INT.TEXT_PARAMETER, 'printer');
   TOOL_INT.ADD_PARAMETER(the_list, 'copies',
         TOOL_INT.TEXT_PARAMETER, '2');
   TOOL_INT.ADD_PARAMETER(the_list, 'my_param',
         TOOL_INT.TEXT_PARAMETER, '67');
   TOOL_INT.ADD_PARAMETER(the_list, 'Q_1',
         TOOL_INT.DATA_PARAMETER, 'query0');
END;


 Using the same login session

  Examples

To use the same login session:

  Pass the login information you supplied with Graphics Builder to the other product in the form of a parameter.  Then, when you do invoke another product from Graphics Builder, you can effectively share your login session with the invoked product.  This can also be handy for suppressing the Connect dialog box.

Form Builder, Report Builder (included with Reports Developer), and Oracle Book all use the USERID executable option to establish a database connection.  Graphics Builder stores its login information in the form of properties for the application.  You can use the property built-in function OG_GET_ATTR to retrieve this information, and then include it in a parameter list as a text parameter.


Example:  Using the same login session

The sample procedure below shows how to pass a remote database connect string from Graphics Builder to Report Builder (included with Reports Developer):

PROCEDURE run_form IS
  rept_list  tool_int.paramlist;
  uname      VARCHAR2;
  pword      VARCHAR2;
  cnxn       VARCHAR2;
BEGIN
/*create the parameter list*/
  rept_list:=TOOL_INT.CREATE_PARAMETER_LIST('list1');

/*find OG login information*/
  uname:=OG_GET_AP_USERNAME;
  pword:=OG_GET_AP_PASSWORD;
  cnxn:=OG_GET_AP_CONNECTION;

/*add OG login info to parameter list*/
  TOOL_INT.ADD_PARAMETER (form_list, 'userid',
TOOL_INT.TEXT_PARAMETER, uname || '/' ||
pword || '@' || cnxn);
/*pass Report Builder the parameter list with login info*/
  TOOL_INT.RUN_PRODUCT(TOOL_INT.REPORTS, 'inventory.rpt',
TOOL_INT.ASYNCHRONOUS, TOOL_INT.RUNTIME, rept_list)
END;


Invoking another product from Graphics Builder

To invoke a product:

  Use the TOOL_INT.RUN_PRODUCT procedure.  This procedure requires the following arguments:

•	The name of the product you are invoking.

•	The form/report/document of the product.

•	The communication mode in which to invoke the product.

•	The product executable mode to use.

•	The name of the parameter list to pass to the product.


Invoking Form Builder from Graphics Builder

  Examples

To invoke Form Builder from Graphics Builder:

  You can invoke Form Builder from Graphics Builder to display a form containing query data from the display.  Remember, when passing data from one product to another, you must invoke the product in synchronous mode.


Example:  Invoking Form Builder from Graphics Builder

The following procedure invokes a Form Builder Runtime application and supplies it with query data from the display.

PROCEDURE open_form (the_form IN VARCHAR2) IS
  form_list  tool_int.paramlist;
  uname      VARCHAR2;
  pword      VARCHAR2;
  cnxn       VARCHAR2;
BEGIN
/*create the parameter list*/
  form_list:=TOOL_INT.CREATE_PARAMETER_LIST('list2');
  uname:=OG_GET_AP_USERNAME;
  pword:=OG_GET_AP_PASSWORD;
  cnxn:=OG_GET_AP_CONNECTION;

/*Add a parameter to the parameter list*/
  TOOL_INT.ADD_PARAMETER (form_list, 'userid',
TOOL_INT.TEXT_PARAMETER, uname || '/' ||
pword || '@' || cnxn);

/*pass Form Builder the parameter list*/
  TOOL_INT.RUN_PRODUCT(TOOL_INT.FORMS, 'the_form',
TOOL_INT.ASYNCHRONOUS, TOOL_INT.RUNTIME, form_list);
END;


Invoking Report Builder from Graphics Builder

  Examples

To invoke Report Builder (included with Reports Developer) from Graphics Builder:

  Define a trigger that invokes Report Builder in batch mode and prints a predefined report.  Alternatively, you could invoke Report Builder runtime to display a report.


Example:  Invoking Report Builder from Graphics Builder

The following example shows a procedure that creates a parameter list to pass to Report Builder (included with Reports Developer), and then calls Report Builder to run the inventory.rep report.  In addition, the procedure includes the USERID executable argument text parameter to suppress the Report Builder Connect dialog box.

PROCEDURE print_inv_rep IS
  rep_list  tool_int.paramlist;
BEGIN
/*create a parameter list*/
  rep_list:=TOOL_INT.CREATE_PARAMETER_LIST('list2');

/*add the USERID executable option to the list*/
  TOOL_INT.ADD_PARAMETER (rep_list, 'userid',
TOOL_INT.TEXT_PARAMETER, 'scott/tiger');

/*add the query data parameter to the list*/
  TOOL_INT.ADD_PARAMETER (rep_list, 'Q_inv',
TOOL_INT.DATA_PARAMETER, 'query_inv');

/*call Report Builder batch mode to print the report*/
  TOOL_INT.RUN_PRODUCT(TOOL_INT.REPORTS, 'inventory.rep',
TOOL_INT.SYNCHRONOUS, TOOL_INT.BATCH,
TOOL_INT.FILESYSTEM, rep_list);
END;

The execution of the Graphics Builder display is suspended until Report Builder has finished printing the report.

For more information about Report Builder executable options, see your Report Builder documentation.


Invoking Oracle Book from Graphics Builder

  Examples

Invoking Oracle Book from Graphics Builder:

  You can associate a procedure to invoke an instance of Oracle Book runtime with a button on your display.  If your Oracle Book document has hypertext targets in it, you can specify that the document be opened at a specific target location using the TARGET executable argument.


Example:  Invoking Oracle Book from Graphics Builder

The following button procedure opens an Oracle Book document named help.obd at the target name "start":

PROCEDURE OGBUTTONPROC0(buttonobj IN og_object, hitobj
 IN og_object, win IN og_window, eventinfo IN og_event)IS
  book_list  tool_int.paramlist;
BEGIN
/*create a parameter list*/
  book_list:=TOOL_INT.CREATE_PARAMETER_LIST('list1');

/*add the target executable option to the list*/
  TOOL_INT.ADD_PARAMETER (book_list, 'target',
TOOL_INT.TEXT_PARAMETER, 'start');

/*open Oracle Book at the target name specified above*/
  TOOL_INT.RUN_PRODUCT(TOOL_INT.BOOK, 'help.obd',
TOOL_INT.ASYNCHRONOUS, TOOL_INT.RUNTIME,
TOOL_INT.FILESYSTEM, book_list);
END;

See your Oracle Book documentation for other executable arguments you can pass to Oracle Book Runtime when you invoke it.


Saving displays in the file system

To save a display in the file system:

1	Choose File [image] Save As [image] File System to display your system file dialog.

2	Specify a unique filename for the display.

You can keep the Graphics Builder default filename or replace it with a unique name.

3	Accept the dialog box to save the display.

The contents of the Layout Editor and other windows within the display are saved as you left them.


Saving displays in the database

To save a display in the database:

1	Choose File [image] Save As [image] Database to display the Save To Database dialog box.

2	Type a unique name for the display in the Name field.

3	Select Save to save the display.

The contents of the Layout Editor and other windows within the display are saved as you left them.

You must be connected to the database, and have the appropriate access to save displays in the database.  In addition, your database must have the Graphics Builder tables set up.  Check with your database administrator for more information.


Discarding changes to displays

To discard changes to a display:

  Choose File [image] Revert to discard the most recent changes.

Your display is restored to the previously saved version.


Renaming displays in the file system

To rename a display in the file system:

  Use your operating system to rename a display that is stored as a file.  You must have the appropriate file permissions to be able to rename the file.

See your operating system documentation for the correct method of renaming files.


Renaming displays in the database

To rename a display stored in the database:

1	Choose File [image] Administration [image] Rename [image] Display to display the Rename dialog box.

2	Specify the old name and a new name for the display.

3	Select Rename to apply the new name.

You can rename a display stored in the database if you created it or were granted access to it.


About renaming, deleting, and granting access to exported chart templates

To rename, delete, and grant access to exported chart templates:

  The procedures for renaming, deleting, and granting access to exported chart templates are the same as those for displays.


Granting and revoking access to displays in the file system

To grant and revoke access to a display in the file system:

  Some operating systems permit users to grant read, write, and execute permissions on individual files.  For more information about how to set file permissions on your operating system, see your operating system documentation or check with your system administrator.


Granting and revoking access to displays in the database

To grant and revoke access to a display stored in the database:

1	Choose File [image] Administration [image] Access [image] Display to display the Module Access in Database dialog box.

This dialog contains a list of all displays stored in the database that you have access to.

2	Select a display from the list.

3	Select OK to display the Module Access dialog.

This dialog contains a list of users who have access to the display.

4	Type the database userid of the person to whom you want to grant access in the User field.

5	Select Add to add the name to the Access list.

6	Select the username of the person from whom you wish to revoke access in the Access list.

7	Select Remove to remove the username from the Access list.

8	Select OK to accept your changes and close the Module Access dialog.

Access privileges are updated for your display.

You can grant another user access (read/write/execute privileges) to a display you've created and stored in the database.  However, the user must also have access to the Graphics Builder database tables.  For more information, consult your database administrator.


Managing external sounds

To manage external sounds:

  The procedures for granting and revoking access, renaming, and deleting sounds in the file system or a database are the same as those for displays.

Sounds that you have created in the Builder or imported into the display are considered to be internal to the display.  Sounds that are stored in the file system or the database are considered external to the display.  The location of the sound determines what methods you use to grant and revoke access, rename, or delete the sound.


Managing artwork

To manage artwork:

  The procedures for granting and revoking access, renaming, and deleting artwork are the same as those for displays.


Exporting artwork

To export artwork:

1	If you are exporting an image, select the image.  If you are exporting the entire display as a drawing, Graphics Builder will automatically include all artwork on the visible layers of the display.

2	Choose Edit [image] Export, and then choose the type of artwork you want to export.

For example, to export objects you've drawn in Graphics Builder, choose Drawing.  The Export dialog appears.

3	Specify the desired options such as the file format to export the artwork in, filename and location, etc.

4	Select OK to confirm the information and close the Export dialog.

The artwork is exported to the location you specified.

You can export an image from a display, or export all visible layers in the display as a drawing.  You can export artwork to the file system, or to a database.  If you have grouped objects in the display, those objects will not retain their grouped properties once exported to a CGM file.


Exporting artwork using PL/SQL

  Related Topics

To export artwork using PL/SQL:

  Use the OG_EXPORT_DRAWING built-in procedure.

The following example exports the contents of a layer to a CGM file:

PROCEDURE export_the_drawing IS
   the_layer   OG_OBJECT;
BEGIN
   the_layer:=OG_GET_LAYER('layer0');
   OG_EXPORT_DRAWING('my_draw', OG_FILESYSTEM,
     OG_CGM16_DFORMAT, the_layer);
END;


Managing color palettes

To manage color palettes:

  The procedures for renaming, granting access to, and deleting color palettes are the same as those for displays.  Likewise, the procedures for importing and exporting color palettes are the same as those for artwork.


Deleting displays in the Object Navigator

To delete a display in the Object Navigator:

1	Select the display object in the Object Navigator.

2	Select Delete, or choose Navigator [image] Delete.

An alert appears, prompting you to confirm the deletion.

3	Select Yes to confirm.

The display is deleted.

You can delete an open display in the Object Navigator regardless of where it is stored.  You must have the appropriate access to the display to delete it.  If you do not have file write permission or database access, you cannot delete the display.


Deleting displays from the file system

To delete displays from the file system:

  You can use your operating system to delete a display that is stored as a file.  You must have the appropriate file permissions to delete the display.

See your operating system documentation for the correct method of deleting files.


Deleting displays from the database

To delete a display stored in the database:

1	Choose File [image] Administration [image] Delete [image] Display to display the Delete From Database dialog.

2	Specify the name of the display.

3	Select Delete to delete the display from the database.

You can delete a display stored in the database if you created or were granted access to it.


About chart properties

Chart properties define options for the chart as a whole, including its associated chart template and query.  Chart properties are accessible through the Chart property sheet and are organized as follows:

Chart

Data

Categories

Values

PL/SQL

In general, you define chart properties by selecting the chart, opening its property sheet, and choosing the options you want to define for it.  You can also define many of these options programmatically, using PL/SQL.


Includes the chart's name, title, chart type, and template.


Includes query-related properties such as a query filter function and the range of data to plot.


Includes the chart categories and any sub-categories to plot in the chart.  Category (independent) data is plotted at fixed intervals.  Category data is not considered to be mathematically related and is usually plotted along what is called the Discrete axis.


Includes the chart values and associated field templates.  Value (dependent) data generally starts at one value and continues until another value.  Value data is considered to be mathematically related and is usually plotted along what is called the Continuous axis.


Includes any mouse events and associated procedures for the chart.


Accessing and modifying chart properties via the Layout Editor

To access chart properties via the Layout Editor:

  Double-click the chart in the Layout Editor, or

  Select the chart in the Layout Editor and then choose the Properties command from the pop-up menu.

You can specify a different query, and chart template to associate with a chart, as well as other options for the chart as a whole.  For example, you may want to name a chart in order to reference it programmatically.  You may also want to associate a chart with a button procedure.

To modify chart properties via the Layout Editor:

1	Double-click the chart to show the Chart property sheet.

2	Specify the desired options.

3	Select OK to apply the changes and close the Chart property sheet, or select Apply to apply your changes to the chart without closing the Chart property sheet.


Accessing and modifying chart properties via the Object Navigator

To access chart properties via the Object Navigator:

  Double-click the chart object in the Object Navigator, or

  Select the chart object in the Object Navigator and choose the Properties command from the pop-up menu, or

  Select the chart object in the Object Navigator and choose Tools [image] Properties.

You can specify a different query, and chart template to associate with a chart, as well as other options for the chart as a whole.  For example, you may want to name a chart in order to reference it programmatically.  You may also want to associate a chart with a button procedure.

To modify chart properties via the Object Navigator:

1	Double-click the chart to show the Chart property sheet.

2	Specify the desired options.

3	Select OK to apply the changes and close the Chart property sheet, or select Apply to apply your changes to the chart without closing the Chart property sheet.


Setting baseline values

To set a baseline value:

1	Select the chart or a single chart object such as the chart title.

2	Choose the Frame command from the pop-up menu, or choose Chart [image] Frame to show the Frame property sheet.

3	Select the Axis Frame tab to show the Axis Frame property page.

4	Specify the desired baseline value.

5	Select OK to apply the changes to the chart.


Specifying bar and column properties

To specify bar and column properties:

1	Select the chart or a single chart object.

2	Choose the Frame command from the pop-up menu, or choose Chart [image] Frame to show the Frame property sheet.

3	If necessary, select the Frame tab to show the Frame property page.

4	Choose one of the options for depth size, shadow size, or shadow direction.

5	Select OK to apply the change and close the Frame property sheet.

Whether you see this change reflected in the chart frame or field template depends on the type of chart you've selected.


Specifying legend properties

To specify legend properties:

1	Select the chart or a single chart object such as the chart title.

2	Choose the Frame command from the pop-up menu, or choose Chart [image] Frame to show the Frame property sheet.

3	Specify the desired settings.

4	Select OK to apply the changes to the frame and close the Frame property sheet.


Moving the legend

To move the legend:

1	Select and drag the legend frame to a new location.

2	If necessary, choose Update from the pop-up menu, or choose Chart [image] Update Chart to update the chart's appearance.


About adding, editing, and deleting reference lines

You can add a reference line that represents a significant value on the chart frame.  Once you've added a reference line to a chart, you can edit the reference line properties, or delete the reference line from the chart.  You can move a reference line by editing its value in the Reference Line property sheet.


Adding reference lines

To add a reference line:

1	Select the chart or a single chart object.

2	Choose the Reference Lines command from the pop-up menu, or choose Chart [image] Reference Lines to show the Reference Line property sheet.

If no reference lines currently exist, an alert appears asking if you want to create a new one.  If you select Yes, a new reference line is automatically created for you in the Reference Line property sheet.

3	Select New in the property sheet to create a new reference line.

4	Accept the default legend label and value, or modify their settings.

5	Select OK to draw the new reference line on the chart frame and close the Reference Line property sheet.


Editing reference line properties

To edit reference line properties:

1	Select the chart or a single chart object.

2	Choose the Reference Lines command from the pop-up menu, or choose Chart [image] Reference Lines to show the Reference Line property sheet.

3	Choose the reference line whose properties you wish to edit from the Reference Line drop-down list.

4	Specify the desired options.

5	Select OK to apply the changes to the reference line and close the Reference Line property sheet.


Deleting reference lines

To delete a reference line:

1	Select the chart or a single chart object.

2	Choose the Reference Lines command from the pop-up menu, or choose Chart [image] Reference Lines to show the Reference Line property sheet.

3	Choose the reference line you wish to delete from the Reference Line drop-down list.

4	Select Delete.

An alert appears, prompting you to confirm the deletion.

5	Select Yes to confirm.

6	Select OK to apply the change and close the Reference Line property sheet.


About specifying axis frame properties

You can modify the appearance of axis charts using the Frame property sheet.  Frame properties include baseline values, category width, depth size, shadow size, and shadow direction.  You can specify depth size, shadow size, and shadow direction. In addition, you can use the Frame property sheet to hide/show the legend. You can also specify that the legend be hidden, or split into multiple columns.


About specifying axis properties

For axis charts, axis properties include options specific to the type of axis you select:  discrete, continuous, or date.

In addition, you can specify custom labels for an axis, and set properties for the tick marks and tick labels used in the chart, or specify grid settings.


Specifying discrete, continuous, and date axis properties

To specify discrete, continuous and date axis properties:

1	Select the chart or a single chart object such as one of the axes.

2	Choose the Axis command from the pop-up menu, or choose Chart [image] Axes to show the Axis property sheet.

3	Choose an axis (e.g., X, Y1) whose properties you wish to modify from the Axis drop-down list.

4	Specify the desired options such as data type, axis direction, tick and tick label settings, etc.

Select the tabs at the top of the property sheet to switch between property pages.

5	Select OK to apply the changes to the selected axis.


About updating charts

When the data in the Query property sheet changes, or you've modified a chart's elements or function in some way, you need to update the chart to reflect those changes.  There are three ways to update a chart:

•	automatically

•	manually

•	using PL/SQL

You can use PL/SQL to update charts by executing timer triggers to be executed at specified intervals.


About dynamic vs. artwork-only charts

  Related Topics

A dynamic chart is a chart linked to a data source.  Initially, every chart is dynamic because Graphics Builder needs data with which to draw it.  Keeping a chart dynamic allows you to update it whenever you re-execute its query or change its chart template.  When you update a chart, Graphics Builder looks at the contents of the Data property page and the Chart Template editor, and redraws the chart based on the new information.

You also have the option of changing the chart to a static object.


About renaming charts

  Related Topics

Graphics Builder provides two locations for changing the name of a chart:

•	The Object Navigator

•	The Chart property sheet

If you rename a chart that is referenced in a PL/SQL program unit, you must change those references to reflect the new chart name.


About deleting charts

  Related Topics

If you wish to completely remove a chart you have created, as opposed to cutting it to the system clipboard, you can do so via:

•	The Object Navigator

•	The menu

If you delete a chart that you have referenced in any PL/SQL program units, you must change those references to reflect the deletion.

Note also that deleting a chart does not delete the query used to create that chart, nor does it delete any chart templates used for that chart.  You can delete these separately, or use them again.


Updating charts automatically

To update charts automatically:

  On the Data property page of the Chart property sheet, activate Update chart on query execution by selecting its check box.

Your chart will be updated whenever its query is executed.


Updating charts manually

To update charts manually:

1	Select the chart you want to update.

2	Choose Update from the pop-up menu or Chart [image] Update Chart.

Graphics Builder re-draws the chart based on the latest information.


Updating charts using PL/SQL

To update charts using PL/SQL:

  Use a timer trigger.

The procedure below shows the use of a timer trigger.

/*You could assign the following procedure to a
**timer trigger to be executed at a specified
**interval.  This example updates the specified
**chart to reflect new query results or new
**properties that have been applied to chart
**elements.
*/

PROCEDURE my_timer IS
   my_query   og_query;
   my_chart   og_object;
BEGIN
   my_query:=og_get_query('emp_query');
   my_chart:=og_get_object('emp_chart');
   og_execute_query(my_query);
   og_update_chart(my_chart, OG_ALL_CHUPDA);
END;


Converting charts to artwork

To convert a dynamic chart into a static artwork object:

1	Select the chart you want to convert to artwork.

2	Choose Chart [image] Convert to Artwork.

Graphics Builder converts the chart to a group object composed of shapes which you can manipulate individually.  As an artwork object, the chart can no longer be updated.


Renaming charts in the Object Navigator

To rename a chart in the Object Navigator:

1	Select the chart object you wish to rename.

2	Move the mouse pointer over the chart name.

The cursor changes from a pointer to a text editor.

3	Select the name once to position the cursor and enter edit mode.

If you wish to replace the entire name, select the name to highlight it, then type the new name.


Renaming charts in the Chart property sheet

To rename chart on the Chart property page:

1	Open the property sheet for the chart.

2	Edit the chart name in the name field.

3	Select OK to apply the new name and close the chart property sheet.


Deleting charts in the Object Navigator

To delete a chart in the Object Navigator:

1	Select the chart object in the Navigator.

2	Select Delete, or choose Navigator [image] Delete from the menu.

An alert appears, prompting you to confirm the deletion.

3	Select Yes to confirm.


Deleting charts using the menu

To delete a chart using the menu:

1. 	In the Layout Editor, select the chart you wish to delete.

2. 	Choose Edit [image] Clear.


About modifying objects

  Related Topics

Most objects are modified through their property sheets.  You can access the property sheet or object type dialog for any object in one of three ways:

•	In the Object Navigator, double-click the icon of the object you wish to edit, or

•	select the object and choose the Properties command from the pop-up menu, or

•	select the object and choose Tools [image] Properties.

The type of object you're editing will determine what events occur and how you proceed.


About selecting objects in the Object Navigator

Depending on what action you wish to take on the selected objects, you can also select single or multiple objects by their node name in the Object Navigator.  Selecting an object name node in the Object Navigator will also select the object in the Layout Editor.

Selecting objects in the Object Navigator can be useful if your objects are very small or close together and difficult to select in the Layout editor.

If you select an object that is a member of a group, the group object at the top of its group tree is selected.  You can select multiple objects by shift-clicking on each one.  When the Select tool is active, you can move objects by selecting them and dragging them.  You can resize objects by dragging their control points.


About scoping rules

Graphics Builder enforces certain scoping rules for selecting objects.  These rules are enforced while any object is selected.  The rules are:

1	The Select tool allows you to select only objects that belong to the same group as the currently selected object(s).  To select an object in another group-or one not in any group-do one of the following:

 First deselect all objects by selecting an unoccupied part of the layout, then select the other object as you normally would.

Choose one of the items in the Arrange [image] Group Operations submenu to add an object to an existing group.

2	You can select multiple objects only if they belong to the same group (i.e., they are siblings).


Selecting single or group objects

To select a single or group object:

1	Select the Select tool in the tool palette.

2	Select the object.

You can also drag a region around the object to select it.

To select a single or group object while other objects are selected:

1	Select the Select tool in the tool palette.

2	Shift-click the object to select it.

You can also hold down the Shift key while you drag a region around the object to select it.

3	Repeat this process for each object you want to select.


Selecting multiple objects

To select multiple objects:

1	Select the Select tool from the tool palette.

2	Drag a region around the objects to select them or select one object at a time using shift-click after you've selected the first object.


Selecting single objects within group objects

To select only the single object within a group object:

1	Select the Select tool in the tool palette.

2	Select the group object to select it.

You can also drag a region around the group object to select it.

3	Select the child object to select it.

When you use the Select tool to select a single object that is part of a group, you'll select the highest level group to which that object belongs.

To select a single object within a group while other objects within the same group are selected:

1	Select the Select tool in the tool palette.

2	Select the group object.

You can also hold down the Shift key while you drag a region around the group object to select it.

3	Select a child object.

4	Shift-click a second child object in the group to select it.

5	Repeat step 4 for each child object you want to select.

You may select multiple objects simultaneously only if they share the same parent.


Selecting all objects

To select all objects on the layout:

  Choose Edit [image] Select All.

All objects on the active layer are selected.


Selecting objects in the Object Navigator

Each object listed in the Navigator has three basic parts from left to right:

subobject indicator

type icon

name

To select an object in the Object Navigator:

  Select the object's type icon or name in the Object Navigator.

Notice that selecting an existing object (e.g., SAL_bars) in the Object Navigator selects the corresponding object(s) in the Layout editor.

Notice also that the name of the selected object appears in the Object Navigator window's title bar, so you know which object is currently selected.

You can select multiple object in the Navigator by holding down the Shift key while selecting an object type icon.


Subobject indicator

The highlighted plus sign indicates that you can expand this object to view its subobjects, an inactive plus sign indicates that the object has no subobjects and cannot be expanded.  The minus sign indicates that the object is already expanded.


Type icon

Indicates the object type such as layer, chart, chart element, shape, etc.


Name

Either the default name assigned by Graphics Builder, or a name you have customized


Deselecting Objects

To deselect objects:

  To deselect all selected objects, select a blank area of the layout.

  To deselect one of multiple selected objects, shift-click the object(s).


Moving a single or group object

To move a single or group object:

1	Select the object you want to move.

2	Select inside the bounding box of the object and drag it to a new location.

To maintain an object's position with respect to the horizontal or vertical axis, hold down the Shift key while dragging it horizontally or vertically.

You can also move an object one pixel at a time in any direction using the arrow keys.


Moving multiple objects

To move multiple objects:

1	Select the objects you want to move.

2	Select inside the bounding box of a single selected object and drag it to a new location.  All other selected objects will move with it.


Reordering objects in the Object Navigator

To reorder an object in the Object Navigator:

  Select and drag the object to its new position in the object hierarchy.

This action only changes the "order" of objects in the Navigator hierarchy.  To change the physical position of the object in the layout, you must move the object in the Layout editor.

Objects are listed in the Navigator in the order in which they are created.


Aligning objects

To align objects:

1	Select the objects you wish to align.

2	Choose Arrange [image] Align Objects to show the Alignment Settings dialog.

3	Specify the desired alignment settings such as whether to align the objects along their top or bottom edges, left or right sides, or centers.  You can also specify that objects be aligned to each other, or to the grid.

4	Select OK to confirm the alignment settings and align the objects.

To align objects using the current alignment settings:

1	Select the objects you want to align.

2	Choose Arrange [image] Repeat Alignment.

The objects are aligned according to the current settings in the Alignment Settings dialog box.

Once you specify alignment settings, those settings remain active until you change them.  You can define your alignment settings once, and repeat them as needed.


Changing stack order

To change stack order:

1	Select the objects(s) you want to move.

2	Choose the Arrange menu and then do one of the following:

•	 To move the object(s) in front of the object directly above it, choose Move Forward.

•	To move the object(s) in back of the object directly behind it, choose Move Backward.

•	To move the object(s) in front of all other objects, choose Bring to Front.

•	To move the object(s) behind all other objects, choose Send to Back.


Moving objects programmatically

  Related Topics

To move objects programmatically:

  Use the built-in procedure OG_MOVE.

The following example moves the specified object to another position on the layout:

PROCEDURE move_inventory(invent_obj IN og_object) IS

   distance   OG_POINT;
BEGIN
   distance.x:=(3*OG_INCH);
   distance.y:=(3*OG_INCH);
   OG_MOVE(invent_obj, distance);
END;


Copying objects

To copy objects:

1	Select the object(s) you want to copy.

2	Select Copy or Edit [image] Copy, or choose the Copy command from the pop-up menu.

Graphics Builder stores the object(s) on the Clipboard.


Cutting objects

To cut objects:

1	Select the object(s) you want to delete.

2	Choose the Cut command from the pop-up menu, or select Cut or choose Edit [image] Cut.

Graphics Builder deletes the object(s) from the layout and stores the object(s) on the Clipboard.


Clearing objects

To clear objects:

1	Select the object(s) you want to delete.

2	Choose the Clear command from the pop-up menu, or choose Edit [image] Clear.

Graphics Builder deletes the object(s) from the layout without affecting the contents of the Clipboard.

Cleared objects cannot be retrieved.


Clearing objects programmatically

  Related Topics

To clear objects programmatically:

  Use the PL/SQL built-in subprogram OG_DESTROY.

The following example deletes ("destroys") the specified window from the runtime display:

PROCEDURE destroy_USA IS
   the_window   OG_WINDOW;
BEGIN
   the_window:=OG_GET_WINDOW('USA_window');
   OG_DESTROY(the_window);
END;


Pasting objects

To paste objects:

  Select Paste or choose Edit [image] Paste.

Graphics Builder pastes the object(s) from the Clipboard to the layout in the same position as the original(s).  The object is selected and you can move it.

If you paste directly over the original object, you won't see the original until you move the copy.


Duplicating objects

To duplicate objects on the layout:

1	Select the object(s) you want to duplicate.

2	Choose Edit [image] Duplicate.

Graphics Builder duplicates the object(s) on the layout, slightly offset from the position of the original.

You can perform multiple duplications of the originally selected object by continuing to choose
Edit [image] Duplicate.


Duplicating objects programmatically

  Related Topics

To duplicate objects programmatically:

  Use the built-in subprogram OG_CLONE.

The following example creates a new object that is identical to the specified object:

PROCEDURE dup_object(my_old_object IN og_object) IS
   my_new_object   OG_OBJECT;
BEGIN
   my_new_object:=OG_CLONE(my_old_object);
END;


Deleting objects

To delete objects:

  Cut or clear them from the layout.   Cutting deletes objects and stores them on the Clipboard so you can paste them somewhere else.  Clearing deletes the objects without affecting the contents of the Clipboard.

In addition, you can delete objects from the Object Navigator.


Deleting objects from the Object Navigator

  Related Topics

To delete an object from the Object Navigator:

1	Select the object you wish to delete.

2	Select Delete or choose Navigator [image] Delete.

An alert appears, prompting you to confirm the deletion.

3	Select Yes to confirm.

If you delete an object that is referenced within a program unit, you must edit the program unit to reflect the deletion.


Setting symbol size

To set the size of symbol objects:

1	Select the symbol object.

2	Choose Format [image] Symbol to show a submenu of options.

3	Choose Large, Medium, or Small.

The size you select is applied to the currently selected symbol object.  The setting remains in effect for the current display until you change it again.


Resizing objects

To resize objects:

  Drag one of their four control points to a new position.  The way in which you drag the control point determines how the object will change size.

To maintain an object's aspect ratio, hold down the Shift key while dragging the control point to a new position.


Resizing single or group objects

To resize a single or group object:

1	Select the object you want to resize.

2	Select a control point and drag it to a new position.


Resizing multiple objects

To resize multiple objects:

1	Select the objects you want to resize.

2	Select the control point of a single selected object and drag it to a new position.

All other selected objects will change size relative to that object.


Making multiple objects the same size

To make multiple objects the same size:

1	Select the objects you want to resize.

2	Choose Arrange [image] Size Objects to show the Size Objects dialog.

3	Specify the desired options such as whether to size according to the larger or smaller object, or use an average, for width, height, or both, and what unit of measure to use.

4	Select OK to resize the objects according to your settings and close the Size Objects dialog


Resizing objects programmatically

  Related Topics

To resize objects programmatically:

  Use the PL/SQL built-in subprogram OG_SCALE.

The following example of a button procedure doubles the size of the specified object:

PROCEDURE double(buttonobj IN og_object, hitobj IN
 og_object, win IN og_window, eventinfo IN og_event) IS
   anchor OG_POINT;
   newpt  OG_POINT;
   oldpt  OG_POINT;
BEGIN
   anchor.x:=OG_INCH;
   anchor.y:=OG_INCH;
   oldpt.x:=OG_INCH+1;
   oldpt.y:=OG_INCH+1;
   newpt.x:=OG_INCH+2;
   newpt.y:=OG_INCH+2;
   OG_SCALE(hitobj, anchor, oldpt, newpt);
END;


Reshaping objects

To reshape objects, drag their vertices to a new position.  Note that the control points you see when reshaping an object differ from those you see when selecting an object.  The Reshaping tool produces different results for different objects:

Object	Reshape

arc	change the sweep angle to something other than 90 degrees (the default)
polygons and polylines	move any vertex to a new position
lines	move the start point or end point to a new position
ellipses, rectangles, rounded rectangles	move any vertex to a new position
freehand objects	move any point to a new position
images	clip (or crop) the image
Reshaping ellipses, rectangles, and rounded rectangles differs from using the Select tool only if the object has been rotated such that the select control points no longer coincide with the reshape control points.

To reshape an object:

1	Select the object you want to reshape.

2	Select the Reshaping tool from the tool palette.

Depending on the type of object, the control points move to the vertices of the object.

3	Select one of the vertices and drag it to a new position.

The Reshaping tool produces different results for different types of objects.


About rotating objects

You can rotate single or multiple objects in any direction using the Rotate tool.  Objects are rotated on their centerpoint.

Some systems do not support rotating text.  For more information, see the your operating system documentation.


Rotating single or multiple objects

To rotate single or multiple objects:

1	Select the Rotate tool from the tool palette.

2	Select a control point of the object(s) and drag it in the direction you want the object(s) to rotate.


Rotating objects within groups

To rotate objects within a group:

1	Select the Select tool from the tool palette.

2	Select the group object.

You can also drag a region around the group object to select it.

3	Select the child object.

Use Shift-click to select multiple child objects in the group.

4	Select the Rotate tool from the tool palette.

5	Select a control point of the object(s) and drag it in the direction you want the object(s) to rotate.


Rotating objects programmatically

  Related Topics

To rotate objects programmatically:

  Use the PL/SQL built-in subprogram OG_ROTATE.

The following example rotates the specified object by the specified number of degrees counterclockwise:

PROCEDURE rotate_needle (degrees IN NUMBER,
 center_pt IN og_point) IS
   the_needle     OG_OBJECT;
BEGIN   the_needle:=og_get_object('Needle 1');
   OG_ROTATE(the_needle, center_pt, degrees);
END;


About group operations

You can group multiple objects together so that you can manipulate them as one object.  The objects that belong to a group are the child objects, and the group is the parent.  You can also group more than one group object together.  The resulting group will be made up of subgroups.


Grouping objects

To group objects:

1	Select the objects you want to group together.

2	Choose Arrange [image] Group.

The objects are grouped together.


Selecting the parent group

To select the parent group:

  Choose Arrange [image] Group Operations [image] Select Parent.

The parent group is selected.


Selecting child objects

To select child objects:

  Choose Arrange [image] Group Operations [image] Select Children.

The child objects of the group object are selected.


Adding and removing child objects

To add or remove child objects:

1	Select both the group object and the object you want to add, or select the child object you want to remove.

2	Choose Arrange [image] Group Operations, and then do one of the following:

•	 To add an object to the group object, select Add to Group.

•	To remove a child object from the group object, select Remove from Group.


Adding and removing child objects programmatically

  Related Topics

To add and remove child objects programmatically:

  Use the PL/SQL built-in subprograms OG_DELETE_CHILD and OG_INSERT_CHILD.

The following example removes a child object from one group object and inserts it into another:

PROCEDURE move_prod(warehouse1 IN og_object, warehouse2 IN
 og_object, prod_index IN NUMBER) IS
   oldpt.x:=OG_INCH+1;
   oldpt.y:=OG_INCH+1;
   newpt.x:=OG_INCH+2;
   newpt.y:=OG_INCH+2;
   OG_SCALE(hitobj, anchor, oldpt, newpt);
   the_prod  og_object;
BEGIN
   the_prod:=OG_GET_CHILD(warehouse1, prod_index);
   OG_DELETE_CHILD(warehouse1, prod_index, 1);
   OG_INSERT_CHILD(warehouse2, the_prod, OG_LAST);
END;


Ungrouping objects

To ungroup objects:

1	Select the group object.

2	Choose Arrange [image] Ungroup.

The grouped objects are separated.


Renaming objects

  Related Topics

To rename objects:

1	Double-click the object or object group to show the Object property sheet.

Alternatively, you can select the object or object group and choose the Properties command from the pop-up menu, or select the object and choose Tools [image] Properties.

2	Type a name in the Name field.

3	Select OK to accept the new name and close the Object property sheet.

Once you have created an object, you can name it using the Object property sheet.  Alternatively, you can name an object directly in the Object Navigator by selecting the object name and editing it accordingly.

If you plan on using your objects in any PL/SQL program units, you should assign each object a unique name so you can reference it easily.

If you change the names of any objects referenced in PL/SQL program units, you must change those references to reflect the new name.


Renaming objects in the Object Navigator

  Related Topics

To rename an object in the Object Navigator:

1	Select the object you wish to rename.

2	Move the mouse pointer over the object name.

The cursor changes from a pointer to a text editor.

3	Select the name once to position the cursor and enter edit mode.

You can rename any object you have created within a display layout.  This includes layers, queries, graphic objects, parameters, timers, sounds, charts, and chart templates.     If you wish to replace the entire name, select the name to highlight it, then type the new name.  Note that if you rename an object that is referenced within a program unit, you must change those references as well to reflect the new name.

If you wish to rename a PL/SQL program unit, you must do so from the Program Unit editor.


Sharing objects between displays

To share an object between displays:

1	In the Object Navigator, select the query, parameter, timer, sound, or program unit you wish to move.

2	Hold down the Select button on the object and drag it vertically to its new location.  The cursor changes to a crosshair and a dashed horizontal line indicates the current node location of the object in the Navigator.

3	Release the mouse button to "drop" the object.  You must "drop" the object into its correct node in the object hierarchy (i.e., queries must be dropped beneath the Query node, etc.).

In addition to reordering objects within a display, you can move queries, program units, parameters, timers, and sounds from one open display to another open display.  You can also move program units to and from attached or open libraries.

Note that when you move a program unit from one display to another, it loses its compiled state and must be recompiled in its new context.


Changing object references in program units

To change object references in program units:

1	Double-click the program unit that references the object to show the program unit in the Program Unit editor.

2	Choose Edit [image] Search/Replace to show the Search/Replace dialog.

3	Type the old object name in the Search field.

You can specify a case sensitive search, or use a regular expression to search by.

4	Type the new object name in the Replace With field.

5	Select Replace All to replace all occurrences of the old object name with the new object name in the current program unit.

To search for and replace a name in all program units in the current scope (i.e. the Program Units node, or an open library node), choose Edit [image] Search/Replace All.


About applying colors and patterns

  Related Topics

The procedures for applying colors and patterns to components of the chart frame are the same as those for objects.


The Line/Fill/Text display shows the edge, fill, and text pattern and colors that are currently selected.  Each object you create will use those settings unless you specify different ones.


Setting colors for objects

To set colors for objects:

1	Select any existing object(s) or chart elements to which you want to apply color.

2	Select the Fill Color palette to select a background color for the object, or select the Line Color palette to select a foreground color for the border of the object.

The appropriate color palette appears.

You can "tear off" the color palette and move it to another location within the Layout Editor by selecting the Tear Off Palette option and then dragging the title bar of the palette to move it.

3	Select a color from the palette.

The palette closes and the color, if any, is applied to any selected objects and any new objects you draw on the layout.  The color also appears in the appropriate part of the Line/Fill/Text display box and remains in effect for the current display until you change it again.

If your system supports color, you can apply colors to both the inside (fill) and border (line) of an object.


Setting fill patterns

To set the fill pattern:

1	Select any existing object(s) to which you want the pattern applied.

2	Select the Fill Color palette.

3	Choose the Patterns command from the Fill Color palette menu to show the Pattern palette.

4	Select the pattern you wish to apply to the object.

The pattern is applied to any selected objects and new objects you draw on the layout.  The pattern also appears in the fill part of the Line/Fill/Text display box and remains in effect for the current display until you change it again.

5	Close the Pattern palette.

Different patterns can be applied to the fill of objects.  For text objects, you can apply patterns to the fill of the bounding box, but not the characters themselves.  For charts, you can apply patterns in the chart template.


Setting pattern colors

To set pattern colors:

1	Select any existing object(s) or chart elements to which you want the foreground and background pattern colors applied.

If you do not select an object, the settings will not be applied to any existing objects, but will remain in affect for any new objects you create until you change them.

2	Select the Fill Color palette.

3	Choose the Patterns command from the Fill Color palette menu.

The Pattern palette appears showing the current settings for foreground and background colors.  You can move this palette around the layout to improve visibility.

4	Select the drop-down color palette for either the Foreground color (left side) or the Background color (right side).

The appropriate palette opens to show the colors available on your system.

5	Select the color you want to apply to the foreground or background of the pattern.

The pattern foreground/background color palette closes and the changes are reflected in the Pattern palette.  In addition, the color is applied to any selected objects, and in the fill part of the Line/Fill/Text display box.

6	Close the Pattern palette or select another color.

The selection remains in effect for the current display until you change it again.

The dark part of a pattern is called the foreground element, and the light part of a pattern is called the background element.  If your system supports color, you can apply different colors to the foreground and background elements of the current fill pattern.


Setting text color

  Related Topics

To set text color:

1	Select the text object or chart element you wish to apply a color to.

2	Select the Text Color palette icon in the Layout Editor to show the Text Color palette.

You can "tear off" the color palette and move it to another location within the Layout Editor by selecting the Tear Off Palette option and then dragging the title bar of the palette to move it.

3	Select a color for the text.

The palette closes and the color, if any, is applied to any selected text objects and new text objects you create on the layout.  The color also appears in the appropriate part of the Line/Fill/Text display box and remains in effect for the current display until you change it again.

In addition to setting colors and patterns for a text object's bounding box, you can select colors for the text itself.  For text within charts, you can apply colors in the chart template, or by selecting the chart element directly in the Layout Editor.

If you want to link a chart element color to your data source, you can apply a color to chart elements using a format trigger.


Removing fill patterns and colors from objects

To remove fill patterns and colors from objects:

1	Select any existing object(s) or chart elements for which you want to reset or remove color or patterns.

2	Select the Fill Color palette.

You can "tear off" the color palette and move it to another location within the Layout editor by selecting the Tear Off Palette option and then dragging the title bar of the palette to move it.

3	Select the No Fill option to remove the current color or pattern selection.

The palette closes and the fill color is reset for any selected objects and any new objects you draw on the layout.  The color also appears in the appropriate part of the Line/Fill/Text display box and remains in effect for the current display until you change it again.

The pattern and colors you select for an object remain active until you reset them.


Changing an object's color programmatically

  Related Topics

To change an object’s color programmatically:

  Use any of the PL/SQL built-in subprograms that modify color, such as OG_SET_FFCOLOR.

The following example uses the OG_SET_FFCOLOR graphic property built-in to set the foreground fill property of the specified object:

PROCEDURE color_country(country_name) IS
   my_object    OG_OBJECT;
BEGIN
   my_object:=OG_GET_OBJECT(country_name);
   OG_SET_FFCOLOR(country_name, 'color 72');
END;


Editing color palettes

To edit a color palette:

1	Choose Format [image] Color Palette to show the Color Palette dialog.

If this menu item is not available, make sure Color Mode is set to Editable in the Tools Options-Defaults property sheet.  If it is not, you must close the display and open it again for the new Color Mode setting to take effect.

2	Select a color to edit.

3	Select Edit.

Your system's color editing dialog box appears.

4	Edit the color by following the procedure for your system.

5	Accept the dialog box to return to the Color Palette dialog box.

6	To rename the color, type a different name in the Current Color field and select Rename.

7	Select OK to close the Color Palette dialog.

If your system supports color, you can edit the current color palette for your display.  You can also import and export color palettes.


Hiding an object's borders

To hide an object’s borders:

1	Select any existing object(s) or chart elements you want to remove the border of.

2	Select the Line Color palette.

You can "tear off" the color palette and move it to another location within the Layout editor by selecting the Tear Off Palette option and then dragging the title bar of the palette to move it.

3	Select the No Line option to hide the border.

The palette closes and the line color is reset for any selected objects and new objects you draw on the layout.  The color, or lack thereof also appears in the appropriate part of the Line/Fill/Text display box and remains in effect for the current display until you change it again.


Setting line properties

To set line properties:

1	Select the line(s).

2	Choose one of the following commands from the Format menu:

•	 Line	Shows a submenu of line width sizes.

•	Dash	Shows a submenu of line dash styles.

•	Arrow	Show a submenu of arrow styles.

3	Specify the desired options.

The properties you select are applied to the line object.  Settings remain in effect for the current display until you change them again.


Setting edge properties

  Related Topics

To set edge properties:

1	Select the object(s).

2	Choose Format [image] Line to set edge width, or Format [image] Bevel to show a list of bevelling options.

If you want to set a bevelling option for the object's edge, you should set a line width of at least 2 pt.

3	Specify the desired options.

The properties you select are applied to the edges of the selected object(s).  Settings remain in effect for the current display until you change them again.


About specifying number and date formats

You can set number and date formats in one of the following locations, depending on your needs:

•	Layout Editor

•	Chart template

•	Preferences file

Set number and date formats in the Layout Editor if you want to set Number and Date formats directly on a specific chart.

Set number and date formats in the Chart template if you want to set Number and Date formats for a specific chart template.

Set number and date formats in the preferences file if you want to apply the formats to all charts and all Builder settings, or if you are using date data from external files such as PRN files.  This ensures that any dates referenced in those external files will map correctly into dates in the chart.  If a matching date format is not specified in your preferences file, Graphics Builder treats the external date as character data.


Setting properties for the whole text object or text field

  Related Topics

To set properties for the whole text object or text field:

1	Select the text object or text field.

2	Choose Format [image] Font, Spacing, or Justification to show a submenu or dialog(Font) of options.

3	Specify the desired options.

The properties you select are applied to the text object or text field.

4	When you're finished, select the layout outside the text object to deselect the text object or text field.


Setting properties for a partial text object or default text field text

To set text properties for a partial text object or default text field text:

1	Select the Text tool from the tool palette.

2	Select the text object or text field where you want to change properties.

The text cursor appears where you selected.

3	Drag over the text you want to change.

4	Choose Format [image] Font, Spacing, or Justification to show a submenu of options.

5	Specify the desired options.

The properties you select are applied to the text.

6	When you're finished, select the layout outside the text object or text field to exit text mode and deselect the text.


Setting number and date formats in your preferences file

To set number and date formats in your preferences file:

1	Choose Tools [image] Tools Options to show the Tools Options property sheet.

2	Select either Number or Date to show the Number Format or Date Format dialog.

3	Enter your preferred date or number format in the Format field.

For more information about valid formats, see the Oracle7 Server SQL Language Reference Manual.

4	Select Add to add the format to the list.

5	Select OK to accept your changes to the format list and close the dialog.

6	Select Save to save your settings to your preferences file, or select OK to save your settings for the current session only.

When you create a chart, the last format added to the format list is used.


Setting number and date formats in the Layout Editor

To set number and date formats directly on the chart in the Layout Editor:

1	Select the chart element whose number or date format you wish to edit.

All elements of that set are selected.

2	Choose Number Format or Date Format from the pop-up menu, or choose Format [image] Number or Format [image] Date to show the Number Format or Date Format dialog.

3	Select Date or Number to show the Date Format dialog box or Number Format dialog box, respectively.

The current number or date format appears in the Format field.

4	You can edit the current format, select an alternate format from the list, or enter a new format and add it to the list.  If you want to add a format to the list permanently, see the section above on setting number and date formats in your preferences file.

5	Select OK to accept your changes to the format list and close the dialog.

Your changes are reflected in all charts that use the template you edited.

For more information about valid formats, see the Oracle7 Server SQL Language Reference Manual.


Setting number and date formats in the chart template

To set the number and date formats in the chart template:

1	Choose Tools [image] Templates to show the Chart Template editor.

2	Select the template you wish to set a number or date format for in the Template drop-down list.

The template appears in the editor's layout.

3	Select the chart template element that represents the number or date format you wish to set.

4	Choose Format [image] Number or Format [image] Date accordingly to show the Number Format or Date Format dialog.

The current number or date format appears in the Format field.

5	You can edit the current format, select an alternate format from the list, or enter a new format and add it to the list.

If you want to add a format to the list permanently, see the section above on setting number and date formats in your preferences file.

6	Select OK to accept your changes to the format list and close the dialog.

7	Close the Chart Template editor.

Your changes are reflected in all charts that use the template you edited.

For more information about valid formats, see the Oracle7 Server SQL Language Reference Manual.


Editing text objects

To edit a text object:

1	Select the Text tool from the tool palette.

2	Select the text object where you want to begin typing or editing.

The text cursor appears where you selected.

3	Type or edit the text.

You can select a block of text by dragging over it.

4	When you're finished, select the layout outside the text object to exit text mode.


Playing and editing sounds

To play or edit a sound:

1	Double-click an existing sound to display the Sound Player dialog box.

2	Play or record over the existing sound by choosing the Play or Record buttons, respectively.

You can also use the Forward and Rewind buttons, or the slide bar to find a position in the sound file.

3	Select OK to close the Sound Player dialog box.


Playing sounds programmatically

  Related Topics

To play sounds programmatically:

  Use the PL/SQL built-in procedure OG_PLAY SOUND, and the function OG_GET_SOUND.

The following example plays the specified sound through the sound output device specified in your preferences:

PROCEDURE warning IS
   the_sound   OG_SOUND;
BEGIN
   the_sound:=OG_GET_SOUND('warning_snd');
   OG_PLAY_SOUND(the_sound);
END;


Exporting sounds

To export sounds:

1	Select the sound object in the Navigator.

2	Choose Edit [image] Export [image] Sound to display the Export Sound dialog.

3	Specify the desired options such as filename and location, the file format and compression to export the sound in, etc.

4	Select OK to confirm the information and close the Export dialog.

The sound is exported to the location you specified.


Renaming internal sounds

  Related Topics

To rename an internal sound:

1	Select the sound object you wish to rename.

2	Move the mouse pointer over the sound name.

The cursor changes from a pointer to a text editor.

3	Select the name once to position the cursor and enter edit mode.

If you want to replace the entire name, select the name to highlight it, then type the new name.

Sounds that you have created in the Builder or imported into the display are considered to be internal to the display.  Sounds that are stored in the file system or the database are considered external to the display.  The location of the sound determines what methods you use to grant and revoke access, rename, or delete the sound.

If you rename a sound that you have referenced in a PL/SQL program unit, you must change all references to reflect the new name.


Deleting internal sounds

To delete an internal sound:

1	Select the sound object you wish to delete.

2	Select Delete, or Navigator [image] Delete.

3	Choose Yes to accept the delete confirmation that appears.

The sound is removed from the display.

Sounds that you have created in the Builder or imported into the display are considered to be internal to the display.  Sounds that are stored in the file system or the database are considered external to the display.  The location of the sound determines what methods you use to grant and revoke access, rename, or delete the sound.


About parameters

Parameters are most commonly used in drill-down relationships, where they represent the value of a chart element or the name of a graphic object in your display.  The parameter is then used in a query or PL/SQL program unit to drive a specified action.

Parameters can also be used in multiple PL/SQL program units as global variables.

Possible uses for parameters are:

•	represent the value of a chart element in a drill-down relationship

•	represent the name of a graphic object in a drill-down relationship or button procedure

•	store a value in a PL/SQL program unit

•	store a string value such as a where clause for use in a query


About parameter components

Each parameter you create has the following components:

name

type

initial value


Name

The name that you will use to refer to the parameter in your SQL or PL/SQL statements.


Type

The data type of the value the parameter represents.  The valid entries in the pop-list are Number, Char, and Date.


Initial value

(Optional)  The value assigned to the parameter when you first run the display.  The value entered here can be superseded by a value that is assigned manually or programmatically.


About creating parameters

Create parameters using the Parameters dialog box.  You can create parameters before you use them, or create them within other tasks such as establishing drill-down relationships.

If you wish to create a global variable of a different datatype than NUMBER, CHAR, or DATE -- for example, one of the Graphics Builder PL/SQL built-in datatypes -- you can create a package to define those variables.  For more information on PL/SQL packages, see the PL/SQL User's Guide and Reference.

Once you have created a parameter, you can reference it within program units, SQL queries, or drill-down procedures.


Creating standalone parameters with the Object Navigator

To create a standalone parameter with the Object Navigator:

1	Select the Parameters node in the Object Navigator

2	Select the Create button, or choose Navigator [image] Create from the menu to display the Parameters dialog box.

If no parameters currently exist, double-click on the Parameters node to display the Parameters dialog box.

The new parameter is initially named paramx and has a type of Char.

3	Define the new parameter's name, type, and initial value.

4	Select OK to accept the new parameter settings and close the dialog box.


Creating standalone parameters with the menu

To create a standalone parameter with the menu:

1	Choose Tools [image] Parameters to display the Parameters dialog box.

2	Select the New button to create a new parameter.

The new parameter is initially named paramx and has a type of Char.

3	Define the parameter's name, type, and initial value.

4	Select OK to accept the new parameter settings and close the dialog box.


Creating new parameters in the drill-down page

  Related Topics

To create a new parameter in the drill-down page:

1	Double-click on an object in your show that you wish to assign parameter values to (chart element, etc.) to display the Object property sheet.

Alternatively, you can select the object and choose the Properties command from the pop-up menu, or choose Tools [image] Properties  to display the Object property sheet.

2	Choose the Drill-down tab to display the Drill-down property page.

3	Select New, to the right of the Set Parameter field, to display the parameters dialog box.

4	Define the parameter's type, and initial value.

5	Select OK to accept the new parameter settings and close the dialog box.

6	Set the To Value Of and Execute Query fields in the Drill-down property page.

7	Select OK to accept the drill-down relationship.


Creating new parameters by reference

To create a new parameter by reference:

1	Within a SQL query or PL/SQL program unit, enter a reference to a unique parameter name.  For example:

:object := OG_GET_OBJECT (circle1);

2	Select OK to execute your query, or select Compile to compile your program unit.

3	An alert appears prompting you that the referenced parameter does not exist and asking if you would like to create it.

4	Select Yes to confirm and display the Parameters dialog.

5	Define the parameter's type, and initial value.

6	Select OK to accept the new parameter settings and close the dialog box.

7	Select OK to re-execute your query, or select Compile to re-compile your program unit.

If you are creating a SQL SELECT statement or PL/SQL program unit and decide you need to use a parameter, simply reference a new and unique parameter name as you would if the parameter existed.  When you attempt to execute the query, or compile the program unit, Graphics Builder will prompt you to create the new parameter and will display the Parameter dialog.


Renaming parameters in the Object Navigator

To rename a parameter in the Object Navigator:

1	Select the parameter object you wish to rename.

2	Select the name once to position the cursor and enter edit mode.

If you wish to replace the entire name, select the name to highlight it, then type the new name.

3	If you have referenced the parameter in any SQL SELECT statements, PL/SQL program units, or drill-down relationships, change those references to reflect the new parameter name.


Renaming parameters in the Parameters dialog

To rename a parameter in the Parameters dialog:

1	Open the Parameters dialog box.

2	Select the parameter you wish to rename from the Name drop-down list.

3	Edit the name.

4	Select OK to accept the new name and close the Parameters dialog box.

5	If you have referenced the parameter in any SQL SELECT statements, PL/SQL program units, or drill-down relationships, change those references to reflect the new parameter name.


Editing parameters with the Object Navigator

To edit a parameter with the Object navigator:

1	Double-click on the parameter object to display the Parameters dialog.

Alternatively, you can select the parameter object and choose the Properties command from the pop-up menu, or choose Tools [image] Properties.

2	Make the desired setting changes.

3	Select OK to accept the changes and close the dialog box.


Editing parameters using the menu

To edit a parameter with the menu:

1	Choose Tools [image] Parameters to display the Parameters dialog box.

2	Choose the name of the parameter you wish to modify from the Parameters drop-down list.

3	Make the desired setting changes.

4	Select OK to accept the changes and close the dialog box.


About referencing parameters

There are two types of parameter references in Graphics Builder:

•	bind

•	lexical

Note that although parameter names are listed in all capital letters in the Parameters dialog box, they are not case-sensitive when used in your SQL or PL/SQL statements.

If you reference a parameter that does not exist, an alert appears asking if you wish to create it at that time.  If you answer yes, the Parameters dialog is displayed.


About assigning values to parameters

You can assign values to parameters in four ways:

•	Initially, in the Parameters dialog box.

•	Within PL/SQL program units.

•	Based on user action.

•	As arguments to the Runtime or Batch executables.

At runtime, the values of the parameters are substituted for their references in the SQL SELECT statements or PL/SQL program units.


About assigning parameter values based on user action

  Related Topics

You can tie a parameter value to any object in your display -- for instance, a chart element -- and have the user set the parameter value by selecting a display object in the Runtime display.  Two possible applications are:

•	Creating a drill-down relationship.

•	Using object button procedures.


Creating a bind reference

To create a bind reference:

  Type a colon(:) immediately before the parameter name.  Because you can create parameters on-the-fly, it is not necessary to define the parameter prior to referencing it.

For example, in the following SQL SELECT statement, my_param represents a single value for the ENAME column in the EMP table:

select ename, sal
from emp
where ename = :my_param

Use a bind reference to substitute a single value, such as a character string, number, or date in either SQL SELECT statements or PL/SQL program units.


Creating a lexical reference

To create a lexical reference:

  Create a lexical reference to a parameter or column by typing an ampersand (&) immediately before the parameter or column name.  Also provide an initial value for each lexical reference, as a default definition is not provided.

For example, to use a parameter to represent a WHERE clause in a SELECT statement, first define the parameter and type the WHERE clause in the initial value field.

Then, create your SELECT statement:

select ename, sal
from emp
&my_param

Alternatively, you could assign the value programmatically, then execute the query based on the new value, and update the associated chart:

PROCEDURE set_param (name IN VARCHAR2, qry IN OG_QUERY) IS
  the_chart  OG_OBJECT;
BEGIN
  :my_param:='WHERE ENAME = '||name;
  OG_EXECUTE_QUERY(qry);
  the_chart:=OG_GET_CHART('chart0');
  OG_UPDATE_CHART(the_chart, OG_ALL_CHUPDA);
END;

If you want to use lexicals to replace column names in a SELECT statement, create a separate lexical for each column you will substitute.  Give each column an alias so that Graphics Builder will be able to map the fields correctly.  Also specify the same number of items at runtime as were specified in the statement.

For example:

select &param1 ONE, &param2 TWO
from &tablename
&where_clause

Use a lexical reference as placeholder for a compound text string in a SQL SELECT statement.  You can use lexical references to replace the clauses appearing after SELECT, FROM, WHERE, GROUP BY, ORDER BY, HAVING, CONNECT BY, and START WITH.

Only a parameter of type Char may be used as a lexical parameter.  Also, you cannot make lexical references in a PL/SQL statement.


Assigning an initial value to a parameter

  Related Topics

To assign an initial value to a parameter:

  Type a value in the Initial Value field.


Assigning a value to a parameter using PL/SQL

  Related Topics

To assign a value to a parameter using PL/SQL:

  Reference the parameter and assign it a value as you would any other variable.

For example, to assign the parameter DNO a value of 10, you could include the following statement in a procedure:

:DNO := 10;

You can assign parameters an absolute value, such as a number or text string, or you can assign them relative values using other variables, parameters, and operators.

For example, suppose you defined a parameter named my_num of type Number.  The following is valid in a PL/SQL statement:

PROCEDURE double IS
BEGIN
  :my_num := :my_num*2;
END;

This would set the value of my_num to twice its previous value.


Assigning parameter values on the command line

  Related Topics

To assign parameter values on the command line:

  Include the parameter assignment as the final arguments in the command string.  The value specified for the parameter supersedes the parameter's initial value as set in the Parameters dialog box.

The example below shows how you would assign values to parameters hisparam (NUMBER datatype) and herparam (DATE datatype):

g30des openfile=chart1 hisparam=29 herparam='02-OCT-94'

Parameters are global, whereas variables can be used only within the program unit where they are defined.  If you wish to use the variable outside the program unit, use a parameter instead.


Using object button procedures to set parameter values

To use an object button procedure

1	Double-click on the graphic object you wish to set the parameter value to.

Alternatively, you can select the object then choose Properties from the pop-up menu, or choose Tools [image] Properties.

2	Choose the Drill-down tab to display the drill-down page.

3	Select a parameter from the Set Parameter pop-list, or select New to create a new parameter.

4	Type the parameter name in the Name field.

Similar to a drill-down chart, a button procedure is activated by the user in the Runtime display.  However, rather than select a chart element to drive the action, the user selects a graphic object.

The Object Name value is defined as the datatype CHAR.  If you have defined the parameter as being a datatype other than CHAR, you must use the TO_CHAR conversion function when you reference the parameter in a query or PL/SQL program unit.  For more information on TO_CHAR, see the PL/SQL User's Guide and Reference.

You can now use the parameter in any program unit within the display.


Deleting parameters in the Object Navigator

To delete a parameter in the Object Navigator:

1	Select the parameter object in the Navigator.

2	Select the Delete button, or choose Navigator [image] Delete from the menu.

3	In the alert, select Yes to confirm.

4	If you have referenced the parameter in any SQL SELECT statements, PL/SQL program units, or drill-down relationships, change those references to reflect the deletion.


Deleting parameters from the Parameters dialog

To delete a parameter from the Parameters dialog:

1	Choose Tools [image] Parameters to display the Parameters dialog box.

2	Select the name of the parameter you wish to delete from the Parameters drop-down list.

3	Select Delete.

4	In the alert, select Yes to confirm.

5	Select OK to close the Parameters dialog.

6	If you have referenced the parameter in any SQL SELECT statements, PL/SQL program units, or drill-down relationships, change those references to reflect the deletion.


Opening a display

To open a display:

1	Choose File [image] Open to display the Filter dialog.

2	Select the appropriate radio button:

•	File System if the display is saved in a file

•	Database if the display is saved in the database

3	Select the Displays or All Files check box, then select OK.

4	Select a display to open, then select OK.


Preparing displays for runtime

  Related Topics

To prepare a display for runtime:

Size the layout:

1	Choose View [image] View Options [image] Layout from the menu.

2	Change the default Horizontal and Vertical size in the Layout Size field.

3	Choose either the Inches or Centimeters radio buttons.

4	Select OK to accept the Layout size settings and close the dialog.

Your display layout is changed to the specified size.  You can use these size settings to determine the size of the window the display appears in.

Set Window Properties for the Default Window:

By default, Graphics Builder opens each display in a window named Main Layout.  You can change the following properties of the default window:

•	position in the Runtime layout

•	horizontal and vertical size of the window

•	window name

If you want to set properties for the default window, you should do so in an Open Display trigger such as the following:

PROCEDURE OGTRIGGERPROC0 IS
  the_win    OG_WINDOW;
  win_pos    OG_POINT;
  win_wid    NUMBER;
  win_ht     NUMBER;
BEGIN
  the_win:=OG_GET_WINDOW('Main Layout');

/*Define the position for the window*/
  win_pos.x:=1*OG_INCH;
  win_pos.y:=.5*OG_INCH;

/*Set the position property for the window*/
  OG_SET_POSITION(the_win, win_pos);

/*Define the size of the window */
  win_wid:=4*OG_APP.HSCREEN_RES;
  win_ht:=5*OG_APP.VSCREEN_RES;

/*Set the size property of the window*/
  OG_SET_WINDOW_SIZE(the_win, win_wid, win_ht);

/*Assign a name to the window */
  OG_SET_WINDOW_NAME(the_win, 'Start Here');
END;

When the display is opened in Graphics Builder Runtime, the display will be opened in a 4x5 window with the title 'Start Here' at the coordinate position (1, .5).

Specify Layout Units:

Define a specific horizontal and vertical size for the display window using the OG_APP constants HSCREEN_RES and VSCREEN_RES.  These are similar to OG_INCH, but are used exclusively for window dimensions.

Horizontal and vertical layout resolution are always equal.  The OG_APP.HSCREEN_RES and OG_APP.VSCREEN_RES constants represent the number of layout units (pixels) in one horizontal inch and one vertical inch, respectively.  This unit of measurement ensures that your display window will appear the same regardless of the screen resolution on which it is used.

Use the OG_POINT PL/SQL built-in datatype to represent (x.y) coordinates on the layout.  The value (0,0) represents the upper left corner of the display.  These coordinates are expressed in layout units.


About generating displays

When you generate a runtime version of a display, it contains only the elements needed to run it with the Graphics Builder Runtime or Batch executables.  For example, a generated display does not contain PL/SQL source code.


Generating a display

To generate a display:

1	Choose File [image] Administration [image] Generate [image] File System or Database, depending on where the display is to be saved.

2	Type the name of the runtime display file or accept the default name.

Graphics Builder runtime displays use the file extension .ogr by default.

3	Select OK to generate a runtime version of the display.


About testing displays

  Related Topics

In the Builder, you can test the execution of your display by accessing the Graphics Builder Debugger.  When you select a display to run in the debugger, Graphics Builder runs the stored version of the display.  Therefore, if your display is open in the Builder, be sure to save any recent changes you've made before running it.


Running an open display

To run an open display:

1	Select the display object in the Navigator.

2	Select the Run button in the toolbar to open the display in the Graphics Builder Debugger Main Layout window, which simulates runtime execution of your display.

3	Choose File [image] Close to close the debugger when you are done.

If you change a display in the Builder while it is open in the debugger, the changes will not be visible in the debugger until you save the display and run it again.  If you edit PL/SQL program units in the debugger, you can incorporate your changes back into the Builder using Edit [image] Synchronize Program Units.


Running a closed display

To run a closed display:

1	Choose File [image] Run to display the filter dialog.

2	Select the appropriate settings for the filter dialog and then select OK to open either the Open from Database or your operating system file dialog.

3	Select a display from the resulting list.

4	Accept the dialog to close it and run the selected display.

5	The display is opened in the Graphics Builder Debugger Main Layout window, which simulates runtime execution of your display.

6	Choose File [image] Close to close the debugger when you are done.


Printing displays

To print a display:

1	Choose File [image] Print to display your system's print dialog box.

2	Specify the appropriate print options for your system.

3	Accept the dialog box to begin printing.

If your display contains multiple layers, only the layers showing are printed.


Setting up pages for printing

To setup pages for printing:

1	Choose File [image] Print Setup to display your system's print setup dialog.

2	Specify the print settings for your system.

3	Accept the dialog box.

The settings remain in effect for the current Builder session.


About chaining displays

You can open one display from another using the PL/SQL built-in procedure OG_OPEN_DISPLAY.  You can either open a second display and keep the original display open, or close the original display.

If you decide to open a new display and close the original one, you must be sure that the OG_CLOSE_DISPLAY subprogram is last in the stack.  This is to ensure that all other subprograms have run before the close display subprogram is called.  Any subprograms listed after the OG_CLOSE_DISPLAY subprogram will not be called.  Upon the OG_CLOSE_DISPLAY subprogram, the Close Display trigger, if any, is executed.

For example:

PROCEDURE next_display IS
  next_disp  OG_DISPLAY;
  old_disp   OG_DISPLAY;
BEGIN
  next_display:=OG_OPEN_DISPLAY('more.ogd', OG_FILESYSTEM);
  old_disp:=OG_GET_DISPLAY('plan.ogd');
  OG_CLOSE_DISPLAY(old_disp);
END;


About creating packages

  Related Topics

A package is a collection of related PL/SQL procedures, functions, datatypes, variables, and other constructs that is stored as a database object.  Displays can share global variables stored in a package as long as all displays involved maintain the same database connection.  Once a display disconnects, the package state is reset.

To ensure that your displays maintain the same database connection, use the OPEN_DISPLAY PL/SQL built-in procedure to open one display from another.

The package you create should contain both the variable definitions, and subprograms to manipulate the variables (i.e., procedures to set the variable value, and functions to retrieve the variable value).  You can reference the variable and the associated subprograms in any display that shares the database connection.

The following example shows a package specification and body that contains a global variable bar and two subprograms:

PACKAGE foo IS
  bar  VARCHAR2;
  PROCEDURE set_bar (txt VARCHAR2);
  FUNCTION get_bar return VARCHAR2;
 END;

PACKAGE BODY foo IS
  PROCEDURE set_bar (txt VARCHAR2) IS
    BEGIN
      foo.bar:=txt;
    END;

  FUNCTION get_bar RETURN VARCHAR2 IS
    BEGIN
      return foo.bar;
    END;
END;

Once you have created the package, you can reference the global variable and manipulate its value between displays by using the stored subprograms.  For example:

PROCEDURE set_param IS
BEGIN
/*assign the local parameter 'param' to the value of the
global variable bar*/

  :param:=foo.get_bar;

/*change the value of bar for the next time it is
referenced*/

  foo.set_bar('object1');
END;

For more information about creating PL/SQL packages, see the PL/SQL User's Guide and Reference.


About windows

In Graphics Builder, windows can function in two different ways:  as work areas and as display areas .

In the Builder, windows are rectangular work areas that contain Graphics Builder interface elements such as editors, tables, and browsers.  You can open multiple windows, but only one window can be active at a time.

The default window configuration defines the position and number of windows that appear when you open a display.  By default, the Layout Editor window is the only one opened.  However, you can set up a different window configuration and save it as the new default using the Preferences dialog box.

You can also create windows programmatically to present objects in different areas of the layout at runtime.  By default, a display's objects appear in the Main Layout window.  Using PL/SQL, you can create additional windows in which to present objects.  You can also define a window's size and position and when it should open or close.


About controlling window visibility

You can further manage the windows used in your Runtime application as follows:

hide	Use this option to temporarily hide a window that you may wish to show again at a later time.
show	Use this option to reveal a window that was previously hidden.
destroy	Use this option to close a window that you no longer need.  This might be a window that has been opened from an existing display.
Note: You cannot destroy the default 'Main Layout' window.  If you wish to destroy a default Main Layout window, use OG_CLOSE_DISPLAY, otherwise, use OG_HIDE_WINDOW.


About using layers with windows

If your display contains multiple layers, you can activate, hide, and show an existing layer among separate windows.  This has the same affect as opening another display.  Each layer can presented in a separate window, allowing the user to see multiple layers of a single display.

You can manipulate layers among multiple windows using the PL/SQL built-in procedures OG_ACTIVATE_LAYER, OG_HIDE_LAYER, and OG_SHOW_LAYER.  Each of these procedures has an optional window handle argument.  If you do not specify a specific window handle for the procedure, Graphics Builder performs the specified action on each window the layer is included in.

Users can only interact with the active layer window.  Remember that you cannot hide the active layer.  You must first activate a new layer, and then hide the old one.

The following example shows a program unit that activates a second layer of the display to a new window:

PROCEDURE activate_layer IS
  new_layer   OG_LAYER;
  old_layer   OG_LAYER;
  new_window  OG_WINDOW;
BEGIN
  new_layer:=OG_GET_LAYER('layer1');
  old_layer:=OG_GET_LAYER('layer0');
  new_window:=OG_GET_WINDOW('Details');
  OG_ACTIVATE_LAYER(new_layer, new_window);
END;


Using database pipes

To use database pipes:

1	Use the PACK_MESSAGE procedure to add information to the local message buffer.

2	Use the SEND_MESSAGE procedure to designate a pipe through which to send the information in the message buffer.

3	Use the RECIEVE_MESSAGE procedure to receive the message on the named pipe.

4	Use the UNPACK _MESSAGE procedure to access the information in the buffer.

The following procedure packs a variable value to a message buffer and then sends the buffer to the server using a pipe named `the_pipe'.

PROCEDURE pass_var (my_var NUMBER) IS
 stat  NUMBER;
BEGIN
  DBMS_PIPE.PACK_MESSAGE(my_var);
  stat:=DBMS_PIPE.SEND_MESSAGE('the_pipe', 30, 8192);
END;

Note: Graphics Builder does not currently recognize default values for arguments in the specs of stored subprograms.  Thus, while DBMS_PIPE.SEND_MESSAGE supplied default values for its TIMEOUT and MAXPIPESIZE arguments, you must provide explicit values.

The following procedure can be executed from a second display that shares the same database connection.

PROCEDURE get_var IS
  my_var  NUMBER;
  stat    NUMBER;
BEGIN
/*Receive the pipe from the server */
  stat:=DBMS_PIPE.RECEIVE_MESSAGE('the_pipe', 30);
/*Unpack the information in the pipe and store in my_var*/
  DBMS_PIPE.UNPACK_MESSAGE(my_var);
/*Use the variable value to perform some action*/
  use_variable(my_var);
END;

For more information about the DBMS_PIPE package, see the Oracle7 Server Application Developer's Guide.


Creating new windows

To create a new window:

  Use the PL/SQL built-in function OG_MAKE_WINDOW to create a new window.  Using this function, you can create multiple windows for a runtime display.  This enables you to show different layers of a display in different windows, or chain displays together by opening one from another.

For example:

PROCEDURE make_win IS
  nu_win   OG_WINDOW;
  win_pos  OG_INCH;
  win_wid  NUMBER;
  win_ht   NUMBER;
BEGIN
  win_pos.x:=0*OG_INCH;
  win_pos.y:=0*OG_INCH;
  win_wid:=7*OG_APP.VSCREEN_RES;
  win_ht:=6*OG_APP.HSCREEN_RES;

  nu_win:=OG_MAKE_WINDOW(win_pos, win_wid, win_ht);
  OG_SET_NAME(nu_win, 'Detail Chart');
END;


Hiding window scrollbars

To hide window scrollbars:

  Use the PL/SQL built-in attribute record OG_SCROLLBARS_WINDOWA.

For example:

PROCEDURE make_window IS
  the_window  OG_WINDOW;
  windo_attr  OG_WINDOW_ATTR;
BEGIN
  windo_attr.name:='Inventory';
  windo_attr.scrollbars:=FALSE;
  windo_attr.width:=4*OG_APP.HSCREEN_RES;
  windo_attr.height:=5*OG_APP.VSCREEN.RES;
  windo_attr.mask:=OG_NAME_WINDOWA+
OG_SCROLLBARS_WINDOWA+
OG_SIZE_WINDOWA;
  the_window:=OG_MAKE(windo_attr);
END;

You cannot change the attribute records for an existing window.  If you wish to hide the scrollbars for an existing window, you must hide or destroy that window and create a new window.  Note that you cannot destroy the original default window named 'Main Layout.'

If you wish to hide scrollbars in the initial window of your runtime display, you should create an Open Display trigger that creates a new window without scrollbars, and hides the 'Main Layout' window.


Hiding windows

To hide a window:

  Use the PL/SQL built-in OG_HIDE_WINDOW.  Using this, you can temporarily hide a window from users, and show it again later.

The following example shows a button procedure that is activated when a user selects a chart element:

PROCEDURE OGBUTTONPROC0 (buttonobj IN og_object, hitobj IN og_object, win IN og_window, eveninfo IN og_event) IS
  curr_window  OG_WINDOW;
BEGIN
  curr_window:=OG_GET_WINDOW('Main Layout');
  OG_HIDE_WINDOW('Main Layout');
END;


Showing windows

To show a window:

  Use the PL/SQL built-in procedure OG_SHOW_WINDOW.

For example:

PROCEDURE show_window IS
  back_window  OG_WINDOW;
BEGIN
  back_window:=OG_GET_WINDOW('Details');
  OG_SHOW_WINDOW(back_window);
END;


Destroying windows

To destroy windows:

  Use the OG_DESTROY PL/SQL built-in.  This enables you to any window that you created with OG_MAKE_WINDOW or OG_MAKE(Window)  OG_DESTROY closes the window without affecting its contents.

To close all windows associated with a display, use the OG_CLOSE_DISPLAY PL/SQL built-in procedure.

Note: You cannot destroy a default 'Main Layout' window.

The following procedure destroys a window:

PROCEDURE close_window (the_window IN og_window) IS
BEGIN
  OG_DESTROY(the_window);
END;


About chart templates

A chart template defines the format of a chart and its various properties.  A chart can be associated with only one chart template at a time.  However, you can perform the following actions on an individual chart template and then use that template to apply the properties to multiple charts.

•	Specify axis frame properties

•	Specify discrete, continuous, and date axis properties

•	Move the legend

•	Define reference lines

•	Specify number and date formats

•	Specify text and line properties

•	Specify colors and patterns

Each chart template can be associated with one or more field templates, which define the properties of the individual fields, such as bars, columns, pie slices, or lines.

Graphics Builder provides a set of 56 default chart templates divided into 10 categories, including bar, line, and pie.  When you create a chart of a specific type and sub-type, Graphics Builder makes a copy of the default chart template associated with that type.  You can customize this copy, but you cannot modify the default chart templates themselves.

When Graphics Builder copies the template for your use, it is assigned the name templatex, where x is a number that is incremented each time you create a new chart template for the current display.  Once you have customized a chart template, you can assign it to multiple charts by selecting it from the Templates drop-down list in the Chart property sheet during char creation.

To customize chart templates, use the Chart Template editor.


About chart template components

Chart template components are divided into two main categories:

•	Chart frames

•	Field templates


About chart frames

Chart frames include components that make up the basic structure of the chart, such as its axis label, fonts, and legend position.  A chart template can have only one chart frame.

When you first select a chart template, the chart frame is what appears in the Chart Template editor by default.


About field templates

Field templates include components that determine how value (dependent) data are represented as chart fields, such as bars or lines.  A chart template has at least one default field template, but you can create additional ones to associate with different chart values (query columns).

You can view a field template when the chart frame is showing in the Chart Template editor by choosing the Field template radio button at the top of the editor.


About chart template properties

Chart template properties define the appearance and behavior of chart frame and field template components.  The properties that apply and how you define them vary depending on the type of chart template.  In general, you define chart template properties in the Chart Template editor by selecting a component, opening its property sheet or Format menu, and choosing options for it.


About the Chart Template editor

Each display contains only one Chart Template editor.  Although you can define many chart templates in a single display, you can view or modify only one at a time in the Chart Template editor.

Note that the Chart Template editor, like the Layout editor, allows you to set multiple views by dragging the split bars in the lower right corner.  This allows you to show a chart template in one view and its field templates in another.

The Chart Template editor has the following components:

frame editor

field template editor

tool palette


About the Frame editor

The frame editor is where you select and modify elements of the chart's frame .    The frame determines the basic structure of the chart, and has little to do with the data that will be plotted.  The appearance of the frame in the editor represents how the chart will appear when it is created.  You can change the font, color, and other graphical properties of frame elements, and see the results immediately.  You can also move the legend (if any) by dragging the legend's box (not the text) to a new location.


About the Field Template editor

The field template editor is where you select and modify elements of the chart's field templates.  A field template determines how a set of data will appear in the chart.  When you create a chart, you must associate columns from the query with specific field templates.  The graphical properties of the field templates determine how the data will be plotted in the chart.


About the Chart Template tool palette

The Tool palette in the Chart Template editor contains a select tool as well as the Line/Fill/Text Display indicator, Line Color palette, Fill Color palette (and Pattern palette), Text Color palette, and Symbol palettes.


About selecting a chart template

If you select Tools [image] Templates from the menu without first selecting a chart, the Chart Template editor appears with the current chart template.  The current chart template is the one that was last selected in the Chart Template editor. You can select a different default or customized chart template to be the "current" chart template.


About customizing chart templates

  Related Topics

Before you edit the chart frame of the current chart template, make sure it's showing in the Chart Template editor so that you can verify the changes you make:

  In the Chart Template editor, select the Frame radio button to show the chart frame.

You customize a chart template's frame and axis properties the same way you customize a chart's frame and axis properties.

Where the sections below reference menu options and tools, use the menu options and tools within the Chart Template editor.

In addition to customizing the template's frame and axis properties, you can customize one or more field templates for use with the chart template.


About administering exported chart templates

Once you have created and customized a chart template, you can the Object Navigator or the Chart Template editor to export it to the file system or to the database for use in other displays.

You can import a previously exported chart template from the Object Navigator, or the Chart Template editor.


Creating a chart template

To create a chart template:

1	In the Object Navigator, select the Templates node, then select the Create button in the toolbar.

2	Accept the default chart type (column) or choose an alternate chart type and subtype from the Type menu.

3	Accept the default chart template name (templatex) or edit the name by choosing Template [image] Rename to show the Rename Template dialog.

4	Customize the chart's frame and axis properties as desired.

5	Choose File [image] Close to close the Chart Template editor when you are done.

You can create a customized chart template prior to creating any charts.  Once you've created (and customized) a chart template, you can assign it to charts in the Chart property sheet by selecting the template name from the Template drop-down list.

In addition, you can export a chart template to the file system or the database so you can use it in other displays.


Selecting a default chart template

To select a default chart template:

1	Choose Tools [image] Templates to display the Chart Template editor.

2	Select the type of chart you want (such as Pie), from the Type menu.

3	Choose one of the chart templates shown on the submenu for that type of chart.

The chart frame for the default chart template you selected appears in the Chart Template editor.  This remains the current chart template until you create or edit another one.

4	Close the Chart Template editor by choosing File [image] Close.

This chart type is now the current chart template.  When you select Tools [image] Templates from the menu, this chart template will be shown in the Chart Template editor.


Selecting a customized chart template

To select a customized chart template:

1	Choose Tools [image] Templates to show the Chart Template editor.

2	In the Chart Template editor, select the Template pop-list to show a list of customized templates.

3	Choose one of the chart templates listed to show it in the Chart Template editor.

This remains the current chart template until you create or edit another one.

4	Close the Chart Template editor by choosing File [image] Close.

This chart type is now the current chart template.  When you select Tools [image] Templates from the menu, this chart template will be shown in the Chart Template editor.


Importing a chart template

To import a chart template:

1	Select the Templates node in the Object Navigator, or choose Tools [image] Templates to show the Chart Template editor.

2	Choose Edit [image] Import [image] Template to show the Import dialog.

3	Select the file/module name and location.

4	Select OK to import the specified chart template into the current display.


Exporting a chart template

To export a chart template:

1	Select the template object in the Navigator, or select the chart template you wish to export from the Templates drop-down list in the Chart Template editor.

2	Choose Edit [image] Export [image] Template to show the Export dialog.

3	Select the export options such as location and file/module name.

4	Select OK to export the template and close the export dialog.


Renaming a chart template

To rename a chart template in the Object Navigator:

1	Select the chart template object you wish to rename.

2	Move the mouse pointer over the chart template name.

The cursor changes from a pointer to a text editor.

3	Select the name once to position the cursor and enter edit mode.

If you wish to replace the entire name, select the name to highlight it, then type the new name.

To rename a chart template in the Chart Template editor:

1	Select the chart template you wish to rename from the Template drop-down list.

The chart template appears in the editor layout.

2	Choose Template [image] Rename to show the Rename Template dialog.

3	Type the new template name in the Template Name field.

4	Select OK to apply the new name and close the dialog.

Note:  If you rename a chart template that you have referenced in any PL/SQL program units, you must change those references to reflect the new name.


Deleting a chart template

To delete a chart template from the Object Navigator:

1	Select the chart template object in the Navigator.

2	Select the Delete button, or choose Navigator [image] Delete from the menu.

3	In the alert, select Yes to confirm.

To delete a chart template from the Chart Template editor:

1	Select the chart template you wish to delete from the Template drop-down list.

2	Choose Template [image] Delete.

An alert appears, prompting you to confirm the deletion.

3	Select Yes to confirm.

Note:  If you delete a chart template that you have referenced in any PL/SQL program units, you must change those references to reflect the deletion.


About creating, modifying, and assigning field templates

You can create multiple field templates for a chart template if you want to assign different properties to value column fields.  Each field template can be assigned to a different value column field, assigned to multiple value column fields, or remain unused until you need it.   Field properties include options such as plot type, line style, and label rotation, depending on the chart type.

Once you have created a field template and customized it, you can assign it to a value column in the chart.


About applying colors and patterns to field templates

The procedures for applying colors and patterns to field templates are the same as those for objects; however, you use the color palettes in the Chart Template editor instead of the color palettes in the Layout Editor.  The color palettes behave the same way.


Adding a field template

To add a field template:

1	Choose Field Templates from the pop-up menu, or choose Templates [image] Field Templates to show the Field Template property sheet.

2	Select New to create a new field template, initially named ftempx.

You can rename the new field template or keep the default.

3	Choose the Axis Field tab to set properties for axis chart field templates.

4	Select OK to apply the new field template and close the Field Templates dialog.

To see a field template appear in your chart, you must associate it with a value column.


Editing a field template

To edit a field template:

1	Before you edit a field template for the current chart template, make sure it's showing in the Chart Template editor so that you can verify the changes you make.

2	From the Chart Template editor, select the Field template radio button to show the current field template.

3	Select the field template you wish to edit from the drop-down list.


Specifying a properties for field template
Specifying properties for a field template

To specify properties for a field template:

1	Select the chart or a single chart object.

2	Choose the Field Templates command from the pop-up menu, or choose Chart [image] Field Templates to show the Field Template property sheet.

3	Choose the Axis Field tab to show the Axis Field property page.

4	Specify the desired options.

5	Select OK to apply the changes to the field template and close the Field Template’s property sheet.


Assigning a field template

To assign a field template:

1	Select the chart in the Layout Editor or Object Navigator.

2	Choose Properties from the pop-up menu, or choose Tools [image] Properties to show the Chart's property sheet.

3	Choose the Value tab to show the chart's Value property page.

4	From the Chart Values list, select the value column you wish to assign a field template to.

5	Select the field template from the Field Templates drop-down list.

6	Select OK to apply your changes and close the Chart property sheet.


Deleting a field template

To delete a field template:

1	Select the chart or a single chart object.

2	Choose the Field Templates command from the pop-up menu, or choose Chart [image] Field Templates to show the Field Template property sheet.

3	Select the field template you want to delete from the Field Template drop-down list.

4	Select Delete.

An alert appears, prompting you to confirm the deletion.

5	Select Yes to confirm.

6	Select OK to accept the changes and close the Field Template property sheet.

If you've created a chart that contains a value column associated with the deleted field template, you must associate the value column with another field template before deleting it.


About PL/SQL

PL/SQL is a procedural extension of SQL that provides programming constructs such as loops, conditionals, and procedures.  Using PL/SQL in Graphics Builder allows you greater control over the way your displays operate, making them more responsive to current data, end-user actions, and other conditions present at runtime.  You might use PL/SQL in your displays to do the following:

•	Create and manipulate objects.  For example, animate an object so that it appears to move across the layout.

•	Control the order in which operations flow.  For example, cause a specified layer to appear if a user selects an object.

•	Control the timing of operations.  For example, cause an action to trigger at timed intervals.

•	Cause operations to occur conditionally.  For example, calculate current data values and show different objects, depending on the results.

•	Define and interpret end-user actions.  For example, display an error message if a user types an invalid statement.


About same name resolution

If you make references to PL/SQL constructs with duplicate names, Graphics Builder will search for them in the following order:

1	Among the following, there is no pre-defined order:

•	local program units saved with a display

•	PL/SQL STANDARD built-ins

•	Graphics Builder built-ins

2	Attached libraries

3	Stored subprograms


About specifying coordinate and size information

Many of the built-in constructs provided refer to, or require you to provide, numeric values that specify a position on the layout, or dimensions of an object.  The unit of measurement that you must use for these values is called a layout unit.

Layout units are used to provide a consistent measurement system for Graphics Builder applications that may be run on several display devices, each with a different display resolution.  For example, 1 inch on a device with a screen resolution of 72 lines/inch is different than on a device with a screen resolution of 90 lines/inch.  In contrast, the Graphics Builder layout resolution is the same on all systems.  By specifying all of your measurements in layout units, you can be sure that they remain consistent across all devices.

OG_INCH Built-in Global

Graphics Builder provides a global variable called OG_INCH that is equal to the number of layout units in one inch.

For example, to define a rectangular region that is three inches high and two inches wide, you could declare a local variable:

   my_rect   OG_RECTANGLE;

Then you could use the OG_INCH global variable, as in the following statements:

   my_rect.height := 3 * OG_INCH;
   my_rect.width := 2 * OG_INCH;

We recommend that you do not determine and use the literal value this global variable in your applications.  To ensure that your display works properly in the current and future version of Graphics Builder, it is best for you to use the supported built-in global variable.


About referencing Graphics Builder objects using object handles

Many built-in subprograms allow you to perform operations on Graphics Builder objects.  For example, the OG_EXECUTE_QUERY procedure allows you to execute a query.  These subprograms require that you specify which object you want to manipulate.

Instead of referring to an object by its name, many built-in procedures, functions, and datatypes require that a handle (i.e., pointer) to the object be used.  For example, to execute a query, you must pass the query's handle to OG_EXECUTE_QUERY:

PROCEDURE getdata IS
  query_handle  OG_QUERY;
BEGIN
  query_handle := OG_GET_QUERY('query0');
  OG_EXECUTE_QUERY(query_handle);
END;

Getting Object Handles

Graphics Builder provides a set of built-in functions that you use to obtain an object's handle.  Each of these functions returns a value of a specific datatype, depending on the type of object whose handle it retrieves.

The following table lists the Graphics Builder objects whose handles you can get, the functions used to get them, and the datatype of the return value:

Object Type	Function	Return Datatype

Axis	OG_GET_AXIS	OG_AXIS
Button Procedure	OG_GET_BUTTONPROC	OG_BUTTONPROC
Chart Template	OG_GET_TEMPLATE	OG_TEMPLATE
Display	OG_GET_DISPLAY	OG_DISPLAY
Field Template	OG_GET_FTEMP	OG_FTEMP
Graphic Object	OG_GET_OBJECT	OG_OBJECT
Layer	OG_GET_LAYER	OG_LAYER
Query	OG_GET_QUERY	OG_QUERY
Reference Line	OG_GET_REFLINE	OG_REFLINE
Sound	OG_GET_SOUND	OG_SOUND
Timer	OG_GET_TIMER	OG_TIMER
Window	OG_GET_WINDOW	OG_WINDOW
Why Use Handles?

Handles are used instead of names to improve efficiency.  Each time you refer to an item by name, Graphics Builder must search through all of the existing items of that type to find the one whose name matches the one you specified.  This approach requires a lot of time, and is used by the functions listed above to find the named item.  However, once the item is found, a handle is created that points directly to that item.  By using the handle, Graphics Builder avoids having to search for the item's name each time you reference it.

The best way to "store" handles is through the use of variables.  You declare any variables you will used at the beginning of your program unit by giving them a name and a datatype.

You can then assign the variable to the value that the function returns.  Using the example above, the variable "query_handle" is declared as having the OG_QUERY built-in datatype.  This is the datatype returned by the function OG_GET_QUERY.

The first line of the procedure assigns the query_handle variable to the value returned by the OG_GET_QUERY function.  You can now use the variable query_handle anywhere within the program unit that requires the object handle for the query that is currently stored in the variable.


About program units

Program units are code structures you can create using PL/SQL.  You can use Graphics Builder to write PL/SQL program units, or you can use your own editor and import or export program units.

There are two types of PL/SQL program units that you can use in Graphics Builder:

•	subprograms

•	packages

After using the Object Navigator to create or access a program unit, you can edit it using the PL/SQL Program Unit editor.  You use the editor to write and debug your code.

For more information about using the editor, see "Using the Program Unit Editor" in the " Working with PL/SQL Constructs" chapter of the Procedure Builder Developer's Guide.


About subprograms

Subprograms are PL/SQL procedures and functions you can create in Graphics Builder.

A procedure is executed to perform a specified sequence of actions.  For example, a procedure might update a chart based on new data.  The following are two special types of Graphics Builder procedures you can create:

Button Procedure	A procedure associated with an object or layer that is executed when a specific mouse event occurs at runtime:  mouse button up/down, or mouse move with button up/down.
Trigger Procedure	A procedure that is executed when a trigger is fired.  Possible triggers are: the display is opened, the display is closed, a timed interval has passed, a query is executed.
A function is executed to perform a specified sequence of actions and then return a value.  For example, a function might calculate and return the sales tax to be charged for an item.  A special type of Graphics Builder function you can create is a query filter function, which filters data returned by a query and only charts those values that meet a specified condition.


About packages

A package groups logically related PL/SQL procedures, functions, datatypes, variables, constants, exceptions, cursors, and other constructs.  Constructs defined in a package are commonly referred to as "packaged," such as packaged functions and packaged procedures.  When you reference a packaged PL/SQL construct, you must precede each appearance of the construct name with the package name followed by a period (.).


About loading program units into displays

You may wish to load individual program units into a display rather than attaching the PL/SQL library a program unit is stored in.  There are no performance benefits to loading individual program units over attaching libraries.

Use the following criteria to determine whether you should load individual program units instead of attaching libraries:

•	Your libraries are very large and you may run into size limitations.

•	Moving your display would require you to change all pathnames that point to the library.

•	Your display only requires a few program units and it's easier to maintain without the attached library.


About PL/SQL built-ins

  Related Topics

Graphics Builder provides extensions to the PL/SQL language that are used specifically for customizing the behavior of Graphics Builder applications.  These constructs, called built-ins, are implemented as extensions to the STANDARD PL/SQL package.

Graphics Builder provides the following types of built-in constructs:

•	datatypes

•	global variables

•	subprograms

•	exceptions

Because the Graphics Builder built-ins have been designed to give you programmatic control over specific features and functionality, they may be used only when defining Graphics Builder displays.

You can use any PL/SQL built-ins within your own program units, but you cannot edit the built-ins themselves.


About exceptions

To trap or isolate the success or failure of PL/SQL program units, you can use exceptions.  For example, you may want to display an error if a user performs an invalid action at runtime.  There are two types of exceptions:

user-defined exceptions	In Graphics Builder, you can declare, raise, and handle your own exceptions.  For more information about exceptions, see the PL/SQL User's Guide and Reference.
pre-defined exceptions	Many exceptions have been pre-defined for use within Graphics Builder.  To take action on a pre-defined exception, you need to write an exception handler for it.  Exception handlers define statements that are executed when certain conditions or exceptions are raised in a PL/SQL program unit.  When an exception is raised, the normal execution is stopped and control is passed to the appropriate exception handler.


About creating program units

To build program units:

1	Determine what Graphics Builder built-in procedures you need to use to perform an action.

2	Examine the procedures to determine what arguments they require.

You can supply arguments to procedures in the form of handles returned by functions, arguments supplied to the program unit you are defining, or absolute values, depending on the procedure definition.

3	Determine what Graphics Builder built-in functions you need (if any) to retrieve the required arguments.

4	Determine what variables you will need to define to store values returned by the functions.


Creating program units

  Example

To create program units:

1	Select the Program Units node in the Object Navigator.

2	Select the Create button or Navigator [image] Create to show the New Program Unit dialog.

If no program units currently exist, double-click on the Program Units node to create a new program unit.

3	Select the type of program unit you wish to create, enter a name for the program unit, and select OK.

The PL/SQL Program Unit editor appears with your program unit name in the Name field.

4	Define your program unit.

5	Select Compile to compile the program unit.

6	Resolve any errors that may have been encountered.

Your program unit must be error-free before it can be successfully compiled and used in your display.

7	Select Close to close the Program Unit editor when you are finished.


Example: Creating a program unit

Since you want to create a program unit that activates a layer in the display, you’ll use the Graphics Builder PL/SQL built-in procedure OG_ACTIVATE_LAYER.  This procedure requires an argument of the Graphics Builder built-in datatype OG_LAYER.  To get this datatype value, you’ll use the function OG_GET_LAYER, and will declare a variable of the datatype OG_LAYER to store the value returned by OG_GET_LAYER.

Working backwards from the above steps, you’d create the following procedure:

PROCEDURE act_layer IS
/*Declare the variable to store the function return */
  the_layer  OG_LAYER;
BEGIN
/*Use the function to assign the variable's value */
  the_layer:=OG_GET_LAYER('layer1');
/*Use the variable value as an argument to the procedure */
  OG_ACTIVATE_LAYER(the_layer);
END;


Editing program units

To edit a PL/SQL program unit:

  Double-click on the program unit object you wish to edit, or select the program unit and choose Properties from the pop-up menu.  The Program Unit editor appears, containing the source of the program unit.

You can edit the program unit as needed.  If you edit a compiled program unit, you must recompile after making changes.


Compiling individual program units

To compile individual program units:

1	Double-click on the program unit in the Object Navigator to open the Program Unit editor.

Alternatively, you can choose Tools [image] Program Units to show the Program Unit editor and then choose the program unit from the Name drop-down list.

The Program Unit status bar reports whether the program unit has been successfully compiled.

2	Select Compile to compile the program unit.

If any errors are encountered, they are reported in the Program Unit editor beneath the program unit body.  You can double-click on an error to navigate to its source in the program unit body.

For more information about compiling program units, see the chapter "Working with PL/SQL Constructs" in the Oracle Procedure Builder Developer's Guide.


Batch compiling program units

To batch compile program units:

1	Choose File [image] Compile to batch compile any uncompiled program units in the display, or choose File [image] Compile All to (re)compile every program unit in the display.  The Compile All command forces the recompilation of already compiled program units.

The Compile dialog appears, providing a progress indicator and a scrollable field where any compilation errors encountered are recorded.

2	You can choose from the following buttons to interact with the compilation:

•	Interrupt	Temporarily stops the compilation.

•	Resume	Resumes batch compilation after an Interrupt operation.

•	OK	Accepts and closes the Compile dialog.

•	Cancel	Cancels the batch compilation.

•	Go To Error	Locates the selected compilation error and opens the associated program unit at the location of the error.

3	When you're finished, select OK to close the Compile dialog.


Recompiling program units

Compiled PL/SQL code is not portable among different systems.  Therefore, to prepare a display for use on a different system, you need to recompile your source code on that system.

  Choose File- [image] Compile All to (re)compile every program unit in the display.


Renaming program units

  Related Topics

To rename a program unit:

1	Double-click on the program unit object to show the Program Unit editor.

2	Edit the program unit to change the name.

3	Recompile the program unit.

If you change the name of a program unit that is referenced in other program units, you need to edit those references to reflect the new name.  Once you recompile the renamed program unit, other program units that reference it will lose their compiled status and will appear in the Object Navigator with an asterisk (*).


Loading program units into displays

To load a program unit into a display:

  Select and drag the library program unit below the Program Units node of the display.

When you release the mouse button, the program unit is automatically copied into the display.  If a program unit of the same name and type already exists in the display, an alert prompts  you to confirm that the program unit be overwritten.


Deleting PL/SQL program units

  Related Topics

To delete a program unit from the Object Navigator:

  Select the program unit object and select the Delete button or choose Navigator [image] Delete.  Select Yes to confirm.

To delete a program unit from the Program Unit editor:

1	Double-click on the program unit object, or choose Program Units from the pop-up menu, or choose Tools [image] Program Unit Editor to show the Program Unit editor.

2	If necessary, select the program unit you wish to delete from the Name drop-down list.

3	Select Delete to delete the program unit.

An alert appears, prompting you to confirm the deletion.

4	Select Yes to confirm.

5	Select Close to close the Program Unit editor.

If you delete a program unit that is referenced by other program units, you must remove those references and recompile the program units to reflect the change.


Checking consistency

To check consistency:

1	Choose File-->Check Consistency to show the Consistency Checker dialog.

Graphics Builder looks for inconsistencies and reports them in the message display field.

2	When you're finished, select OK to close the Consistency Checker dialog.

If you've used PL/SQL in your display, you may want to verify that there are no inconsistencies between program units and references to those program units.  An example of an inconsistency would be if you referenced a trigger procedure but failed to create it.


About libraries

PL/SQL libraries are a useful way to store commonly used PL/SQL program units for future use.

They consist of collections of PL/SQL program units that you can create in Graphics Builder.  Unlike individual program units that you can store with displays, PL/SQL libraries are stored in the database or file system and can be used by multiple users in multiple displays.  To reference PL/SQL libraries in Graphics Builder, you need to attach them to your displays, using the Object Navigator.  In addition, you can grant access to libraries you have created so others can use them.

You can reference PL/SQL libraries multiple times within a single display or share them with other modules in an application.

For more information about working with PL/SQL libraries, see "Using PL/SQL Libraries" in the "Working with PL/SQL Constructs" chapter of the Procedure Builder Developer's Guide.


About granting and revoking access to libraries

You can grant and revoke access to PL/SQL libraries if you created the library or were granted access to it.  Granting access to other users allows them to grant access to other users, rename, and modify the PL/SQL library.


Creating libraries

To create a PL/SQL library:

1	Select the Libraries node in the Object Navigator.

2	Select the Create button or Navigator [image] Create.

A new open library, initially named LIB_xxx, is created.

3	If no libraries are currently open, you can double-click on the Libraries node in the Navigator to create a new library.

Now that you've created a library, you can add existing or create new program units to store in it.


Opening libraries

To open a library:

1	Select File [image] Open to show the Filter dialog.

2	Select Libraries or All Files from the Display field.

3	Select either the Database or File System radio button in the Object Access field according to where the library is stored.

4	Select OK to confirm your selections.

If your library is stored on the file system, your system file dialog appears.  If your library is stored in the database, the Open from Database dialog appears.

5	Specify the name of the library you wish to open and accept the dialog to open the library.

Libraries use the .pll file extension to distinguish them from other files.


Adding existing program units to open libraries

To add an existing program unit to an open library:

1	In the Object Navigator, expand the subnodes of the open library you wish to modify.

2	Select the program unit you wish to add from the Displays node.

3	Select and drag the program unit's icon below the Program Units subnode of the open library.

When you release the mouse button, the program unit is automatically copied into the open library.  If a program unit of the same name and type already exists in the library, an alert prompts you to confirm that the original program unit be overwritten.


Creating new program units in an open library

To create a new program unit in an open library:

1	Select the Program Units subnode beneath the open library node in the Object Navigator.

2	Select the Create button, or choose Navigator [image] Create to show the New Program Unit dialog.

If no program units currently exist in the library, double-click on the Program Units subnode in the Navigator to show the New Program Unit dialog.

3	Type a name for the new program unit.

4	Select a type for the new program unit.

5	Select OK to accept the New Program Unit dialog and show the Program Unit editor.

6	Define the new program unit.

7	Select Compile to compile the new program unit.

8	Select Close to close the Program Unit editor.

Your new program unit appears below the Program Units subnode of the library.


Deleting program units from an open library

To delete a program unit from an open library:

1	Expand the subnodes of the open library you wish to modify.

2	Select the program unit you wish to delete from the library.

3	Select the Delete button or choose Navigator [image] Delete.

An alert appears, prompting you to confirm the deletion.

4	Select Yes to confirm.


Saving libraries

To save a library:

1	Select the open library you wish to save.

2	Select Save, or choose File [image] Save or File [image] Save As to show  the Save Library dialog.

Use the Save As command only if this is the first time you are saving the library.

3	Specify a name for the library and whether to save the library in the file system or the database.

4	Select OK to save the library.

Libraries are automatically assigned the file extension .pll if saved on the file system.


Attaching libraries to displays

To attach a library to a display:

1	In the Object Navigator, select the Attached Libraries node (within the display node).

2	Select the Create button or choose Navigator [image] Create to show the Attach Library dialog.

If no libraries are currently attached, double-click on the Attached Libraries node in the Navigator to show the Attach Library dialog.

3	Enter the name of the library you wish to attach.

4	Select Attach to attach the library.

If you supply a pathname with the library (i.e., the library is not stored in your current or working directory), you will be prompted to strip the pathname.  If you decide not to strip the pathname, Graphics Builder will look for the library only in the specified pathname.  If you decide to distribute your display, Graphics Builder may not be able to find the library.

If you decide to strip the pathname, Graphics Builder will search for the library in the following search path:

•	the user's current or working directory

•	the directory specified by the Graphics Builder path environment variable

•	the directory specified by the Oracle path environment variable

You can attach a specific library to a display to use the contents of that library in the display.  By attaching the library to the display, you ensure that the library and its contents will accompany the (runtime) display.  The attached library is not static, that is, it is not a "snapshot" of the library at the time you attached it.  Rather, the attached library is a link to the library and receives all updates you make to the library.

You cannot attach open libraries.  If the library you wish to attach is currently open, close it and then attach it.  You can attach multiple libraries to a display.


Detaching libraries from displays

 To detach a library from a display:

1	Select the library you wish to detach under the Attached Libraries node in the Object Navigator.

2	Select the Delete button or choose Navigator [image] Delete.

An alert appears, prompting you to confirm the detachment.

3	Select OK to detach the library.


Granting and revoking access to libraries in the file system

To grant and revoke access to libraries in the file system:

  Some operating systems permit users to grant read, write, and execute permissions on individual files.  For more information about how to set file permissions on your operating system, see your operating system documentation or check with your system administrator.


Granting and revoking access to libraries in the database

To grant and revoke access to a library in the database:

1	Choose File [image] Administration [image] Access [image] Library to show the Module Access in Database dialog box.

This dialog contains a list of all libraries stored in the database that you have access to.

2	Select a library from the list.

3	Select OK to show the Module Access dialog.

This dialog contains a list of users who have access to the library.

4	To grant access, type the database username of the person to whom you want to grant access in the User field.

5	Select Add to add the username to the Access list.

6	To revoke access from a user in the Access list, select the username in the list.

7	Select Remove to remove the username from the Access list.

8	Select OK to accept your changes and close the Module Access dialog.

Access privileges are updated for your library.  You can grant another user access (read/write/execute privileges) to a library you've created and stored in the database.  However, the user must also have access to the Graphics Builder database tables.  For more information, consult your database administrator.


Renaming libraries stored in the file system

To rename libraries in the file system:

  You can use your operating system to rename a library that is stored on the file system.  You must have the appropriate file permissions to be able to rename the file.

See your operating system documentation for the correct method of renaming files.


Renaming libraries stored in the database

To rename a library stored in the database:

1	Choose Tools [image] PL/SQL Interpreter to show the PL/SQL Interpreter.

2	Type the RENAME command on the Interpreter command line as follows:

PL/SQL> .RENAME LIB library_name1 TO library_name2

If you did not create the library yourself, and the library is stored in the database, you must have GRANT privilege to rename the library.  If the library is stored in the file system, you must have the correct file permissions to rename the library.


Deleting libraries from the file system

To delete libraries from the file system:

  You can use your operating system to delete a library that is stored as a file.  You must have the appropriate file permissions to delete a file.

See your operating system documentation for the correct method of deleting files.


Deleting libraries from the database

 To delete a library from the database:

1	Choose Tools [image] PL/SQL Interpreter to show the PL/SQL Interpreter.

2	Enter the following command on the Interpreter command line:

PL/SQL> .DELETE LIBRARY library_name;

where library_name is the name of the library you want to delete.

3	Close the PL/SQL Interpreter.


About trigger execution order

Triggers are PL/SQL procedures that fire at specific times during runtime.  Using triggers, you can enhance your displays with such features as buttons, dynamic "on-the-fly" chart formatting, and automatic updates and commits.  Graphics Builder executes all of the trigger procedures associated with a display in a particular order.  Understanding the order of execution can prove useful when developing your displays.

The following events can or do occur, in the order given:

•	Open Display trigger fires

•	query executes

•	chart updates

•	timer executes

•	button executes

•	Close Display trigger fires


About the firing of the Open Display trigger

An Open Display trigger fires at the time implied by its name:  immediately after a display is run (opened in runtime).  Open Display triggers are the first triggers to fire.


About query execution

  Related Topics

During query execution, the following occurs in the order given:

1	The query is executed automatically upon opening a display if the Execute on Opening Display option is set for the query.  By default, this option is activated, meaning that the query is executed immediately after the Open Display trigger is fired.

If Execute on Opening Display is not activated, query execution does not occur until the OG_EXECUTE_QUERY built-in procedure is called.

2	If it exists, the Post-Execution trigger fires immediately after the query is executed.

3	If it exists, the query filter function is executed immediately after the Post-Execution trigger is fired.  The query filter does not restrict fetched data from appearing in the Query property sheet, but determines what subset of that data will be charted.


About chart updates

  Related Topics

Chart updates include the following related events, occurring in the order shown given:

1	Chart updates occur automatically following query execution if the Update chart on query execution option is set for the chart.  By default, this option is activated, meaning that the chart is updated immediately after the query execution procedures are run.

If Update chart on query execution is not activated, chart update does not occur until the OG_UPDATE_CHART built-in procedure is called.

2	If it exists, the Format trigger fires in the final stage of the chart update, immediately before the chart is drawn.

You can use format triggers to set conditional formatting properties such as color for a chart element.


About timer execution

  Related Topics

Timer execution includes the following related events, occurring in the order given:

1	If a query is associated with a timer (via the Execute on Timer option on the Options page of the Query property sheet), the query is executed automatically when the timer expires.  By default, this option is not activated.

However, if Execute on Timer is activated, query execution could in turn spawn a chart update.

2	The timer procedure is executed simultaneously with the optional query execution (described above) when the timer expires.  If no query is to be executed at timer expiration, the timer procedure is the only event to occur.

Timers can be automatically activated when the display is run, or activated programmatically from a PL/SQL program unit using the Graphics Builder PL/SQL built-in procedure OG_ACTIVATE_TIMER.


About button execution

  Related Topics

Button execution includes the following related events, occurring in the order shown below:

1	When a mouse event is detected on a chart element acting as a button (e.g., a pie slice) in a drill-down relationship, Graphics Builder assigns a column value to a parameter using the column and parameter specified on the Drill-down page of the chart element's property sheet.

2	When a mouse event is detected on a chart element acting as a button (e.g., a pie slice) in a drill-down relationship, Graphics Builder executes the detail chart query specified on the Drill-down page of the chart element's property sheet.

3	When a mouse event is detected on any button object, the button procedure (if it exists) for that object is executed.

Query execution could in turn spawn a chart update.


About the firing of the Close Display trigger

A Close Display trigger fires immediately before the display is closed.  Close Display triggers are the last triggers to fire.


About referencing a trigger

For each type of trigger, a corresponding assignment/reference node appears in the Object Navigator.  These nodes represent which procedures, if any, are assigned to a particular trigger.

You can assign an existing program unit to a trigger by selecting the program unit object in the Navigator, and dragging it directly beneath one of the trigger assignment nodes.  When you release the mouse, the program unit name appears with the trigger node.

The following table shows which trigger procedure assignment nodes are associated with what objects in the Navigator:

Trigger Type	Object Node in Navigator

Open Display	Display
Post Execution	Query
Format	Chart Element
Timer	Query, Timer
Button	Object, Chart Element, Layer, etc.
Close Display	Display
At any time, you can double-click one of the trigger nodes to create a new trigger procedure with the Program Unit editor, or edit the currently assigned trigger procedure.


About using Open Display triggers

  Related Topics

An Open Display trigger executes a PL/SQL procedure when the display is first run.  For example, you could define an Open Display trigger that sets the initial state of the display by executing queries and creating charts, activating timers, etc.


Creating Open Display triggers

  Example	   Related Topics

To create an open display trigger:

1	Double-click on the Open Display object in the Navigator to show the Program Unit editor.

The Program Unit editor appears containing a default trigger procedure template (initially named OGTRIGGERPROCx).

2	Rename the trigger procedure or keep the default, then enter the body of the procedure.

3	Select Compile to compile the program unit.

If any errors are encountered, correct them and recompile.

4	Select Close to close the Program Unit editor.


Example: Open Display trigger

PROCEDURE open_disp IS
  old_layr  OG_LAYER;
  nu_layr   OG_LAYER;
  the_qry   OG_QUERY;
BEGIN
  old_layer:=OG_GET_LAYER('layer_home');
  nu_layer:=OG_GET_LAYER('layer_buttn');
  the_qry:=OG_GET_QUERY('query0');
  OG_ACTIVATE_LAYER(nu_layr);
  OG_HIDE_LAYER(old_layr);
  OG_EXECUTE_QUERY(the_qry);
END:


Modifying references to Open Display trigger procedures

To modify a reference to an Open Display trigger  procedure:

1	Choose Tools [image] Display to open the Display Property sheet.

2	Select an available trigger procedure from the Open Trigger drop-down list, or select None if no behavior is desired when the display is opened.

3	Select OK to apply the change and close the Display property sheet.

Graphics Builder allows you to create multiple trigger procedures and assign any one to an Open Display trigger while developing your display.


About using Post-Execution triggers

  Related Topics

Post-Execution triggers are PL/SQL procedures associated with queries.  They fire immediately after their associated query is executed.


Creating Post-Execution triggers

  Example

To create a Post-Execution trigger:

1	Double-click on the Post Execution object under the query object in the Navigator.

The Program Unit editor appears, containing a default trigger procedure template (initially named OGQUERYPROCx).

2	Rename the trigger procedure or keep the default, then enter the body of the procedure.

3	Select Compile to compile the program unit.

If any errors are encountered, correct them and recompile.

4	Select Close to close the Program Unit editor.


Example: Post-Execution trigger

PROCEDURE post_exec IS
  the_timer  OG_TIMER;
BEGIN
  the_timer:=OG_GET_TIMER('check_stock');
  OG_ACTIVATE_TIMER(the_timer);
END:


Modifying references to Post-Execution triggers

To modify a reference to a Post-Execution trigger:

1	Double-click on a query object in the Navigator, or select the query and choose the Properties command from the pop-up menu to show the Query property sheet.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet for the current query.

2	Select the Options tab to show the Options property page.

3	Select any available post-execution trigger procedure from the Post-Execution Trigger drop-down list, or select None if no post-execution behavior is desired.

4	Select OK to apply the change and close the Object property sheet.

Graphics Builder allows you to create multiple post-execution trigger procedures and easily assign them to any query in your display.


About using format triggers

  Related Topics

A format trigger is a PL/SQL procedure associated with a chart element.  Format triggers are executed just before the chart element is drawn, allowing you to dynamically change the formatting attributes of the element.  For example, you could define a format trigger to color a chart's bars green if they exceed a certain value.


Creating format triggers

  Example	  Related Topics

To create a format trigger:

1	Double-click on the chart element you want to format, or select the chart element and choose the Properties command from the pop-up menu, to show the chart element's Object property sheet.

2	Select New, to the right of the Format Trigger drop-down list.

The Program Unit editor appears, containing a default format trigger procedure template   (initially named OGFORMATTRIGx).

3	Rename the format trigger procedure or keep the default, then enter the body of the procedure.

4	Select Compile to compile the program unit.

If any errors are encountered, correct them and recompile.

5	Select Close to close the Program Unit editor.


Example: Format trigger

PROCEDURE format_point (elem IN og_object, query IN
og_query) IS
  st_price  NUMBER;
BEGIN
  st_price:=OG_GET_NUMCELL(query, OG_NEWDATA, 'sell_pr');
 IF st_price > 200 THEN
   OG_SET_BFCOLOR (elem, 'red');
 END IF;
END:


Modifying references to format triggers

To modify a reference to a format trigger:

1	Double-click on the chart element, or select the element and choose the Properties command from the pop-up menu to show the chart element's Object property sheet.

2	Select an available format trigger procedure from the Format Trigger drop-down list, or select None if no special formatting is desired.

3	Select OK to apply the change and close the Object property sheet.

Graphics Builder allows you to create multiple format trigger procedures and access them easily from any valid chart element's property sheet.


About timer triggers

  Related Topics

A timer executes a PL/SQL trigger procedure at each occurrence of a specified time interval.  For example, you could define a timer that fires every minute and executes a PL/SQL procedure that updates a chart.


Creating timer triggers

  Example	  Related Topics

To create a timer trigger:

1	Select the Timers node in the Object Navigator.

2	Select the Create button or choose Navigator [image] Create to show the Timer Triggers dialog box.

If no timers currently exist, double-click on the Timers node in the Navigator to show a new default timer in the Timer Triggers dialog box.  This dialog shows the default settings for a new timer (initially named timerx).

Alternatively, you can select Tools [image] Timers and select New to create a new timer.

3	If you wish to create a new procedure, select New, to the right of the Procedure drop-down list.

The Program Unit editor appears, containing a default trigger procedure template (initially named OGTRIGGERPROCx).

4	Rename the trigger procedure or keep the default, then enter the body of the procedure.

5	Select Compile to compile the new procedure.

6	Select Close to close the Program Unit editor and return the Timer Triggers dialog.

7	If you have an existing program unit you want to assign, select it from the Procedure drop-down list.

8	Modify the timer's name and interval, if desired.

Use the Active check-box to determine if the timer will be activated automatically when the display is run (checked), or activated from another PL/SQL program unit (unchecked).

You can also use the Graphics Builder PL/SQL built-in procedure OG_ACTIVATE_TIMER to activate the timer from another program unit.  For example, you may want to allow the user to activate the timer by pressing a button in the runtime display.


Example: Timer trigger

PROCEDURE check_stock IS
  the_query  OG_QUERY;
  the_chart  OG_OBJECT;
BEGIN
  the_query:=OG_GET_QUERY('stock_val');
  the_chart:=OG_GET_CHART('stock');
  OG_EXECUTE_QUERY(the_query);
  OG_UPDATE_CHART(the_chart, OG_ALL_CHUPDA);
END:


Modifying references to timer trigger procedures

To modify a reference to a timer trigger:

1	Double-click on the timer you wish to modify, or choose Tools [image] Timers to show the Timer Triggers dialog box.

2	Select an available procedure from the Procedure drop-down list, or select None if no behavior is desired when the timer expires.

3	Select OK to apply the change and close the Timer Triggers dialog.

You can easily assign any PL/SQL procedure stored in the display to an existing timer in this manner.


About button procedures

Any object you create within or import into Graphics Builder can be assigned a button procedure, including layers, graphic objects, chart elements, symbols, and text objects.  Button procedures are executed when a specified "mouse event" (e.g.,  mouse down) involving the associated object is detected.

Buttons and button procedures require certain special considerations:

•	mouse events

•	event-active objects

•	button procedure specification

•	creating button procedures

•	modifying references to button procedures

Since buttons are invoked automatically and do not return values, button functions are not supported.  (For simplicity, all references to an "object" while discussing buttons should be taken to mean an "object or layer.")


About mouse events

Graphics Builder recognizes the following mouse events:

Event	Description

mouse down	detected when the mouse button is pressed
mouse up	detected when the mouse button is released
mouse move down	detected when the mouse is moved while the button is held down
mouse move up	detected when the mouse is moved while the button is not held down (may be detected only by a layer)


About event-active objects

The mouse down event is the most important event, since it determines which object becomes "event-active."  The event-active object "receives" the mouse down event and every subsequent event until the next mouse down (which then determines a new event-active object).

Only an object that has a procedure associated with it and is set to receive at least one mouse event is eligible to become the event-active object.  (You can set an object's procedure and desired events either in its Properties dialog or via PL/SQL.)  Note that an object does not have to be set to receive a mouse down event in order to become event-active.

When Graphics Builder detects a mouse down event, it uses the following search strategy to find the first object that meets the above criteria:

•	topmost object (on the active layer) to which the mouse is pointing

•	the parent group of the topmost object (note that you can assign a procedure to a group object that is invoked when any of its children are selected, as long as the children have not been assigned their own procedures, which would take priority)

•	the parent's parent, and so on up the group tree of the topmost object

•	the active layer

The first object that Graphics Builder finds that meets the stated criteria becomes the event-active object.  If no qualified objects are found, the mouse down event is ignored.  Note that the active layer can be made event-active by selecting a spot on the layout that is not occupied by an object that resides on that layer.

Once the event-active object has been chosen, Graphics Builder checks if that object is set to receive mouse down events.  If so, it receives the mouse down event that made it event-active, and the procedure is executed.  Graphics Builder then does the same for all subsequently detected events, invoking the procedure only for the events the object is set to receive.

When Graphics Builder detects a mouse up event, the event-active object is "deactivated."  It no longer receives any mouse events, unless it is again made event-active by a mouse down.

A Special Note About Layers

A layer is able to receive two events that an object cannot:  mouse move up and mouse move down.  If the active layer has a procedure associated with it and is set to receive either event, it will do so while no other object is event-active.


About button procedure specifications

  Example	  Related Topics

A button procedure must have exactly four specific arguments.  Graphics Builder supplies the following default procedure specification when you create a new button procedure:

PROCEDURE proc_name
  (buttonobj  IN  og_object,
   hitobj     IN  og_object,
   win        IN  og_window,
   eventinfo  IN  og_event) IS

where:

proc_name	Is the name of the procedure.  Graphics Builder  supplies a default unique name for the procedure; however, you may change it.
buttonobj	Is the handle to the event-active object (i.e., the object that has this button procedure associated with it).
hitobj	Is the handle to the topmost object on the active layer that the mouse is pointing to when the event is detected.  This may differ from buttonobj if the object that was selected is a child of a group that has a button procedure; in that case, buttonobj is the group object and hitobj is the child.
win	Is the handle to the window in which the event-active object became event-active.
eventinfo	Is a record containing information about the mouse event that invoked this procedure.  This field is of the Graphics Builder built-in datatype OG_EVENT.
You can use the button procedure's eventinfo argument to have the procedure perform different actions on different events.  Note that a button procedure is invoked by any event it is set to receive.  If there are no conditions placed on the procedure's actions, all statements not limited to a specific condition are executed.


Example: Button procedure -- moving an object

The following button procedure moves the button object to the right and down two inches when it receives a mouse down event, and then rotates the object 45 degrees (using the mouse position as the center of rotation) when it receives a mouse up event.  Note that even though the button object may also be set to receive mouse move down events-and therefore those events do invoke the procedure, this procedure simply ignores them.

PROCEDURE move_and_rotate(buttonobj IN og_object, hitobj IN og_object, win IN og_window, eventinfo IN og_event) IS
  move_offset  OG_POINT;
BEGIN
  IF eventinfo.event_type=OG_MOUSE_DOWN THEN
    move_offset.x := 2 * OG_INCH;
    move_offset.y := 2 * OG_INCH;
    OG_MOVE(buttonobj, move_offset);
  ELSIF eventinfo.event_type=OG_MOUSE_UP THEN
    OG_ROTATE(buttonobj, eventinfo.mouse_position, 45);
  END IF;
END;


Creating button procedures

  Example

To create a button procedure:

1	Double-click on the object, or select the object and choose Tools [image] Properties to show the Object property sheet.

2	If the object is unnamed, type a name in the Name field.

3	Select New, to the right of the Procedure drop-down list.

The Program Unit editor appears, containing a default button procedure template (initially named OGBUTTONPROCx).

4	Rename the button procedure or accept the default, then enter the body of the procedure.

5	Select Compile to compile the program unit.

If any errors are encountered, correct them and recompile.

6	Select Close to close the Program Unit editor.


Example: Button procedure -- stopping a timer

PROCEDURE stop_plot (buttonobj IN og_object, hitobj IN
og_object, win IN og_object) IS
  the_timer  OG_TIMER;
BEGIN
  the_timer:=og_get_timer('stockchk');
  OG_DEACTIVATE_TIMER(the_timer);
END;


Modifying references to button procedures

 To modify a reference to a button procedure:

1	Double-click on the object, or select the object and choose Tools [image] Properties to show the Object property sheet.

2	Select an available button procedure from the Procedure drop-down list, or select None if no button behavior is desired.

3	Select OK to apply the change and close the Object property sheet.

Graphics Builder allows you to create multiple button procedures and access them easily from any object's property sheet while developing your displays.


About using Close Display triggers

  Related Topics

A Close Display trigger executes a PL/SQL procedure when the display is closed at runtime.  For example, you could define a Close Display trigger to print the display or commit changes to the database.

Note that the display will not actually close until the Close Display trigger procedure has finished executing.


Creating Close Display triggers

  Example	  Related Topics

To create a Close Display trigger:

1	In the Object Navigator, double-click on the Close Trigger icon, or choose Tools [image] Display to show the Display property sheet.

2	Select New, to the right of the Close Trigger drop-down list.

The Program Unit editor appears, containing a default trigger procedure template (initially named OGTRIGGERPROCx).

3	Rename the procedure, or keep the default, then enter the body of the procedure.

4	Select Compile to compile the program unit.

If any errors are encountered, correct them and recompile.

5	Select Close to close the Program Unit editor.


Example: Close Display trigger

PROCEDURE close_disp IS
  the_sound  OG_SOUND;
BEGIN
  the_sound:=OG_GET_SOUND('playme');
  OG_PLAY_SOUND(the_sound);
END;


Modifying references to Close Display trigger procedures

To modify a  reference to a Close Display trigger:

1	Choose Tools [image] Display to open the Display property sheet.

2	Select an available trigger procedure from the Close Trigger drop-down list, or select None if no behavior is desired when the display is closed.

3	Select OK to apply the change and close the Display property sheet.

Graphics Builder allows you to create multiple trigger procedures and easily assign one as a Close Display trigger while developing your display.


About queries

Queries are SQL SELECT statements or files that you can use to retrieve data for a display.  In most cases, you'll use queries to retrieve data for charts, but you can also execute queries programmatically and use the data to create and modify objects.

Regardless of whether you create your queries at chart creation time, or separately, it is a good idea to give each query a unique and representative name.  Each query you create is given a default name of queryn by Graphics Builder.  Assigning indicative names can help you easily locate the query in the Object Navigator, or pick a query from a drop-down list when creating a chart.


Connecting to the datasource

To connect to the datasource:

1	Choose File [image] Connect to display the Connect dialog box.

Before you can query a datasource, you need to connect to it.  Then you can create a SQL SELECT statement to retrieve the data.

2	Type your username and password.  (Your password will not appear when you type.)  If you're not sure which username and password to use, consult your datasource administrator.

Leave the Database field blank, unless you're connecting to a remote datasource.  If so, you'll need to enter the SQL*Net communications protocol, datasource node, and database name, separated by colons.  For example:

t:boston:payroll

Or, for an ODBC datasource:

ODBC:boston:payroll

You can specify a default datasource connection string to use for all connections.

1	Select Connect to log on.

If you successfully log on to the datasource, the Connect dialog box closes.  If you get an error message, consult your datasource administrator and confirm that you're using the correct logon ID and datasource specification.


About creating queries

Graphics Builder gives you the following options for creating queries:

creating a SQL SELECT statement

specifying files as queries

creating queries at chart creation time

creating a query using PL/SQL

Which method you use depends on your data source.  If it’s a database, you'll use a SQL SELECT statement.  If your data source is a file, such as a spreadsheet, you'll specify the entire file as the query.  Further, you can create custom queries using a combination of SQL statements and PL/SQL code.

When you execute a query, Graphics Builder retrieves the specified set of data columns and their rows, and places them in the Data property page in the Query property sheet.  The Data property page always contains the data retrieved from the current query.  When you create a chart, Graphics Builder uses the data from the current query unless you specify otherwise.


About using external SQL queries

If you have existing SQL queries stored in files, you can use either of the following options:

•	reference external SQL queries

•	import external SQL queries

For more information about SQL SELECT statements and how to store them in text files, see the Oracle7 Server SQL Language Reference Manual.


Creating a SQL SELECT statement

To create a SQL SELECT statement query:

1	Select the Queries node in the Object Navigator and select Create or choose Navigator [image] Create to show the Query property sheet.

If no queries currently exist, double-click on the Queries node in the Navigator to show the Query property sheet.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet and then select New to create a new query.

The default name is queryx, where x is an instance number that increments by one each time a new query is created during the current session.

2	Keep the default name or type a new name in the Name field.

3	Type a SQL SELECT statement in the SQL Statement field.

For more information about SQL SELECT statements, see the Oracle7 Server SQL Language Reference Manual.

4	Select Execute to execute the query.

The data appears in the Data property page.

5	Select OK or Close to close the Query property sheet.

The query remains the current query until you create or edit another one.

If you wish to create your queries up front and create your charts at a later time, use this method.  With the Query property sheet, you can create multiple queries at one time.


Specifying files as queries

To specify a file as a query:

1	Select the Queries node in the Object Navigator and select Create or choose Navigator [image] Create to show the Query property sheet.

If no queries currently exist, double-click on the Queries node in the Navigator to show the Query property sheet.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet and then select New to create a new query.

The default name is queryx, where x is an instance number that increments by one each time a new query is created during the current session.

2	Keep the default name, or type a new name in the Name field.

3	Select a file type from the Query Type drop-down list.

4	Select Find to show your system's file dialog.

5	Select a valid file and accept the dialog box.

Graphics Builder places the directory path and filename in the File name field.

If your file contains dates, see Setting Date Formats for File Queries.

6	Select Execute to execute the query.

The data appears in the Data property page.

7	Select OK or Close to close the Query property sheet.

The query remains the current query until you create or edit another one.

File formats that might be used as queries are SYLK, WKS, or PRN


Creating a query using PL/SQL

  Related Topics

To create a query using PL/SQL:

  Use parameters and Graphics Builder PL/SQL built-ins to create and execute queries programmatically.  For example, you may want to use a parameter to programmatically set a where clause for the query.  You could do this by creating a query (query0) that includes a lexical reference to a parameter of the type CHAR. (the_param).

The following procedure sets a value for the parameter based on the argument provided, then executes the query and updates the associated chart:

PROCEDURE add_param (the_name IN VARCHAR2) IS
  query  OG_QUERY;
  the_chart  OG_OBJECT;
BEGIN
  :the_param:='WHERE ename = '|| the_name;
  query:=OG_GET_QUERY('query0');
  OG_EXECUTE_QUERY(query);
  the_chart:=OG_GET_CHART('name_chart');
  OG_UPDATE_CHART(the_chart, OG_ALL_CHUPDA);
END;

Alternatively, you can create the entire query programmatically using the OG_MAKE_QUERY function.  For example:

FUNCTION make_ch RETURN og_query IS
BEGIN
  query:=OG_MAKE_QUERY(OG_SQL_QTYPE, 'select ename,
sal from emp');
END;

Once you've created a query with the above function, you can execute the resulting query to create a chart.


Referencing external SQL queries

  Related Topics

To reference an external query:

1	Select the Queries node in the Object Navigator and select Create or choose Navigator [image] Create to show the Query property sheet.

If no queries currently exist, double-click on the Queries node in the Navigator to show the Query property sheet.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet and then select New to create a new query.

2	Select External SQL File from the Type drop-down list.

The File field and Browse are activated.

3	Type the name and location of the SQL file in the File field or select Browse to show your operating system file dialog.

4	Select the SQL file you wish to reference and accept the file dialog to close it.

Graphics Builder stores the path location to that file.

5	Select Execute to execute the query in the external file.

6	Select OK to close the Query property sheet.

Referencing an external query file in Graphics Builder provides a link to that file, rather than including the query in the display.  Use this method if you do not want to edit the query, or include it in the display.

If you distribute the display at runtime, you must also distribute the external query file so that Graphics Builder can find it to execute.


Importing external SQL queries

To import an external SQL query:

1	Select the Queries node in the Object Navigator and select Create or choose Navigator [image] Create to show the Query property sheet.

If no queries currently exist, double-click on the Queries node in the Navigator to show the Query property sheet.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet and then select New to create a new query.

2	Select the cursor in the SQL Statement field.

3	Select Import SQL to show your system's file dialog.

4	Select a text file containing a SQL SELECT statement and accept the dialog box.

Graphics Builder imports the SQL statement stored in the file into the SQL Statement field.

5	Select Execute to execute the imported query.

6	Select OK to close the dialog.

Once the query is imported, you can edit it, if necessary.


Exporting queries to text files

To export a query to a text file:

1	Double-click on the query object you wish to modify, or select the query object in the Object Navigator and choose the Properties command from the pop-up menu.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet for the current query.

2	If necessary, select an alternate query from the Query drop-down list.

3	Select the cursor in the SQL Statement field.

4	Select the Export SQL to show your system's file dialog.

5	Select a text file you wish to contain the SQL statement and accept the dialog box.

6	Select OK to close the Query property sheet.

Graphics Builder exports the SQL statement to the named file.

Once you have created a SQL query in Graphics Builder, you can export that query to a text file for use in other Oracle products.  You can re-use queries within Graphics Builder by dragging a query from one display to another in the Object Navigator.


About creating custom queries

Custom queries allow you to create columns and populate them with data using just PL/SQL, or a combination of SQL and PL/SQL.

You can populate query columns using a custom execution procedure or by using an external source.  After you've created a custom query, you can reference it when creating a chart.


About populating query columns using an external source

When you include a Graphics Builder chart in another Oracle product such as Form Builder or Report Builder (included with Reports Developer), the chart will use the data from the calling product's query as long as the query columns used to create the chart and the columns used in the calling product's query match.

If the chart you are building will only be called by another Oracle product, you can use a custom query to create an "empty" chart.  This chart will be populated with data when it is invoked by the calling product.  Use the custom query Schema property page to create columns with the same names as the query used by the calling product.  Then define the chart's properties as you normally would, assigning category and value data, etc.

The chart will appear in the layout with no data in it.

When the Graphics Builder display is called by the other product, the calling product's query is substituted for the custom query, and because the column names are the same, the chart is drawn to your specifications.

In this case, there is no need to create a custom execution procedure to populate the columns with data.


Creating custom query columns

To create custom query columns:

1	Select the Queries node in the Object Navigator and select Create or Navigator [image] Create to show the Query property sheet.

If no queries currently exist, double-click on the Queries node in the Navigator to show the Query property sheet.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet and then select New to create a new query.

The default name is queryx, where x is an instance number that increments by one each time a new query is created during the current session.

2	Keep the default name or type a new name in the Name field.

3	Select Custom from the Query Type drop-down list.

4	Choose the Schema tab to show the Schema property page.

5	Select New Column to create a column.

6	Change the name, type, and other settings, where applicable.

Continue creating all of the columns you wish to graph.

7	Create a custom execution procedure to populate the columns with data, or select Close to close the Query property sheet.


Populating query columns using a custom execution procedure

  Example

To create a custom execution procedure:

1	Double-click on the (custom) query object you wish to modify, or select the query object in the Object Navigator and choose the Properties command from the pop-up menu.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet for the current query.

2	If necessary, select an alternate query from the Query drop-down list.

3	Choose the Options tab to show the Options property page.

4	Select an existing custom execution trigger from the drop-down list, or select New to create a new custom execution procedure.

The Program Unit editor appears with a template OGQUERYPROC0 procedure.

5	Edit the template procedure to populate the custom columns.

Use the OG_SET_xxxCELL and OG_APPEND_ROW PL/SQL built-in procedures.

6	Select OK to apply your changes and close the Query property sheet.

You can save and run your display, or choose Chart [image] Update Chart to test the custom execution procedure.


Example: Using a custom query procedure

The following procedure is an example of a custom execution procedure.  This procedure assumes that three columns were created in the Schema property page.  The Name column is of type CHAR, the Salary column is of type NUMBER, and the Hired columns is of type DATE.

Graphics Builder maintains a buffer row, or virtual row for the table.  You populate the virtual row using OG_SET_xxxCELL, and then append the virtual row to the table using OG_APPEND_ROW.  Notice that since there is only one virtual row, you can only populate one row of the table at a time.

PROCEDURE fill_columns (query IN og_query)IS

/* Set the data for the first row */
  OG_SET_CHARCELL(query, 'Name', 'Smith');
  OG_SET_NUMCELL(query, 'Salary', '50000');
  OG_SET_DATECELL(query, 'Hired', '12-NOV-88');

/* Append the row of data to the table*/
  OG_APPEND_ROW(query);

/* Set the data for the next row*/
  OG_SET_CHARCELL(query, 'Name', 'Jones');
  OG_SET_NUMCELL(query, 'Salary', '55000');
  OG_SET_DATECELL(query, 'Hired', '19-APR-92');

/* Append the row of data to the table*/
  OG_APPEND_ROW(query);

END;


Accessing queries with the Object Navigator

To access a query with the Object Navigator:

1	Double-click on the query object in the Navigator to show the Query property sheet for that query, or select the query object and choose the Properties command from the pop-up menu.

2	Once the Query property sheet is open, you can select other queries to modify from the Query drop-down list.


Accessing queries with the menu

To access queries with the menu:

1	Choose Tools [image] Queries to show the Query property sheet.

2	Select a query from the Query drop-down list.

Perform the desired action.

This method opens the Query property sheet for the current query.  Once opened, you can select an alternate query from the Query drop-down list.  The current query is the most recently created or modified in the Query property sheet.


Modifying queries

To modify a query:

1	Double-click on the query object you wish to modify, or select the query object in the Navigator and choose the Properties command from the pop-up menu.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet for the current query.

2	If necessary, select an alternate query from the Query drop-down list.

3	Edit the query as follows:

   If the query is a SQL SELECT statement, edit the SQL SELECT statement in the SQL Statement field.

  If the query is based on a file, your system's file dialog box appears.  Select a file and accept the dialog box.  Edit the file as necessary.

4	Select Execute to re-execute the query.

The new data appears in the Data property page.

5	Select OK to close the Query property sheet.

The query remains the current query until you create or edit another one.


Modifying queries with the Object Navigator

To modify a query using the Object Navigator:

  Select the query object and then choose one of the buttons in the Object Navigator, such as Create or Delete, or choose an option from the Navigator menu.


Renaming queries in the Object Navigator

To rename a query in the Object Navigator:

1	Select the query object you wish to rename.

2	Select the name once to position the cursor and enter edit mode.

If you wish to replace the entire name, select the name to highlight it, then type the new name.

Use this method to quickly rename one or more queries directly in the object navigator.  If you want to view the contents of the query before renaming it, use the menu method below.

3	If the query is referenced in any PL/SQL program units or drill-down relationships, change all references to reflect the new query name.


Renaming queries in the Query property sheet

To rename a query in the Query property sheet:

1	Double-click on the query object you wish to modify, or select the query object in the Object Navigator and choose the Properties command from the pop-up menu.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet for the current query.

2	If necessary, select an alternate query from the Query drop-down list.

3	Type a new name for the query in the Name field.

4	Select OK to apply the new name and close the Query property sheet.

Use this method if you want to view the contents of the query before renaming it.

5	If the query is referenced in any PL/SQL program units or drill-down relationships, change all references to reflect the new query name.


Setting date formats for file queries

To set date formats for file queries:

1	Double-click on the query object you wish to modify, or select the query object in the Object Navigator and choose the Properties command from the pop-up menu.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet for the current query.

2	If necessary, select an alternate query from the Query drop-down list.

3	Choose the Options tab to show the Options property page.

4	Type a date format in the Date Format field, or choose List and select an existing format from the Date Format dialog box.

For more information about valid formats, see the Oracle7 Server SQL Language Reference Manual.

5	Select OK to accept the dialog box and return to the Query property sheet.

6	Select Execute to re-execute the query and plot the data in the new format.

If you are querying a file (SYLK, WKS, or PRN) that includes dates, and you want Graphics Builder to recognize them as dates and not as individual characters, you need to specify date formats in the Query property sheet.

These date formats are used only for dates on the Data property page in the Query property sheet.  For charts, you can set date formats in the Layout or Chart Template editors.


About executing queries

You can execute queries in the following ways:

•	automatically upon opening a display

•	at specific time intervals

•	using PL/SQL


About filtering chart data

When you want to restrict the amount of data plotted in a chart, you normally filter the data by specifying a WHERE clause in your query (e.g., "WHERE DEPTNO = :DNO").  However, this method requires that each chart be assigned its own unique query.  In addition, re-executing a query every time its chart is updated can negatively impact your chart's performance.

To avoid this problem, you can create a query filter on a chart.  Query filters are PL/SQL functions that restrict the amount of data plotted in a chart.  Because each chart can be assigned its own query filter, a single query—executed only once—can provide the data used by multiple charts.

The query filter function reads through each row in your query and evaluates that row of data according to the condition(s) you set in the query filter itself.  Each row that meets the condition(s) is plotted.  Each row that does not meet the condition(s) is not plotted but still remains in the Data property page of the Query property sheet.


Creating a query filter

  Related Topics	  Example

To create a query filter:

1	Decide what condition you wish to set on the query data.

You may want to set a maximum limit on a column, compare values of multiple columns, or select a specific range of allowable data.

2	Double-click on the chart to show the Chart property sheet.

3	Select the Data tab to show the Data property page.

4	Select the New button that appears to the right of the Filter Function drop-down list.

The PL/SQL Program Unit editor appears, containing a default query filter function template (initially named OGQUERYFILTER0).

You will need to supply a condition based on one or more columns in your query.

5	Define the condition to filter by.

6	Select Compile in the Program Unit editor to compile the query filter.

If you encounter any errors, correct them and re-compile.  The query filter must be successfully compiled before it can be used.

7	Select Close to close the Program Unit editor.

8	Select OK to close the Chart property sheet.

You can choose Chart [image] Update Chart to see the results of the query filter function on your chart.

Although the query selects every row from the table, the query filter ensures that only certain rows are charted.

For more information about setting conditions using PL/SQL, see "Control Structures," in the PL/SQL User's Guide and Reference.


Using query filter functions

  Related Topics

To use query filter functions:

1	Double-click on the chart, or select the chart you wish to add a query filter to (either in the Layout editor or the Object Navigator) and choose the Properties command from the pop-up menu.

Alternatively, you can choose Tools [image] Properties to show the Chart property sheet.

2	Choose the Data tab to show the Data property page.

3	Select an existing query filter function from the Filter Function drop-down list, or select New to create a new query filter.

4	Select OK to apply your changes and close the Chart property sheet.

You can use Chart [image] Update Chart to test the query filter function.

Using Graphics Builder, you can create a single query that can be assigned to multiple charts.  By creating a query filter function for a chart, you can restrict the data plotted in the chart (e.g., all salaries greater than 5000) without the need to re-execute your query.

Also, if you plan to create multiple charts that use the same data source, you can create one generic query and use query filters to determine which data is plotted.  In this case, the query filter would perform the same function as a WHERE clause, but with the added performance advantage of only requiring one query to be executed against the server, as the filter would apportion the data on the client side.


Executing queries upon opening a display

To execute a query upon opening a display:

1	Double-click on the query object you wish to modify, or select the query object in the Object Navigator and choose the Properties command from the pop-up menu.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet for the current query.

2	If necessary, select an alternate query from the Query drop-down list.

3	Choose the Options tab to show the Options property page.

4	Activate Execute on Opening Display by selecting its check box.


Executing queries at specific time intervals

To execute a query at specific time intervals:

1	Double-click on the query object you wish to modify, or select the query object in the Object Navigator and choose the Properties command from the pop-up menu.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet for the current query.

2	If necessary, select an alternate query from the Query drop-down list.

3	Choose the Options tab to show the Options property page.

4	Activate Execute on Timer by selecting its check box.

5	Select an existing timer from the drop-down list, or select New to create a new timer.


Executing queries using PL/SQL

  Related Topics

To execute a query using PL/SQL:

  Use the PL/SQL built-in subprograms OG_EXECUTE_QUERY and OG_UPDATE_CHART.

The following example executes the specified query and updates the associated chart:

PROCEDURE every_30_secs IS
   query   OG_QUERY;
   the_chart   OG_OBJECT;
BEGIN
   query:=OG_GET_QUERY('emp_query');
   the_chart:=OG_GET_OBJECT('emp_chart');
   OG_EXECUTE_QUERY(query);
   OG_UPDATE_CHART(the_chart, OG_ALL_CHUPDA);
END;


Deleting queries in the Object Navigator

To delete a query in the Object Navigator:

1	Select the query object you wish to delete.

2	Select Delete in the Object Navigator, or choose Navigator [image] Delete.

An alert appears, prompting you to confirm the deletion.

3	Select Yes to confirm.

Use this method to quickly delete one or more queries listed in the Object Navigator.  If you wish to view the query before deleting it, use the Query property sheet method described below.


Deleting queries in the Query property sheet

To delete a query in the Query property sheet:

1	Double-click on the query object you wish to modify, or select the query object in the Object Navigator and choose the Properties command from the pop-up menu.

Alternatively, you can choose Tools [image] Queries to show the Query property sheet for the current query.

2	If necessary, select an alternate query from the Query drop-down list.

3	Select Delete.

An alert appears, prompting you to confirm the deletion.

4	Select Yes to confirm.

Use this method if you wish to view the contents of a query prior to deleting it.


About renaming layers

  Related Topics

You can rename a layer in either of two locations:

•	the Layer Settings dialog box

•	the Object Navigator

If you rename a layer that you have referenced in a PL/SQL program unit, you must change all references to reflect the new name.


Activating layers

To activate a layer:

1	Double-click on the layer object in the Navigator to display the Layer Settings dialog.

Alternatively, you can select the layer object in the Navigator and choose the Properties command from the pop-up menu, or choose Tools [image] Properties from the menu.

2	Select a layer from the Existing Layers list.

3	Select Activate.

The layer is listed in the Active Layer field.  If the layer was previously hidden, it will now be showing.

4	Select OK to confirm the changes and close the Layer Settings dialog.

To work on a layer, you need to make it the active layer.  Only one layer can be active at a time.


Activating a layer using PL/SQL

  Related Topics

To activate a layer using PL/SQL:

  Use the PL/SQL built-in subprogram OG_ACTIVATE_LAYER.

The following example activates the specified layer in the specified window:

PROCEDURE activate_a_layer(layer_num IN NUMBER, the_window
 IN og_window) IS
   layer_name   VARCHAR2(6);
   the_layer    OG_LAYER;
BEGIN
   layer_name:='layer'||TO_CHAR(layer_num);
   the_layer:=OG_GET_LAYER(layer_name);
   OG_ACTIVATE_LAYER(the_layer, the_window);
END;


Renaming a layer in the Layer Settings dialog

To rename a layer in the Layer Settings dialog:

1	Double-click on the layer object in the Navigator to display the Layer Settings dialog.

Alternatively, you can select the layer object in the Navigator and choose the Properties command from the pop-up menu, or choose Tools [image] Properties from the menu.

2	Select the layer from the Existing Layers list

The layer appears in the Rename field.

3	Type a new name for the layer in the Rename field.

4	Select Rename.

In the Existing Layers list, the new name replaces the old name.

5	Select OK to confirm the changes and close the Layer Settings dialog.


Renaming a layer in the Object Navigator

To rename a layer in the Object Navigator:

1	Select the layer object you wish to rename.

2	Move the mouse pointer over the layer name.  The cursor changes from a pointer to a text editor.

3	Select the name once to position the cursor and enter edit mode.  If you wish to replace the entire name, select the name to highlight it, then type the new name.


Hiding and showing layers

To hide or show a layer:

1	Double-click on the layer object in the Navigator to display the Layer Settings dialog.

Alternatively, you can select the layer object in the Navigator and choose the Properties command from the pop-up menu, or choose Tools [image] Properties from the menu.

2	Select the layer from the Existing Layers list.

3	Select Hide/Show.

   If the layer was hidden, a plus (+) sign appears in front of the layer, indicating that it's now showing.

  If the layer was showing, a minus (-) sign appears in front of the layer, indicating that it's now hidden.

  You can hide any layer that is showing except the active layer.  To hide the layer that is currently active, you must first activate a different layer.

4	Select OK to confirm the changes and close the Layer Settings dialog.

You can hide or show any number of layers.  You cannot hide the active layer.  If you wish to hide a layer that is currently active, you must first activate a different layer.


Hiding and showing layers using PL/SQL

  Related Topics

To hide and show layers using PL/SQL

  Use the PL/SQL built-in subprograms OG_HIDE_LAYER and OG_SHOW_LAYER.

The first example hides the specified layer and the second example shows the specified layer:

PROCEDURE make_layer1_invis(the_window) IS
   my_layer   OG_LAYER;
BEGIN
   my_layer:=OG_GET_LAYER('layer1');
   OG_HIDE_LAYER(my_layer, the_window);
END;

PROCEDURE make_layer_visible(the_window) IS
   my_layer   OG_LAYER;
BEGIN
   my_layer:=OG_GET_LAYER('layer1');
   OG_SHOW_LAYER(my_layer, the_window);
END;


Re-ordering layers
Reordering layers

To reorder layers:

1	Double-click on the layer object in the Navigator to display the Layer Settings dialog.

Alternatively, you can select the layer object in the Navigator and choose the Properties command from the pop-up menu, or choose Tools [image] Properties from the menu.

2	Select the layer you want to place in a different order from the Existing Layers list

3	Choose either the Up (up a layer), Down (down a layer), Top (to the top of the stack), or Bottom (to the bottom of the stack) buttons.

The layer moves to its new position in the stack.

4	Select OK to confirm the changes and close the Layer Settings dialog.


Deleting layers

To delete a layer:

1	Double-click on the layer object in the Navigator to display the Layer Settings dialog.

Alternatively, you can select the layer object in the Navigator and choose the Properties command from the pop-up menu, or choose Tools [image] Properties from the menu.

2	Select the layer you want to delete from the Existing Layers list.

3	Select Delete.

4	Select Yes to confirm the alert that appears.

The layer is removed from the Existing Layers List.

5	Select OK to confirm the changes and close the Layer Settings dialog

The layer and its objects are deleted from the display.  You can delete any non-active layers, whether hiding or showing.  Deleting a layer also deletes all objects on that layer.  You cannot delete the active layer.  If you wish to delete the active layer, you must first activate another layer.


About user exits

A user exit is a program that you write and then link into the Graphics Builder executable files..  User exits enable you to call your 3GL programs from Graphics Builder.  Build user exits when you want to pass control from Graphics Builder to a program you have written that performs some function, and then return control to Graphics Builder.

User exits can perform the following tasks:

•	pass data to Graphics Builder from operating system text files

•	manipulate LONG RAW data

•	support PL/SQL blocks

•	control real time devices, such as a printer or machinery

You can use user exits for other tasks, such as mathematical processing.  However, Oracle recommends that you perform such tasks with PL/SQL within Graphics Builder, because PL/SQL is portable and user exits are not.

Note:  Not all types of user exits can perform all of the described tasks.  You can accomplish most of these tasks only with ORACLE Precompiler user exits.


About ORACLE Precompiler user exits

An ORACLE Precompiler user exit incorporates the ORACLE Precompiler interface.  With this interface you can write a subroutine in one of the host languages (Ada, C, COBOL, FORTRAN, Pascal, PL/l) and embed SQL commands.  The user exit can also access ORACLE (via embedded SQL commands) and Graphics Builder parameters.

Because of these features, you will write most of your user exits as ORACLE Precompiler user exits.  For more information on the ORACLE Precompiler interface, see the Programmer's Guide to the ORACLE Precompilers.

You can also write a user exit that combines both the ORACLE Precompiler interface and the OCI.

Note: Not all operating systems support all of the listed languages.  For more information, see the Graphics Builder documentation for your operating system.


About OCI (ORACLE Call Interface) user exits

An OCI user exit incorporates the ORACLE Call Interface.  With this interface, you can write a subroutine that contains calls to ORACLE.

A user exit that incorporates only the OCI (and not the ORACLE Precompiler interface) cannot access Graphics Builder parameters.  For more information on the OCI, see the Programmer's Guide to the ORACLE Call Interface.

You can also write a user exit that combines both the ORACLE Precompiler interface and the OCI.


About non-ORACLE user exits

A non-ORACLE user exit does not incorporate either the ORACLE Precompiler interface or the OCI.  For example, a non-ORACLE user exit might be written entirely in C.  By definition, a non-ORACLE user exit cannot access ORACLE, or Graphics Builder parameters.


About writing a user exit

  Related Topics

This section explains the basic steps of writing an ORACLE Precompiler user exit.  (This section applies specifically to a ORACLE Precompiler user exits, because it is the type of user exit that you will use most often.  It can access Graphics Builder variables, parameters, and ORACLE database data, and it is the type that Oracle Corporation recommends for most tasks.)

To write a user exit, you need to know the following information:

•	supported functions (includes how Graphics Builder gets and passes arguments, and how you can raise errors from the user exit)

•	syntax of a passed user exit call (i.e., what the call looks like when the user exit program receives it)

Note:  We do  not cover all details on how to write and implement a user exit.  Those details vary with the operating system on which you are working and the language in which you choose to write the user exit.


About implementing user exits

In general, implementing a user exit involves the following steps:

•	creating an IAPXTB table and insert into it each user exit name (one row per user exit).

•	generating a source file from the IAPXTB table.

•	compiling the IAPXTB source file and the program you wrote, and then linking the resultant object modules with G30DES, G30RUN, and/or G30BAT.


Building a user exit

To build a user exit:

1	Create your display without user exits.

2	Decide which user exits are needed.

3	Write the user exit using one of the host programming languages.

4	Implement the user exit, which involves the following steps:

   Create an IAPXTB table and insert each user exit name (one row per user exit).

  Generate a source file from the IAPXTB table.

  Compile the IAPXTB source file and the program you wrote, and then link them with G30DES, G30RUN, and/or G30BAT.

5	Create the Graphics Builder object and the user exit call (followed by arguments that you wish to pass).

Note:  Some details of implementing user exits are specific to each operating system.  For more information on the exact steps you need to follow, see the Graphics Builder documentation for your operating system.


Creating the IAPXTB table

To create the IAPXTB table:

  Before you can implement a user exit (on any operating system), you should have available the GENXTB program and GENXTB form.  For more information on how to make these facilities available, see to the Graphics Builder documentation for your operating system.

Use the GENXTB program to create the IAPXTB table, the base table that will be used by the GENXTB form.  For more information on how to use GENXTB program, see to the Graphics Builder documentation for your operating system.  If you do not own Form Builder, create an IAPXTB table yourself using SQL*Plus.  See the SQL*Plus User's Guide and Reference for details on how to create tables.

The IAPXTB table lists all of the user exits that you will link with Graphics Builder.  Below is a description of each column in the IAPXTB table:

Column Name	Description	Usage

XTB$XNM	NAME	This column specifies the name of the  user exit. (This is not necessarily the  name of the file that contains the user  exit.) Note that some host languages  are case-sensitive.
XTB$XTY	TYPE	This column specifies the language in  which the user exit is written.
XTB$REM	REMARKS	This column specifies a text string that  describes the purpose of the user exit.   The string can have a maximum length  of 80 characters.
XTB$CRE	CREATION	This column specifies the date that you  created a record in the IAPXTB table.   When you commit a record, the GENXTB  form automatically enters a value in this  column.
XTB$MOD	MODIFY	This column specifies the date on which  you last modified a record in the IAPXTB  table.  When you commit a record, the  GENXTB form automatically enters a  value in this column.

The table must contain the names of all user exits you wish to use.  For example, if you already have a table with Form Builder user exits in it, you need to add the Graphics Builder packaged user exits (none are provided yet), and any new user exits you create.

Use the GENXTB form, a Form Builder form, to insert descriptions of your user exits into the IAPXTB table.  If you do not have Form Builder, use SQL*Plus to insert the rows (see the SQL*Plus User's Guide and Reference for details on how to insert rows into a table).

You must enter one row in the IAPXTB table for every user exit name.  (This condition is true for ORACLE Precompiler user exits whether a user exit is in a file that will be precompiled and compiled all by itself or with several other user exits.)  Also, you should maintain all production user exits for a system in one IAPXTB table.

The process of implementing a user exit is specific to each operating system.  For more information on the exact steps you need to follow, see to the Graphics Builder documentation for your operating system.

Notes:

You should keep text versions of your user exits in a separate IAPXTB table in case the table is accidentally deleted.


Generating the IAPXTB source file

To generate the IAPXTB source file:

  Use the GENXTB program to read the information in the IAPXTB table and generate its source file.  This source file is the entry point file needed to link your user exits.

Note:  The process of implementing a user exit is specific to each operating system.  For more information on the exact steps you need to follow, see to the Graphics Builder documentation for your operating system.


Compiling the source file and program

To compile the source file and program:

  Compile the IAPXTB source file and your user exit program.  For more information, see the Graphics Builder documentation for your operating system.  Next, link the resulting IAPXTB object file with the G30DES, G30RUN, and/or G30BAT executable(s).

Note:  The process of implementing a user exit is specific to each operating system.  For more information on the exact steps you need to follow, see to the Graphics Builder documentation for your operating system.


Writing a user exit call

To write a user exit call:

You can call the user exit from any place in which you can enter PL/SQL within Graphics Builder .  Use the following syntax:

Syntax:	og_user_exit('user_exit_name [argument_list]');

where:

user_exit_name	Is the name of the user exit to which you are passing control.  The user exit name may be any length.  (On some operating systems, the name may be at most 6 characters.  Check with your system administrator.)

argument_list	Can contain the names of arbitrary parameters that you wish to pass to the user exit.  The argument list may be any length.

Note:  The above syntax will need to be embedded in a PL/SQL button or trigger procedure.

Examples:

Assume you have written a user exit (named INTEGRAL) that computes the area under a curve, based on two points on the curve.  Assume you have four Graphics Builder parameters (named POINT1X, POINT1Y, POINT2X, and POINT2Y) whose values contain the x and y coordinates of the two points.  Your user exit call would look like that below:

og_user_exit('integral point1x point1y point2x point2y');

Finally, assume that you want the user exit program to return (EXEC TOOLS SET) the computed area into an Graphics Builder parameter named AREA.  To do this, you simply write the user exit to SET the value for the AREA parameter.

Rules:

1	User exit names must follow the rules of your operating system and host language.  Be aware that these rules might include case sensitivity rules.

2	Maximum length of the user_exit_name is 10 characters (on some operating systems the limit is 6 characters).  Maximum length of the argument_list is 230 characters.  Spaces are counted.

Note:  These limits may be operating-system dependent.  Consult your system administrator for exact limits.

3	Arguments must be separated by spaces only.  If more than one space exists between arguments in the argument_list, Graphics Builder will delete the extra spaces before it passes the string to the user exit.

For example, the following call:

'quota 10 20     Q4'

is passed to the user exit as:

'quota 10 20 Q4'

4	To reference a literal double quote within an argument list, use \".  The \ will be deleted before the argument is passed.


Checking for user exit errors in PL/SQL

To check for user exit errors in PL/SQL:

  Use  the following exceptions:

OG_USEREXIT_FAILURE_ERROR

OG_USEREXIT_FATAL_ERROR

The OG_USEREXIT_FAILURE_ERROR exception is raised when the user exit returns FAILURE.  The OG_USEREXIT_FATAL_ERROR exception is raised when the user exit returns FATAL.

Example:

Assume you have a user exit called MYEXIT, and you want to check if it failed.  Your user exit call might look like that below:

BEGIN
  og_user_exit('myexit');
EXCEPTION
  WHEN og_userexit_failure_error THEN
    og_quit;
  WHEN og_userexit_fatal_error THEN
    og_quit;
END;


About Graphics Builder file storage

Some systems allow (or require) you to append extensions to the end of file names when you save them.  On these systems, Graphics Builder suggests the following extensions:

Extension	File type	Created by

.afc	AIFF-c sound	exporting a sound
.bmp	BMP image	exporting an image
.cgm	CGM drawing	exporting a drawing
.cht	chart template	exporting a chart template
.jpg	JFIF image	exporting an image
.odf	Oracle Format drawing	exporting a drawing
.ogd	Graphics Builder file	saving a display
.ogr	Graphics Builder Runtime file	generating a display
.oif	Oracle Format image	exporting an image
.osf	Oracle Format sound	exporting a sound
.pal	color palette	exporting a color palette
.pcx	PCX image	exporting an image
.pic	PICT image	exporting an image
.pll	PL/SQL library	saving a PL/SQL library
.pls	PL/SQL program unit	exporting PL/SQL source text
.tif	TIFF image	exporting an image


About file searching

  Related Topics

When you reference a file using PL/SQL built-in subprograms, Graphics Builder searches for the file in the following order:

1	The path prefixed to the file name (e.g., C:\images\product.tif), if any.

2	The path that your operating system considers to be the "current" (or "working") path.  For more information, see the Graphics Builder documentation for your operating system.

3	The path specified by the GRAPHICS30 environment variable.

4	The path specified by the ORACLE_HOME environment variable.


About file extensions and search order

  Related Topics

File names that you specify in Graphics Builder PL/SQL built-ins may contain file extensions.  If the file name you specify includes an extension, Graphics Builder looks for the file whose name exactly matches the one you specify.

If the file name you specify does not include an extension, Graphics Builder first looks for the file exactly as specified.  If the file is not found, Graphics Builder then appends the extension appropriate for that file type and searches for the file again.

For example, if you are importing a TIFF image and specify the file name as budgie, Graphics Builder first looks for the file with that name; if that search fails, Graphics Builder then looks for the file named budgie.tif.


About moving documents between files and the database

You can move the following types of documents between files and the database:

displays

other modules


Moving displays between file system and database

To move a display stored in a file to the database:

1	In the Builder, choose File [image] Open.

2	Choose File [image] Save As [image] Database.

If desired, you can then delete the file in your file system using operating system commands.

To move a display stored in the database to a file:

1	In the Builder, choose File [image] Open.

2	Choose File [image] Save As [image] File System.

If desired, you can then delete the database version of the module by selecting File [image] Administration [image] Delete.


Moving other documents between file system and database

To move another document between file system and database:

  Import it into a display, then export it.  You can move the following documents in this fashion:

•	chart templates

•	color palettes

•	drawings

•	images

•	PL/SQL libraries

•	sounds


Deleting documents

To delete a document stored in a file:

  Use the appropriate operating system commands.

To delete a module from the database:

  Choose File [image] Administration [image] Delete [image] <module_type>.


About executables

Executables are binary files that you use to invoke the Builder, Runtime, and Batch mode components.  Executables are either one-word names, which you type (along with keywords) at a command prompt, or icons that you invoke from a bit-mapped desktop.  The executables should initially appear in the bin subdirectory or folder.

The Graphics Builder executables are listed below:

G30BAT	Runs a builder or runtime file in a non-bitmapped environment, enabling the display's output to be directed to a printer, file, or database.

G30RUN	Runs a display stored in a builder or runtime file.

G30DES	Invokes the Graphics Builder, in which you can create, modify, and test displays.


Command-line syntax rules

  Related Topics

When you invoke an executable on the command line, it generally has the form shown below:

executable_name keyword1=value1 keyword2=value2 ...

Each keyword=value is called an argument.  Because it would be cumbersome to enter the keywords each time, they may be omitted.

The following syntax rules apply to all Graphics Builder executables:

1	No spaces should be placed before or after the equal sign of an argument.

2	Separate arguments with one or more spaces; do not use commas to separate arguments.

3	Values of arguments may be in single or double quotes.  The effect of single or double quotes is system-specific.  For more information, see the Graphics Builder documentation for your operating system.

4	The keyword= part of all arguments is not case-sensitive.  The value portion of all arguments except USERID, PRINT, COPIES, CLOSE, and QUIT may be case-sensitive, depending on your system.  For more information, see the Graphics Builder documentation for your operating system.

5	Keywords may sometimes be omitted.

6	Full pathnames are supported for all file references.

7	Values specified on the command line override Builder or Runtime default values.  For example, if the default printer name is `printer1' and you invoke the Builder from the command line with PRINTER=`printer2', the display will be printed to `printer2'.

Similarly, values explicitly set in an executable override command line values.  For example, if you invoke the Builder and set the printer name on the command line, you can override that printer value by changing it in the Builder.


Keyword usage

The keyword= part of each argument is optional as long as the arguments are entered in the order specified by the syntax.  If you skip one of the arguments, you must use keywords after the skipped argument.

For example, if an executable has four arguments and you want to specify only the first, second, and fourth arguments, you can specify the first two without the keywords.  The fourth requires a keyword, however, because you are not entering it in the order specified by the syntax.

Examples (Valid):

Below are examples of valid command line sequences:

     g30des openfile=my_display print=yes userid=scott/tiger

     g30des my_display scott/tiger print=yes

In this last example, the PRINT keyword must be used because an unused keyword appears in the syntax between USERID and PRINT.

Example (Invalid):

Below is an example of an invalid command line sequence:

     g30des scott/tiger openfile=my_display

This example is invalid because "scott/tiger" has been typed out of order and without the USERID keyword.


Value lists

Most keywords allow you to specify more than just one value.  For example, the OPENFILE and OPENDB keywords accept a value list, indicating that multiple displays will be opened by the executable:

     g30des openfile=(d1,d2,d3)

This allows you to process multiple displays with one command line statement.  For example, you can open multiple displays, export them to CGM files, and print them-all with a single command line statement.

You must surround a value list with parentheses, and place a comma between each value.  Note that some systems have special restrictions on using parentheses and commas on the command line.  For more information, see the Graphics Builder documentation for your operating system.

Value Matching

When you open a single display and specify other keywords on the command line, Graphics Builder performs the actions indicated by the other keywords on the display that is opened.  For example, if you use both the OPENFILE and PRINT keywords in a command line statement, Graphics Builder opens the specified file and prints it:

     g30des openfile=d1 print=yes

If you use a value list to open multiple displays from the command line, and also type a value list for other keywords, Graphics Builder matches the keyword values with the opened displays according to their positions in their value lists.  For example:

     g30des openfile=(d1,d2,d3) print=(yes,no,yes)

In this example, Graphics Builder opens all three displays, but prints only d1 and d3.

If you use both OPENFILE and OPENDB to open displays, the displays opened by OPENFILE take precedence when matched with other keyword values.  For example:

     g30des opendb=(d1,d2) openfile=d3 print=(yes,no,yes)

In this example, d3 and d2 are printed, but d1 is not.

You cannot specify a "null" value for any of the keywords.  For example, you cannot open three displays, and generate only the first and third ones:

     g30des openfile=(d1,d2,d3) generatefile=(g1,,g3)  --invalid

The absence of the second value in the GENERATEFILE value list will result in an error.

Fill-in Values

If a keyword's value list contains fewer values than the number of displays that are opened, Graphics Builder fills in the missing values with either the keyword's last-specified value, or its default value.  The fill-in behavior for each keyword is stated in its description, below.

If a keyword's value list contains more values than the number of opened displays, the extra values are ignored.

Examples:

Below are examples of command line statements:

1	g30run openfile=d1 print=yes copies=2 exportcgm=cgm_file quit=yes

Graphics Builder runs the display d1, prints two copies of it to your default printer, exports it to the CGM file cgm_file, then quits.

2	g30run openfile=(d1,d2) userid=(scott/tiger,steve/lion)

Graphics Builder runs the display d1 using the database userid scott/tiger, and d2 using the database userid steve/lion.

3	g30des openfile=(d1,d2) print=yes

Graphics Builder opens and prints one copy of both d1 and d2 to your default printer.  Note that the PRINT keyword uses its last-specified value (yes) to fill-in missing values.

4	g30des openfile=(d1,d2) opendb=d3 generatefile=(g1,g2) print=(no,no,yes) 	close=(yes,yes)

Graphics Builder opens, generates, and closes d1; opens, generates, and closes d2; and opens, prints, and closes d3.  Note that the GENERATEFILE keyword does not fill-in missing values, and that the CLOSE keyword uses its last-specified value (yes) to fill-in missing values.


Explicit login

You explicitly login to the database by using the USERID keyword for an executable; by selecting File [image] Connect in the Builder or Runtime executables; or by selecting Connect in the SQL Statement Editor dialog box in the Builder.

USERID

Is your ORACLE username and password with an optional SQL*Net protocol.

Options:	The value for this keyword must be in one of the following forms:

username/password

username/password@node

And, if you wish to connect to a non-Oracle datasource,

username/password@ODBC:datasource[:dbname]

If you use the option username/password@ODBC:datasource[:dbname] to connect to an ODBC database without specifying the dbname, the current database for the ODBC connection is used.


Automatic login

The ORACLE automatic login feature allows you to connect to Graphics Builder without explicitly stating a username and password.  You can use the automatic login feature with all Graphics Builder executables.  For more information about using this feature, see the Oracle7 Server Administrator's Guide.

When you connect in this way, ORACLE uses a default logon (e.g., OPS$) to associate your ORACLE username with your operating system username.  To invoke an automatic login procedure, do one of the following:

•	Invoke an executable from the command line with the USERID keyword.  By omitting an explicit username and password, you are telling Graphics Builder to attempt an automatic login.

•	Leave the username and password fields in the Connect dialog box empty.

When logging on in this way, you can access a remote database by typing @node after the USERID keyword, or by typing node in the Connect dialog's Database field.


Remote login

Through SQL*Net, you can specify a remote database (i.e., one not on your local computer).  When you use the remote login feature, the remote database is transparent to you-Graphics Builder behaves the same whether it is accessing a node across the country or accessing the database on your local computer.

Syntax:	driver_name:node_name:db_name

where:

driver_name	Is the driver you want to use to access the remote (i.e., t:, d:, or, for a non-Oracle datasource, ODBC:).  The default setting is system-dependent.

node_name	Is the remote network node that contains the target database (e.g., london).

db_name	Is the name of the data base (e.g., :rds).

For more information about SQL*Net, see the Oracle Network Manager Administrator's Guide.

Example

To run a display off of the INV database on the 'london' node, you might type the following:

g30run openfile=invent.ogd userid=scott/tiger@D:london:INV


Log files

Some systems allow startup error messages to be written to a command line.  On systems that don't support this, Graphics Builder creates a log file in a temporary directory to which startup messages are written.  Each executable has its own log file, as described below:

Executable	Log file name

G30DES	godes.log
G30RUN	gorun.log
G30BAT	gobat.log
The temporary directory in which these files are placed is system-specific.  For more information, see the Graphics Builder documentation for your operating system.


G30DES

Use the G30DES executable to invoke the Graphics Builder, where you create and maintain displays.

Syntax:     g30des [[keyword=]value ]...

where the following are valid keyword=value arguments:

OPENFILE={filename|(filename1,filename2,...)}

USERID={login_string|(login_string1,login_string2,...)}

OPENDB={display_name|(display_name1,display_name2,...)}

PRINT={{YES|NO}|({YES|NO},{YES|NO},...)}

COPIES={n|(n1,n2,...)}

PRINTER={printer_name|(printer_name1,printer_name2,...)}

PRINTFILE={filename|(filename1,filename2,...)}

EXPORTFILE={filename|(filename1,filename2,...)}

EXPORTCGM={filename|(filename1,filename2,...)}

EXPORTBIT={{16|32}|({16|32},{16|32},...)}

EXPORTDB={drawing_name|(drawing_name1,drawing_name2,...)}

EXPORTIMAGE={filename}

GENERATEFILE={filename|(filename1,filename2,...)}

GENERATEDB={display_name|(display_name1,display_name2,...)}

SAVEFILE={filename|(filename1,filename2,...)}

SAVEDB={display_name|(display_name1,display_name2,...)}

CLOSE={{YES|NO}|({YES|NO},{YES|NO},...)}

QUIT={YES|NO}

CMDFILE=filename

LOGFILE=filename

MODULE={filename|(filename1,filename2,...)}

param={value|(value1,value2,...)}


OPENFILE

Is the name of a file that contains the display to be opened.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


USERID

Is your database login string.

Options:	Type any valid database login string.

Default:	None, unless automatic login is enabled.

Fill-in Value::	Last-specified login string.

If the Logon at startup preference setting is checked and you specify a login string here, the Connect dialog box will not appear.


OPENDB

Is the name of a display to be opened that is stored in a database.  You must also login to a database using a USERID argument.

Options:	Type any valid display name.

Default:	None.

Fill-in Value:	N/A


PRINT

Specifies whether the display that was opened with OPENFILE or OPENDB should be printed to a printer specified by a PRINTER argument as soon as it is opened.

Options:	yes means the display will be printed.

Default:	no means the display will not be printed.

Fill-in Value:	Last-specified value.


COPIES

Is the number of copies of the display to print.

Options:	Type any valid integer.

Default:	1

Fill-in Value:	1


PRINTER

Is the name of the printer to which the display will be printed.

Options:	Type any valid printer name.  For more information, refer to your system documentation.

Default:	The default printer name for your system.

Fill-in Value:	Last-specified value; if none, then default printer for your system.


PRINTFILE

Is the name of the file to which the display will be printed in PostScript format.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


EXPORTFILE

Is the name of the file to which the display will be exported as a drawing in the Oracle format.  All layers, whether showing or hidden, will be exported.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


EXPORTCGM

Is the name of the file to which the display will be exported as a drawing in CGM format.  All layers, whether showing or hidden, will be exported.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


EXPORTBIT

Specifies the format for a display exported to a CGM file.

Options:	16 Bit means a 2-byte coordinate space is used.

32 Bit means a 4-byte coordinate space is used.

Default:	16

Fill-in Value:	16


EXPORTDB

Is the name under which the display will be exported to the database as a drawing in the Oracle format.  You must also login to a database using a USERID argument.  All layers, whether showing or hidden, will be exported.

Options:	Type any valid name.

Default:	None.

Fill-in Value:	None.


EXPORTIMAGE

Is the name under which the display will be exported to an image in the format specified by the file extension.  All layers, whether showing or hidden, will be exported.

Options:	Type any valid filename with one of the following extensions:
.gif 	to export the display to a GIF file
.jpg 	to export the display to a JPEG file
.bmp 	to export the display to a bitmap
.tif 	to export the display to a TIFF file
.pict	to export the display to a PICT file

You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


GENERATEFILE

Is the name of the file to which the display will be generated.  When this keyword is used, Graphics Builder compiles all PL/SQL programs in the display.  If any compilation errors occur, error messages will be written to the file specified by LOGFILE, and the resulting generated display will not be complete.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


GENERATEDB

Is the name under which the display will be generated and stored in the database.  You must also login to a database using a USERID argument.  When this keyword is used, Graphics Builder compiles all PL/SQL programs in the display.  If any compilation errors occur, error messages will be written to the file specified by LOGFILE, and the resulting generated display will not be complete.

Options:	Type any valid display name.

Default:	None.

Fill-in Value:	None.


SAVEFILE

Is the name of the file to which the display will be saved.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


SAVEDB

Is the name under which the display will be saved in the database.  You must also login to a database using a USERID argument.

Options:	Type any valid display name.

Default:	None.

Fill-in Value:	None.


CLOSE

Specifies whether the display should be closed after Graphics Builder is finished processing it.

Options:	yes means the display will be closed.

no means the display will not be closed.

Default:	no

Fill-in Value:	no


QUIT

Specifies whether Graphics Builder should quit when finished processing all opened displays.

Options:	yes means Graphics Builder will quit.

no means Graphics Builder will not quit.

Default:	no

Fill-in Value:	N/A


CMDFILE

Is a text file that contains valid G30DES command line arguments.  This allows you to specify many arguments, or a standard set of arguments, without typing them in each time you use Graphics Builder.

This file may contain only arguments that would be value in a single command line construct.  The arguments may be separated by spaces or linefeeds.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


LOGFILE

Is a text file to which Graphics Builder will write error messages if they cannot be shown in an alert.  These errors include non-Graphics Builder errors, as well as errors that occur while Graphics Builder is attempting to process your command line arguments.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


MODULE

Is a synonym for the keyword OPENFILE.


param

Is the name of a parameter that has been defined in your display.  The value of a parameter specified here will supersede the parameter's initial value as set in the display's Parameter Table.

Options:	Type any parameter that is defined in your display's Parameter Table, and a value that is valid for that parameter's datatype.

Default:	Parameters and values as defined in the display's Parameter Table.

Fill-in Value:	Last-specified value.

Parameter values may be listed in single or double quotes, depending on your system's requirements.  For more information, see the Graphics Builder documentation for your operating system.

Examples:

1	g30des openfile=d1 hisparam=26 herparam=`Birthday' ourparam=`14-JULY-94'

2	g30des openfile=(d1,d2,d3) myparam=(5,6)

In this example, myparam will be 5 in d1, and 6 in d2 and d3.


G30RUN

Use the G30RUN executable to run a display from the command line.

Syntax:     g30run [[keyword=]value ]...

where the following are valid keyword=value arguments:

OPENFILE={filename|(filename1,filename2,...)}

USERID={login_string|(login_string1,login_string2,...)}

OPENDB={display_name|(display_name1,display_name2,...)}

PRINT={{YES|NO}|({YES|NO},{YES|NO},...)}

COPIES={n|(n1,n2,...)}

PRINTER={printer_name|(printer_name1,printer_name2,...)}

PRINTFILE={filename|(filename1,filename2,...)}

EXPORTFILE={filename|(filename1,filename2,...)}

EXPORTCGM={filename|(filename1,filename2,...)}

EXPORTBIT={{16|32}|({16|32},{16|32},...)}

EXPORTDB={drawing_name|(drawing_name1,drawing_name2,...)}

EXPORTIMAGE={filename}

CLOSE={{YES|NO}|({YES|NO},{YES|NO},...)}

QUIT={YES|NO}

CMDFILE=filename

LOGFILE=filename

MODULE={filename|(filename1,filename2,...)}

EXECPLSFILE={filename}

ORACLE_STARTUP={YES|NO}

param={value|(value1,value2,...)}


OPENFILE

Is the name of a file that contains the display to be opened.  Any uncompiled PL/SQL programs will be compiled, and then the display will be executed.  If any compilation errors occur, error messages will be written to the file specified by LOGFILE, and the display execution will abort.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


USERID

Is your database login string.

Options:	Type any valid database login string.

Default:	None, unless automatic login is enabled.

Fill-in Value:	Last-specified login string.

If the Logon at startup preference setting is checked and you specify a login string here, the Connect dialog box will not appear.


OPENDB

Is the name of a display to be opened that is stored in a database.  You must also login to a database using a USERID argument.  Any uncompiled PL/SQL programs will be compiled, and then the display will be executed.  If any compilation errors occur, error messages will be written to the file specified by LOGFILE, and the display execution will abort.

Options:	Type any valid display name.

Default:	None.

Fill-in Value:	N/A


PRINT

Specifies whether the display that was opened with OPENFILE or OPENDB should be printed to the printer specified by a PRINTER argument.  The display will be printed after its Open Display trigger has finished executing.

Options:	yes means the display will be printed.

no means the display will not be printed.

Default:	no

Fill-in Value:	Last-specified value.


COPIES

Is the number of copies of the display to print.

Options:	Type any valid integer.

Default:	1

Fill-in Value:	1


PRINTER

Is the name of the printer to which the display will be printed, after its Open Display trigger has finished executing.

Options:	Type any valid printer name.  For more information, refer to your system documentation.

Default:	The default printer name for your system.

Fill-in Value:	Last-specified value; if none, then default printer for your system.


PRINTFILE

Is the name of the file to which the display will be printed in PostScript format, after its Open Display trigger has finished executing.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


EXPORTFILE

Is the name of the file to which the display will be exported as a drawing in the Oracle format.  All layers, whether showing or hidden, will be exported after the display's Open Display trigger has finished executing.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


EXPORTCGM

Is the name of the file to which the display will be exported as a drawing in CGM format.  All layers, whether showing or hidden, will be exported after the display's Open Display trigger has finished executing.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


EXPORTBIT

Specifies the format for a display exported to a CGM file.

Options:	16 Bit means a 2-byte coordinate space is used.

32 Bit means a 4-byte coordinate space is used.

Default:	16

Fill-in Value:	16


EXPORTDB

Is the name under which the display will be exported to the database as a drawing in the Oracle format.  You must also login to a database using a USERID argument.  All layers, whether showing or hidden, will be exported after the display's Open Display trigger has finished executing.

Options:	Type any valid name.

Default:	None.

Fill-in Value:	None.


EXPORTIMAGE

Is the name under which the display will be exported to an image in the format specified by the file extension.  All layers, whether showing or hidden, will be exported.

Options:	Type any valid filename with one of the following extensions:
.gif 	to export the display to a GIF file
.jpg 	to export the display to a JPEG file
.bmp 	to export the display to a bitmap
.tif 	to export the display to a TIFF file
.pict	to export the display to a PICT file

You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


CLOSE

Specifies whether the display should be closed after Graphics Builder is finished processing it.

Options:	yes means the display will be closed.

no means the display will not be closed.

Default:	no

Fill-in Value:	no


QUIT

Specifies whether Graphics Builder should quit when finished processing all opened displays.

Options:	yes means Graphics Builder will quit.

no means Graphics Builder will not quit.

Default:	no

Fill-in Value:	N/A


CMDFILE

Is a text file that contains valid G30RUN command line arguments.  This allows you to specify many arguments, or a standard set of arguments, without typing them in each time you use Graphics Builder.

This file may contain only arguments that would be value in a single command line construct.  The arguments may be separated by spaces or linefeeds.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


LOGFILE

Is a text file to which Graphics Builder will write error messages if they cannot be shown in an alert.  These errors include non-Graphics Builder errors, as well as errors that occur while Graphics Builder is attempting to process your command line arguments.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


MODULE

Is a synonym for the keyword OPENFILE.


EXECPLSFILE

Is the name of a text file containing either a PL/SQL anonymous block or a named procedure to be executed at display start-up.

Options:	Any valid filename.  You must specify a file’s absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


ORACLE_STARTUP

Specifies whether Graphics Builder should execute the OPEN_DISPLAY trigger at start-up.  When used in conjunction with the EXECPLSFILE command line option, ORACLE_STARTUP enables you to substitute a different action for that executed by the OPEN_DISPLAY trigger.

Options:	yes means Graphics Builder will execute the OPEN_DISPLAY trigger.

no means Graphics Builder will suppress the execution of the OPEN_DISPLAY trigger.

Default:	yes

Fill-in Value:	N/A


param

Is the name of a parameter that has been defined in your display.  The value of a parameter specified here will supersede the parameter's initial value as set in the display's Parameter Table.

Options:	Type any parameter that is defined in your display's Parameter Table, and a value that is valid for that parameter's datatype.

Default:	Parameters and values as defined in the display's Parameter Table.

Fill-in Value:	Last-specified value.

Parameter values may be listed in single or double quotes, depending on your system's requirements.  For more information, see the Graphics Builder documentation for your operating system.

Examples:

1	g30run openfile=d1 hisparam=26 herparam=`Birthday' ourparam=`14-JULY-94'

2	g30run openfile=(d1,d2,d3) myparam=(5,6)

In this example, myparam will be 5 in d1, and 6 in d2 and d3.


G30BAT

Use the G30BAT executable to run a display in batch mode, from a bit-mapped or non-bit-mapped terminal.  This executable does not quit automatically when processing is finished.  If your display is stand-alone, include OG_QUIT in a Close_Display trigger.  If your display is embedded in a form, you can force Graphics Builder batch mode to quit by including a call to OG_INTERPRET from a Forms trigger and passing the PL/SQL string, “og_quit;”.

Syntax:     g30bat [[keyword=]value ]...

where the following are valid keyword=value arguments:

OPENFILE={filename|(filename1,filename2,...)}

USERID={login_string|(login_string1,login_string2,...)}

OPENDB={display_name|(display_name1,display_name2,...)}

PRINT={{YES|NO}|({YES|NO},{YES|NO},...)}

COPIES={n|(n1,n2,...)}

PRINTER={printer_name|(printer_name1,printer_name2,...)}

PRINTFILE={filename|(filename1,filename2,...)}

EXPORTFILE={filename|(filename1,filename2,...)}

EXPORTCGM={filename|(filename1,filename2,...)}

EXPORTBIT={{16|32}|({16|32},{16|32},...)}

EXPORTDB={drawing_name|(drawing_name1,drawing_name2,...)}

EXPORTIMAGE=[filename]

CMDFILE=filename

LOGFILE=filename

MODULE={filename|(filename1,filename2,...)}

EXECPLSFILE={filename}

ORACLE_STARTUP={YES|NO}

SHOWTOOLBAR={YES|NO}

SESSIONID={nnnnnn.nnnnnn}

param={value|(value1,value2,...)}


OPENFILE

Is the name of a file that contains the display to be opened.  Any uncompiled PL/SQL programs will be compiled, and then the display will be executed.  If any compilation errors occur, error messages will be written to the file specified by LOGFILE, and the display execution will abort.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


USERID

Is your database login string.

Options:	Type any valid database login string.

Default:	None, unless automatic login is enabled.

Fill-in Value:	Last-specified login string.

If the Logon at startup preference setting is checked and you specify a login string here, the Connect dialog box will not appear.


OPENDB

Is the name of a display to be opened that is stored in a database.  You must also login to a database using a USERID argument.  Any uncompiled PL/SQL programs will be compiled, and then the display will be executed.  If any compilation errors occur, error messages will be written to the file specified by LOGFILE, and the display execution will abort.

Options:	Type any valid display name.

Default:	None.

Fill-in Value:	N/A


PRINT

Specifies whether the display that was opened with OPENFILE or OPENDB should be printed to the printer specified by a PRINTER argument.  The display will be printed after its Open Display trigger has finished executing.

Options:	yes means the display will be printed.

no means the display will not be printed.

Default:	no

Fill-in Value:	Last-specified value.


COPIES

Is the number of copies of the display to print.

Options:	Type any valid integer.

Default:	1

Fill-in Value:	1


PRINTER

Is the name of the printer to which the display will be printed, after its Open Display trigger has finished executing.

Options:	Type any valid printer name.  For more information, refer to your system documentation.

Default:	The default printer name for your system.

Fill-in Value:	Last-specified value; if none, then default printer for your system.


PRINTFILE

Is the name of the file to which the display will be printed in PostScript format, after its Open Display trigger has finished executing.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


EXPORTFILE

Is the name of the file to which the display will be exported as a drawing in the Oracle format.  All layers, whether showing or hidden, will be exported after the display's Open Display trigger has finished executing.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


EXPORTCGM

Is the name of the file to which the display will be exported as a drawing in CGM format.  All layers, whether showing or hidden, will be exported after the display's Open Display trigger has finished executing.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


EXPORTBIT

Specifies the format for a display exported to a CGM file.

Options:	16 Bit means a 2-byte coordinate space is used.

32 Bit means a 4-byte coordinate space is used.

Default:	16

Fill-in Value:	16


EXPORTDB

Is the name under which the display will be exported to the database as a drawing in the Oracle format.  You must also login to a database using a USERID argument.  All layers, whether showing or hidden, will be exported after the display's Open Display trigger has finished executing.

Options:	Type any valid name.

Default:	None.

Fill-in Value:	None.


EXPORTIMAGE

Is the name under which the display will be exported to an image in the format specified by the file extension.  All layers, whether showing or hidden, will be exported.

Options:	Type any valid filename with one of the following extensions:
.gif 	to export the display to a GIF file
.jpg 	to export the display to a JPEG file
.bmp 	to export the display to a bitmap
.tif 	to export the display to a TIFF file
.pict	to export the display to a PICT file

You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	None.


CMDFILE

Is a text file that contains valid G30BAT command line arguments.  This allows you to specify many arguments, or a standard set of arguments, without typing them in each time you use Graphics Builder.

This file may contain only arguments that would be value in a single command line construct.  The arguments may be separated by spaces or linefeeds.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


LOGFILE

Is a text file to which Graphics Builder will write error messages if they cannot be shown in an alert.  These errors include non-Graphics Builder errors, as well as errors that occur while Graphics Builder is attempting to process your command line arguments.

Options:	Type any valid filename.  You must specify a file's absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


MODULE

Is a synonym for the keyword OPENFILE.


EXECPLSFILE

Is the name of a text file containing either a PL/SQL anonymous block or a named procedure to be executed at display start-up.

Options:	Any valid filename.  You must specify a file’s absolute or relative pathname.

Default:	None.

Fill-in Value:	N/A


ORACLE_STARTUP

Specifies whether Graphics Builder should execute the OPEN_DISPLAY trigger at start-up.  When used in conjunction with the EXECPLSFILE command line option, ORACLE_STARTUP enables you to substitute a different action for that executed by the OPEN_DISPLAY trigger.

Options:	yes means Graphics Builder will execute the OPEN_DISPLAY trigger.

no means Graphics Builder will suppress the execution of the OPEN_DISPLAY trigger.

Default:	yes

Fill-in Value:	N/A


SHOWTOOLBAR

Turns Graphics Web toolbar on or off.

Options:	yes means show Graphics Web toolbar.

no means do not show Graphics Web toolbar.

Default:	yes, if no other parameters are included in URL; no, if other parameters are included in URL

Fill-in Value:	N/A

NOTE:  This keyword is only valid when opening a display on the Web, via a URL submitted by the Graphics Web cartridge.


SESSIONID

The unique identifier for the  instance of a Graphics display being viewed via the Graphics Web cartridge.

Options:	Any alpha-numeric session ID number generated by the Graphics Web cartridge.  For example:

sessionid=000001.091032

Default:	N/A

Fill-in Value:	N/A; this number is generated by the Graphics Web cartridge.

NOTE:  This keyword is only valid when opening a display on the Web, via a URL submitted by the Graphics Web cartridge.


param

Is the name of a parameter that has been defined in your display.  The value of a parameter specified here will supersede the parameter's initial value as set in the display's Parameter Table.

Options:	Type any parameter that is defined in your display's Parameter Table, and a value that is valid for that parameter's datatype.

Default:	Parameters and values as defined in the display's Parameter Table.

Fill-in Value:	Last-specified value.

Parameter values may be listed in single or double quotes, depending on your system's requirements.  For more information, see the Graphics Builder documentation for your operating system.

Examples:

1	g30bat openfile=d1 hisparam=26 herparam=`Birthday' ourparam=`14-JULY-94'

2	g30bat openfile=(d1,d2,d3) myparam=(5,6)

In this example, myparam will be 5 in d1, and 6 in d2 and d3.


About SQL scripts

Graphics Builder is shipped with several SQL scripts, with which you can quickly perform some database administration that might otherwise require significantly more time.  These SQL scripts that allow you do to the following:

•	create the database tables used to store modules in the database

•	grant a user access to these tables

•	revoke a user's access to these tables

To run any of the SQL scripts, run SQL*Plus, connect to your database, then type the following:

START script_name

where:

script_name	Is the name of the script you would like to run.

For a list of these scripts, and descriptions of how to use them, see the Graphics Builder documentation for your operating system.

For details on how to use SQL*Plus, see the SQL*Plus User's Guide and Reference.


About installation files

Installation files are SQL scripts used to install Graphics Builder.  For a list of installation files you will use to install Graphics Builder, see the Graphics Builder documentation for your operating system.


About demo files

Certain demo files have been shipped with Graphics Builder.  They are either Graphics Builder files or SQL scripts.  The Builder files are portable binary files that contain definitions of displays.  The SQL scripts create the sample database tables used in the Graphics Builder Developer's Guide.


About administration files

  Related Topics

Administration files are SQL scripts with which you can perform administrative tasks more quickly and easily.


About preference files

Preference settings are stored in a text file in your file system.  Graphics Builder supports the following preference files:

•	user preference file	contains preferences for a single user

•	global preference file	contains preferences that are used if no user preference file is found

Your system may not support both user and global preferences.  For more information, see the Graphics Builder documentation for your operating system.

File Format

Entries in the preference file are generally in the following format:

preference = value

where:

preference	Is the name of the preference.

value	Is the preference's value.  This may be a character string or a number; strings that contain white space must be within double quotes.

Additional Settings

In addition to the preferences you can set in the Preferences dialog, you can also set other values by typing them directly in the preference file.  You can set the following:

environment variables

Keep_Password preference


About environment variables

Regardless of whether your operating system supports them, you can set certain environment variables by listing their names and values in your preference file.

Note:  Only user-defined variables and variables not required to install and run Graphics Builder can be set.

Example

Suppose you want to set the environment variable GRAPHICS30, which points to a directory containing image files.  You can put the following line in your preference file:

GRAPHICS30 = C:\mystuff\images


About Keep_Password

The Keep_Password preference setting specifies whether Graphics Builder keeps the current database user's password in memory while running the display.

The following are valid values for this preference:

•	Yes	Specifies that Graphics Builder keeps the password in memory.

•	No	Specifies that Graphics Builder does not keep the password in memory.

You may want to keep the password in memory so that you can invoke another product and pass it the same username and password currently being used.

You may not want to keep the password in memory if you consider it to be a security risk.

This preference is settable only by typing it directly in the preference file; you cannot set it in the Preferences dialog.

Example

Suppose you want to set this preference so that Graphics Builder keeps the user's password in memory.  You can put the following line in your preference file:

OracleGraphics.Keep_Password = Yes


 Arrange Menu

This section describes the following Graphics Builder Arrange menu items:

Bring to Front

Send to Back

Move Forward

Move Backward

Align Objects

Repeat Alignment

Size Objects

Repeat Sizing

Group

Ungroup

Group Operations


Bring to Front

Moves an object within its group (or layer), placing it in front of every other object in that group (or layer).  The foremost object is always drawn last, overlaying other objects that share the same space on the layout.


Send to Back

Moves an object within its group (or layer), placing it in behind every other object in that group (or layer).  The rearmost object is always drawn first, and may be partially obscured by objects in front of it that share the same space on the layout.


Move Forward

Moves an object within its group (or layer), placing it in front of the one object it is immediately behind.  An object that is in front of another is drawn on top of it, and may partially obscure it if they share the same space on the layout.

You may need to move an object forward more than once if the object that is obscuring it on the layout is not immediately in front of it in their group (or layer).


Move Backward

Moves an object within its group (or layer), placing it behind the one object it is immediately in front of.  An object that is behind another is drawn beneath it, and may be partially obscured if they share the same space on the layout.

You may need to move an object backward more than once if the object it is obscuring on the layout is not immediately behind it in their group (or layer).


Align Objects

Positions the selected objects on the layout, relative to each other or the grid.  Specified alignment settings become the default for aligning objects with the Repeat Alignment menu command.

Dialog Box Options

Align To Each Other

Specifies that the selected objects should be aligned with respect to each other.

Align To Grid

Specifies that the selected object(s) should be aligned with respect to the grid snap points.  Grid Snap does not have to be turned on.

Horizontally

Specifies how you want to align the selected objects horizontally.  You can select from the following options:

None	Specifies that the horizontal positions of the objects do not change.

Align Left	Specifies that the selected objects are moved such that their left sides line up with the left side of the leftmost selected object.

Align Right	Specifies that the selected objects are moved such that their right sides line up with the right side of the rightmost selected object.

Align Center	Specifies that the selected objects are moved such that their horizontal midpoints line up at a horizontal position that is the average of all of their midpoints.

Distribute	Specifies that the selected objects are moved such that there is an equal amount of horizontal space between each object, with the leftmost and rightmost objects retaining their original horizontal positions.

Stack	Specifies that the selected objects are moved such that the left side of each object lines up with the right side of the object immediately to the left of it, with the leftmost object retaining its original position.

Vertically

Specifies how you want to align the selected objects vertically.  You can select from the following options:

None	Specifies that the vertical positions of the objects will not change.

Align Top	Specifies that the selected objects will be moved such that their tops line up with the top of the highest selected object.

Align Bottom	Specifies that the selected objects will be moved such that their bottoms line up with the bottom of the lowest selected object.

Align Center	Specifies that the selected objects will be moved such that their vertical midpoints line up at a vertical position that is the average of all of their midpoints.

Distribute	Specifies that the selected objects will be moved such that there is an equal amount of vertical space between each object, with the highest and lowest objects retaining their original vertical positions.

Stack	Specifies that the selected objects will be moved such that the top of each object lines up with the bottom of the object immediately above it, with the highest object retaining its original position.


Repeat Alignment

Aligns the currently selected objects using the current alignment settings, as specified in the Align Objects dialog box.


Size Objects

Resizes the selected objects relative to each other.  Specified sizing settings become the default for sizing objects with the Repeat Sizing menu command.

Dialog Box Options

Width

Specifies how you want to change the width of the selected objects.  You can select from the following options:

No Change	Specifies that the width of the objects will not change.

Smallest	Specifies that each object will be resized such that its width is equal to the width of the thinnest selected object.

Largest	Specifies that each object will be resized such that its width is equal to the width of the widest selected object.

Average	Specifies that each object will be resized such that its width is equal to the average width of all of the selected objects.

Custom	Specifies that each object will be resized such that its width is equal to the custom width typed here.  The unit of measurement for this value is specified by the Units radio button.

Height

Specifies how you want to change the height of the selected objects.  You can select from the following options:

No Change	Specifies that the height of the objects will not change.

Smallest	Specifies that each object will be resized such that its height is equal to the height of the shortest selected object.

Largest	Specifies that each object will be resized such that its height is equal to the height of the tallest selected object.

Average	Specifies that each object will be resized such that its height is equal to the average height of all of the selected objects.

Custom	Specifies that each object will be resized such that its height is equal to the custom height typed here.  The unit of measurement for this value is specified by the Units radio button.

Units

Specifies the units for custom height and custom width values.


Repeat Sizing

Resizes the currently selected objects using the current sizing settings, as specified in the Size Objects dialog box.


Group

Consolidates all of the selected objects into a group object.  The eight control points of the group object become visible, indicating that it is now one object.


Ungroup

Disbands the selected group object.

The selected group object is destroyed.  All of the children that composed it are moved up one level in the group tree, and are otherwise unmodified.  Each child, then, occupies the same level in the group tree as its former parent, and becomes the new child of its former grandparent.


Group Operations

Provides control over grouping, selecting, and modifying group objects.  This command shows a submenu in which you specify which group operation you want to perform:

Select Parent

Select Children

Add to Group

Remove from Group


Select Parent

Selects the parent group of the currently selected object.  If the selected object is not a member of a group (and therefore has no parent), an error occurs.


Select Children

Selects all of the children of the currently selected group object.  To then select only one of its children, select it.  If the child that you want to select is another group object, select one of its own children to select it.  If the initially selected object is not a group (and therefore has no children), an error occurs.


Add to Group

Makes the currently selected single object a child of the currently selected group object.  You must have at least two objects selected, and exactly one of them must be a group object; if not, an error occurs.


Remove from Group

Removes the currently selected single or group object from its parent group, and moves it up one level in the group tree.  It then becomes a sibling to its former parent, and a child of its former grandparent.  If the selected object is not a member of a group (and therefore has no parent), an error occurs.


 Chart Menu

This section describes the following Graphics Builder Chart menu items:

Create Chart

Frame

Axes

Field Templates

Reference Lines

Update Chart

Convert to Artwork


Create Chart

Creates a chart.

If no queries exist, you are prompted to create one in the New Query dialog box.

If queries exist, you are prompted to choose one or create a new one in the Chart Genie dialog box.

After you specify a query, the Chart property sheet appears.


Frame

Modifies properties of the selected chart's frame.

Select the property page for the options you want to set:

Frame Property Page

Sets depth, shadow, and legend settings.

Axis Frame Property Page (axis chart only)

Sets baseline, category width, and second Y-axis properties.

Pie Frame Property Page (pie chart only)

Sets pie usage, labels, "other" slice definition, and other properties.

Table Frame Property Page (table chart only)

Sets label, grid, number of rows/columns, and other properties.


Axes

Modifies properties of the selected chart's axes.

Select the property page for the options you want to set:

Axis Property Page

Sets label, position, direction, tick mark, grid, and other properties.

Continuous Axis Property Page

Sets axis maximum, minimum, step, and scale.

Date Axis Property Page

Sets maximum, minimum, step, label, and other properties.

Discrete Axis Property Page

Sets minimum and maximum number of categories.


Field Templates

Modifies properties of the selected chart's field templates.

Select the property page for the options you want to set:

Field Property Page

Sets the field template name and color/pattern rotation scheme.

Axis Field Property Page

Sets plot type, line style, label rotation, curve fit, and other properties.


Reference Lines

Modifies properties of the selected chart's reference lines.

Property Sheet Options

Reference Line

Select the reference line to modify.  All reference lines that exist in the selected chart's template appear in this list.

Legend Label

Is the text label that identifies the reference line in the legend.

Value

Is the reference value at which the reference line appears.

Axis Mapping

Specifies with which axis the reference value is compared to determine its position.

New

Creates a new reference line for the selected chart's template.

Delete

Deletes the reference line from the selected chart's template.


Update Chart

Recreates the selected chart based on its associated query and chart template, which may have changed since the last time the chart was drawn.

You may update a chart only if it is a dynamic chart.  If you converted it to artwork using the Convert to Artwork menu command, then it cannot be updated.


Convert to Artwork

Changes a dynamic chart that can be updated to a static chart that cannot be updated.

You should treat a static chart exactly like any other group object; you can select its children, edit single objects, etc.  Remember, though, that the chart can no longer be updated based on its query or template.  In essence, Graphics Builder ceases to consider it a chart.

It is not possible to convert a static chart to a dynamic chart.  If the chart's query and template are still available, however, you can recreate the chart.


 Edit Menu

This section describes the following Graphics Builder Edit menu items:

Undo

Cut

Copy

Paste

Clear

Duplicate

Select All

Select Object

Reduce Resolution

Synchronize Program Units

Search/Replace


Undo

Reverses the most recent operation that you performed.  For example, if you accidentally deleted an object, Undo would retrieve it for you.

Note that certain operations (such as saving a display) cannot be undone.  When this situation arises, the Undo menu item will be inactive.

You cannot select Undo within a dialog box.  To undo changes made in a dialog, select the dialog's Cancel or Close buttons without accepting your changes.


Cut

Deletes the currently selected object(s) or text and stores it on the Clipboard.  You can then use the Paste menu item to place the contents of the Clipboard elsewhere in your display.

Each new Cut operation causes the contents of the Clipboard to be overwritten.  When you undo a Cut operation, the previous contents of the Clipboard are not restored.


Copy

Stores the currently selected objects or text on the Clipboard, without deleting them (as Cut does).  You can then use the Paste menu item to place the contents of the Clipboard elsewhere in your display.

Each new Copy operation causes the contents of the Clipboard to be overwritten.  A Copy operation cannot be undone.


Paste

Places the contents of the Clipboard (i.e., the most recently cut or copied objects or text) on the layout in the current window.

If the Clipboard is empty, or if a paste operation cannot be performed (e.g., a rectangle cannot be pasted into a text field), the Paste menu item is inactive.

A Paste operation does not alter the contents of the Clipboard.  If you wish, you can paste contents of the Clipboard  multiple times.


Clear

Deletes the currently selected objects or text without not storing them on the Clipboard (as Cut does).

A Clear operation does not alter the contents of the Clipboard.


Duplicate

Makes an exact copy of the selected object or objects.

A copy of the selected object or objects appears on the layout, slightly offset from the position of the original.  The original is deselected, and the copy becomes selected.

A Duplicate operation does not alter the contents of the Clipboard.


Select All

Selects every object on the layout.

If there are no objects currently selected when you choose Select All, every object on the active layer of the layout is selected.

If an object is selected when you choose Select All, all of the object's siblings in its group tree are selected.


Select Object

Selects or deselects a named graphical object.

Dialog Box Options

Name

Is name of the object to select or deselect.

Select

Selects the specified object.

Deselect

Deselects the specified object, or removes it from the current selection (if any).


Reduce Resolution

Reduces the resolution of the selected image to the lowest resolution required to show it accurately at its current size.  Graphics Builder discards any excess resolution information.

If you resize an image to be smaller, the default behavior is to maintain the image's original resolution.  However, the smaller image can be shown with a lower resolution than that of the original with no loss of quality.  Reducing the resolution of a resized image may reduce the amount of memory required to manipulate the image, as well as the storage space used to save the display.

You cannot increase an image's resolution.  Therefore, if you make an image smaller, reduce its resolution, then enlarge it back to its original size, the quality of the image will suffer.


Synchronize Program Units

Replaces the state of the program units in the designer display with the current state of the program units in the runtime debugger.  This allows you to test your program units at runtime, modify them to achieve the desired behavior, then incorporate those changes back into the designer display.

This menu item is available only during runtime simulation.

Warning: All program units in the designer display are overwritten by their runtime counterparts.  Designer program units that are deleted during runtime simulation are also deleted from the designer display.


Search/Replace

Searches for and replaces text in PL/SQL program units.  This command is valid only within a program unit editor.

Dialog Box Options

Search

Is the text you want to search for in the program unit.  To search for a regular expression, type it here and select the Regular Expression check box.

Replace with

Is the text to use as the replacement for the found text.

Regular Expression

Specifies whether the search text is a regular expression.  For more information on regular expressions, see your Procedure Builder Developer's Guide.

Case Sensitive

Finds only text that matches the exact use of uppercase and lowercase letters in the search text.

Search

Finds and highlights the next occurrence of the search text.

Replace

Replaces the current selection with the replacement text, and finds the next occurrence of the search text.

Replace All

Replaces all occurrences of the search text with the replacement text, without stopping at and highlighting each occurrence.  Only text that is below the cursor position is changed.


 File Menu

This section describes the following Graphics Builder File menu items:

New

Open

Close

Save

Save As

Revert

Import

Export

Run

Compile

Compile All

Check Consistency

Connect

Disconnect

Administration

Print

Print Setup

Most Recently Accessed Files List

Exit


New

Creates a new display or PL/SQL library.

This menu item shows the following submenu:

Display	Creates a new display.  A node for the new display appears in the Object Navigator, and the display's Layout editor appears.

Library	Creates a new PL/SQL library.  A node for the new library appears under the Open Libraries node in the Object Navigator


Open

Retrieves an existing display that is stored in a file or the database.

While several different displays can be open simultaneously, multiple instances of one display cannot be open in the same Graphics Builder session.

Dialog Box Options

Object Access

Specifies the location of the display to open.  Choosing Database shows the Open from Database dialog box.  Choosing File System shows the Open File dialog for your system.

Display

Specifies the type of files or modules to view when selecting one to open.


Close

Dismisses the current display.

If the display has not been saved since changes were made, a dialog box appears from which you choose to save the changes, discard the changes, or cancel the close operation.


Save

Stores the current display in a file or the database according to the following rules:

•	If the display has previously been saved in the current session, it is saved under the same name and location as before.

•	If the display has been opened but not saved, it is saved under the same name and location from which it was opened.

•	If the display is new and has not yet been saved, the Save To dialog box appears, in which you specify the storage location of the display.


Save As

Stores the current display under a newly specified name and location.

This menu item shows the submenu items listed below.

Database

Shows the Save to Database dialog box.

File System

Shows the Save File dialog for your system.

If the display has never been saved before, the default for Save As is to save the display under the name "Dispx" (where x is some number).  Otherwise, the default is the name under which the display was last opened or saved.


Revert

Discards all changes made to the display and restores it to the state it was in at the last time it was last saved or opened.

Revert behavior follows these rules:

•	If the display has previously been saved in the current session, it will be restored to its state at the time it was last saved.

•	If the display has been opened but not saved, it will be restored to its state at the time it was opened.

•	If the display is new and has not yet been saved, all changes will be discarded and it will be restored to its initial state.


Import

Incorporates a module that is stored in a file or the database into the current display.

Select the submenu item for the object you want to import.

Display

Merges a display that is saved in a database or file into the current display.  Choosing this command shows the Import Display dialog box.

Drawing

Places a line-art drawing into the current layout.  Choosing this command shows the Import dialog box.

Image

Places a bit-mapped image into the current layout.  Choosing this command shows the Import Image dialog box.

Sound

Creates a new sound from one that is stored in the database or file system.  Choosing this command shows the Import Sound dialog box.

Text

Places text from a file into a PL/SQL Program Unit editor.  Choosing this command shows your system's Open File dialog.

Template

Incorporates a chart template that is stored in a file or the database into the current display.  Choosing this command shows the Import dialog box.

Color Palette

Replaces the display's current color palette with a new one.  This menu item is enabled only if the display's color palette mode is Editable, as set in the Tools Options dialog box.  Choosing this command shows the Import dialog box.


Export

Stores a module from the current display into a file or the database.

The following are descriptions of the Export submenu items:

Drawing

Stores the contents of the showing layers into a file or the database.  Choosing this command shows the Export dialog box.

Image

Stores the selected image into a file or the database.  Choosing this command shows the Export Image dialog box.

Sound

Loads a sound into the current display.  Choosing this command shows the Export Sound dialog box.

Text

Places text from a file into a PL/SQL Program Unit editor.  Choosing this command shows your system's Save File dialog.

Template

Stores a chart template from the current display to a file or the database.  Choosing this command shows the Export dialog box.

Color Palette

Stores the current display's color palette into a file or the database.  Choosing this command shows the Export dialog box.


Run

Runs a display in the runtime simulation mode.  This simulates runtime execution of the display and allows you to locate errors in the logic of your PL/SQL code.

When you run a display, Graphics Builder performs a batch compile of all of the PL/SQL code it contains.  If no compilation or other errors are found, the display's Main Layout window appears.


Compile

Compiles all program units in the display that are currently not compiled, and shows the Compile dialog box.  Program units that are already compiled are not affected.


Compile All

Recompiles all program units in the display, regardless of whether they are already compiled, and shows the Compile dialog box.  Program units that are currently compiled are first invalidated, and then recompiled.


Check Consistency

Verifies that there are no inconsistencies among the various parts of your display.  For example, a button procedure whose parameter list has accidentally been deleted will compile correctly, but will not function properly when the display is run.  A consistency check notifies you of this problem.

After a consistency check, one or more of the following messages are shown:

No consistency errors.

Cause:	The display contains no inconsistency errors.

Action:	None.

 <trigger_type>: Procedure `<proc_name>' not found.

Cause:	You named a PL/SQL program unit as a trigger, but Graphics Builder could not find a procedure with that name.

Action:	Verify that:

•	you have defined and compiled the procedure named in the trigger dialog

•	you used the correct name in both the trigger dialog and the procedure's header

•	the program unit you associated with the trigger is a procedure (and not a function or a package)

 <trigger_type>: Procedure `<proc_name>' must be unparameterized.

Cause:	The PL/SQL procedure that you associated with the trigger requires that arguments be passed to it when it is invoked.  Since Graphics Builder invokes trigger procedures without arguments, this is invalid.

Action:	Assign the trigger a procedure that does not require arguments.

Procedure `<proc_name>' associated with object `<obj_name>' does not exist.

Cause:	You associated a PL/SQL button procedure with the object, but Graphics Builder could not find a procedure with that name.

Action:	Verify that the name in the Procedure field of the object's Object Properties dialog matches a procedure that has been defined.

Program unit `<pu_name>' associated with object `<obj_name>' is not a procedure.

Cause:	The program unit you associated with the object is not a procedure.  You cannot associate functions or packages with an object.

Action:	Verify that the name in the Procedure field of the object's Object Properties dialog is that of a valid procedure.

Procedure `<proc_name>' associated with object `<obj_name>' must have exactly four parameters.

Cause:	The header of the PL/SQL procedure you associated with the object does not contain the four arguments required for button procedures.

Action:	Verify that the procedure header contains the four arguments needed.

Procedure `<proc_name>' associated with object `<obj_name>' has incorrect argument types.

Cause:	The header of the PL/SQL procedure you associated with the object contains one or more arguments that are not of the correct type required for button procedures.

Action:	Verify that the procedure header contains arguments that are of the correct type, and that they are listed in the correct order.


Connect

Logs you on to a database.

You can type in each text box separately, or you can type the following all on one line in the User Name text box:

username/password@database

You can also type just the user name and database in the User Name text box, and type the password in the password text box so that it is not displayed:

username@database

Dialog Box Options

User Name

Is the user name of the database account to connect to.

Password

Is the password for the database account.

Database

Is the connect string that specifies the database.  To connect to a remote database, you must also type the appropriate SQL*Net database connect string.


Disconnect

Closes your current database connection.


Administration

Allows you to manage modules stored in the database, generate a runtime display, and manage source control of files.

This menu item shows the submenu items described below.

Access

Grants or revokes access to a module stored in the database.  After you choose a module type from this submenu, the Module Access in Database dialog box is shown.

Delete

Deletes a module stored in the database.  After you choose a module type from this submenu, the Delete from Database dialog box is shown.

Rename

Renames a module stored in the database.  After you choose a module type from this submenu, the Rename dialog box is shown.

Generate

Creates a runtime version of the current display.  If you choose to save it to the database, the Save to Database dialog box is shown.  If you save it to the file system, your system's Save File dialog box is shown.

When you generate a display, any uncompiled PL/SQL program units are automatically compiled.  If compilation or other errors occur, an error message appears and the generate is aborted.

Check In

Invokes the Source Control: Check-in dialog.  This enables you to check in and archive a display file.  This command is available only if the Polytron Version Control System (PVCS) is installed.

When you check in a display file, PVCS performs a binary-to-text conversion automatically and archives the file in the specified location as a text file. .

See also:  Source Control: Check In dialog box.

Check Out

Invokes the Source Control:  Check-out dialog.  This enables you to retrieve a display file that has previously been checked into a source control archive.  This command is available only if the Polytron Version Control System (PVCS) is installed.

Archived files are stored as text files.  When you check out a file, Graphics Builder automatically converts the text file to a binary file (.OGD) suitable for editing in the Designer.

See also:  Source Control: Check Out dialog box.

Source Control Options

Invokes the Source Control Options dialog.  This enables you to set source control system options.  This command is available only if the Polytron Version Control System (PVCS) is installed.

See also:  Source Control: Options dialog box.


Print

Prints the layout to the default printer.

Only the layers that are showing will be printed.

Your system may display a Printer dialog when the Print menu item is chosen.  For more information, refer to your system documentation.


Print Setup (Page Setup)

Sets page size, orientation, and other output-related settings.

This dialog is system-specific.  For more information, refer to your system documentation.


Most Recently Accessed Files List

Lists the four most recently accessed files, in descending order.  Possible filetypes are .ogd and .pll.  Double-clicking the filename of an .ogd file opens that file in the designer, while double-clicking the filename of a .pll file loads the library.


Exit (Quit)

Ends your Graphics Builder Designer session.

All open displays are closed, and the session is ended.  If any displays have been modified since they were last saved or opened, you will be prompted to save the changes, discard the changes, or abort the exit operation.


 Format Menu

This section describes the following Graphics Builder Format menu items:

Font

Spacing

Alignment

Direction

Line

Dash

Bevel

Arrow

Symbol

Drawing Options

Color Palette

Number

Date


Font

Sets the font typeface of the selected text.  On some systems, Font shows a submenu containing a list of fonts; on others, Font shows a dialog box.

The available fonts are system-specific, but may include options such as Times, Helvetica, and Courier.  For more information, refer to your system documentation.

If a text object is selected, the font you choose is applied to all of the text in that object.  If only a segment of text within a text object is selected, the chosen font is applied only to that segment.

The chosen font becomes the default for all subsequently created text, whether or not text was selected when the font was chosen.


Spacing

Set the inter-line spacing of a text object.

This menu item shows the following submenu options:

Single

Means inter-line spacing is equal to the point size of the largest text segment on each line.

1 1/2

Means inter-line spacing is equal to one-and-one-half times the point size of the largest text segment on each line.

Double

Means inter-line spacing is equal to twice the point size of the largest text segment on each line.

Custom

Sets inter-line spacing to a custom amount.  Choosing this submenu item shows the Custom Spacing dialog box, described below.

Dialog Box Options

Select a spacing size, or select Custom and type an amount in the corresponding text box.


Alignment

Set the alignment of text within a text object, relative to its bounding box.

This menu item shows the following submenu options:

Left

Aligns the left side of each line of text with the left edge of the text object's bounding box.

Center

Aligns the center of each line of text with the horizontal center of the text object's bounding box.

Right

Aligns the right side of each line of text with the right edge of the text object's bounding box.

Start

Aligns the text to the start point indicated by your system's language settings.  For example, an English language system would align text to the left, and an Arabic language system would align text to the right.

End

Aligns the text to the end point indicated by your system's language settings.  For example, an English language system would align text to the right, and an Arabic language system would align text to the left.


Direction

Set the direction in which new text is inserted into the text object.

This menu item shows the following submenu options:

Default

Inserts new text in the direction indicated by your system's language settings.  For example, an English language system would insert text from left to right, and an Arabic language system would insert text from right to left.

Left to Right

Inserts new text from left to right.

Right to Left

Inserts new text from right to left.


Line

Sets the line width of a line or an object's edge.

Choose a line width from the submenu.  Choosing Custom shows the Custom Line Width dialog, described below.

Dialog Box Options

Width

Is the line width.

Units

Is the unit of measurement in which the width is specified.


Dash

Set the dash style of a line or an object's edge.

Choose the desired dash style from the submenu.


Bevel

Set the bevel style of a line or an object's edge.

Choose the desired bevel style from the submenu.


Arrow

Sets the arrow style of a line.

Choose the desired arrow style from the submenu.


Symbol

Sets the size of a symbol.

Choose the desired symbol size from the submenu.


Drawing Options

Sets drawing styles and options.

Select the submenu item for the options you want to set:

General

Sets cap and join styles, draw from corner/center, and transfer mode.

Arc

Sets arc fill and closure styles.

Text

Sets text origin, bounding box, word wrap, and other options.

Rounded Rectangle

Sets rounded rectangle corner radii.

Image

Sets image quality and dithering options.


Color Palette

Changes the colors defined in the color palette.

This menu item is enabled only if the Color Palette Mode in the Tools Options dialog box is set to Editable.

Since the color palette is saved with the display, any changes you make to the palette are also saved.

Dialog Box Options

Select Color to Edit

Shows the contents of the current color palette.  Select a color cell to modify the color it contains.

Current Color

Is the name of the color that is currently selected in the palette.  To change its name, type a new name in this text box, then select Rename.

Edit

Shows a system-specific dialog that allows you to change the definition of the selected color.  For more information, refer to your system documentation.

Rename

Changes the name of the selected color to the name appearing in the Current Color text box.


Number

Adds, removes, or applies available number format masks.  You cannot apply a format mask to a text object that is not a chart element.

Choosing this menu item shows the Number Format dialog box.


Date

Adds, removes, or applies available date format masks.  You cannot apply a format mask to a text object that is not a chart element.

Choosing this menu item shows the Date Format dialog box.


 Help Menu

The Help menu is system-specific.  For more information, refer to your system documentation.  However, the menu items listed below always appear:

Contents

Cue Cards

Quick Tour

Get Module Info

About Graphics Builder


Contents

Invokes the Graphics Builder help system.  If applicable, the help system uses the standard help interface for your operating system.  If not, the Oracle Help system is shown.


Cue Cards

Invokes the Cue Cards, which are instructional cards providing assistance on performing many basic Graphic Builder tasks.


Quick Tour

(New topic text goes here.)

Invokes the Quick Tour, an overview of tools available with Graphic Builder and the basic steps involved in the display-building process.


Get Module Info

Shows the creation and revision information for the current display.

Dialog Box Options

Created

Shows information about the display creation, if the display is stored in the database.

By	Is the user name of the user who first saved the display in the database.

Date	Is the date at which the display was first saved in the database.

Version	Is the Graphics Builder version used to create the display.

Last Modified

Shows information about the display modification, if the display is stored in the database.

By	Is the user name of the user who most recently saved the display in the database.

Date	Is the date at which the display was most recently saved in the database.

Version	Is the Graphics Builder version used to most recently update the display.

Copyright

Shows copyright information about the display.  Copyright is useful is you plan to distribute the display to others.  It also appears in the Get Module Info dialog box in the Graphics Builder Runtime executable.  Type text here that you want to be shown within runtime versions of the display that you distribute.  The default for this field is the contents of the Copyright Message field in the Tools Options dialog box.


About Graphics Builder

Shows information about the Graphics Builder executable, including the version number and copyright notice.


 Navigator Menu

This section describes the following Graphics Builder Navigator menu items:

Create

Delete

Expand

Collapse

Expand All

Collapse All

Set Mark

Go to Mark

Navigator Options


Create

Creates a new object that is the same type as the currently selected object or heading node.


Delete

Deletes the currently selected object.


Expand

Shows the immediate children of the currently selected node.


Collapse

Hides the immediate children of the currently selected node.


Expand All

Recursively expands the children nodes of the currently selected node.


Collapse All

Recursively collapses the children nodes of the currently selected node.


Set Mark

Places a reference mark at the currently selected node.  This allows you to work with other objects in the Object Navigator, then return to the marked node by choosing the Go to Mark menu item.


Go To Mark

Selects the node that was previously marked by choosing the Set Mark menu item.


Navigator Options

Sets options that determine the appearance of objects in the Object Navigator.

Dialog Box Options

Show Reference Nodes

Shows nodes under an object that represent other objects that the object references.  For example, a chart object contains a Query node, which shows the query that the chart references.

Show Reference-by Nodes

Shows nodes under an object that represent references to that object by other objects.  For example, a query object may show that the query is referenced by a chart.


 Template Menu

This section describes the following Graphics Builder Template menu items:

Create

Rename

Delete

Frame

Axes

Field Templates

Reference Lines


Create

Creates a new chart template.

When you create a new display, the Chart Template editor initially contains no chart templates.  To create the very first template, you can:

•	Choose Template [image] Create, as described here.

•	Choose a chart type from the Type menu.  A new chart template named “template0” is automatically created.

After you accept this dialog, a new chart template appears in the Chart Template editor.

Dialog Box Options

Chart Type

Is the type of chart to create.  Select an icon to select a chart type.

Template Name

Is the template name.


Rename

Changes the name of the template that is showing in the Chart Template editor.

Dialog Box Options

Template Name

Is the new name for the template.


Delete

Deletes the template that is showing in the Chart Template editor.


Frame

Modifies properties of the frame of the template that is showing in the Chart Template editor.

Select the property page for the options you want to set:

Frame Property Page

Sets depth, shadow, and legend properties.

Axis Frame Property Page (axis chart only)

Sets baseline, category width, and second Y-axis properties.

Pie Frame Property Page (pie chart only)

Sets pie usage, labels, "other" slice definition, and other properties.

Table Frame Property Page (table chart only)

Sets label, grid, number of rows/columns, and other properties.


Axes

Modifies properties of the axes of the template that is showing in the Chart Template editor.

Select the property page for the options you want to set:

Axis Property Page

Sets label, position, direction, tick mark, grid, and other properties.

Continuous Axis Property Page

Sets axis maximum, minimum, step, and scale.

Date Axis Property Page

Sets maximum, minimum, step, label, and other properties.

Discrete Axis Property Page

Sets minimum and maximum number of categories.


Field Templates

Modifies properties of the field templates for the chart template that is showing in the Chart Template editor.

Select the property page for the options you want to set:

Field Property Page

Sets the field template name and color/pattern rotation scheme.

Axis Field Property Page

Sets plot type, line style, label rotation, curve fit, and other properties.


Reference Lines

Modifies properties of the reference lines of the template that is showing in the Chart Template editor.

Property Sheet Options

Reference Line

Select the reference line to modify.  All reference lines that exist in the current template appear in this list.

Legend Label

Is the text label that identifies the reference line in the legend.

Value

Is the reference value at which the reference line appears.

Axis Mapping

Specifies with which axis the reference value is compared to determine its position.

New

Creates a new reference line for the current template.

Delete

Deletes the reference line from the current template.


 Tools Menu

This section describes the following Graphics Builder Tools menu items:

Properties

PL/SQL Interpreter

Program Units

Stored Program Units

Database Triggers

Display

Layers

Parameters

Queries

Templates

Timers

Tools Options


Properties

Sets properties for the selected object.  You can select an object either on the Layout or in the Object Navigator.

Select the type of object to modify:

Chart

Sets chart type, query, categories, values, and other properties.

Display

Sets Open Display and Close Display triggers, and changes the parameter date format.

Graphic Object

Sets name, button procedure, and drill-down properties.

Layer

Creates, deletes, hides, shows, activates, and renames layers.

Parameter

Creates and deletes parameters, and sets name, data type, and initial value.

Query

Creates and deletes queries, and sets data source and other properties.

Template

Shows the Chart Template editor.  Creates and deletes chart templates, and sets frame, field template, axis, and other properties.

Timer

Creates and deletes timers, and sets timer name, trigger procedure, and time interval.

Tools Options


PL/SQL Interpreter

Shows the PL/SQL Interpreter, in which you execute and debug PL/SQL program units.  For more information, see the Procedure Builder Developer's Guide.


Program Units

Shows the Program Unit editor, in which you create and edit PL/SQL program units.  For more information, see the Procedure Builder Developer's Guide.


Stored Program Units

Shows the Stored Program Unit editor, in which you create and edit stored PL/SQL program units.  For more information, see the Procedure Builder Developer's Guide.


Database Triggers

Shows the Database Trigger editor, in which you create and edit database triggers.  For more information, see the Procedure Builder Developer's Guide.


Display

Sets Open Display and Close Display triggers, and changes the parameter date format.

Property Sheet Options

Open Trigger

Is the name of the PL/SQL procedure that is executed when the display is first opened at runtime.  Only procedures that have a valid open trigger procedure header appear in this list.

New

Creates a new Open Display trigger.

Close Trigger

Is the name of the PL/SQL procedure that is executed when the display is closed at runtime.  Only procedures that have a valid close trigger procedure header appear in this list.

New

Creates a new Close Display trigger.

Parameter Date Format

Specifies the date format mask used to recognize valid values for parameters of type DATE.

List

Shows the date format masks currently available in the display, and allows you to add or delete masks.  Choosing the button shows the Date Format dialog box.

Direction

Determines the default direction of text, arrows, etc. for bi-directional NLS support.  Choose Left to Right, Right to Left, or Default (determined by current language).


Layers

Creates, deletes, hides, shows, activates, and renames layers.

Dialog Box Options

Existing Layers

Shows the layers that exist in the display.  The order of the layers in the list determines how their objects appear on the layout.  Each layer's objects overlay the objects of all showing layers that are beneath it in the list.

New

Creates a new, empty layer named "layerx" (where x is some number).

Delete

Removes the layer that is selected in the list.  All of the objects on that layer will also be deleted.

Hide/Show

Hides the selected layer if it is showing, or shows it if it is hidden.  A `+' next to the layer name in the list indicates that it is currently showing; a `-' indicates that it is hidden.  You cannot hide the active layer.

Activate

Makes the selected layer active.  If the layer is hidden, it will be automatically be set to be showing.  To deactivate a layer, make another layer active.

Up/Down/Top/Bottom

Moves the selected layer up one position in the list, down one position in the list, to the top of the list, or to the bottom of the list.  The order of the layers in the list determines how their objects appear on the layout.  Each layer's objects will overlay the objects of all showing layers that are beneath it in the list.

Active Layer

Shows the name of the currently active layer.  Only one layer can be active at a time.

New Name

Is the new name for the selected layer.  Select Rename to rename the layer.

Rename

Renames the selected layer to the name specified in the New Name text box.


Parameters

Creates and deletes parameters, and sets name, data type, and initial value.

Property Sheet Options

Parameter

Select the parameter to modify.  All parameters that exist in the display appear in this list.

Name

Is the name of the parameter.

Type

Is the datatype of the parameter.

Initial Value

Is the parameter's initial value when you first run the display.  The value entered here can be superseded by a value specified on the command line, and you can change the value at runtime.

The length of a parameter value cannot exceed 2000 bytes.


Queries

Creates and deletes queries, and sets data source and other properties.

Select the property page for the options you want to set:

Query Property Page

Sets the name, data source and SQL statement (if needed) for a query.

Data Property Page

Shows the data returned by the query.

Options Property Page

Sets execution and data caching properties, triggers, and other properties.

Schema Property Page (custom queries only)

Creates and deletes, and sets the name and datatype of custom columns.


Query Property Page

Sets the name, data source and SQL statement (if needed) for a query.

Property Page Options

Query

Select the query to modify.  All queries that exist in the display appear in this list.

Name

Is the name of the query.

Type

Is the type of query.  Select one of the following options:

SQL Statement  	Means the query retrieves its data from a database, based on a SQL SELECT statement you provide.  Enter the SQL statement in the SQL Statement text box.

SYLK File    	Means the query retrieves its data from a file that is in the SYLK format.  SYLK is a format used by several popular applications, such as Microsoft Excel.  When you execute the query, the data is read from the file.  Specify the file to use in the File text box.

WKS File    	Means the query retrieves its data from a file that is in the WKS format.  WKS is a format used by several popular applications, such as Lotus 1-2-3.  When you execute the query, the data is read from the file.  Specify the file to use in the File text box.

PRN File    	Means the query retrieves its data from a file that is in the PRN format.  PRN is a text file format.  When you execute the query, the data is read from the file.  Specify the file to use in the File text box.

Custom	Allows you to customize the query's columns and data.  To set the columns, use the controls that appear on the Schema property page.  To set the data, use the built-in procedure OG_APPEND_ROW.

External SQL File	Means the query retrieves its data from a text file that contains a SQL SELECT statement.  When you execute the query, the SQL statement is read from the file and executed.  Specify the file to use in the File text box.

File

Shows the location and name of the file to use for a SYLK, WKS, PRN, or External SQL query.  To locate the file in your file system, Select the Browse button.

Browse

Allows you to locate and select the filename to show in the File text box.

SQL Statement

Is the SQL SELECT statement that is executed for a SQL Statement query.

Connect

Shows the Connect dialog box, allowing you to connect to a database.

Import SQL

Allows you to place the contents of a text file into the SQL Statement text box.  Note that the text is copied, not linked to the file.  To create a link to SQL text in a file, use a query type of External SQL File.

Export SQL

Allows you to place the contents of the SQL Statement text box into a file.

New

Creates a new query.

Delete

Deletes the current query.

Execute

Executes the current query.  If the query is a SQL SELECT statement, the data is retrieved from the databae.  If the query retrieves data from a file, the file is read.  If the query is a custom query, its custom query procedure is executed.

Clear Data

Clears the data cache of all data retrieved.  This does not delete or in any way modify the query itself.


Data Property Page

Shows the data returned by the query.  Select a cell to show its contents in the text box above the spread table.  The top row of the spread table shows the column names and datatypes.

Property Page Options

Query

Select the query to modify.  All queries that exist in the display appear in this list.

New

Creates a new query.

Delete

Deletes the current query.

Execute

Executes the current query.  If the query is a SQL SELECT statement, the data is retrieved from the database.  If the query retrieves data from a file, the file is read.  If the query is a custom query, its custom query procedure is executed.

Clear Data

Clears the data cache of all data retrieved.  This does not delete or in any way modify the query itself.


Options Property Page

Sets execution and data caching properties, triggers, and other properties.

Property Page Options

Query

Select the query to modify.  All queries that exist in the display appear in this list.

Execute on

Specifies when the query is automatically executed.  Select from the following options:

Opening Display	Executes the query when the display is first opened at runtime.

Timer	Executes the query at the frequency specified by a timer.  Select a timer from the drop-down list, or select New to create a new timer.

Data

Sets several options related to the queries data.

New Data	Determines how the newly retrieved data from a query execution is treated.

Replaces Old Data means all of the data from the previous execution is discarded, and the newly retrieved data replaces it.

Appends to Old Data means all of the existing rows of data are retained, and the new rows of data are added to the bottom of the existing data set.

Save Old Data	Specifies whether previously retrieved data is stored in a special buffer when it is replaced by new data.  You can then access this "old data" buffer using built-in routines such as OG_GET_NUMCELL.  This property is valid only when the New Data setting is Replaces Old Data.

Maximum Number of Rows	Specifies the maximum number of rows of data that are retained in the query's data set.  If appending data causes the number of rows to exceed this maximum, excess rows are discarded from the top of the data set.  This property is valid only when the New Data setting is Appends to Old Data.  In addition, the maxflag attribute for the query must be set to TRUE (the default).  For more information on setting the maxflag, see Maximum Rows Flag Property.

Date Format  	Specifies the format used to recognize date data from a file, and determines how dates appear in the Data property page.  If the dates in the file are in a format other than the one specified here, Graphics Builder will not recognize them as dates.

PL/SQL

Sets several options related to the use of PL/SSQL by the query.

Custom Execute Procedure	(Custom queries only.)  Is the PL/SQL procedure that is invoked when a Custom query is executed.  Typically, this procedure contains PL/SQL statements that populate the query with data.  Only procedures that have a valid custom query trigger procedure header appear in this list.

Select New to create a new custom query procedure.

Post-Execution Trigger	Is the PL/SQL procedure that is invoked after the query is executed.  Only procedures that have a valid post-query trigger procedure header appear in this list.

Select New to create a new post-execution procedure.

New

Creates a new query.

Delete

Deletes the current query.

Execute

Executes the current query.  If the query is a SQL SELECT statement, the data is retrieved from the database.  If the query retrieves data from a file, the file is read.  If the query is a custom query, its custom query procedure is executed.

Clear Data

Clears the data cache of all data retrieved.  This does not delete or in any way modify the query itself.


Schema Property Page

(Custom queries only.)  Creates and deletes, and sets the name and datatype of columns in a custom query.

Property Page Options

Query

Select the query to modify.  All queries that exist in the display appear in this list.

Column

Select the column to modify.  All columns that have been defined for this query appear in this list.

Name

Is the column name.  To change the column name, type a new name here and select Apply.

Type

Is the column datatype.

Maximum Length

Is the maximum length of the data contained in the column.  This applies only to columns of type CHAR.

New Column

Adds a new column to the query.

Delete Column

Removes the current column from the query.

New

Creates a new query.

Delete

Deletes the current query.

Execute

Executes the current query.  If the query is a SQL SELECT statement, the data is retrieved from the databae.  If the query retrieves data from a file, the file is read.  If the query is a custom query, its custom query procedure is executed.

Clear Data

Clears the data cache of all data retrieved.  This does not delete or in any way modify the query itself.


Templates

Shows the Chart Template editor.  Creates and deletes chart templates, and sets frame, field template, axis, and other properties.


Timers

Creates and deletes timers, and sets timer name, trigger procedure, and time interval.

Property Sheet Options

Timer

Select the timer to modify.  All timers that exist in the display appear in this list.

Name

Is the name of the timer.

Procedure

Is the PL/SQL procedure (if any) that is executed when the timer fires.  Only procedures that have a valid timer trigger procedure header appear in this list.

To create a new timer procedure, select New.

Interval

Is the amount of time that passes between each firing of the timer.

Active

Specifies whether the timer fires.

New

Creates a new timer.

Delete

Deletes the current timer.


Tools Options

Changes various Graphics Builder options.

Select the dialog tab for the options you want to set:

Defaults Tab

Sets copyright message, color palette, number/date format lists, and page size.

Preferences Tab

Sets startup options, and other general settings.


Defaults Tab

Sets copyright message, color palette, number/date format lists, and page size.

Dialog Box Options

Copyright Message

Is the default text that will appear in a newly created display's Get Info dialog in the Copyright field.  This setting takes effect with the next display you create or open.

Color Palette

Sets options related to the color palette in use.

File	Is the name of the file that contains the color palette to be used for any new displays you create.  If this field is blank, Graphics Builder uses its default color palette.  This field must contain the color palette's full or relative pathname.  This setting takes effect with the next display you create or open.

Mode	Determines how a display's color palette is implemented on your system.  Each time you make a different display active, Graphics Builder tries to modify your system's color palette to match--or come as close as possible to--that display's color palette.  Since your system can handle only a limited number of colors at once, Graphics Builder may not be able to accurately show multiple displays simultaneously if they are using different color palettes.   This setting takes effect with the next display you create or open.  The list contains the following options:

Editable means Graphics Builder temporarily replaces your system's color palette with the palette of the active display.  Each time a new display is made active, its color palette replaces the system palette.  The active display will then be shown accurately, although the appearance of the inactive displays may suffer.  The palette must be Editable in order to modify or import a color palette.

Read Only - Shared means Graphics Builder continues to append each active display's color palette to your system's original palette until there is no room left in the palette for any more colors.  That palette becomes the single palette that all open displays share.  If you make a display that uses entirely different colors active, it may not be shown accurately.

Read Only - Private means each time you make a display active, Graphics Builder appends that display's color palette to your system's original palette until there is no room left in the palette for any more colors.  That palette becomes the palette that is used whenever that display is active.  The active display is then shown accurately, although the appearance of the inactive displays may suffer.

Format Lists

Sets the date and number formats that are available by default in the number and date format dialog boxes.  This setting takes effect immediately.  You can choose the following buttons:

Date	Sets the date format masks, and shows the Date Format dialog box.

Number	Sets the number format masks, and shows the Number Format dialog box.

Page Size

Sets the width, height, and units of a physical page, which determines the placement of page break lines on the layout.  Note that the layout can be larger than the page size.

Save

Accepts the options and saves them in your options file.


Preferences Tab

Sets startup options, and other general settings.

Dialog Box Options

Startup

Sets several options that control the behavior of Graphics Builder when you first run it.

Open	Determines whether Graphics Builder opens or creates a display by default.

No Display means no display is initially created or opened when you first run Graphics Builder.

New Display means Graphics Builder automatically creates a new display and shows its Layout editor.

Open File means Graphics Builder automatically shows the Filter dialog box, allowing you to initially open a display from a file.

Logon at Startup	Shows the Connect dialog box when you first run Graphics Builder.  If you connect to a database using the USERID executable argument, the Connect dialog does not appear.  This setting takes effect the next time you run an Graphics Builder executable.

General

Sets general options.

Sound Output

Is the output device to be used when playing sounds.  The items that appear in this list are system-specific.  For more information, refer to your system documentation.  This setting takes effect immediately.

Image Compression

Specifies the compression scheme used to compress all image in the display when you save or generate a display, or copy an image to the Clipboard.

If you select a compression scheme that is not applicable to an image in the display, that image is not compressed.  For example, if you select PackBits and save a display containing a color image, that image is not compressed.  This setting takes effect with the next display you create or open.

Automatic Character Set Conversion

Specifies whether Graphics Builder automatically converts a display's text into the character set specified by the NLS_LANG environment variable when the display is opened.  This setting takes effect with the next display you create or open.

Smooth Redraw at Runtime

Determines how Graphics Builder updates portions of the layout that are affected by drawing operations.  This setting takes effect at Runtime.

If this setting is off, Graphics Builder individually draws each modified object within a damage region.

If this setting is on, Graphics Builder first renders each of the modified objects in an internal buffer.  When the rendering is complete, the layout is updated with a single redraw.

Smooth Redraw significantly reduces flickering of the layout as it is updated.  However, if the damage region is large, the internal buffer generated by Smooth Redraw may require a large amount of memory.  We recommend that you leave Smooth Redraw on unless you encounter memory problems.

Keep Backup File

Specifies whether Graphics Builder keeps a backup copy of the display each time you save it.  The backup file has the same base name as the original, and the filename extension is changed to .bak.  For example, if you save the display trends.ogd, the backup file is named trends.bak.

Apply Properties on Navigation

Specifies whether changes in a property sheet are automatically applied when you show another object's properties in that property sheet (e.g., by selecting another object from the property sheet's drop-down list).  If this check box is not on, you will be prompted to save pending changes when necessary.

Apply Query Properties on Navigation

Specifies whether changes in the Query property sheet are automatically applied when you execute the query.  If this check box is not on, you will be prompted to save pending changes when necessary.

Save

Accepts the options and saves them in your options file.


 Type Menu

The Type menu contains pre-defined templates for each of the chart types supported by Graphics Builder.  These templates are starting points for you to use when customizing your own templates.  This section describes the following Graphics Builder Type menu items:

Column

Bar

Line

Mixed

Pie

Double-Y

High-Low

Gantt

Scatter

Table


Column

Shows a submenu containing predefined column chart templates.  If a template is showing in the Chart Template editor, choosing a predefined template from this menu replaces the properties of the existing template.  If no templates currently exist, choosing one from this menu creates a new template with the chosen default properties.


Bar

Shows a submenu containing predefined bar chart templates.  If a template is showing in the Chart Template editor, choosing a predefined template from this menu replaces the properties of the existing template.  If no templates currently exist, choosing one from this menu creates a new template with the chosen default properties.


Line

Shows a submenu containing predefined line chart templates.  If a template is showing in the Chart Template editor, choosing a predefined template from this menu replaces the properties of the existing template.  If no templates currently exist, choosing one from this menu creates a new template with the chosen default properties.


Mixed

Shows a submenu containing predefined mixed chart templates.  If a template is showing in the Chart Template editor, choosing a predefined template from this menu replaces the properties of the existing template.  If no templates currently exist, choosing one from this menu creates a new template with the chosen default properties.


Pie

Shows a submenu containing predefined pie chart templates.  If a template is showing in the Chart Template editor, choosing a predefined template from this menu replaces the properties of the existing template.  If no templates currently exist, choosing one from this menu creates a new template with the chosen default properties.


Double-Y

Shows a submenu containing predefined double-Y chart templates.  If a template is showing in the Chart Template editor, choosing a predefined template from this menu replaces the properties of the existing template.  If no templates currently exist, choosing one from this menu creates a new template with the chosen default properties.


High-Low

Shows a submenu containing predefined high-low chart templates.  If a template is showing in the Chart Template editor, choosing a predefined template from this menu replaces the properties of the existing template.  If no templates currently exist, choosing one from this menu creates a new template with the chosen default properties.


Gantt

Shows a submenu containing predefined Gantt chart templates.  If a template is showing in the Chart Template editor, choosing a predefined template from this menu replaces the properties of the existing template.  If no templates currently exist, choosing one from this menu creates a new template with the chosen default properties.


Scatter

Shows a submenu containing predefined scatter chart templates.  If a template is showing in the Chart Template editor, choosing a predefined template from this menu replaces the properties of the existing template.  If no templates currently exist, choosing one from this menu creates a new template with the chosen default properties.


Table

Shows a submenu containing predefined table chart templates.  If a template is showing in the Chart Template editor, choosing a predefined template from this menu replaces the properties of the existing template.  If no templates currently exist, choosing one from this menu creates a new template with the chosen default properties.


 View Menu

This section describes the following Graphics Builder View menu items:

Normal Size

Fit to Window

Zoom In

Zoom Out

Rulers

Ruler Guides

Grid

Grid Snap

Page Breaks

Tool Palette

Status Bar

View Options


Normal Size

Restores the magnified layout to normal magnification.


Fit to Window

Demagnifies the layout so that the entire layout is visible at once.


Zoom In

Magnifies the layout by a factor of 2x.


Zoom Out

Demagnifies the layout by a factor of 1/2x.


Rulers

Shows or hides the rulers on the layout.


Ruler Guides

Shows or hides the ruler guides on the layout.


Grid

Shows or hides the grid on the layout.


Grid Snap

Activates or deactivates grid snap for the layout.


Page Breaks

Shows or hides the page breaks on the layout.


Tool Palette

Shows or hides the Tool palette on the layout.


Status Bar

Shows or hides the status bar on the layout.


View Options

Changes options associated with viewing the layout.

Select the submenu item for the options you want to set:

Ruler

Sets ruler units, grid spacing, and grid snap resolution options.

Layout

Sets layout size and page direction options.


Window Menu

This menu lists all of the Graphics Builder windows that are currently open, and it allows you to choose one to activate.

The chosen window will be made the active window, and it will be moved in front of all other windows.  For example, if you have the Layout editor and Chart Template editor open, and the Layout editor is active (in front of all other windows), you can choose the Chart Template editor from the Window menu to activate it.  For more information on the Window menu, refer to your system documentation.


About OLE

Object Linking and Embedding (OLE) allows you to combine the features of multiple applications in one document.

A container application is one that can show another application's objects.  For example, Forms can contain a Microsoft Excel spreadsheet.

A server application is one whose objects can be shown by a container.  For example, a Graphics Builder display can be embedded in a Visual Basic form.

Graphics Builder is an OLE server.  You can embed a Graphics Builder display in any OLE container application.  For more information, see the documentation for the container application.


About OLE verbs

A verb specifies the operation a Graphics Builder display performs when it is activated within an OLE container.  Graphics Builder supports the following verbs:

HIDE

OPEN

SHOW

The PRIMARY (i.e., default) verb is OPEN.


About HIDE

The OLE verb HIDE deactivates the embedded Graphics Builder object, and hides the display.


About OPEN

The OLE verb OPEN runs the Graphics Builder executable and loads the embedded display into the container application.


About SHOW

The OLE verb SHOW activates the embedded Graphics Builder object, and prepares it for interaction with the container application.


About OLE automation

OLE Automation allows you to manipulate an embedded Graphics Builder display using programmatic constructs from within the container application.  Graphics Builder supports several methods that provide access to Graphics Builder functionality.  For information about invoking these methods, see the documentation for the container application.


ClearQuery

Clears all data from a Graphics Builder query.

Visual Basic Syntax:

ole.Object.ClearQuery query_name

where:

ole	Is the OLE object.

query_name	Is the name of the Graphics Builder query to clear.


Connect

Establishes a database connection for the embedded Graphics Builder display.

Visual Basic Syntax:

ole.Object.Connect connect_string

where:

ole	Is the OLE object.

connect_string	Is a valid Oracle database connection string of the form username/password@remote_server.


GetCharParam

Returns the character value of a Graphics Builder parameter.  If the parameter is not of type CHAR, it is converted to CHAR before it is returned.

Visual Basic Syntax:

x = ole.Object.GetCharParam param_name

where:

ole	Is the OLE object.

param_name	Is the name of the parameter in the Graphics Builder display.


Interpret

Instructs Graphics Builder to execute any PL/SQL string.

Visual Basic Syntax:

ole.Object.Interpret pls_string

where:

ole	Is the OLE object.

pls_string	Is any PL/SQL string that can be successfully executed by Graphics Builder.


MouseDown

Signals a mouse down event to the Graphics Builder display.

Visual Basic Syntax:

ole.Object.MouseDown pos_x pos_y

where:

ole	Is the OLE object.

pos_x	Is the x-coordinate of the location of the mouse event.  For example, this information is provided by the Visual Basic MouseDown event.

pos_y	Is the y-coordinate of the location of the mouse event.  For example, this information is provided by the Visual Basic MouseDown event.


MouseMove

Signals a mouse move event to the Graphics Builder display.

Visual Basic Syntax:

ole.Object.MouseMove pos_x pos_y

where:

ole	Is the OLE object.

pos_x	Is the x-coordinate of the location of the mouse event.  For example, this information is provided by the Visual Basic MouseMove event.

pos_y	Is the y-coordinate of the location of the mouse event.  For example, this information is provided by the Visual Basic MouseMove event.


MouseUp

Signals a mouse up event to the Graphics Builder display.

Visual Basic Syntax:

ole.Object.MouseUp pos_x, pos_y

where:

ole	Is the OLE object.

pos_x	Is the x-coordinate of the location of the mouse event.  For example, this information is provided by the Visual Basic MouseUp event.

pos_y	Is the y-coordinate of the location of the mouse event.  For example, this information is provided by the Visual Basic MouseUp event.


SetRow

Appends a row of data to a custom query in the embedded Graphics Builder display.

Visual Basic Syntax:

ole.Object.SetRow query_name, value[, value...]

where:

ole	Is the OLE object.

query_name	Is the name of the custom query.

value	Is a character or numeric data value.  These values are combined into a single row of data, then appended to the query.  For example, if you define custom query 'query0' that contains the columns ENAME and SAL, you would use the following Visual Basic command to append a row containing the values 'SMITH' and 2000:

ole.Object.SetRow "query0", "SMITH", 2000


Sync

Updates the appearance of the embedded object so that it reflects the current state of the display.

Visual Basic Syntax:

ole.Object.Sync

where:

ole	Is the OLE object.


Pattern Palette

To see a sample of each pattern in the palette, along with its name, select one of the links below:

Patterns, Part 1

Patterns, Part 2


Default color palette

Graphics Builder uses its default color palette if you do not explicitly specify or import another.

The default palette is also provided as a file that you can import into a display.  For information on the location of this file, see the installation information for your operating system.

The default color palette is defined by the following rules:

1	The upper-left region of the palette contains 16 commonly used colors, with the following names:

black	white	green	darkgreen
	gray	darkgray	cyan	darkcyan
	red	darkred	blue	darkblue
	yellow	darkyellow	magenta	darkmagenta
1	The lower-left region of the palette contains eight empty cells into which you can place custom defined colors.

2	The next five columns are composed of varying shades of gray.  Each color is named 'gray<value>', according to its percentage gray value.  The values range from 4 to 96, in increments of 4.  For example, valid color names include 'gray96', 'gray92', and 'gray4'.

3	The remainder of the palette contains colors specified by varying percentages of red, green, and blue (RGB) components:

The percentage values for each red or green component are:  0, 25, 50, 75, 88, or 100

The percentage values for each blue component are:  0, 50, 75, 88, or 100.

Each color is named `r<value>g<value>b<value>', according to its RGB values (e.g., the color that is composed of 100% red, 0% green, and 88% blue is named `r100g0b88').

Except for the color cells described above, the palette is composed of five major regions, each containing 36 colors in a 6x6 arrangement.  These colors are defined by the following rules:

The red value increases as the colors progress from left to right within each major region.

The green value increases as the colors progress from top to bottom within each major region.

The blue value increases as the major regions progress from left to right, with all of the colors in a single region using the same blue value.


Grayscale

The grayscale color palette is composed entirely of varying shades of gray.  It is defined by the following rules:

1	The first two colors are named `black' and `white'.

2	The remainder of the palette contains colors specified by varying percentages of gray.  Each color is named `gray<value>', according to its gray value.  These colors are defined by the following rules:

The gray value of the first gray color (to the right of `white') is 100%, and is named `gray100'.

As the colors progress from left to right across the palette (and wrapping from the rightmost cell in one row to the leftmost cell in the next), the gray value for each color is .5 less than the one before it.

After `gray12.5', the gray value for each color is .25 less than the one before it.

The gray values continue to decrease to the last color in the palette, named `gray0'.


Oracle CDE1

The Oracle CDE1 color palette was the default color palette in Graphics Builder 2.0.  It is defined by the following rules:

1	The first two columns in the palette contain:

commonly used colors, named `blue', `magenta', `red', `cyan', `green', and `yellow'

shades of gray, named `black', `gray60', `gray45', `gray30', `gray15', and `white'

2	The remainder of the palette contains colors specified by varying percentages of red, green, and blue (RGB) components.  The percentage value for each component is:  0, 40, 55, 70, 85, or 100.

Each color is named `r<value>g<value>b<value>', according to its RGB values (e.g., the color that is composed of 100% red, 40% blue, and 0% green is named `r100b40g0').

Except for the first two columns, the palette is composed of six major regions, each containing 36 colors in a 6x6 arrangement.  These colors are defined by the following rules:

   The red value increases as the colors progress from left to right within each major region.

  The green value increases as the colors progress from top to bottom within each major region.

  The blue value increases as the major regions progress from left to right, with all of the colors in a single region using the same blue value.


Patterns, Part 1


Patterns, Part 2


Alphabetical list of objects

axis properties

chart properties

display properties

field template properties

frame properties

layer properties

object properties

parameter properties

query properties

reference line properties

timer properties


Axis properties

axis properties

Label, position, direction, tick mark, grid, and other settings.

continuous axis properties

Axis maximum, minimum, step, and scale.

date axis properties

Maximum, minimum, step, label, and other settings.

discrete axis properties

Minimum and maximum number of categories.


Axis properties

Custom Label

Specifies the text of the label that appears along the axis.

Data Type

Specifies the behavior of the data that appears along the axis.

Axis Position

Specifies along which edge of the chart the axis appears.

Axis Direction

Specifies in which direction increasing values, or successive categories, are placed along the axis.

Tick Position

Specifies how the major and minor tick marks appear.

Tick Label Rotation

Specifies the rotation angle of the tick mark labels.  Note:  Some systems do not support rotating text.  For more information, see the Graphics Builder documentation for your operating system.

Minor Ticks per Interval

Is the number of minor ticks defined within each major tick interval.

Show Major Ticks

Specifies whether major tick marks appear at each major interval.

Show Minor Ticks

Specifies whether minor tick marks appear, as specified by the value set for Minor Ticks per Interval.

Show Major Grid

Specifies whether a grid line appears at each major tick mark.

Show Minor Grid

Specifies whether a grid line appears at each minor tick mark.

Show Axis Label

Specifies whether labels that identify values along the axis appear.

Show Tick Labels

Specifies whether labels that identify values along the axis appear.


Continuous Axis properties

Maximum

Is the largest value to appear on the axis.

Step Size

Is the major interval along the axis at which major tick marks and tick labels appear.

Minimum

Is the smallest value to appear on the axis.

Scale

Specifies the algorithm used for scaling the axis.

Linear	Means the axis is scaled using a fixed interval between the minimum and maximum axis values.

Logarithmic	Means the axis is scaled using a logarithmic algorithm (based on powers of 10) to determine the intervals between the minimum and maximum axis values.

Percent of	Means the axis is scaled so that data values will be plotted relative to one of the following amounts:

sum	Means each data value is plotted as a percentage of the sum of all data values.

minimum	Means each data value is plotted as a percentage of the smallest data value.

maximum	Means each data value is plotted as a percentage of the largest data value.

Note:  Percent of scaling is not applicable to a continuous axis that is also independent (e.g., on a scatter chart).

If you select Percent of, you must also specify how the comparison values are calculated:

field	Means the percentage for each data value is calculated relative to data values for the same field in other categories.  For example, SMITH's salary will be plotted as compared to the salaries of all other employees.

category	Means the percentage for each data value is calculated relative to data values in the same category for other fields (this option is meaningful only when more than one field is plotted for a category).  For example, SMITH's salary and commission will be plotted as compared to each other, but not to any other employee's.


Date Axis properties

Maximum

Is the largest value to appear on the axis.

Step Size

Specifies the granularity with which an independent date axis is divided into categories.  The step size is divided into the major unit specified by the setting for Labels, resulting in the number of categories plotted between the tick marks.

Minimum

Is the smallest value to appear on the axis.

First Month

Is the month that is considered to begin a new year.

Skip Weekends

Specifies whether weekends are ignored when calculating axis values.

Labels

Specifies the major interval along the axis at which major tick marks and tick labels appear, as well as the appearance of the tick labels.  Label settings for units smaller than the one specified by Step Size are ignored.

Custom	You must enter a custom date format in the corresponding text field.  If the smallest unit used in this date format is smaller than any of the ones checked, Graphics Builder behaves as if you checked that unit.  For information about valid date formats, see the Oracle7 Server SQL Language Reference Manual.


Discrete Axis properties

Minimum Number of Categories

Is the minimum number of categories that are plotted in the chart.  If the actual number of categories is less than the number specified here, space is left on the chart to accommodate the specified minimum number of categories.

Maximum Number of Categories

Is the maximum number of categories that are plotted in the chart.  After the maximum number of categories has been plotted, any remaining data will be ignored.


Chart properties

chart properties

Name, title, and chart type, and template properties.

data properties (chart)

Query, filter, data range, and other properties.

category properties

Query columns that appear as categories on the chart.

values properties

Query columns that appear as values on the chart.

PL/SQL properties

PL/SQL button procedure settings.


Chart properties

Name

Is the name of the chart.  You need to use the name of the chart in order to reference it in your PL/SQL programs units.  If you do not intend to programmatically refer to the chart, naming it is unnecessary.

Title

Is the title of the chart.  By default, the title appears above the chart.  If desired, you can drag it to a new location.

Type

Is the base chart type.

Subtype

Is the variation of the chart type.  Each variation is based on the specified chart type, with various properties set to achieve a different look.

Template

Is the chart template on which the chart is based.  A new template is automatically created when you create a new chart.  To base a chart on an existing template, select it from this list.


Data properties (chart)

Query

Is the query that supplies the data for the chart.

Note that Graphics Builder creates the chart using the most recently retrieved data for the query that you select.  To use more recent data, re-execute the query.

Update Chart on Query Execution

Specifies that the chart is automatically be updated when the query is executed.  You can also use the built-in procedure OG_UPDATE_CHART to update the chart programmatically.

Filter Function

Is the PL/SQL function used to filter the data provided by the query.  Only data rows for which this function returns the value TRUE appear on the chart.  Only functions that have a valid filter trigger function header appear in this list.

Mapping Type

Determines the layout of the Values property page.  The available choices depend on the chart type.

General	Allows you to specify a single list of values.

Gantt	Allows you to specify columns that appear as "begin" and "end" values.

High-Low	Allows you to specify columns that appear as "high", "close", and "low" values.

Data Range

Specifies which rows of data from the chart's query are plotted on the chart.

Plot All Rows	Shows all of the query's rows on the chart.

Plot Rows	Shows only the rows of data that fall within the specified range.


Category properties

Query Columns

Shows the columns from the chart's query that are eligible to be used as chart categories.

Chart Categories

Shows the columns that are plotted as chart categories.

Subcategory

Specifies the query column to be used as a subcategory in a break chart.

Insert

Adds the selected column to the list of categories.

Delete

Removes the selected column from the list of categories.

Top

Moves the selected column to the top of the category list so that it is plotted first.

Bottom

Moves the selected column to the bottom of the category list so that it is plotted last.

Up

Moves the selected column up one slot in the category list so that it is plotted earlier.

Down

Moves the selected column down one slot in the category list so that it is plotted later.


Values properties

Query Columns

Shows the columns from the chart's query that are eligible to be used as chart values.

Chart Values

(General Mapping Type)  Shows the columns that are plotted as chart values.

Field Template

(General Mapping Type)  Specifies the field template used to determine the appearance of the selected column.

Begin

(Gantt Mapping Type)  Specifies the column whose data is plotted as the begin value.

End

(Gantt Mapping Type)  Specifies the column whose data is plotted as the end value.

High

(High-Low Mapping Type)  Specifies the column whose data is plotted as the high value.

Close

(High-Low Mapping Type)  Specifies the column whose data is plotted as the close value.

Low

(High-Low Mapping Type)  Specifies the column whose data is plotted as the low value.


PL/SQL properties

Procedure

Is the name of the PL/SQL button procedure associated with the chart.  This procedure is executed when a specified "mouse event" that is related to the chart is detected.  Only procedures that have a valid button trigger procedure header appear in this list.

Event Types

Specifies which "mouse events" invoke the specified button procedure.

Mouse Button Down	Means the procedure is invoked when the mouse button is selected.

Mouse Button Up	Means the procedure is invoked when the mouse button is released.

Mouse Move with Button Down	Means the procedure is invoked when the mouse is moved while the button is held down.


Display properties

Sets Open Display and Close Display triggers, and changes the parameter date format.

Open Trigger

Is the name of the PL/SQL procedure that is executed when the display is first opened at runtime.  Only procedures that have a valid open trigger procedure header appear in this list.

New

Creates a new Open Display trigger.

Close Trigger

Is the name of the PL/SQL procedure that is executed when the display is closed at runtime.  Only procedures that have a valid close trigger procedure header appear in this list.

New

Creates a new Close Display trigger.

Parameter Date Format

Specifies the date format mask used to recognize valid values for parameters of type DATE.

List

Shows the date format masks currently available in the display, and allows you to add or delete masks.  Choosing the button shows the Date Format dialog box.

Direction

Determines the default direction of text, arrows, etc. for bi-directional NLS support.  Choose Left to Right, Right to Left, or Default (determined by current language).


Field Template properties

field properties

Field template name and color/pattern rotation scheme.

axis field properties

Plot type, line style, label rotation, curve fit, and other settings.


Field properties

Name

Is the name of the field template.

Color Rotation

Specifies whether Graphics Builder automatically rotates through the color or pattern palette to select a unique shading for each field that uses this field template.  If not, all fields that use this field template appear with the same shading.


Axis Field properties

Plot Type

Specifies the elements used to plot this field on the chart.

Bar	Means each data values for the field are plotted as a bar extending from the baseline to its value along the value axis.

Line	Means the data values for the field are plotted as lines connecting the values for each category.

Fill  	Means the data values for the field are plotted as a filled-in area whose boundaries are the baseline, the edges of the chart, and a line connecting the values for each category.

Symbol  	Means each data value for the field are plotted as a symbol appearing at its data point.  To choose a custom symbol, select one of the template's symbols and choose a new symbol from the symbol palette.

Spike  	Means each data value for the field are plotted as a straight line connecting the baseline with the data point.

Label    	Means each data value for the field are plotted as a text label containing its value.

Line Style

Specifies the line style used to connect the data points of a field with a line plot type.

Label Rotation

Specifies the rotation angle of the labels for a field with a label plot type.

Axis Mapping

Specifies the axis to which data values are compared to determine how the field is plotted.

Curve Fit Type

Specifies whether a curve fit is applied to the chart and, if so, which algorithm is used.

Graphics Builder computes the curve using a least-squares approximation of the data.  In other words, Graphics Builder tries to find values a and b for the equations listed below such that the sum of the squares of the differences between the values of the curve and the actual data values is minimized.  The curve for each fit type is defined as listed below:

linear	Means the curve is defined by the equation:

y = ax + b.

logarithmic	Means the curve is defined by the equation:

y = a(log x) + b.

exponential	Means the curve is defined by the equation:

(log y) = ax + b.

power	Means the curve is defined by the equation:

(log y) = a(log x) + b.

Plot Position

Specifies--for each category--the relationship between the data values of two or more fields.

Normal	Means data values from multiple fields are plotted normally, and evenly split the amount of space available to plot data for the category.

From Previous Field	Means data values from multiple fields are stacked on top of each other, with each chart element (i.e., bar, line, etc.) drawn starting at the end point of the previous one, and continuing to the new data point.

Stacked	Means data values from multiple fields are stacked on top of each other, and share the same space available to plot data for the category.  The location of each data point is determined by adding its value to the previous one.

Overlap

Specifies the percentage by which bars representing data values from multiple fields in a bar or column chart overlap each other.


Frame properties

frame properties

Depth, shadow, and legend settings.

axis frame properties

Baseline, category width, and second Y-axis settings.

pie frame properties

Pie usage, labels, "other" slice definition, and other settings.

table frame properties

Label, grid, number of rows/columns, and other settings.


Frame properties

Depth Size

Specifies the amount of depth with which the chart frame and elements are drawn to provide them with a 3-dimensional look.

Shadow Size

Specifies the size of the shadow with which the chart frame and elements are drawn.

Shadow Direction

Specifies the direction of the shadow with which the chart frame and elements are drawn.

Show Plot Frame

Specifies whether the rectangle that surrounds the chart should be shown.  (Not applicable to pie charts.)

Show Legend

Specifies whether the chart's legend should be shown.  (Not applicable to table charts.)

Number of Columns in Legend

Is the number of columns used to display the labels that appear in the legend.  If this number is greater than or equal to the number of labels that exist, each label appears in a separate column.


Axis Frame properties

Baseline Value

Is the value used as the starting point for plotting fields along the value axis.  All values greater than the baseline value are plotted above the baseline; all values less than the baseline value are plotted below the baseline.

Minimum	Means the baseline is the minimum axis value.

Maximum	Means the baseline is the maximum axis value.

Zero	Means the value 0 is used as the baseline.

Custom	Means the value entered in the associated text field is used as the baseline.

Baseline Mapping

Specifies the axis to which the baseline value is compared to determine its position.

Category Width

Is the width of the bars in a bar or column chart, as a percentage of the "strip width."  The strip width is the widest the bars can be without overlapping each other, and it is determined by dividing the length of the category axis by the number of bars to be plotted.

Setting the category width provides a way to put space between the bars, by setting it to less than 100%.

Show Second Y Axis

Specifies whether a second Y axis appears in the chart.


Pie Frame properties

Pie Usage

Specifies the relationship between the individual pie slices and the complete chart.

Total Value	Means each pie slice is plotted as if its data value is a percentage of the total value specified here.

Percent	Means the sum of the existing data values represents the specified percentage of the chart's total value, and the individual slices are plotted accordingly.

Plotting Order

Specifies the direction in which the data values are plotted.  The first pie slice always appears at the top of the chart, and each subsequent slice appears in the direction specified here.

Show Category Labels

Specifies whether each pie slice is labeled with the name of the category it represents.

Show Data Values

Specifies whether each pie slice is labeled with its data value.

Show Percent Values

Specifies whether each pie slice is labeled with the percentage of the complete chart it represents.

Show Ticks

Specifies whether the tick marks that connect each pie slice to its label are shown.

Put Slices Smaller Than x% as 'Other'

Specifies that pie slices that individually represent percentages less than the number entered here are combined into a single pie slice with the label "Other".

Prevent Label Overlap

Specifies that the labels for the pie slices should not overlap each other.  If the labels are long, they may need to be placed far away from the chart to achieve this.  In that case, you may wish to turn this setting off.


Table Frame properties

Table Direction

Specifies whether the rows of data are listed horizontally or vertically.

Minimum Number of Rows

Is the minimum number of rows plotted in the table chart.  If the actual number of rows is less than the number specified here, space is left in the chart to accommodate the specified minimum number of rows.

Maximum Number of Rows

Is the maximum number of rows plotted in the table chart.  After the maximum number of rows is plotted, remaining rows are ignored.

Show Column Names

Specifies whether the names of the columns appear as the first row in the chart.

Show Vertical Grid Lines

Specifies whether vertical grid lines appear between the columns.

Show Horizontal Grid Lines

Specifies whether horizontal grid lines appear between the rows.

Rows per Horizontal Line

Is the number of rows of data plotted before each horizontal grid line is drawn.


Layer properties

Creates, deletes, hides, shows, activates, and renames layers.

Dialog Box Options

Existing Layers

Shows the layers that exist in the display.  The order of the layers in the list determines how their objects appear on the layout.  Each layer's objects overlay the objects of all showing layers that are beneath it in the list.

New

Creates a new, empty layer named "layerx" (where x is some number).

Delete

Removes the layer that is selected in the list.  All of the objects on that layer will also be deleted.

Hide/Show

Hides the selected layer if it is showing, or shows it if it is hidden.  A `+' next to the layer name in the list indicates that it is currently showing; a `-' indicates that it is hidden.  You cannot hide the active layer.

Activate

Makes the selected layer active.  If the layer is hidden, it will be automatically be set to be showing.  To deactivate a layer, make another layer active.

Up/Down/Top/Bottom

Moves the selected layer up one position in the list, down one position in the list, to the top of the list, or to the bottom of the list.  The order of the layers in the list determines how their objects appear on the layout.  Each layer's objects will overlay the objects of all showing layers that are beneath it in the list.

Active Layer

Shows the name of the currently active layer.  Only one layer can be active at a time.

New Name

Is the new name for the selected layer.  Select Rename to rename the layer.

Rename

Renames the selected layer to the name specified in the New Name text box.


Object properties

object properties

Name, button procedure, mouse event, and format trigger.

drill-down properties

Drill-down properties.


Object properties

Name

Is the name of the object.  You need to use the name of the object to reference it in your PL/SQL program units.  If you do not intend to programmatically refer to the object, naming it is unnecessary.

Procedure

Is the name of the PL/SQL button procedure associated with the object.  This procedure is executed when a specified "mouse event" that is related to the object is detected.  Only procedures that have a valid button trigger procedure header appear in this list.

Event Types

Specifies which "mouse events" invoke the specified button procedure.

Mouse Button Down	Means the procedure is invoked when the mouse button is selected.

Mouse Button Up	Means the procedure is invoked when the mouse button is released.

Mouse Move with Button Down	Means the procedure is invoked when the mouse is moved while the button is held down.

Mouse Move with Button Up	(layers only)  Means the procedure is invoked when the mouse is moved while the button is not held down.

Format Trigger

Is the name of the chart format trigger procedure associated with this object.  Only procedures that have a valid format trigger procedure header appear in this list.  Note:  This property is applicable only if the object is a chart element.


Drill-down properties

Set Parameter

Is the parameter whose value is set when the object is selected.

New

Creates a new parameter, and shows the Parameter property page.

To Value of

Specifies the value to which the parameter is set when the object is selected.

If the object is a chart element, you can select a column that appears in the chart's query  The parameter is then set to the data value that appears in the specified column for the current query row.

If the object is not a chart element, the only choice is to set the parameter to the object's name.

Execute Query

Specifies the query to execute when the object is selected.  If you also specify that a parameter is set, the parameter is set before the query executes.

New

Creates a new query, and shows the Query property page.


Parameter properties

Parameter

Select the parameter to modify.  All parameters that exist in the display appear in this list.

Name

Is the name of the parameter.

Type

Is the datatype of the parameter.

Initial Value

Is the parameter's initial value when you first run the display.  The value entered here can be superseded by a value specified on the command line, and you can change the value at runtime.

The length of a parameter value cannot exceed 2000 bytes.


Query properties

query properties

Name, data source and SQL statement (if needed) for a query.

data properties (query)

Data returned by the query.

option properties

Execution and data caching properties, triggers, and other properties.

schema properties (custom queries only)

Creates, deletes, and sets the name and datatype of custom columns.


Query properties

Query

Select the query to modify.  All queries that exist in the display appear in this list.

Name

Is the name of the query.

Type

Is the type of query.  Select one of the following options:

SQL Statement  	Means the query retrieves its data from a database, based on a SQL SELECT statement you provide.  Enter the SQL statement in the SQL Statement text box.

SYLK File    	Means the query retrieves its data from a file that is in the SYLK format.  SYLK is a format used by several popular applications, such as Microsoft Excel.  When you execute the query, the data is read from the file.  Specify the file to use in the File text box.

WKS File    	Means the query retrieves its data from a file that is in the WKS format.  WKS is a format used by several popular applications, such as Lotus 1-2-3.  When you execute the query, the data is read from the file.  Specify the file to use in the File text box.

PRN File    	Means the query retrieves its data from a file that is in the PRN format.  PRN is a text file format.  When you execute the query, the data is read from the file.  Specify the file to use in the File text box.

Custom	Allows you to customize the query's columns and data.  To set the columns, use the controls that appear on the Schema property page.  To set the data, use the built-in procedure OG_APPEND_ROW.

External SQL File	Means the query retrieves its data from a text file that contains a SQL SELECT statement.  When you execute the query, the SQL statement is read from the file and executed.  Specify the file to use in the File text box.

File

Shows the location and name of the file to use for a SYLK, WKS, PRN, or External SQL query.  To locate the file in your file system, select the Browse button.

Browse

Allows you to locate and select the filename to show in the File text box.

SQL Statement

Is the SQL SELECT statement that is executed for a SQL Statement query.

Connect

Shows the Connect dialog box, allowing you to connect to a database.

Import SQL

Allows you to place the contents of a text file into the SQL Statement text box.  Note that the text is copied, not linked to the file.  To create a link to SQL text in a file, use a query type of External SQL File.

Export SQL

Allows you to place the contents of the SQL Statement text box into a file.

New

Creates a new query.

Delete

Deletes the current query.

Execute

Executes the current query.  If the query is a SQL SELECT statement, the data is retrieved from the databae.  If the query retrieves data from a file, the file is read.  If the query is a custom query, its custom query procedure is executed.

Clear Data

Clears the data cache of all data retrieved.  This does not delete or in any way modify the query itself.


Data properties (query)

Query

Select the query to modify.  All queries that exist in the display appear in this list.

New

Creates a new query.

Delete

Deletes the current query.

Execute

Executes the current query.  If the query is a SQL SELECT statement, the data is retrieved from the database.  If the query retrieves data from a file, the file is read.  If the query is a custom query, its custom query procedure is executed.

Clear Data

Clears the data cache of all data retrieved.  This does not delete or in any way modify the query itself.


Options properties

Query

Select the query to modify.  All queries that exist in the display appear in this list.

Execute on

Specifies when the query is automatically executed.  Select from the following options:

Opening Display	Executes the query when the display is first opened at runtime.

Timer	Executes the query at the frequency specified by a timer.  Select a timer from the drop-down list, or select New to create a new timer.

Data

Sets several options related to the queries data.

New Data	Determines how the newly retrieved data from a query execution is treated.

Replaces Old Data means all of the data from the previous execution is discarded, and the newly retrieved data replaces it.

Appends to Old Data means all of the existing rows of data are retained, and the new rows of data are added to the bottom of the existing data set.

Save Old Data	Specifies whether previously retrieved data is stored in a special buffer when it is replaced by new data.  You can then access this "old data" buffer using built-in routines such as OG_GET_NUMCELL.  This property is valid only when the New Data setting is Replaces Old Data.

Maximum Number of Rows	Specifies the maximum number of rows of data that are retained in the query's data set.  If appending data causes the number of rows to exceed this maximum, excess rows are discarded from the top of the data set.  This property is valid only when the New Data setting is Appends to Old Data.  In addition, the maxflag attribute for the query must be set to TRUE (the default).  For more information on setting the maxflag, see Maximum Rows Flag Property.

Date Format  	Specifies the format used to recognize date data from a file, and determines how dates appear in the Data property page.  If the dates in the file are in a format other than the one specified here, Graphics Builder will not recognize them as dates.

PL/SQL

Sets several options related to the use of PL/SSQL by the query.

Custom Execute Procedure	(Custom queries only.)  Is the PL/SQL procedure that is invoked when a Custom query is executed.  Typically, this procedure contains PL/SQL statements that populate the query with data.  Only procedures that have a valid custom query trigger procedure header appear in this list.

Select New to create a new custom query procedure.

Post-Execution Trigger	Is the PL/SQL procedure that is invoked after the query is executed.  Only procedures that have a valid post-query trigger procedure header appear in this list.

Select New to create a new post-execution procedure.

New

Creates a new query.

Delete

Deletes the current query.

Execute

Executes the current query.  If the query is a SQL SELECT statement, the data is retrieved from the database.  If the query retrieves data from a file, the file is read.  If the query is a custom query, its custom query procedure is executed.

Clear Data

Clears the data cache of all data retrieved.  This does not delete or in any way modify the query itself.


Schema properties

These properties are for custom queries only.

Query

Select the query to modify.  All queries that exist in the display appear in this list.

Column

Select the column to modify.  All columns that have been defined for this query appear in this list.

Name

Is the column name.  To change the column name, type a new name here and select Apply.

Type

Is the column datatype.

Maximum Length

Is the maximum length of the data contained in the column.  This applies only to columns of type CHAR.

New Column

Adds a new column to the query.

Delete Column

Removes the current column from the query.

New

Creates a new query.

Delete

Deletes the current query.

Execute

Executes the current query.  If the query is a SQL SELECT statement, the data is retrieved from the database.  If the query retrieves data from a file, the file is read.  If the query is a custom query, its custom query procedure is executed.

Clear Data

Clears the data cache of all data retrieved.  This does not delete or in any way modify the query itself.


Reference Line properties

Modifies properties of the reference lines of the template that is showing in the Chart Template editor.

Reference Line

Select the reference line to modify.  All reference lines that exist in the current template appear in this list.

Legend Label

Is the text label that identifies the reference line in the legend.

Value

Is the reference value at which the reference line appears.

Axis Mapping

Specifies with which axis the reference value is compared to determine its position.

New

Creates a new reference line for the current template.

Delete

Deletes the reference line from the current template.


Timer properties

Creates and deletes timers, and sets timer name, trigger procedure, and time interval.

Property Sheet Options

Timer

Select the timer to modify.  All timers that exist in the display appear in this list.

New

Creates a new timer.

Delete

Deletes the current timer.

Name

Is the name of the timer.

Procedure

Is the PL/SQL procedure (if any) that is executed when the timer fires.  Only procedures that have a valid timer trigger procedure header appear in this list.

To create a new timer procedure, select New.

Interval

Is the amount of time that passes between each firing of the timer.

Active

Specifies whether the timer fires.

New

Creates a new timer.

Delete

Deletes the current timer.


About file security and restrictions

Graphics Builder uses your operating system environment to determine the security of modules stored in files.  The way in which you acquire permission to access modules stored in files is operating system-dependent.  For more information, refer to your system documentation.


About database security and restrictions

There are two types of restrictions you can place on Graphics Builder users:   You can:

control access to Graphics Builder

control access to other users’ modules

Graphics Builder' security mechanism utilizes Oracle's GRANT and REVOKE commands, providing extra measures of control.  All restrictions places through GRANT and REVOKE still apply.


Controlling access to Graphics Builder

To control access to Graphics Builder:

  A user will be unable to access Graphics Builder unless the user is granted access to Graphics Builder tables by running the appropriate installation script.  You must revoke a user's access manually.


Controlling others' access to your modules

To control others’ access to your modules:

1	Choose a module type from the Layout Editor's File [image] Administration [image] Access menu to show the Module Access in Database dialog box.

2	Select a module name.

3	Select OK to show the Module Access dialog box.

4	Type a username (or PUBLIC) in the User field.  If you type PUBLIC, all users that have been granted access to the system-owned tables will have access to the module.


About database table storage

There are three sets of tables used with Graphics Builder:

•	Demo tables	Contain sample data used in demos.

•	Data tables	Contain your own data.

•	Graphics Builder tables	Contain Graphics Builder modules.

Graphics Builder Tables

When you store a Graphics Builder module (display, drawing, chart template, color palette, sound, image) in a database, it is stored in the Graphics Builder tables.  These tables comprise the following:

Graphics Builder-specific tables:  Graphics Builder-specific tables contain module and other display definitions.  The tables are used solely by Graphics Builder, and are not shared with other Oracle products.  Through the use of views and public synonyms, users can see information about modules they own or to which they have been granted access.

Shared Oracle product tables:  Shared Oracle product tables contain module definitions, and may be shared with other Oracle products.  Through the use of database views and public synonyms, users can see information about modules they own or to which they have been granted access.

Caution: Oracle Corporation does not guarantee the functionality or integrity of modules whose table definitions have been modified via SQL*Plus or another database tool not specifically intended to modify the Graphics Builder tables.  Also, be aware that Oracle Corporation reserves the right to change the names or structures of its tables at any time and without notice.


About database storage requirements

The shared Oracle product tables require approximately 255 database blocks (or 460 Kbytes) of storage when empty.  The Graphics Builder-specific tables require an additional 130 database blocks (or 260 Kbytes) of storage when empty.  If multiple users will share one set of tables, only 385 blocks are needed initially per installation.  Otherwise, if each user will have his or her own set of tables, allow 385 blocks per user.

The storage occupied by the tables increases as modules are defined.  The actual storage per module can vary significantly.  For displays, it depends on the number of objects, number of queries, size of PL/SQL program units, etc.


About Graphics Builder-specific tables

Graphics Builder-specific tables contain module and other display definitions.  The tables are used solely by Graphics Builder, and are not shared with other Oracle products.  Through the use of views and public synonyms, users can see information about modules they own or to which they have been granted access.


Graphics Builder-specific tables

GC_CHARTING

GC_FIELD

GC_REFERENCE

GO_DOCUMENT

GO_PARAMETER

GO_QUERY

GO_SOUND

GO_TIMER

VG_COLOR

VG_FONT

VG_IMAGE


GC_CHARTING

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEMID	INTEGER	Instance ID
CHARTNAME	RAW(255)	Chart name
CHARTNAME_LEN	INTEGER	Chart name length
CHARTNAME_CS	INTEGER	Chart name char. Set
CHART_TYPE	INTEGER	Chart type
CHART_VIS	INTEGER	Chart visibility flag
DEPTH_SIZE	INTEGER	Depth size (0 => 20
SHADOW_SIZE	INTEGER	Shadow size (0 => no shadow
SHADOW_DIR	INTEGER	Shadow direction
BASELN_FLG	INTEGER	Baseline definition flag
BASELN_DAT	DATE	Baseline date value
BASELN_VAL	FLOAT	Baseline value
CATEGORY_WD	FLOAT	Category total width (pct of strip wd)
BASELN_AXIS	INTEGER	Baseline axis mapping (y1 or y2)
X1_AXIS_TYPE	INTEGER	Axis data type: cont date or discr
X1_AXIS_DEP	INTEGER	Axis dependency state: true if dep.
X1_SCALE_FNC	INTEGER	Scale function: linear log pct
X1_AXIS_POS	INTEGER	Axis position: top/bottom/left/right
X1_GRID_VIS	INTEGER	Major/minor tick/grid visibility mask
X1_AXIS_STEP	INTEGER	User-fixed min/max/step bit flag
X1_NUM_STRIP	INTEGER	Number of strips on discrete axis
X1_CONT_AX_MN	FLOAT	Continuous axis min.
X1_CONT_AX_MX	FLOAT	Continuous axis max.
X1_CONT_AX_ST	FLOAT	Continuous axis step
X1_DATE_AX_MN	DATE	Date axis min.
X1_DATE_AX_MX	DATE	Date axis max.
X1_DATE_AX_ST	INTEGER	Date axis step
X1_AX_LBL_HS	INTEGER	Axis label hide/show flag
X1_TIC_TYPE	INTEGER	Tick type (centered in out)
X1_MINOR_TIC	INTEGER	Minor tick/grid count 0..9
X1_NUM_FORMAT	RAW(255)	Numeric format string for tick labels
X1_NUM_FORMAT_CS	INTEGER	Numeric format char set for tick labels
X1_NUM_FORMAT_LEN	INTEGER	Numeric format char len for tick labels
X1_DAT_FORMAT	RAW(255)	Date format string for tick labels
X1_DAT_FORMAT_CS	INTEGER	Date format char set for tick la bels
X1_DAT_FORMAT_LEN	INTEGER	Date format char len for tic labels
X1_TIC_ROT	INTEGER	Tick label orientation (rotation)
X1_TIC_FIX	INTEGER	Tick label fixed orientation flag
X1_TIC_DT_VIS	INTEGER	Date labeled axis tick label visibility
X1_DATE_ABBR	INTEGER	Date abbreviated flags
X1_WKEND_FLG	INTEGER	No weekend flag
X1_START_MNTH	INTEGER	Starting month of fiscal year (1..2)
X1_PCT_TYP	INTEGER	Percent type (sum, min, or max)
X1_PCT_GRP	INTEGER	Percent grouping (column or category)
X2_AXIS_TYPE	INTEGER	Axis data type: cont date or discr
X2_AXIS_DEP	INTEGER	Axis dependency state: true if dep.
X2_SCALE_FNC	INTEGER	Scale function: linear log pct
X2_AXIS_POS	INTEGER	Axis position: top/bottom/left/right
X2_GRID_VIS	INTEGER	Major/minor tick/grid visibility mask
X2_AXIS_STEP	INTEGER	User-fixed min/max/step bit flag
X2_NUM_STRIP	INTEGER	Number of strips on discrete axis
X2_CONT_AX_MN	FLOAT	Continuous axis min.
X2_CONT_AX_MX	FLOAT	Continuous axis max.
X2_CONT_AX_ST	FLOAT	Continuous axis step
X2_DATE_AX_MN	DATE	Date axis min.
X2_DATE_AX_MX	DATE	Date axis max.
X2_DATE_AX_ST	INTEGER	Date axis step
X2_AX_LBL_HS	INTEGER	Axis label hide/show flag
X2_TIC_TYPE	INTEGER	Tick type (centered in out)
X2_MINOR_TIC	INTEGER	Minor tick/grid count 0..9
X2_NUM_FORMAT	RAW(255)	Numeric format string for tick labels
X2_NUM_FORMAT_CS	INTEGER	Numeric format char set for tick labels
X2_NUM_FORMAT_LEN	INTEGER	Numeric format char len for tick labels
X2_DAT_FORMAT	RAW(255)	Date format string for tick labels
X2_DAT_FORMAT_CS	INTEGER	Date format char set for tick labels
X2_DAT_FORMAT_LEN	INTEGER	Date format char len for tick labels
X2_TIC_ROT	INTEGER	Tick label orientation (rotation)
X2_TIC_FIX	INTEGER	Tick label fixed orientation flag
X2_TIC_DT_VIS	INTEGER	Date labeled axis tick label visibility
X2_DATE_ABBR	INTEGER	Date abbreviated flags
X2_WKEND_FLG	INTEGER	No weekend flag
X2_START_MNTH	INTEGER	Starting month of fiscal year (1..2)
X2_PCT_TYP	INTEGER	Percent type (sum min or max)
X2_PCT_GRP	INTEGER	Percent grouping (column or category)
X3_AXIS_TYPE	INTEGER	Axis data type: cont date or discr
X3_AXIS_DEP	INTEGER	Axis dependency state: true if dep.
X3_SCALE_FNC	INTEGER	Scale function: linear log pct
X3_AXIS_POS	INTEGER	Axis position: top/bottom/left/right
X3_GRID_VIS	INTEGER	Major/minor tick/grid visibility mask
X3_AXIS_STEP	INTEGER	User-fixed min/max/step bit flag
X3_NUM_STRIP	INTEGER	Number of strips on discrete axis
X3_CONT_AX_MN	FLOAT	Continuous axis min.
X3_CONT_AX_MX	FLOAT	Continuous axis max.
X3_CONT_AX_ST	FLOAT	Continuous axis step
X3_DATE_AX_MN	DATE	Date axis min.
X3_DATE_AX_MX	DATE	Date axis max.
X3_DATE_AX_ST	INTEGER	Date axis step
X3_AX_LBL_HS	INTEGER	Axis label hide/show flag
X3_TIC_TYPE	INTEGER	Tick type (centered in out)
X3_MINOR_TIC	INTEGER	Minor tick/grid count 0..9
X3_NUM_FORMAT	RAW(255)	Numeric format string for tick labels
X3_NUM_FORMAT_CS	INTEGER	Numeric format char set for tick labels
X3_NUM_FORMAT_LEN	INTEGER	Numeric format char len for tick labels
X3_DAT_FORMAT	RAW(255)	Date format string for tick labels
X3_DAT_FORMAT_CS	INTEGER	Date format char set for tick labels
X3_DAT_FORMAT_LEN	INTEGER	Date format char len for tick labels
X3_TIC_ROT	INTEGER	Tick label orientation (rotation)
X3_TIC_FIX	INTEGER	Tick label fixed orientation flag
X3_TIC_DT_VIS	INTEGER	Date labeled axis tick label visibility
X3_DATE_ABBR	INTEGER	Date abbreviated flags
X3_WKEND_FLG	INTEGER	No weekend flag
X3_START_MNTH	INTEGER	Starting month of fiscal year (1..2)
X3_PCT_TYP	INTEGER	Percent type (sum min or max)
X3_PCT_GRP	INTEGER	Percent grouping (column or category)
P_CLOCK_FLG	INTEGER	Clockwise flag
P_SUM_FLG	INTEGER	Sum flag
P_TIC_VIS	INTEGER	Tick/label visibility bit mask
P_FIXED_SUM	FLOAT	User-fixed sum
P_FIXED_PCT	FLOAT	User-fixed percentage
P_CAT_LBL_FMT	RAW(255)	Category label format string
P_CAT_LBL_FMT_CS	INTEGER	Category label format char set
P_CAT_LBL_FMT_LEN	INTEGER	Category label format string len
P_DAT_LBL_FMT	RAW(255)	Date label format string
P_DAT_LBL_FMT_CS	INTEGER	Date label format char set
P_DAT_LBL_FMT_LEN	INTEGER	Date label format string len
P_ABS_LBL_FMT	RAW(255)	Absolute label format string
P_ABS_LBL_FMT_CS	INTEGER	Absolute label format char set
P_ABS_LBL_FMT_LEN	INTEGER	Absolute label format string len
P_PCT_LBL_FMT	RAW(255)	Percent label format string
P_PCT_LBL_FMT_CS	INTEGER	Percent label format char set
P_PCT_LBL_FMT_LEN	INTEGER	Percent label format string len
T_MAX_ROW	INTEGER	Max. Number of rows
T_MAX_ROW_FIX	INTEGER	Max rows fixed flag
T_GRID_VIS	INTEGER	Grid visibility flags
T_TABLE_DIR	INTEGER	Table direction
T_ROW_PERGRID	INTEGER	Rows per horizontal grid line
L_NUM_COL	INTEGER	Legend: number of columns
L_SHADOW_SIZE	INTEGER	Legend: shadow size (0 => no shadow)


GC_FIELD

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEMID	INTEGER	Instance ID
TEMPLATE_SEQ	INTEGER	Field template order(sequence) number
FIELDNAME	RAW(255)	Field template name
FIELDNAME_LEN	INTEGER	Field template name length
FIELDNAME_CS	INTEGER	Field template name char. Set
PLOT_DEF	INTEGER	Plot definition bit mask
CONNECT_TYPE	INTEGER	Connector type
PLOT_EXT	INTEGER	Plot extent
REGRESS_TST	INTEGER	Regression type
ROT_COL_FLAG	INTEGER	Rotate colors/patterns flag
LABEL_ROT_ANG	INTEGER	Label rotation angle
BAR_OVERLAP	FLOAT	Bar overlap (frac of bar wd)
NUM_FORMAT	RAW(255)	Num format string for text/annotation
NUM_FORMAT_CS	INTEGER	Num format char set for text/annotation
NUM_FORMAT_LEN	INTEGER	Num format len for text/annotation
DAT_FORMAT	RAW(255)	Date format str for text/annotation
DAT_FORMAT_CS	INTEGER	Date format cs for text/annotation
DAT_FORMAT_LEN	INTEGER	Date format len for text/annotation
AXIS_MAPPING	INTEGER	Axis mapping


GC_REFERENCE

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEMID	INTEGER	Instance ID
REFLINE_ID	INTEGER	Reference line ID
REFLINE_MAP	INTEGER	Reference line mapping
CONT_AXIS_VAL	FLOAT	Cont. axis value mapping for this line
DATE_AXIS_VAL	DATE	Date axis value mapping for this line
LEG_LBL	RAW(255)	Legend label string
LEG_LBL_LEN	INTEGER	Legend label string length
LEG_LBL_CS	INTEGER	Legend label string char. set


GO_DOCUMENT

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
FOREGROUND_EDGE_COLOR	INTEGER	Default foreground edge color
BACKGROUND_EDGE_COLOR	INTEGER	Default background edge color
EDGE_PATTERN	INTEGER	Default edge pattern
FOREGROUND_FILL_COLOR	INTEGER	Default foreground fill color
BACKGROUND_FILL_COLOR	INTEGER	Default background fill color
FILL_PATTERN	INTEGER	Default fill pattern
DASH_STYLE	INTEGER	Default dash style
ARROW_STYLE	INTEGER	Default arrow style
SYMBOL_SIZE	INTEGER	Default symbol size
SYMBOL_INDEX	INTEGER	Default symbol index
BRUSH_WIDTH	INTEGER	Default line width
TRANS_MODE	INTEGER	Default transfer mode
CAP_STYLE	INTEGER	Default cap style
JOIN_STYLE	INTEGER	Default join style
ARC_FILL_STYLE	INTEGER	Default arc fill
ARC_CLOSURE	INTEGER	Default arc closure
RRECT_CORNER_WIDTH	INTEGER	Default rounded rectangle corner
RRECT_CORNER_HEIGHT	INTEGER	Default rounded rectangle corner
FACE_NAME	RAW(255)	Default font typeface
FACE_NAME_CHAR	INTEGER	Typeface name character set
FACE_NAME_LEN	INTEGER	Typeface name length
FONT_SIZE	INTEGER	Default font point size
FONT_STYLE	INTEGER	Default font style
FONT_WEIGHT	INTEGER	Default font weight
FONT_WIDTH	INTEGER	Default font width
IMAGE_TEXT	INTEGER	Default image text
KERNING	INTEGER	Default kerning setting
CHAR_SET	INTEGER	Default character set
TEXT_COLOR	INTEGER	Default text color
TEXT_HOR_ALIGN	INTEGER	Default text horizontal alignment
TEXT_VER_ALIGN	INTEGER	Default text vertical alignment
TEXT_HOR_JUSTI	INTEGER	Default text horizontal justification
TEXT_VER_JUSTI	INTEGER	Default text vertical justification
TEXT_SPACING	INTEGER	Default text spacing
TEXT_FIXED_FLAG	INTEGER	Default fixed text flag
TEXT_FONTSC_FLAG	INTEGER	Default scalable font flag
TEXT_WRAP_FLAG	INTEGER	Default text wrap flag
TEXT_BBOX_SCALABILITY	INTEGER	Default scalable text bbox flag
TEXT_INVISIBILITY	INTEGER	Default invisible text flag
TEXT_CUSTOM_SPACING	INTEGER	Default custom spacing flag
HOR_ALIGN_MODE	INTEGER	Default horizontal alignment settings
VER_ALIGN_MODE	INTEGER	Default vertical alignment settings
CTR_TRACK_FLAG	INTEGER	Default draw from center/corner flag
DRAW_SIZE_WIDTH_DEN	INTEGER	Layout width denominator
DRAW_SIZE_WIDTH_NUM	INTEGER	Layout width numerator
DRAW_SIZE_HEIGHT_DEN	INTEGER	Layout height denominator
DRAW_SIZE_HEIGHT_NUM	INTEGER	Layout height numerator
PAGE_COUNT	INTEGER	Default page count
ACTIVE_LAYER	INTEGER	Active layer ID
MAIN_EDITOR_X	INTEGER	Layout editor X-coordinate
MAIN_EDITOR_Y	INTEGER	Layout editor Y-coordinate
MAIN_EDITOR_WIDTH	INTEGER	Layout editor width
MAIN_EDITOR_HEIGHT	INTEGER	Layout editor height
CHART_TEMP_HS	INTEGER	Chart Template editor hiding/showing
CHART_TEMP_X	INTEGER	Chart Template editor X-coordinate
CHART_TEMP_Y	INTEGER	Chart Template editor Y-coordinate
CHART_TEMP_WIDTH	INTEGER	Chart Template editor width
CHART_TEMP_HEIGHT	INTEGER	Chart Template editor height
DATATABLE_HS	INTEGER	Data Table hiding/showing
DATATABLE_X	INTEGER	Data Table X-coordinate
DATATABLE_Y	INTEGER	Data Table Y-coordinate
DATATABLE_WIDTH	INTEGER	Data Table width
DATATABLE_HEIGHT	INTEGER	Data Table height
CONST_WIND_HS	INTEGER	Consistency Checker hiding/showing
CONST_WIND_X	INTEGER	Consistency Checker X-coordinate
CONST_WIND_Y	INTEGER	Consistency Checker Y-coordinate
CONST_WIND_WIDTH	INTEGER	Consistency Checker width
CONST_WIND_HEIGHT	INTEGER	Consistency Checker height
PLSQL_WIND_HS	INTEGER	Batch Compiler hiding/showing
PLSQL_WIND_X	INTEGER	Batch Compiler X-coordinate
PLSQL_WIND_Y	INTEGER	Batch Compiler Y-coordinate
PLSQL_WIND_WIDTH	INTEGER	Batch Compiler width
PLSQL_WIND_HEIGHT	INTEGER	Batch Compiler height
PLSQL_PROG_HS	INTEGER	PL/SQL Browser hiding/showing
PLSQL_PROG_X	INTEGER	PL/SQL Browser X-coordinate
PLSQL_PROG_Y	INTEGER	PL/SQL Browser Y-coordinate
PLSQL_PROG_WIDTH	INTEGER	PL/SQL Browser width
PLSQL_PROG_HEIGHT	INTEGER	PL/SQL Browser height
PLSQL_BROWSER_HS	INTEGER	Library Browser hiding/showing
PLSQL_BROWSER_X	INTEGER	Library Browser X-coordinate
PLSQL_BROWSER_Y	INTEGER	Library Browser Y-coordinate
PLSQL_BROWSER_WIDTH	INTEGER	Library Browser width
PLSQL_BROWSER_HEIGHT	INTEGER	Library Browser height
BIND_VAR_HS	INTEGER	Parameter Table hiding/showing
BIND_VAR_X	INTEGER	Parameter Table X-coordinate
BIND_VAR_Y	INTEGER	Parameter Table Y-coordinate
BIND_VAR_WIDTH	INTEGER	Parameter Table width
BIND_VAR_HEIGHT	INTEGER	Parameter Table height
OPEN_DRAWING_TRIGNAME	RAW(255)	Open Display trigger name
OPEN_DRAWING_CHARSET	INTEGER	Open Display trigger name char set
OPEN_DRAWING_CHARLEN	INTEGER	Open Display trigger name length
CLOSE_DRAWING_TRIGNAME	RAW(255)	Close Display trigger name
CLOSE_DRAWING_CHARSET	INTEGER	Close Display trigger name char set
CLOSE_DRAWING_CHARLEN	INTEGER	Close Display trigger name length
BIND_VAR_NAME	RAW(255)	Parameter Table date format
BIND_VAR_CHAR	INTEGER	Parameter Table date format char set
BIND_VAR_LEN	INTEGER	Parameter Table date format length
TEMPLATE_NAME	RAW(255)	Current template name
TEMPLATE_NAME_CHAR	INTEGER	Current template name char set
TEMPLATE_NAME_LEN	INTEGER	Current template name length
ACTIVE_QUERY	INTEGER	Current query ID
DISPLAY_ROW	INTEGER	Number of rows in Parameter Table
OCL_VERSION	INTEGER	Oracle Charting Library version number


GO_PARAMETER

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEM	INTEGER	Parameter ID
PARAM_NAME	RAW(255)	Parameter name
PARAM_NAME_CHAR	INTEGER	Parameter name character set
PARAM_NAME_LEN	INTEGER	Parameter name length
PARAM_TYPE	INTEGER	Parameter type
PARAM_STR_NAME	RAW(255)	Parameter value
PARAM_STR_NAME_CHAR	INTEGER	Parameter value character set
PARAM_STR_NAME_LEN	INTEGER	Parameter value length
ROW_NUMBER	INTEGER	Parameter Table row


GO_QUERY

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEMID	INTEGER	Query ID
QUERY_NAME	RAW(255)	Query name
QUERY_NAME_CHAR	INTEGER	Query name character set
QUERY_NAME_LEN	INTEGER	Query name length
QUERY_SRC	LONG RAW	Query source
QUERY_SRC_CHAR	INTEGER	Query source character set
QUERY_SRC_LEN	INTEGER	Query source length
QUERY_TYPE	INTEGER	Query type
DATE_FORMAT	RAW(255)	Date format
DATE_FORMAT_CHAR	INTEGER	Date format character set
DATE_FORMAT_LEN	INTEGER	Date format length


GO_SOUND

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEMID	INTEGER	Sound ID
NAME	RAW(255)	Sound name
NAME_SET	INTEGER	Sound name character set
NAME_LEN	INTEGER	Sound name length
LONGID	INTEGER	Long field ID
RECVOLUME	INTEGER	Recording volume
PLAYVOLUME	INTEGER	Playback volume


GO_TIMER

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEM	INTEGER	Timer ID
TIMER_NAME	RAW(255)	Timer name
TIMER_NAME_CHARSET	INTEGER	Timer name character set
TIMER_NAME_LENGTH	INTEGER	Timer name length
PROC_NAME	RAW(255)	Timer procedure name
PROC_NAME_CHARSET	INTEGER	Procedure name character set
PROC_NAME_LENGTH	INTEGER	Procedure name length
TIMER_INTERVAL	INTEGER	Timer interval


GO_VISLAYER

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
LAYERID	INTEGER	Layer ID


VG_COLOR

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEMID	INTEGER	Instance ID
CELLID	INTEGER	Color cell ID
COLOR_NAME	RAW(255)	Color name
NAME_SET	INTEGER	Character set of color name
NAME_LENGTH	INTEGER	Length off color name
RED	INTEGER	Red component
GREEN	INTEGER	Green component
BLUE	INTEGER	Blue component


VG_DRAWING

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEMID	INTEGER	Instance ID
LONGID	INTEGER	Long field ID


VG_FONT

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEMID	INTEGER	Instance ID
FONTID	INTEGER	Font ID
COUNT	INTEGER	Number of objects that reference font
NAME	RAW(255)	Font name
NAME_SET	INTEGER	Font name character set
NAME_LEN	INTEGER	Font name length
FONT_SIZE	INTEGER	Font size
STYLE	INTEGER	Font style
WEIGHT	INTEGER	Font weight
WIDTH	INTEGER	Font width
IMAGETEXT	INTEGER	Font imagetext
KERNING	INTEGER	Font kerning
CHAR_SET	INTEGER	Font character set


VG_IMAGE

Name	Type	Description

OWNER	VARCHAR(30)	Owner ID
MODID	INTEGER	Module ID
ITEMID	INTEGER	Instance ID
IMAGEID	INTEGER	Image ID
COUNT	INTEGER	Number of objects that reference image
LONGID	INTEGER	Long field ID


About shared Oracle Product tables

Shared Oracle product tables contain module definitions, and may be shared with other Oracle products.  Through the use of database views and public synonyms, users can see information about modules they own or to which they have been granted access.


Shared Oracle Product tables

DE_ATTACHED_LIBS

ROSLFDESC

ROSSTRINGS

TOOL_ACCESS

TOOL_LRAW

TOOL_MODULE

TOOL_PLSQL


DE_ATTACHED_LIBS

Name	Type	Description

OWNER	VARCHAR(30)	Owner
MODID	DECIMAL(10)	Module ID
ITEMID	DECIMAL(10)	Library number (order in list)
LIBNAME	VARCHAR(30)	Library Name
LIBMODE	DECIMAL(10)	Library Mode (this is a bit mask)


ROSLFDESC

Name	Type	Description

OWNER	VARCHAR(30)	User
MODID	DECIMAL(10)	Module ID
ID	DECIMAL(10)	Long field ID
LPAGEID	DECIMAL(10)	Logical page sequence number
LFLEN	DECIMAL(10)	Long field length
N	DECIMAL(10)	Number of pages
DATALEN	DECIMAL(10)	Length of data this page
DATA	LONG RAW	Data (string)


ROSSEQUENCES

Name	Type	Description

OWNER	VARCHAR2(30)	Owner
MODID	DECIMAL(10)	Module ID
SEQNAME	VARCHAR2(30)	Sequence name
MIN_VAL	DECIMAL(10)	Minimum value
MAX_VAL	DECIMAL(10)	Maximum value
INC_BY	DECIMAL(10)	Increment step
CURRVAL	DECIMAL(10)	Current value
NEXTVAL	DECIMAL(10)	Next value
CACHESIZE	DECIMAL(10)	Cache size


ROSSTRINGS

Name	Type	Description

OWNER	VARCHAR(30)	User
MODID	DECIMAL(10)	Module ID
GROUPID	DECIMAL(10)	Group ID
STRINGID	DECIMAL(10)	Identifies instance of string in module
LFID	DECIMAL(10)	For ROS use
LEN length	DECIMAL(10)	Data (string)
CS	DECIMAL(10)	Character set
STR	LONG RAW	Data (string)


TOOL_ACCESS

Name	Type	Description

PRODUCT	VARCHAR(30)	Product name
OWNER	VARCHAR(30)	Module owner
MODID	INTEGER	Module ID
GRANTEE	VARCHAR(30)	User to whom access is granted


TOOL_LRAW

Name	Type	Description

OWNER	VARCHAR(30)	Module owner
MODID	DECIMAL(10)	Module ID
ID	DECIMAL(10)	LONG RAW field ID
LPAGEID	DECIMAL(10)	LONG RAW page ID
LFLEN	DECIMAL(10)	LONG RAW field length
N	DECIMAL(10)	LONG RAW field sequence number
ATALEN	DECIMAL(10)	LONG RAW field length
DATA	LONG RAW	LONG RAW data chunk


TOOL_MODULE

Name	Type	Description

PRODUCT	VARCHAR(30)	Product name
MODTYPE	VARCHAR(30)	Module type
MODID	DECIMAL(10)	Module ID
NEXT_ITEMID	DECIMAL(10)	Next available internal ID
OWNER	VARCHAR(30)	Module owner
MODNAME	VARCHAR(30)	Module name
CREATOR	VARCHAR(30)	User who created the module
CREATE_DATE	DATE	Creation date
CREATE_VER	DECIMAL(10)	Product version created with
MODIFIER	VARCHAR(30)	User who last modified the module
MOD_DATE	DATE	Modification date
MOD_VER	DECIMAL(10)	Product version modified with
COPYRIGHT	VARCHAR(250)	Module copyright notice
REQ_ROLE	VARCHAR(30)	Role required to run this module
TCS_VER	DECIMAL(8)	Version of TCS
VGS_VER	DECIMAL(8)	Version of VGS
DE_VER	DECIMAL(8)	Version of DE
ROS_VER	DECIMAL(8)	Version of ROS


TOOL_PLSQL

Name	Type	Description

OWNER	VARCHAR(30)	Module owner
MODID	DECIMAL(10)	Module ID
ITEMID	DECIMAL(10)	Item (program unit) ID
OBJECT_ID	DECIMAL(10)	Associated object ID (optional)
TYPE	DECIMAL(4)	Type of program unit (optional, product-defined)
NAME	VARCHAR(30)	Name of program unit
PLSLFID_ST	DECIMAL(10)	LONG field ID of PL/SQL source text
PLSLFID_EP	DECIMAL(10)	LONG field ID of PL/SQL encoded program unit


Font mapping

If you develop a display using one character set (e.g., WE8ISO8859P1) and then use another character set at runtime (EEC8EUROPA3), ensure that you make appropriate entries in your font aliasing file (uifont.ali) to map fonts between the character sets.

To define the font aliases used by Graphics Builder, edit uifont.ali.  For each font that you want to alias, make the following entry in the file:

source_font = destination_font

For each font, you can specify the following attributes:

<face>.<size>.<style>.<weight>.<width>.<character_set>

The <face> must be the name (string/identifier) of a font face.  The <style>, <weight>, <width>, and <character_set> may either be a numeric value or a predefined identifier/string.  For example, both US7ASCII and 1 are valid values, and refer to the same character set.  The <size> dimension must be an explicit size, in points.

The following is a list of recognized names and their numeric equivalents:

Styles	Numeric Value
----------------------------------------
plain	0
italic	1
oblique	2
underline	4
outline	8
shadow	16
inverted	32
overstrike	64
blink	128

Weights	Numeric Value
---------------------------------------
ultralight	1
extralight	2
light	3
demilight	4
medium	5
demibold	6
bold	7
extrabold	8
ultrabold	9
ultradense	1
extradense	2
dense	3
semidense	4
normal	5
semiexpand	6
expand	7
extraexpand	8
ultraexpand	9

Styles can be combined using the plus sign (+).  For example:

Arial..Italic+Overstrike = Helvetica.12.Italic.Bold

All strings are case-insensitive in mapping.  Font faces are likely to be case-sensitive on lookup, depending on the platform and surface, so care should be taken with names used on the right-hand side; but they will be mapped case-insensitively.

The backslash (\) is used as a continuation character.  Comments can be included as follows:

/* comment */
# comment
; comment

Font Mapping Verification

To verify that the uifont.ali file is correct, you can use fontchk.  This program will check your file to ensure there are no errors.  Enter the following to parse your font mapping file:

fontchk filename

Font Mapping Example

Below is a sample font mapping file that could be used with Graphics Builder.

[ Global ]  # Put mappings for all surfaces here.

# Mapping from MS Windows

Arial             = helvetica
"Courier New"     = courier
"Times New Roman" = times
Modern            = helvetica
"MS Sans Serif"   = helvetica
"MS Serif"        = times
"Small Fonts"     = helvetica

# Mapping from Macintosh

"New Century Schlbk" = "new century schoolbook"
"New York"           = "times"
[ Printer ]  # Put mappings for all printers here.
[ Printer:PostScript1 ]  /* Put mappings for PostScript
                            level 1 printers here. */

# Mapping from MS Windows

Roman             = palatino
Script            = "itc zapf chancery"
FixedSys          = courier
System            = helvetica
# Mapping from Macintosh
"Avant Garde"     = "itc avant garde gothic"

# Mapping from Motif display

fixed             = courier
clean             = times
lucidatypewriter  = courier
lucidabright      = times

# Sample Kanji font mappings

courier...Medium..JEUC   = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
courier...Bold..JEUC     = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC
courier...Medium..SJIS   = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
courier...Bold..SJIS     = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC
times...Medium..JEUC     = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
times...Bold..JEUC       = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC
times...Medium..SJIS     = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
times...Bold..SJIS       = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC
helvetica...Medium..JEUC = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
helvetica...Bold..JEUC   = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC
helvetica...Medium..SJIS = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
helvetica...Bold..SJIS   = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC

[ Printer:PostScript2 ]  /* Put mappings for PostScript
                            level 2 printers here. */

# Mapping from MS Windows

Roman             = palatino
Script            = "itc zapf chancery"
FixedSys          = courier
System            = helvetica

# Mapping from Macintosh

"Avant Garde"     = "itc avant garde gothic"

# Mapping from Motif display

fixed             = courier
clean             = times
lucidatypewriter  = courier
lucidabright      = times

# Sample Kanji font mappings

courier...Medium..JEUC   = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
courier...Bold..JEUC     = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC
Courier...Medium..SJIS   = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
courier...Bold..SJIS     = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC
times...Medium..JEUC     = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
times...Bold..JEUC       = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC
times...Medium..SJIS     = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
times...Bold..SJIS       = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC
helvetica...Medium..JEUC = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
helvetica...Bold..JEUC   = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC
helvetica...Medium..SJIS = \
   "Ryumin-Light-83pv-RKSJ-H"...Light..JEUC
helvetica...Bold..SJIS   = \
   "GothicBBB-Medium-83pv-RKSJ-H"...Medium..JEUC

[ Display ]  # Put mappings for all display surfaces here.

[ Display:Motif ]  # Put mappings for Motif displays here

# Mapping from MS Windows

Courier           = courier
Roman             = lucida
Script            = lucidabright
FixedSys          = fixed
System            = lucida

# Mapping from Macintosh

"Avant Garde"     = helvetica
"Bookman"         = times
[ Display:CM ]     # Put mappings for all CM displays here.

# These are DEC-specific, and may need localization

*..Blink          = Blinking
*..Inverted+Underline.Bold = ReverseBoldUnderline
*..Inverted+Underline.     = UnderlineReverse
*..Underline.Bold = UnderlineBold
*..Inverted.Bold  = ReverseBold
*...Bold          = Bold
*..Underline      = Underline
*..Inverted       = Reverse
*                 = Plain    # The font of last resort


Font mapping file

Graphics Builder supports font aliases.  The font mappings used by Graphics Builder are defined in the file uifont.ali.  You can alter these mappings by editing this file.  The location of this file varies according to your operating system.

Note:  Graphics Builder will look for the font mapping file in the location specified via the environment variable TK2_FONTALIAS.  If TK2_FONTALIAS is not specified, Graphics Builder will look in the default location for your operating system.


Supported functions for user exits

When you write a user exit using one of the ORACLE Precompiler host languages, the user exit can perform the following:

•	procedural operations (via host language statements)

•	additional functions (via the statements in the table below)

Available Statements	Usage

EXEC SQL	Performs SQL commands.
EXEC TOOLS GET	Passes values from Graphics Builder to a user exit.
EXEC TOOLS SET	Passes values from a user exit to Graphics Builder.
EXEC TOOLS MESSAGE	Passes one message and an optional message code from a user exit to Graphics Builder.
EXEC TOOLS GET CONTEXT	Passes a context pointer from Graphics Builder to a user exit.
EXEC TOOLS SET CONTEXT	Passes a context pointer from a user exit to Graphics Builder.
EXEC ORACLE	Executes ORACLE Precompiler options.


EXEC SQL

This statement is a SQL command, prefixed with "EXEC SQL".  EXEC SQL statements enable you to perform any SQL command in an ORACLE Precompiler user exit.  It is your means of selecting or manipulating data in the database from a user exit.

Syntax:	EXEC SQL sql_statement;

where:

sql_statement	Is any valid ORACLE SQL statement, except for the restricted commands noted in this section.

You do not need to perform an explicit CONNECT in an ORACLE Precompiler user exit, because Graphics Builder establishes the connection automatically.  However, ORACLE does support concurrent connects.  For more information, see the Programmer's Guide to the ORACLE Precompilers.

Note:  Graphics Builder does not COMMIT changes to the database after executing a display (with G30DES, G30RUN and/or G30BAT).  If you wish to COMMIT, you can do so with your user exit.


EXEC TOOLS GET

This statement passes a value from Graphics Builder to an ORACLE Precompiler user exit .  Specifically, it places the value of an Graphics Builder parameters into a host language variable.  Once Graphics Builder passes a value to a user exit, the user exit can use the value for calculation, manipulation, or update.

Syntax:	EXEC TOOLS GET display_variable_1[,
display_variable_2, ...]INTO :host_variable_1[,
:host_variable_2, ...];

where:

display_variable_n	Contains the name of the Graphics Builder parameter from which you are reading a value.

host_variable_n	Is the name of the host language variable into which you are reading a value.

Notes:

1	display_variable_n can be a reference to any of the following:

   a Graphics Builder parameter

  a host language variable (prefixed with a colon) whose value is a parameter name

2	Graphics Builder passes the display arguments to the user exit in standard SQL format:

   strings are passed surrounded with single quotes (see Rule 1 below)

  constants are passed as is (i.e., without any quotes)

  dates are passed in the format specified by the parameter's format mask, surrounded with single quotes (see Rule 1 below)

  host variables are preceded by colons (:)

The following table provides examples of how Graphics Builder passes arguments to a user exit:

Value	Result

`Summit'	Is how the constant string value Summit is passed.
413.60	Is how the constant numeric value 413.60 is passed.
`19910414083000'	Is how the date value April 14, 1991, 8:30 A.M., with a format mask of YYYYMMDDHH24MISS, is passed.
:holder1	Is how the value of the host variable holder1 is passed.
(For more information on restrictions on host language variables, see the Programmer's Guide to the ORACLE Precompilers.)

Rules:

1	Some of the host languages use double quotes, instead of single quotes.

2	If an Graphics Builder object's data is longer than 32K characters, the value returned from an EXEC TOOLS GET is truncated to the left-most 32K characters.


EXEC TOOLS SET

  Related Topics

This statement passes a value from an ORACLE Precompiler user exit to Graphics Builder .  Specifically, it places the value of a constant or the value of a host language variable into an Graphics Builder parameter.

Syntax:	EXEC TOOLS SET display_variable[, ...]VALUES
({:host_variable | constant}[, ...]);

where:

display_variable	Is the name of the Graphics Builder parameter into which you are reading a value.

host_variable	Is the name of the host language variable from which you are reading a value.

Constant	Is the constant that you are reading.

Note:  Arguments are passed to and from the user exit identically.

Rules:

1	Data that is longer than 32K characters cannot be EXEC TOOLS SET into an Graphics Builder parameter.


EXEC TOOLS GET CONTEXT

This statement passes a context from one ORACLE Precompiler user exit to another.  Specifically, it enables you to GET information from one user exit from another, without requiring global variables.

Syntax:	EXEC TOOLS GET CONTEXT application_context_name INTO
:host_variable_pointer;

where:

application_context_name	Is the name of the context you wish to access.

host_variable_pointer	Is the name of the host language pointer variable into which you putting the context.

Rules:

1	To GET a context, user exit must reside in the same process as the Graphics Builder executable in which it is linked (i.e., the user exit should not spawn a subprocess and expect the subprocess to be able to access the context).


EXEC TOOLS SET CONTEXT

This statement creates a named context .  Contexts enable you to share information across user exits, without requiring global variables.  Specifically, if a user exit named A creates a context, your other user exits that are linked with A can GET any information found in the context that A created.

Syntax:	EXEC TOOLS SET CONTEXT :host_variable_pointer BY
application_context_name;

where:

host_variable_pointer	Is the pointer to the context you are creating.

application_context_name	Is the name of the context.

Rules:

1	To share a context, the user exit must reside in the same process as the Graphics Builder executable in which it is linked (i.e., the user exit should not spawn a subprocess and expect the subprocess to be able to access the context).


 EXEC ORACLE

This is a statement that is not standard SQL, and is used to execute ORACLE Precompiler options.  For more information, see the Programmer's Guide to the ORACLE Precompilers.

Rules:

1	Graphics Builder does not COMMIT changes to the database after executing a display (with G30DES, G30RUN and/or G30BAT).  If you wish to COMMIT, you can do so with your user exit.


EXEC TOOLS MESSAGE

  Related Topics

This statement passes a message from an ORACLE Precompiler user exit to Graphics Builder.  Specifically, Graphics Builder will display the message like any other Graphics Builder's message (e.g., displayed as an alert, directed to your standard system output device, etc.).

Syntax:	EXEC TOOLS MESSAGE msg_text [msg_number];

where:

msg_text	Is at most 190 minus msg_text alphanumeric characters to be raised as the message.

msg_number	Is a number from 0-9999 to be raised as the message number.

Note:  You can also define and raise an error message using PL/SQL.


General rule

You cannot perform host language screen I/O from an ORACLE Precompiler user exit .  This restriction exists because the runtime routines that a host language uses to perform screen I/O conflict with the routines that Graphics Builder uses to perform its I/O.

You can perform host language file I/O from a user exit.


Syntax of a passed user exit call

Your user exit program will receive the user exit call as one string that contains first the user_exit_name and then optionally an argument_list.  Arguments in the argument_list are separated by one space.

Examples:

1	The following call:

OG_USER_EXIT('quota 10 20 Q4');

is passed to the user exit as:

'quota 10 20 Q4'

2	The following call:

OG_USER_EXIT('quota');

is passed to the user exit as:

'quota'

Rules:

1	It is the responsibility of the user exit — not Graphics Builder — to parse the user exit call string.

2	If more than one space exists between arguments that are passed with the user exit name, Graphics Builder will delete the extra spaces before it passes the strings to the user exit.

For example, the following call:

'quota 10     20  Q4'

is passed to the user exit as:

'quota 10 20 Q4'


Using Attribute Records

•	overview

•	shortcut built-ins

•	attribute record descriptions


Overview

Many of the built-in subprograms accept an argument that is described as an "attribute record."  An "attribute" is simply a property or characteristic of some Graphics Builder object.  For example, one attribute of a rectangle is the foreground fill color; two attributes of an arc are the start angle and end angle.  Graphics Builder has identified enough attributes to completely describe the structure and appearance of any object.

Graphics Builder provides several new built-in variable datatypes to control these attributes, most of which are defined to be RECORDs.  (For more information on the RECORD datatype, see the PL/SQL User's Guide and Reference.)  Each field in one of these records represents a particular attribute.  Thus, an "attribute record" refers to some variable whose type you have declared to be one of these new record datatypes.

For example, below is the type definition of OG_LINE_ATTR, the attribute record for a line:

TYPE og_line_attr IS RECORD
(mask        NUMBER(1,1),
 startpt     og_point,
 endpt       og_point,
 arrowstyle  NUMBER(1,0)
);

This record specifies attributes for a line's starting point, end point, and arrow style (the mask attribute will be described later).

All of an object's attributes are represented in one of several attribute records.  To programmatically modify one of these attributes (for example, to change its fill pattern), you must change the values of the appropriate fields in the appropriate attribute record, and then pass the attribute record to a procedure or function.  (Note that procedures and functions actually carry out your desired actions; however, you must use an attribute record to indicate to the procedure or function exactly what it is you want it to do.)


Attribute Classes

Some attribute records contain attributes that are common to many object types, while others contain attributes that are specific only to one object type.  For example, every object can have a name, but only text objects have a font size.

All attributes have been organized into the following classes:

•	generic

•	graphic

•	object-specific

Generic Attributes

Generic attributes apply to most object classes.  For example, most objects may have a name, an associated button procedure, or a parent object.

Graphic Attributes

Graphic attributes apply to many object classes, but not all.  They may be applied only to graphical objects (those objects that can be created with one of the graphical tools in the Layout editor).  For example, a graphic attribute such as `fill color' may be used to describe a rectangle, arc, symbol, etc.  However, it is meaningless to describe an image-which has no fill color-with this attribute.  Similarly, a group object cannot be described by graphic attributes.  (Note that while a group is not a graphical object, the individual components of the group may be.  Graphic attributes, then, may be applied to these components.)

Object-specific Attributes

Object-specific attributes apply only to a specific object class.  For example, `start angle' is an attribute that describes only an arc, and not a rectangle, line, image, or any other object.  Similarly, you may want to know the `number of children' that compose a group object, but it would be meaningless to use this attribute with any other object class.  Graphics Builder has identified attributes that are specific to application, arc, chart, group, image, line, polygon, rectangle, rounded rectangle, symbol, text, and window objects.

A built-in attribute record has been defined for generic attributes, and another for graphic attributes.  In addition, a separate attribute record has been defined for each collection of object-specific attributes.

The following is a list of Graphics Builder objects and the attribute records that are meaningful to each:

Object Class	Attribute Records
application	application
arc	generic graphic arc
chart	generic group chart
chart element	graphic chart element
display	display
graphic	generic graphic
group	generic group
image	genericimage
line	generic graphic line
polygon	generic graphic polygon
printer	printer
query	query
rectangle	generic graphic rectangle
rounded rectangle	generic graphic rounded rectangle
sound	sound
symbol	generic graphic symbol
text	generic graphic text
timer	timer
window	window


Combined Attribute Records

In addition to the attribute records described above, Graphics Builder also defines "combined attribute records."  A combined attribute record combines into a single variable all of the attribute records needed to completely describe an object.  As the name implies, it is another record, but each of its fields is either a generic, graphic, or object-specific attribute record.  Thus, in most cases you can use a single combined attribute record to control all of an object's attributes, instead of using several separate attribute records to represent each of the object's attribute classes.

For example, the rectangle combined attribute record contains three fields, representing the generic, graphic, and rectangle attribute records.  The image combined attribute record contains only two fields, representing the generic and image attribute records.

Below is the type definition of OG_LINE_CA, the combined attribute record for a line object:

TYPE og_line_ca IS RECORD
(line_caob  og_generic_attr,  /* generic attribute record*/
 line_caoh  og_graphic_attr,  /* graphic attribute record */
 line_caol  og_line_attr      /* line attribute record */
);

This combined attribute record contains three fields, representing generic, graphic, and line attribute records.


Mask Attributes

Each attribute record (but not combined attribute record) has a numeric field called a "mask."  The value of this field indicates which attributes in the attribute record you want to change (i.e., set) or examine (i.e., get).  When you use an attribute record as an argument for a procedure or function, that procedure or function will use the mask to determine which attributes it should pay attention to.

For example, suppose you want to change only an object's foreground fill color by setting the ffcolor attribute in a graphic attribute record, and then passing both that attribute record and the object's handle as arguments to the OG_SET_ATTR procedure.  The procedure does not know which attributes you want it to set; should it change all of the object's graphic attributes, or just some of them?  To learn this, it will look at the attribute record's mask attribute.

The value of a mask attribute indicates which attributes in its attribute record a procedure or function should use.  This value is called a "mask value."


Mask Constants

To help you determine an appropriate mask value for an attribute record, Graphics Builder has associated each attribute with a different built-in numeric constant, called a "mask constant."

Below is another listing of the line attribute record, this time with its mask constants:

TYPE og_line_attr IS RECORD    Mask Constants:
(mask       NUMBER(1,0),
 startpt    og_point,          OG_STARTPT_LINEA
 endpt      og_point,          OG_ENDPT_LINEA
 arrowstyle NUMBER(1,0)        OG_ARROWSTYLE_LINEA
);
                               OG_ALL_LINEA
                               OG_NONE_LINEA

After determining which attributes in an attribute record you want to use, calculate the sum of the mask constants that are associated with those attributes.  The result will be a mask value that represents only those attributes.  If you set the mask attribute in the attribute record to this mask value, then any procedure or function to which you pass this attribute record will pay attention only to those attributes.

For example, to change the startpt attribute in the above line attribute record, first declare a variable of this type:

my_variable   og_line_attr;

Then set the new value of the startpt attribute:

my_variable.startpt := new_point;

Finally, set the mask to indicate that you want to set a new starting point:

my_variable.mask := OG_STARTPT_LINEA;

(Note that this series of actions only prepares an attribute record for use by a procedure or function.  To understand how this relates to actually modifying an object, see the description of the specific procedure or function.)

If you wanted to set new values for both the starting point and end point of the line, you need to set the mask to indicate that.  In this case, the appropriate mask value would be the sum of the mask constants for those two attributes:

my_variable.mask := OG_STARTPT_LINEA +  OG_ENDPT_LINEA;

In addition to the mask constants for each attribute, every attribute record contains two additional attributes to indicate that all of the attributes should be used by a procedure or function, or that none should be used.  For the line attribute record, these mask constants are OG_ALL_LINEA and OG_NONE_LINEA.

Remember that these mask constants are numbers, and may be treated as such.  Besides adding them to indicate multiple attributes, you can also subtract them.  For example, to indicate that all attributes except the end point should be affected by a procedure or function, you can set the mask value to:

my_variable.mask := OG_ALL_LINEA - OG_ENDPT_LINEA;

In some cases, the same mask constant is used to represent multiple attributes within an attribute record.  If that mask constant is used to calculate the mask value, then all of the attributes represented by that constant will be used by the procedure or function to which the attribute record is passed.

Masks in Combined Attribute Records

It was stated above that all attribute records contain a mask attribute, but combined attribute records do not.  When you pass a combined attribute record as an argument to a procedure, that procedure will use the masks from each of the attribute records that are contained within it.

For example, suppose you declare a variable to be a line combined attribute record (recall that a line combined attribute record contains attribute records for generic, graphic, and line-specific attributes):

comb_variable   og_line_ca;

Next, you want to change several of the record's attributes.  In the generic attribute record, you want to change no values; in the graphic attribute record, you want to change the values of both the dashstyle and capstyle attributes; in the line attribute record, you want to change the value of only the arrowstyle attribute.  Below are the statements you might use:

comb_variable.line_caoh.dashstyle := new_dashstyle;
comb_variable.line_caoh.capstyle := new_capstyle;
comb_variable.line_caol.arrowstyle := new_arrowstyle;

Before you can pass this combined attribute record to a procedure that will implement your changes, you must set the mask in each attribute record to indicate which attributes in that record the procedure should use:

comb_variable.line_caob.mask := OG_NONE_GENERICA;
comb_variable.line_caoh.mask := OG_DASHSTYLE_GRAPHICA +
                                OG_CAPSTYLE_GRAPHICA;
comb_variable.line_caol.mask := OG_ARROWSTYLE_LINEA;

Note that you must set the mask for every attribute record within a combined attribute record, even if you do not want to use any attributes within that attribute record.  In this situation, you would set the mask to the mask constant that indicates no attributes will be used.

Once you have set the masks for each of the individual attribute records, you can pass the combined attribute record to a procedure or function.  Remember that an attribute record's mask value is the only way the procedure or function will know which attributes you want it to use.


Createable, Setable, Getable Attributes

Next to the listing of each attribute described below, you will find a one-, two-, or three-letter designation.

Letter	Meaning
C	Indicates the attribute is createable.  This means that Graphics Builder will recognize the value you assign to the attribute when the object containing the attribute is first created.  If the attribute is not createable, Graphics Builder will provide a default value when the object is created.
S	Indicates the attribute is setable.  This means that you are able to set the value of the attribute by invoking the appropriate Graphics Builder built-in subprogram.
G	Indicates the attribute is getable.  This means that you are able to get the value of the attribute by invoking the appropriate Graphics Builder built-in subprogram.


Shortcut Built-ins

In addition to the attribute record approach described above, Graphics Builder also provides a series of built-in subprograms to simplify the process of creating objects and getting or setting their attributes.  Each of these "shortcut" subprograms can be used to set or get a single attribute of an object.  For more information, see Graphics Builder Built-in overview.

For example, to set an object's fill and edge patterns using the attribute record approach, you need to set the new fill patterns, set the appropriate masks, and call OG_SET_ATTR:

PROCEDURE attr_rec_approach (my_obj OG_OBJECT) IS
   my_rec   og_graphic_ca;
BEGIN
   my_rec.graphic_caoh.fillpatt:='gray50';
   my_rec.graphic_caoh.edgepatt:='kangaroo';
   my_rec.graphic_caob.mask:=OG_NONE_GENERICA;
   my_rec.graphic_caoh.mask:=OG_FILLPATT_GRAPHICA+
                             OG_EDGEPATT_GRAPHICA;
   og_set_attr(my_obj, my_rec);
END;

By using the shortcuts, you can accomplish the same thing with only two procedure calls:

PROCEDURE shortcut_approach (my_obj OG_OBJECT) IS
BEGIN
   og_set_fillpatt(my_obj, 'gray50');
   og_set_edgepatt(my_obj, 'kangaroo');
END;

Advantages

Using the shortcuts instead of attribute records has the following advantages:

•	It requires less PL/SQL code, thus reducing development time.

•	It makes your program units easier to read and understand.

Disadvantages

Using the shortcuts instead of attribute records has the following disadvantages:

•	It is less efficient.  Because Graphics Builder uses attribute records internally, each time you call a shortcut, Graphics Builder must define and populate a new internal attribute record.  In addition, it takes longer to execute multiple `set' routines than it does to execute just one.  In the above example, the first procedure (with one `set' call) will be roughly twice as fast as the second procedure (with two `set' calls).

•	It requires your application to rely on default settings, since calling multiple shortcuts to set all of the necessary attributes may seriously affect your application's performance.


Application Attribute Record

The application attribute record contains attributes that may be used with the current application.

TYPE og_app_attr IS RECORD            Mask Constants:
(mask         NUMBER(3,0),
 cursor       VARCHAR2(255),          OG_CURSOR_APPA
 hscreen_res  NUMBER(5,0),            OG_SCREEN_RES_APPA
 vscreen_res  NUMBER(5,0),            OG_SCREEN_RES_APPA
 hlayout_res  NUMBER(10,0),           OG_LAYOUT_RES_APPA
 vlayout_res  NUMBER(10,0),           OG_LAYOUT_RES_APPA
 platform     NUMBER(1,0),            OG_PLATFORM_APPA
 username     VARCHAR2(255),          OG_USERNAME_APPA
 password     VARCHAR2(255),          OG_PASSWORD_APPA
 connection   VARCHAR2(255)           OG_CONNECTION_APPA
);
                                      OG_ALL_APPA
                                      OG_NONE_APPA

	Attribute	Description
SG	cursor	Is the name of the mouse cursor to use.  The value of this attribute may be one of the following strings: default insertion crosshair help busy The appearance of each cursor is system-specific.  For more information, refer to your system documentation.  If you set this attribute to an invalid value, it assumes the value `default.'
G	hscreen_res	Is the horizontal resolution of the screen.  This value is the number of screen resolution units (i.e., pixels) in one horizontal inch of the screen.
G	vscreen_res	Is the vertical resolution of the screen.  This value is the number of screen resolution units (i.e., pixels) in one vertical inch of the screen.
G	hlayout_res	Is the horizontal resolution of the layout.  This value is the number of layout units in one horizontal inch of the layout.
G	vlayout_res	Is the vertical resolution of the layout.  This value is the number of layout units in one vertical inch of the layout.
G	platform	Is the platform on which Graphics Builder is running.  The value of this attribute may be one of the following built-in constants:
		OG_MACINTOSH_PLATFORM   Means the platform is the Apple Macintosh.
		OG_MOTIF_PLATFORM   Means the platform is OSF/MOTIF.
		OG_MSWINDOWS_PLATFORM   Means the platform is Microsoft Windows.
		OG_PM_PLATFORM   Means the platform is Presentation Manager.
		OG_X_PLATFORM   Means the platform is the X Window System.
G	username	Is the username for the current database connection.  If the user is not connected, this attribute is NULL.
G	password	Is the password for the current database connection.  If the user is not connected, or the Keep_Password preference setting is set to No, this attribute is NULL.
G	connection	Is the database connection string for the current database connection.  If the user is not connected, this attribute is NULL.


Arc Combined Attribute Record

The arc combined attribute record consists of a generic attribute record, graphic attribute record, and arc attribute record:

TYPE og_arc_ca IS RECORD
(arc_caob  og_generic_attr,   /* generic */
 arc_caoh  og_graphic_attr,   /* graphic */
 arc_caoa  og_arc_attr        /* arc */
);


Arc Attribute Record

The arc attribute record contains attributes that may be used only with arc objects:

TYPE og_arc_attr IS RECORD                Mask Constants:
(mask     NUMBER(1,0),
 basearc  og_arc,                         OG_BASEARC_ARCA
 arcfill  NUMBER(1,0),                    OG_ARCFILL_ARCA
 closed   BOOLEAN                         OG_CLOSED_ARCA
);
                                          OG_ALL_ARCA
                                          OG_NONE_ARCA

	Attribute	Description
CSG	basearc	Is the x- and y-coordinates of the upper-left corner, and the height and width of the rectangle used as the basis for the ellipse from which the arc is cut.
CSG	arcfill	Is the fill shape of the arc.  The value of this attribute may be one of the following built-in constants:
		OG_CHORD_ARCFILL   Means the fill shape of the arc is that of a chord.
		OG_PIE_ARCFILL   Means the fill shape of the arc is that of a full pie slice.
CSG	closed	Is the closure of the arc.  The value of this attribute may be one of the following:
		TRUE   Means the arc is closed.
		FALSE   Means the arc is open.


Continuous Axis Combined Attribute Record

TYPE og_contaxis_ca IS RECORD
(ca_axis  og_axis_attr,       /* generic axis */
 ca_cont  og_contaxis_attr   /* continuous axis */
);


Continuous Axis Attribute Record

TYPE og_contaxis_attr IS RECORD     Mask Constants:
(mask      NUMBER(4,0),
 automin   BOOLEAN,                 OG_MINIMUM_CONTAXISA
 minimum   NUMBER(6),               OG_MINIMUM_CONTAXISA
 autostep  BOOLEAN,                 OG_STEP_CONTAXISA
 step      NUMBER(6),               OG_STEP_CONTAXISA
 automax   BOOLEAN,                 OG_MAXIMUM_CONTAXISA
 maximum   NUMBER(6),               OG_MAXIMUM_CONTAXISA
 scale     NUMBER(1,0),             OG_SCALE_CONTAXISA
 pct_of    NUMBER(1,0),             OG_PCTOF_CONTAXISA
 pct_by    NUMBER(1,0),             OG_PCTBY_CONTAXISA
 numfmt    VARCHAR2(255)            OG_NUMFMT_CONTAXISA
);
                                    OG_ALL_CONTAXISA
                                    OG_NONE_CONTAXISA

	Attribute	Description
SG	automin	Specifies whether the axis minimum is set to Auto.
SG	minimum	Specifies the minimum axis value (if automin is FALSE).
SG	autostep	Specifies whether the axis step value is set to Auto.
SG	step	Specifies the axis step value (if autostep is FALSE).
SG	automax	Specifies whether the axis maximum is set to Auto.
SG	maximum	Specifies the maximum axis value (if automax is FALSE).
SG	scale	Specifies the algorithm used for scaling the axis.  The value of this attribute may be one of the following built-in constants:
		OG_LINEAR_SCALE   Means the axis is scaled using a fixed interval between the minimum and maximum axis values.
		OG_LOG_SCALE   Means the axis is scaled using a logarithmic algorithm (based on powers of 10) to determine the intervals between the minimum and maximum axis values.
		OG_PCT_SCALE   Means the axis is scaled so that data values will be plotted relative to the amount specified by pct_of.
SG	pct_of	Specifies the relative scaling factor (if scale is set to OG_PCT_SCALE).  The value of this attribute may be one of the following built-in constants:
		OG_MAXIMUM_PCTOF   Meanseach data value is plotted as a percentage of the largest data value.
		OG_MINIMUM_PCTOF   Means each data value is plotted as a percentage of the smallest data value.
		OG_SUM_PCTOF   Means each data value is plotted as a percentage of the sum of all data values.
SG	pct_by	Specifies how the pct_of scaling values are calculated.  The value of this attribute may be one of the following built-in constants:
		OG_CATEGORY_PCTBY   Means the percentage for each data value is calculated relative to data values for the same field in other categories.
		OG_FIELD_PCTBY   Means the percentage for each data value is calculated relative to data values in the same category for other fields.
SG	numfmt	Specifies the number format for the axis tick labels.  This must be a valid SQL format string.  For more information, see yourOracle7 Server SQL Reference.


Date Axis Combined Attribute Record

TYPE og_dateaxis_ca IS RECORD
(ca_axis  og_axis_attr,       /* generic axis */
 ca_date  og_dateaxis_attr   /* date axis */
);


Date Axis Attribute Record

TYPE og_dateaxis_attr IS RECORD   Mask Constants:
(mask       NUMBER(5,0),
 automin    BOOLEAN,              OG_MINIMUM_DATEAXISA
 minimum    DATE,                 OG_MINIMUM_DATEAXISA
 autostep   BOOLEAN,              OG_STEP_DATEAXISA
 step       NUMBER(2,0),          OG_STEP_DATEAXISA
 automax    BOOLEAN,              OG_MAXIMUM_DATEAXISA
 maximum    DATE,                 OG_MAXIMUM_DATEAXISA
 firstmon   NUMBER(2,0),          OG_FIRSTMON_DATEAXISA
 skipwknds  BOOLEAN,              OG_SKIPWKNDS_DATEAXISA
 labels     NUMBER(4,0),          OG_LABELS_DATEAXISA
 dayfmt     NUMBER(1,0),          OG_DAYFMT_DATEAXISA
 monthfmt   NUMBER(1,0),          OG_MONTHFMT_DATEAXISA
 qtrfmt     NUMBER(1,0),          OG_QTRFMT_DATEAXISA
 yearfmt    NUMBER(1,0),          OG_YEARFMT_DATEAXISA
 custfmt    VARCHAR2(255)         OG_CUSTMT_DATEAXISA
);
                                  OG_ALL_DATEAXISA
                                  OG_NONE_DATEAXISA

	Attribute	Description
SG	automin	Specifies whether the axis minimum is set to Auto.
SG	minimum	Specifies the minimum axis value (if automin is FALSE).
SG	autostep	Specifies whether the axis step value is set to Auto.
SG	step	Specifies the axis step value (if autostep is FALSE).  The value of this attribute may be one of the following built-in constants:
		OG_SECOND_STEP
		OG_MINUTE_STEP
		OG_HOUR_STEP
		OG_DAY_STEP
		OG_WEEK_STEP
		OG_MONTH_STEP
		OG_QUARTER_STEP
		OG_YEAR_STEP
SG	automax	Specifies whether the axis maximum is set to Auto.
SG	maximum	Specifies the maximum axis value (if automax is FALSE).
SG	firstmonth	Is the month that is considered to begin a new year.  The value of this attribute may be one of the following built-in constants:
		OG_JAN_MONTH
		OG_FEB_MONTH
		OG_MAR_MONTH
		OG_APR_MONTH
		OG_MAY_MONTH
		OG_JUN_MONTH
		OG_JUL_MONTH
		OG_AUG_MONTH
		OG_SEP_MONTH
		OG_OCT_MONTH
		OG_NOV_MONTH
		OG_DEC_MONTH
SG	skipweekends	Specifies whether weekends are ignored when calculating axis values.
SG	labels	Specifies the major interval along the axis at which major tick marks and tick labels appear, as well as the appearance of the tick labels.  The value of this attribute may be one of the following built-in constants:
		OG_NO_LABELS
		OG_SECOND_LABELS
		OG_MINUTE_LABELS
		OG_HOUR_LABELS
		OG_AMPM_LABELS
		OG_DAY_LABELS
		OG_DAYOFWEEK_LABELS
		OG_WEEK_LABELS
		OG_MONTH_LABELS
		OG_QUARTER_LABELS
		OG_YEAR_LABELS
		OG_CUSTOM_LABELS   (If labels is set to this value, you must specify the custom date format in the customfmt attribute.)
SG	dayfmt	Determines the appearance of day-of-the-week labels along the axis.  The value of this attribute may be one of the following built-in constants:
		OG_FIRSTLETTER_FMT
		OG_THREELETTER_FMT
SG	monthfmt	Determines the appearance of month labels along the axis.  The value of this attribute may be one of the following built-in constants:
		OG_FIRSTLETTER_FMT
		OG_THREELETTER_FMT
SG	quarterfmt	Determines the appearance of quarter labels along the axis.  The value of this attribute may be one of the following built-in constants:
		OG_ARABIC_FMT
		OG_ROMAN_FMT
SG	yearfmt	Determines the appearance of year labels along the axis.  The value of this attribute may be one of the following built-in constants:
		OG_FOURDIGIT_FMT
		OG_TWODIGIT_FMT
SG	custfmt	Is the custom date format for the axis tick labels.  This must be a valid SQL format string.  For more information, see yourOracle7 Server SQL Reference.


Discrete Axis Combined Attribute Record

TYPE og_discaxis_ca IS RECORD
(ca_axis  og_axis_attr,       /* generic axis */
 ca_disc  og_discaxis_attr   /* discrete axis */
);


Discrete Axis Attribute Record

TYPE og_discaxis_attr IS RECORD       Mask Constants:
(mask     NUMBER(3,0),
 automin  BOOLEAN,                    OG_MINCAT_DISCAXISA
 mincat   NUMBER(10,0),               OG_MINCAT_DISCAXISA
 automax  BOOLEAN,                    OG_MAXCAT_DISCAXISA
 maxcat   NUMBER(10,0),               OG_MAXCAT_DISCAXISA
 numfmt   VARCHAR2(255),              OG_NUMFMT_DISCAXISA
 datefmt  VARCHAR2(255)               OG_DATEFMT_DISCAXISA
);
                                      OG_ALL_DISCAXISA
                                      OG_NONE_DISCAXISA

	Attribute	Description
SG	automin	Specifies whether the minimum number of categories that appear on the axis is set to Auto.
SG	mincat	Specifies the minimum number of categories that appear on the axis (if automin is FALSE).
SG	automax	Specifies whether the maximum number of categories that appear on the axis is set to Auto.
SG	maxcat	Specifies the maximum number of categories that appear on the axis (if automax is FALSE).
SG	numfmt	Specifies the number format for the axis tick labels.  This must be a valid SQL format string.  For more information, see yourOracle7 Server SQL Reference.
SG	datefmt	Specifies the date format for the axis tick labels.  This must be a valid SQL format string.  For more information, see yourOracle7 Server SQL Reference.


Axis Attribute Record

TYPE og_axis_attr IS RECORD          Mask Constants:
(mask          NUMBER(5,0),
 axistype      NUMBER(1,0),          OG_AXISTYPE_AXISA
 custlabel     VARCHAR2(255),        OG_CUSTLABEL_AXISA
 position      NUMBER(1,0),          OG_POSITION_AXISA
 direction     NUMBER(1,0),          OG_DIRECTION_AXISA
 tickpos       NUMBER(1,0),          OG_TICKPOS_AXISA
 ticklabelrot  NUMBER(1,0),          OG_TICKLABELROT_AXISA
 minorct       NUMBER(1,0),          OG_MINORCT_AXISA
 majorticks    BOOLEAN,              OG_MAJORTICKS_AXISA
 minorticks    BOOLEAN,              OG_MINORTICKS_AXISA
 majorgrid     BOOLEAN,              OG_MAJORGRID_AXISA
 minorgrid     BOOLEAN,              OG_MINORGRID_AXISA
 axislabel     BOOLEAN,              OG_AXISLABEL_AXISA
 ticklabels    BOOLEAN               OG_TICKLABELS_AXISA
);
                                     OG_ALL_AXISA
                                     OG_NONE_AXISA

	Attribute	Description
SG	axistype	The value of this attribute may be one of the following built-in constants:
		OG_CONTINUOUS_AXISTYPE
		OG_DATE_AXISTYPE
		OG_DISCRETE_AXISTYPE
SG	custlabel	Specifies the text of the label that appears along the axis.
SG	position	Specifies along which edge of the chart the axis appears.  The value of this attribute may be one of the following built-in constants:
		OG_BOTTOM_POSITION
		OG_LEFT_POSITION
		OG_RIGHT_POSITION
		OG_TOP_POSITION
SG	direction	Specifies in which direction increasing values, or successive categories, are placed along the axis.  The value of this attribute may be one of the following built-in constants:
		OG_DOWN_DIRECTION
		OG_LEFT_DIRECTION
		OG_RIGHT_DIRECTION
		OG_UP_DIRECTION
SG	tickpos	Specifies how the major and minor tick marks appear.  The value of this attribute may be one of the following built-in constants:
		OG_CROSS_TICKPOS
		OG_INSIDE_TICKPOS
		OG_OUTSIDE_TICKPOS
SG	ticklabelrot	The value of this attribute may be one of the following built-in constants:
		OG_CCW_ROTATION
		OG_CW_ROTATION
		OG_NO_ROTATION
SG	minorct	Is the number of minor ticks defined within each major tick interval.
SG	majorticks	Specifies whether major tick marks appear at each major interval.
SG	minorticks	Specifies whether minor tick marks appear, as specified by the value set for Minor Ticks per Interval.
SG	majorgrid	Specifies whether a grid line appears at each major tick mark.
SG	minorgrid	Specifies whether a grid line appears at each minor tick mark.
SG	axislabel	Specifies whether labels that identify values along the axis appear.
SG	ticklabels	Specifies whether labels that identify values along the axis appear.


Chart Combined Attribute Record

A chart is treated like a group object, consisting of lines, rectangles, text, etc.  Therefore, the chart combined attribute record allows you access to group attributes, as well as attributes specific to a chart.  Additionally, since a chart itself is not a graphical object (although the objects that compose it are), this record does not provide access to graphic attributes.  To set the graphical attributes of individual elements of a chart, use the chart element attribute record (described below).

This record may be used to access the attributes of a chart drawn manually on the layout only if the chart was specified as dynamic.  If the chart is artwork, it is considered to be a group object, and not a chart object.  A chart that is created programmatically is a dynamic chart.

The chart combined attribute record consists of a generic attribute record, group attribute record, and chart attribute record:

TYPE og_chart_ca IS RECORD
(chart_caob  og_generic_attr,   /* generic */
 chart_caog  og_group_attr,     /* graphic */
 chart_caoc  og_chart_attr      /* chart */
);


Chart Attribute Record

The chart attribute record contains attributes that may be used only with chart objects:

TYPE og_chart_attr IS RECORD        Mask Constants:
(mask        NUMBER(4,0),
 frame       og_rectangle,          OG_FRAME_CHARTA
 template    og_template,           OG_TEMPLATE_CHARTA
 query       og_query,              OG_QUERY_CHARTA
 title       VARCHAR2(255),         OG_TITLE_CHARTA
 autoupdate  BOOLEAN,               OG_AUTOUPDATE_CHARTA
 rangeflag   BOOLEAN,               OG_ROWS_CHARTA
 startrow    NUMBER(10,0),          OG_ROWS_CHARTA
 endrow      NUMBER(10,0),          OG_ROWS_CHARTA
 filter      VARCHAR2(255)          OG_FILTER_CHARTA
);
                                    OG_ALL_CHARTA
                                    OG_NONE_CHARTA

	Attribute	Description
CSG	frame	Is the x- and y-coordinates, height, and width of the chart's frame (in layout units).
CSG	template	Is the handle to the template to be used for the chart.
CSG	query	Is the handle to the query to be used for the chart.
CSG	title	Is the title of the chart.
CSG	autoupdate	Specifies that the chart is automatically be updated when the query is executed.
CSG	rangeflag	Specifies whether the number of query rows that appear on the chart is restricted to the range specified by startrow and endrow.
CSG	startrow	Is the first row from the query that appears on the chart.  The first query row is 0, the second row is 1, and so on.
CSG	endrow	Is the last row from the query that appears on the chart.
CSG	filter	Is the name of the query's filter trigger procedure.


Chart Element Combined Attribute Record

A chart element is a graphical object that represents a single value for a field.  For example, bars and pie slices are chart elements.This combined attribute record is used in conjunction with the OG_SET_ATTR procedure to change the attributes of a chart element.

The chart element combined attribute record consists of a graphic attribute record and chart element attribute record:

TYPE og_chelement_ca IS RECORD
(chelement_cagr  og_graphic_attr,    /* graphic */
 chelement_cace  og_chelement_attr   /* chart element */
);


Chart Element Attribute Record

The chart element attribute record contains attributes that may be used only with chart elements:

TYPE og_chelement_attr IS RECORD   Mask Constants:
(mask       NUMBER(1,0),
 button     og_buttonproc,         OG_BUTTON_CHELEMENTA
 events     NUMBER(2,0),           OG_BUTTON_CHELEMENTA
 explosion  NUMBER(10,0),          OG_EXPLOSION_CHELEMENTA
 name       VARCHAR2(255)          OG_NAME_CHELEMENTA
);
                                   OG_ALL_CHELEMENTA
                                   OG_NONE_CHELEMENTA

	Attribute	Description
S	button	Is the handle to the button procedure that should be associated with this chart element.  Note that the events attribute must be set properly in order to ensure that this procedure receives the desired mouse events.
S	events	Is the type of mouse events that the button procedure should receive.  The value of this attribute may be one of the built-in constants listed below.  To enable the procedure to receive multiple event types, set this attribute to be the sum of the constants for the desired events.
		OG_NO_EVENTS   Means the procedure receives no mouse events.
		OG_MOUSE_DOWN   Means the procedure receives only mouse down events.
		OG_MOUSE_MOVE_DOWN   Means the procedure receives only mouse move down events.
		OG_MOUSE_UP   Means the procedure receives only mouse up events.
		OG_MOUSE_MOVE_UP   Means the procedure receives only mouse move up events.
S	explosion	Is the distance that the chart element (i.e., pie  slice) should be exploded, in terms of the percentage of the chart's x- and y-radii.  This attribute is meaningful only when used with a pie chart.  In addition, all of the pie slices for a given category will be exploded the same amount.  Therefore, the attribute record that specifies an explosion value should be associated with an independent field.
S	name	Is the name of the chart element.  To get the name of a chart element, use the generic attribute record.


Display Attribute Record

The display attribute record contains attributes that may be used only with the current display:

TYPE og_display_attr IS RECORD	   Mask Constants:
(mask          NUMBER(2,0),
 opentrigger   VARCHAR2(255),        OG_OPENTRIGGER_DISPLAYA
 closetrigger  VARCHAR2(255),        OG_CLOSETRIGGER_DISPLAYA
 width         NUMBER(10,0),         OG_SIZE_DISPLAYA
 height        NUMBER(10,0),         OG_SIZE_DISPLAYA
 dateformat    VARCHAR2(255)         OG_DATEFORMAT_DISPLAYA
);
                                     OG_ALL_DISPLAYA
                                     OG_NONE_DISPLAYA

	Attribute	Description
SG	opentrigger	Is the name of diplay's Open Display trigger.
SG	closetrigger	Is tforhe name of diplay's Close Display trigger.
SG	width	Is the width of the layout (in layout units).
SG	height	Is the height of the layout (in layout units).
SG	dateformat	Specifies the date format for parameters.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.


Axis Field Template Combined Attribute Record

TYPE og_axisftemp_ca IS RECORD
(ca_ftemp   og_ftemp_attr,     /* generic field template */
 ca_aftemp  og_axisftemp_attr  /* axis field template */
);


Axis Field Template Attribute Record

TYPE og_axisftemp_attr IS RECORD   Mask Constants:
(mask       NUMBER(3,0),
 plottype   NUMBER(3,0),           OG_PLOTTYPE_AXISFTEMPA
 linestyle  NUMBER(1,0),           OG_LINESTY_AXISFTEMPA
 labelrot   NUMBER(1,0),           OG_LABELROT_AXISFTEMPA
 plotpos    NUMBER(1,0),           OG_PLOTPOS_AXISFTEMPA
 overlap    NUMBER(3),             OG_OVERLAP_AXISFTEMPA
 axis       NUMBER(1,0),           OG_AXIS_AXISFTEMPA
 curvefit   NUMBER(1,0)            OG_CURVEFIT_AXISFTEMPA
);
                                   OG_ALL_AXISFTEMPA
                                   OG_NONE_AXISFTEMPA

	Attribute	Description
SG	plottype	Specifies the elements used to plot this field on the chart.  The value of this attribute may be one of the following built-in constants:
		OG_NONE_PLOTTYPE
		OG_BAR_PLOTTYPE
		OG_LINE_PLOTTYPE
		OG_SYMBOL_PLOTTYPE
		OG_FILL_PLOTTYPE
		OG_SPIKE_PLOTTYPE
		OG_LABEL_PLOTTYPE
SG	linestyle	Specifies the line style used to connect the data points of a field with a line plot type.  The value of this attribute may be one of the following built-in constants:
		OG_SPLINE_LINESTYLE
		OG_STEP_LINESTYLE
		OG_STRAIGHT_LINESTYLE
SG	labelrot	Specifies the rotation angle of the labels for a field with a label plot type.  The value of this attribute may be one of the following built-in constants:
SG	plotpos	Specifies—for each category—the relationship between the data values of two or more fields.  The value of this attribute may be one of the following built-in constants:
		OG_NORMAL_PLOTPOS
		OG_FROMPREV_PLOTPOS
		OG_STACKED_PLOTPOS
SG	overlap	Specifies the percentage by which bars representing data values from multiple fields in a bar or column chart overlap each other.
SG	axis	Specifies the axis to which data values are compared to determine how the field is plotted.  The value of this attribute may be one of the following built-in constants:
		OG_X_AXIS
		OG_Y1_AXIS
		OG_Y2_AXIS
SG	curvefit	Specifies whether a curve fit is applied to the chart and, if so, which algorithm is used.  The value of this attribute may be one of the following built-in constants:
		OG_NO_CURVEFIT
		OG_LINEAR_CURVEFIT
		OG_LOG_CURVEFIT
		OG_EXP_CURVEFIT
		OG_POWER_CURVEFIT


Field Template Attribute Record

TYPE og_ftemp_attr IS RECORD           Mask Constants:
(mask      NUMBER(3,0),
 name      VARCHAR2(255),              OG_NAME_FTEMPA
 root      OG_OBJECT,                  OG_ROOT_FTEMPA
 colorrot  NUMBER(1,0),                OG_COLORROT_FTEMPA
 numfmt    VARCHAR2(255),              OG_NUMFMT_FTEMPA
 datefmt   VARCHAR2(255)               OG_DATEFMT_FTEMPA
);
                                       OG_ALL_FTEMPA
                                       OG_NONE_FTEMPA

	Attribute	Description
SG	name	Is the name of the field template.
G	root	Is a handle to the chart template to which the field template belongs.
SG	colorrot	Specifies whether Graphics Builder automatically rotates through the color or pattern palette to select a unique shading for each field that uses this field template.  The value of this attribute may be one of the following built-in constants:
		OG_NO_COLORROT
		OG_AUTO_COLORROT
		OG_COLOR_COLORROT
		OG_PATTERN_COLORROT
		OG_BOTH_COLORROT
SG	numfmt	Specifies the number format for the field labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.
SG	datefmt	Specifies the date format for the field labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.


Axis Frame Combined Attribute Record

TYPE og_axisframe_ca IS RECORD
(ca_frame  og_frame_attr,       /* generic frame */
 ca_axis   og_axisframe_attr    /* axis frame */
);


Axis Frame Attribute Record

TYPE og_axisframe_attr IS RECORD   Mask Constants:
(mask       NUMBER(3,0),
 reflinect  NUMBER(3,0),           OG_REFLINECT_AXISFRAMEA
 basevalue  NUMBER(1,0),           OG_BASEVALUE_AXISFRAMEA
 cust_num   NUMBER(6),             OG_BASEVALUE_AXISFRAMEA
 cust_date  DATE,                  OG_BASEVALUE_AXISFRAMEA
 base_axis  NUMBER(1,0),           OG_BASEAXIS_AXISFRAMEA
 catwidth   NUMBER(3,0),           OG_CATWIDTH_AXISFRAMEA
 second_y   BOOLEAN                OG_SECONDY_AXISFRAMEA
);
                                   OG_ALL_AXISFRAMEA
                                   OG_NONE_AXISFRAMEA

	Attribute	Description
G	reflinect	Is the number of reference lines that belong to the chart template.
SG	baseline_value	Is the value used as the starting point for plotting fields along the value axis.  The value of this attribute may be one of the following built-in constants:
		OG_MIN_BASELINE
		OG_MAX_BASELINE
		OG_ZERO_BASELINE
		OG_CUSTOM_BASELINE
SG	custom_num	Specifies the custom number to set the baseline to.  This will automatically set the base value to OG_CUSTOM_BASELINE.
SG	custom_date	Specifies the custom date to set the custom date value to.  This will automatically set the base value to OG_CUSTOM_BASELINE.
SG	baseline_axis	Specifies the axis to which the baseline value is compared to determine its position.
SG	catwidth	Is the width of the bars in a bar or column chart, as a percentage of the "strip width."  The strip width is the widest the bars can be without overlapping each other, and it is determined by dividing the length of the category axis by the number of bars to be plotted.
SG	second_y	Specifies whether a second Y axis appears in the chart.


Frame Attribute Record

TYPE og_frame_attr IS RECORD       Mask Constants:
(mask         NUMBER(4,0),
 name         VARCHAR2(255),       OG_NAME_FRAMEA
 frametype    NUMBER(1,0),         OG_FRAMETYPE_FRAMEA
 ftempct      NUMBER(5,0),         OG_FTEMPCT_FRAMEA
 root         OG_OBJECT,           OG_ROOT_FRAMEA
 depthsize    NUMBER(1,0),         OG_DEPTHSIZE_FRAMEA
 shadowsize   NUMBER(1,0),         OG_SHADOWSIZE_FRAMEA
 shadowdir    NUMBER(1,0),         OG_SHADOWDIR_FRAMEA
 plotframe    BOOLEAN,             OG_PLOTFRAME_FRAMEA
 legend       BOOLEAN,             OG_LEGEND_FRAMEA
 legendcolct  NUMBER(3,0)          OG_LEGENDCOLCT_FRAMEA
);
                                   OG_ALL_FRAMEA
                                   OG_NONE_FRAMEA

	Attribute	Description
SG	name	Is the name of the chart template.
G	frametype	Is the type of chart represented by this template  The value of this attribute may be one of the following built-in constants:
		OG_AXIS_FRAMETYPE
		OG_PIE_FRAMETYPE
		OG_TABLE_FRAMETYPE
G	ftempct	Is the number of field templates that belong to the chart template.
G	root	Is the handle to the chart template.
SG	depthsize	Specifies the amount of depth with which the chart frame and elements are drawn to provide them with a 3-dimensional look.  The value of this attribute may be one of the following built-in constants:
		OG_NONE_DEPTHSIZE
		OG_SMALL_DEPTHSIZE
		OG_MEDIUM_DEPTHSIZE
		OG_LARGE_NONE_DEPTHSIZE
		OG_XLARGE_DEPTHSIZE
SG	shadowsize	Specifies the size of the shadow with which the chart frame and elements are drawn.  The value of this attribute may be one of the following built-in constants:
		OG_NONE_SHADOWSIZE
		OG_SMALL_SHADOWSIZE
		OG_MEDIUM_SHADOWSIZE
		OG_LARGE_SHADOWSIZE
		OG_XLARGE_SHADOWSIZE
SG	shadowdir	Specifies the direction of the shadow with which the chart frame and elements are drawn.  The value of this attribute may be one of the following built-in constants:
		OG_UPPERRIGHT_SHADOWDIR
		OG_UPPERLEFT_SHADOWDIR
		OG_LOWERRIGHT_SHADOWDIR
		OG_LOWERLEFT_SHADOWDIR
SG	plotframe	Specifies whether the rectangle that surrounds the chart should be shown.  (Not applicable to pie charts.)
SG	legend	Specifies whether the chart's legend should be shown.  (Not applicable to table charts.)
SG	legendcolct	Is the number of columns used to display the labels that appear in the legend.


Pie Frame Combined Attribute Record

TYPE og_pieframe_ca IS RECORD
(ca_frame  og_frame_attr,     /* generic frame */
 ca_pie   og_pieframe_attr   /* pie frame */
);


Pie Frame Attribute Record

TYPE og_pieframe_attr IS RECORD   Mask Constants:
(mask        NUMBER(3,0),
 usage       NUMBER(1,0),         OG_USAGE_PIEFRAMEA
 usagevalue  NUMBER(6),           OG_USAGE_PIEFRAMEA
 plotorder   NUMBER(1,0),         OG_PLOTORDER_PIEFRAMEA
 categs      BOOLEAN,             OG_CATEGS_PIEFRAMEA
 datavals    BOOLEAN,             OG_DATAVALS_PIEFRAMEA
 pctvalues   BOOLEAN,             OG_PCTVALUES_PIEFRAMEA
 ticks       BOOLEAN,             OG_TICKS_PIEFRAMEA
 other       NUMBER(3),           OG_OTHER_PIEFRAMEA
 nooverlap   BOOLEAN,             OG_NOOVERLAP_PIEFRAMEA
 catnumfmt   VARCHAR2(255),       OG_CATNUMFMT_PIEFRAMEA
 catdatefmt  VARCHAR2(255),       OG_CATDATEFMT_AXSFRAMEA
 valuefmt    VARCHAR2(255),       OG_VALUEFMT_PIEFRAMEA
 pctfmt      VARCHAR2(255)        OG_PCTFMT_PIEFRAMEA
);
                                  OG_ALL_PIEFRAMEA
                                  OG_NONE_PIEFRAMEA

	Attribute	Description
SG	usage	Specifies the relationship between the individual pie slices and the complete chart.  The value of this attribute may be one of the following built-in constants:
		OG_TOTALVALUE_USAGE
		OG_PCT_USAGE
SG	usagevalue	Each pie slice is plotted as if its data value is a percentage of the total value specified here.  (Valid only is usage is set to OG_TOTALVALUE_USAGE.
SG	plotorder	Specifies the direction in which the data values are plotted.  The value of this attribute may be one of the following built-in constants:
		OG_CCW_PLOTORDER
		OG_CW_PLOTORDER
SG	categs	Specifies whether each pie slice is labeled with the name of the category it represents.
SG	datavals	Specifies whether each pie slice is labeled with its data value.
SG	pctvalues	Specifies whether each pie slice is labeled with the percentage of the complete chart it represents.
SG	ticks	Specifies whether the tick marks that connect each pie slice to its label are shown.
SG	other	Specifies that pie slices that individually represent percentages less than the number entered here are combined into a single pie slice with the label "Other".
SG	nooverlap	Specifies that the labels for the pie slices should not overlap each other.
SG	catnumfmt	Specifies the number format for the category labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.
SG	catdatefmt	Specifies the date format for the category labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.
SG	valuefmt	Specifies the number format for the data value labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.
SG	pctfmt	Specifies the number format for the percent value labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.


Table Frame Combined Attribute Record

TYPE og_tableframe_ca IS RECORD
(ca_frame  og_frame_attr,       /* generic frame */
 ca_table  og_tableframe_attr   /* table frame */
);


Table Frame Attribute Record

TYPE og_tableframe_attr IS RECORD   Mask Constants:
(mask     NUMBER(3,0),
 automin  BOOLEAN,                  OG_MIN_TABLEFRAMEA
 minrows  NUMBER(10,0),             OG_MIN_TABLEFRAMEA
 automax  BOOLEAN,                  OG_MAX_TABLEFRAMEA
 maxrows  NUMBER(10,0),             OG_MAX_TABLEFRAMEA
 cname    BOOLEAN,                  OG_CNAME_TABLEFRAMEA
 vgrid    BOOLEAN,                  OG_VGRID_TABLEFRAMEA
 hgrid    BOOLEAN,                  OG_HGRID_TABLEFRAMEA
 gridct   NUMBER(10,0)              OG_GRIDCT_TABLEFRAMEA
);
                                    OG_ALL_TABLEFRAMEA
                                    OG_NONE_TABLEFRAMEA

	Attribute	Description
SG	automin	Specifies whether the minimum number of rows that appear on the chart is set to Auto.
SG	minrows	Specifies the maximum number of rows that appear on the chart (if automin is FALSE).
SG	automax	Specifies whether the maximum number of rows that appear on the chart is set to Auto.
SG	maxrows	Specifies the maximum number of rows that appear on the chart (if automax is FALSE).
SG	colnames	Specifies whether the names of the columns appear as the first row in the chart.
SG	vgrid	Specifies whether vertical grid lines appear between the columns.
SG	hgrid	Specifies whether horizontal grid lines appear between the rows.
SG	gridct	Is the number of rows of data plotted before each horizontal grid line is drawn (if hgrid is set to TRUE).


Generic Attribute Record

The generic attribute record contains attributes that may be used with every object.

TYPE og_generic_attr IS RECORD    Mask Constants:
(mask       NUMBER(6,0),
 name       VARCHAR2(255),          OG_NAME_GENERICA
 parent     og_object,              OG_PARENT_GENERICA
 ibbox      og_rectangle,           OG_IBBOX_GENERICA
 obbox      og_rectangle,           OG_OBBOX_GENERICA
 objtype    NUMBER(2,0),            OG_OBJTYPE_GENERICA
 button     og_buttonproc,          OG_BUTTON_GENERICA
 events     NUMBER(2,0),            OG_EVENTS_GENERICA
 keycol     VARCHAR2(255,           OG_KEYCOL_GENERICA
 execquery  og_query,               OG_EXECQUERY_GENERICA
 setparam   VARCHAR2(255),          OG_SETPARAM_GENERICA
 fmttrig    VARCHAR2(255),          OG_FMTTRIG_GENERICA
 hide       BOOLEAN                 OG_HIDE_GENERICA
);
                                    OG_ALL_GENERICA
                                    OG_NONE_GENERICA

	Attribute	Description
CSG	name	Is the object's name.
CG	parent	Is the handle to the object's parent object.
G	ibbox	Is the object's inner bounding box.  This is the rectangle that constitutes the object's ideal shape (i.e., connects the object's four control points), regardless of edge thickness or other attribute settings.
G	obbox	Is the object's outer bounding box.  This is the smallest rectangle that completely surrounds the object.  This may differ from the inner bounding box if the object has a thick edge.  While the inner bounding box traces only the ideal shape of the object, the outer bounding box surrounds the entire object.
G	objtype	Is the object's type.  The value of this attribute may be one of the following built-in constants:
		OG_ARC_OBJTYPE   Means the object is an arc.
		OG_CHART_OBJTYPE   Means the object is a chart.
		OG_GROUP_OBJTYPE   Means the object is a group.
		OG_IMAGE_OBJTYPE   Means the object is an image.
		OG_LINE_OBJTYPE   Means the object is a line.
		OG_POLY_OBJTYPE   Means the object is a polygon or polyline.
		OG_RECT_OBJTYPE   Means the object is a rectangle.
		OG_RRECT_OBJTYPE   Means the object is a rounded rectangle.
		OG_SYMBOL_OBJTYPE   Means the object is a symbol.
		OG_TEXT_OBJTYPE   Means the object is a text object.
CSG	button	Is the handle to the button procedure to be associated with this object.  Note that the events attribute must be set properly in order to ensure that this procedure receives the desired mouse events.
CSG	events	Is the type of mouse events that the procedure specified by the button attribute should receive.  The value of this attribute may be one of the built-in constants listed below.  To enable the procedure to receive multiple event types, set this attribute to be the sum of the constants for the desired events.
		OG_NO_EVENTS   Means the procedure receives no mouse events.
		OG_MOUSE_DOWN   Means the procedure receives only mouse down events.
		OG_MOUSE_UP   Means the procedure receives only mouse up events.
		OG_MOUSE_MOVE_UP   Means the procedure receives only mouse move up events.
CSG	keycol	Is the column to set in a drill-down chart.  This attribute applies only to chart elements.
CSG	execquery	Specifies the query to execute when the object is selected.
CSG	setparam	Is the parameter whose value is set when the object is selected.
CSG	fmttrig	Is the format trigger.  This attribute applies only to chart elements.
SG	hide	Hides the specified Graphics Builder object.


Graphic Combined Attribute Record

The graphic combined attribute record consists of a generic attribute record and graphic attribute record:

TYPE og_graphic_ca IS RECORD
(graphic_caob  og_generic_attr,   /* generic */
 graphic_caoh  og_graphic_attr    /* graphic */
);


Graphic Attribute Record

The graphic attribute record contains attributes that may be used only with graphical objects:

TYPE og_graphic_attr IS RECORD     Mask Constants:
(mask        NUMBER(4,0),
 ewidth      NUMBER(10,0),         OG_EWIDTH_GRAPHICA
 rotang      NUMBER(5,2),          OG_ROTANG_GRAPHICA
 fecolor     VARCHAR2(255),        OG_FECOLOR_GRAPHICA
 becolor     VARCHAR2(255),        OG_BECOLOR_GRAPHICA
 edgepatt    VARCHAR2(255),        OG_EDGEPATT_GRAPHICA
 ffcolor     VARCHAR2(255),        OG_FFCOLOR_GRAPHICA
 bfcolor     VARCHAR2(255),        OG_BFCOLOR_GRAPHICA
 fillpatt    VARCHAR2(255),        OG_FILLPATT_GRAPHICA
 dashstyle   NUMBER(1,0),          OG_DASHSTYLE_GRAPHICA
 capstyle    NUMBER(2,0),          OG_CAPSTYLE_GRAPHICA
 joinstyle   NUMBER(2,0),          OG_JOINSTYLE_GRAPHICA
 transfer    NUMBER(1,0)           OG_TRANSFER_GRAPHICA
 bevelstyle  NUMBER(2,0)           OG_BEVELSTYLE_GRAPHICA
);
                                   OG_ALL_GRAPHICA
                                   OG_NONE_GRAPHICA

	Attribute	Description
CSG	ewidth	Is the width of the object's edge (in layout units).
CSG	rotang	Is the object's rotation angle.  The angle at which the object is initially created is considered to be 0, and this attribute is the number of degrees clockwise the object currently differs from that initial angle.  You can rotate an object to an absolute angle by setting this attribute, or use the OG_ROTATE procedure to rotate an object by a relative amount.  (Note that when you use OG_ROTATE to rotate an object, the rotang attribute will automatically be updated to reflect the new absolute angle.)
CSG	fecolor	Is the object's foreground edge color.  For more information about valid color palettes, see Default color palettes .
CSG	becolor	Is the object's background edge color.  For more information about valid color names, see Default color palettes .
CSG	edgepatt	Is the object's edge pattern.  For more information about valid pattern names, see Pattern palette .
CSG	ffcolor	Is the object's foreground fill color.  For more information about valid color names, see Default color palettes .
CSG	bfcolor	Is the object's background fill color.  For more information about valid color names, see Default color palettes .
CSG	fillpatt	Is the object's fill pattern.  For more information about valid pattern names, see Pattern palette.
CSG	dashstyle	Is the dash style of the object's edge.  The value of this attribute may be one of the following built-in constants:
		OG_SOLID_DSTYLE   Means the line is solid.
		OG_DOT_DSTYLE   Means the line is dotted.
		OG_LONG_DSTYLE   Means the line is a series of long dashes.
		OG_DASHDOT_DSTYLE   Means the line is a series of dashes followed by dots.
		OG_DOTDOT_DSTYLE   Means the line is a series of two consecutive dots.
		OG_SHORT_DSTYLE   Means the line is a series of short dashes.
		OG_DASHDOTDOT_DSTYLE   Means the line is a series of a dash followed by two dots.
CSG	capstyle	Is the cap style of the object's edge.  The value of this attribute may be one of the following built-in constants:
		OG_BUTT_CSTYLE   Means the cap style is butt.
		OG_PROJECTING_CSTYLE   Means the cap style is projecting.
		OG_ROUND_CSTYLE   Means the cap style is round.
CSG	joinstyle	Is the join style of the object's edge.  The value of this attribute may be one of the following built-in constants:
		OG_MITRE_JSTYLE   Means the join style is metre.
		OG_BEVEL_JSTYLE   Means the join style is bevel.
		OG_ROUND_JSTYLE   Means the join style is round.
CSG	transfer	Is the object's transfer mode.  The value of this attribute may be one of the following built-in constants:
		OG_COPY_TRANSFER   Means the transfer mode is copy.
		OG_REVCOPY_TRANSFER   Means the transfer mode is reverse copy.
		OG_OR_TRANSFER   Means the transfer mode is or.
		OG_REVOR_TRANSFER   Means the transfer mode is reverse or.
		OG_CLEAR_TRANSFER   Means the transfer mode is clear.
		OG_REVCLEAR_TRANSFER   Means the transfer mode is reverse clear.
		OG_INVERT_TRANSFER   Means the transfer mode is invert.
		OG_BACKINVERT_TRANSFER   Means the transfer mode is background invert.
CSG	bevelstyle	Is the object's bevel style.  The value of this attribute may be one of the following built-in constants:
		OG_INSET_BSTYLE   Means the bevel is inset.
		OG_LOWERED_BSTYLE   Means the bevel is lowered.
		OG_OUTSET_BSTYLE   Means the bevel is outset.
		OG_PLAIN_BSTYLE   Means the object has no bevel.
		OG_RAISED_BSTYLE   Means the bevel is raised.


Group Combined Attribute Record

The group combined attribute record consists of a generic attribute record and group attribute record:

TYPE og_group_ca IS RECORD
(group_caob  og_generic_attr,   /* generic */
 group_caog  og_group_attr      /* group */
);


Group Attribute Record

The group attribute record contains attributes that may be used only with group objects:

TYPE og_group_attr IS RECORD        Mask Constants:
(mask        NUMBER(1,0),
 childcount  NUMBER(10,0),          OG_CHILDCOUNT_GROUPA
 clipflag    BOOLEAN                OG_CLIPFLAG_GROUPA
);
                                    OG_ALL_GROUPA
                                    OG_NONE_GROUPA

	Attribute	Description
G	childcount	Is the number of children that belong to the group object.  If another group object is a child of the group being checked, that object will be counted only as one object.
CSG	clipflag	Specifies whether the first object in the group is a rectangle object that should be used as a clipping rectangle.  If TRUE, the only members of the group that appear on the layout are those objects-or portions of those objects-that appear within the bounds of the clipping rectangle.  The rectangle object itself also appears.  The value of this attribute may be one of the following:
		TRUE   Means the first object in the group is treated as a clipping rectangle.
		FALSE   Means the first object in the group is not treated as a clipping rectangle.


Image Combined Attribute Record

The image combined attribute record consists of a generic attribute record and image attribute record:

TYPE og_image_ca IS RECORD
(image_caob  og_generic_attr,   /* generic */
 image_caoi  og_image_attr      /* image */
);


Image Attribute Record

The image attribute record contains attributes that may be used only with image objects:

TYPE og_image_attr IS RECORD          Mask Constants:
(mask        NUMBER(3,0),
 cliprect    og_rectangle,            OG_CLIPRECT_IMAGEA
 upperleft   og_point,                OG_UPPERLEFT_IMAGEA
 width       NUMBER(10,0),            OG_SIZE_IMAGEA
 height      NUMBER(10,0),            OG_SIZE_IMAGEA
 query       og_query,                OG_DATA_IMAGEA
 which_data  NUMBER(1,0),             OG_DATA_IMAGEA
 colname     VARCHAR2(255),           OG_DATA_IMAGEA
 quality     NUMBER(5,0),             OG_QUALITY_IMAGEA
 dither      BOOLEAN                  OG_DITHER_IMAGEA
);
                                      OG_ALL_IMAGEA
                                      OG_NONE_IMAGEA

	Attribute	Description
SG	cliprect	Is the x- and y-coordinates, height, and width of the image's clipping rectangle (in layout units).  Only the portion of the image that falls within this clipping rectangle will be displayed.  If this attribute is not specified, the clipping rectangle will equal the full dimensions of the image.
SG	upperleft	Is the x- and y-coordinates of the image's upper-left corner (in layout units).
SG	width	Is the image's width (in layout units).  If you set this attribute to some value other than the image's default width, the image will be scaled to fit within the new width.
SG	height	Is the image's height (in layout units).  If you set this attribute to some value other than the image's default height, the image will be scaled to fit within the new height.
C	query	Is the handle to the query that retrieves the image from a table in a database.  Note that this table must be a user table, and not one the private tables used by Graphics Builder when you save or export a display, drawing, chart template, color palette, image, or sound to the database.  Only Oracle Format images can be stored in the database.
C	which_data	Specifies whether the image to be created is contained in a query's new or old data set.  Graphics Builder provides two built-in numeric constants that may be used as values for this attribute:
		OG_NEWDATA   Means the image is contained in the query's new data set.
		OG_OLDDATA   Means the image is contained in the query's old data set.
C	colname	Is the name of the query column that contains the image data.  The image that is created is the one contained in the query cell at the intersection of the column specified by this attribute and the row pointed to by the query's cursor.
CSG	quality	Specifies with what  quality the image is drawn.  Higher quality images look better, but require more processing time to manipulate (e.g., draw, move, scale, etc.).  The value of this attribute may be one of the following built-in constants:
		OG_HIGH_IQUALITY   Means the quality is high.
		OG_MED_IQUALITY   Means the quality is medium.
		OG_LOW_IQUALITY   Means the quality is low.
CSG	dither	Specifies whether Graphics Builder dithers the image when displaying it.  The value of this attribute may be one of the following:
		TRUE   Means dither the image.
		FALSE   Means do not dither the image.


Line Combined Attribute Record

The line combined attribute record consists of a generic attribute record, graphic attribute record, and line attribute record:

TYPE og_line_ca IS RECORD
(line_caob  og_generic_attr,   /* generic */
 line_caoh  og_graphic_attr,   /* graphic */
 line_caol  og_line_attr       /* line */
);


Line Attribute Record

The line attribute record contains attributes that may be used only with line objects:

TYPE og_line_attr IS RECORD           Mask Constants:
(mask        NUMBER(1,0),
 startpt     og_point,                OG_STARTPT_LINEA
 endpt       og_point,                OG_ENDPT_LINEA
 arrowstyle  NUMBER(1,0)              OG_ARROWSTYLE_LINEA
);
                                      OG_ALL_LINEA
                                      OG_NONE_LINEA

	Attribute	Description
CSG	startpt	Is the x- and y-coordinates of the line's starting point (in layout units).
CSG	endpt	Is the x- and y-coordinates of the line's end point (in layout units).
CSG	arrowstyle	Is the line's arrow style.  The value of this attribute may be one of the following built-in constants:
		OG_NOARROW_ASTYLE   Means the line has no arrow.
		OG_START_ASTYLE   Means the line has an arrow at its starting point.
		OG_END_ASTYLE   Means the line has an arrow at its end point.
		OG_BOTH_ASTYLE   Means the line has an arrow at both ends.
		OG_MIDTOSTART_ASTYLE   Means the line has an arrow at its middle, pointing toward its starting point.
		OG_MIDTOEND_ASTYLE   Means the line has an arrow at its middle, pointing toward its end point.


Polygon Combined Attribute Record

The polygon combined attribute record consists of a generic attribute record, graphic attribute record, and polygon attribute record:

TYPE og_poly_ca IS RECORD
(poly_caob  og_generic_attr,   /* generic */
 poly_caoh  og_graphic_attr,   /* graphic */
 poly_caop  og_poly_attr       /* polygon */
);


Polygon Attribute Record

The polygon attribute record contains attributes that may be used only with polygon objects:

TYPE og_poly_attr IS RECORD               Mask Constants:
(mask     NUMBER(1,0),
 pointct  NUMBER(10,0),                   OG_POINTCT_POLYA
 closed   BOOLEAN                         OG_CLOSED_POLYA
);
                                          OG_ALL_POLYA
                                          OG_NONE_POLYA

	Attribute	Description
G	pointct	Is the number of points that compose the polygon object.
CSG	closed	Is the closure of the polygon.  The value of this attribute may be one of the following:
		TRUE   Means the polygon is closed.
		FALSE   Means the polygon is open.


Printer Attribute Record

TYPE og_printer_attr IS RECORD      Mask Constants:
(mask       NUMBER(3,0),
 name       VARCHAR2(255),          OG_NAME_PRINTERA
 landscape  BOOLEAN,                OG_LANDSCAPE_PRINTERA
 startpage  NUMBER(5,0),            OG_STARTPAGE_PRINTERA
 endpage    NUMBER(5,0),            OG_ENDPAGE_PRINTERA
 width      NUMBER(10,0),           OG_WIDTH_PRINTERA
 height     NUMBER(10,0),           OG_HEIGHT_PRINTERA
 copies     NUMBER(5,0),            OG_COPIES_PRINTERA
 printfile  VARCHAR2(255)           OG_PRINTFILE_PRINTERA
);
                                    OG_ALL_PRINTERA
                                    OG_NONE_PRINTERA

	Attribute	Description
SG	name	Is the name of the current printer.
SG	landscape	Specifies whether the display is printed in landscape or portrait mode.
SG	startpage	Is the first page to print.
SG	endpage	Is the last page to print.
S	width	Is the page width.
S	height	Is the page height.
SG	copies	Is the number of copies to print.
SG	printfile	Is the name of the PostScript file to print to.  If this property is NULL, the output is sent to the printer.


Query Attribute Record

The query attribute record contains attributes that may be used only with queries:

TYPE og_query_attr IS RECORD       Mask Constants:
(mask         NUMBER(4,0),
 name         VARCHAR2(255),       OG_NAME_QUERYA
 dateformat   VARCHAR2(255),       OG_DATEFORMAT_QUERYA
 querysource  VARCHAR2(2000),      OG_QUERYSOURCE_QUERYA
 querytype    NUMBER(1,0),         OG_QUERYTYPE_QUERYA
 cachetype    NUMBER(1,0),         OG_CACHETYPE_QUERYA
 maxflag      BOOLEAN,             OG_MAXFLAG_QUERYA
 maxrows      NUMBER(10,0),        OG_MAXROWS_QUERYA
 execopen     BOOLEAN,             OG_EXECOPEN_QUERYA
 exectimer    VARCHAR2(255),       OG_EXECTIMER_QUERYA
 execalert    VARCHAR2(255),       OG_EXECALERT_QUERYA
 customproc   VARCHAR2(255),       OG_CUSTOMPROC_QUERYA
 postproc     VARCHAR2(255)        OG_POSTPROC_QUERYA
);
                                   OG_ALL_QUERYA
                                   OG_NONE_QUERYA

	Attribute	Description
CSG	name	Is the name of the query.
CSG	dateformat	Is the date format mask for the query.
CSG	querysource	Is the source of the query's data.  If the data comes from a database, this attribute should contain the text of the the query's SQL SELECT statement.  If the data is stored in the filesystem, this attribute should contain the path and name of the data file.
CSG	querytype	Is the type of query.  The value of this attribute may be one of the following built-in constants:
		OG_CUSTOM_QTYPE   Means the query is a Custom query.
		OG_EXSQL_QTYPE   Means  the query retrieves its data from a text file that contains a SQL SELECT statement.
		OG_PRN_QTYPE   Means the query is based on a PRN file.
		OG_SQL_QTYPE   Means the query is a SQL SE.LECT statement.
		OG_SYLK_QTYPE   Means the query is based on a SYLK file.
		OG_WKS_QTYPE   Means the query is based on a WKS file.
CSG	cachetype	Determines how the newly retrieved data from a query execution is treated.  The value of this attribute may be one of the following built-in constants:
		OG_APPEND_CACHETYPE   Means all of the existing rows of data are retained, and the new rows of data are added to the bottom of the existing data set.
		OG_COPY_CACHETYPE   Means all of the data from the previous execution is copied to a special buffer, and the newly retrieved data replaces it.
		OG_NONE_CACHETYPE   Means all of the data from the previous execution is discarded, and the newly retrieved data replaces it.
CSG	maxflag	Specifies whether a limit is placed on the number of rows contained in the data set.
CSG	maxrows	Specifies the maximum number of rows of data that are retained in the query's data set.
CSG	execopen	Specifies whether the query is automatically executed when the display is opened at runtime.
CSG	exectimer	Is the name of the timer on which the query executes.
CSG	execalert	Reserved for future use.
CSG	customproc	Is the PL/SQL procedure that is invoked when a Custom query is executed.
CSG	postproc	Is the PL/SQL procedure that is invoked after the query is executed.


Rectangle Combined Attribute Record

The rectangle combined attribute record consists of a generic attribute record, graphic attribute record, and rectangle attribute record:

TYPE og_rect_ca IS RECORD
(rect_caob  og_generic_attr,   /* generic */
 rect_caoh  og_graphic_attr,   /* graphic */
 rect_caor  og_rect_attr       /* rectangle */
);


Rectangle Attribute Record

The rectangle attribute record contains attributes that may be used only with rectangle objects:

TYPE og_rect_attr IS RECORD              Mask Constants:
(mask      NUMBER(1,0),
 baserect  og_rectangle                  OG_BASERECT_RECTA
);
                                         OG_ALL_RECTA
                                         OG_NONE_RECTA

	Attribute	Description
CSG	baserect	Is the x- and y-coordinates of the upper-left corner, and the height and width of the rectangle used as the basis for the rectangle object (in layout units).


Reference Line Attribute Record

TYPE og_refline_attr IS RECORD           Mask Constants:
(mask       NUMBER(2,0),
 numvalue   NUMBER(6),                   OG_VALUE_REFLINEA
 datevalue  DATE,                        OG_VALUE_REFLINEA
 label      VARCHAR2(255),               OG_LABEL_REFLINEA
 axis       NUMBER(1,0)                  OG_AXIS_REFLINEA
);
                                         OG_ALL_REFLINEA
                                         OG_NONE_REFLINEA

	Attribute	Description
SG	numvalue	Is the number value at which the reference line appears.
SG	datevalue	Is the date value at which the reference line appears.
SG	label	Is the text label that identifies the reference line in the legend.
SG	axis	Specifies which axis the reference value is compared to determine its position.


Rounded Rectangle Combined Attribute Record

The rounded rectangle combined attribute record consists of a generic attribute record, graphic attribute record, and rounded rectangle attribute record:

TYPE og_rrect_ca IS RECORD
(rrect_caob  og_generic_attr,   /* generic */
 rrect_caoh  og_graphic_attr,   /* graphic */
 rrect_caor  og_rrect_attr      /* rounded rectangle */
);


Rounded Rectangle Attribute Record

The rounded rectangle attribute record contains attributes that may be used only with rounded rectangle objects:

TYPE og_rrect_attr IS RECORD            Mask Constants:
(mask      NUMBER(1,0),
 baserect  og_rectangle,                OG_BASERECT_RRECTA
 corner    og_point                     OG_CORNER_RRECTA
);
                                        OG_ALL_RRECTA
                                        OG_NONE_RRECTA

	Attribute	Description
CSG	baserect	Is the x- and y-coordinates of the upper-left corner, and the height and width of the rectangle used as the basis for the rectangle object (in layout units).
CSG	corner	Is the x- and y-radii (in layout units) of the ellipse that would result if the arcs that form the rounded corners were continued to follow a full 360 degree path.


Sound Attribute Record

The sound attibute record contains attributes that may be used only with sounds.

TYPE og_sound_attr IS RECORD              Mask Constants:
(mask        NUMBER(1,0),
 query       og_query,                    OG_DATA_SOUNDA
 which_data  NUMBER(1,0),                 OG_DATA_SOUNDA
 colname     VARCHAR2(255),               OG_DATA_SOUNDA
 name        VARCHAR2(255),               OG_NAME_SOUNDA
);
                                          OG_ALL_SOUNDA
                                          OG_NONE_SOUNDA

	Attribute	Description
C	query	Is the handle to the query that retrieves the sound from a table in a database.  Note that this table must be a user table, and not one the private tables used by Graphics Builder when you save or export a display, drawing, chart template, color palette, image, or sound to the database.
C	which_data	Specifies whether the sound to be created is contained in a query's new or old data set.  Graphics Builder provides two built-in numeric constants that may be used as values for this attribute:
		OG_NEWDATA   Means the sound is contained in the query's new data set.
		OG_OLDDATA   Means the sound is contained in the query's old data set.
C	colname	Is the name of the query column that contains the sound data.  The sound that is created is the one contained in the query cell at the intersection of the column specified by this attribute and the row pointed to by the query's cursor.
CSG	name	Is the name of the sound.


Symbol Combined Attribute Record

The symbol combined attribute record consists of a generic attribute record, graphic attribute record, and symbol attribute record:

TYPE og_symbol_ca IS RECORD
(symbol_caob  og_generic_attr,   /* generic */
 symbol_caoh  og_graphic_attr,   /* graphic */
 symbol_caos  og_symbol_attr     /* symbol */
);


Symbol Attribute Record

The arc attribute record contains attributes that may be used only with arc objects:

TYPE og_symbol_attr IS RECORD          Mask Constants:
(mask     NUMBER(1,0),
 center   og_point,                    OG_CENTER_SYMBOLA
 indx     NUMBER(3,0),                 OG_INDX_SYMBOLA
 symsize  NUMBER(1,0)                  OG_SYMSIZE_SYMBOLA
);
                                       OG_ALL_SYMBOLA
                                       OG_NONE_SYMBOLA

	Attribute	Description
CSG	center	Is the x- and y-coordinates of the symbol's center (in layout units).
CSG	indx	Is the index (or number) of the symbol's position as it appears in the symbol palette in the Designer.
CSG	symsize	Is the symbol's size.  The value of this attribute may be one of the following built-in constants:
		OG_LARGE_SYMSIZE   Means the symbol is large.
		OG_MEDIUM_SYMSIZE   Means the symbol is medium.
		OG_SMALL_SYMSIZE   Means the symbol is small.


Text Attributes Overview

The text attribute record does not contain the text that will appear in the text object.  Instead, you must first create a text object, and then use the OG_INSERT_CMPTEXT procedure to insert a "compound text element" into the text object.  You may insert multiple compound text elements into a text object, and each one will represent one line of text in the object.  In addition, each compound text element may contain one or more "simple text elements."  A simple text element contains an actual text string, and must be inserted into a compound text element with the OG_INSERT_SMPTEXT procedure.

The attribute records for compound and simple text are listed below.


Text Combined Attribute Record

The text combined attribute record consists of a generic attribute record, graphic attribute record, and text attribute record:

TYPE og_text_ca IS RECORD
(text_caob  og_generic_attr,   /* generic */
 text_caoh  og_graphic_attr,   /* graphic */
 text_caot  og_text_attr       /* text */
);


Text Attribute Record

The text attribute record contains attributes that may be used only with text objects:

TYPE og_text_attr IS RECORD            Mask Constants:
(mask       NUMBER(6,0),
 origin     og_point,                  OG_ORIGIN_TEXTA
 ctcount    NUMBER(10,0),              OG_CTCOUNT_TEXTA
 gfont      og_font_attr,              OG_GFONT_TEXTA
 gcolor     VARCHAR2(255),             OG_GCOLOR_TEXTA
 spacing    NUMBER(1,0),               OG_SPACING_TEXTA
 custom     NUMBER(10,0),              OG_SPACING_TEXTA
 horigin    NUMBER(1,0),               OG_HORIGIN_TEXTA
 vorigin    NUMBER(1,0),               OG_VORIGIN_TEXTA
 halign     NUMBER(2,0),               OG_HALIGN_TEXTA
 valign     NUMBER(3,0),               OG_VALIGN_TEXTA
 fixed      BOOLEAN,                   OG_FIXED_TEXTA
 wrap       BOOLEAN,                   OG_WRAP_TEXTA
 bbscale    BOOLEAN,                   OG_BBSCALE_TEXTA
 fontscale  BOOLEAN,                   OG_FONTSCALE_TEXTA
 invisible  BOOLEAN,                   OG_INVISIBLE_TEXTA
 width      NUMBER(10,0),              OG_FIXEDWH_TEXTA
 height     NUMBER(10,0)               OG_FIXEDWH_TEXTA
);
                                       OG_ALL_TEXTA
                                       OG_NONE_TEXTA

	Attribute	Description
CSG	origin	Is the x- and y-coordinates of the text object's upper-left corner (in layout units).
G	ctcount	Is the number of compound text elements that compose the text object.
S	gfont	Is the text object's global font.  When this attribute is set, the font attribute for every simple text element in the text object will be set to this font.  Note that setting this attribute will affect existing simple text elements only; any simple text elements added later will appear in the font specified in their simple text attribute records.
S	gcolor	Is the text object's global color.  When this attribute is set, the color attribute for every simple text element in the text object will be set to this color.  Note that setting this attribute will affect existing simple text elements only; any simple text elements added later will appear in the color specified in their simple text attribute records.
CSG	spacing	Is the line spacing for the text object.  The value of this attribute may be one of the built-in constants listed below.  If custom spacing is set, the value of the custom attribute should specify the exact spacing amount.
		OG_SINGLE_SPACE   Means the text use single line spacing.
		OG_ONEHALF_SPACE   Means the text used 1-1/2 line spacing.
		OG_DOUBLE_SPACE   Means the text uses double line spacing.
		OG_CUSTOM_SPACE   Means the text uses custom line spacing.   The actual spacing used is defined in the custom attribute.
CSG	custom	Is the custom spacing for the text object (in layout units).  This attribute is used to specify spacing only if the gspacing attribute is set to custom spacing.
CSG	horigin	Is the horizontal position of the text object relative to its origin point.  The value of this attribute may be one of the following built-in constants:
		OG_LEFT_HORIGIN   Means the origin point lies along the left edge of the bounding box.
		OG_CENTER_HORIGIN   Means the origin point lies equally between the left and right edges of the bounding box.
		OG_RIGHT_HORIGIN   Means the origin point lies along the right edge of the bounding box.
CSG	vorigin	Is the vertical position of the text object relative to its origin point.  The value of this attribute may be one of the following built-in constants:
		OG_TOP_VORIGIN   Means the origin point lies along the top edge of the bounding box.
		OG_MIDDLE_VORIGIN   Means the origin point lies equally between the top and bottom edges of the bounding box.
		OG_BOTTOM_VORIGIN   Means the origin point lies along the bottom edge of the bounding box.
CSG	halign	Is the horizontal alignment of the text object.  The value of this attribute may be one of the following built-in constants:
		OG_LEFT_HALIGN   Means the text is left-aligned.
		OG_CENTER_HALIGN   Means the text is center-aligned.
		OG_RIGHT_HALIGN   Means the text is right-aligned.
CSG	valign	Is the vertical alignment of the text object.  The value of this attribute may be one of the following built-in constants:
		OG_TOP_VALIGN   Means the text is top-aligned.
		OG_MIDDLE_VALIGN   Means the text is middle-aligned.
		OG_BOTTOM_VALIGN   Means the text is bottom-aligned.
CSG	wrap	Specifies whether the text should "wrap" to fit into the text object's bounding box.  As described below, a compound text element represents a line of text, and is made up of simple text elements.  The value of this attribute may be one of the following:
		TRUE   Means wrap the text.
		FALSE   Means do not wrap the text.
CSG	bbscale	Specifies whether the text object's bounding box should be scaled when the text object is scaled.  The value of this attribute may be one of the following:
		TRUE   Means scale the bounding box.
		FALSE   Means do not scale the bounding box.
CSG	fontscale	Specifies whether the point size of the font should be scaled when the text object is scaled.  The value of this attribute may be one of the following:
		TRUE   Means scale the point size.
		FALSE   Means do not scale the point size.
CSG	fixed	Specifies whether the text object's bounding box should remain a fixed size.  If this attribute is TRUE, the values of the width and height attributes should specify the size of the bounding box.  The value of this attribute may be one of the following:
		TRUE   Means the bounding box is fixed.   The dimensions of the bounding box are defined in the width and height attributes.
		FALSE   Means the bounding box is not fixed.
CSG	width	Is the width of the bounding box (in layout units).  Whenever the bounding box changes, this attribute will automatically be updated to reflect the new width.  This attribute is used to set the width only if the fixed attribute is TRUE.
CSG	height	Is the height of the bounding box (in layout units).  Whenever the bounding box changes, this attribute will automatically be updated to reflect the new height.  This attribute is used to set the height only if the fixed attribute is TRUE.
CSG	invisible	Specifies whether the text in the text object should be invisible.  This is useful for text fields in which a user enters a password, if you don't want the password to be seen.  The value of this attribute may be one of the following:
		TRUE   Means the text is invisible.
		FALSE   Means the text is visible.


Font Attribute Record

The font attribute record is used to specify the properties of a font, such as typeface and point size.

TYPE og_font_attr IS RECORD           Mask Constants:
(mask         NUMBER(3,0),
 typeface     VARCHAR2(255),          OG_TYPEFACE_FONTA
 ptsize       NUMBER(10,2),           OG_PTSIZE_FONTA
 style        NUMBER(5,0),            OG_STYLE_FONTA
 weight       NUMBER(5,0),            OG_WEIGHT_FONTA
 width        NUMBER(5,0),            OG_WIDTH_FONTA
 kerning      BOOLEAN,                OG_KERNING_FONTA
 nearest      BOOLEAN,                OG_NEAREST_FONTA
 synthesize   BOOLEAN,                OG_SYNTHESIZE_FONTA
 charset      NUMBER(5,0)             OG_CHARSET_FONTA
);
                                      OG_ALL_FONTA
                                      OG_NONE_FONTA

	Attribute	Description
CG	typeface	Is the font's style.  Values for this field specify styles such as italic, shadow, and underline, and are system-specific.  For more information, consult your system administrator or your system documentation.
CG	ptsize	Is the font's point size.  Values for this field are system-specific.  For more information, consult your system administrator or your system documentation.
CG	style	Is the font's style.  Not all styles are available on all systems.  For more information, consult your system administrator or your system documentation.  The value of this field may be one of the following built-in constants:
		OG_BLINK_FONTSTYLE   Means the style is blinking.
		OG_INVERTED_FONTSTYLE   Means the style is inverted.
		OG_ITALIC_FONTSTYLE   Means the style is italic.
		OG_OBLIQUE_FONTSTYLE   Means the style is oblique.
		OG_OUTLINE_FONTSTYLE   Means the style is outline.
		OG_OVERSTRIKE_FONTSTYLE   Means the style is overstrike.
		OG_PLAIN_FONTSTYLE   Means the style is plain.
		OG_SHADOW_FONTSTYLE   Means the style is shadow.
		OG_UNDERLINE_FONTSTYLE   Means the style is underline.
		OG_UNKNOWN_FONTSTYLE   Means the style is unknown.  You cannot set a style to this value; however, if you get a font and Graphics Builder cannot determine its style, this value is returned.
CG	weight	Is the font's weight.  Not all weights are available on all systems.  For more information, consult your system administrator or your system documentation.  The value of this field may be one of the following built-in constants:
		OG_BOLD_FONTWEIGHT   Means the weight is bold.
		OG_DEMIBOLD_FONTWEIGHT   Means the weight is demibold.
		OG_DEMILIGHT_FONTWEIGHT   Means the weight is demilight.
		OG_EXTRABOLD_FONTWEIGHT   Means the weight is extra bold.
		OG_EXTRALIGHT_FONTWEIGHT   Means the weight is extra light.
		OG_LIGHT_FONTWEIGHT   Means the weight is light.
		OG_MEDIUM_FONTWEIGHT   Means the weight is medium.
		OG_ULTRABOLD_FONTWEIGHT   Means the weight is ultrabold.
		OG_ULTRALIGHT_FONTWEIGHT   Means the weight is ultralight.
		OG_UNKNOWN_FONTWEIGHT   Means the weight is unknown.  You cannot set a weight to this value; however, if you get a font and Graphics Builder cannot determine its weight, this value is returned.
CG	width	Is the font's width.  Not all widths are available on all systems.  For more information, consult your system administrator or your system documentation.  The value of this field may be one of the following built-in constants:
		OG_DENSE_FONTWIDTH   Means the width is dense.
		OG_EXPAND_FONTWIDTH   Means the width is expanded.
		OG_EXTRADENSE_FONTWIDTH   Means the width is extra dense.
		OG_EXTRAEXPAND_FONTWIDTH   Means the width is extra expanded.
		OG_NORMAL_FONTWIDTH   Means the width is normal.
		OG_SEMIDENSE_FONTWIDTH   Means the width is semidense.
		OG_SEMIEXPAND_FONTWIDTH   Means the width is semiexpanded.
		OG_ULTRADENSE_FONTWIDTH   Means the width is ultradense.
		OG_ULTRAEXPAND_FONTWIDTH   Means the width is ultraexpanded.
		OG_UNKNOWN_FONTWIDTH   Means the width is unknown.  You cannot set a weight to this value; however, if you get a font and Graphics Builder cannot determine its width, this value is returned.
CG	kerning	Specifies whether the font should be kerned.  Kerning is the adjustment of the space between adjacent letters to improve the readability of the text.  The value of this field may be one of the following:
		TRUE   Means kern the font.
		FALSE   Means do not kern the font.
C	nearest	Specifies whether Graphics Builder should substitute the nearest matching font if the exact font specified cannot be found.  The precedence for finding the nearest font is typeface, point size, style, weight, and width (meaning that Graphics Builder first tries to find the specified typeface, then size, etc.).  The value of this attribute may be one of the following:
		TRUE   Means substitute the nearest font.
		FALSE   Means do not substitute the nearest font.
C	synthesize	Specifies whether Graphics Builder should try to synthesize the desired font (if the specified font cannot be found) by transforming the nearest-matching font.  The value of this field may be one of the following:
		TRUE   Means synthesize the font.
		FALSE   Means do not synthesize the font.
CG	charset	Is the font's character set.  Values for this field specify character sets such as U.S. ASCII, Kanji, and Arabic.  For a list of valid values for this field, see the Graphics Builder documentation for your operating system.
		OG_US7ASCII_CHARSET
		OG_WE8DEC_CHARSET
		OG_WE8HP_CHARSET
		OG_US8PC437_CHARSET
		OG_WE8EBCDIC37_CHARSET
		OG_WE8EBCDIC500_CHARSET
		OG_WE8PC850_CHARSET
		OG_D7DEC_CHARSET
		OG_F7DEC_CHARSET
		OG_S7DEC_CHARSET
		OG_E7DEC_CHARSET
		OG_SF7ASCII_CHARSET
		OG_NDK7DEC_CHARSET
		OG_I7DEC_CHARSET
		OG_NL7DEC_CHARSET
		OG_CH7DEC_CHARSET
		OG_SF7DEC_CHARSET
		OG_WE8ISO8859P1_CHARSET
		OG_EE8ISO8859P2_CHARSET
		OG_SE8ISO8859P3_CHARSET
		OG_NEE8ISO8859P4_CHARSET
		OG_CL8ISO8859P5_CHARSET
		OG_AR8ISO8859P6_CHARSET
		OG_EL8ISO8859P7_CHARSET
		OG_IW8ISO8859P8_CHARSET
		OG_WE8ISO8859P9_CHARSET
		OG_AR8ASMO708PLUS_CHARSET
		OG_AR7ASMO449PLUS_CHARSET
		OG_WE8MACROMAN8_CHARSET
		OG_JVMS_CHARSET
		OG_JEUC_CHARSET
		OG_JDEC_CHARSET
		OG_SJIS_CHARSET
		OG_JDBCS_CHARSET
		OG_JHP_CHARSET
		OG_KSC5601_CHARSET
		OG_KIBM5540_CHARSET
		OG_KDBCS_CHARSET
		OG_CGB231380_CHARSET
		OG_CDBCS_CHARSET
		OG_BIG5_CHARSET
		OG_CNS1164386_CHARSET


Compound Text Element Attribute Record

The compound text element attribute record contains attributes that may be used only with compound text elements:

TYPE og_cmptext_attr IS RECORD	   Mask Constants:
(mask     NUMBER(1,0),
 stcount  NUMBER(10,0)               OG_STCOUNT_CMPTEXTA
);
                                     OG_ALL_CMPTEXTA
                                     OG_NONE_CMPTEXTA

	Attribute	Description
G	stcount	Is the number of simple text elements that compose the compound text element.


Simple Text Element Attribute Record

The simple text element attribute record contains attributes that may be used only with simple text elements:

TYPE og_smptext_attr IS RECORD    Mask Constants:
(mask   NUMBER(1,0),
 str    VARCHAR2(2000)            OG_STR_SMPTEXTA
 font   og_font_attr,             OG_FONT_SMPTEXTA
 color  VARCHAR2(255)             OG_COLOR_SMPTEXTA
);
                                  OG_ALL_SMPTEXTA
                                  OG_NONE_SMPTEXTA

	Attribute	Description
CSG	str	Is the character string containing the actual text for the simple text element.
CSG	font	Is the font in which the character string's text should be displayed.  The only font attributes that will be used are those specified by the value of the mask attribute(s) in the font attribute record.  Fields in the attribute record for which the mask is not set will be unaffected.
CSG	color	Is the color in which the character string's text should be displayed.  Note that this is the color for the text itself.  To set the text object's edge or fill colors, change the text object's graphic attributes.
Example

This procedure creates a text object named "Message" at origin point (1", 1"), and contains the following two lines of text in a 12-point Times font.

This is line 1.

And now line 2.

Remember that each compound text element represents exactly one line of text in the text object.

PROCEDURE make_text IS
   text_obj   og_object;
   text_rec   og_text_ca;
   smp_rec    og_smptext_attr;
   font_rec   og_font_attr;
BEGIN
/* Set text object's name and origin attributes */
   text_rec.text_caob.name:='Message';
   text_rec.text_caot.origin.x:=OG_INCH;
   text_rec.text_caot.origin.y:=OG_INCH;
   text_rec.text_caob.mask:=OG_NAME_GENERICA;
   text_rec.text_caoh.mask:=OG_NONE_GRAPHICA;
   text_rec.text_caot.mask:=OG_ORIGIN_TEXTA;
/* Make the text object */
   text_obj:=og_make(text_rec);
/* Insert new compound text element into the text object at
      index 0 */
   og_insert_cmptext(text_obj, 0);
/* Set font record's typeface and point size attributes */
   font_rec.typeface:='times';
   font_rec.ptsize:=12;
   font_rec.mask:=OG_TYPEFACE_FONTA+
                  OG_PTSIZE_FONTA;
/* Set simple text record for text string and font */
   smp_rec.str:='This is line 1.';
   smp_rec.font:=font_rec;
   smp_rec.mask:=OG_STR_SMPTEXTA+
                 OG_FONT_SMPTEXTA;
/* Insert a new simple text element at index 0 in text
      object's compound text element at index 0, using
      defined simple text record */
   og_insert_smptext(text_obj, smp_rec, 0, 0);
/* Insert new compound text element into the text object at
      index 1 */
   og_insert_cmptext(text_obj, 1);
/* Change the simple text record's text string */
   smp_rec.str:='And now';
/* Insert a new simple text element at index 0 in text
      object's compound text element at index 1, using
      defined simple text record */
   og_insert_smptext(text_obj, smp_rec, 1, 0);
/* Change the simple text record's text string */
   smp_rec.str:=' line 2.';
/* Insert a new simple text element at index 1 in text
      object's compound text element at index 1, using
      defined simple text record */
   og_insert_smptext(text_obj, smp_rec, 1, 1);
END;

Example

This function takes a handle to a text field object as an argument, and returns the text contained in that field.  Note that since only the compound text element is accessed, only the text field's first line of text is retrieved.

FUNCTION get_text(text_obj IN og_object) RETURN VARCHAR2 IS
   smp_rec   og_smptext_attr;
BEGIN
   /* Set the simple text record's mask, indicating that the text string is the only attribute to get */
   smp_rec.mask:=OG_STR_SMPTEXTA;
   /* Get the 0th simple text element in the text object's
      0th compound text element, and store the results in
      the simple text record */
   og_get_smptext(text_obj, 0, 0, smp_rec);
   /* Return the text string attribute of the simple text
      record */
   RETURN(smp_rec.str);
END;


Timer Attributes

The timer attribute record contains attributes that may be used only with timers:

TYPE og_timer_attr IS RECORD          Mask Constants:
(mask       NUMBER(2,0),
 name       VARCHAR2(255),            OG_NAME_TIMERA
 interval   NUMBER(10,3),             OG_INTERVAL_TIMERA
 timerproc  VARCHAR2(255),            OG_TIMERPROC_TIMERA
 active     BOOLEAN                   OG_ACTIVE_TIMERA
);
                                      OG_ALL_TIMERA
                                      OG_NONE_TIMERA

	Attribute	Description
CSG	name	Is the name of the timer.
CSG	interval	Is the number of seconds that will pass between each execution of the timer procedure.
CSG	timerproc	Is the name of the procedure that will be executed when the timer is fired.


Window Attribute Record

The position and dimensions of windows are expressed in "screen resolution units," more commonly known as pixels.  Both the horizontal and vertical values of the screen resolution are provided in a built-in global record called OG_APP.  This record is of type OG_APP_ATTR, which is fully defined in the section "Application Attribute Record" in this chapter.

You should use this global variable instead of an actual numeric value so that your application will maintain a consistent look on systems with different screen resolutions.

The window attibute record contains attributes that may be used only with windows.

TYPE og_window_attr is RECORD      Mask Constants:
(mask        NUMBER(2,0),
 position    og_point,             OG_POSITION_WINDOWA
 width       NUMBER(5,0),          OG_SIZE_WINDOWA
 height      NUMBER(5,0),          OG_SIZE_WINDOWA
 name        VARCHAR2(255),        OG_NAME_WINDOWA
 scrollbars  BOOLEAN,              OG_SCROLLBARS_WINDOWA
 helptarget  VARCHAR2(255)         OG_HELPTARGET_WINDOWA
);
                                   OG_ALL_WINDOWA
                                   OG_NONE_WINDOWA

	Attribute	Description
CSG	position	Is the x- and y-coordinates of the window's upper left corner (in screen resolution units).
CSG	width	Is the width of the window (in screen resolution units).
CSG	height	Is the height of the window (in screen resolution units)
CSG	name	Is the window's name.  At runtime, the default name of the layout window is "Main Layout".
C	scrollbars	Specifies whether scroll bars appear in the window.  The value of this attribute may be one of the following:
		TRUE   Means the window has scroll bars.
		FALSE   Means the window does not have scroll bars.
CSG	helptarget	Is the hypertext target in the runtime Help document that is displayed when the Help system is invoked while the window is active.


About PL/SQL built-ins

This section describes all of the Graphics Builder built-in subprograms.  These subprograms are extensions to the PL/SQL language, and can be used in your own subprograms to access Graphics Builder features and functionality.

For more information on using these subprograms, see the Graphics Builder Developer's Guide.

using the damage flag

using the bounding box update flag

working with lists of objects

built-in subprogram descriptions


About using the damage flag

Many of the following procedures and functions accept a Boolean argument called the "damage flag."  The damage argument is always optional; its value defaults to TRUE if not otherwise specified.

If the damage flag is set to TRUE, the portions of the layout that are affected by the procedure or function are marked as "damaged."  These areas are called "damage regions."  For example, if you change the color or size of an object, the areas of the display in which the object appears are damaged.

Damage regions are always rectangular.  If the affected object is not rectangular, the damage region is the smallest rectangular area that completely encompasses the object.

Damage regions are redrawn automatically when the highest level procedure or function in which they were damaged ends, or when you make an explicit call to the built-in procedure OG_SYNCHRONIZE.  After an area of the screen is redrawn, it is no longer damaged (until another procedure call damages it again).

If the damage flag is set to FALSE, the portions of the layout that are affected by the subprogram call are not damaged, and thus are not redrawn in either of the above situations.

Keep in mind that even if the damage flag is set to FALSE when you modify an object, the changes that you make are still applied to the internal description of that object.  If you later try to programmatically examine the attributes of such an object (e. g., by using the built-in procedure OG_GET_ATTR), you will find that it does not match what appears in the display.

For example, if you change the size of an object, but set the damage flag to FALSE, you will not see any change in the object's size as it appears on the layout.  However, the internal representation of the object will change; if you later use OG_GET_ATTR to determine the object's size, you will find that Graphics Builder considers it to be the size you changed it to, and not the size that it appears to be on the layout.

Be careful when specifying a FALSE damage flag; it is not difficult to cause the display's appearance and the internal description of the display's objects to become "out of sync."

To explicitly damage a region of the layout, use the built-in procedure OG_DAMAGE.


About using the bounding box update flag

Many of the following procedures and functions accept a Boolean argument called the "bounding box update flag."  The bounding box update argument is always optional; its value defaults to TRUE if not otherwise specified.

There are many modifications you can make to an object that affect its inner and/or outer bounding boxes.  For example, when you change an object's edge width, its inner bounding box remains the same, but its outer bounding box may adjust to the new size of the object.  When you move an object, both of its bounding boxes change.

Each time you perform such an operation, Graphics Builder updates the object's bounding boxes internally.  (Bounding boxes are represented by the obbox and ibbox attributes of the generic attribute record.)

If the bounding box update flag is TRUE, Graphics Builder updates the object's bounding boxes normally, after each operation that may affect them.  In addition, Graphics Builder updates the bounding boxes of all of its antecedents, up to¾and including¾the layer on which the object resides.

If the bounding box flag is FALSE, Graphics Builder does not update any bounding boxes.

If you modify many objects¾or modify a few objects many times¾the amount of time Graphics Builder spends updating all of their bounding boxes may adversely affect the performance of your application.  Therefore, to improve efficiency, you may want to wait until all of your modifications are made before updating the bounding boxes.  For example, if you make several modifications to an object, the default behavior is to update the bounding boxes after each modification.  You may choose, however, to inhibit these multiple, automatic bounding box updates, and then explicitly bring the bounding boxes up-to-date via a single call to the built-in procedure OG_UPDATE_BBOX.

On the other hand, if the modifications you make to an object do not affect its bounding boxes (such as changing its color), you may not care whether they are properly updated.  In that case, you may choose to inhibit automatic bounding box updates, and not even bother to update them later.

To explicitly update an object's bounding boxes, use the built-in procedure OG_UPDATE_BBOX.

When you modify an object and set the bounding box update flag to FALSE, it is recommended that you also set the damage flag to FALSE.  Graphics Builder uses the object's bounding boxes to determine the damage region to redraw.  If the bounding boxes are inaccurate, it is likely that the layout will be improperly damaged.


About working with lists of objects

Several of the procedures and functions listed in this section are used to create or modify a "list" of items.  For example, each of the following is composed of a list:

•	a group object contains a list of child objects

•	a polygon object contains a list of points

•	a text object contains a list of compound text elements

•	a compound text element contains a list of simple text elements

•	a chart object contains a list of fields

Each item in a list is assigned an "index," or number, which represents its position in the list.  Lists are zero-based, meaning the first item in a list has an index of 0, the second item has an index of 1, and so on.

For example, below is a graphical representation of a group object (a tennis racquet), and the list of child objects that compose it (head, handle, and grip):

List Operations

There are three operations you can perform on these lists:

•	insert an item

•	delete an item

•	get an item (to examine its value)

For each object that uses a list, Graphics Builder has provided built-in subprograms that allow you to perform these operations.  For example, the subprograms related to a group object and its children are:  OG_INSERT_CHILD, OG_DELETE_CHILD, and OG_GET_CHILD.

All of these subprograms require that you specify the index of the item that you want to manipulate.

For example, suppose you have created the following text object, consisting of one compound text element and three simple text elements:

To delete the second simple text element from the first compound text element, you could pass the text object to this procedure:

PROCEDURE delete_second_word(textobj og_object) IS
BEGIN
   og_delete_smptext(textobj, 0, 1, 1);
END;

As another example, suppose you want to add an object to a group by inserting that object at the end of the group's list of child objects.  To specify an index corresponding to the last item in the list, you would need to know how many items the list contained.  However, the Graphics Builder provides a built-in numeric constant that you can use as an index to specify the last item in the list:  OG_LAST.  (Graphics Builder also provides the constant OG_FIRST to specify the first item in a list.)

The following procedure accepts a group object and another object as arguments, and attaches the other object to the end of the group:

PROCEDURE stick_at_end(groupobj og_object, childobj og_object) IS
BEGIN
   og_insert_child(groupobj, childobj, OG_LAST);
END;

Note that the OG_LAST index may be used only to insert an item at the end of a list.  To delete or get an item from the end of a list, you must specify the actual index value of that item.  To insert an item into an empty list, you may use an index of OG_FIRST or OG_LAST.

When you insert an item using an index that is already occupied by another item, the new item is inserted in front of the old one (i.e., the new item occupies the specified index position).

For more information, refer to the complete description of the list-related subprogram you want to use.


Built-in Subprogram Description

Description:

Specifies the purpose and use of the subprogram.

Syntax:

Is the syntax for calling the subprogram.  If there are multiple ways to call the subprogram, all of the overloadings are shown.

Parameters:

Describes the subprogram's parameters.

Returns:

Describes the subprogram's return value (for functions only).

Comment:

Discusses usage rules and caveats.

Example:

Is a working example of using the subprogram.


Exceptions by name

  Related Topics

Syntax

Exceptions By Name EXCEPTION;


OG_Active_Layer_Del

  Related Topics

Description	This exception is raised when the currently active layer is used as an argument to OG_Destroy.

Syntax

OG_Active_Layer_Del EXCEPTION;

Error Code	 102034


 OG_Append_Failure

  Related Topics

Description	This exception is raised when an error occurs while trying to append data to a custom query.

Syntax

OG_Append_Failure EXCEPTION;

Error Code	 102166


  OG_Column_Not_Settable

  Related Topics

Description	This exception is raised when you attempt to modify the schema of a query column, but the query is not a custom query.

Syntax

OG_Column_Not_Settable EXCEPTION;

Error Code	 102167


OG_Colors_Not_Writable

  Related Topics

Description	This exception is raised when you set call OG_Import_Image and set the use_colors argument to TRUE, but the display's color palette is not editable.

Syntax

OG_Colors_Not_Writable EXCEPTION;

Error Code	 102097


OG_Column_Type_Mismatch

  Related Topics

Description	This exception is raised when the data returned by OG_Get_Charcell, OG_Get_Datecell, or OG_Get_Numcell is not of the type that is expected by that function.

Syntax

OG_Column_Type_Mismatch EXCEPTION;

Error Code	 102043


OG_Date_Overflow

  Related Topics

Description	This exception is raised when you call OG_Update_Chart and the chart contains a date axis, but the range of the data is too big.  For example, if the data spans many years, and the axis step size is seconds, this exception is raised.

Syntax

OG_Date_Overflow EXCEPTION;

Error Code	 102074


OG_Delete_Column_Failure

  Related Topics

Description	This exception is raised when you attempt to delete a column from a query.  You can delete columns only from custom queries.

Syntax

OG_Delete_Column_Failure EXCEPTION;

Error Code	 102169


OG_Delete_Object_Prop_Failure

  Related Topics

Description	This exception is raised when you attempt to delete a property from an object.

Syntax

OG_Delete_Object_Prop_Failure EXCEPTION;

Error Code	 102164


OG_Delete_Param_Error

  Related Topics

Description	This exception is raised when you attempt to delete a parameter.

Syntax

OG_Delete_Param_Error EXCEPTION;

Error Code	 102176


OG_Delete_Property_Error

  Related Topics

Description	This exception is raised when you attempt to delete a property from an object.

Syntax

OG_Delete_Property_Error EXCEPTION;

Error Code	 102181


OG_Display_Closed

  Related Topics

Description	This exception is raised when you attempt to perform an operation on a display after it has been closed via a call to OG_Close_Display.

Syntax

OG_Display_Closed EXCEPTION;

Error Code	 102115


OG_Drawing_Export_Failure

  Related Topics

Description	This exception is raised when OG_Export_Drawing encounters an error while attempting to export a drawing.

Syntax

OG_Drawing_Export_Failure EXCEPTION;

Error Code	 102091


OG_Drawing_Import_Failure

  Related Topics

Description	This exception is raised when OG_Import_Drawing encounters an error while attempting to import a drawing.

Syntax

OG_Drawing_Import_Failure EXCEPTION;

Error Code	 102095


OG_Duplicate_Column_Name

  Related Topics

Description	This exception is raised when you define a column in a custom query, but the column name is already used by another column.

Syntax

OG_Duplicate_Column_Name EXCEPTION;

Error Code	 102172


OG_Duplicate_Display_Name

  Related Topics

Description	This exception is raised when you call OG_Save_Display and set the name argument to be the same as that of another display that is open.

Syntax

OG_Duplicate_Display_Name EXCEPTION;

Error Code	 102106


OG_Duplicate_Ftemp_Name

  Related Topics

Description	This exception is raised when you create a field template, but another field template with that name already exists.

Syntax

OG_Duplicate_Ftemp_Name EXCEPTION;

Error Code	 102156


OG_Duplicate_Query_Name

  Related Topics

Description	This exception is raised when you create a query, but another query with that name already exists.

Syntax

OG_Duplicate_Query_Name EXCEPTION;

Error Code	 102171


OG_Duplicate_Template_Name

  Related Topics

Description	This exception is raised when you create a chart template, but another chart template with that name already exists.

Syntax

OG_Duplicate_Template_Name EXCEPTION;

Error Code	 102157


OG_Env_Var_Error

  Related Topics

Description	This exception is raised when OG_Translate_Envvar encounters an error while attempting to evaluate an environment variable.

Syntax

OG_Env_Var_Error EXCEPTION;

Error Code	 102102


OG_Env_Var_Notfound

  Related Topics

Description	This exception is raised when OG_Translate_Envvar tries to translate an environment variable, but that variable has not been defined for your system.

Syntax

OG_Env_Var_Notfound EXCEPTION;

Error Code	 102103


OG_Font_Not_Found

  Related Topics

Description	This exception is raised when you try to set a font using a font name that cannot be found on your system.

Syntax

OG_Font_Not_Found EXCEPTION;

Error Code	 102098


OG_Generate_Display_Failure

  Related Topics

Description	This exception is raised when OG_Generate_Display encounters an error while attempting to generate a display.

Syntax

OG_Generate_Display_Failure EXCEPTION;

Error Code	 102105


OG_Get_Object_Prop_Failure

  Related Topics

Description	This exception is raised when an error occurs while attempting to get an object property value.

Syntax

OG_Get_Object_Prop_Failure EXCEPTION;

Error Code	 102163


OG_Get_Param_Error

  Related Topics

Description	This exception is raised when an error occurs while attempting to get a parameter value.

Syntax

OG_Get_Param_Error EXCEPTION;

Error Code	 102175


OG_Get_Printer_Failure

  Related Topics

Description	This exception is raised when a you try to print, but Graphics Builder could not find the printer.

Syntax

OG_Get_Printer_Failure EXCEPTION;

Error Code	 102160


OG_Get_Property_Error

  Related Topics

Description	This exception is raised when an error occurs while attempting to get an object property value.

Syntax

OG_Get_Property_Error EXCEPTION;

Error Code	 102179


OG_Hide_Active_Layer

  Related Topics

Description	This exception is raised when the currently active layer is used as the argument for OG_Hide_Layer.  To deactivate a layer, make another layer active by using OG_Activate_Layer.

Syntax

OG_Hide_Active_Layer EXCEPTION;

Error Code	 102013


OG_Host_Failure_Error

  Related Topics

Description	This exception is raised when the built-in procedure OG_Host encounters an error while trying to execute a command on the host system.

Syntax

OG_Host_Failure_Error EXCEPTION;

Error Code	 102059


OG_Image_Creation_Failure

  Related Topics

Description	This exception is raised when you encounter an error while trying to create an image.

Syntax

OG_Image_Creation_Failure EXCEPTION;

Error Code	 102083


OG_Image_Export_Failure

  Related Topics

Description	This exception is raised when OG_Export_Image encounters an error while attempting to export an image.

Syntax

OG_Image_Export_Failure EXCEPTION;

Error Code	 102087


OG_Image_Import_Failure

  Related Topics

Description	This exception is raised when OG_Import_Image encounters an error while attempting to import an image.

Syntax

OG_Image_Import_Failure EXCEPTION;

Error Code	 102093


OG_Incompatible_Pos_Dir

  Related Topics

Description	This exception is raised when you specify an invalid axis direction or position.

Syntax

OG_Incompatible_Pos_Dir EXCEPTION;

Error Code	 102141


OG_Insert_Column_Failure

  Related Topics

Description	This exception is raised when you attempt to insert a column into a query.  You can insert columns only into custom queries.

Syntax

OG_Insert_Column_Failure EXCEPTION;

Error Code	 102168


OG_Internal_OG_Error

  Related Topics

Description	This exception is raised when a serious internal error occurs.  Contact your Oracle support representative.

Syntax

OG_Internal_OG_Error EXCEPTION;

Error Code	 102000


OG_Internal_Tk_Error

  Related Topics

Description	This exception is raised when a serious internal error occurs.  Contact your Oracle support representative.

Syntax

OG_Internal_Tk_Error EXCEPTION;

Error Code	 102001


OG_Invalid_Arc_Fill

  Related Topics

Description	This exception is raised when you use an invalid value when setting the fill style of an arc.

Syntax

OG_Invalid_Arc_Fill EXCEPTION;

Error Code	 102066


OG_Invalid_Arrowstyle

  Related Topics

Description	This exception is raised when you use an invalid value when setting the arrow style of a line.

Syntax

OG_Invalid_Arrowstyle EXCEPTION;

Error Code	 102022


OG_Invalid_Axis

  Related Topics

Description	This exception is raised when you specify an invalid axis value.  Valid values are OG_X_Axis, OG_Y1_Axis, and OG_Y2_Axis only.

Syntax

OG_Invalid_Axis EXCEPTION;

Error Code	 102140


OG_Invalid_Axis_Handle

  Related Topics

Description	This exception is raised when you attempt to reference an invalid axis handle.

Syntax

OG_Invalid_Axis_Handle EXCEPTION;

Error Code	 102122


OG_Invalid_Axis_Mapping

  Related Topics

Description	This exception is raised when you attempt to update a chart with an invalid axis mapping.

Syntax

OG_Invalid_Axis_Mapping EXCEPTION;

Error Code	 102134


OG_Invalid_Baselinetype

  Related Topics

Description	This exception is raised when you specify an invalid baseline type.

Syntax

OG_Invalid_Baselinetype EXCEPTION;

Error Code	 102132


OG_Invalid_Baseline_Value

  Related Topics

Description	This exception is raised when you specify an invalid baseline value.

Syntax

OG_Invalid_Baseline_Value EXCEPTION;

Error Code	 102153


OG_Invalid_Bbox

  Related Topics

Description	This exception is raised when you use an invalid value for the which_bbox argument in the built-in procedure OG_Update_Bbox.

Syntax

OG_Invalid_Bbox EXCEPTION;

Error Code	 102060


OG_Invalid_Buttonproc_Handle

  Related Topics

Description	This exception is raised when an attribute record used as an argument for a procedure contains an invalid value for the button procedure attribute.

Syntax

OG_Invalid_Buttonproc_Handle EXCEPTION;

Error Code	 102006


OG_Invalid_Cachetype

  Related Topics

Description	This exception is raised when you specify an invalid cachetype.  Valid values are OG_Append_Cachetype, OG_Copy_Cachetype, and OG_None_Cachetype only.

Syntax

OG_Invalid_Cachetype EXCEPTION;

Error Code	 102170


OG_Invalid_Cap_Style

  Related Topics

Description	This exception is raised when you specify an invalid value for the cap style.

Syntax

OG_Invalid_Cap_Style EXCEPTION;

Error Code	 102018


OG_Invalid_Catwidth

  Related Topics

Description	This exception is raised when you specify an invalid category width.

Syntax

OG_Invalid_Catwidth EXCEPTION;

Error Code	 102135


OG_Invalid_Chart_Creation_Attr

  Related Topics

Description	This exception is raised when a chart combined attribute record used as an argument for OG_Make contains a chart attribute record whose attributes are not valid.  When a chart is first created, you must specify both a template and a query to be attached to the chart.

Syntax

OG_Invalid_Chart_Creation_Attr EXCEPTION;

Error Code	 102054


OG_Invalid_Chart_Update_Mask

  Related Topics

Description	This exception is raised when the mask value used as an argument for OG_Update_Chart is invalid.

Syntax

OG_Invalid_Chart_Update_Mask EXCEPTION;

Error Code	 102052


OG_Invalid_Child_Del_Total

  Related Topics

Description	This exception is raised when the value used as an argument for OG_Delete_Child that specifies the total number of children to be deleted is greater than the number of children that actually exist in the group after (and including) the specified first child to be deleted.

Syntax

OG_Invalid_Child_Del_Total EXCEPTION;

Error Code	 102032


OG_Invalid_Child_Index

  Related Topics

Description	This exception is raised when the index value used as an argument for OG_Delete_Child, OG_Get_Child, or OG_Insert_Child is greater than the number of children in the group minus one.

Syntax

OG_Invalid_Child_Index EXCEPTION;

Error Code	 102031


OG_Invalid_Child_Object

  Related Topics

Description	This exception is raised when you call OG_Insert_Child and set the child_hdl argument to be an object that cannot be inserted into a group.

Syntax

OG_Invalid_Child_Object EXCEPTION;

Error Code	 102116


OG_Invalid_Cmptext_Del_Total

  Related Topics

Description	This exception is raised when the value used as an argument for OG_Delete_Cmptext that specifies the total number of compound text elements to be deleted is greater than the number of compound text elements that actually exist in the text object after (and including) the specified first element to be deleted.

Syntax

OG_Invalid_Cmptext_Del_Total EXCEPTION;

Error Code	 102037


OG_Invalid_Cmptext_Index

  Related Topics

Description	This exception is raised when you specify a compound text index that is greater than the number of compound text elements in the text object minus one.

Syntax

OG_Invalid_Cmptext_Index EXCEPTION;

Error Code	 102036


OG_Invalid_Color_Name

  Related Topics

Description	This exception is raised when you specify an invalid value for one of the color properties.

Syntax

OG_Invalid_Color_Name EXCEPTION;

Error Code	 102015


OG_Invalid_Column_Index

  Related Topics

Description	This exception is raised when you use an invalid value for the col_num argument in the built-in function OG_Get_Schema.

Syntax

OG_Invalid_Column_Index EXCEPTION;

Error Code	 102099


OG_Invalid_Column_Name

  Related Topics

Description	This exception is raised when:

•	a field record containing an invalid column name has been inserted into a chart (using OG_Insert_Field), and then the chart is updated by a call to OG_Update_Chart

•	an invalid column name is used as an argument for OG_Set_Attr (when setting the attributes of one of the elements of a chart), and then the chart is updated by a call to OG_Update_Chart

•	an invalid column name is used as an argument for OG_Get_Charcell, OG_Get_Datecell, or OG_Get_Numcell

 Syntax

OG_Invalid_Column_Name EXCEPTION;

Error Code	 102044


OG_Invalid_Compression_Type

  Related Topics

Description	This exception is raised when you specify an invalid image compression constant.

Syntax

OG_Invalid_Compression_Type EXCEPTION;

Error Code	 102121


OG_Invalid_Cursor_Offset

  Related Topics

Description	This exception is raised when the offset value used as an argument for OG_Start_From is greater than the number of rows that exist for the specified query minus one.

Syntax

OG_Invalid_Cursor_Offset EXCEPTION;

Error Code	 102047


OG_Invalid_Curvefit

  Related Topics

Description	This exception is raised when you specify an invalid curvefit.

Syntax

OG_Invalid_Curvefit EXCEPTION;

Error Code	 102158


OG_Invalid_Dash_Style

  Related Topics

Description	This exception is raised when an attribute record used as an argument for OG_Make or OG_Set_Attr contains an invalid value for the dash style attribute.

Syntax

OG_Invalid_Dash_Style EXCEPTION;

Error Code	 102019


OG_Invalid_Data_File

  Related Topics

Description	This exception is raised when Graphics Builder encounters an error while attempting to open or read from a PRN, SYLK, or WKS file.

Syntax

OG_Invalid_Data_File EXCEPTION;

Error Code	 102077


OG_Invalid_Data_Flag

  Related Topics

Description	This exception is raised when you specify an invalid data flag.  Valid values are the built-in constants OG_Newdata and OG_Olddata only.

Syntax

OG_Invalid_Data_Flag EXCEPTION;

Error Code	 102042


OG_Invalid_Data_Value

  Related Topics

Description	This exception is raised when you call OG_Update_Chart, and the query on which the chart is based contains data that is invalid for that chart type (e.g., if the chart type is pie and the query contains negative data).

Syntax

OG_Invalid_Data_Value EXCEPTION;

Error Code	 102070


OG_Invalid_Date_Format

  Related Topics

Description	This exception is raised when you specify an invalid date format.

Syntax

OG_Invalid_Date_Format EXCEPTION;

Error Code	 102108


OG_Invalid_Datevalue

  Related Topics

Description	This exception is raised when you specify an invalid date value.

Syntax

OG_Invalid_Datevalue EXCEPTION;

Error Code	 102133


OG_Invalid_Depthsize

  Related Topics

Description	This exception is raised when you specify an invalid depthsize.

Syntax

OG_Invalid_Depthsize EXCEPTION;

Error Code	 102129


OG_Invalid_Direction

  Related Topics

Description	This exception is raised when you specify an invalid axis direction.

Syntax

OG_Invalid_Direction EXCEPTION;

Error Code	 102143


OG_Invalid_Display_Handle

  Related Topics

Description	This exception is raised when an invalid display handle is used as an argument for OG_Close_Display.

Syntax

OG_Invalid_Display_Handle EXCEPTION;

Error Code	 102011


OG_Invalid_Drawing_Format

  Related Topics

Description	This exception is raised when you use an invalid value for the format argument in the built-in procedures OG_Export_Drawing or OG_Import_Drawing.

Syntax

OG_Invalid_Drawing_Format EXCEPTION;

Error Code	 102089


OG_Invalid_External_Location

  Related Topics

Description	This exception is raised when you specify an invalid location.  Valid values are the built-in constants OG_Db and OG_Filesystem only.

Syntax

OG_Invalid_External_Location EXCEPTION;

Error Code	 102056


OG_Invalid_Event_Mask

  Related Topics

Description	This exception is raised when you attempt to specify an invalid value for the events property.

Syntax

OG_Invalid_Event_Mask EXCEPTION;

Error Code	 102058


OG_Invalid_Field_Datatype

  Related Topics

Description	This exception is raised when you call OG_Update_Chart, and the query on which the chart is based contains data whose type is invalid for that chart.  For example, the dependent fields of a pie chart cannot be of type CHAR.  If they are, this exception is raised.

Syntax

OG_Invalid_Field_Datatype EXCEPTION;

Error Code	 102069


OG_Invalid_Field_Del_Total

  Related Topics

Description	This exception is raised when the value used as an argument for OG_Delete_Field that specifies the total number of fields to be deleted from a chart is greater than the number of fields that actually exist in the chart after (and including) the specified first field to be deleted.

Syntax

OG_Invalid_Field_Del_Total EXCEPTION;

Error Code	 102041


OG_Invalid_Field_Index

  Related Topics

Description	This exception is raised when the index value used as an argument for OG_Delete_Field, OG_Get_Field, or OG_Insert_Field is greater than the number of fields in the chart minus one.

Syntax

OG_Invalid_Field_Index EXCEPTION;

Error Code	 102040


OG_Invalid_Field_Template

  Related Topics

Description	This exception is raised when you specify an invalid field template name.

Syntax

OG_Invalid_Field_Template EXCEPTION;

Error Code	 102067


OG_Invalid_Field_Type

  Related Topics

Description	This exception is raised when a field record containing an invalid field type value has been inserted into a chart (using OG_Insert_Field), and then the chart is updated by a call to OG_Update_Chart.  Valid field type values include the built-in constants OG_Dependent and OG_Independent.

Syntax

OG_Invalid_Field_Type EXCEPTION;

Error Code	 102045


OG_Invalid_Ftemp_Del_Total

  Related Topics

Description	This exception is raised when you attempt to delete more field templates than exist in a chart template.

Syntax

OG_Invalid_Ftemp_Del_Total EXCEPTION;

Error Code	 102125


OG_Invalid_Ftemp_Index

  Related Topics

Description	This exception is raised when you specify an invalid field template to delete from a chart template.

Syntax

OG_Invalid_Ftemp_Index EXCEPTION;

Error Code	 102124


OG_Invalid_Gridct

  Related Topics

Description	This exception is raised when you specify an invalid grid count.

Syntax

OG_Invalid_Gridct EXCEPTION;

Error Code	 102155


OG_Invalid_Image_Format

  Related Topics

Description	This exception is raised when you use an invalid value for the format argument in the built-in procedures OG_Export_Image or OG_Import_Image.

Syntax

OG_Invalid_Image_Format EXCEPTION;

Error Code	 102082


OG_Invalid_Join_Style

  Related Topics

Description	This exception is raised when you specify an invalid join style.

Syntax

OG_Invalid_Join_Style EXCEPTION;

Error Code	 102017


OG_Invalid_Labelrot

  Related Topics

Description	This exception is raised when you specify an invalid label rotation.

Syntax

OG_Invalid_Labelrot EXCEPTION;

Error Code	 102150


OG_Invalid_Layer_Handle

  Related Topics

Description	This exception is raised when an invalid layer handle is used as an argument for OG_Activate_Layer, OG_Hide_Layer, or OG_Show_Layer.

Syntax

OG_Invalid_Layer_Handle EXCEPTION;

Error Code	 102009


OG_Invalid_Linestyle

  Related Topics

Description	This exception is raised when you specify an invalid linestyle.

Syntax

OG_Invalid_Linestyle EXCEPTION;

Error Code	 102159


OG_Invalid_Min_Max

  Related Topics

Description	This exception is raised when you specify an invalid axis minimum or maximum.

Syntax

OG_Invalid_Min_Max EXCEPTION;

Error Code	 102139


OG_Invalid_Minimum

  Related Topics

Description	This exception is raised when you specify an invalid axis minimum.

Syntax

OG_Invalid_Minimum EXCEPTION;

Error Code	 102154


OG_Invalid_Month

  Related Topics

Description	This exception is raised when you specify an invalid month.

Syntax

OG_Invalid_Month EXCEPTION;

Error Code	 102149


OG_Invalid_Number_Format

  Related Topics

Description	This exception is raised when you specify an invalid number format.

Syntax

OG_Invalid_Number_Format EXCEPTION;

Error Code	 102138


OG_Invalid_Object_Handle

  Related Topics

Description	This exception is raised when you use an invalid object handle as an argument to a subprogram.

Syntax

OG_Invalid_Object_Handle EXCEPTION;

Error Code	 102003


OG_Invalid_Object_Type

  Related Topics

Description	This exception is raised when an attribute record used as an argument for OG_Make or OG_Set_Attr contains an invalid value for the object type attribute.

Syntax

OG_Invalid_Object_Type EXCEPTION;

Error Code	 102020


OG_Invalid_Overlap

  Related Topics

Description	This exception is raised when you specify an invalid overlap value.

Syntax

OG_Invalid_Overlap EXCEPTION;

Error Code	 102152


OG_Invalid_Pattern_Name

  Related Topics

Description	This exception is raised when you specify an invalid pattern name.

Syntax

OG_Invalid_Pattern_Name EXCEPTION;

Error Code	 102016


OG_Invalid_Pct_By

  Related Topics

Description	This exception is raised when you specify an invalid percent by value.

Syntax

OG_Invalid_Pct_By EXCEPTION;

Error Code	 102148


OG_Invalid_Pct_Of

  Related Topics

Description	This exception is raised when you specify an invalid percent of value.

Syntax

OG_Invalid_Pct_Of EXCEPTION;

Error Code	 102147


OG_Invalid_Pie_Usage

  Related Topics

Description	This exception is raised when you specify an invalid percent of value.

Syntax

OG_Invalid_Pie_Usage EXCEPTION;

Error Code	 102136


OG_Invalid_Pie_Usagevalue

  Related Topics

Description	This exception is raised when you specify an invalid usage value.

Syntax

OG_Invalid_Pie_Usagevalue EXCEPTION;

Error Code	 102137


OG_Invalid_Plotpos

  Related Topics

Description	This exception is raised when you specify an invalid plot position.

Syntax

OG_Invalid_Plotpos EXCEPTION;

Error Code	 102151


OG_Invalid_Point_Del_Total

  Related Topics

Description	This exception is raised when the value used as an argument for OG_Delete_Point that specifies the total number of points to be deleted is greater than the number of points that actually exist in the object after (and including) the specified first point to be deleted.

Syntax

OG_Invalid_Point_Del_Total EXCEPTION;

Error Code	 102035


OG_Invalid_Point_Index

  Related Topics

Description	This exception is raised when the index value used as an argument for OG_Delete_Point, OG_Get_Point, or OG_Insert_Point is greater than the number of points in the object minus one.

Syntax

OG_Invalid_Point_Index EXCEPTION;

Error Code	 102033


OG_Invalid_Position

  Related Topics

Description	This exception is raised when you specify an invalid axis position.

Syntax

OG_Invalid_Position EXCEPTION;

Error Code	 102142


OG_Invalid_Prn_Format

  Related Topics

Description	This exception is raised when you execute a query that references a PRN file, but the file is not a valid PRN format.

Syntax

OG_Invalid_Prn_Format EXCEPTION;

Error Code	 102079


OG_Invalid_Query_Handle

  Related Topics

Description	This exception is raised when you specify an invalid query handle.

Syntax

OG_Invalid_Query_Handle EXCEPTION;

Error Code	 102004


OG_Invalid_Query_Source

  Related Topics

Description	This exception is raised when you specify an invalid SQL statement or filename for a query.

Syntax

OG_Invalid_Query_Source EXCEPTION;

Error Code	 102107


OG_Invalid_Query_Type

  Related Topics

Description	This exception is raised when you specify an invalid query type.

Syntax

OG_Invalid_Query_Type EXCEPTION;

Error Code	 102109


OG_Invalid_Refline_Del_Total

  Related Topics

Description	This exception is raised when you attempt to delete more reference lines than exist in a chart template.

Syntax

OG_Invalid_Refline_Del_Total EXCEPTION;

Error Code	 102128


OG_Invalid_Refline_Index

  Related Topics

Description	This exception is raised when you specify an invalid reference line to delete.

Syntax

OG_Invalid_Refline_Index EXCEPTION;

Error Code	 102127


OG_Invalid_Refline_Handle

  Related Topics

Description	This exception is raised when you reference an invalid reference line handle.

Syntax

OG_Invalid_Refline_Handle EXCEPTION;

Error Code	 102123


OG_Invalid_Row_Number

  Related Topics

Description	This exception is raised when an invalid row number is used as an argument for OG_Set_Attr (when setting the attributes of one of the elements of a chart), and then the chart is updated by a call to OG_Update_Chart.

Syntax

OG_Invalid_Row_Number EXCEPTION;

Error Code	 102053


OG_Invalid_Scale

  Related Topics

Description	This exception is raised when you specify an invalid scale value.

Syntax

OG_Invalid_Scale EXCEPTION;

Error Code	 102146


OG_Invalid_Shadowdir

  Related Topics

Description	This exception is raised when you specify an invalid shadow direction.

Syntax

OG_Invalid_Shadowdir EXCEPTION;

Error Code	 102131


OG_Invalid_Shadowsize

  Related Topics

Description	This exception is raised when you specify an invalid shadow size.

Syntax

OG_Invalid_Shadowsize EXCEPTION;

Error Code	 102130


OG_Invalid_Smptext_Del_Total

  Related Topics

Description	This exception is raised when the value used as an argument for OG_Delete_Smptext that specifies the total number of simple text elements to be deleted is greater than the number of simple text elements that actually exist in the compound text element after (and including) the specified first element to be deleted.

Syntax

OG_Invalid_Smptext_Del_Total EXCEPTION;

Error Code	 102039


OG_Invalid_Smptext_Index

  Related Topics

Description	This exception is raised when the index value used as an argument for OG_Delete_Smptext, OG_Get_Smptext, or OG_Insert_Smptext is greater than the number of simple text elements in the compound text element minus one.

Syntax

OG_Invalid_Smptext_Index EXCEPTION;

Error Code	 102038


OG_Invalid_Sound_Format

  Related Topics

Description	This exception is raised when you specify an invalid sound format.

Syntax

OG_Invalid_Sound_Format EXCEPTION;

Error Code	 102084


OG_Invalid_Sound_Handle

  Related Topics

Description	This exception is raised when an invalid sound handle is used as an argument for OG_Play_Sound.

Syntax

OG_Invalid_Sound_Handle EXCEPTION;

Error Code	 102007


OG_Invalid_Step

  Related Topics

Description	This exception is raised when you specify an invalid step value.

Syntax

OG_Invalid_Step EXCEPTION;

Error Code	 102145


OG_Invalid_Sylk_Format

  Related Topics

Description	This exception is raised when you execute a query that references a SYLK file, but the file is not a valid SYLK format.

Syntax

OG_Invalid_Sylk_Format EXCEPTION;

Error Code	 102078


OG_Invalid_Symbol_Index

  Related Topics

Description	This exception is raised when you specify an invalid symbol index.

Syntax

OG_Invalid_Symbol_Index EXCEPTION;

Error Code	 102023


OG_Invalid_Symbol_Size

  Related Topics

Description	This exception is raised when you specify an invalid symbol size.

Syntax

OG_Invalid_Symbol_Size EXCEPTION;

Error Code	 102024


OG_Invalid_Template_Handle

  Related Topics

Description	This exception is raised when you attempt to use an invalid template handle.

Syntax

OG_Invalid_Template_Handle EXCEPTION;

Error Code	 102005


OG_Invalid_Template_Type

  Related Topics

Description	This exception is raised when you specify an invalid template type.

Syntax

OG_Invalid_Template_Type EXCEPTION;

Error Code	 102126


OG_Invalid_Text_Horalign

  Related Topics

Description	This exception is raised when you specify an invalid alignment value.

Syntax

OG_Invalid_Text_Horalign EXCEPTION;

Error Code	 102026


OG_Invalid_Text_Horjust

  Related Topics

Description	This exception is raised when you specify an invalid justification value.

Syntax

OG_Invalid_Text_Horjust EXCEPTION;

Error Code	 102027


OG_Invalid_Text_Spacing

  Related Topics

Description	This exception is raised when you specify an invalid spacing value.

Syntax

OG_Invalid_Text_Spacing EXCEPTION;

Error Code	 102025


OG_Invalid_Text_Vertalign

  Related Topics

Description	This exception is raised when you specify an invalid alignment value.

Syntax

OG_Invalid_Text_Vertalign EXCEPTION;

Error Code	 102028


OG_Invalid_Text_Vertjust

  Related Topics

Description	This exception is raised when you specify an invalid justification value.

Syntax

OG_Invalid_Text_Vertjust EXCEPTION;

Error Code	 102029


OG_Invalid_Tickpos

  Related Topics

Description	This exception is raised when you specify an invalid tick position.

Syntax

OG_Invalid_Tickpos EXCEPTION;

Error Code	 102144


OG_Invalid_Timer_Handle

  Related Topics

Description	This exception is raised when you specify an invalid timer handle.

Syntax

OG_Invalid_Timer_Handle EXCEPTION;

Error Code	 102010


OG_Invalid_Timer_Procedure

  Related Topics

Description	This exception is raised when you specify an invalid trigger procedure.

Syntax

OG_Invalid_Timer_Procedure EXCEPTION;

Error Code	 102112


OG_Invalid_Timer_Interval

  Related Topics

Description	This exception is raised when you specify an invalid time interval.

Syntax

OG_Invalid_Timer_Interval EXCEPTION;

Error Code	 102113


OG_Invalid_Transfer_Mode

  Related Topics

Description	This exception is raised when you set an invalid transfer mode.

Syntax

OG_Invalid_Transfer_Mode EXCEPTION;

Error Code	 102057


OG_Invalid_Userexit_Invocation

  Related Topics

Description	This exception is raised when Graphics Builder cannot invoke a specified user exit.

Syntax

OG_Invalid_Userexit_Invocation EXCEPTION;

Error Code	 102048


OG_Invalid_Window_Dimensions

  Related Topics

Description	This exception is raised when you specify invalid window dimensions.

Syntax

OG_Invalid_Window_Dimensions EXCEPTION;

Error Code	 102002


OG_Invalid_Window_Handle

  Related Topics

Description	This exception is raised when an invalid window handle is used as an argument for a subprogram.

Syntax

OG_Invalid_Window_Handle EXCEPTION;

Error Code	 102008


OG_Invalid_Wks_Format

  Related Topics

Description	This exception is raised when you execute a query that references a WKS file, but the file is not a valid WKS format.

Syntax

OG_Invalid_Wks_Format EXCEPTION;

Error Code	 102080


OG_Layer_Not_Child_Of_Root

  Related Topics

Description	This exception is raised when an attribute record used as an argument for OG_Make contains an invalid value for the parent attribute.

Syntax

OG_Layer_Not_Child_Of_Root EXCEPTION;

Error Code	 102012


OG_Login_Failure

  Related Topics

Description	This exception is raised when you attempt to connect to a database, using OG_Connect or OG_Logon, but the connection failed.

Syntax

OG_Login_Failure EXCEPTION;

Error Code	 102085


OG_Logoff_Disallowed

  Related Topics

Description	This exception is raised when you call OG_Logoff, but Graphics Builder cannot close the database connection because your display contains open SQL cursors.

Syntax

OG_Logoff_Disallowed EXCEPTION;

Error Code	 102101


OG_Logon_Disallowed

  Related Topics

Description	This exception is raised when you call OG_Logon, but Graphics Builder cannot close the previous database connection because your display contains open SQL cursors.

Syntax

OG_Logon_Disallowed EXCEPTION;

Error Code	 102100


OG_Logoff_Failure

  Related Topics

Description	This exception is raised when OG_Logoff encounters an error while trying to close the database connection.

Syntax

OG_Logoff_Failure EXCEPTION;

Error Code	 102086


OG_Main_Window_Destruction

  Related Topics

Description	This exception is raised when the main display window is used as the argument for OG_Destroy.  To close the main window without destroying it, use OG_Hide_Window.

Syntax

OG_Main_Window_Destruction EXCEPTION;

Error Code	 102046


OG_Missing_Chart_Field

  Related Topics

Description	This exception is raised when you call OG_Update_Chart, but the query on which the chart is based does not contain one or more fields that the chart is expecting.  For example, if you create a chart to plot values for ENAME, SAL, and COMM, but the query returns only ENAME and SAL, this exception is raised.

Syntax

OG_Missing_Chart_Field EXCEPTION;

Error Code	 102068


OG_No_Chart_Data

  Related Topics

Description	This exception is raised when you call OG_Update_Chart, but the query associated with the chart has not yet been executed.

Syntax

OG_No_Chart_Data EXCEPTION;

Error Code	 102114


OG_No_Database_Connection

  Related Topics

Description	This exception is raised when an attempt is made to access a database that has not yet been successfully connected.  It may be raised by OG_Execute_Query or OG_Open_Display.

Syntax

OG_No_Database_Connection EXCEPTION;

Error Code	 102055


OG_No_Dependent_Fields

  Related Topics

Description	This exception is raised when you try to update a chart that does not contain any dependent fields.

Syntax

OG_No_Dependent_Fields EXCEPTION;

Error Code	 102072


OG_No_Independent_Fields

  Related Topics

Description	This exception is raised when you try to update a chart that does not contain any independent fields.

Syntax

OG_No_Independent_Fields EXCEPTION;

Error Code	 102186


OG_No_Query_Name

  Related Topics

Description	This exception is raised when you specify an invalid query name.

Syntax

OG_No_Query_Name EXCEPTION;

Error Code	 102173


OG_No_Schema

  Related Topics

Description	This exception is raised when you attempt to execute a custom query that has no schema.

Syntax

OG_No_Schema EXCEPTION;

Error Code	 102165


OG_Not_Chart_Element

  Related Topics

Description	This exception is raised when you attempt to treat an object as a chart element, but it is not.

Syntax

OG_Not_Chart_Element EXCEPTION;

Error Code	 102184


OG_Not_Supported_In_Designer

  Related Topics

Description	This exception is raised when you attempt to execute a PL/SQL statement that is not applicable to the Graphics Builder designer.  Most likely, you should execute the statement at runtime only.

Syntax

OG_Not_Supported_In_Designer EXCEPTION;

Error Code	 102183


OG_Sound_Conversion_Failure

  Related Topics

Description	This exception is raised when you import a sound, but Graphics Builder could not convert from the sound's original sampling rate or encoding scheme.  Usually, this means the sound is too large.

Syntax

OG_Sound_Conversion_Failure EXCEPTION;

Error Code	 102120


OG_No_Sound_Input_Device

  Related Topics

Description	This exception is raised when you use OG_Play_Sound to play a sound, but there is no sound output device throughwhich to play it.

Syntax

OG_No_Sound_Input_Device EXCEPTION;

Error Code	 102118


OG_No_Sound_Output_Device

  Related Topics

Description	This exception is raised when you use OG_Record_Sound to record a sound, but there is not sound input device through which to record it.

Syntax

OG_No_Sound_Output_Device EXCEPTION;

Error Code	 102117


OG_Not_Chart_Object

  Related Topics

Description	This exception is raised when you call a built-in subprogram that operates on a chart, but the argument you pass it is not a valid handle to a chart object.

Syntax

OG_Not_Chart_Object EXCEPTION;

Error Code	 102061


OG_Not_Group_Object

  Related Topics

Description	This exception is raised when you call a built-in subprogram that operates on a group, but the argument you pass it is not a valid handle to a group object.

Syntax

OG_Not_Group_Object EXCEPTION;

Error Code	 102062


OG_Not_Image_Object

  Related Topics

Description	This exception is raised when you call a built-in subprogram that operates on an image, but the argument you pass it is not a valid handle to a image object.

Syntax

OG_Not_Image_Object EXCEPTION;

Error Code	 102064


OG_Not_Polygon_Object

  Related Topics

Description	This exception is raised when you call a built-in subprogram that operates on a polyline or polygon, but the argument you pass it is not a valid handle to a polyline or polygon object.

Syntax

OG_Not_Polygon_Object EXCEPTION;

Error Code	 102063


OG_Not_Text_Object

  Related Topics

Description	This exception is raised when you call a built-in subprogram that operates on text object, but the argument you pass it is not a valid handle to a text object.

Syntax

OG_Not_Text_Object EXCEPTION;

Error Code	 102065


OG_Null_Chart_Element

  Related Topics

Description	This exception is raised when you call OG_Get_Chart_Element and the chart element is NULL.

Syntax

OG_Null_Chart_Element EXCEPTION;

Error Code	 102187


OG_Null_Module_Name

  Related Topics

Description	This exception is raised when you specify a NULL module name as an argument to a built-in subprogram that exports, imports, or opens a module from the filesystem or database.

Syntax

OG_Null_Module_Name EXCEPTION;

Error Code	 102110


OG_Open_Display_Failure

  Related Topics

Description	This exception is raised when OG_Open_Display encounters an error while attempting to open a display.

Syntax

OG_Open_Display_Failure EXCEPTION;

Error Code	 102030


OG_Parent_Not_Group

  Related Topics

Description	This exception is raised when the parent attribute in an attribute record used as an argument for OG_Make does not contain a valid handle to a group object.

Syntax

OG_Parent_Not_Group EXCEPTION;

Error Code	 102014


OG_Pctchart_Zero

  Related Topics

Description	This exception is raised when you specify an invalid Percent of value for a chart.

Syntax

OG_Pctchart_Zero EXCEPTION;

Error Code	 102071


OG_Piechart_Sum_Overflow

  Related Topics

Description	This exception is raised when you update a pie chart for which you specified a Total Value (in the Pie Frame property sheet) that is less than the actual sum of data returned by the query.

Syntax

OG_Piechart_Sum_Overflow EXCEPTION;

Error Code	 102073


OG_Print_Failure

  Related Topics

Description	This exception is raised when Graphics Builder encounters an error while trying to print the display.

Syntax

OG_Print_Failure EXCEPTION;

Error Code	 102111


OG_Query_Execution_Error

  Related Topics

Description	This exception is raised when Graphics Builder encounters an error while trying to execute a query.

Syntax

OG_Query_Execution_Error EXCEPTION;

Error Code	 102075


OG_Recursive_Chart_Update

  Related Topics

Description	This exception is raised when a process that updates a chart invokes a trigger that explicitly updates the same chart.

Syntax

OG_Recursive_Chart_Update EXCEPTION;

Error Code	 102185


OG_Root_Object_Destruction

  Related Topics

Description	This exception is raised when the object used as an argument to OG_Destroy is the root object in the layout group tree.

Syntax

OG_Root_Object_Destruction EXCEPTION;

Error Code	 102021


OG_Row_Retrieval_Failure

  Related Topics

Description	This exception is raised when OG_Get_Charcell, OG_Get_Datecell, or OG_Get_Numcell fails to find the current row of data.

Syntax

OG_Row_Retrieval_Failure EXCEPTION;

Error Code	 102081


OG_Save_Display_Failure

  Related Topics

Description	This exception is raised when OG_Save_Display encounters an error while attempting to save a display.

Syntax

OG_Save_Display_Failure EXCEPTION;

Error Code	 102104


OG_Set_Object_Prop_Failure

  Related Topics

Description	This exception is raised when an error occurs while setting an object property.

Syntax

OG_Set_Object_Prop_Failure EXCEPTION;

Error Code	 102162


OG_Set_Param_Error

  Related Topics

Description	This exception is raised when an error occurs while setting a parameter.

Syntax

OG_Set_Param_Error EXCEPTION;

Error Code	 102174


OG_Set_Printer_Failure

  Related Topics

Description	This exception is raised when an error occurs while setting the printer name.

Syntax

OG_Set_Printer_Failure EXCEPTION;

Error Code	 102161


OG_Set_Property_Error

  Related Topics

Description	This exception is raised when an error occurs while setting an object property.

Syntax

OG_Set_Property_Error EXCEPTION;

Error Code	 102180


OG_Sound_Export_Failure

  Related Topics

Description	This exception is raised when OG_Export_Sound encounters an error while attempting to export a sound.

Syntax

OG_Sound_Export_Failure EXCEPTION;

Error Code	 102088


OG_Sound_Import_Failure

  Related Topics

Description	This exception is raised when OG_Import_Sound encounters an error while attempting to import a sound.

Syntax

OG_Sound_Import_Failure EXCEPTION;

Error Code	 102094


OG_Sql_Execution_Error

  Related Topics

Description	This exception is raised when Graphics Builder encounters an error while attempting to execute a query based on a SQL statement.

Syntax

OG_Sql_Execution_Error EXCEPTION;

Error Code	 102076


OG_Template_Export_Failure

  Related Topics

Description	This exception is raised when OG_Export_Template encounters an error while attempting to export a template.

Syntax

OG_Template_Export_Failure EXCEPTION;

Error Code	 102092


OG_Template_Import_Failure

  Related Topics

Description	This exception is raised when OG_Import_Template encounters an error while attempting to import a template.

Syntax

OG_Template_Import_Failure EXCEPTION;

Error Code	 102096


OG_Too_Many_Data_Rows

  Related Topics

Description	This exception is raised when you execute a query that returns more rows of data than Graphics Builder can process on your system.

Syntax

OG_Too_Many_Data_Rows EXCEPTION;

Error Code	 102119


OG_Undefined_Param

  Related Topics

Description	This exception is raised when you attempt to reference a parameter that is undefined.

Syntax

OG_Undefined_Param EXCEPTION;

Error Code	 102178


OG_Undefined_Property

  Related Topics

Description	This exception is raised when you attempt to reference an object property that is undefined.

Syntax

OG_Undefined_Property EXCEPTION;

Error Code	 102182


OG_Userexit_Failure_Error

  Related Topics

Description	This exception is raised when a user exit returns its corresponding error code to Graphics Builder.

Syntax

OG_Userexit_Failure_Error EXCEPTION;

Error Code	 102049


OG_Userexit_Fatal_Error

  Related Topics

Description	This exception is raised when a user exit returns its corresponding error code to Graphics Builder.

Syntax

OG_Userexit_Fatal_Error EXCEPTION;

Error Code	 102050


OG_Userexit_Unknown_Error

  Related Topics

Description	This exception is raised when a user exit returns an unrecognized error code to Graphics Builder.

Syntax

OG_Userexit_Unknown_Error EXCEPTION;

Error Code	 102051


Tool_Int.Duplicate_Parameter_Key

  Related Topics

Description	This exception is raised when you attempt to add a parameter to a parameter list, but a parameter with that name is already defined.

Syntax

Tool_Int.Duplicate_Parameter_Key EXCEPTION;

Error Code	 104508


Tool_Int.Duplicate_Parameter_List_Name

  Related Topics

Description	This exception is raised when you attempt to create a parameter list with a name that is already being used by another parameter list.

Syntax

Tool_Int.Duplicate_Parameter_List_Name EXCEPTION;

Error Code	 104504


Tool_Int.Internal_Tools_Error

  Related Topics

Description	This exception is raised when a serious internal error occurs.  Contact your Oracle support representative.

Syntax

Tool_Int.Internal_Tools_Error EXCEPTION;

Error Code	 104500


Tool_Int.Invalid_Communication_Mode

  Related Topics

Description	This exception is raised when you attempt to call Tool_Int.Run_Product using an invalid communication mode.  Valid values are the package constants Tool_Int.Synchronous and Tool_Int.Asynchronous only.

Syntax

Tool_Int.Invalid_Communication_Mode EXCEPTION;

Error Code	 104511


Tool_Int.Invalid_Execution_Mode

  Related Topics

Description	This exception is raised when you attempt to call Tool_Int.Run_Product using an invalid execution mode.  Valid values are the package constants Tool_Int.Batch and Tool_Int.Runtime only.

Syntax

Tool_Int.Invalid_Execution_Mode EXCEPTION;

Error Code	 1045010


Tool_Int.Invalid_Location

  Related Topics

Description	This exception is raised when you attempt to call Tool_Int.Run_Product using an invalid location for the specified module.  Valid values are the package constants Tool_Int.Db and Tool_Int.Filesystem only.

Syntax

Tool_Int.Invalid_Location EXCEPTION;

Error Code	 104503


Tool_Int.Invalid_Parameter_List_Handle

  Related Topics

Description	This exception is raised when you attempt to reference an invalid parameter list handle.

Syntax

Tool_Int.Invalid_Parameter_List_Handle EXCEPTION;

Error Code	 104506


Tool_Int.Invalid_Parameter_Key

  Related Topics

Description	This exception is raised when you attempt to reference a parameter using an invalid name.

Syntax

Tool_Int.Invalid_Parameter_Key EXCEPTION;

Error Code	 104507


Tool_Int.Invalid_Parameter_List_Name

  Related Topics

Description	This exception is raised when you attempt to reference a parameter list using an invalid name.

Syntax

Tool_Int.Invalid_Parameter_List_Name EXCEPTION;

Error Code	 104505


Tool_Int.Invalid_Parameter_Type

  Related Topics

Description	This exception is raised when you set a parameter type to anything other than CHAR, DATE, or NUMBER.

Syntax

Tool_Int.Invalid_Parameter_Type EXCEPTION;

Error Code	 104501


Tool_Int.Invalid_Product

  Related Topics

Description	This exception is raised when you attempt to call Tool_Int.Run_Product using an invalid product.  Valid values are the package constants Tool_Int.Book, Tool_Int.Forms, and Tool_Int.Reports only.

Syntax

Tool_Int.Invalid_Product EXCEPTION;

Error Code	 104502


Tool_Int..Run_Product_Failure
Tool_Int.run_product_failure

  Related Topics

Description	This exception is raised when Graphics Builder cannot run the product specified by a call to Tool_Int.Run_Product.  For information about preparing another product for use with Graphics Builder, see the Graphics Builder documentation for your operating system, or your product documentation.

Syntax

Tool_Int..Run_Product_Failure EXCEPTION;

Error Code	 104509


About PL/SQL built-in exceptions

This section describes all of the Graphics Builder built-in exceptions.  The exceptions are first listed by their error codes, then each one is described completely.  The syntax, description, and error message are provided for each.

If unhandled, each exception will temporarily stop the display execution and raise the listed error message.  After the message is raised and you accept it, the display execution will continue.

For information about scoping rules and propagation of exceptions, see the PL/SQL User's Guide and Reference.


Exceptions by error code

Description

Error Code	Exception Name
102000	OG_Internal_OG_Error
102001	OG_Internal_Tk_Error
102002	OG_Invalid_Window_Dimensions
102003	OG_Invalid_Object_Handle
102004	OG_Invalid_Query_Handle
102005	OG_Invalid_Template_Handle
102006	OG_Invalid_Buttonproc_Handle
102007	OG_Invalid_Sound_Handle
102008	OG_Invalid_Window_Handle
102009	OG_Invalid_Layer_Handle
102010	OG_Invalid_Timer_Handle
102011	OG_Invalid_Display_Handle
102012	OG_Layer_Not_Child_Of_Root
102013	OG_Hide_Active_Layer
102014	OG_Parent_Not_Group
102015	OG_Invalid_Color_Name
102016	OG_Invalid_Pattern_Name
102017	OG_Invalid_Join_Style
102018	OG_Invalid_Cap_Style
102019	OG_Invalid_Dash_Style
102020	OG_Invalid_Object_Type
102021	OG_Root_Object_Destruction
102022	OG_Invalid_Arrowstyle
102023	OG_Invalid_Symbol_Index
102024	OG_Invalid_Symbol_Size
102025	OG_Invalid_Text_Spacing
102026	OG_Invalid_Text_Horalign
102027	OG_Invalid_Text_Horjust
102028	OG_Invalid_Text_Vertalign
102029	OG_Invalid_Text_Vertjust
102030	OG_Open_Display_Failure
102031	OG_Invalid_Child_Index
102032	OG_Invalid_Child_Del_Total
102033	OG_Invalid_Point_Index
102034	OG_Active_Layer_Del
102035	OG_Invalid_Point_Del_Total
102036	OG_Invalid_Cmptext_Index
102037	OG_Invalid_Cmptext_Del_Total
102038	OG_Invalid_Smptext_Index
102039	OG_Invalid_Smptext_Del_Total
102040	OG_Invalid_Field_Index
102041	OG_Invalid_Field_Del_Total
102042	OG_Invalid_Data_Flag
102043	OG_Column_Type_Mismatch
102044	OG_Invalid_Column_Name
102045	OG_Invalid_Field_Type
102046	OG_Main_Window_Destruction
102047	OG_Invalid_Cursor_Offset
102048	OG_Invalid_Userexit_Invocation
102049	OG_Userexit_Failure_Error
102050	OG_Userexit_Fatal_Error
102051	OG_Userexit_Unknown_Error
102052	OG_Invalid_Chart_Update_Mask
102053	OG_Invalid_Row_Number
102054	OG_Invalid_Chart_Creation_Attr
102055	OG_No_Database_Connection
102056	OG_Invalid_External_Location
102057	OG_Invalid_Transfer_Mode
102058	OG_Invalid_Event_Mask
102059	OG_Host_Failure_Error
102060	OG_Invalid_Bbox
102061	OG_Not_Chart_Object
102062	OG_Not_Group_Object
102063	OG_Not_Polygon_Object
102064	OG_Not_Image_Object
102065	OG_Not_Text_Object
102066	OG_Invalid_Arc_Fill
102067	OG_Invalid_Field_Template
102068	OG_Missing_Chart_Field
102069	OG_Invalid_Field_Datatype
102070	OG_Invalid_Data_Value
102071	OG_Pctchart_Zero
102072	OG_No_Dependent_Fields
102073	OG_Piechart_Sum_Overflow
102074	OG_Date_Overflow
102075	OG_Query_Execution_Error
102076	OG_Sql_Execution_Error
102077	OG_Invalid_Data_File
102078	OG_Invalid_Sylk_Format
102079	OG_Invalid_Prn_Format
102080	OG_Invalid_Wks_Format
102081	OG_Row_Retrieval_Failure
102082	OG_Invalid_Image_Format
102083	OG_Image_Creation_Failure
102084	OG_Invalid_Sound_Format
102085	OG_Login_Failure
102086	OG_Logoff_Failure
102087	OG_Image_Export_Failure
102088	OG_Sound_Export_Failure
102089	OG_Invalid_Drawing_Format
102091	OG_Drawing_Export_Failure
102092	OG_Template_Export_Failure
102093	OG_Image_Import_Failure
102094	OG_Sound_Import_Failure
102095	OG_Drawing_Import_Failure
102096	OG_Template_Import_Failure
102097	OG_Colors_Not_Writable
102098	OG_Font_Not_Found
102099	OG_Invalid_Column_Index
102100	OG_Logon_Disallowed
102101	OG_Logoff_Disallowed
102102	OG_Env_Var_Error
102103	OG_Env_Var_Notfound
102104	OG_Save_Display_Failure
102105	OG_Generate_Display_Failure
102106	OG_Duplicate_Display_Name
102107	OG_Invalid_Query_Source
102108	OG_Invalid_Date_Format
102109	OG_Invalid_Query_Type
102110	OG_Null_Module_Name
102111	OG_Print_Failure
102112	OG_Invalid_Timer_Procedure
102113	OG_Invalid_Timer_Interval
102114	OG_No_Chart_Data
102115	OG_Display_Closed
102116	OG_Invalid_Child_Object
102117	OG_No_Sound_Output_Device
102118	OG_No_Sound_Input_Device
102119	OG_Too_Many_Data_Rows
102120	OG_Sound_Conversion_Failure
102121	OG_Invalid_Compression_Type
102122	OG_Invalid_Axis_Handle
102123	OG_Invalid_Refline_Handle
102124	OG_Invalid_Ftemp_Index
102125	OG_Invalid_Ftemp_Del_Total
102126	OG_Invalid_Template_Type
102127	OG_Invalid_Refline_Index
102128	OG_Invalid_Refline_Del_Total
102129	OG_Invalid_Invalid_Depthsize
102130	OG_Invalid_Shadowsize
102131	OG_Invalid_Shadowdir
102132	OG_Invalid_Baselinetype
102133	OG_Invalid_Datevalue
102134	OG_Invalid_Axis_Mapping
102135	OG_Invalid_Catwidth
102136	OG_Invalid_Pie_Usage
102137	OG_Invalid_Pie_Usagevalue
102138	OG_Invalid_Number_Format
102139	OG_Invalid_Min_Max
102140	OG_Invalid_Axistype
102141	OG_Incompatible_Pos_Dir
102142	OG_Invalid_Position
102143	OG_Invalid_Direction
102144	OG_Invalid_Tickpos
102145	OG_Invalid_Step
102146	OG_Invalid_Scale
102147	OG_Invalid_Pct_Of
102148	OG_Invalid_Pct_By
102149	OG_Invalid_Month
102150	OG_Invalid_Labelrot
102151	OG_Invalid_Plotpos
102152	OG_Invalid_Overlap
102153	OG_Invalid_Baseline_Value
102154	OG_Invalid_Minimum
102155	OG_Invalid_Gridct
102156	OG_Duplicate_Ftemp_Name
102157	OG_Duplicate_Template_Name
102158	OG_Invalid_Curvefit
102159	OG_Invalid_Linestyle
102160	OG_Get_Printer_Failure
102161	OG_Set_Printer_Failure
102162	OG_Set_Object_Prop_Failure
102163	OG_Get_Object_Prop_Failure
102164	OG_Delete_Object_Prop_Failure
102165	OG_No_Schema
102166	OG_Get_Append_Failure
102167	OG_Column_Not_Settable
102168	OG_Insert_Column_Failure
102169	OG_Delete_Column_Failure
102170	OG_Invalid_Cachetype
102171	OG_Duplicate_Query_Name
102172	OG_Duplicate_Column_Name
102173	OG_No_Query_Name
102174	OG_Set_Param_Error
102175	OG_Get_Param_Error
102176	OG_Delete_Param_Error
102178	OG_Undefined_Param
102179	OG_Get_Property_Error
102180	OG_Set_Property_Error
102181	OG_Delete_Property_Error
102182	OG_Undefined_Property
102183	OG_Not_Supported_In_Designer
102184	OG_Not_Chart_Element
102185	OG_Recursive_Chart_Update
102186	OG_No_Independent_Fields
102187	OG_Null_Chart_Element
104500	Tool_Int.Internal_Tools_Error
104501	Tool_Int.Invalid_Parameter_Type
104502	Tool_Int.Invalid_Product
104503	Tool_Int.Invalid_Location
104504	Tool_Int.Duplicate_Parameter_List_Name
104505	Tool_Int.Invalid_Parameter_List_Name
104506	Tool_Int.Invalid_Parameter_List_Handle
104507	Tool_Int.Invalid_Parameter_Key
104508	Tool_Int.Duplicate_Parameter_Key
104509	Tool_Int.Run_Product_Failure
104510	Tool_Int.Invalid_Execution_Mode
104511	Tool_Int.Invalid_Communication_Mode


Built-in Datatypes

OG_Arc

OG_Axis

OG_Buttonproc

OG_Colschema

OG_Display

OG_Event

OG_Field

OG_Ftemp

OG_Layer

OG_Object

OG_Point

OG_Query

OG_Rectangle

OG_Refline

OG_Sound

OG_Template

OG_Timer

OG_Window

Tool_Int.Param_Attr

Tool_Int.Paramlist


 OG_Arc

Description	Defines the path of an arc.  This datatype is a record, as defined below:

Syntax

TYPE OG_Arc IS RECORD
(x       NUMBER(10,0),
 y       NUMBER(10,0),
 height  NUMBER(10,0),
 width   NUMBER(10,0),
 sangle  NUMBER(5,0),
 eangle  NUMBER(5,0)
);

where: x	Is the x-coordinate (in layout units) of the upper-left corner of the rectangle used as the basis for the arc (i.e., the rectangle that would connect the arc's four control points).
y	Is the y-coordinate of the upper-left corner of the rectangle used as the basis for the arc (in layout units).
height	Is the height of the rectangle used as the basis for the arc (in layout units).
width	Is the width of the rectangle used as the basis for the arc (in layout units).
sangle	Is the arc's starting angle (in degrees).
eangle	Is the arc's ending angle (in degrees).


 OG_Axis

Description	Is the handle to a chart axis.


 OG_Buttonproc

Description	Is a handle to a button procedure.


OG_Colschema

Description	Describes the schema of a column in a query.  This datatype is a record, as defined below:

Syntax

TYPE OG_Colschema IS RECORD
(colname     VARCHAR2(255),
 coltype     NUMBER(3,0),
 not_null    BOOLEAN,
 precision   NUMBER(3,0),
 scale       NUMBER(3,0),
 maxlen      NUMBER(10,0),
 dateformat  VARCHAR2(255)
);

where: colname	Is the name of the column.
coltype	Is the column type.  The value of this record field may be one of the following built-in constants: OG_Char_Coltype   Means the column type is CHAR, VARCHAR2, or ROWID. OG_Number_Coltype   Means the column type is NUMBER. OG_Long_Coltype   Means the column type is LONG. OG_Date_Coltype   Means the column type is DATE. OG_Raw_Coltype   Means the column type is RAW. OG_Longraw_Coltype   Means the column type is LONGRAW. OG_Mlslabel_Coltype   Means the column type is MLSLABEL.
not_null	Specifies whether the column is constrained to be NOT NULL.  The value of this record field may be one of the following: TRUE   Means the column is constrained to be NOT NULL. FALSE   Means the column is not constrained to be NOT NULL.
precision	Is the precision value set for a column of type NUMBER.  For more information, see the Oracle7 Server SQL Reference.  This record field is meaningful only for SQL queries from a database.
scale	Is the scale value set for a column of type NUMBER.  For more information, see the Oracle7 Server SQL Reference.  This record field is meaningful only for SQL queries from a database.
maxlen	Is the maximum length (in bytes) of the data that the column may contain.  For more information, see the Oracle7 Server SQL Reference.
dateformat	Is the date format mask used recognize column values as dates.


 OG_Display

Description	Is a handle to a display.


 OG_Event

Description	Describes information about a mouse event that invoked a button procedure.  This datatype is a record, as defined below:

Syntax

TYPE OG_Event IS RECORD
(event_type      NUMBER(1,0),
 mouse_position  OG_Point,
 click_count     NUMBER(5,0),
 constrained     BOOLEAN,
 mouse_button    NUMBER(1,0)
);

where: event_type	Is the type of mouse event that was received by the button procedure.  The value of this record field may be one of the following built-in constants: OG_Mouse_Down   Means the procedure received a mouse down event. OG_Mouse_Move_Down   Means the procedure received a mouse move down event. OG_Mouse_Up   Means the procedure received a mouse up event. OG_Mouse_Move_Up   Means the procedure received a mouse move up event.
mouse_position	Is the x- and y- coordinates of the mouse's position on the layout at the time the event was received.
click_count	Is the number of mouse selections that were detected, only if the event was mouse down.  Note:  If a double-click is detected, the procedure also receives all of the events that compose the double-click:  first a mouse down with a click count of 1, then a mouse up, then a mouse down with a click count of 2, and finally another mouse up.  Keep this in mind when defining the logic of your procedures.
constrained	Specifies whether the shift key is down.  The value of this record field may be one of the following: TRUE   Means the shift key is down. FALSE   Means the shift key is not down.
mouse_button	Specifies which button was pressed..  The value of this record field may be one of the following: OG_Left_Mouse_Button OG_Center_Mouse_Button OG_Right_Mouse_Button


OG_Field

Description	Specify properties of a field in a char.t.  This datatype is a record, as defined below:

Syntax

TYPE OG_Field IS RECORD
(field_type  NUMBER(1,0),
 colname     VARCHAR2(255),
 ftname      VARCHAR2(255)
);

where: field_type	Is the field type.  The value of this record field may be one of the following built-in constants: OG_Category   Means the field is plotted in the chart as a category. OG_Dependent   Is a synonym for OG_Value. OG_Subcategory   Means the field is used as a subcategory in a break chart. OG_Independent   Is a synonym for OG_Category. OG_Value   Means the field is plotted in the chart as a value.
colname	Is the name of the column in the chart's query that this field should represent on a chart.
ftname	Is the name of the field template associated with the field.  Note that it is meaningless to associate a field template with a category; when defining such a field, you should not assign it a template.


OG_Ftemp

Description	Is a handle to a field template.


OG_Layer

Description	Is a handle to a layer.


OG_Object

Description	Is a handle to a graphic object.


OG_Point

Description	Specifies the x- and y- values for operations that require coordinate or size information..  This datatype is a record, as defined below:

Syntax

TYPE OG_Point IS RECORD
(x  NUMBER(10,0),
 y  NUMBER(10,0)
);

where: x	Is the value for the x-component.  This value is usually expressed in layout units.
y	Is the value for the y-component.  This value is usually expressed in layout units.


OG_Query

Description	Is a handle to a query.


 OG_Rectangle

Description	Defines a rectangular region.  This datatype is a record, as defined below:

Syntax

TYPE OG_Rectangle IS RECORD
(x       NUMBER(10,0),
 y       NUMBER(10,0),
 height  NUMBER(10,0),
 width   NUMBER(10,0)
);

where: x	Is the x-coordinate of the rectangle's upper-left corner (in layout units).
y	Is the y-coordinate of the rectangle's upper-left corner (in layout units).
height	Is the rectangle's height (in layout units).
width	Is the rectangle's width (in layout units).


 OG_Refline

Description	Is a handle to a reference line.


OG_Sound

Description	Is a handle to a sound.


OG_Template

Description	Is a handle to a chart template.


 OG_Timer

Description	Is a handle to a timer.


OG_Window

Description	Is a handle to a window.


 TOOL_INT.PARAMLIST

Description	Is a handle to a parameter list.


TOOL_INT.PARAM_ATTR

Description	Defines a parameter.  This datatype is a record, as defined below:

Syntax

TYPE TOOL_INT.param_attr IS RECORD
(mask       NUMBER(1,0),
 paramtype  NUMBER(1,0),
 value      VARCHAR2(255))
);

where: mask	Is the mask for the attribute record.
paramtype	Is the parameter type.  The value of this record field may be one of the following built-in constants: TOOL_INT.DATA_PARAMETER TOOL_INT.TEXT_PARAMETER
value	Is the parameter's value.


Built-in Global Variables

OG_App

OG_Inch

OG_Null_Axis

OG_Null_Buttonproc

OG_Null_Display

OG_Null_Ftemp

OG_Null_Layer

OG_Null_Object

OG_Null_Query

OG_Null_Refline

OG_Null_Sound

OG_Null_Template

OG_Null_Timer

OG_Null_Window


OG_App

Description	Contains a snapshot of the application attribute values at the time the first Graphics built-in PL/SQL construct is executed.

Syntax

OG_App  OG_App_Attr;

Note: Since this global variable is a snapshot of values at one point in time, changes you make to the application's attributes will not be reflected in this variable.  For example, the username, password, and connection attributes are not automatically updated when the database connection changes.


OG_Inch

Description	Contains the number of layout units in one inch.

Syntax

OG_Inch  NUMBER;


 OG_Null_Axis

Description	Is a null handle to a chart axis.

Syntax

OG_Null_Axis  OG_Axis;


OG_Null_Buttonproc

Description	Is a null handle to a button procedure.

Syntax

OG_Null_Buttonproc  OG_Buttonproc;


OG_Null_Display

Description	Is a null handle to a display.

Syntax

OG_Null_Display  OG_Display;


OG_Null_Ftemp

Description	Is a null handle to a field template.

Syntax

OG_Null_Ftemp  OG_Ftemp;


OG_Null_Layer

Description	Is a null handle to a layer.

Syntax

OG_Null_Layer  OG_Layer;


OG_Null_Object

Description	Is a null handle to a graphic object.

Syntax

OG_Null_Object  OG_Object;


OG_Null_Query

Description	Is a null handle to a query.

Syntax

OG_Null_Query  OG_Query;


OG_Null_Refline

Description	Is a null handle to a reference line.

Syntax

OG_Null_Refline  OG_Refline;


OG_Null_Sound

Description	Is a null handle to a sound.

Syntax

OG_Null_Sound  OG_Sound;


OG_Null_Template

Description	Is a null handle to a chart template.

Syntax

OG_Null_Template  OG_Template;


OG_Null_Timer

Description	Is a null handle to a timer.

Syntax

OG_Null_Timer  OG_Timer;


OG_Null_Window

Description	Is a null handle to a window.

Syntax

OG_Null_Window  OG_Window;


Alphabetic list of built-in subprograms

OG_Activate_Layer

OG_Activate_Timer

OG_Append_Directory

OG_Append_File

OG_Append_Row

OG_Center

OG_Clear_Query

OG_Clone (Object)

OG_Clone (Template)

OG_Close_Display

OG_Connect

OG_Damage (Object)

OG_Damage (Region)

OG_Data_Changed

OG_Data_Queried

OG_Deactivate_Timer

OG_Delete_Child

OG_Delete_Cmptext

OG_Delete_Column

OG_Delete_Field

OG_Delete_Ftemp

OG_Delete_Param

OG_Delete_Point

OG_Delete_Property

OG_Delete_Refline

OG_Delete_Smptext

OG_Destroy (Object)

OG_Destroy (Query)

OG_Destroy (Sound)

OG_Destroy (Template)

OG_Destroy (Timer)

OG_Destroy (Window)

Do_Sql

OG_Draw

OG_Execute_Query

OG_Export_Drawing (Display)

OG_Export_Drawing (Object/Layer)

OG_Export_Drawing (Window)

OG_Export_Image

OG_Export_Sound

OG_Export_Template

OG_Generate_Display

OG_Get_Attr (Application)

OG_Get_Attr (Axis)

OG_Get_Attr (Display)

OG_Get_Attr (Field Template)

OG_Get_Attr (Frame Template)

OG_Get_Attr (Object)

OG_Get_Attr (Printer)

OG_Get_Attr (Query)

OG_Get_Attr (Reference Line)

OG_Get_Attr (Sound)

OG_Get_Attr (Timer)

OG_Get_Attr (Window)

OG_Get_Axis

OG_Get_Buttonproc

OG_Get_Char_Param

OG_Get_Char_Property

OG_Get_Charcell

OG_Get_Chart_Element

OG_Get_Child

OG_Get_Cmptext

OG_Get_Column

OG_Get_Date_Param

OG_Get_Date_Property

OG_Get_Datecell

OG_Get_Display

OG_Get_Field

OG_Get_Ftemp

OG_Get_Layer

OG_Get_Newrows

OG_Get_Num_Param

OG_Get_Num_Property

OG_Get_Numcell

OG_Get_Object

OG_Get_Param_Type

OG_Get_Point

OG_Get_Query

OG_Get_Refline

OG_Get_Row

OG_Get_Schema

OG_Get_Smptext

OG_Get_Sound

OG_Get_Template

OG_Get_Timer

OG_Get_Window

OG_Help

OG_Hide_Layer

OG_Hide_Window

OG_Host

OG_Import_Drawing

OG_Import_Image

OG_Import_Sound

OG_Import_Template

OG_Insert_Child

OG_Insert_Cmptext

OG_Insert_Column

OG_Insert_Field

OG_Insert_Ftemp

OG_Insert_Point

OG_Insert_Refline

OG_Insert_Smptext

OG_Isnull

OG_Logged_On

OG_Logoff

OG_Logon

OG_Make_Chart

OG_Make_Ellipse

OG_Make_Group

OG_Make_Image

OG_Make_Line

OG_Make_Poly

OG_Make_Query

OG_Make_Rect

OG_Make_Rrect

OG_Make_Sound

OG_Make_Symbol

OG_Make_Template

OG_Make_Text

OG_Make_Timer

OG_Make_Window

OG_Move

OG_Next_Row

OG_Numcols

OG_Numrows

OG_Open_Display

OG_Param_Exists

OG_Pause

OG_Play_Sound

OG_Point_In

OG_Point_Near

OG_Print

OG_Property_Exists

OG_Quit

OG_Record_Sound

OG_Root_Object

OG_Rotate

OG_Same

OG_Save_Display

OG_Scale

OG_Set_Edgecolor

OG_Set_Fillcolor

OG_Set_Attr (Application)

OG_Set_Attr (Axis)

OG_Set_Attr (Chart Element)

OG_Set_Attr (Display)

OG_Set_Attr (Field Template)

OG_Set_Attr (Frame Template)

OG_Set_Attr (Object)

OG_Set_Attr (Printer)

OG_Set_Attr (Query)

OG_Set_Attr (Reference Line)

OG_Set_Attr (Sound)

OG_Set_Attr (Timer)

OG_Set_Attr (Window)

OG_Set_Charcell

OG_Set_Datecell

OG_Set_Numcell

OG_Set_Schema

OG_Set_Param

OG_Set_Property

OG_Show_Layer

OG_Show_Window

OG_Start_From

OG_Stop_Sound

OG_Synchronize

Tool_Int.Add_Parameter

Tool_Int.Create_Parameter_List

Tool_Int.Delete_Parameter

Tool_Int.Destroy_Parameter_List

Tool_Int.Get_Parameter_Attr

Tool_Int.Get_Parameter_List

Tool_Int.Isnull

Tool_Int.Run_Product

Tool_Int.Set_Parameter_Attr

OG_Translate_Envvar

OG_Update_Chart

OG_Update_Bbox

OG_User_Exit


No built-in subprograms begin with this letter.


Chart Built-ins

OG_Delete_Column

OG_Delete_Field

OG_Get_Chart_Element

OG_Get_Column

OG_Get_Field

OG_Get_Row

OG_Insert_Field

OG_Make_Chart

OG_Update_Chart


OG_Delete_Column

  Examples	  Related Topics

Description  This procedure deletes a column from a custom query.

Syntax

PROCEDURE OG_Delete_Column
  (query_hdl  OG_Query,
   indx       NUMBER,
   total      NUMBER);

Parameters

query_hdl	Is the handle to the query from which to delete the column.
indx	Is the index of the first column to delete from the query.
total	Is the total number of columns to delete.


OG_Delete_Column Example

  Alphabetic List          [image]  All Examples    [image]  Related Topics

 /* The following procedure deletes a column
 ** from the query ‘query0’:
 */

PROCEDURE example(col_num number) IS
   query   OG_Query;
BEGIN
   query:=OG_Get_Query(‘query0’);
   OG_Delete_Column(query, col_num, 1);
END;


OG_Delete_Field

  Examples	  Related Topics

Description  This procedure deletes one or more fields from the specified chart object.

Syntax

PROCEDURE OG_Delete_Field
  (chart_hdl  OG_Object,
   indx       NUMBER,
   total      NUMBER);

Parameters

chart_hdl	Is the handle to the chart object.
indx	Is the index of the first field to delete from the field list.
total	Is the total number of fields to delete.

Usage Notes  Deleting a field only removes it from the specified chart.  It does not delete (or otherwise modify) the field template that the field may reference.  In addition, any changes you make to the chart's field list will not be applied until the chart is updated via a call to OG_Update_Chart.


OG_Delete_Field Examples

  Alphabetic List          [image]  All Examples    [image]  Related Topics

 /* Suppose one chart currently displays plots for both salary
 ** and commission data, and you want to remove the
 ** commission plot from that chart and plot it on another one.
 */

PROCEDURE transfer_comm(chart1 IN OG_Object, chart2 IN
OG_Object, field_index in number) IS
   the_field   OG_Field;
BEGIN
   the_field:=OG_Get_Field(Chart1, field_index);
   OG_Delete_Field(Chart1, field_index, 1);
   OG_Insert_Field(Chart2, the_field, OG_Last);
   OG_Update_Chart(Chart1, OG_All_Chupda);
   OG_Update_Chart(Chart2, OG_All_Chupda);
END;


OG_Get_Chart_Element

  Examples	  Related Topics

Description  Given the handle to a group of chart elements (bars, pie slices, etc) and a row number, this function returns the individual element corresponding to that row number.

Syntax

FUNCTION OG_Get_Chart_Element
  (group_hdl  OG_Object,
   row_num    NUMBER)
RETURN OG_Object;

Parameters

group_hdl	Is the handle to the group containing the chart element.
row_num	Is the row number corresponding to the chart element you wish to get.
Returns  The individual chart element for the specified row number.

Usage Notes  The group handle can be retrieved from the chart object using OG_Get_Object with the appropriate name.


OG_Get_Chart_Element Examples

  Alphabetic List          [image]  All Examples    [image]  Related Topics

 /* The following procedure changes the color of the first:
 ** bar in a column chart, regardless of its value:
 */

PROCEDURE example(chart OG_Object) IS
  bars_group  OG_Object;
  elem        OG_Object;
BEGIN
  bars_group := OG_Get_Object('Sal_Bars', chart);
  elem := OG_Get_Chart_Element(Bars_Group, 0);
  OG_Set_Fillcolor(Elem, 'red');
END;


OG_Get_Column

  Examples	  Related Topics

Description  This function returns the name of the query column represented by a specific chart element.

Syntax

FUNCTION OG_Get_Column
  (chelement_hdl  OG_Object)
RETURN VARCHAR2;

Parameters

chelement_hdl	Is the handle to the chart element.
Returns  The name of the column associated with the chart element.


OG_Get_Column Examples

  Alphabetic List          [image]  All Examples    [image]  Related Topics

 /* The following function returns the query column represented by
 ** the first bar in a column chart:
*/

FUNCTION example(chart OG_Object) RETURN CHAR IS
  bars  OG_Object;
  elem  OG_Object;
  col   VARCHAR2(15);
BEGIN
  bars := OG_Get_Object('Sal_Bars', chart);
  elem := OG_Get_Chart_Element(Bars, 0);
  col := OG_Get_Column(Elem);
  RETURN(col);
END;


OG_Get_Field

  Examples	  Related Topics

Description  This function returns a record containing the field's attribute values in the specified chart.

Syntax

FUNCTION OG_Get_Field
  (chart_hdl  OG_Object,
   indx       NUMBER)
RETURN OG_Field;

Parameters

chart_hdl	Is the handle to the chart object.
indx	Is the index of the field in the chart's field list to be returned.
Returns  The attributes of the specified field.


OG_Get_Field Examples

  Alphabetic List          [image]  All Examples    [image]  Related Topics

 /* Suppose one chart currently displays plots for both salary
 ** and commission data, and you want to remove the
 ** commission plot from that chart and plot it on another one:
 */

PROCEDURE transfer_comm(chart1 IN OG_Object, chart2 IN
  OG_Object, field_index IN NUMBER) IS
   the_field   OG_Field
BEGIN
   the_field:=OG_Get_Field(The_Chart, field_index);
   OG_Delete_Field(Chart1, field_index, 1);
   OG_Insert_Field(Chart2, the_field, OG_Last);
END;


OG_Get_Row

  Examples	  Related Topics

Description  This function returns the query row number that is represented by a specific chart element.

Syntax

FUNCTION OG_Get_Row
  (chelement_hdl  OG_Object,
RETURN NUMBER;

Parameters

chelement_hdl	Is the handle to the chart element.
Returns  The row number associated with the chart element.


OG_Get_Row Examples

  Alphabetic List          [image]  All Examples    [image]  Related Topics

 /* The following format trigger explodes the pie slice
 ** representing SAL for employee 'SMITH':
 */

PROCEDURE OGFORMATTRIG0(elem IN OG_Object,
                        query IN OG_Query) IS
  ename    VARCHAR2(10);
  chart    OG_Object;
  row_num  NUMBER;
BEGIN
  ename := OG_Get_Charcell(Query, 'ENAME');
  IF ename = 'SMITH' THEN
    chart := OG_Get_Object('Chart0');
    row_num := OG_Get_Row(Elem);
    OG_Set_Explosion(Chart, row_num, 'SAL', 25);
  END IF;
END;


OG_Insert_Field

  Examples	  Related Topics

Description  This procedure inserts a new field into the specified chart.

Syntax

PROCEDURE OG_Insert_Field
  (chart_hdl  OG_Object,
   field_rec  OG_Field,
   indx       NUMBER);

Parameters

chart_hdl	Is the handle to the chart object,
field_rec	Is the record containing the field's attributes.
indx	Is the index at which to insert the new field in the chart's field list.  This argument must be an integer between 0 and n (inclusive), where n is the number of fields in the chart prior to the insertion.  The value of this argument may also be one of the following built-in constants: OG_First   Means insert the new field at the beginning of the chart's field list (index = 0). OG_Last   Means insert the new field at the end of the chart's field list (index = the number of fields in the chart prior to the insertion).
Usage Notes  Any changes you make to the chart's field list are not applied until the chart is updated via a call to OG_Update_Chart.


OG_Insert_Field Examples

  Alphabetic List          [image]  All Examples    [image]  Related Topics

 /* Suppose one chart currently displays plots for both
 ** salary and commission data, and you want to remove
 ** the commission plot from that chart and plot it on another one:
 */

PROCEDURE transfer_comm (chart1 IN OG_Object, chart2 IN
OG_Object, field_index IN NUMBER) IS
   the_field   OG_Field;
BEGIN
   the_field:=OG_Get_Field(The_Chart, field_index);
   OG_Delete_Field(Chart1, field_index, 1);
   OG_Insert_Field(Chart2, the_field, OG_Last);
END;


OG_Make_Chart

  Examples	  Related Topics

Description  This function creates a chart.

Syntax

FUNCTION OG_Make_Chart
  (position  OG_Point,
   height    NUMBER,
   width     NUMBER,
   template  OG_Template,
   query     OG_Query)
RETURN OG_Object;

Parameters

position	The x- and y-coordinates of the chart frame.
height	The chart height.
width	The chart width.
template	The template to use for the chart.
query	The query to use for the chart.
Returns  A handle to the newly created chart.

Usage Notes   The chart will not be complete until you add fields to it using OG_Insert_Field and update it using OG_Update_Chart.


OG_Make_Chart Examples

  Alphabetic List          [image]  All Examples    [image]  Related Topics

 /* The following function creates a chart using
 ** the specified template and query:
 */

FUNCTION example(template OG_Template, query OG_Query) RETURN OG_Object IS
  chart   OG_Object;
  pos     OG_Point;
  height  NUMBER;
  width   NUMBER;
BEGIN
  pos.x := OG_Inch;
  pos.y := OG_Inch;
  height := 4* OG_Inch;
  width := 4* OG_Inch;

  chart := OG_Make_Chart(Pos, height, width, template, query);
  RETURN(chart);
END;


OG_Update_Chart

  Examples	  Related Topics

Description  This procedure updates the specified part(s) of the specified chart to reflect new query results or new attributes that have been applied to chart elements.  You must have executed the query at least once before you can update a chart that is based upon it.

Syntax

PROCEDURE OG_Update_Chart
  (chart_hdl    OG_Object,
   chart_mask   NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

chart_hdl	Is the handle to the chart to be updated.
chart_mask	Specifies which part(s) of the chart should be updated.  The value of this argument may be one of the following built-in constants:  OG_All_Chupda   Means update the entire chart. OG_Dep1axis_Chupda   Means update only the parts of the chart associated with the first dependent axis.. OG_Dep2axis_Chupda   Means update only the parts of the chart associated with the second dependent axis.. OG_Frame_Chupda   Means update only the parts of the chart associated with the frame. OG_Indaxis_Chupda   Means update only the parts of the chart associated with the independent axis. OG_Inframe_Chupda   Means update only the parts of the chart that appear within the frame. OG_Legend_Chupda   Means update only the parts of the chart associated with the legend. OG_None_Chupda   Means do not update any parts of the chart. OG_Title_Chupda   Means update only the chart title.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  When this procedure is invoked, Graphics Builder will destroy the current chart and rebuild it, based on updated query results and attribute settings.  Because of this, any changes to a chart element's attribute settings since the last invocation of OG_Update_Chart will be lost.  For example, if you use OG_Set_Attr to set the attributes for a specific bar in the chart and then update it, you will see the desired results.  If you call OG_Update_Chart again, however, the changes will be lost and the bar will appear with its default settings.

Remember, then, that each time you update the chart, you must first make the changes to the chart elements.  In many cases you will find that this extra step is desirable, since the criteria for modifying chart elements may change as the data changes.


OG_Update_Chart Examples

  Alphabetic List          [image]  All Examples    [image]  Related Topics

 /* Suppose you want to update a chart periodically.
 ** You could write the following timer trigger:
 */

PROCEDURE my_timer IS+
   my_query   OG_Query;
   my_chart   OG_Object;
BEGIN
   my_query:=OG_Get_Query('Emp_Query');
   my_chart:=OG_Get_Object('Emp_Chart');
   OG_Execute_Query(My_Query);
   OG_Update_Chart(My_Chart, OG_All_Chupda);
END;


Database Built-ins

OG_Connect

OG_Logged_On

OG_Logoff

OG_Logon


 OG_Connect

  Examples	  Related Topics

Description  This function shows the Connect dialog box.

Syntax

FUNCTION OG_Connect
RETURN BOOLEAN;

Parameters:

None.


OG_Connect Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose your application requires the
** user to be connected to a database.  The
** following procedure checks if a connection
** exists and, if not, prompts the user to
** connect by showing the Connect dialog box:
*/

PROCEDURE ensure_connection IS
BEGIN
   IF NOT OG_Logged_On THEN
   status:=OG_Connect;
   END IF;
END;


OG_Logged_On

  Examples	  Related Topics

Description  This function returns TRUE if the user is currently connected to a database, and FALSE if not connected.

Syntax

FUNCTION OG_Logged_On
RETURN BOOLEAN;

Parameters:

None.

Returns TRUE	If the user is connected to a database.
FALSE	If the user is not connected to a database.


OG_Logged_On Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose your application requires the user to be
** connected to a database.  The following procedure
** checks if a connection exists and, if not, prompts the
** user to connect by showing the Connect dialog box:
*/

PROCEDURE ensure_connection IS
BEGIN
   IF NOT OG_Logged_On THEN
      OG_Connect;
   END IF;
END;


OG_Logoff

  Examples	  Related Topics

Description  This procedure closes the existing database connection.

Syntax

PROCEDURE OG_Logoff;

Parameters:

None.


OG_Logoff Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to disconnect from a database when the display is closed.
** You could write the following Close Display trigger:
*/

PROCEDURE close_trig IS
BEGIN
   IF OG_Logged_On THEN
      OG_Logoff;
   END IF;
END;


OG_Logon

  Examples	  Related Topics

Description This procedure connects to the specified database.

Syntax

PROCEDURE OG_Logon
  (username        VARCHAR2  :=  NULL,
   password        VARCHAR2  :=  NULL,
   connect_string  VARCHAR2  :=  NULL);

Parameters

username	Is the username to use.
password	Is the password to use.
connect_string	Is the database connect string to use.  To connect to a remote database, you must provide the appropriate SQL*Net database connect string.   For more information, see the Oracle Network Manager Administrator's Guide.
Usage Notes  If a connection already exists, it is first dropped, regardless of whether the connection then attempted by this procedure is successful.


OG_Logon Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose your application requires the user to be connected to a database.
** The following procedure checks if a connection exists and, if not,
**automatically establishes a connection:
*/

PROCEDURE ensure_connection IS
BEGIN
   IF NOT OG_Logged_On THEN
      OG_Logon('Scott', 'tiger', 't:london:MY_DB');
   END IF;
END;


Display Built-ins

OG_Close_Display

OG_Generate_Display

OG_Get_Display

OG_Isnull

OG_Open_Display

OG_Save_Display


OG_Close_Display

  Examples	  Related Topics

Description  This procedure closes the specified display and destroys all windows used by that display. It also causes the Close Display trigger for the specified display to execute.

Syntax

PROCEDURE OG_Close_Display
  (display_hdl  OG_Display);

Parameters

display_hdl	Is the handle to the display to be closed.
Usage Notes  Note that if you call a procedure that closes the current display (i.e., the display in which the executing procedure is defined), OG_Close_Display must appear on the last line of that procedure.  In other words, you cannot execute any further PL/SQL instructions in a display after you have closed it.


OG_Close_Display Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose the user is through with one display,
** and you want to close it and open another one.
*/

PROCEDURE continue (old_disp_name, new_disp_name) IS
   old_disp   OG_Display;


OG_Generate_Display

  Examples	  Related Topics

Description  This function generates the current of the display.  The generated display may be run by the Graphics Builder Runtime and Batch executables.

Syntax

PROCEDURE OG_Generate_Display;

PROCEDURE OG_Generate_Display
  (name        VARCHAR2,
   repository  OG_Number);

Parameters

name	Is the name to which the display is generated.  If the display is to be stored in the database, this argument should contain only the name of the display.  If the display is to be stored in the file system, this argument should contain the absolute or relative pathname of the display file.
repository	Specifies whether the display is to be stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the display is to be stored in the database. OG_Filesystem   Means the display is to be stored in the file system.
Usage Notes  If you omit name and repository, the display is generated to the name and repository from which it was most recently opened.


OG_Generate_Display Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose your display allows the user to interactively specify
**which queries to view, and what chart types to use.
**When the user selects a `generate' button, you may want to
**generate a runtime version of the display
** that the user can use in the future.
*/

PROCEDURE gen(buttonobj IN OG_Object, hitobj IN OG_Object,
  win IN OG_Window, eventinfo IN OG_Event) IS


OG_Get_Display

  Examples	  Related Topics

Description  Note that display_name must already be open in the current Graphics Builder session.  To open a display other than the one that is currently running, use OG_Open_Display.

Syntax

FUNCTION OG_Get_Display
RETURN OG_Display;

FUNCTION OG_Get_Display
  (display_name  VARCHAR2,
   repository    NUMBER)
RETURN OG_Display;

Parameters

display_name	Is the name of the display.  If the display is stored in the database, this argument should contain only the name of the display.  If the display is stored in the file system, this argument should contain the absolute or relative pathname of the display file.
repository	Specifies whether the display is stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the display is to be stored in the database. OG_Filesystem   Means the display is to be stored in the file system.
Returns  A handle to the specified display.  If the display does not exist or is not open, this function returns a null handle.

Usage Notes  If display_name and repository are omitted, this function returns a handle to the current display.


OG_Get_Display Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose the user is through with one display,
** and you would like to close it and open another one.
*/
.

PROCEDURE continue(old_disp_name, new_disp_name) IS
   old_disp   OG_Display;
   new_disp   OG_Display;
BEGIN
   old_dispb:=OG_Get_Display(Old_Disp_Name, OG_Filesystem);
   OG_Close_Display(Old_Disp);
   new_dispb:=OG_Open_Display(New_Disp_Name, OG_Filesystem);
END;


OG_Isnull

  Examples	  Related Topics

Description  This function determines if the specified handle is a null handle.

Syntax

FUNCTION OG_Isnull                           query
  (handle  OG_Query)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           object
  (handle  OG_Object)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           chart template
  (handle  OG_Template)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           button procedure
  (handle  OG_Buttonproc)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           sound
  (handle  OG_Sound)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           window
  (handle  OG_Window)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           layer
  (handle  OG_Layer)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           timer
  (handle  OG_Timer)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           display
  (handle  OG_Display)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           axis
  (handle  OG_Axis)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           field template
  (handle  OG_Ftemp)
RETURN BOOLEAN;

FUNCTION OG_Isnull                           reference line
  (handle  OG_Refline)
RETURN BOOLEAN;

Parameters

handle	Is the handle to be evaluated.
Returns TRUE	If the handle is a null handle.
FALSE	If the handle is not a null handle.


OG_Isnull Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose your display occasionally creates a text object that contains a warning message.  At times you
** may want to remove the warning message before continuing with the execution of the display.  Rather
** than keeping track of whether a warning has been generated, you can check for the existence of the
** text object before deleting it.
*/

PROCEDURE remove_warning IS
   warning_obj   OG_Object;
BEGIN
   warning_obj:=OG_Get_Object(‘warning’);
   IF NOT (OG_Isnull(warning_obj)) THEN;
      OG_Destroy(warning_obj);
   END IF;
END;


OG_Open_Display

  Examples	  Related Topics

Description  This function opens the specified display and executes its Open Display trigger.  It returns a handle to the display, which you may later use as an argument for OG_Close_Display. If the display does not exist, this function returns a null handle.

Syntax

FUNCTION OG_Open_Display
  (display_name  VARCHAR2,
   repository    NUMBER)
RETURN OG_Display;

Parameters

display_name	Is the name of the display.  If the display is stored in the database, this argument should contain only its name.  If the display is stored in the file system, this argument should contain the absolute or relative pathname of the display file.
repository	Specifies whether the display is stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the display is stored in the database. OG_Filesystem   Means the display is stored in the file system.
Returns  A handle to the newly opened display.

Usage Notes  Note that this function does not accept a handle to a display as an argument.  This is because the existence of the display in the file system or database must be verified before the display can be opened.  Suppose you used OG_Get_Display to get the display handle, then you deleted the display from the file system or database.  If you tried to pass the display handle to OG_Open_Display, it would not be able to find the display that the handle referred to.  Therefore, the display name must again be used.


OG_Open_Display Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose the user is through with one display,
** and you would like to close it and open another one.
*/
.

PROCEDURE continue(old_display_name IN CHAR,
new_display_name IN CHAR) IS
   old_display   OG_Display;
   new_display   OG_Display;
BEGIN
   old_display:=OG_Get_Display(old_display_name, OG_Filesystem);
   new_display:=OG_Open_Display(new_display_name, OG_Filesystem);
   OG_Close_Display(old_display);
END;


OG_Save_Display

  Examples	  Related Topics

Description  This function saves the current state of the display.  The saved display is complete and may be opened and edited in the Graphics Builder Builder.

Syntax

PROCEDURE OG_Save_Display;

PROCEDURE OG_Save_Display
  (name        VARCHAR2,
   repository  OG_Number);

Parameters

name	Is the name to which the display is saved.  If the display is to be stored in the database, this argument should contain only the name of the display.  If the display is to be stored in the file system, this argument should contain the absolute or relative pathname of the display file.
repository	Specifies whether the display is to be stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the display is to be stored in the database. OG_Filesystem   Means the display is to be stored in the file system.
Usage Notes  If you omit name and repository, the display is saved to the name and repository from which it was most recently opened.


OG_Save_Display Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to import 100 TIFF images.  Doing this
**manually is tedious and would take a long time.
**The solution is to write the following procedure,
**which imports images from the files named `image00'
**through `image99'.  When finished, it saves the display
**so that you can open it again in the Builder.
*/

PROCEDURE import_100 IS
   the_image   OG_Image;
   file_name   VARCHAR2(7);
BEGIN
   FOR i IN 0..99 LOOP
      file_name:='image'||SUBSTR(TO_CHAR(i, `09'), 2);
      the_image:=OG_Import_Image(File_Name, OG_Filesystem, OG_Tiff_Iformat);
   END LOOP;
   OG_Save_Display;
END;


Layer Built-ins

OG_Activate_Layer

OG_Get_Layer

OG_Hide_Layer

OG_Show_Layer


OG_Activate_Layer

  Examples	  Related Topics

Description  This procedure activates the specified layer in the specified window.

Syntax

PROCEDURE OG_Activate_Layer
  (layer_hdl   OG_Layer,
   window_hdl  OG_Window
   damage      BOOLEAN   :=  TRUE);

PROCEDURE OG_Activate_Layer
  (layer_hdl   OG_Layer,
   damage      BOOLEAN   :=  TRUE);

Parameters

layer_hdl	Is the handle to the layer that is activated.
window_hdl	Is the handle to the window in which the layer is activated.  If not specified, the layer is activated in all windows.
damage	Is the damage flag.
Usage Notes  Activating a hidden layer forces it to be shown.  One layer only can be active at a time; when you activate a layer, the previously active layer is deactivated.

If you insert a group object as a child of the display's root object, you can then use OG_Get_Layer to get a layer handle to that group.  Activating such a group object forces Graphics Builder to recognize it as a layer.


OG_Activate_Layer Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose your layout contains several layers,
**each of which contains a set of buttons.
**If you want certain buttons to be active at
**a specific time, you can activate the layer
**that contains those buttons.  If the user
**selects a button object that is not in the active
**layer, nothing will happen.
*/

PROCEDURE activate_a_layer(layer_num NUMBER, the_window OG_Window) IS
   layer_name   VARCHAR2(6);
   the_layer    OG_Layer;
BEGIN
   layer_name:='layer'||TO_CHAR(layer_num);
   the_layer:=OG_Get_Layer(Layer_Name);
   OG_Activate_Layer(The_Layer, the_window);
END;


OG_Get_Layer

  Examples	  Related Topics

Description  Note that you can also treat a layer as a group object by passing its name to OG_Get_Object.

Syntax

FUNCTION OG_Get_Layer
  (layer_name  VARCHAR2)
RETURN OG_Layer;

Parameters

layer_name	Is the name of the layer whose handle should be returned.
Returns  A handle to the specified layer.  If the layer does not exist, this function will return a null handle.

Usage Notes  In addition, you can user OG_Get_Layer to get a layer handle to a group object, then force that group to become a layer by showing it or activating it.


OG_Get_Layer Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to hide "layer1".
*/

PROCEDURE make_layer1_invis (the_window) IS
   my_layer   OG_Layer;
BEGIN
   my_layer:=OG_Get_Layer('Layer1');
   OG_Hide_Layer(My_Layer, the_window);
END;


OG_Hide_Layer

  Examples	  Related Topics

Description  This procedure hides the specified layer.

Syntax

PROCEDURE OG_Hide_Layer
  (layer_hdl   OG_Layer);

PROCEDURE OG_Hide_Layer
  (layer_hdl   OG_Layer,
   window_hdl  OG_Window);

Parameters

layer_hdl	Is the handle to the layer that is hidden.
window_hdl	Is the handle to the window in which the layer is hidden.  If not specified, the layer is hidden in all windows.
Usage Notes  If the layer is showing in more than one window, it will be hidden in the specified window only.  The active layer cannot be hidden; to do so, you must first activate another layer.


OG_Hide_Layer Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose "layer1" contains information that is no longer useful to view.
**The following procedure will hide it:
*/

PROCEDURE make_layer1_invis(the_window) IS
   my_layer   OG_Layer;
BEGIN
   my_layer:=OG_Get_Layer('Layer1');
   OG_Hide_Layer(My_Layer, the_window);
END;


OG_Show_Layer

  Examples	  Related Topics

Description  This procedure shows the specified layer.

Syntax

PROCEDURE OG_Show_Layer
  (layer_hdl   OG_Layer,
   window_hdl  OG_Window);

Parameters

layer_hdl	Is the handle to the layer that is shown.
window_hdl	Is the handle to the window in which the layer is shown.  If not specified, the layer is shown in all windows.
Usage Notes  If the layer is hidden in more than one window, it will be shown in the specified window only.

If you insert a group object as a child of the display's root object, you can then use OG_Get_Layer to get a layer handle to that group.  Showing such a group object forces Graphics Builder to recognize it as a layer.


OG_Show_Layer Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to show "layer1".
*/

PROCEDURE make_layer_visible (the_window) IS
   my_layer   OG_Layer;
BEGIN
   my_layer:=OG_Get_Layer('Layer1');
   OG_Show_Layer(My_Layer, the_window);
END;


Miscellaneous Built-ins

Do_Sql

OG_Append_Directory

OG_Append_File

OG_Center

OG_Damage (Region)

OG_Get_Attr (Application)

OG_Get_Attr (Axis)

OG_Get_Attr (Display)

OG_Get_Attr (Field Template)

OG_Get_Attr (Frame Template)

OG_Get_Attr (Object)

OG_Get_Attr (Printer)

OG_Get_Attr (Query)

OG_Get_Attr (Reference Line)

OG_Get_Attr (Sound)

OG_Get_Attr (Timer)

OG_Get_Attr (Window)

OG_Get_Buttonproc

OG_Help

OG_Host

OG_Pause

OG_Print

OG_Quit

OG_Root_Object

OG_Set_Attr (Application)

OG_Set_Attr (Axis)

OG_Set_Attr (Chart Element)

OG_Set_Attr (Display)

OG_Set_Attr (Field Template)

OG_Set_Attr (Frame Template)

OG_Set_Attr (Object)

OG_Set_Attr (Printer)

OG_Set_Attr (Query)

OG_Set_Attr (Reference Line)

OG_Set_Attr (Sound)

OG_Set_Attr (Timer)

OG_Set_Attr (Window)

OG_Translate_Envvar

OG_User_Exit


DO_SQL

  Examples	  Related Topics

Description  This procedure executes the specified SQL statement.

Syntax

PROCEDURE do_sql
  (sql_stmt  VARCHAR2);

Parameters

sql_stmt	Is any valid SQL statement.  This includes either  DML (data manipulation language) or DDL (data definition language) statements.
Usage Notes  Since standard PL/SQL does not allow you to execute DDL statements, use this procedure to execute them, instead.  You can, however, include DML statements in your PL/SQL program units.  In general, DML statements are executed more efficiently within program units than with the DO_SQL procedure.


Do_Sql Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure creates a table from within Graphics Builder:
*/

PROCEDURE create_table(table_name VARCHAR2) IS
BEGIN
  do_sql('create table' || table_name ||
         '  (empno  number(4),' ||
         '   ename  varchar2(10));');
END;


OG_Append_Directory

  Examples	  Related Topics

Description  This function builds a string that specifies a pathname in your file system.

Syntax

FUNCTION OG_Append_Directory
  (dir     VARCHAR2,
   subdir  VARCHAR2)
RETURN VARCHAR2;

Parameters

dir	Is a string specifying the directory to which subdir is appended.  This argument must contain the complete name of a valid directory.
subdir	Is a string specifying a subdirectory that is appended to dir.
Returns  A character string containing the complete directory path.

Usage Notes  You provide the names of the directory and subdirectory, and this function concatenates them using the directory separator that is appropriate for your system.


OG_Append_Directory Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you create a display that is run on several different systems,
**and one function of that display is to import an image from the file
**`my_image'.  Assume the identical directory structure exists on all systems
**on which the display is run; however, each system requires a different
**directory separator.  The following procedure creates a valid directory
**string for each system:
*/

PROCEDURE import_my_image(file_path VARCHAR2) IS
   the_image   OG_Object;
BEGIN
   file_path:=OG_Append_Directory(File_Path, 'home');
   file_path:=OG_Append_Directory(File_Path, 'smith');
   file_path:=OG_Append_Directory(File_Path, 'images');
   file_path:=OG_Append_File(File_Path, 'my_image');
   the_image:=OG_Import_Image(File_Path, OG_Filesystem,
OG_Tiff_Iformat);
END;

 /*Assume the intial value of file_path is `C:\'.  On MS-DOS systems,
**the value of **file_path that is passed to OG_Import_Image is:
**C:\home\smith\images\my_image.
*/

 /*Assume the initial value of file_path is `disk$ic1[]'.  On VMS systems,
**the value of file_path that is passed to OG_Import_Image is:
**disk$ic1:[home.smith.images]my_image.
*/


OG_Append_File

  Examples	  Related Topics

Description  This function builds a string that specifies a file's pathname in your file system.

Syntax

FUNCTION OG_Append_File
  (dir       VARCHAR2,
   filename  VARCHAR2)
RETURN VARCHAR2;

Parameters

dir	Is a string specifying the directory to which filename is appended. This argument must contain the complete name of a valid directory.
filename	Is a string specifying a filename that is appended to dir.
Returns  A character string containing the complete file path.

Usage Notes  You provide the names of the directory and file, and this function concatenates them using the directory separator that is appropriate for your system.


OG_Append_File Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you create a display that is run on several different systems,
**and one function of that display is to import an image from the file `my_image'.
**Assume the identical directory structure exists on all systems on which the display
**is run; however, each system requires a different directory separator.
**The following procedure creates a valid directory string for each system:
*/

PROCEDURE import_my_image(file_path VARCHAR2) IS
   the_image   OG_Object;
BEGIN
   file_path:=OG_Append_Directory(File_Path, 'home');
   file_path:=OG_Append_Directory(File_Path, 'smith');
   file_path:=OG_Append_Directory(File_Path, 'images');
   file_path:=OG_Append_File(File_Path, 'my_image');
   the_image:=OG_Import_Image(File_Path, OG_Filesystem,
     OG_Tiff_Iformat);
END;

 /*Assume the intial value of file_path is `C:\'.  On MS-DOS systems, the value of
**file_path that is passed to OG_Import_Image is:  C:\home\smith\images\my_image.
*/

 /*Assume the initial value of file_path is `disk$ic1[]'.  On VMS systems, the value of
**file_path that is passed to OG_Import_Image is:  disk$ic1:[home.smith.images]my_image.
*/


OG_Center

  Examples	  Related Topics

Description  This procedure redraws the display in the specified window such that the point in the display represented by center_pt appears at the center of the window.

Syntax

PROCEDURE OG_Center
  (window_hdl  OG_Window,
   center_pt   OG_Point);

Parameters

window_hdl	Is the handle to the window.
center_pt	Is the point in the display around which the window should be centered.


OG_Center Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have a chart that you want to appear in the center of a window.
**To do this, you need to get the location and dimensions of the chart's outer
**bounding box, calculate its center point, then use center_pt to place this
**point in the center of the window.
*/

PROCEDURE center_chart (my_window IN og_window, my_chart IN
og_object) IS
   center_point   og_point;
   chart_record   og_chart_ca;
BEGIN
   chart_record.chart_caob.mask:=OG_OBBOX_GENERICA;
   chart_record.chart_caog_mask:=OG_NONE_GROUPA;
   chart_record.chart_caoc_mask:=OG_NONE_CHARTA;
   og_get_attr (my_chart, chart_record);
   center_pt.x:=chart_record.chart_caob.obbox.x +
(chart_record.chart_caob.obbox.width / 2);
   center_pt.y:=chart_record.chart_caob.obbox.y +
(chart_record.chart_caob.obbox.height / 2);
   og_center (my_window, center_point);
END;


OG_Damage (Region)

  Examples	  Related Topics

Description  This procedure damages a rectangular region on the layout.

Syntax

PROCEDURE OG_Damage
  (region  OG_Rectangle);

PROCEDURE OG_Damage
  (region     OG_Rectangle,
   layer_hdl  OG_Layer);

Parameters

region	Is a rectangular region to damaged.
layer_hdl	Is the layer in which the rectangular region is damaged.  If layer_hdl is not specified, the region on all layers are damaged.
Usage Notes  For more information, see "Damage Flag" .


OG_Damage (Region) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure damages a 3"x2"
** area in the upper-left corner of the layout:
*/

PROCEDURE example IS
  damage_region  OG_Rectangle;
BEGIN
  damage_region.x := 0;
  damage_region.y := 0;
  damage_region.width := 3 * OG_Inch;
  damage_region.height := 2 * OG_Inch;

  OG_Damage(Damage_Region);
END;


OG_Get_Attr (Application)

  Examples	  Related Topics

Description

Syntax

PROCEDURE OG_Get_Attr
  (attr  IN OUT  OG_App_Attr);

Parameters

attr	Is the attribute record to be filled with the attributes of the application.
Usage Notes  This procedure gets the attribute values of the currently running Graphics Builder executable.

The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Application) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the number of screen resolution units
**(i.e., pixels) for the current display device:
*/

FUNCTION example RETURN NUMBER IS
  rec  OG_App_Attr;
BEGIN
  rec.mask := OG_Screen_Res_Appa;
  OG_Get_Attr(Rec);
  RETURN(rec.hscreen_res);
END;


OG_Get_Attr (Axis)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified axis.

Syntax

PROCEDURE OG_Get_Attr                        generic
  (axis_hdl  IN      OG_Axis,
   attr      IN OUT  OG_Axis_Attr);

PROCEDURE OG_Get_Attr                        continuous
  (axis_hdl  IN      OG_Axis,
   attr      IN OUT  OG_Contaxis_Ca);

PROCEDURE OG_Get_Attr                        date
  (axis_hdl  IN      OG_Axis,
   attr      IN OUT  OG_Dateaxis_Ca);

PROCEDURE OG_Get_Attr                        discrete
  (axis_hdl  IN      OG_Axis,
   attr      IN OUT  OG_Discaxis_Ca);

Parameters

axis_hdl	Is the handle to the axis whose attributes you want to get.
attr	Is the attribute record to be filled with the attributes of the axis.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Axis) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the custom label for the specified axis:
*/

FUNCTION example(axis OG_Axis) RETURN CHAR IS
  rec  OG_Contaxis_Ca;
BEGIN
  rec.ca_axis.mask := OG_Custlabel_Axisa;
  rec.ca_cont.mask := OG_None_Contaxisa;
  OG_Get_Attr(Axis, rec);
  RETURN(rec.ca_axis.custlabel);
END;


OG_Get_Attr (Display)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the current display.

Syntax

PROCEDURE OG_Get_Attr
  (attr  IN OUT  OG_Display_Attr);

Parameters

attr	Is the attribute record to be filled with the attributes of the display.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Display) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the display width:
*/

FUNCTION example RETURN NUMBER IS
  rec  OG_Display_Attr;
BEGIN
  rec.mask := OG_Size_Displaya;
  OG_Get_Attr(Rec);
  RETURN(rec.width);
END;


OG_Get_Attr (Field Template)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified field template.

Syntax

PROCEDURE OG_Get_Attr                        generic
  (ftemp_hdl  IN      OG_Ftemp,
   attr       IN OUT  OG_Ftemp_Attr);

PROCEDURE OG_Get_Attr                        axis
  (ftemp_hdl  IN      OG_Ftemp,
   attr       IN OUT  OG_Axisftemp_Ca);

Parameters

ftemp_hdl	Is the handle to the field template whose attributes you want to get.
attr	Is the attribute record to be filled with the attributes of the field template.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Field Template) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the number format mask for the specified field template:
*/

FUNCTION example(ftemp OG_Ftemp) RETURN CHAR IS
  rec  OG_Axisftemp_Ca;
BEGIN
  rec.ca_ftemp.mask := OG_Numfmt_Ftempa;
  rec.ca_aftemp.mask := OG_None_Axisftempa;
  OG_Get_Attr(Ftemp, rec);
  RETURN(rec.ca_ftemp.numfmt);
END;


OG_Get_Attr (Frame Template)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified frame template.

Syntax

PROCEDURE OG_Get_Attr                        generic frame
  (template_hdl  IN      OG_Template,
   attr          IN OUT  OG_Frame_Attr);

PROCEDURE OG_Get_Attr                        axis frame
  (template_hdl  IN      OG_Template,
   attr          IN OUT  OG_Axisframe_Ca);

PROCEDURE OG_Get_Attr                        pie frame
  (template_hdl  IN      OG_Template,
   attr          IN OUT  OG_Pieframe_Ca);

PROCEDURE OG_Get_Attr                        table frame
  (template_hdl  IN      OG_Template,
   attr          IN OUT  OG_Tableframe_Ca);

Parameters

template_hdl	Is the handle to the chart template whose frame attributes you want to get.
attr	Is the attribute record to be filled with the attributes of the frame template.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Frame Template) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the depth size for the specified template frame:
*/

FUNCTION example(temp OG_Template) RETURN NUMBER IS
  rec  OG_Axisframe_Ca;
BEGIN
  rec.ca_frame.mask := OG_Depthsize_Framea;
  rec.ca_axis.mask := OG_None_Framea;
  OG_Get_Attr(Temp, rec);
  RETURN(rec.ca_frame.depthsize);
END;


OG_Get_Attr (Object)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified object.

Syntax

PROCEDURE OG_Get_Attr                        arc
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Arc_Ca);

PROCEDURE OG_Get_Attr                        chart
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Chart_Ca);

PROCEDURE OG_Get_Attr                        generic
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Generic_Attr);

PROCEDURE OG_Get_Attr                        graphic
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Graphic_Ca);

PROCEDURE OG_Get_Attr                        group
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Group_Ca);

PROCEDURE OG_Get_Attr                        image
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Image_Ca);

PROCEDURE OG_Get_Attr                        line
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Line_Ca);

PROCEDURE OG_Get_Attr                        polygon/polyline
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Poly_Ca);

PROCEDURE OG_Get_Attr                        rectangle
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Rect_Ca);

PROCEDURE OG_Get_Attr                        rounded rectangle
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Rrect_Ca);

PROCEDURE OG_Get_Attr                        symbol
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Symbol_Ca);

PROCEDURE OG_Get_Attr                        text/text field
  (object_hdl  IN      OG_Object,
   attr        IN OUT  OG_Text_Ca);

Parameters

object_hdl	Is the handle to the object whose attributes you want to get.
attr	Is the attribute record to be filled with the attributes of the object.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Object) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose the user selects an object whose color determines what information
**the user is interested in viewing.  The following function will take an object
**as its **argument and return the name of its foreground fill color.  The color
**can then be determined, and the appropriate information displayed.
*/

FUNCTION get_color(the_object IN OG_Object) RETURN VARCHAR2
IS
   obj_record   OG_Graphic_Ca;
BEGIN
   obj_record.graphic_caoh.mask:=OG_Ffcolor_Graphica;
   obj_record.generic_caob.mask:=OG_None_Generica;
   OG_Get_Attr(The_Object, obj_record);
   RETURN(obj_record.graphic_caoh.ffcolor);
END;


OG_Get_Attr (Printer)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the current printer..

Syntax

PROCEDURE OG_Get_Attr
  (attr  IN OUT  OG_Printer_Attr);

Parameters

attr	Is the attribute record to be filled with the attributes of the printer.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Printer) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the name of the current printer:
*/

FUNCTION example RETURN CHAR IS
  rec  OG_Printer_Attr;
BEGIN
  rec.mask := OG_Name_Printera;
  OG_Get_Attr(Rec);
  RETURN(rec.name);
END;


OG_Get_Attr (Query)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified query.

Syntax

PROCEDURE OG_Get_Attr
  (query_hdl  IN      OG_Query,
   attr       IN OUT  OG_Query_Attr);

Parameters

query_hdl	Is the handle to the query whose attributes you want to get.
attr	Is the attribute record to be filled with the attributes of the query.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Query) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the SQL statement that defines the specified query:
*/

FUNCTION example(query OG_Query) RETURN CHAR IS
  rec  OG_Query_Attr;
BEGIN
  rec.mask := OG_Querysource_Querya;
  OG_Get_Attr(Query, rec);
  RETURN(rec.querysource);
END;


OG_Get_Attr (Reference Line)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified reference line.

Syntax

PROCEDURE OG_Get_Attr
  (refline_hdl  IN      OG_Refline,
   attr         IN OUT  OG_Refline_Attr);

Parameters

refline_hdl	Is the handle to the reference line whose attributes you want to get.
attr	Is the attribute record to be filled with the attributes of the reference line.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Reference Line) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the label for the specified reference line.
*/

FUNCTION example(refline OG_Refline) RETURN CHAR IS
  rec  OG_Refline_Attr;
BEGIN
  rec.mask := OG_Label_Reflinea;
  OG_Get_Attr(Refline, rec);
  RETURN(rec.label);
END;


OG_Get_Attr (Sound)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified sound.

Syntax

PROCEDURE OG_Get_Attr
  (sound_hdl  IN      OG_Sound,
   attr       IN OUT  OG_Sound_Attr);

Parameters

sound_hdl	Is the handle to the sound whose attributes you want to get.
attr	Is the attribute record to be filled with the attributes of the sound.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Sound) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the name of the specified sound:
*/

FUNCTION example(sound OG_Sound) RETURN CHAR IS
  rec  OG_Sound_Attr;
BEGIN
  rec.mask := OG_Name_Sounda;
  OG_Get_Attr(Sound, rec);
  RETURN(rec.name);
END;


OG_Get_Attr (Timer)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified timer.

Syntax

PROCEDURE OG_Get_Attr
  (timer_hdl  IN      OG_Timer,
   attr       IN OUT  OG_Timer_Attr);

Parameters

timer_hdl	Is the handle to the timer whose attributes you want to get.
attr	Is the attribute record to be filled with the attributes of the timer.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Timer) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the procedure name assigned to the specified timer:
*/

FUNCTION example(timer OG_Timer) RETURN CHAR IS
  rec  OG_Timer_Attr;
BEGIN
  rec.mask := OG_Timerproc_Timera;
  OG_Get_Attr(Timer, rec);
  RETURN(rec.timerproc);
END;


OG_Get_Attr (Window)

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified window.

Syntax

PROCEDURE OG_Get_Attr
  (window_hdl  IN      OG_Window,
   attr        IN OUT  OG_Window_Attr);

Parameters

window_hdl	Is the handle to the window whose attributes you want to get.
attr	Is the attribute record to be filled with the attributes of the window.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Get_Attr (Window) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function returns the specified window's position:
*/

FUNCTION example(window OG_Window) RETURN OG_Point IS
  rec  OG_Window_Attr;
BEGIN
  rec.mask := OG_Position_Windowa;
  OG_Get_Attr(Window, rec);
  RETURN(rec.position);
END;


OG_Get_Buttonproc

  Examples	  Related Topics

Description  The button procedure must already be defined, and not exist in any PL/SQL package.

Syntax

FUNCTION OG_Get_Buttonproc
  (proc_name  VARCHAR2)
RETURN OG_Buttonproc;

Parameters

proc_name	Is the name of the PL/SQL button procedure whose handle should be returned.
Returns  A handle to the specified button procedure.  If the specified button procedure does not exist, this function will return a null handle.


OG_Get_Buttonproc Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have written a button procedure named `show_sales_data'
**and you want to assign that procedure to an object; then, when the user
**selects the object, the procedure will be executed.
*/

PROCEDURE make_object_button(my_obj IN OG_Object) IS
   obj_rec         OG_Generic_Attr;
   my_buttonproc   OG_Buttonproc;
BEGIN
   my_buttonproc:=OG_Get_Buttonproc('Show_Sales_Data');
   obj_rec.mask:=OG_Button_Generica;
   obj_rec.button:=my_buttonproc;
   obj_rec.events:=OG_Mouse_Down;
   OG_Set_Attr(My_Obj, obj_rec);
END;


OG_Help

  Examples	  Related Topics

Description  This procedure invokes the Help system and shows the runtime Help document at the specified hypertext target.

Syntax

PROCEDURE OG_Help
  (target  VARCHAR2);

Parameters

target	Is the hypertext target in the runtime Help document that is displayed.


OG_Help Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want the user to be able to select a button and invoke
**the Help system.  You could write the following button procedure:
*/

PROCEDURE get_help (buttonobj IN OG_Object, hitobj IN
OG_Object, win IN OG_Window, eventinfo IN OG_Event) IS
BEGIN
   IF eventinfo.event_type=OG_Mouse_Up THEN
      OG_Help('Topic_1');
   END IF;
END;


OG_Host

  Examples	  Related Topics

Description  This procedure passes the specified command to the operating system.

Syntax

PROCEDURE OG_Host
  (command  VARCHAR2);

Parameters

command	Is a text string containing the command to execute.


OG_Host Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to be notified via electronic mail when a user closes a display.
**You could create a script named `mail_me' in your file system that sends you mail,
**and then invoke it with the following Close Display trigger:
*/

PROCEDURE send_me_mail IS
BEGIN
   OG_Host('Mail_Me');
END;


OG_Pause

  Examples	  Related Topics

Description  This procedure suspends the execution of the display for the specified number of seconds.

Syntax

PROCEDURE OG_Pause
  (secs  NUMBER);

Parameters

secs	Is the number of seconds to pause.


OG_Pause Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure suspends display execution for seven seconds:
*/

PROCEDURE example IS
BEGIN
  OG_Pause(7);
END;


OG_Print

  Examples	  Related Topics

Description  This procedure prints the contents of the layout to the currently selected print device.

Syntax

PROCEDURE OG_Print;

PROCEDURE OG_Print
  (window_hdl  OG_Window);

Parameters

window_hdl	Is the handle to the window to be printed.
Usage Notes  If a window handle is specified, only the layers showing in that window are printed; otherwise, all layers in the display are printed, regardless of what window they are in or whether they are showing or hidden.


OG_Print Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to print the contents of the main layout window.
*/

PROCEDURE print_main_window IS
   the_window   OG_Window;
BEGIN
   the_window:=OG_Get_Window('Main Layout');
   OG_Print(The_Window);
END;


OG_Quit

  Examples	  Related Topics

Description  This procedure quits the current Graphics Builder session.

Syntax

PROCEDURE OG_Quit;

Parameters:

None.


OG_Quit Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to provide the user with a button that-when selected
**commits database changes and quits Graphics Builder.  You could write the
**following button procedure:
*/

PROCEDURE commit_and_quit (hitobj IN OG_Object, buttonobj
  IN OG_Object, win IN OG_Window, eventinfo IN OG_Event) IS
BEGIN
   COMMIT;
   OG_Quit;
END;


OG_Root_Object

  Examples	  Related Topics

Description  This function returns a handle to the display's root object.

Syntax

FUNCTION OG_Root_Object
RETURN OG_Object;

Parameters:

None.

Returns  A handle to the display's root object.

Usage Notes  The root object is the topmost object in the display.  Its immediate children are the display's layers.


OG_Root_Object Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure moves the topmost layer in the display to the bottom of the layer list:
*/

PROCEDURE example IS
  root   OG_Object;
  layer  OG_Object;
BEGIN
  root := OG_Root_Object;
  layer := OG_Get_Child(Root, 0);
  OG_Insert_Child(Root, layer, OG_Last);
END;


OG_Set_Attr (Application)

  Examples	  Related Topics

Description  This procedure sets the attributes of the currently running Graphics Builder executable.

Syntax

PROCEDURE OG_Set_Attr
  (attr  OG_App_Attr);

Parameters

attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Application) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the cursor to 'busy':
*/

PROCEDURE example IS
  attr  OG_App_Attr;
BEGIN
  attr.cursor := 'busy';
  attr.mask := OG_Cursor_Appa;
  OG_Set_Attr(Attr);
END;


OG_Set_Attr (Axis)

  Examples	  Related Topics

Description  This procedure sets the attribute values of the specified axis.

Syntax

PROCEDURE OG_Set_Attr                        generic
  (axis_hdl  OG_Axis,
   attr      OG_Axis_Attr);

PROCEDURE OG_Set_Attr                        continuous
  (axis_hdl  OG_Axis,
   attr      OG_Contaxis_Ca);

PROCEDURE OG_Set_Attr                        date
  (axis_hdl  OG_Axis,
   attr      OG_Dateaxis_Ca);

PROCEDURE OG_Set_Attr                        discrete
  (axis_hdl  OG_Axis,
   attr      OG_Discaxis_Ca);

Parameters

axis_hdl	Is the handle to the axis whose attributes you want to set.
attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Axis) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the custom label for the specified axis:
*/

PROCEDURE example(axis OG_Axis, label VARCHAR2) IS
  rec  OG_Contaxis_Ca;
BEGIN
  rec.ca_axis.custlabel := 'New Label';
  rec.ca_axis.mask := OG_Custlabel_Axisa;
  rec.ca_cont.mask := OG_None_Contaxisa;
  OG_Set_Attr(Axis, rec);
END;


OG_Set_Attr (Chart Element)

  Examples	  Related Topics

Description  This procedure sets the attributes of a chart element, such as a bar or pie slice.

Syntax

PROCEDURE OG_Set_Attr
  (chart_hdl  OG_Object,
   row_num    NUMBER,
   col_name   VARCHAR2,
   attr       OG_Chelement_Ca);

Parameters

chart_hdl	Is the handle to the chart containing the data value whose attributes you want to set.
row_num	Is the row number of the data value whose attributes you want to set.
col_name	Is the column name of the data value whose attributes you want to set.
attr	Is the attribute record containing the new attribute values.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  You must specify the chart, row, and column of the corresponding data value, as well as a chart set attribute record.  The attribute record contains graphical and other attributes that will be applied to the chart element that represents the specified data value.  For example, you can set the color of a bar in a bar chart by specifying an attribute record for the data value that corresponds to that bar.

Note that any changes made to a chart element will not be applied until the chart is updated via a call to OG_Update_Chart.

The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Chart Element) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure loops through all rows in a chart's query,
**and then sets the color of each bar in the chart based on its value:
*/

PROCEDURE OGTRIGGERPROC0 IS
chart og_object;
query og_query;
rec og_chelement_ca;
total number;
bar_val number;

BEGIN
  chart := og_get_object ('Employees');
  query:= og_get_query ('query0');
  og_execute_query (query);
  og_start_from(query, OG_NEWDATA);
  total := og_numrows (query, OG_NEWDATA);
for i in 0..total-1 loop
  bar_val:=og_get_numcell (query, OG_NEWDATA,'SAL');
   IF bar_val>2000 THEN^M
   rec.chelement_cagr.mask :=OG_BFCOLOR_GRAPHICA;
   rec.chelement_cace.mask :=OG_NONE_CHELEMENTA;
   rec.chelement_cagr.bfcolor := 'cyan';
og_set_attr (chart, i, 'SAL', rec);
   END; IF;
  og_next_row(query, OG_NEWDATA);
 END LOOP;
 og_update_chart (chart, OG_ALL_CHUPDA);
END;


OG_Set_Attr (Display)

  Examples	  Related Topics

Description  This procedure sets the attributes of the current display.

Syntax

PROCEDURE OG_Set_Attr
  (attr  OG_Display_Attr);

Parameters

attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Display) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the display width:
*/

PROCEDURE example IS
  rec  OG_Display_Attr;
BEGIN
  rec.width := 4 * OG_Inch;
  rec.height := 5 * OG_Inch;
  rec.mask := OG_Size_Displaya;
  OG_Set_Attr(Rec);
END;


OG_Set_Attr (Field Template)

  Examples	  Related Topics

Description  This procedure sets the attribute values of the specified field template.

Syntax

PROCEDURE OG_Set_Attr                        generic
  (ftemp_hdl  OG_Ftemp,
   attr       OG_Ftemp_Attr);

PROCEDURE OG_Set_Attr                        axis
  (ftemp_hdl  OG_Ftemp,
   attr       OG_Axisftemp_Ca);

Parameters

ftemp_hdl	Is the handle to the field template whose attributes you want to set.
attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Field Template) Examples

  Alphabetic List           [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the number format mask for the specified field template:
*/

PROCEDURE example(ftemp OG_Ftemp) IS
  rec  OG_Axisftemp_Ca;
BEGIN
  rec.ca_ftemp.numfmt := '9,990';
  rec.ca_ftemp.mask := OG_Numfmt_Ftempa;
  rec.ca_aftemp.mask := OG_None_Axisftempa;
  OG_Set_Attr(Ftemp, rec);
END;


OG_Set_Attr (Frame Template)

  Examples	  Related Topics

Description  This procedure sets the attribute values of the specified frame template.

Syntax

PROCEDURE OG_Set_Attr                        generic frame
  (template_hdl  OG_Template,
   attr          OG_Frame_Attr);

PROCEDURE OG_Set_Attr                        axis frame
  (template_hdl  OG_Template,
   attr          OG_Axisframe_Ca);

PROCEDURE OG_Set_Attr                        pie frame
  (template_hdl  OG_Template,
   attr          OG_Pieframe_Ca);

PROCEDURE OG_Set_Attr                        table frame
  (template_hdl  OG_Template,
   attr          OG_Tableframe_Ca);

Parameters

template_hdl	Is the handle to the chart template whose frame attributes you want to set.
attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Frame Template) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the depth size for the specified template frame:
*/

PROCEDURE example(temp OG_Template) IS
  rec  OG_Axisframe_Ca;
BEGIN
  rec.ca_frame.depthsize := OG_Large_Depthsize;
  rec.ca_frame.mask := OG_Depthsize_Framea;
  rec.ca_axis.mask := OG_None_Framea;
  OG_Set_Attr(Temp, rec);
END;


OG_Set_Attr (Object)

  Examples	  Related Topics

Description  This procedure sets the attributes of the specified object.

Syntax

PROCEDURE OG_Set_Attr                        arc
  (object_hdl   OG_Object,
   attr         OG_Arc_Ca,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

PROCEDURE OG_Set_Attr                        chart
  (object_hdl   OG_Object,
   attr         OG_Chart_Ca,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

PROCEDURE OG_Set_Attr                        generic
  (object_hdl   OG_Object,
   attr         OG_Generic_Attr,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

PROCEDURE OG_Set_Attr                        graphic
  (object_hdl   OG_Object,
   attr         OG_Graphic_Ca,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

PROCEDURE OG_Set_Attr                        group
  (object_hdl   OG_Object,
   attr         OG_Group_Ca,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

PROCEDURE OG_Set_Attr                        image
  (object_hdl   OG_Object,
   attr         OG_Image_Ca,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

PROCEDURE OG_Set_Attr                        line
  (object_hdl   OG_Object,
   attr         OG_Line_Ca,
   damage       BOOLEAN          := TRUE,
   update_bbox  BOOLEAN          := TRUE);

PROCEDURE OG_Set_Attr                        polygon/polyline
  (object_hdl   OG_Object,
   attr         OG_Poly_Ca,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

PROCEDURE OG_Set_Attr                        rectangle
  (object_hdl   OG_Object,
   attr         OG_Rect_Ca,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

PROCEDURE OG_Set_Attr                        rounded rectangle
  (object_hdl   OG_Object,
   attr         OG_Rrect_Ca,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

PROCEDURE OG_Set_Attr                        symbol
  (object_hdl   OG_Object,
   attr         OG_Symbol_Ca,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

PROCEDURE OG_Set_Attr                        text/text field
  (object_hdl   OG_Object,
   attr         OG_Text_Ca,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

Parameters

object_hdl	Is the handle to the object whose attributes you want to set.
attr	Is the attribute record containing the new attribute values.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Object) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have a map of the world and you want to change the
**color of one of the countries.  First, you would get the handle to the
**country object, then you would change its color.
*/

PROCEDURE color_country (country_name) IS
   my_object    OG_Object;
   obj_record   OG_Graphic_Ca;
BEGIN
   my_object:=OG_Get_Object(Country_Name);
   obj_record.graphic_caob.mask:=OG_None_Generica;
   obj_record.graphic_caoh.mask:=OG_Ffcolor_Graphica;
   obj_record.graphic_caoh.ffcolor:='red';
   OG_Set_Attr(My_Object, obj_record);
END;


OG_Set_Attr (Printer)

  Examples	  Related Topics

Description  This procedure sets the attribute values of the current printer..

Syntax

PROCEDURE OG_Set_Attr
  (attr  OG_Printer_Attr);

Parameters

attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Printer) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure tells sets the number of copies to print:
*/

PROCEDURE example IS
  rec  OG_Printer_Attr;
BEGIN
  rec.copies := 2;
  rec.mask := OG_Copies_Printera;
  OG_Set_Attr(Rec);
END;


OG_Set_Attr (Query)

  Examples	  Related Topics

Description  This procedure sets the attributes of the specified query.

Syntax

PROCEDURE OG_Set_Attr
  (query_hdl  OG_Query,
   attr       OG_Query_Attr);

Parameters

query_hdl	Is the handle to the query whose attributes you want to set.
attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Query) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the SQL statement that defines the specified query:
*/

PROCEDURE example(query OG_Query) IS
  rec  OG_Query_Attr;
BEGIN
  rec.querysource := 'select ename, sal from emp';
  rec.mask := OG_Querysource_Querya;
  OG_Set_Attr(Query, rec);
END;


OG_Set_Attr (Reference Line)

  Examples	  Related Topics

Description  This procedure sets the attributes of the specified reference line.

Syntax

PROCEDURE OG_Set_Attr
  (refline_hdl  OG_Refline,
   attr         OG_Refline_Attr);

Parameters

refline_hdl	Is the handle to the reference line whose attributes you want to Set.
attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Reference Line) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the label for the specified reference line.
*/

PROCEDURE example(refline OG_Refline) IS
  rec  OG_Refline_Attr;
BEGIN
  rec.label := 'Average';
  rec.mask := OG_Label_Reflinea;
  OG_Set_Attr(Refline, rec);
END;


OG_Set_Attr (Sound)

  Examples	  Related Topics

Description  This procedure sets the attributes of the specified sound.

Syntax

PROCEDURE OG_Set_Attr
  (sound_hdl  OG_Sound,
   attr       OG_Sound_Attr);

Parameters

sound_hdl	Is the handle to the sound whose attributes you want to set.
attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Sound) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the name of the specified sound:
*/

PROCEDURE example(sound OG_Sound) IS
  rec  OG_Sound_Attr;
BEGIN
  rec.name := 'Alert';
  rec.mask := OG_Name_Sounda;
  OG_Set_Attr(Sound, rec);
END;


OG_Set_Attr (Timer)

  Examples	  Related Topics

Description  This procedure sets the attributes of the specified timer.

Syntax

PROCEDURE OG_Set_Attr
  (timer_hdl  OG_Timer,
   attr       OG_Timer_Attr);

Parameters

timer_hdl	Is the handle to the timer whose attributes you want to set.
attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Timer) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the procedure name assigned to the specified timer:
*/

PROCEDURE example(timer OG_Timer) IS
  rec  OG_Timer_Attr;
BEGIN
  rec.timerproc := 'update_proc';
  rec.mask := OG_Timerproc_Timera;
  OG_Set_Attr(Timer, rec);
END;


OG_Set_Attr (Window)

  Examples	  Related Topics

Description  This procedure sets the attributes of the specified window.

Syntax

PROCEDURE OG_Set_Attr
  (window_hdl  OG_Window,
   attr        OG_Window_Attr);

Parameters

window_hdl	Is the handle to the window whose attributes you want to set.
attr	Is the attribute record containing the new attribute values.
Usage Notes  The only attribute values that will be set are those specified by the value of the mask attribute(s) in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to this procedure.


OG_Set_Attr (Window) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the specified window's size:
*/

PROCEDURE example(window OG_Window) IS
  rec  OG_Window_Attr;
BEGIN
  rec.width := 4 * OG_Get_Ap_Hscreen_Res;
  rec.height := 5 * OG_Get_Ap_Vscreen_Res;
  rec.mask := OG_Size_Windowa;
  OG_Set_Attr(Window, rec);
END;


OG_Translate_Envvar

  Examples	  Related Topics

Description  This function returns the value of the specified environment variable.

Syntax

FUNCTION OG_Translate_Envvar
  (envvar  VARCHAR2)
RETURN VARCHAR2;

Parameters

envvar	Is the environment variable to translate.
Returns  A character string containing the value of the environment variable.

Usage Notes  The treatment (and even the existence) of environment variables is system-specific.  For more information, see the Graphics Builder documentation for your operating system.

When searching for the environment variable, Graphics Builder first checks your operating system to see if it defined.  If not, it looks in your preferences file.


OG_Translate_Envvar Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose your system has an environment variable named IMAGE_DIR
**that specifies the directory path of the image file `my_image'.  The following
**procedure imports that image:
*/

PROCEDURE import_my_image IS
   the_image   OG_Object;
   file_path   VARCHAR2(50);
BEGIN
   file_path:=OG_Translate_Envvar('Image_Dir');
   file_path:=OG_Append_File(File_Path, 'my_image');
   the_image:=OG_Import_Image(File_Path, OG_Filesystem,
     OG_Tiff_Iformat);
END;


OG_User_Exit

  Examples	  Related Topics

Description  This procedure runs a user-defined executable.

Syntax

PROCEDURE OG_User_Exit
  (command  VARCHAR2);

Parameters

command	Is the name of the user exit, along with any arguments you wish to pass it.


OG_User_Exit Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose your display controls the operation of hardware
**components connected to your system.  When the user selects
**a button, you may want to invoke the hardware controller
**routine, which you have linked in as a user exit.  In addition,
**you may want to pass an argument to this user exit.  The following
**procedure invokes the user exit `hw_ctrl' with the parameter `signal':
*/

PROCEDURE control_hw(buttonobj IN OG_Object, hitobj IN OG_Object, win IN OG_Window, eventinfo IN OG_Event) IS
BEGIN
   OG_User_Exit('Hw_Ctrl' || :signal);
END;


Type Caption for New Topic Right Here
No built-in subprograms begin with this letter.


Parameter Built-ins

OG_Delete_Param

OG_Get_Char_Param

OG_Get_Date_Param

OG_Get_Num_Param

OG_Get_Param_Type

OG_Param_Exists

OG_Set_Param


OG_Delete_Param

  Examples	  Related Topics

Description  This procedure deletes the specified parameter.

Syntax

PROCEDURE OG_Delete_Param
  (param_name  VARCHAR2);

Parameters

param_name	Is the name of the parameter to delete.


OG_Delete_Param Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure deletes the parameter 'param0':
*/

PROCEDURE example IS
BEGIN
  OG_Delete_Parameter('Param0');
END;


OG_Get_Char_Param

  Examples	  Related Topics

Description  This function gets the value of the specified CHAR parameter.  It is equivalent to using a bind reference to the parameter.

Syntax

FUNCTION OG_Get_Char_Param
  (param_name  VARCHAR2)
RETURN VARCHAR2;

Parameters

param_name	Is the name of the parameter whose value you want to get.
Returns  The value of the specified parameter.

Usage Notes  This function is useful when you want to reference the parameter within a program unit that is in a library.  Bind references do not compile within the context of a library; however, this function does.


OG_Get_Char_Param Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure gets the value of the parameter 'status',
**and changes the color of the specified object based on its value:
*/

PROCEDURE example(object OG_Object) IS
  stat  VARCHAR2(10);
BEGIN
  stat := OG_Get_Char_Param('Status');
  IF stat = 'obsolete' THEN
    OG_Set_Fillcolor(Object, 'red');
  END IF;
END;


OG_Get_Date_Param

  Examples	  Related Topics

Description  This function gets the value of the specified DATE parameter.  It is equivalent to using using a bind reference to the parameter.

Syntax

FUNCTION OG_Get_Date_Param
  (param_name  VARCHAR2,
   fmt         VARCHAR2)
RETURN DATE;

Parameters

param_name	Is the name of the parameter whose value you want to get.
Returns  The value of the specified parameter.

Usage Notes  This function is useful when you want to reference the parameter within a program unit that is in a library.  Bind references do not compile within the context of a library; however, this function does.


OG_Get_Date_Param Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure gets the value of the parameter 'due_date',
**and changes the color of the specified object based on its value:
*/

PROCEDURE example(object OG_Object) IS
  due  DATE;
BEGIN
  due := OG_Get_Date_Param('Due_Date');
  IF due < sysdate THEN
    OG_Set_Fillcolor(Object, 'red');
  END IF;
END;


OG_Get_Num_Param

  Examples	  Related Topics

Description  This function gets the value of the specified NUMBER parameter.  It is equivalent to using using a bind reference to the parameter.

Syntax

FUNCTION OG_Get_Num_Param
  (param_name  VARCHAR2)
RETURN NUMBER;

Parameters

param_name	Is the name of the parameter whose value you want to get.
Returns  The value of the specified parameter.

Usage Notes  This function is useful when you want to reference the parameter within a program unit that is in a library.  Bind references do not compile within the context of a library; however, this function does.


OG_Get_Num_Param Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure gets the value of the parameter 'priority', and increases it by 1:
*/

PROCEDURE example IS
  val  NUMBER;
BEGIN
  val := OG_Get_Num_Param('Priority');
  OG_Set_Param('Priority', val + 1);
END;


OG_Get_Param_Type

  Examples	  Related Topics

Description  This function returns the datatype of a parameter.

Syntax

FUNCTION OG_Get_Param_Type
  (param_name  VARCHAR2)
RETURN NUMBER;

Parameters

param_name	Is the name of the parameter.
Returns  This function returns one of the following built-in constants:

•	OG_Char_Paramtype

•	OG_Date_Paramtype

•	OG_Num_Paramtype


OG_Get_Param_Type Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure retrieves the datatype of the parameter 'param0',
**then increases it by one if the type is NUMBER:
*/

PROCEDURE example IS
  dtype  NUMBER;
BEGIN
  dtype := OG_Get_Param_Type('Param0');
  IF dtype = OG_Num_Paramtype THEN
    :param0 := :param0 + 1;
  END IF;
END;


OG_Param_Exists

  Examples	  Related Topics

Description  This function determines whether a parameter has been created.

Syntax

FUNCTION OG_Param_Exists
  (param_name  VARCHAR2)
RETURN BOOLEAN;

Parameters

param_name	Is the name of the parameter.
Returns TRUE	If the parameter exists.
FALSE	If the parameter does not exist.


OG_Param_Exists Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure assigns drill-down behavior to a chart, but first verifies
**that the parameter it sets exists (and creates it if it doesn't exist):
*/

PROCEDURE example(chart OG_Object, param_name VARCHAR2) IS
  chelement_group  OG_Object;
BEGIN
  IF NOT OG_Param_Exists(Param_Name) THEN
    OG_Set_Param(Param_Name, 10);
  END IF;

  chelement_group := OG_Get_Object('Sal_Bars', chart);
  OG_Set_Setparam(Chelement_Group, param_name);
  OG_Set_Keycol(Chelement_Group, 'DEPTNO');
END;


OG_Set_Param

  Examples	  Related Topics

Description  This procedure sets the value of the specified parameter.  If the parameter does not exist, it will be created.

Syntax

PROCEDURE OG_Set_Param                       date
  (param_name    VARCHAR2,
   param_value   DATE,
   param_format  VARCHAR2  :=  'DD-MON-YY');

PROCEDURE OG_Set_Param                       number
  (param_name   VARCHAR2,
   param_value  NUMBER);

PROCEDURE OG_Set_Param                       char
  (param_name   VARCHAR2,
   param_value  VARCHAR2);

Parameters

param_name	Is the name of the parameter whose value you want to set.
param_value	Is the value to which the parameter will be set.
param_format	Is the format mask used to interpret param_value for date parameters.
Usage Notes  This procedure is useful when you want to reference the parameter within a program unit that is in a library.  Bind references do not compile within the context of a library; however, this procedure does.


OG_Set_Param Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure gets the value of the parameter
**'priority', and increases it by 1:
*/

PROCEDURE example IS
  val  NUMBER;
BEGIN
  val := OG_Get_Num_Param('Priority');
  OG_Set_Param('Priority', val + 1);
END;


Query Built-ins

OG_Append_Row

OG_Clear_Query

OG_Data_Changed

OG_Data_Queried

OG_Destroy (Query)

OG_Execute_Query

OG_Get_Charcell

OG_Get_Datecell

OG_Get_Newrows

OG_Get_Numcell

OG_Get_Query

OG_Get_Schema

OG_Insert_Column

OG_Make_Query

OG_Next_Row

OG_Numcols

OG_Numrows

OG_Set_Charcell

OG_Set_Datecell

OG_Set_Numcell

OG_Set_Schema

OG_Start_From


OG_Append_Row

  Examples	  Related Topics

Description  This procedure adds the current row buffer to the bottom of a custom query.

Syntax

PROCEDURE OG_Append_Row
  (query_hdl  OG_Query);

Parameters

query_hdl	Is the handle to the query to which the row buffer is appended.
Usage Notes  Specify the contents of the row buffer using OG_Set_Charcell, OG_Set_Datecell, and OG_Set_Numcell.


OG_Append_Row Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to create a custom query using the ENAME, SAL, and
**HIREDATE columns in the existing query 'query0' as a basis.  However, in the
**new query, you want to double every SAL value.  The following procedure
**is a custom query procedure you could use:
*/

PROCEDURE OGQUERYPROC0(query IN OG_Query) IS
  other_ename     VARCHAR2(10);
  other_sal       NUMBER(7,2);
  other_query     OG_Query;
  other_hiredate  DATE;
  row_count       NUMBER;
BEGIN
  OG_Clear_Query(Query);

  other_query := OG_Get_Query('Query0');
  row_count := OG_Numrows(Other_Query, OG_Newdata);
  OG_Start_From(Other_Query, OG_Newdata, 0);

  FOR i IN 0..row_count loop
    other_ename := OG_Get_Charcell(Other_Query, 'ENAME');
    other_sal := OG_Get_Numcell(Other_Query, 'SAL');
    other_hiredate := OG_Get_Numcell(Other_Query, 'HIREDATE');
    OG_Set_Charcell(Query, 'ENAME', other_ename);
    OG_Set_Numcell(Query, 'SAL', other_sal * 2);
    OG_Set_Datecell(Query, 'HIREDATE', other_hiredate);
    OG_Append_Row(Query);
    OG_Next_Row(Other_Query, OG_Newdata);
  END LOOP;

END;


OG_Clear_Query

  Examples	  Related Topics

Description  This procedure removes all rows of data from the specified query.

Syntax

PROCEDURE OG_Clear_Query
  (query_hdl  OG_Query);

Parameters

query_hdl	Is the handle to the query to clear..


OG_Clear_Query Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to create a custom query using the ENAME, SAL, and
**HIREDATE columns in the existing query 'query0' as a basis.  However, in the
**new query, you want to double every SAL value.  The following procedure
**is a custom query procedure you could use:
*/

PROCEDURE OGQUERYPROC0(query IN OG_Query) IS
  other_ename     VARCHAR2(10);
  other_sal       NUMBER(7,2);
  other_query     OG_Query;
  other_hiredate  DATE;
  row_count       NUMBER;
BEGIN
  OG_Clear_Query(Query);

  other_query := OG_Get_Query('Query0');
  row_count := OG_Numrows(Other_Query, OG_Newdata);
  OG_Start_From(Other_Query, OG_Newdata, 0);

  FOR i IN 0..row_count loop
    other_ename := OG_Get_Charcell(Other_Query, 'ENAME');
    other_sal := OG_Get_Numcell(Other_Query, 'SAL');
    other_hiredate := OG_Get_Numcell(Other_Query, 'HIREDATE');
    OG_Set_Charcell(Query, 'ENAME', other_ename);
    OG_Set_Numcell(Query, 'SAL', other_sal * 2);
    OG_Set_Datecell(Query, 'HIREDATE', other_hiredate);
    OG_Append_Row(Query);
    OG_Next_Row(Other_Query, OG_Newdata);
  END LOOP;

END;


OG_Data_Changed

  Examples	  Related Topics

Description  This function compares the old data and new data resulting from the most recent call to OG_Execute_Query for the specified query.  It returns TRUE if the data sets differ, and FALSE if they do not.

Syntax

FUNCTION OG_Data_Changed
  (query_hdl  OG_Query)
RETURN BOOLEAN;

Parameters

query_hdl	Is the handle to the query.
Returns TRUE	If the data has changed.
FALSE	If the data has not changed.
Usage Notes  This function compares the following for the old and new data, stopping as soon as a discrepancy is detected:

1	the number of rows returned

2	the query's schema

3	a cell-by-cell comparison of data (note that this comparison can be time-consuming for large sets of data)


OG_Data_Changed Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to update a chart periodically, but only if the
**data has changed.  You could write the following timer trigger:
*/

PROCEDURE my_timer IS
   my_query   OG_Query;
   my_chart   OG_Object;
BEGIN
   my_query:=OG_Get_Query('Emp_Query');
   OG_Execute_Query(My_Query);
   IF OG_Data_Changed(My_Query) THEN
      my_chart:=OG_Get_Object('Emp_Chart');
      OG_Update_Chart(My_Chart, OG_All_Chupda);
   END IF;
END;


OG_Data_Queried

  Examples	  Related Topics

Description  This function determines if the specified data category was queried by the most recent call to OG_Execute_Query for the specified query.

Syntax

FUNCTION OG_Data_Queried
  (query_hdl   OG_Query,
   which_data  NUMBER)
RETURN BOOLEAN;

Parameters

query_hdl	Is the handle to the query.
which_data	Specifies whether the status of the old data or the new data should be checked.  Graphics Builder provides two built-in numeric constants that may be used as values for this argument: OG_Newdata and OG_Olddata.
Returns TRUE	If the data has queried.
FALSE	If the data has not been queried.
Usage Notes  If the query has not been executed by OG_Execute_Query, neither data category will have been queried, and this function will return FALSE.  If the query has been executed exactly once, this function will return TRUE for the new data and FALSE for the old.  If the query has been executed more than once, this function will always return TRUE.


OG_Data_Queried Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to use OG_Data_Changed to check if a query's
**data has changed, and then update a chart that uses that query.
**Before you do so, you may want to make sure that both the old and
**new data for the query have been queried.
*/

PROCEDURE check_and_update IS
   my_query   OG_Query;
   my_chart   OG_Object;
BEGIN
   my_query:=OG_Get_Query('Sales Query');
   IF OG_Data_Queried(My_Query, OG_Olddata) AND
OG_Data_Queried(My_Query, OG_Newdata) THEN
      IF data_changed(my_query) THEN
         my_chart:=OG_Get_Object('Sales Chart');
         OG_Update_Chart(My_Chart, OG_All_Chupda);
      END IF;
   END IF;
END;


OG_Destroy (Query)

  Examples	  Related Topics

Description  This procedure destroys the specified query.

Syntax

PROCEDURE OG_Destroy
  (query_hdl  OG_Query);

Parameters

query_hdl	Is the handle to the query to destroy.


OG_Destroy (Query) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure destroys the specified query:
*/

PROCEDURE destroy_query(query_name VARCHAR2) IS
  query  OG_Query;
BEGIN
  query := OG_Get_Query(Query_Name);
  OG_Destroy(Query);
END;


OG_Execute_Query

  Examples	  Related Topics

Description  This procedure executes the specified query and stores the results internally.

Syntax

PROCEDURE OG_Execute_Query
  (query_hdl  OG_Query);

Parameters

query_hdl	Is the handle to the query to execute.
Usage Notes  The query must be defined in the Builder.  If the query requires database access and the database is not connected, the OG_No_Database_Connection exception is raised.  Note that this procedure only retrieves data; it does not apply the data to a chart, nor does it manipulate data in any other way.

For each query, two sets of the data are stored:  the current results of the query ("new" data), and the previous results of the query ("old" data).  This makes it possible to perform operations that depend on changing data, such as updating a chart only if the data have changed since the last time the query was executed.  Other built-in procedures and functions that allow you to manipulate and examine data let you specify which data set you want to use.

If a query has not been executed via a call to this procedure, neither the old data nor the new data for the query will exist.  The first time the query is executed, the results are stored as new data, but the old data still does not exist.  Subsequently, each time the query is executed the old data is discarded, the existing new data becomes the old data, and the latest results of the query are stored as new data.

Each time a query is executed, an implicit cursor is created for the new data.  (Several other procedures and functions allow you to manipulate this cursor and examine the data.)  When new data is reclassified as old data, its cursor (and the cursor's current position in the data list) remains with it.  Note, however, that a new cursor does not automatically point to a valid row of data.  To prepare the cursor for use, use OG_Start_From.


OG_Execute_Query Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to update a chart periodically.
**You could write the following timer trigger:
*/

PROCEDURE every_30_secs IS
   the_query   OG_Query;
   the_chart   OG_Object;
BEGIN
   the_query:=OG_Get_Query('Emp_Query');
   the_chart:=OG_Get_Object('Emp_Chart');
   OG_Execute_Query(The_Query);
   OG_Update_Chart(The_Chart, OG_All_Chupda);
END;


OG_Get_Charcell

  Examples	  Related Topics

Description  This function returns a character data value for the specified query, in the current row of data, for the specified column.

Syntax

FUNCTION OG_Get_Charcell
  (query_hdl   OG_Query,
   col_name    VARCHAR2)
RETURN VARCHAR2;

FUNCTION OG_Get_Charcell
  (query_hdl   OG_Query,
   which_data  NUMBER,
   col_name    VARCHAR2)
RETURN VARCHAR2;

Parameters

query_hdl	Is the handle to the query containing the data to return.
col_name	Is the column name containing the data to return.
which_data	Specifies whether the cell value is retrieved from the old data or the new data.  If not specified, the value of this argument defaults to OG_Newdata.  The value of this argument may be one of the following built-in constants:  OG_Newdata   Means the cell value is retrieved from the new data. OG_Olddata   Means the cell value is retrieved from the old data.
Returns  The contents of the specified data cell.

Usage Notes  The current row is determined by the query's implicit cursor, which is initially created when OG_Execute_Query is used to execute the query.

If you picture the query results displayed in the Data table, this function returns the data contained in the cell at the intersection of the current row and the specified column.

You may use this function to return data values from columns that are of type CHAR, VARCHAR2, or RAW.


OG_Get_Charcell Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*Suppose that you have a chart that
**displays employee salaries. The following
**procedure uses a format trigger to paint
**a specific employee's salary column
**yellow (in this case, "Scott’s").
*/

PROCEDURE CharCell (elem IN og_object,

                        query IN og_query) IS

  ename varchar2(10);

BEGIN

  ename := og_get_charcell(query, OG_NEWDATA, 'ename');

  if ename = 'SCOTT' then

     og_set_bfcolor(elem, 'yellow');

  end if;

END;


OG_Get_Datecell

  Examples	  Related Topics

Description  This function returns the date data value for the specified query, in the current row of data, for the specified column.

Syntax

FUNCTION OG_Get_Datecell
  (query_hdl   OG_Query,
   which_data  NUMBER,
   col_name    VARCHAR2)
RETURN DATE;

Parameters

query_hdl	Is the handle to the query containing the data to return.
col_name	Is the column name containing the data to return.
which_data	Specifies whether the cell value is retrieved from the old data or the new data.  If not specified, the value of this argument defaults to OG_Newdata.  The value of this argument may be one of the following built-in constants:  OG_Newdata   Means the cell value is retrieved from the new data. OG_Olddata   Means the cell value is retrieved from the old data.
Returns  The contents of the specified data cell.

Usage Notes  The current row is determined by the query's implicit cursor, which is initially created when OG_Execute_Query is used to execute the query.

If you picture the query results displayed in a data table, this function will return the data contained in the cell at the intersection of the current row and the specified column.


OG_Get_Datecell Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

/* Suppose you have a bar chart that
**shows the hire dates of several employees.
**The following format trigger changes the
**column color for employees with
**a HireDate prior to '28-SEP-81'
**to green.
*/

 PROCEDURE DateCell (elem IN og_object,
                        query IN og_query) IS
  HireDate date;
BEGIN
  HireDate := og_get_datecell(query, OG_NEWDATA, 'HIREDATE');
  if HireDate < '28-SEP-81' then
     og_set_bfcolor(elem, 'green');
  end if;
END;


OG_Get_Newrows

  Examples	  Related Topics

Description  This function determines the number of new rows of data appended to a query.

Syntax

FUNCTION OG_Get_Newrows
  (query  OG_Query)
RETURN NUMBER;

Parameters

query	Is a handle the query.
Returns  The number of rows appended to the query the last time it was executed.

Usage Notes  This function is useful only if the query properties specify that new data is appended to old data.  If the new data replaces old data, this function returns the same result as OG_Numrows.


OG_Get_Newrows Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have a query that appends new data old data, but you want to
**know a cell value for the first new row returned.  The following function sets the
**query's cursor to start at the first new row returned:
*/

FUNCTION example(query OG_Query) RETURN CHAR IS
  total_rows  NUMBER;
  new_rows    NUMBER;
  new_name    VARCHAR2(10);
BEGIN
  OG_Execute_Query(Query);
  total_rows := OG_Numrows(Query, OG_Newdata);
  new_rows := OG_Get_Newrows(Query);
  OG_Start_From(Query, OG_Newdata, total_rows - new_rows);

  new_name := OG_Get_Charcell(Query, 'ENAME');
  RETURN(new_name);
END;


OG_Get_Numcell

  Examples	  Related Topics

Description  This function returns the numeric data value for the specified query, in the current row of data, for the specified column.

Syntax

FUNCTION OG_Get_Numcell
  (query_hdl   OG_Query,
   col_name    VARCHAR2)
RETURN NUMBER;

FUNCTION OG_Get_Numcell
  (query_hdl   OG_Query,
   which_data  NUMBER,
   col_name    VARCHAR2)
RETURN NUMBER;

Parameters

query_hdl	Is the handle to the query containing the data to return.
col_name	Is the column name containing the data to return.
which_data	Specifies whether the cell value is retrieved from the old data or the new data.  If not specified, the value of this argument defaults to OG_Newdata.  The value of this argument may be one of the following built-in constants:  OG_Newdata   Means the cell value is retrieved from the new data. OG_Olddata   Means the cell value is retrieved from the old data.
Returns  The contents of the specified data cell.

Usage Notes  The current row is determined by the query's implicit cursor, which is initially created when OG_Execute_Query is used to execute the query.

If you picture the query results displayed in a data table, this function will return the data contained in the cell at the intersection of the current row and the specified column.


OG_Get_Numcell Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following is an example of a
**format trigger that changes the color
**of the chosen chart element (e.g. pie
**slice or bar) to red if its value is
**greater than 200.
/*

PROCEDURE format_point (elem IN og_object, query IN
    og_query) IS
  st_price NUMBER;
BEGIN
  st_price:=OG_GET_NUMCELL (query, OG_NEWDATA, 'sell_pr');
IF st_price > 200 THEN
  OG_SET_BFCOLOR (elem,'red');
END IF;
END;


OG_Get_Query

  Examples	  Related Topics

Description  This function returns a handle to the specified query.

Syntax

FUNCTION OG_Get_Query
  (query_name  VARCHAR2)
RETURN OG_Query;

Parameters

query_name	Is the name of the query whose handle is returned.  Note:  QUERY_NAME is case-sensitive.
Returns  A handle to the specified query.

Usage Notes  If the query does not exist, this function returns a null handle.


OG_Get_Query Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to update a chart periodically.
**You could write the following timer trigger:
*/

PROCEDURE every_30_secs IS
   the_query   OG_Query;
   the_chart   OG_Object;
BEGIN
   the_query:=OG_Get_Query('Emp_Query');
   the_chart:=OG_Get_Object('Emp_Chart');
   OG_Execute_Query(The_Query);
   OG_Update_Chart(The_Chart, OG_All_Chupda);


OG_Get_Schema

  Examples	  Related Topics

Description  This function returns information about the schema of a particular column in a query.

Syntax

FUNCTION OG_Get_Schema
  (query_hdl   OG_Query,
   which_data  NUMBER,
   col_num     NUMBER)
RETURN OG_Colschema;

Parameters

query_hdl	Is the handle to the query that contains the column.
which_data	Specifies whether the column whose schema is retrieved exists in the query's old data or new data.  The value of this argument may be one of the following built-in constants: OG_Newdata   Means the column exists in the query's new data. OG_Olddata   Means the column exists in the query's old data.
col_num	Specifies which column's schema is retrieved.  The first column's number is 0, the second is 1, etc.
Returns  The schema of the column in the specified query.


OG_Get_Schema Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to query a database table, and then use the name
**of the first column elsewhere in your application.  Assume you have
**defined a parameter named `my_query' that is of type CHAR,
**and that you have defined the following SQL query named `query0':
*/

&my_query

/* The following function takes a table name as an argument and
**returns the name of the table's first column:
*/

FUNCTION get_col_name (table_name IN VARCHAR2) RETURN VARCHAR2 IS
   my_schema    OG_Colschema;
   star_query   OG_Query;
BEGIN
   :my_query:='select * from ' || table_name;
   star_query:=OG_Get_Query('Query0');
   OG_Execute_Query(Star_Query);
   my_schema:=OG_Get_Schema(Star_Query, OG_Newdata, 0);
   RETURN(my_schema.colname);
END;


OG_Insert_Column

  Examples	  Related Topics

Description  This procedure inserts a column into a custom query.

Syntax

PROCEDURE OG_Insert_Column
  (query_hdl  OG_Query,
   indx       NUMBER,
   schema     OG_Colschema);

Parameters

query_hdl	Is the handle to the query in which to insert the column.
indx	Is the index at which to insert the new column in the query's column list.  This argument must be an integer between 0 and n (inclusive), where n is the number of columns in the query prior to the insertion.  The value of this argument may also be one of the following built-in constants:  OG_First   Means insert the new column at the beginning of the query's column list (index = 0). OG_Last   Means insert the new column at the end of the query's column list (index = the number of columns in the query prior to the insertion).
schema	Is the schema of the column to insert.


OG_Insert_Column Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure creates 'query0', containing the columns ENAME and SAL:
*/

PROCEDURE example IS
  query  OG_Query;
  col    OG_Colschema;
BEGIN
  query := OG_Make_Query('Query0', NULL);
  OG_Set_Querytype(Query, OG_Custom_Qtype);

  col.colname := 'ENAME';
  col.coltype := OG_Char_Coltype;
  col.maxlen := 10;

  OG_Insert_Column(Query, OG_Last, col);

  col.colname := 'SAL';
  col.coltype := OG_Number_Coltype;
  col.precision := 7;
  col.scale := 2;

  OG_Insert_Column(Query, OG_Last, col);

END;


OG_Make_Query

  Examples	  Related Topics

Description  This function creates a query.

Syntax

FUNCTION OG_Make_Query
  (querytype    NUMBER,
   querysource  VARCHAR2
RETURN OG_Query;

Parameters

querytype	Is the query type.  This value may be one of the following built-in constants: OG_Custom_Qtype   Means the query is a Custom query. OG_Exsql_Qtype   Means  the query retrieves its data from a text file that contains a SQL SELECT statement. OG_Prn_Qtype   Means the query is based on a PRN file. OG_Sql_Qtype   Means the query is a SQL SE.LECT statement. OG_Sylk_Qtype   Means the query is based on a SYLK file. OG_Wks_Qtype   Means the query is based on a WKS file.
querysource	Is the source of the query's data.  If the data comes from a database, this property should contain the text of the query's SQL SELECT statement.  If the data is stored in the filesystem, this property should contain the path and name of the data file.
Returns  A handle to the newly created query.


OG_Make_Query Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates a SQL query:
*/

FUNCTION example(query_name VARCHAR2) RETURN OG_Query IS
  query   OG_Query;
  qtype   NUMBER;
  qsource VARCHAR2(2000);
BEGIN
  qtype := OG_Sql_Qtype;
  qsource := 'select ename, sal from emp';

  query := OG_Make_Query(Qtype, qsource);

  OG_Set_Name(Query, query_name);
  OG_Execute_Query(Query);
  RETURN(query);
END;


OG_Next_Row

  Examples	  Related Topics

Description

Syntax This procedure advances the implicit cursor associated with the specified query ahead to the next row of data.

PROCEDURE OG_Next_Row
  (query_hdl   OG_Query,
   which_data  NUMBER);

Parameters

query_hdl	Is the handle to the query.
which_data	Specifies whether the old data or the new data should be processed.  The value of this argument may be one of the following built-in constants:  OG_Newdata   Means advance the cursor for the query's new data. OG_Olddata   Means advance the cursor for the query's old data.
Usage Notes  If the cursor is pointing to the last row of data in the query, the next call to OG_Next_Row will leave the cursor where it is.  The cursor will not advance to a non-existent row, and no error or exception will be raised.  To recognize that the cursor is pointing to the last row of data, you must use OG_Numrows to determine the exact number of rows, then keep track of how many times you use OG_Next_Row to advance the cursor.


OG_Next_Row Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to name each bar in a bar chart so that when
**the user selects one of the bars you can determine which one it is
**by checking its name.  For this example, assume the query for the chart is:
*/

SELECT ENAME, SAL FROM EMP

 /*The following procedure gives each bar the name of its category,
**which in this case is its associated ENAME:
*/

PROCEDURE name_the_bars (my_chart IN OG_Object, my_query IN
  OG_Query) IS
   bar_rec    OG_Chelement_Ca;
   curr_row   NUMBER;
   total      NUMBER;
   bar_name   VARCHAR2(15);
BEGIN
   OG_Execute_Query(My_Query);
   OG_Start_From(My_Query, OG_Newdata, 0);
   total:=OG_Numrows(My_Query, OG_Newdata);
   FOR curr_row IN 0..total-1 LOOP
      bar_name:=OG_Get_Charcell(My_Query,
        OG_Newdata, 'ENAME');
      bar_rec.chelement_cagr.mask:=OG_None_Graphica;
      bar_rec.chelement_cace.mask:=OG_Name_Chelementa;
      bar_rec.chelement_cace.name:=bar_name;
      OG_Set_Attr(My_Chart, curr_row, 'ENAME', bar_rec);
      OG_Next_Row(My_Query, OG_Newdata);
   END LOOP;
   OG_Update_Chart(My_Chart, OG_All_Chupda);
END;


OG_Numcols

  Examples	  Related Topics

Description  This function returns the number of columns that exist in a query.

Syntax

FUNCTION OG_Numcols
  (query_hdl   OG_Query,
   which_data  NUMBER)
RETURN NUMBER;

Parameters

query_hdl	Is the handle to the query.
which_data	Specifies whether the old data or the new data should be checked.  The value of this argument may be one of the following built-in constants:  OG_Newdata   Means return the number of columns in the query's new data. OG_Olddata   Means return the number of columns in the query's old data.
Returns  The number of columns in the specified query.


OG_Numcols Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose Reports will pass data to your display, and you want to chart it.
**Since you may not be sure what columns your display will receive,
**you can make your charting procedure generic.  You can write one
**procedure that creates an chart, then pass the query and chart to
**another procedure that inserts the query's columns as fields.  The following
**procedure inserts the columns (it assumes the first column is the independent
**field, and the rest are dependent fields):
*/

PROCEDURE add_columns(the_query OG_Query, the_chart OG_Object) IS
   num_of_cols   NUMBER(1);
   the_field     OG_Field;
   the_column    OG_Colschema;
BEGIN
   OG_Execute_Query(The_Query);
   num_of_cols:=OG_Numcols(The_Query, OG_Newdata);
   FOR i IN 0..num_of_cols-1 LOOP
      the_column:=OG_Get_Schema(The_Query, OG_Newdata, i);
      the_field.colname:=the_column.colname;
      IF i=0 THEN
         the_field.field_type:=OG_Independent;
      ELSE
         the_field.field_type:=OG_Dependent;
         the_field.ftname:='line';
      END IF;
      OG_Insert_Field(The_Chart, the_field, i);
   END LOOP;
   OG_Update_Chart(The_Chart, OG_All_Chupda);
END;


OG_Numrows

  Examples	  Related Topics

Description  This function returns the number of rows that exist in a query.

Syntax

FUNCTION OG_Numrows
  (query_hdl   OG_Query,
   which_data  NUMBER)
RETURN NUMBER;

Parameters

query_hdl	Is the handle to the query.
which_data	Specifies whether the old data or the new data should be checked.  The value of this argument may be one of the following built-in constants:  OG_Newdata   Means return the number of rows in the query's new data. OG_Olddata   Means return the number of rows in the query's old data.
Returns  The number of rows of data in the specified query.


OG_Numrows Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to name each bar in a bar chart so that when
**the user selects one of the bars you can determine which one it is
**by checking its name.  For this example, assume the query for the chart is:
*/

SELECT ENAME, SAL FROM EMP

 /*The following procedure gives each bar the name of its category,
**which in this case is its associated ENAME:
*/

PROCEDURE name_the_bars(my_chart IN OG_Object, my_query IN
  OG_Query) IS
   bar_rec    OG_Chelement_Ca;
   curr_row   NUMBER;
   total      NUMBER;
   bar_name   VARCHAR2(15);
BEGIN
   OG_Execute_Query(My_Query);
   OG_Start_From(My_Query, OG_Newdata, 0);
   total:=OG_Numrows(My_Query, OG_Newdata);
   FOR curr_row IN 0..total-1 LOOP
      bar_name:=OG_Get_Charcell(My_Query, OG_Newdata,
        'ENAME');
      bar_rec.chelement_cagr.mask:=OG_None_Graphica;
      bar_rec.chelement_cace.mask:=OG_Name_Chelementa;
      bar_rec.chelement_cace.name:=bar_name;
      OG_Set_Attr(My_Chart, curr_row, 'ENAME', bar_rec);
      OG_Next_Row(My_Query, OG_Newdata);
   END LOOP;
   OG_Update_Chart(My_Chart, OG_All_Chupda);
END;


OG_Set_Charcell

  Examples	  Related Topics

Description  This procedure sets the value of a CHAR cell in the row buffer.

Syntax

PROCEDURE OG_Set_Charcell
  (query_hdl   OG_Query,
   col_name    VARCHAR2
   cell_value  VARCHAR2);

Parameters

query_hdl	Is the handle to the query in which to set the cell value.
col_name	Is the name of the column containing the cell to set.
cell_value	Is the value that the cell will contain.
Usage Notes  Once you set the values for all the cells in the buffer, use OG_Append_Row to add the buffer as a new row at the end of a custom query.


OG_Set_Charcell Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to create a custom query using the ENAME, SAL,
**and HIREDATE columns in the existing query 'query0' as a basis.
**However, in the new query, you want to double every SAL value.
**The following procedure is a custom query procedure you could use:
*/

PROCEDURE OGQUERYPROC0(query IN OG_Query) IS
  other_ename     VARCHAR2(10);
  other_sal       NUMBER(7,2);
  other_query     OG_Query;
  other_hiredate  DATE;
  row_count       NUMBER;
BEGIN
  OG_Clear_Query(Query);

  other_query := OG_Get_Query('Query0');
  row_count := OG_Numrows(Other_Query, OG_Newdata);
  OG_Start_From(Other_Query, OG_Newdata, 0);

  FOR i IN 0..row_count-1 loop
    other_ename := OG_Get_Charcell(Other_Query, 'ENAME');
    other_sal := OG_Get_Numcell(Other_Query, 'SAL');
    other_hiredate := OG_Get_Numcell(Other_Query, 'HIREDATE');
    OG_Set_Charcell(Query, 'ENAME', other_ename);
    OG_Set_Numcell(Query, 'SAL', other_sal * 2);
    OG_Set_Datecell(Query, 'HIREDATE', other_hiredate);
    OG_Append_Row(Query);
    OG_Next_Row(Other_Query, OG_Newdata);
  END LOOP;

END;


OG_Set_Datecell

  Examples	  Related Topics

Description  This procedure sets the value of a DATE cell in the row buffer.

Syntax

PROCEDURE OG_Set_Datecell
  (query_hdl   OG_Query,
   col_name    VARCHAR2
   cell_value  DATE);

Parameters

query_hdl	Is the handle to the query in which to set the cell value.
col_name	Is the name of the column containing the cell to set.
cell_value	Is the value that the cell will contain.
Usage Notes  Once you set the values for all the cells in the buffer, use OG_Append_Row to add the buffer as a new row at the end of a custom query.


OG_Set_Datecell Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to create a custom query using the ENAME, SAL,
**and HIREDATE columns in the existing query 'query0' as a basis.
**However, in the new query, you want to double every SAL value.
**The following procedure is a custom query procedure you could use:
*/

PROCEDURE OGQUERYPROC0(query IN OG_Query) IS
  other_ename     VARCHAR2(10);
  other_sal       NUMBER(7,2);
  other_query     OG_Query;
  other_hiredate  DATE;
  row_count       NUMBER;
BEGIN
  OG_Clear_Query(Query);

  other_query := OG_Get_Query('Query0');
  row_count := OG_Numrows(Other_Query, OG_Newdata);
  OG_Start_From(Other_Query, OG_Newdata, 0);

  FOR i IN 0..row_count-1 loop
    other_ename := OG_Get_Charcell(Other_Query, 'ENAME');
    other_sal := OG_Get_Numcell(Other_Query, 'SAL');
    other_hiredate := OG_Get_Numcell(Other_Query, 'HIREDATE');
    OG_Set_Charcell(Query, 'ENAME', other_ename);
    OG_Set_Numcell(Query, 'SAL', other_sal * 2);
    OG_Set_Datecell(Query, 'HIREDATE', other_hiredate);
    OG_Append_Row(Query);
    OG_Next_Row(Other_Query, OG_Newdata);
  END LOOP;

END;


OG_Set_Numcell

  Examples	  Related Topics

Description  This procedure sets the value of a NUMBER cell in the row buffer.

Syntax

PROCEDURE OG_Set_Numcell
  (query_hdl   OG_Query,
   col_name    VARCHAR2,
   cell_value  NUMBER);

Parameters

query_hdl	Is the handle to the query in which to set the cell value.
col_name	Is the name of the column containing the cell to set.
cell_value	Is the value that the cell will contain.
Usage Notes  Once you set the values for all the cells in the buffer, use OG_Append_Row to add the buffer as a new row at the end of a custom query.


OG_Set_Numcell Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to create a custom query using the ENAME, SAL,
**and HIREDATE columns in the existing query 'query0' as a basis.
**However, in the new query, you want to double every SAL value.
**The following procedure is a custom query procedure you could use:
*/

PROCEDURE OGQUERYPROC0(query IN OG_Query) IS
  other_ename     VARCHAR2(10);
  other_sal       NUMBER(7,2);
  other_query     OG_Query;
  other_hiredate  DATE;
  row_count       NUMBER;
BEGIN
  OG_Clear_Query(Query);

  other_query := OG_Get_Query('Query0');
  row_count := OG_Numrows(Other_Query, OG_Newdata);
  OG_Start_From(Other_Query, OG_Newdata, 0);
  FOR i IN 0..row_count-1 loop
    other_ename := OG_Get_Charcell(Other_Query, 'ENAME');
    other_sal := OG_Get_Numcell(Other_Query, 'SAL');
    other_hiredate := OG_Get_Numcell(Other_Query, 'HIREDATE');
    OG_Set_Charcell(Query, 'ENAME', other_ename);
    OG_Set_Numcell(Query, 'SAL', other_sal * 2);
    OG_Set_Datecell(Query, 'HIREDATE', other_hiredate);
    OG_Append_Row(Query);
    OG_Next_Row(Other_Query, OG_Newdata);
  END LOOP;

END;


OG_Set_Schema

  Examples	  Related Topics

Description  This procedure sets the schema of a column in a custom query.

Syntax

PROCEDURE OG_Set_Schema
  (query_hdl  OG_Query,
   col_num    NUMBER,
   schema     OG_Colschema);

Parameters

query_hdl	Is the handle to the query whose schema you want to set.
col_num	Is the index of the column that you want to set.
schema	Is the new schema to which you want to set the column.


OG_Set_Schema Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure changes the name of the fist column
**in a custom query from ENAME to EMPLOYEE:
*/

PROCEDURE example(query OG_Query) IS
  schema  OG_Colschema;
BEGIN
  schema.colname := 'EMPLOYEE';
  schema.coltype := OG_Char_Coltype;
  schema.maxlen := 10;

  OG_Set_Schema(Query, 0, schema);

END;


OG_Start_From

  Examples	  Related Topics

Description  This procedure causes the implicit cursor associated with the specified query to point to the specified row of data.

Syntax

PROCEDURE OG_Start_From
  (query_hdl   OG_Query,
   which_data  NUMBER,
   start_row   NUMBER);

Parameters

query_hdl	Is the handle to the query.
which_data	Specifies whether the old data or the new data should be processed.  The value of this argument may be one of the following built-in constants:  OG_Newdata   Means set the cursor for the query's new data. OG_Olddata   Means set the cursor for the query's old data.
start_row	Is the row number at which to position the cursor.
Usage Notes  To point to the very first row of data, use an offset value of 0.  The last row of data will have an offset equal to the value returned by OG_Numrows minus one.  Note that each time OG_Execute_Query is used to execute the query, the cursor position will be discarded and must be set again.  Be aware that the number of rows retrieved by a query may change each time the query is executed.


OG_Start_From Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to name each bar in a bar chart so that
**when the user selects one of the bars you can determine
**which one it is by checking its name.  For this example,
**assume the query for the chart is:
*/

SELECT ENAME, SAL FROM EMP

 /*The following procedure gives each bar the name of its
**category, which in this case is its associated ENAME:
*/

PROCEDURE name_the_bars (my_chart IN OG_Object, my_query IN
  OG_Query) IS
   bar_rec    OG_Chelement_Ca;
   curr_row   NUMBER;
   total      NUMBER;
   bar_name   VARCHAR2(15);
BEGIN
   OG_Execute_Query(My_Query);
   OG_Start_From(My_Query, OG_Newdata, 0);
   total:=OG_Numrows(My_Query, OG_Newdata);
   FOR curr_row IN 0..total-1 LOOP
      bar_name:=OG_Get_Charcell(My_Query, OG_Newdata,
        'ENAME');
      bar_rec.chelement_cagr.mask:=OG_None_Graphica;
      bar_rec.chelement_cace.mask:=OG_Name_Chelementa;
      bar_rec.chelement_cace.name:=bar_name;
      OG_Set_Attr(My_Chart, curr_row, 'ENAME', bar_rec);
      OG_Next_Row(My_Query, OG_Newdata);
   END LOOP;
   OG_Update_Chart(My_Chart, OG_All_Chupda);
END;


No built-in subprograms begin with this letter.


Sound Built-ins

OG_Destroy (Sound)

OG_Export_Sound

OG_Get_Sound

OG_Import_Sound

OG_Make_Sound

OG_Play_Sound

OG_Record_Sound

OG_Stop_Sound


OG_Destroy (Sound)

  Examples	  Related Topics

Description  This procedure destroys the specified sound.

Syntax

PROCEDURE OG_Destroy
  (sound_hdl  OG_Sound);

Parameters

sound_hdl	Is the handle to the sound to destroy.


OG_Destroy (Sound) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure destroys the specified sound:
*/

PROCEDURE destroy_sound(sound_name VARCHAR2) IS
  sound  OG_Sound;
BEGIN
  sound := OG_Get_Sound(Sound_Name);
  OG_Destroy(Sound);
END;


OG_Export_Sound

  Examples	  Related Topics

Description  This procedure exports a sound.

Syntax

PROCEDURE OG_Export_Sound
  (name        VARCHAR2,
   repository  NUMBER,
   format      NUMBER,
   sound_hdl   OG_Sound);

Parameters

name	Is the name to which the sound will be exported.  If the sound is to be stored in the database, this argument should contain only the name of the sound module.  If the sound is to be stored in the file system, this argument should contain the absolute or relative pathname of the sound file.
repository	Specifies whether the sound is to be stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the sound is to be stored in the database. OG_Filesystem   Means the sound is to be stored in the file system.
format	Specifies the format in which the sound is exported.  The value of this argument may be one of the following built-in constants: OG_Aiff_Sformat   Means the sound is saved in the AIFF format. OG_Aiffc_Sformat   Means the sound is saved in the Audio Interchange File Format-c. OG_Au_Sformat   Means the sound is saved in the SUN au format. OG_Wave_Sformat   Means the sound is saved in the PCM WAVE format.
sound_hdl	Is the handle to the sound that will be exported.


OG_Export_Sound Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to export the sound named `sound0' to the AIFF-c file
**`my_sound' so that you can later import it into some other application.
**The following procedure does this:
*/

PROCEDURE export_the_sound IS
   the_sound   OG_Sound;
BEGIN
   the_sound:=OG_Get_Sound('Sound0');
   OG_Export_Sound('My_Sound', OG_Filesystem,
OG_Aiffc_Sformat, the_sound);
END;


OG_Get_Sound

  Examples	  Related Topics

Description  This function returns a handle to the specified sound.

Syntax

FUNCTION OG_Get_Sound
   (sound_name  VARCHAR2)
RETURN OG_Sound;

Parameters

sound_name	Is the name of the sound whose handle should be returned.
Returns  A handle to the specified sound.  If the sound does not exist, this function will return a null handle.


OG_Get_Sound Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to play a warning sound, to indicate
**low inventory or an illegal action by the user.
*/

PROCEDURE warning IS
   the_sound   OG_Sound;
BEGIN
   the_sound:=OG_Get_Sound('Warning_Snd');
   OG_Play_Sound(The_Sound);
END;


OG_Import_Sound

  Examples	  Related Topics

Description  This procedure imports a sound from the database or a file.

Syntax

FUNCTION OG_Import_Sound
  (name        VARCHAR2,
   repository  NUMBER,
   format      NUMBER,
   sound_name  VARCHAR2)
RETURN OG_Sound;

Parameters

name	Is the name of the sound as it is stored.  If the sound is stored in the database, this argument should contain only the name of the sound.  If the sound is stored in the file system, this argument should contain the absolute or relative pathname of the sound file.
repository	Specifies whether the sound is stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the sound is stored in the database. OG_Filesystem   Means the sound is stored in the file system.
format	Specifies the format in which the sound is saved.  The value of this argument may be one of the following built-in constants: OG_Aiff_Sformat   Means the sound is saved in the AIFF format. OG_Aiffc_Sformat   Means the sound is saved in the AIFF-c format. OG_Any_Sformat   Means Graphics Builder automatically determines the sound's format.  Note:  Specify this format if your sound was exported in the Oracle Format (now obsolete). OG_Au_Sformat   Means the sound is saved in the SUN AU format. OG_Oracle_Sformat   Means the sound is saved in the Oracle Format, used by other Oracle products. OG_Wave_Sformat   Means the sound is saved in the WAV format.
sound_name	Is the name that Graphics Builder will assign to the sound.  If another sound already has this name, Graphics Builder replaces it with the imported sound.
Returns  A handle to the imported sound.


OG_Import_Sound Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to import the contents of the AIFF-c file
**`my_sound' into your display as the sound named `sound0'.
**The following procedure does this:
*/

PROCEDURE import_the_sound IS
   the_sound   OG_Sound;
BEGIN
   the_sound:=OG_Import_Sound('My_Sound', OG_Filesystem,
OG_Aiffc_Sformat, 'sound0');
END;


OG_Make_Sound

  Examples	  Related Topics

Description  This function creates a sound from data stored in a database table.

Syntax

FUNCTION OG_Make_Sound
  (query       OG_Query,
   which_data  NUMBER,
   colname     VARCHAR2)
RETURN OG_Sound;

Parameters

query	Is the handle to the query that retrieves the sound from a table in a database.  Note that this table must be a user table, and not one the private tables used by Graphics Builder when you save or export a module to the database.
which_data	Specifies whether the sound to be created is contained in a query's new or old data set.  Graphics Builder provides two built-in numeric constants that may be used as values for this attribute: OG_Newdata   Means the sound is contained in the query's new data set. OG_Olddata   Means the sound is contained in the query's old data set.
colname	Is the name of the query column that contains the sound data.  The sound that is created is the one contained in the query cell at the intersection of the column specified by this attribute and the row pointed to by the query's cursor.
Returns  A handle to the newly created sound.


OG_Make_Sound Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates a sound from data in the sixth
**row of the query 'sound_query' in the column SOUND_COLUMN:
*/

FUNCTION example(sound_name VARCHAR2) RETURN OG_Sound IS
  query  OG_Query;
  sound  OG_Sound;
BEGIN
  query := OG_Get_Query('Sound_Query');
  OG_Execute_Query(Query);
  OG_Start_From(Query, OG_Newdata, 5);
  sound := OG_Make_Sound(Query, OG_Newdata, 'SOUND_COLUMN');

  OG_Set_Name(Sound, sound_name);
  RETURN(sound);
END;


OG_Play_Sound

  Examples	  Related Topics

Description  This procedure plays the specified sound through the sound output device specified in your preferences.

Syntax

PROCEDURE OG_Play_Sound
  (sound_hdl  OG_Sound);

Parameters

sound_hdl	Is the handle to the sound to be played.


OG_Play_Sound Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to play a warning sound, to indicate
**low inventory or an illegal action by the user.
*/

PROCEDURE warning IS
   the_sound   OG_Sound;
BEGIN
   the_sound:=OG_Get_Sound('Warning_Snd');
   OG_Play_Sound(The_Sound);
END;


OG_Record_Sound

  Examples	  Related Topics

Description  This procedure shows the sound dialog box and allows the user to record a new sound.

Syntax

PROCEDURE OG_Record_Sound
  (sound_hdl  OG_Sound);

Parameters

sound_hdl	Is the handle to the sound.
Usage Notes  The new sound overwrites the sound pointed to by sound_hdl.  In addition, sound_hdl must point to a sound previously created either in the Builder, or by the built-in functions OG_Import_Sound and OG_Make.


OG_Record_Sound Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want the user to record a sound to be played as a warning
**when data changes.  You could write the following procedure:
*/

PROCEDURE record_warning IS
   warn_sound   OG_Sound;
BEGIN
   warn_sound:=OG_Get_Sound('Warning');
   IF not OG_Isnull(Warn_Sound) THEN
      OG_Record_Sound(Warn_Sound);
   END IF;
END;


OG_Stop_Sound

  Examples	  Related Topics

Description  This procedure cancels the playback of a sound that is in the process of playing.

Syntax

PROCEDURE OG_Stop_Sound
  (sound_hdl   OG_Sound);

Parameters

sound_hdl	Is the handle to the sound whose playback you want to stop.


OG_Stop_Sound Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to create a button that the user
**can select to cancel a sound that is currently playing.
**The following button procedure does this:
*/

PROCEDURE OGBUTTONPROC0 (buttonobj IN OG_Object, hitobj IN OG_Object, win IN OG_Window, eventinfo IN OG_Event) IS
  sound  OG_Sound;
BEGIN
  sound := OG_Get_Sound('Alarm');
  OG_Stop_Sound(Sound);
END;


Template Built-ins

OG_Clone (Template)

OG_Delete_Ftemp

OG_Delete_Refline

OG_Destroy (Template)

OG_Export_Template

OG_Get_Axis

OG_Get_Ftemp

OG_Get_Refline

OG_Get_Template

OG_Import_Template

OG_Insert_Ftemp

OG_Insert_Refline

OG_Make_Template


OG_Clone (Template)

  Examples	  Related Topics

Description  This function creates a new chart template that is identical to the specified template.

Syntax

FUNCTION OG_Clone
  (template_hdl  OG_Template,
   name          VARCHAR2)
RETURN OG_Template;

Parameters

template_hdl	Is the handle to the chart template to be cloned.
name	Is the name to be given to the new template.
Returns  The handle to the newly created template.


OG_Clone (Template) Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* Suppose you have created  atemplate, and you want to create another
**identical template without having to again specify the same properties.
*/

PROCEDURE dup_template(old_template IN OG_Template) IS
   new_template   OG_Template;
BEGIN
   new_template:=OG_Clone(Old_Template);
END;


OG_Delete_Ftemp

  Examples	  Related Topics

Description  This procedure deletes one or more field template from the specified chart template.

Syntax

PROCEDURE OG_Delete_Ftemp
  (template_hdl  OG_Template,
   indx          NUMBER,
   total         NUMBER);

Parameters

template_hdl	Is the handle to the chart template.
indx	Is the index of the first field template to delete from the chart template's list of field templates..
total	Is the total number of field template to delete.


OG_Delete_Ftemp Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* The following procedure deletes a column from the template 'template0':
*/

PROCEDURE example(ft_num  NUMBER) IS
  template  OG_Template;
BEGIN
  template := OG_Get_Template('Template0');
  OG_Delete_Ftemp(Template, ft_num, 1);
END;


OG_Delete_Refline

  Examples	  Related Topics

Description  This procedure deletes one or more reference lines from the specified chart template.

Syntax

PROCEDURE OG_Delete_Refline
  (template_hdl  OG_Template,
   indx          NUMBER,
   total         NUMBER);

Parameters

template_hdl	Is the handle to the chart template.
indx	Is the index of the first reference line to delete from the chart template's list of reference lines.
total	Is the total number of reference lines to delete.


OG_Delete_Refline Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* The following procedure deletes a reference line template 'template0':
*/

PROCEDURE example(rl_num  NUMBER) IS
  template  OG_Template;
BEGIN
  template := OG_Get_Template('Template0');
  OG_Delete_Refline(Template, rl_num, 1);
END;


OG_Destroy (Template)

  Examples	  Related Topics

Description  This procedure destroys the specified chart template.

Syntax

PROCEDURE OG_Destroy
  (template_hdl  OG_Template);

Parameters

template_hdl	Is the handle to the chart template to destroy.


OG_Destroy (Template) Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* The following procedure destroys the specified template:
*/

PROCEDURE destroy_template(template_name VARCHAR2) IS
  template  OG_Template;
BEGIN
  template := OG_Get_Template(Template_Name);
  OG_Destroy(Template);
END;


OG_Export_Template

  Examples	  Related Topics

Description  This procedure exports a chart template.

Syntax

PROCEDURE OG_Export_Template
  (name          VARCHAR2,
   repository    NUMBER,
   template_hdl  OG_Template);

Parameters

name	Is the name to which the template will be exported.  If the template is to be stored in the database, this argument should contain only the name of the template.  If the template is to be stored in the file system, this argument should contain the absolute or relative pathname of the template file.
repository	Specifies whether the template is to be stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the template is to be stored in the database. OG_Filesystem   Means the template is to be stored in the file system.
tamplate_hdl	Is the handle to the template that will be exported.


OG_Export_Template Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* Suppose you want to export the chart template named `template0'
**to the file `my_temp' so that you can later import it into some other
**Graphics Builder display.  The following procedure does this:
*/

PROCEDURE export_the_template IS
   the_temp   OG_Template;
BEGIN
   the_temp:=OG_Get_Template('Template0');
   OG_Export_Template('My_Temp', OG_Filesystem, the_temp);
END;


OG_Get_Axis

  Examples	  Related Topics

Description  This function returns a handle to an axis in a chart template.

Syntax

FUNCTION OG_Get_Axis
  (template_hdl  OG_Template,
   which_axis    NUMBER)
RETURN OG_Axis;

Parameters

template_hdl	Is the handle to the chart template containing the axis whose handle should be returned.
which_axis	Specifies which axis will be returned.  The value of this argument may be one of the following built-in constants:  OG_X_Axis    OG_Y1_Axis    OG_Y2_Axis
Returns  A handle to the specified axis.  If the specified button procedure does not exist, this function will return a null handle.


OG_Get_Axis Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* The following function returns a handle to the specified template's X axis:
*/

FUNCTION example(template_name VARCHAR2) RETURN OG_Axis IS
  template  OG_Template;
  axis      OG_Axis;
BEGIN
  template := OG_Get_Template(Template_Name);
  axis := OG_Get_Axis(Template, OG_X_Axis);
  RETURN(axis);
END;


OG_Get_Ftemp

  Examples	  Related Topics

Description  This function returns a handle to a field template within a chart template.

Syntax

FUNCTION OG_Get_Ftemp
  (template_hdl  OG_Template,
   indx          NUMBER)
RETURN OG_Ftemp;

Parameters

template_hdl	Is the handle to the chart template containing the field template that should be returned.
indx	Is the index of the field template in the chart's field template list to be returned.
Returns  The attributes of the specified field template.


OG_Get_Ftemp Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* The following function returns the handle to the
**first field template in the specified chart template:
*/

FUNCTION example(temp_name VARCHAR2) RETURN OG_Ftemp IS
  template  OG_Template;
  ftemp   OG_Ftemp;
BEGIN
  template := OG_Get_Template(Temp_Name);
  ftemp := OG_Get_Ftemp(Template, 0);
  RETURN(ftemp);
END;


OG_Get_Refline

  Examples	  Related Topics

Description  This function returns a handle to a reference line in a chart template:

Syntax

FUNCTION OG_Get_Refline
  (template_hdl  OG_Template,
   indx          NUMBER)
RETURN OG_Refline;

Parameters

template_hdl	Is the handle to the chart template containing the reference line that should be returned.
indx	Is the index of the reference line in the chart's reference line list to be returned.
Returns  A handle to the specified reference line.


OG_Get_Refline Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* The following function returns the handle to the
**first reference line in the specified chart template:
*/

FUNCTION example(temp_name VARCHAR2) RETURN OG_Refline IS
  template  OG_Template;
  refline   OG_Refline;
BEGIN
  template := OG_Get_Template(Temp_Name);
  refline := OG_Get_Refline(Template, 0);
  RETURN(refline);
END;


OG_Get_Template

  Examples	  Related Topics

Description  This function returns a handle to the specified template.

Syntax

FUNCTION OG_Get_Template
  (template_name  VARCHAR2)
RETURN OG_Template;

Parameters

template_name	Is the name of the chart template whose handle should be returned.
Returns  A handle to the specified chart template.  If the template does not exist, this function will return a null handle.


OG_Get_Template Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* Suppose you want to create a chart programmatically.  You would need to assign attribute values (including a template) to a chart combined attribute record, then pass that record to OG_Make.
*/

PROCEDURE create_emp_chart IS
   chart_rec      OG_Chart_Ca;
   the_template   OG_Template;
   the_query      OG_Query;
   the_chart      OG_Object;
BEGIN
   the_template:=OG_Get_Template('Emp_Template');
   the_query:=OG_Get_Query('Emp_Query');
   chart_rec.chart_caoc.template:=the_template;
   chart_rec.chart_caoc.query:=the_query;
   chart_rec.chart_caob.mask:=OG_None_Generica;
   chart_rec.chart_caog.mask:=OG_None_Groupa;
   chart_rec.chart_caoc.mask:=OG_Template_Charta+
                              OG_Query_Charta;
   the_chart:=OG_Make(Chart_Rec);
END;


OG_Import_Template

  Examples	  Related Topics

Description  This procedure imports a chart template.

Syntax

FUNCTION OG_Import_Template
  (name           VARCHAR2,
   repository     NUMBER,
   template_name  VARCHAR2)
RETURN OG_Template;

Parameters

name	Is the name of the template as it is stored.  If the template is stored in the database, this argument should contain only the name of the template.  If the template is stored in the file system, this argument should contain the absolute or relative pathname of the template file.
repository	Specifies whether the template is stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the template is stored in the database. OG_Filesystem   Means the template is stored in the file system.
template_name	Is the name that Graphics Builder will assign to the template.  If another template already has this name, Graphics Builder replaces it with the imported template.
Returns  A handle to the imported template.


OG_Import_Template Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* Suppose you want to import the chart template file `my_temp'
**into your display as the template named `template0'.
**The following procedure does this:
*/

PROCEDURE import_the_template IS
   the_temp   OG_Template;
BEGIN
   the_temp:=OG_Import_Template('My_Temp', OG_Filesystem,
'template0');
END;


OG_Insert_Ftemp

  Examples	  Related Topics

Description  This procedure inserts a new field template into the specified chart template.

Syntax

PROCEDURE OG_Insert_Ftemp                    pie/table chart
  (template_hdl  OG_Template,
   attr          OG_Ftemp_Attr,
   indx          NUMBER);

PROCEDURE OG_Insert_Ftemp                    axis chart
  (template_hdl  OG_Template,
   attr          OG_Axisftemp_Ca,
   indx          NUMBER);

Parameters

template_hdl	Is the handle to the chart template.
attr	Is the record containing the field template's attributes.
indx	Is the index at which to insert the new field template in the chart template's list of field templates.  This argument must be an integer between 0 and n (inclusive), where n is the number of field templates in the chart template prior to the insertion.  The value of this argument may also be one of the following built-in constants:  OG_First   Means insert the new field template at the beginning of the chart template's list of field templates (index = 0). OG_Last   Means insert the new field at the end of the chart template's list of field templates (index = the number of field templates in the chart template prior to the insertion).


OG_Insert_Ftemp Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* The following procedure inserts a new field
**template into the specified chart template.
*/

PROCEDURE example(template OG_Template) IS
  attr  OG_Axisftemp_Ca;
BEGIN
  attr.ca_aftemp.plottype := OG_Bar_Plottype;
  attr.ca_ftemp.name := 'column';
  attr.ca_aftemp.mask:= OG_Plottype_Axisftempa;
  attr.ca_ftemp.mask := OG_Name_Ftempa;

  OG_Insert_Ftemp(Template, attr, 0);
END;


OG_Insert_Refline

  Examples	  Related Topics

Description  This procedure inserts a new reference line into the specified chart template.

Syntax

PROCEDURE OG_Insert_Refline
  (template_hdl  OG_Template,
   attr          OG_Refline_Attr,
   indx          NUMBER);

Parameters

template_hdl	Is the handle to the chart template.
attr	Is the record containing the reference line's attributes.
indx	Is the index at which to insert the new reference line in the chart template's list of reference lines.  This argument must be an integer between 0 and n (inclusive), where n is the number of reference lines in the chart template prior to the insertion.  The value of this argument may also be one of the following built-in constants:  OG_First   Means insert the new reference line at the beginning of the chart template's list of reference lines (index = 0). OG_Last   Means insert the new reference line at the end of the chart template's list of reference lines (index = the number of reference lines in the chart template prior to the insertion).


OG_Insert_Refline Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* The following procedure inserts a new refernce
**line into the specified chart template.
*/

PROCEDURE example(template OG_Template) IS
  attr  OG_Refline_Attr;
BEGIN
  attr.numvalue := 1000;
  attr.label := 'Average';
  attr.mask:= OG_Value_Reflinea+
              OG_Label_Reflinea;

  OG_Insert_Refline(Template, attr, 0);
END;


OG_Make_Template

  Examples	  Related Topics

Description  This function creates a chart template.

Syntax

FUNCTION OG_Make_Template
  (name        VARCHAR2,
   chart_type  NUMBER
RETURN OG_Template;

Parameters

name	Is the template name.
chart_type	Is the chart type for the template.  This value may be one of the following built-in constants:  OG_Column OG_Column_Stacked OG_Column_Overlap OG_Column_Pct OG_Column_Zero OG_Column_Shadow OG_Column_3d OG_Column_Line OG_Bar OG_Bar_Stacked OG_Bar_Overlap OG_Bar_Pct OG_Bar_Zero OG_Bar_Shadow OG_Bar_3d OG_Bar_Line OG_Line OG_Line_Symbol OG_Line_Stacked OG_Line_Fill OG_Step OG_Step_Symbol OG_Step_Stacked OG_Step_Fill OG_Spline OG_Spline_Symbol OG_Spline_Stacked OG_Spline_Fill OG_Mixed_Line OG_Mixed_Fill OG_Mixed_Spline OG_Mixed_Spfill OG_Doubley_Column OG_Doubley_Overlap OG_Doubley_Line OG_Doubley_Symbol OG_Highlow_Symbol OG_Highlow_Spike OG_Highlow_Both OG_Highlow_Line OG_Highlow_Fill OG_Scatter_Symbol OG_Scatter_Curvefit OG_Scatter_Linear OG_Scatter_Log OG_Scatter_Loglog OG_Scatter_Connect OG_Gantt OG_Gantt_Shadow OG_Gantt_Depth OG_Pie OG_Pie_Shadow OG_Pie_Depth OG_Table OG_Table_Shadow OG_Table_Depth
Returns  A handle to the newly created template.


OG_Make_Template Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /* The following function creates a column
**chart template with shadows on the bars:
*/

FUNCTION example RETURN OG_Template IS
  template  OG_Template;
BEGIN
  template := OG_Make_Template('Template0', OG_Column_Shadow);
  RETURN(template);
END;


Timer Built-ins

OG_Activate_Timer

OG_Deactivate_Timer

OG_Destroy (Timer)

OG_Get_Timer

OG_Make_Timer


OG_Activate_Timer

  Examples	  Related Topics

Description  This procedure activates the specified timer.

Syntax

PROCEDURE OG_Activate_Timer
  (timer_hdl  OG_Timer);

Parameters

timer_hdl	Is the handle to the timer to be activated.
Usage Notes  Note that all timers are activated by default when a display is opened.  You do not need to activate a timer unless you have explicitly deactivated it by using the OG_Deactivate_Timer procedure.


OG_Activate_Timer Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have created timers to update all of your charts
**every 30 seconds, and that you have deactivated the timers
**for charts that are not displayed.  When you display a chart,
**however, you want to re-activate its timer.
*/

PROCEDURE activate_emp_timer IS
   my_timer   OG_Timer;
BEGIN
   my_timer:=OG_Get_Timer('Emp_Timer');
   OG_Activate_Timer(My_Timer);
END;


OG_Deactivate_Timer

  Examples	  Related Topics

Description  This procedure deactivates the specified timer.

Syntax

PROCEDURE OG_Deactivate_Timer
  (timer_hdl  OG_Timer);

Parameters

timer_hdl	Is the handle to the timer.
Usage Notes  Note that when you open a display, all timers are activated automatically.  If you want a timer to be inactive, you must deactivate it explicitly by using this procedure.  It is often useful to deactivate timers when they are not required for the portion of the display being viewed.  Your system will then not waste time processing irrelevant timers.


OG_Deactivate_Timer Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have created timers to update all of your
**charts every 30 seconds, and that you have deactivated
**the timers for charts that are not displayed.
*/

PROCEDURE deactivate_emp_timer IS
   my_timer   OG_Timer;
BEGIN
   my_timer:=OG_Get_Timer('Emp_Timer');
   OG_Deactivate_Timer(My_Timer);
END;


OG_Destroy (Timer)

  Examples	  Related Topics

Description  This procedure destroys the specified timer.

Syntax

PROCEDURE OG_Destroy
  (timer_hdl  OG_Timer);

Parameters

timer_hdl	Is the handle to the timer to destroy.


OG_Destroy (Timer) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure destroys the specified timer:
*/

PROCEDURE destroy_timer(timer_name VARCHAR2) IS
  timer  OG_Timer;
BEGIN
  timer := OG_Get_Timer(Timer_Name);
  OG_Destroy(Timer);
END;


OG_Get_Timer

  Examples	  Related Topics

Description  This function returns a handle to the specified timer.

Syntax

FUNCTION OG_Get_Timer
  (timer_name  VARCHAR2)
RETURN OG_Timer;

Parameters

timer_name	Is the name of the timer whose handle is returned.
Returns  A handle to the specified timer.  If the timer does not exist, this function will return a null handle.


OG_Get_Timer Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have created timers to update all of your
**charts every 30 seconds, and that you have deactivated
**the timers for charts that are not displayed.  When you
**display a chart, however, you want to re-activate its timer.
*/

PROCEDURE activate_emp_timer IS
   my_timer   OG_Timer;
BEGIN
   my_timer:=OG_Get_Timer('Emp_Timer');
   OG_Activate_Timer(My_Timer);
END;


OG_Make_Timer

  Examples	  Related Topics

Description  This function creates a timer.

Syntax

FUNCTION OG_Make_Timer
  (interval   OG_Point,
   timerproc  VARCHAR2
RETURN OG_Timer;

Parameters

interval	Is the interval (in seconds) at which the timer is fired.
timerproc	Is the name of the procedure to execute at the timed interval.
Returns  A handle to the newly created timer.


OG_Make_Timer Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure creates a timer that executes
**the procedure 'update_proc' every 30 seconds.
*/

PROCEDURE example(timer_name VARCHAR2) IS
  timer  OG_Timer;
BEGIN
  timer := OG_Make_Timer(30, 'update_proc');
  OG_Set_Name(Timer, timer_name);
END;


TOOLS_INT Built-ins

Tool_Int.Add_Parameter

Tool_Int.Create_Parameter_List

Tool_Int.Delete_Parameter

Tool_Int.Destroy_Parameter_List

Tool_Int.Get_Parameter_Attr

Tool_Int.Get_Parameter_List

Tool_Int.Isnull

Tool_Int.Run_Product

Tool_Int.Set_Parameter_Attr


TOOL_INT.ADD_PARAMETER

  Examples	  Related Topics

Description  This procedure adds a parameter to the specified parameter list.

Syntax

PROCEDURE TOOL_INT.add_parameter
  (list_hdl    TOOL_INT.PARAMLIST,
   param_name  CHAR,
   attr        TOOL_INT.PARAM_ATTR);

PROCEDURE TOOL_INT.add_parameter
  (list_hdl    TOOL_INT.PARAMLIST,
   param_name  CHAR,
   attr        TOOL_INT.PARAM_ATTR);

PROCEDURE TOOL_INT.add_parameter
  (list_hdl    TOOL_INT.PARAMLIST,
   param_name  CHAR,
   param_type  NUMBER,
   value       CHAR);

Parameters

list_hdl	Is the handle to the parameter list.
param_name	Is the name of the parameter to add.
attr	Is the parameter attribute record that contains the type and value of the parameter to add.
param_type	Is the type of the parameter to add.  The value of this argument may be one of the following built-in constants: TOOL_INT.DATA_PARAMETER   Means the parameter represents a mapping of a query from one product to the other. TOOL_INT.TEXT_PARAMETER   Means the parameter is a single value.
value	Is the value of the parameter to add.
Usage Notes  You can provide either a parameter attribute record that contains the parameter's type and value, or you can specify the type and value directly in this procedure call.


Tool_Int.Add_Parameter Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure creates a parameter list and
**adds several parameters to it:
*/

PROCEDURE create_plist IS
  the_list  tool_int.paramlist;
BEGIN
  the_list:=tool_int.create_parameter_list('my_plist');
  tool_int.add_parameter(the_list, 'userid',
    TOOL_INT.TEXT_PARAMETER, 'scott/tiger');
  tool_int.add_parameter(the_list, 'destype',
    TOOL_INT.TEXT_PARAMETER, 'printer');
  tool_int.add_parameter(the_list, 'copies',
    TOOL_INT.TEXT_PARAMETER, '2');
  tool_int.add_parameter(the_list, 'my_param',
    TOOL_INT.TEXT_PARAMETER, '67');
  tool_int.add_parameter(the_list, 'Q_1',
    TOOL_INT.DATA_PARAMETER, 'query0');
END;


TOOL_INT.CREATE_PARAMETER_LIST

  Examples	  Related Topics

Description  This function creates a new parameter list with the specified name.

Syntax

FUNCTION TOOL_INT.create_parameter_list
  (name  CHAR)
RETURN TOOL_INT.PARAMLIST;

Parameters

name	Is the name of the parameter list to create.
Returns  A handle to the newly created parameter list.


Tool_Int.Create_Parameter_List Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure creates a parameter list and
**adds several parameters to it:
*/

PROCEDURE create_plist IS
  the_list  tool_int.paramlist;
BEGIN
  the_list:=tool_int.create_parameter_list('my_plist');
  tool_int.add_parameter(the_list, 'userid',
    TOOL_INT.TEXT_PARAMETER, 'scott/tiger');
  tool_int.add_parameter(the_list, 'destype',
    TOOL_INT.TEXT_PARAMETER, 'printer');
  tool_int.add_parameter(the_list, 'copies',
    TOOL_INT.TEXT_PARAMETER, '2');
  tool_int.add_parameter(the_list, 'my_param',
    TOOL_INT.TEXT_PARAMETER, '67');
  tool_int.add_parameter(the_list, 'Q_1',
    TOOL_INT.DATA_PARAMETER, 'query0');
END;


TOOL_INT.DELETE_PARAMETER

  Examples	  Related Topics

Description  This procedure deletes the specified parameter from the specified parameter list.

Syntax

PROCEDURE TOOL_INT.delete_parameter
  (list_hdl    TOOL_INT.PARAMLIST,
   param_name  CHAR);

Parameters

list_hdl	Is the handle to the parameter list from which to delete the parameter.
param_name	Is the name of the parameter to delete.


Tool_Int.Delete_Parameter Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure deletes the parameter 'username' from a parameter list:
*/

PROCEDURE example IS
  list  tool_int.paramlist;
BEGIN
  list := tool_int.get_parameter_list('list0');
  tool_int.delete_parameter(list, 'username');
END;


TOOL_INT.DESTROY_PARAMETER_LIST

  Examples	  Related Topics

Description  This procedure destroys the specified parameter list.

Syntax

PROCEDURE TOOL_INT.destroy_parameter_list
  (list_hdl  TOOL_INT.PARAMLIST);

Parameters

list_hdl	Is the handle to the parameter list to destroy.


Tool_Int.Destroy_Parameter_List Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure creates a parameter list,
**first destroying an existing list (if any):
*/

PROCEDURE example IS
  list  tool_int.paramlist;
BEGIN
  list := tool_int.get_parameter_list('list0');

  IF NOT tool_int.isnull(list) THEN
    tool_int.destroy_parameter_list(list);
  END IF;

  list := tool_int.create_parameter_list('list0');
END;


TOOL_INT.GET_PARAMETER_ATTR

  Examples	  Related Topics

Description  This procedure gets the attributes of the specified parameter in the specified parameter list.

Syntax

PROCEDURE TOOL_INT.get_parameter_attr
  (list_hdl    TOOL_INT.PARAMLIST,
   param_name  CHAR,
   attr        TOOL_INT.PARAM_ATTR);

PROCEDURE TOOL_INT.get_parameter_attr
  (list_hdl    TOOL_INT.PARAMLIST,
   param_name  CHAR,
   param_type  NUMBER,
   value       CHAR);

Parameters

list_hdl	Is the handle to the parameter list from which to get the parameter.
param_name	Is the name of the parameter to get.
attr	Is the attribute record to be set to the parameter's attributes.
param_type	Is a variable that this procedure will set to be the parameter's type when it is called.  The value of this argument may be one of the following built-in constants: TOOL_INT.DATA_PARAMETER   Means the parameter represents a mapping of a query from one product to the other. TOOL_INT.TEXT_PARAMETER   Means the parameter is a single value.
value	Is a variable that this procedure will set to be the parameter's value when it is called.
Usage Notes  You can provide either a parameter attribute record that this procedure will set to the parameter's attributes, or you can provide separate variables that will be set.


Tool_Int.Get_Parameter_Attr Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure gets the value of the 'priority' parameter,
**and increases its value by one:
*/

PROCEDURE example IS
  list    tool_int.paramlist;
  ptype   NUMBER;
  pvalue  VARCHAR2;
BEGIN
  list := tool_int.get_parameter_list('list0');
  tool_int.get_parameter_attr(list, 'priority', ptype,
    pvalue);

  pvalue := to_char(to_number(pvalue) + 1);

  tool_int.set_parameter_attr(list, 'priority',
    tool_int.TEXT_PARAMETER, pvalue);

END;


TOOL_INT.GET_PARAMETER_LIST

  Examples	  Related Topics

Description  This function returns the handle to the parameter list with the specified name.

Syntax

FUNCTION TOOL_INT.get_parameter_list
  (list_name  CHAR)
RETURN TOOL_INT.paramlist;

Parameters

list_name	Is the name of the parameter list to get.
Returns  A handle to the named parameter list.


Tool_Int.Get_Parameter_List Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure creates a parameter list,
**first destroying an existing list (if any):
*/

PROCEDURE example IS
  list  tool_int.paramlist;
BEGIN
  list := tool_int.get_parameter_list('list0');

  IF NOT tool_int.isnull(list) THEN
    tool_int.destroy_parameter_list(list);
  END IF;

  list := tool_int.create_parameter_list('list0');
END;


TOOL_INT.ISNULL

  Examples	  Related Topics

Description  This function determines if the specified parameter list handle is a null handle.

Syntax

FUNCTION TOOL_INT.isnull
  (list_hdl  TOOL_INT.PARAMLIST)
RETURN BOOLEAN;

Parameters

list_hdl	Is the handle to be evaluated.
Returns TRUE	If the handle is null.
FALSE	If the handle is not null.
Usage Notes  TOOL_INT.GET_PARAMETER_LIST returns a null handle if the parameter list it attempts to get does not exist.


Tool_Int.Isnull Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure creates a parameter list,
**first destroying an existing list (if any):
*/

PROCEDURE example IS
  list  tool_int.paramlist;
BEGIN
  list := tool_int.get_parameter_list('list0');

  IF NOT tool_int.isnull(list) THEN
    tool_int.destroy_parameter_list(list);
  END IF;

  list := tool_int.create_parameter_list('list0');
END;


TOOL_INT.RUN_PRODUCT

  Examples	  Related Topics

Description  This procedure invokes another supported Oracle product.

Syntax

PROCEDURE TOOL_INT.run_product
  (product     NUMBER,
   module      CHAR,
   comm_mode   NUMBER,
   exec_mode   NUMBER,
   repository  NUMBER,
   list_hdl    TOOL_INT.PARAMLIST);

PROCEDURE TOOL_INT.run_product
  (product     NUMBER,
   module      CHAR,
   comm_mode   NUMBER,
   exec_mode   NUMBER,
   repository  NUMBER,
   list_name   CHAR);

Parameters

product	Is the Oracle product that will be invoked.  The value of this argument may be one of the following built-in constants: TOOL_INT.BOOK   Means invoke Oracle Book. TOOL_INT.FORMS   Means invoke Forms. TOOL_INT.REPORTS   Means invoke Reports.
module	Is the name of the module to be executed by the invoked product.  If the module is stored in the database, this argument should contain only the name of the module .  If the module is stored in the file system, this argument should contain the absolute or relative pathname of the module file.
comm_mode	Is the communication mode in which the product will be invoked.  The value of this argument may be one of the following built-in constants:  TOOL_INT.SYNCHRONOUS   Means the product is invoked synchronously. TOOL_INT.ASYNCHRONOUS   Means the product is invoked asynchronously.
exec_mode	Is the execution mode for the invoked product.  The value of this argument may be one of the following built-in constants: TOOL_INT.BATCH   Means the product is invoked in batch mode. TOOL_INT.RUNTIME   Means the product is invoked in runtime mode.
repository	Specifies whether the module is stored in the file system or database.  The value of this argument may be one of the following built-in constants:  TOOL_INT.DB   Means the module is stored in the database. TOOL_INT.FILESYSTEM   Means the module is stored in the filesystem.
list_hdl	Is the handle to the parameter list to be passed to the invoked product.
list_name	Is the name of the parameter list to be passed to the invoked product.
Usage Notes  For more information, refer to your Oracle product documentation.


Tool_Int.Run_Product Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure opens the Oracle Book document named
**`catalog' and jumps to the hypertext target sailboard:
*/

PROCEDURE call_book is
  list  tool_int.paramlist;
BEGIN
  list:=tool_int.create_parameter_list('plist');

  tool_int.add_parameter(list, 'target',
    tool_int.TEXT_PARAMETER, 'sailboard');

  tool_int.RUN_PRODUCT(tool_int.BOOK, 'catalog',
    tool_int.ASYNCHRONOUS, tool_int.RUNTIME,
    tool_int.FILESYSTEM, list);

END;


TOOL_INT.SET_PARAMETER_ATTR

  Examples	  Related Topics

Description  This procedure sets the attributes of the specified parameter in the specified parameter list.

Syntax

PROCEDURE TOOL_INT.set_parameter_attr
  (list_hdl    TOOL_INT.PARAMLIST,
   param_name  CHAR,
   attr        TOOL_INT.PARAM_ATTR);

PROCEDURE TOOL_INT.set_parameter_attr
  (list_hdl    TOOL_INT.PARAMLIST,
   param_name  CHAR,
   param_type  NUMBER,
   value       CHAR);

Parameters

list_hdl	Is the handle to the parameter list that contains the parameter.
param_name	Is the name of the parameter to set.
attr	Is the attribute record that contains the parameter's attributes to set.
param_type	Is the type to which to set the parameter.  The value of this argument may be one of the following built-in constants: TOOL_INT.DATA_PARAMETER   Means the parameter represents a mapping of a query from one product to the other. TOOL_INT.TEXT_PARAMETER   Means the parameter is a single value.
value	Is the value to which to set the parameter.
Usage Notes  You can provide either a parameter attribute record that this procedure will use to set the parameter's attributes, or you can provide separate variables that contain the attributes to be set.


Tool_Int.Set_Parameter_Attr Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure gets the value of the 'priority'
**parameter, and increases its value by one:
*/

PROCEDURE example IS
  list    tool_int.paramlist;
  ptype   NUMBER;
  pvalue  VARCHAR2;
BEGIN
  list := tool_int.get_parameter_list('list0');
  tool_int.get_parameter_attr(list, 'priority', ptype,
    pvalue);

  pvalue := to_char(to_number(pvalue) + 1);

  tool_int.set_parameter_attr(list, 'priority',
    tool_int.TEXT_PARAMETER, pvalue);

END;


Window Built-ins

OG_Destroy (Window)

OG_Get_Window

OG_Hide_Window

OG_Make_Window

OG_Show_Window


OG_Destroy (Window)

  Examples	  Related Topics

Description  This procedure destroys the specified window.  Destroying a window closes it, but does not affect its contents.

Syntax

PROCEDURE OG_Destroy
  (window_hdl  OG_Window);

Parameters

window_hdl	Is the handle to the window to destroy.


OG_Destroy (Window) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose a user selects a country in a map of the world,
**and the application creates a new window to display
**information about sales in that country.  When the user selects
**another country, you may want to destroy the old window
**and create another one containing information about the new country.
*/

PROCEDURE destroy_USA IS
   the_window   OG_Window;
BEGIN
   the_window:=OG_Get_Window('Usa_Window');
   OG_Destroy(The_Window);
END;


OG_Get_Window

  Examples	  Related Topics

Description  This function returns a handle to the specified window.

Syntax

FUNCTION OG_Get_Window
  (window_name  VARCHAR2)
RETURN OG_Window;

Parameters

window_name	Is the name of the window whose handle should be returned.
Returns  A handle to the specified window.  If the window does not exist, this function will return a null handle.

Usage Notes  The window may be the main window for the display (named "Main Layout") or one that has been created programmatically.


OG_Get_Window Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose the main window-which was previously hidden-contains information
**that is now useful to view.  The following procedure will show it:
*/

PROCEDURE show_main_window IS
   the_main_window   OG_Window;
BEGIN
   the_main_window:=OG_Get_Window('Main Layout');
   OG_Show_Window(The_Main_Window);
END;


OG_Hide_Window

  Examples	  Related Topics

Description  This procedure hides the specified window.

Syntax

PROCEDURE OG_Hide_Window
  (window_hdl  OG_Window);

Parameters

window_hdl	Is the handle to the window that should be hidden.
Usage Notes  Note that the window will not be destroyed.  As a result, you can hide the window when its contents are not useful, then show it again when they are.


OG_Hide_Window Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose the main layout window contains a chart that the user
**no longer needs to see.  The following procedure will hide it temporarily.
**Remember that this does not destroy the window; it will still exist
**and be available to be shown again when needed.
*/

PROCEDURE hide_main_window IS
   the_main_window   OG_Window;
BEGIN
   the_main_window:=OG_Get_Window('Main Layout');
   OG_Hide_Window(The_Main_Window);
END;


OG_Make_Window

  Examples	  Related Topics

Description  This function creates a window.

Syntax

FUNCTION OG_Make_Window
  (position  OG_Point,
   height    NUMBER,
   width     NUMBER)
RETURN OG_Window;

Parameters

position	Is the x- and y-coordinates of the window's upper left corner (in screen resolution units).
height	Is the height of the window (in screen resolution units)
width	Is the width of the window (in screen resolution units).
Returns  A handle to the newly created window.


OG_Make_Window Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates a 5"x4" window
**in the upper left corner of the screen:
*/

FUNCTION example(window_name VARCHAR2) RETURN OG_Window IS
  window  OG_Window;
  pos     OG_Point;
  height  NUMBER;
  width   NUMBER;
BEGIN
  pos.x := 0;
  pos.y := 0;
  width := 5 * OG_Get_Ap_Hscreen_Res;
  height := 4 * OG_Get_Ap_Vscreen_Res;

  window := OG_Make_Window(Pos, height, width);
  OG_Set_Name(Window, window_name);
  RETURN(window);
END;


OG_Show_Window

  Examples	  Related Topics

Description  This procedure shows the specified window.

Syntax

PROCEDURE OG_Show_Window
  (window_hdl  OG_Window);

Parameters

window_hdl	Is the handle to the window that should be shown.


OG_Show_Window Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose the main window-which was previously hidden
**contains information that is now useful to view.
**The following procedure will show it.
*/

PROCEDURE show_main_window IS
   the_main_window   OG_Window;
BEGIN
   the_main_window:=OG_Get_Window('Main Layout');
   OG_Show_Window(The_Main_Window);
END;


Graphic Object Built-ins

OG_Clone (Object)

OG_Damage (Object)

OG_Delete_Child

OG_Delete_Cmptext

OG_Delete_Point

OG_Delete_Property

OG_Delete_Smptext

OG_Destroy (Object)

OG_Draw

OG_Export_Drawing (Display)

OG_Export_Drawing (Object/Layer)

OG_Export_Drawing (Window)

OG_Export_Image

OG_Get_Char_Property

OG_Get_Child

OG_Get_Cmptext

OG_Get_Date_Property

OG_Get_Num_Property

OG_Get_Object

OG_Get_Point

OG_Get_Smptext

OG_Import_Drawing

OG_Import_Image

OG_Insert_Child

OG_Insert_Cmptext

OG_Insert_Point

OG_Insert_Smptext

OG_Make_Ellipse

OG_Make_Group

OG_Make_Image

OG_Make_Line

OG_Make_Poly

OG_Make_Rect

OG_Make_Rrect

OG_Make_Symbol

OG_Make_Text

OG_Move

OG_Point_In

OG_Point_Near

OG_Property_Exists

OG_Rotate

OG_Same

OG_Scale

OG_Set_Edgecolor

OG_Set_Fillcolor

OG_Set_Property

OG_Synchronize

OG_Update_Bbox


OG_Clone (Object)

  Examples	  Related Topics

Description  This function creates a new object that is identical to the specified object.

Syntax

FUNCTION OG_Clone
  (object_hdl   OG_Object,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE)
RETURN OG_Object;

Parameters

object_hdl	Is the handle to the object to be cloned.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Returns  The handle to the newly created object.


OG_Clone (Object) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have created an object, and you want to
** create another identical object without having to
**again specify the same properties.
*/

PROCEDURE dup_object(old_object IN OG_Object) IS
   new_object   OG_Object;
BEGIN
   new_object:=OG_Clone(Old_Object);
END;


OG_Damage (Object)

  Examples	  Related Topics

Description  This procedure damages an object on the layout.

Syntax

PROCEDURE OG_Damage
  (object_hdl  OG_Object);

Parameters

object_hdl	Is the handle to the object to damaged.


OG_Damage (Object) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*Suppose you want to move an object.  The default behavior of the built-in
**procedure OG_Move is to update the bounding boxes of all of the modified
**object's antecedants, including the layer on which the object resides.
**To update a layer's bounding boxes, Graphics Builder must examine every object
**on that layer.  If the layer contains a large number of objects,
**this operation can be very time-consuming.
*/

 /*To make your application more efficient, you can move the object
**while inhibiting this automatic bounding box update, then explicitly
**update only that object's bounding boxes.  (Note that since the
**automatic bounding box update does not occur, the bounding boxes
**of the object's antecedants may be inaccurate.)
*/

 /*When you modify an object with a FALSE bounding box update flag,
**you may also want to use a FALSE damage flag.  In this case,
**when you are through modifying the object, you would invoke
**OG_Damage to explicitly damage the object.
*/

PROCEDURE move_efficiently (the_object OG_Object) IS
   offset   OG_Point;
BEGIN
   offset.x:=OG_Inch;
   offset.y:=OG_Inch;
   OG_Move(The_Object, offset, FALSE, FALSE)
   OG_Update_Bbox(The_Object, OG_Bothbbox);
   OG_Damage(The_Object);
END;


OG_Delete_Child

  Examples	  Related Topics

Description  This procedure deletes one or more child objects from the specified group object.

Syntax

PROCEDURE OG_Delete_Child
  (group_hdl    OG_Object,
   indx         NUMBER,
   total        NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

group_hdl	Is the handle to the group object.
indx	Is the index of the first object to delete from the group's child list.
total	Is the total number of child objects to delete.
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  .To delete a child means only that the object will no longer be associated with its parent group; it does not mean that the child object will be destroyed.  The parent attribute in the deleted child's generic attribute record will be set to a null handle, and the child will no longer exist in the group's object list.  Note that an object that has a null handle for a parent will not be displayed on the layout.

You can delete a layer by treating the display's root object as a group, and by passing it and the layer index to this procedure.


OG_Delete_Child Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*Suppose you have a several objects representing products
**in a warehouse, and you want to move one of the products
**from one warehouse to another.  Your display may use a group
**comprised of the products to represent the inventory for each
**warehouse.  To move a product from one warehouse to another,
**you would want to get the handle to the product object,
**delete it from one warehouse group, and add it to another
**warehouse group.
*/

 /*Note that this procedure changes only the internal composition
**of the group objects.  To move or change the appearance of the
**product object, you must use other Graphics Builder built-in procedures.
*/

PROCEDURE move_prod(warehouse1 IN OG_Object, warehouse2 IN
OG_Object, prod_index IN number) IS
   the_prod   OG_Object;
BEGIN
   the_prod:=OG_Get_Child(Warehouse1, prod_index);
   OG_Delete_Child(Warehouse1, prod_index, 1);
   OG_Insert_Child(Warehouse2, the_prod, OG_Last);
END;


OG_Delete_Cmptext

  Examples	  Related Topics

Description  This procedure deletes one or more compound text elements from the specified text object.  As described in "Text Attributes," a compound text element represents one line of text in a text object.

Syntax

PROCEDURE OG_Delete_Cmptext
  (text_hdl     OG_Object,
   indx         NUMBER,
   total        NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text_hdl	Is the handle to the text object.
indx	Is the index within the text object of the first compound text element to delete from the compound text element list.
total	Is the total number of compound text elements to delete.
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  When you delete a compound text element, it and all of the simple text elements that compose it will be destroyed.


OG_Delete_Cmptext Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*Suppose you use a text object to display messages to the user.
**A previous part of your application produced two-line messages,
**but the part of the display that is currently being used produces
**only one-line messages.  You may want to delete the extraneous
**compound text element.
*/

PROCEDURE delete_msg_line(msg_object IN OG_Object,
line_index IN number) IS
BEGIN
   OG_Delete_Cmptext(Msg_Object, line_index, 1);
END;


OG_Delete_Point

  Examples	  Related Topics

Description  This procedure deletes one or more points from the specified polygon or polyline object.

Syntax

PROCEDURE OG_Delete_Point
  (poly_hdl     OG_Object,
   indx         NUMBER,
   total        NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

poly_hdl	Is the handle to the polygon or polyline object.
indx	Is the index of the first point to delete from the point list.
total	Is the total number of points to delete.
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  If the object was created in the Builder, the initial index values for the points will correspond to the order in which the mouse was selected when the object was drawn (with the first point having an index of 0).  Index values for points that were inserted programmatically will depend on the index that was specified when they were inserted.


OG_Delete_Point Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

/*Suppose you have several polygons on a map, each of which
**connects the cities along a specific distribution route.
**If a city is transferred from one distribution route to another,
**you would want to get the point representing that city,
**delete it from one polygon, and add it to another polygon.
*/

PROCEDURE move_city(route1 IN OG_Object, route2 IN
OG_Object, city_index IN number) IS
   the_city   OG_Point;
BEGIN
   the_city:=OG_Get_Point(Route1, city_index);
   OG_Delete_Point(Route1, city_index, 1);
   OG_Insert_Point(Route2, OG_Last, the_city);
END;


OG_Delete_Property

  Examples	  Related Topics

Description  This procedure deletes an object's user-defined property.

Syntax

PROCEDURE OG_Delete_Property
  (object_hdl  OG_Object,
   prop_name   VARCHAR2);

Parameters

object_hdl	Is the handle to the object whose property you want to delete.
prop_name	Is the name of the property to delete.


OG_Delete_Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure deletes the property 'priority'
** from every child object in a named group:
*/

PROCEDURE example(group_name VARCHAR2) IS
  group_obj    OG_Object;
  child_count  NUMBER;
  child_obj    OG_Object;
BEGIN
  group_obj := OG_Get_Object(Group_Name);
  child_count := OG_Get_Childcount(Group_Obj);

  FOR i IN 0..child_count LOOP
    child_obj := OG_Get_Child(Group_Obj, i);
    OG_Delete_Property(Child_Obj, 'priority');
  END LOOP;
END;


OG_Delete_Smptext

  Examples	  Related Topics

Description  This procedure deletes one or more simple text elements from the specified compound text element in the specified text object.  As described in "Text Attributes," a simple text element represents a text string in a compound text element.

Syntax

PROCEDURE OG_Delete_Smptext
  (text_hdl     OG_Object,
   cmpindex     NUMBER,
   smpindex     NUMBER,
   total        NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text_hdl	Is the handle to the text object.
Cmpindex	Is the index of the compound text element that contains the simple text element(s) to delete.
smpindex	Is the index of the first simple text element to delete
total	Is the total number of simple text elements to delete.
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  Deleting simple text will not affect the existence or index of its compound text element.  It is possible, in fact, to delete all of the simple text for a compound text element, and be left with an empty compound text element.


OG_Delete_Smptext Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

/*Suppose you have created a message text object.  To change
**the message it contains, you would delete the simple text element
**containing the current message and insert a new simple text element
**containing the new message.  To maintain the font and other attributes,
**however, you first would want to get the simple text element into an
**attribute record.  That way, you could modify only the text string,
**and leave the other attribute settings (such as font) unchanged.
*/

PROCEDURE put_msg(mess IN VARCHAR2) IS
  msgobj    OG_Object;
  msgrec    OG_Smptext_Attr;
BEGIN
  msgobj := OG_Get_Object(’msg’);
  OG_Get_Smptext(msgobj, 0, 0, msgrec);
  OG_Delete_Smptext(msgobj, 0, 0, 1);
  msgrec.mask:= OG_STR_SMPTEXTA;
  msgrec.str:= mess;
  OG_Insert_Smptext(msgobj, msgrec, 0, OG_LAST);
END;


OG_Destroy (Object)

  Examples	  Related Topics

Description  This procedure destroys the specified object  If you destroy a group object, all of that group's children are also destroyed

Syntax

PROCEDURE OG_Destroy
  (object_hdl   OG_Object,
   recurse      BOOLEAN    :=  FALSE,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

object_hdl	Is the handle to the object to destroy.
Recurse	Is the recursive-destroy flag.  This argument is optional; its value will default to FALSE if not otherwise specified.  Also, this argument is ignored if the object you are destroying is not the only child of a group.
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  .If the object you are destroying is the only child of a group, a recurse value of TRUE indicates that that parent group also should be destroyed.  This action will continue up the object's group tree (i.e., if the object's parent is the only child of its parent group, then that parent group also will be destroyed, etc.).  Finally, if the last object on a layer is destroyed, the layer itself is also destroyed (unless it is active in some window).

If recurse is FALSE, only the object specified by object_hdl will be destroyed.


OG_Destroy (Object)  Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure destroys the specified object:
*/

PROCEDURE destroy_obj(obj_name VARCHAR2) IS
  object  OG_Object;
BEGIN
  object := OG_Get_Object(Obj_Name);
  OG_Destroy(Object);
END;


OG_Draw

  Examples	  Related Topics

Description  This procedure causes the specified object to be drawn on the layout.

Syntax

PROCEDURE OG_Draw
  (object_hdl  OG_Object);

Parameters

object_hdl	Is the handle to the object to draw.
Usage Notes  Unlike other procedures that modify objects, this procedure does not "damage" a rectangular area on the layout.  It draws only the specified object, and disturbs nothing else.

The benefit of using this procedure is that you can have an object appear on the layout, while preventing Graphics Builder from re-drawing a rectangular damage region that may be larger than necessary.


OG_Draw Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

/*Suppose you want to clone an object and have it appear on the
**layout smoothly, without causing a damage region to be redrawn.
**First, you would create the object by calling OG_Clone with a FALSE
**damage flag .  Then, you can make the object appear on the layout
**by calling OG_Draw.
*/

PROCEDURE clone_object IS
   the_object   OG_Object;
   new_object   OG_Object;
BEGIN
   the_object:=OG_Get_Object('My_Object');
   new_object:=OG_Clone(The_Object, FALSE);
   OG_Draw(new_object);
END;


OG_Export_Drawing (Display)

  Examples	  Related Topics

Description  This procedure exports the entire layout (including hidden layers0 as a drawing.

Syntax

PROCEDURE OG_Export_Drawing
  (name         VARCHAR2,
   repository   NUMBER,
   format       NUMBER,
   compression  NUMBER    :=  OG_No_Icompression);

Parameters

name	Is the name to which the drawing will be exported.  If the drawing is to be stored in the database, this argument should contain only the name of the drawing.  If the drawing is to be stored in the file system, this argument should contain the absolute or relative pathname of the drawing file.
repository	Specifies whether the drawing is to be stored in the file system or database.  The value of this argument may be one of the following built-in constants: OG_Db   Means the drawing is to be stored in the database. OG_Filesystem   Means the drawing is to be stored in the file system.
format	Specifies the format in which the drawing is exported.  The value of this argument may be one of the following built-in constants: OG_Cgm16_Dformat   Means the drawing is saved in the CGM 2-byte format. OG_Cgm32_Dformat   Means the drawing is saved in the CGM 4-byte format. OG_Oracle_Dformat   Means the drawing is saved in the Oracle Format, used by other Oracle products.
compression	Is the type of compression used to compress images that are part of the drawing.  The value of this argument may be one of the following built-in constants:  OG_No_Icompression   Means images are not compressed. OG_H3g_Icompression   Means images are compressed using CCITT Group 3 with Huffman encoding compression OG_G3fax_Icompression   Means images are compressed using Group 3 Fax compression.  This compression type is valid for monochrome images only. OG_G4fax_Icompression   Means images are compressed using Group 4 Fax compression.  This compression type is valid for monochrome images only. OG_Pack_Icompression   Means images are compressed using PackBits compression.  This compression type is valid for monochrome TIFF images only. OG_Lzwhdiff_Icompression   Means images are compressed using LZW compression with horizontal differencing. OG_Lzwnohdiff_Icompression   Means images are compressed using LZW compression without horizontal differencing. OG_Jpeg_Lowest_Icompression   Means images are compressed using JPEG compression resulting in the lowest compression ratio and highest quality. OG_Jpeg_Low_Icompression   Means images are compressed using JPEG compression resulting in a low compression ratio and high quality. OG_Jpeg_Medium_Icompression   Means images are compressed using JPEG compression resulting in a medium compression ratio and medium quality. OG_Jpeg_High_Icompression   Means images are compressed using JPEG compression resulting in a high compression ratio and low quality. OG_Jpeg_Highest_Icompression   Means images are compressed using JPEG compression resulting in the highest compression ratio and lowest quality.


OG_Export_Drawing (Display) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

/*Suppose you want to export the display contents to the CGM file
**`my_draw' so that you can later import it into some other application.
**The following procedure does this:
*/

PROCEDURE export_the_drawing IS
BEGIN
   OG_Export_Drawing('My_Draw', OG_Filesystem, OG_Cgm16_Dformat);
END;


OG_Export_Drawing (Object/Layer)

  Examples	  Related Topics

Description  This procedure exports the specified object or layer as a drawing.

Syntax

PROCEDURE OG_Export_Drawing
  (name         VARCHAR2,
   repository   NUMBER,
   format       NUMBER,
   object_hdl   OG_Object,
   compression  NUMBER     :=  OG_No_Icompression);

Parameters

name	Is the name to which the drawing will be exported.  If the drawing is to be stored in the database, this argument should contain only the name of the drawing.  If the drawing is to be stored in the file system, this argument should contain the absolute or relative pathname of the drawing file.
Repository	Specifies whether the drawing is to be stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the drawing is to be stored in the database. OG_Filesystem   Means the drawing is to be stored in the file system.
format	Specifies the format in which the drawing is exported.  The value of this argument may be one of the following built-in constants: OG_Cgm16_Dformat   Means the drawing is saved in the CGM 2-byte format. OG_Cgm32_Dformat   Means the drawing is saved in the CGM 4-byte format. OG_Oracle_Dformat   Means the drawing is saved in the Oracle Format, used by other Oracle products.
object_hdl	Is the handle to the object to be exported.  The object can be either a group or the object handle to a layer; the object and all of its descendants will be exported.  To specify a layer to export, use OG_Get_Object to specify an object handle to the layer.
Compression	Is the type of compression used to compress images that are part of the drawing.  The value of this argument may be one of the following built-in constants: OG_No_Icompression   Means images are not compressed. OG_H3g_Icompression   Means images are compressed using CCITT Group 3 with Huffman encoding compression OG_G3fax_Icompression   Means images are compressed using Group 3 Fax compression.  This compression type is valid for monochrome images only. OG_G4fax_Icompression   Means images are compressed using Group 4 Fax compression.  This compression type is valid for monochrome images only. OG_Pack_Icompression   Means images are compressed using PackBits compression.  This compression type is valid for monochrome TIFF images only. OG_Lzwhdiff_Icompression   Means images are compressed using LZW compression with horizontal differencing. OG_Lzwnohdiff_Icompression   Means images are compressed using LZW compression without horizontal differencing. OG_Jpeg_Lowest_Icompression   Means images are compressed using JPEG compression resulting in the lowest compression ratio and highest quality. OG_Jpeg_Low_Icompression   Means images are compressed using JPEG compression resulting in a low compression ratio and high quality. OG_Jpeg_Medium_Icompression   Means images are compressed using JPEG compression resulting in a medium compression ratio and medium quality. OG_Jpeg_High_Icompression   Means images are compressed using JPEG compression resulting in a high compression ratio and low quality. OG_Jpeg_Highest_Icompression   Means images are compressed using JPEG compression resulting in the highest compression ratio and lowest quality.


OG_Export_Drawing (Object/Layer) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to export the contents of `layer0' to the CGM file
** `my_draw' so that you can later import it into some other application.
** The following procedure does this:
*/

PROCEDURE export_the_drawing IS
   the_layer   OG_Object;
BEGIN
   the_layer:=OG_Get_Object('Layer0');
   OG_Export_Drawing('My_Draw', OG_Filesystem,
OG_Cgm16_Dformat, the_layer);
END;


OG_Export_Drawing (Window)

  Examples	  Related Topics

Description  This procedure exports the visible contents of the specified window as a drawing.

Syntax

PROCEDURE OG_Export_Drawing
  (name         VARCHAR2,
   repository   NUMBER,
   format       NUMBER,
   window_hdl   OG_Window,
   compression  NUMBER     :=  OG_No_Icompression);

Parameters:

name	Is the name to which the drawing will be exported.  If the drawing is to be stored in the database, this argument should contain only the name of the drawing.  If the drawing is to be stored in the file system, this argument should contain the absolute or relative pathname of the drawing file.
Repository	Specifies whether the drawing is to be stored in the file system or database.  The value of this argument may be one of the following built-in constants: OG_Db   Means the drawing is to be stored in the database. OG_Filesystem   Means the drawing is to be stored in the file system.
format	Specifies the format in which the drawing is exported.  The value of this argument may be one of the following built-in constants: OG_Cgm16_Dformat   Means the drawing is saved in the CGM 2-byte format. OG_Cgm32_Dformat   Means the drawing is saved in the CGM 4-byte format. OG_Oracle_Dformat   Means the drawing is saved in the Oracle Format, used by other Oracle products.
window_hdl	Is the handle to the window that contains the drawing to be exported.  All of the layers that are showing in the window will be exported.
Compression	Is the type of compression used to compress images that are part of the drawing.  The value of this argument may be one of the following built-in constants: OG_G3fax_Icompression   Means images are compressed using Group 3 Fax compression.  This compression type is valid for monochrome images only. OG_G4fax_Icompression   Means images are compressed using Group 4 Fax compression.  This compression type is valid for monochrome images only. OG_H3g_Icompression   Means images are compressed using CCITT Group 3 with Huffman encoding compression OG_Jpeg_High_Icompression   Means images are compressed using JPEG compression resulting in a high compression ratio and low quality. OG_Jpeg_Highest_Icompression   Means images are compressed using JPEG compression resulting in the highest compression ratio and lowest quality. OG_Jpeg_Low_Icompression   Means images are compressed using JPEG compression resulting in a low compression ratio and high quality. OG_Jpeg_Lowest_Icompression   Means images are compressed using JPEG compression resulting in the lowest compression ratio and highest quality. OG_Jpeg_Medium_Icompression   Means images are compressed using JPEG compression resulting in a medium compression ratio and medium quality. OG_Lzwhdiff_Icompression   Means images are compressed using LZW compression with horizontal differencing. OG_Lzwnohdiff_Icompression   Means images are compressed using LZW compression without horizontal differencing. OG_No_Icompression   Means images are not compressed. OG_Pack_Icompression   Means images are compressed using PackBits compression.  This compression type is valid for monochrome TIFF images only.


OG_Export_Drawing (Window) Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to export the contents of the `Main Layout'
** window to the CGM file `my_draw' so that you can later import it
** into some other application.  The following procedure does this:
*/

PROCEDURE export_the_drawing IS
   the_window   OG_Window;
BEGIN
   the_window:=OG_Get_Window('Main Layout');
   OG_Export_Drawing('My_Draw', OG_Filesystem,
OG_Cgm16_Dformat, the_window);
END;


OG_Export_Image

  Examples	  Related Topics

Description  This procedure exports a Graphics Builder object, surrounded by a one-half inch border, to an image.

Syntax

PROCEDURE OG_Export_Image
  (name         VARCHAR2,
   repository   NUMBER,
   format       NUMBER,
   image_hdl    OG_Object,
   compression  NUMBER     :=  OG_No_Icompression);

Parameters

name	Is the name to which the image will be exported.  If the image is to be stored in the database, this argument should contain only the name of the image.  If the image is to be stored in the file system, this argument should contain the absolute or relative pathname of the image file.
Repository	Specifies whether the image is to be stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the image is to be stored in the database. OG_Filesystem   Means the image is to be stored in the file system.
format	Specifies the format in which the image is to be exported.  The value of this argument may be one of the following built-in constants:  OG_Bmp_Iformat   Means the image is saved in the Windows/OS2 Bitmap format. OG_Cals_Iformat   Means the image is saved in the CALS Type 1 Raster format. OG_Gif_Iformat   Means the image is saved in the CompuServe GIF format.  You must compress GIF files using OG_Lzwhdiff_Icompression. OG_Jfif_Iformat   Means the image is saved in the JPEG File Image Format. OG_Pict_Iformat   Means the image is saved in the Macintosh PICT format. OG_Ras_Iformat   Means the image is saved in the SUN Raster format. OG_Tiff_Iformat   Means the image is saved in the Tag Image File Format.
image_hdl	Is the handle to the image object that will be exported.  Can be any Graphics Builder object.
Compression	Is the type of compression used.  The value of this argument may be one of the following built-in constants:  OG_G3fax_Icompression   Means the image is compressed using Group 3 Fax compression.  This compression type is valid for monochrome images only. OG_G4fax_Icompression   Means the image is compressed using Group 4 Fax compression.  This compression type is valid for monochrome images only. OG_H3g_Icompression   Means the image is compressed using CCITT Group 3 with Huffman encoding compression OG_Jpeg_High_Icompression   Means the image is compressed using JPEG compression resulting in a high compression ratio and low quality. OG_Jpeg_Highest_Icompression   Means the image is compressed using JPEG compression resulting in the highest compression ratio and lowest quality. OG_Jpeg_Low_Icompression   Means the image is compressed using JPEG compression resulting in a low compression ratio and high quality. OG_Jpeg_Lowest_Icompression   Means the image is compressed using JPEG compression resulting in the lowest compression ratio and highest quality. OG_Jpeg_Medium_Icompression   Means the image is compressed using JPEG compression resulting in a medium compression ratio and medium quality. OG_Lzwhdiff_Icompression   Means the image is compressed using LZW compression with horizontal differencing.  You must use this type of compression on GIF files. OG_Lzwnohdiff_Icompression   Means the image is compressed using LZW compression without horizontal differencing. OG_No_Icompression   Means the image is not compressed. OG_Pack_Icompression   Means the image is compressed using Packbits compression.  This compression type is valid for monochrome TIFF images only.


OG_Export_Image Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to export the image named `image0' to the TIFF file
**`my_image' so that you can later import it into some other application
**The following procedure does this:
*/

 PROCEDURE export_the_image IS
   the_image   OG_Object;
BEGIN
   the_image:=OG_Get_Object('image0');
   OG_Export_Image('my_image', OG_Filesystem,
      OG_Tiff_Iformat, the_image);
END;


OG_Get_Char_Property

  Examples	  Related Topics

Description  This procedure gets the value of a user-defined CHAR property of an object.

Syntax

FUNCTION OG_Get_Char_Property
  (object_hdl  OG_Object,
   prop_name   VARCHAR2)
RETURN VARCHAR2;

Parameters

object_hdl	Is the handle to the object containing the property you want to get.
prop_name	Is the name of the property whose value you want to get.
Returns  The value of the specified property.


OG_Get_Char_Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure gets the 'status' property
**in each child object in a group, and then changes
**the object’s color if the status is 'obsolete':
*/

PROCEDURE example(group_name VARCHAR2) IS
  group_obj    OG_Object;
  child_count  NUMBER;
  child_obj    OG_Object;
  stat         VARCHAR2(10);
BEGIN
  group_obj := OG_Get_Object(Group_Name);
  child_count := OG_Get_Childcount(Group_Obj);

  FOR i IN 0..child_count LOOP
    child_obj := OG_Get_Child(Group_Obj, i);
    stat := OG_Get_Char_Property(Child_Obj, 'status');
    IF stat = 'obsolete' THEN
      OG_Set_Fillcolor(Child_Obj, 'red');
    END IF;
  END LOOP;

END;


OG_Get_Child

  Examples	  Related Topics

Description  This function returns a handle to a child object within a group object.

Syntax

FUNCTION OG_Get_Child
  (group_hdl  OG_Object,
   indx       NUMBER)
RETURN OG_Object;

Parameters

group_hdl	Is the handle to the group object containing the child.
indx	Is the index of the object in the group's child list whose handle should be returned.
Returns  A handle to the specified child object within a group.


OG_Get_Child Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*Suppose you have a several objects representing products
**in a warehouse, and you want to move one of the products
**from one warehouse to another.  Your display may use a group
**comprised of the products to represent the inventory for each
**warehouse.  To move a product from one warehouse to another,
**you would want to get the handle to the product object, delete it
**from one warehouse group, and add it to another warehouse group.
*/

PROCEDURE move_prod(warehouse1 IN OG_Object, warehouse2 IN
OG_Object, prod_index in number) IS
   the_prod   OG_Object;
BEGIN
   the_prod:=OG_Get_Child(Warehouse1, prod_index);
   OG_Delete_Child(Warehouse1, prod_index, 1);
   OG_Insert_Child(Warehouse2, the_prod, OG_Last);
END;

 /*Note that this procedure changes only the internal composition
**of the group objects.  To move or change the appearance of the
**product object, you must use other Graphics Builder built-in procedures.
*/


OG_Get_Cmptext

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified compound text element and assigns them to the corresponding fields in the specified compound text attribute record.  As described in "Text Attributes," a compound text element represents one line of text in a text object.

Syntax

PROCEDURE OG_Get_Cmptext
  (text_hdl          OG_Object,
   indx              NUMBER,
   attr      IN OUT  OG_Cmptext_Attr);

Parameters

text_hdl	Is the handle to the text object.
indx	Is the index of the compound text element in the compound text element list whose attributes you want to retrieve.
attr	Is the compound text attribute record that will receive the compound text element's attributes.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to OG_Get_Cmptext.


OG_Get_Cmptext Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to determine how many simple text elements
**compose the first compound text element within a text object.
**Knowing this, you can loop through and examine each simple text element.
*/

FUNCTION how_many(my_text IN OG_Object) RETURN NUMBER IS
   ctext_rec   OG_Cmptext_Attr;
BEGIN
   ctext_rec.mask:=OG_Stcount_Cmptexta;
   OG_Get_Cmptxt(My_Text, 0, ctext_rec);
   RETURN(ctext_rec.stcount);
END;


OG_Get_Date_Property

  Examples	  Related Topics

Description  This procedure gets the value of a user-defined DATE property of an object.

Syntax

FUNCTION OG_Get_Date_Property
  (object_hdl  OG_Object,
   prop_name   VARCHAR2,
   date_fmt    VARCHAR2   := 'DD-MON-YY')
RETURN DATE;

Parameters

object_hdl	Is the handle to the object containing the property you want to get.
prop_name	Is the name of the property whose value you want to get.
date_fmt	Is the date format mask used to set the date property with OG_Set_Property.
Returns  The value of the specified property.


OG_Get_Date_Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure gets the 'due_date' property in each child object
**in a group, and then changes the object's color if the due date has past:
*/

PROCEDURE example(group_name VARCHAR2) IS
  group_obj    OG_Object;
  child_count  NUMBER;
  child_obj    OG_Object;
  due          DATE;
BEGIN
  group_obj := OG_Get_Object(Group_Name);
  child_count := OG_Get_Childcount(Group_Obj);

  FOR i IN 0..child_count-1 LOOP
    child_obj := OG_Get_Child(Group_Obj, i);
    due := OG_Get_Date_Property(Child_Obj, 'due_date');
    IF due < sysdate THEN
      OG_Set_Fillcolor(Child_Obj, 'red');
    END IF;
  END LOOP;

END;


OG_Get_Num_Property

  Examples	  Related Topics

Description  This procedure gets the value of a user-defined NUMBER property of an object.

Syntax

FUNCTION OG_Get_Num_Property
  (object_hdl  OG_Object,
   prop_name   VARCHAR2)
RETURN NUMBER;

Parameters

object_hdl	Is the handle to the object containing the property you want to get.
prop_name	Is the name of the property whose value you want to get.
Returns  The value of the specified property.


OG_Get_Num_Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure gets the 'priority' property in each child object
**in a group, and then sets the priority to one greater than its current value:
*/

PROCEDURE example(group_name VARCHAR2) IS
  group_obj    OG_Object;
  child_count  NUMBER;
  child_obj    OG_Object;
  current_p    NUMBER;
BEGIN
  group_obj := OG_Get_Object(Group_Name);
  child_count := OG_Get_Childcount(Group_Obj);

  FOR i IN 0..child_count-1 LOOP
    child_obj := OG_Get_Child(Group_Obj, i);
    current_p := OG_Get_Num_Property(Child_Obj, 'priority');
    OG_Set_Property(Child_Obj, 'priority', current_p + 1);
  END LOOP;

END;


OG_Get_Object

  Examples	  Related Topics

Description  The object may be an arc, chart, group, image, line, polygon, rectangle, rounded rectangle, symbol, or text object.  The object must be created and named either in the Builder or programmatically prior to retrieving it with this function.  If the specified object does not exist, this function will return a null handle.

Syntax

FUNCTION OG_Get_Object
  (object_name  VARCHAR2)
RETURN OG_Object;

FUNCTION OG_Get_Object
  (object_name  VARCHAR2,
   root_hdl     OG_Object)
RETURN OG_Object;

Parameters

object_name	Is the name of the object whose handle should be returned.  Note:  OBJECT_NAME is case-sensitive.
root_hdl	Is the handle to the object in whose group tree you want to search.
Returns  A handle to the specified object.

Usage Notes  If you do not specify root_hdl, Graphics Builder will begin the search with the display's actual root object, thus searching every object in the display for the one whose name is specified.  If you do specify root_hdl, Graphics Builder will search only in the group tree below that object for the named object.  You will get unpredictable results if multiple objects in the search path have the same name.

If object_name is the name of a layer, this function treats it as a group object and returns a handle to that group.  You can then use the group-related subprograms (OG_Insert_Child, OG_Delete_Child, etc.) to manipulate the objects on the layer.


OG_Get_Object Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have a map of the world and you want to change
**the color of one of the countries.  First, you would get the handle
**to the country object, then you would change its color.
*/

PROCEDURE color_country(country_name) IS
   my_object    OG_Object;
   obj_record   OG_Graphic_Ca;
BEGIN
   my_object:=OG_Get_Object(Country_Name);
   obj_record.graphic_caob.mask:=OG_None_Generica;
   obj_record.graphic_caoh.mask:=OG_Ffcolor_Graphica;
   obj_record.graphic_caoh.ffcolor:='red';
   OG_Set_Attr(My_Object, obj_record);
END;


OG_Get_Point

  Examples	  Related Topics

Description  This function returns a record containing the x- and y-coordinates of a point in the specified object.

Syntax

FUNCTION OG_Get_Point
  (object_hdl  OG_Object,
   indx        NUMBER
   rotated     BOOLEAN    :=  FALSE)
RETURN OG_Point;

Parameters

object_hdl	Is the handle to the object.
indx	Is the index of the point in the point list to be returned.
rotated	Specifies whether the point returned should reflect any rotation angle applied to the object.
Returns  The location of the specified point.

Usage Notes

Polygon: Returns indx'th point of the object.

Arc, Chart, Rectangle, Rounded Rectangle:  0 index returns top-left corner; 1 index returns top-right corner; 2 index returns bottom-right corner; 3 index returns bottom-left corner.

Text:  0 index returns top-left corner; 1 index returns top-right corner; 2 index returns bottom-right corner; 3 index returns bottom-left corner.

Line: 0 index returns start point; 1 index returns end point

Image, Group, Symbol:  Does not apply.

If the object was created in the Builder, the initial index values for the points will correspond to the order in which the mouse was selected when the object was drawn (with the first point having an index of 0).  Index values for points that were inserted programmatically will depend on the index that was specified when they were inserted.


OG_Get_Point Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have several polygons on a map, each of which connects
**the cities within a specific distribution area.  If a city is transferred from one
**distribution area to another, you would want to get a handle to the point
**representing that city, delete it from one polygon, and add it to another polygon.
*/

PROCEDURE move_city(area1 IN OG_Object, area2 IN OG_Object,
  city_index NUMBER) IS
   the_city   OG_Point;
BEGIN
   the_city:=OG_Get_Point(Area1, city_index);
   OG_Delete_Point(Area1, city_index, 1);
   OG_Insert_Point(Area2, OG_Last, the_city);
END;


OG_Get_Smptext

  Examples	  Related Topics

Description  This procedure gets the attribute values of the specified simple text element within the specified compound text element and the specified text object.  These attributes are then assigned to the corresponding fields in the specified simple text attribute record.  As described in "Text Attributes," a simple text element represents a text string in a compound text element.

Syntax

PROCEDURE OG_Get_Smptext
  (text_hdl          OG_Object,
   cmpindex          NUMBER,
   smpindex          NUMBER,
   attr      IN OUT  OG_Smptext_Attr);

Parameters

text_hdl	Is the handle to the text object.
Cmpindx	Is the index within the text object of the compound text element that contains the simple text element whose attributes should be retrieved.
Smpindex	Is the index within the compound text element of the simple text element whose attributes should be retrieved.
attr	Is the simple text attribute record that will receive the simple text element's attributes.
Usage Notes  The only attribute values that will be retrieved are those specified by the value of the mask attribute in the attribute record.  Fields in the attribute record for which the mask is not set will be unaffected by the call to OG_Get_Smptext.


OG_Get_Smptext Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have created a message text object.  To change the
**message it contains, you would delete the simple text element containing
**the current message and insert a new simple text element containing the
**new message.  To maintain the font and other attributes, however,
**you first would want to get the simple text element into an attribute record.
**That way you could modify only the text string, and leave the other attribute
**settings (such as font) unchanged.
*/

PROCEDURE put_msg (mess IN VARCHAR2) IS
   msgobj   OG_Object;
   msgrec   OG_Smptext_Attr;
BEGIN
   msgobj:=OG_Get_Object('Msg');
   msgrec.mask:=OG_Font_Smptexta+
                OG_Color_Smptexta;
   msgrec.font.mask:=OG_All_Fonta;
   OG_Get_Smptext(Msgobj, 0, 0, msgrec);
   OG_Delete_Smptext(Msgobj, 0, 0, 1, FALSE);
   msgrec.mask:=msgrec.mask + OG_Str_Smptexta;
   msgrec.str:=mess;
   OG_Insert_Smptext(Msgobj, msgrec, 0, OG_Last);
END;


OG_Import_Drawing

  Examples	  Related Topics

Description  This procedure imports a drawing.  It returns a handle to the first object in the drawing.

Syntax

FUNCTION OG_Import_Drawing
  (name         VARCHAR2,
   repository   NUMBER,
   format       NUMBER,
   use_colors   BOOLEAN,
   damage       BOOLEAN   :=  TRUE,
   update_bbox  BOOLEAN   :=  TRUE)
RETURN OG_Object;

FUNCTION OG_Import_Drawing
  (name         VARCHAR2,
   repository   NUMBER,
   format       NUMBER,
   use_colors   BOOLEAN,
   parent_hdl   OG_Object,
   damage       BOOLEAN   :=  TRUE,
   update_bbox  BOOLEAN   :=  TRUE)
RETURN OG_Object;

Parameters

name	Is the name of the drawing.  If the drawing is stored in the database, this argument should contain only the name of the drawing.  If the drawing is stored in the file system, this argument should contain the absolute or relative pathname of the drawing file.
Repository	Specifies whether the drawing is stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the drawing is stored in the database. OG_Filesystem   Means the drawing is stored in the file system.
format	Specifies the format in which the drawing is saved.  The value of this argument may be one of the following built-in constants: OG_Cgm_Dformat   Means the drawing is saved in the CGM format (either 2-byte or 4-byte). OG_Oracle_Dformat   Means the drawing is saved in the Oracle Format, used by other Oracle products.
use_colors	Specifies whether the drawing's color palette should be used.  If this argument is TRUE, the drawing's palette will be used.  If FALSE, the default Graphics Builder color palette will be used.
parent_hdl	Is the handle to a group object into which the imported drawing should be inserted as a child.  If this argument is not supplied, the drawing is inserted as a child of the root object (although it is not recognized as a layer until you activate or show it).
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Returns  A handle to the imported drawing.


OG_Import_Drawing Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to import the contents of the CGM file `my_draw'
**onto the layer `layer0'.  You can get the object handle to the layer,
**then use that for parent_hdl.  The following procedure does this:
*/

PROCEDURE import_the_drawing IS
   the_layer   OG_Object;
   dummy   OG_Object;
BEGIN
   the_layer:=OG_Get_Object('Layer0');
   dummy:=OG_Import_Drawing('My_Draw', OG_Filesystem,
OG_Cgm16_Dformat, FALSE, the_layer);
END;


OG_Import_Image

  Examples	  Related Topics

Description  This procedure imports an image onto the active layer in the active window.

Syntax

FUNCTION OG_Import_Image
  (name         VARCHAR2,
   repository   NUMBER,
   format       NUMBER,
   damage       BOOLEAN   :=  TRUE,
   update_bbox  BOOLEAN   :=  TRUE)
RETURN OG_Object;

Parameters

name	Is the name of the image.  If the image is stored in the database, this argument should contain only the name of the image.  If the image is stored in the file system, this argument should contain the absolute or relative pathname of the image file.
Repository	Specifies whether the image is stored in the file system or database.  The value of this argument may be one of the following built-in constants:  OG_Db   Means the image is stored in the database. OG_Filesystem   Means the image is stored in the file system.
format	Specifies the format in which the image is saved.  The value of this argument may be one of the following built-in constants: OG_Any_Iformat   Means Graphics Builder automatically determines the image's format.  Note:  Specify this format if your image was exported in the Oracle Format (now obsolete). OG_Bmp_Iformat   Means the image is saved in the BMP format. OG_Cals_Iformat   Means the image is saved in the CALS format. OG_Gif_Iformat   Means the image is saved in the GIF format. OG_Jfif_Iformat   Means the image is saved in the JFIF format. OG_Oracle_Sformat   Means the image is saved in the Oracle Format, used by other Oracle products. OG_Pcd_Iformat   Means the image is saved in the PCD format. OG_Pcx_Iformat   Means the image is saved in the PCX format. OG_Pict_Iformat   Means the image is saved in the PICT format. OG_Ras_Iformat   Means the image is saved in the Sun raster format. OG_Tiff_Iformat   Means the image is saved in the TIFF format.
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Returns  A handle to the imported image.


OG_Import_Image Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to import the contents of the TIFF file `my_image'
**onto the layer `layer0'.  The following procedure does this:
*/

PROCEDURE import_the_image IS
   the_image   OG_Object;
BEGIN
   OG_Activate_Layer(OG_Get_Layer('Layer0'));
   the_image:=OG_Import_Image('My_Image', OG_Filesystem,
     OG_Tiff_Iformat);
END;


OG_Insert_Child

  Examples	  Related Topics

Description  This procedure inserts a child object into the specified group object.  If the object to be inserted is already a child of another group object, Graphics Builder will first automatically delete the child from its current parent.

Syntax

PROCEDURE OG_Insert_Child
  (group_hdl    OG_Object,
   child_hdl    OG_Object,
   indx         NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

group_hdl	Is the handle to the group object into which the child should be inserted.
child_hdl	Is the handle to the object that should be inserted as a child.
indx	Is the index in the group's child list at which to insert the new child.  This argument must be an integer between 0 and n (inclusive), where n is the number of children in the group prior to the insertion.  The value of this argument may also be one of the following built-in constants:  OG_First   Means insert the object as the first child in the group (index = 0). OG_Last   Means insert the object as the last child in the group (index = the number of children in the group prior to the insertion).
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  You can insert an object into a layer by treating the layer as a group object, and passing its object handle to this procedure.  You can also create a new layer by inserting a group object into the display's root object.  However, Graphics Builder will not recognize that group as a layer until you explicitly show it by calling OG_Activate_Layer or OG_Show_Layer.

Note that Graphics Builder does not check for loops in group objects, which would result it you insert a group as a child of one of its descendants.  If this occurs, Graphics Builder will enter an infinite loop when it traverses the group tree to update the bounding boxes of the affected objects.

Note that this procedure changes only the internal composition of the group objects.  To move or change the appearance of the product object, you must use other Graphics Builder built-in procedures.


OG_Insert_Child Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have a several objects representing products in a warehouse,
**and you want to move one of the products from one warehouse to another.
**Your display may use a group comprised of the products to represent the
**inventory for each warehouse.  To move a product from one warehouse to
**another, you would want to get the handle to the product object, delete it
**from one warehouse group, and add it to another warehouse group.
*/

PROCEDURE move_prod (warehouse1 IN OG_Object, warehouse2 IN
  OG_Object, prod_index IN number) IS
   the_prod   OG_Object;
BEGIN
   the_prod:=OG_Get_Child(Warehouse1, prod_index);
   OG_Delete_Child(Warehouse1, prod_index, 1);
   OG_Insert_Child(Warehouse2, the_prod, OG_Last);
END;


OG_Insert_Cmptext

  Examples	  Related Topics

Description  This procedure inserts a new compound text element into the specified text object.  As described in "Text Attributes," a compound text element represents one line of text in a text object.

Syntax

PROCEDURE OG_Insert_Cmptext
  (text_hdl     OG_Object,
   indx         NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text_hdl	Is the handle to the text object.
indx	Is the index in the compound text element list within the text object at which to insert the new compound text element.  This argument must be an integer between 0 and n (inclusive), where n is the number of compound text elements in the text object prior to the insertion.  The value of this argument may also be one of the following built-in constants:  OG_First   Means insert the new compound text element at the beginning of the text object (index = 0). OG_Last   Means insert the new compound text element at the end of the text object (index = the number of compound text elements in the text object prior to the insertion).
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  The attributes of a compound text element are set automatically by Graphics Builder.  Therefore, you do not need to provide a compound text attribute record when creating new compound text.  (In constrast, if you want to get the element's attributes, you must provide OG_Get_Cmptext with a compound text attribute record to receive them.)


OG_Insert_Cmptext Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to create a text object that contains a message for
**the user.  The following function will create the object, insert a compound text
**element, then insert a simple text element that contains the text of the message.
*/

PROCEDURE make_text (the_message IN VARCHAR2) IS
   text_rec   OG_Text_Ca;
   text_obj   OG_Object;
   smp_rec    OG_Smptext_Attr;
BEGIN
   text_rec.text_caob.mask:=OG_None_Generica;
   text_rec.text_caoh.mask:=OG_None_Graphica;
   text_rec.text_caot.mask:=OG_None_Texta;
   text_obj:=OG_Make(Text_Rec);
   OG_Insert_Cmptext(Text_Obj, OG_Last);
   smp_rec.mask:=OG_Str_Smptexta;
   smp_rec.str:=the_message;
   OG_Insert_Smptext(Text_Obj, smp_rec, 0, OG_Last);
END;


OG_Insert_Point

  Examples	  Related Topics

Description  This procedure inserts a new point into the specified polygon object.

Syntax

PROCEDURE OG_Insert_Point
  (poly_hdl     OG_Object,
   indx         NUMBER,
   pt           OG_Point,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

poly_hdl	Is the handle to the polygon or polyline object.
indx	Is the index in the point list at which to insert the new point.  This argument must be an integer between 0 and n (inclusive), where n is the number of points in the object prior to the insertion.  The value of this argument may also be one of the following built-in constants:  OG_First   Means insert the new point at the beginning of the object's point list (index = 0). OG_Last   Means insert the new point at the end of the object's point list (index = the number of compound text elements in the text object prior to the insertion).
pt	Is the record containing the x- and y-coordinates of the point to be inserted.
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  If the object was created in the Builder, the initial index values for the points will correspond to the order in which the mouse was selected when the object was drawn (with the first point having an index of 0).  Index values for points that were inserted programmatically will depend on the index that was specified when they were inserted.


OG_Insert_Point Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have several polygons on a map, each of which connects
**the cities within a specific distribution area.  If a city is transferred from one
**distribution area to another, you would want to get a handle to the point
**representing that city, delete it from one polygon, and add it to another polygon.
*/

PROCEDURE move_city(area1 IN OG_Object, area2 IN OG_Object,
city_index IN NUMBER) IS
   the_city   OG_Point;
BEGIN
   the_city:=OG_Get_Point(Area1, city_index);
   OG_Delete_Point(Area1, city_index, 1);
   OG_Insert_Point(Area2, OG_Last, the_city);
END;


OG_Insert_Smptext

  Examples	  Related Topics

Description  This procedure inserts a new simple text element into the specified compound text element within the specified text object.  As described in "Text Attributes," a simple text element represents a text string in a compound text element.

Syntax

PROCEDURE OG_Insert_Smptext
  (textobj      OG_Object,
   smp_attr     OG_Smptext_Attr,
   cmpindex     NUMBER,
   smpindex     NUMBER,
   damage       BOOLEAN          :=  TRUE,
   update_bbox  BOOLEAN          :=  TRUE);

Parameters

text_hdl	Is the handle to the text object.
smp_attr	Is the attribute record for the simple text element to be inserted.
Cmpindex	Is the index of the compound text element within the text object into which the simple text should be inserted.
Smpindex	Is the index within the compound text element at which the new simple text element should be inserted.  This argument must be an integer between 0 and n (inclusive), where n is the number of simple text elements in the compound text element prior to the insertion.  The value of this argument may also be one of the following built-in constants: OG_First   Means insert the new simple text element at the beginning of the compound text element (index = 0). OG_Last   Means insert the new simple text element at the end of the compound text element (index = the number of simple text elements in the compound text element prior to the insertion).
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  The specified simple text element attribute record (smp_attr) contains the attributes for the simple text element, including the text string.  The only attribute values that will be set are those specified by the value of the mask attribute in that attribute record.


OG_Insert_Smptext Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to create a text object that contains a message
**for the user.  The following procedure will create the object, insert a
**compound text element, then insert a simple text element that contains
**the text of the message.
*/

PROCEDURE make_text (the_message IN VARCHAR2) IS
   text_rec   OG_Text_Ca;
   text_obj   OG_Object;
   smp_rec    OG_Smptext_Attr;
BEGIN
   text_rec.text_caob.mask:=OG_None_Generica;
   text_rec.text_caoh.mask:=OG_None_Graphica;
   text_rec.text_caot.mask:=OG_None_Texta;
   text_obj:=OG_Make(Text_Rec);
   OG_Insert_Cmptext(Text_Obj, OG_Last);
   smp_rec.mask:=OG_Str_Smptxta;
   smp_rec.str:=the_message;
   OG_Insert_Smptext(Text_Obj, smp_rec, 0, OG_Last);
END;


OG_Make_Ellipse

  Examples	  Related Topics

Description  This function creates an ellipse.

Syntax

FUNCTION OG_Make_Ellipse
  (position  OG_Point,
   height    NUMBER,
   width     NUMBER)
RETURN OG_Object;

Parameters

position	The x- and y-coordinates of the ellipse.
height	The ellipse height.
width	The ellipse width.
Returns  A handle to the newly created ellipse.


OG_Make_Ellipse Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates an ellipse:
*/

FUNCTION example RETURN OG_Object IS
  object  OG_Object;
  pos     OG_Point;
  height  NUMBER;
  width   NUMBER;
BEGIN
  pos.x := OG_Inch;
  pos.y := OG_Inch;
  height := 4* OG_Inch;
  width := 4* OG_Inch;

  object := OG_Make_Ellipse(Pos, height, width);
  RETURN(object);
END;


OG_Make_Group

  Examples	  Related Topics

Description  This function creates a group object (note that the group will be empty until you add children to it using OG_Insert_Child).

Syntax

FUNCTION OG_Make_Group
RETURN OG_Object;

Parameters:

None.

Returns  A handle to the newly created group.


OG_Make_Group Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates a group with the specified name:
*/

FUNCTION example(group_name VARCHAR2) RETURN OG_Object IS
  object  OG_Object;
BEGIN
  object := OG_Make_Group;
  OG_Set_Name(Object, group_name);
  RETURN(object);
END;


OG_Make_Image

  Examples	  Related Topics

Description  This function creates an image from data stored in a database table.

Syntax

FUNCTION OG_Make_Image
  (query       OG_Query,
   which_data  NUMBER,
   colname     VARCHAR2)
RETURN OG_Object;

Parameters

query	Is the handle to the query that retrieves the image from a table in a database.  Note that this table must be a user table, and not one the private tables used by Graphics Builder when you save or export a module to the database.
which_data	Specifies whether the image to be created is contained in a query's new or old data set.  This value may be one of the following built-in constants:  OG_Newdata   Means the image is contained in the query's new data set. OG_Olddata   Means the image is contained in the query's old data set.
Colname	Is the name of the query column that contains the image data.  The image that is created is the one contained in the query cell at the intersection of the column specified by this attribute and the row pointed to by the query's cursor.
Returns  A handle to the newly created image.


OG_Make_Image Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates an image from data in the sixth
**row of the query 'image_query' in the column IMAGE_COLUMN:
*/

FUNCTION example(image_name VARCHAR2) RETURN OG_Object IS
  query   OG_Query;
  object  OG_Object;
BEGIN
  query := OG_Get_Query('Image_Query');
  OG_Execute_Query(Query);
  OG_Start_From(Query, OG_Newdata, 5);
  object := OG_Make_Image(Query, OG_Newdata, 'IMAGE_COLUMN');

  OG_Set_Name(Object, image_name);
  RETURN(object);
END;


OG_Make_Line

  Examples	  Related Topics

Description  This function creates a line.

Syntax

FUNCTION OG_Make_Line
  (startpt  OG_Point,
   endpt    OG_Point)
RETURN OG_Object;

Parameters

startpt	Is the starting point of the line (in layout units).
endpt	Is the ending point of the line (in layout units).
Returns  A handle to the newly created line.


OG_Make_Line Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates a 2" horizontal line:
*/

FUNCTION example RETURN OG_Object IS
  object   OG_Object;
  startpt  OG_Point;
  endpt    OG_Point;
BEGIN
  startpt.x := OG_Inch;
  startpt.y := OG_Inch;
  endpt.x := 2 * OG_Inch;
  endpt.y := OG_Inch;

  object := OG_Make_Line(Startpt, endpt);
  RETURN(object);
END;


OG_Make_Poly

  Examples	  Related Topics

Description  This function creates a polygon/polyline object (note that the object will contain no points until you add them using OG_Insert_Point).

Syntax

FUNCTION OG_Make_Poly
RETURN OG_Object;

Parameters:

None.

Returns  A handle to the newly created polygon/polyline object.


OG_Make_Poly Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates a polygon with the specified name:
*/

FUNCTION example(poly_name VARCHAR2) RETURN OG_Object IS
  object  OG_Object;
BEGIN
  object := OG_Make_Poly;
  OG_Set_Name(Object, poly_name);
  RETURN(object);
END;


OG_Make_Rect

  Examples	  Related Topics

Description  This function creates a rectangle.

Syntax

FUNCTION OG_Make_Rect
  (position  OG_Point,
   height    NUMBER,
   width     NUMBER)
RETURN OG_Object;

Parameters

position	Is the x- and y-coordinates of the rectangle.
height	Is the height of the rectangle.
width	Is the width of the rectangle.
Returns  A handle to the newly created rectangle.


OG_Make_Rect Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates a rectangle:
*/

FUNCTION example RETURN OG_Object IS
  object  OG_Object;
  pos     OG_Point;
  height  NUMBER;
  width   NUMBER;
BEGIN
  pos.x := OG_Inch;
  pos.y := OG_Inch;
  height := 4* OG_Inch;
  width := 4* OG_Inch;

  object := OG_Make_Rect(Pos, height, width);
  RETURN(object);
END;


OG_Make_Rrect

  Examples	  Related Topics

Description  This function creates a rounded rectangle.

Syntax

FUNCTION OG_Make_Rrect
  (position  OG_Point,
   height    NUMBER,
   width     NUMBER)
RETURN OG_Object;

Parameters

position	Is the x- and y-coordinates of the rounded rectangle.
height	Is the height of the rounded rectangle.
width	Is the width of the rounded rectangle.
Returns  A handle to the newly created rounded rectangle.


OG_Make_Rrect Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates a rounded rectangle:
*/

FUNCTION example RETURN OG_Object IS
  object  OG_Object;
  pos     OG_Point;
  height  NUMBER;
  width   NUMBER;
BEGIN
  pos.x := OG_Inch;
  pos.y := OG_Inch;
  height := 4* OG_Inch;
  width := 4* OG_Inch;

  object := OG_Make_Rrect(Pos, height, width);
  RETURN(object);
END;


OG_Make_Symbol

  Examples	  Related Topics

Description  This function creates a symbol.

Syntax

FUNCTION OG_Make_Symbol
  (position  OG_Point,
   indx      NUMBER,
   symsize   NUMBER)
RETURN OG_Object;

Parameters

position	Is the symbol's center point.
indx	Is the index (or number) of the symbol's position as it appears in the symbol palette in the Builder.
Symsize	Is the symbol's size.  The value of this property may be one of the following built-in constants:  OG_Large_Symsize    OG_Medium_Symsize    OG_Small_Symsize
Returns  A handle to the newly created symbol.


OG_Make_Symbol Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates a symbol:
*/

FUNCTION example RETURN OG_Object IS
  symbol  OG_Object;
  pos     OG_Point;
BEGIN
  pos.x := OG_Inch;
  pos.y := OG_Inch;

  symbol := OG_Make_Symbol(Pos, 5, OG_Large_Symsize);
  RETURN(symbol);

END;


OG_Make_Text

  Examples	  Related Topics

Description  This function creates a text object.

Syntax

FUNCTION OG_Make_Text
  (position  OG_Point,
RETURN OG_Object;

OG_Make_Text
  (position  OG_Point,
   string    VARCHAR2)
RETURN OG_Object;

OG_Make_Text
  (position  OG_Point,
   string    VARCHAR2,
   ptsize    NUMBER)
RETURN OG_Object;

Parameters

position	Is the x- and y-coordinates of the text object.
string	Is the text string.
ptsize	Is the point size.
Returns  A handle to the newly created text object.


OG_Make_Text Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following function creates a text object:
*/

FUNCTION example RETURN OG_Object IS
  object  OG_Object;
  pos     OG_Point;
BEGIN
  pos.x := OG_Inch;
  pos.y := OG_Inch;
  object := OG_Make_Text(Pos, 'Sales Rankings');
  RETURN(object);
END;


OG_Move

  Examples	  Related Topics

Description  This procedure moves the specified object to another position on the layout.

Syntax

PROCEDURE OG_Move
  (object_hdl   OG_Object,
   offset       OG_Point,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

object_hdl	Is the handle to the object to move.
offset	Is the relative distance that the object should be moved from its current position.
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  Note that you are able to move the object off the layout by specifying an offset that results in negative coordinates.

Positive values for the x- and y- components of offset will move the object to the right and down.  Negative values will move the object to the left and up.

To move an object to an absolute position on the layout, set the new position in its appropriate attribute record.


OG_Move Examples

  Alphabetic List           [image]  All Examples     [image]  Related Topics

 /* Suppose you have an object that represents inventory in a warehouse.
**If the inventory is moved from one warehouse to another, you would
**want to move the object that represents it.
*/

PROCEDURE move_inventory(invent_obj IN OG_Object) IS
   distance   OG_Point;
BEGIN
   distance.x:=(3*OG_Inch);
   distance.y:=(3*OG_Inch);
   OG_Move(Invent_Obj, distance);
END;


OG_Point_In

  Examples	  Related Topics

Description  This function determines if the specified reference point lies within the fill region of an object.

Syntax

FUNCTION OG_Point_In
  (object_hdl  OG_Object,
   ref_pt      OG_Point,
   aperture    OG_Point)
RETURN OG_Object;

FUNCTION OG_Point_In
  (window_hdl  OG_Window,
   ref_pt      OG_Point,
   aperture    OG_Point)
RETURN OG_Object;

Parameters

object_hdl	Is the handle to the object to be checked.
window_hdl	Is the handle to the window to be checked.
ref_pt	Is the reference point.
Aperture	Is the maximum acceptable distance from the reference point (used only if object_hdl has a transparent fill).
Returns  If the specified reference point lies within the fill region of an object, the function returns the handle to that object.  If the point does not lie within an object's fill region, the function returns a null handle.

Usage Notes  This function is most useful when monitoring a user's mouse activity.  For example, you could write a button procedure for a group object and use the event record in the procedure header to determine the position of the mouse when it is selected or moved.  Then you could call OG_Point_In or OG_Point_Near and pass in the group object and the mouse coordinates as arguments.  The function will then return the single object in the group the user selected.

Note that this function determines only if the point lies within the fill region of an object.  If the point lies exactly on an object's edge, this function returns a null handle.  (This function assumes the object's edge to be the minimum possible thickness; the area covered by a thick edge is ignored.)  If the object has a transparent fill pattern (and therefore no fill region), this function defaults to the behavior of OG_Point_Near.  Note that the argument aperture is not used by OG_Point_In, but is passed on to OG_Point_Near if the object has a transparent fill pattern.

If a single object is specified as an argument, this function will check if the point lies within that object.  If a group object is specified, this function will check each member of the group (and subgroups) and return the top-most single object that the point lies within (or a null handle, if the point does not lie within any object in the group).  Note that a layer may be passed in as a group object.  Similarly, if a window is specified instead of an object, this function will check each object in the window.

If the point lies within more than one object, the object that is highest in its group tree is returned.


OG_Point_In Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose your application allows the user to select an object and drag it on
**top of other objects that are within a group.  When the user releases the mouse
**button, you want to determine which object the mouse is pointing to, and destroy it.
**The following procedure could be used as a button procedure for the object that was dragged.
*/

PROCEDURE destroy_target (hitobj IN OG_Object, buttonobj IN
OG_Object, win IN OG_Window, eventinfo IN OG_Event) IS
   the_group    OG_Object;
   aper         OG_Point;
   target_obj   OG_Object;
BEGIN
   IF eventinfo.event_type=OG_Mouse_Up THEN
      the_group:=OG_Get_Object('Big_Group');
      aper.x:=3*OG_App.HSCREEN_RES;   /* three pixels */
      aper.y:=3*OG_App.VSCREEN_RES;   /* three pixels */
      target_obj:=OG_Point_In(The_Group,
        eventinfo.mouse_position, aper);
      IF not(OG_Isnull(Target_Obj)) THEN
         OG_Destroy(Target_Obj);
      END IF;
   END IF;
END;


OG_Point_Near

  Examples	  Related Topics

Description  This function determines if the specified reference point lies along an object's edge.

Syntax

FUNCTION OG_Point_Near
  (object_hdl  OG_Object,
   ref_pt      OG_Point,
   aperture    OG_Point)
RETURN OG_Object;

FUNCTION OG_Point_Near
  (window_hdl  OG_Window,
   ref_pt      OG_Point,
   aperture    OG_Point)
RETURN OG_Object;

Parameters

object_hdl	Is the handle to the object to be checked.
window_hdl	Is the handle to the window to be checked.
ref_pt	Is the reference point.
Aperture	Is the maximum acceptable distance from the reference point.
Returns  If the specified reference point lies along an object's edge, the function returns the handle to that object.  If the point does not lie on an object's edge, the function returns a null handle.

Usage Notes  This function is most useful when monitoring a user's mouse activity.  For example, you could write a button procedure for a group object and use the event record in the procedure header to determine the position of the mouse when it is selected or moved.  Then you could call OG_Point_In or OG_Point_Near and pass in the group object and the mouse coordinates as arguments.  The function will then return the single object the user selected.

Note that if the object has a transparent edge pattern, this function returns a null handle.

If a single object is specified as an argument, this function will check if the point lies along the edge of that object.  If a group object is specified, this function will check each member of the group (and subgroups) and return the single object whose edge the point lies on (or a null handle, if the point does not lie along the edge of any object in the group).  Note that a layer may be passed in as a group object.  Similarly, if a window is specified instead of an object, this function will check each object in the window.

The argument aperture specifies the maximum distance that the reference point can be from an object's edge and still return the handle to that object.  If the area specified by the aperture extends onto the object's edge, OG_Point_Near will return the handle to the object.  Note that the aperture has both an x- and a y-component.

If the point lies within more than one object, the object that is highest in its group tree is returned.

Typically, you will use the aperture to give the user a margin of error, allowing for imprecise positioning of the mouse.  In this situation, you would set both the x- and y-components of the aperture to the same value, possibly the equivalent of three screen pixels.


OG_Point_Near Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose your application allows the user to select an object and drag it
**to the edge of other objects that are within a group.  When the user releases
**the mouse button, you want to determine which object's edge the mouse
**is pointing to, and destroy it. The following procedure could be used as a
**button procedure for the object that was dragged.
*/

PROCEDURE destroy_target (hitobj IN OG_Object, buttonobj IN
  OG_Object, win IN OG_Window, eventinfo IN OG_Event) IS
   the_group    OG_Object;
   aper         OG_Point;
   target_obj   OG_Object;
BEGIN
   IF eventinfo.event_type=OG_Mouse_Up THEN
      the_group:=OG_Get_Object('Big_Group');
      aper.x:=3*OG_App.HSCREEN_RES;   /* three pixels */
      aper.y:=3*OG_App.VSCREEN_RES;   /* three pixels */
      target_obj:=OG_Point_Near(The_Group,
        eventinfo.mouse_position, aper);
      IF not(OG_Isnull(Target_Obj)) THEN
         OG_Destroy(Target_Obj);
      END IF;
   END IF;
END;


OG_Property_Exists

  Examples	  Related Topics

Description  This function determines if a user-defined property has been created for a particular object.

Syntax

FUNCTION OG_Property_Exists
  (object_hdl  OG_Object,
   prop_name   VARCHAR2)
RETURN BOOLEAN;

Parameters

object_hdl	Is the handle to the object containing the property.
prop_name	is the name of the property whose existence you want to check.
Returns TRUE	If the property exists.
FALSE	If the property does not exist.


OG_Property_Exists Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure adds the property 'priority' to an object, if it doesn't already exist:
*/

PROCEDURE example(object OG_Object) IS
BEGIN
  IF NOT OG_Property_Exists(Object, 'priority') THEN
    OG_Set_Property(Object, 'priority', 10);
  END IF;
END;


OG_Rotate

  Examples	  Related Topics

Description  This procedure rotates the specified object by the specified number of degrees counter-clockwise.

Syntax

PROCEDURE OG_Rotate
  (object_hdl   OG_Object,
   center_pt    OG_Point,
   degrees      NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

object_hdl	Is the handle to the object to be rotated.
center_pt	Is the point on the layout to be used as the center of rotation.
Degrees	Is the number of degrees counter-clockwise the object should be rotated.
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


OG_Rotate Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you have a display that contains a dial.  The needle of the dial
**points at specific values along the face of the dial.  When the data changes,
**you may want to rotate the needle to point to a new value.
*/

PROCEDURE rotate_needle (degrees IN NUMBER,
  center_pt IN OG_Point) IS
   the_needle   OG_Object;
BEGIN
   the_needle:=OG_Get_Object('Needle 1');
   OG_Rotate(The_Needle, center_pt, degrees);
END;


OG_Same

  Examples	  Related Topics

Description  This function compares the two handles to see if they are the same.  For example, if you pass this function handles to two objects, it checks whether the two handles point to the same object.

Syntax

FUNCTION OG_Same                             object
  (handle1  OG_Object,
   handle2  OG_Object)
RETURN BOOLEAN;

FUNCTION OG_Same                             query
  (handle1  OG_Query,
   handle2  OG_Query)
RETURN BOOLEAN;

FUNCTION OG_Same                             chart template
  (handle1  OG_Template,
   handle2  OG_Template)
   RETURN BOOLEAN;

FUNCTION OG_Same                             button procedure
  (handle1  OG_Buttonproc,
   handle2  OG_Buttonproc)
RETURN BOOLEAN;

FUNCTION OG_Same                             sound
  (handle1  OG_Sound,
   handle2  OG_Sound)
RETURN BOOLEAN;

FUNCTION OG_Same                             window
  (handle1  OG_Window,
   handle2  OG_Window)
RETURN BOOLEAN;

FUNCTION OG_Same                             layer
  (handle1  OG_Layer,
   handle2  OG_Layer)
RETURN BOOLEAN;

FUNCTION OG_Same                             timer
  (handle1  OG_Timer,
   handle2  OG_Timer)
RETURN BOOLEAN;

FUNCTION OG_Same                             display
  (handle1  OG_Display,
   handle2  OG_Display)
RETURN BOOLEAN;

FUNCTION OG_Same                             axis
  (handle1  OG_Axis,
   handle2  OG_Axis)
RETURN BOOLEAN;

FUNCTION OG_Same                             field template
  (handle1  OG_Ftemp,
   handle2  OG_Ftemp)
RETURN BOOLEAN;

FUNCTION OG_Same                             reference line
  (handle1  OG_Refline,
   handle2  OG_Refline)
RETURN BOOLEAN;

Parameters

handle1	Is the first of two handles to compare.
handle2	Is the second of two handles to compare.
Returns TRUE	If the two handles are the same.
FALSE	If the two handles are not the same.
Usage Notes

This function is necessary because you cannot use "=" to compare the values of handles.  For eample, the following procedure is not legal:

PROCEDURE invalid (obj1 OG_Object, obj2 OG_Object) IS
BEGIN
   IF obj1 = obj2 THEN     --illegal comparison
      NULL;
   END IF;
END;


OG_Same Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to compare two objects to see if they are the same.
**The following function returns TRUE if they are the same and FALSE if they are not:
*/

FUNCTION compare (obj1 OG_Object, obj2 OG_Object) RETURN BOOLEAN IS
BEGIN
   IF OG_Same(Obj1, obj2) THEN
      RETURN(TRUE);
   ELSE
      RETURN(FALSE);
   END IF;
END;


OG_Scale

  Examples	  Related Topics

Description  This procedure resizes the specified object.

Syntax

PROCEDURE OG_Scale
  (object_hdl.  OG_Object,
   anchor       OG_Point,
   oldpt        OG_Point,
   newpt        OG_Point,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

object_hdl	Is the handle to the object to scale.
anchor	Is the anchor point of the object.
oldpt	Is the start point.
newpt	Is the end point.
Damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
Usage Notes  The scaling factor is calculated by taking the distance between the new point and the anchor point, and the distance between the old point and the anchor point.  The ratio of these two distances is the scaling factor.  A separate scaling factor is calculated for the x- and y-coordinates.

The relative position of each of the object's control points with respect to the anchor point will then be scaled by this factor.  Note that if the x- and y-scaling factors are equal, the object will be resized while maintaining its aspect ratio (e.g., a square will remain a square).

For example, to double the size of an object whose upper-left control point is at (OG_Inch, OG_Inch), you can use the following values:  anchor = (OG_Inch, OG_Inch), oldpt = (OG_Inch+1, OG_Inch+1), newpt = (OG_Inch+2, OG_Inch+2).  Thus, the x-scaling factor would be: (newpt.x-anchor.x) / (oldpt.x-anchor.x) = (OG_Inch+2-OG_Inch) / (OG_Inch+1-OG_Inch) = 2 / 1 = 2.  The y-scaling factor would be:  (newpt.y-anchor.y) / (oldpt.y-anchor.y) = (OG_Inch+2-OG_Inch) / (OG_Inch+1-OG_Inch) = 2 / 1 = 2.

The distance between the anchor point and each of the object's control points will then be scaled by this factor.  Following the above example, if the scale factor is 2 and the upper-right control point of the object is 1.5 inches to the right of the anchor point, the control point will be moved to a position that is 3 inches to the right of the anchor point.  The object's other control points will be moved in a similar manner.

Note that if a control point is used as an anchor point, its position will not change (since the distance between the control point and the anchor point would be 0).

You can also use this procedure to resize the specified object, as if you had used a Select tool to select on a control point and drag it to a new position on the layout.  The anchor point is the control point that does not move during the operation (the point diagonally opposite the point you would drag on the layout).  The control point you want to move is oldpt, and newpt is the new position to move it to.


OG_Scale Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to double the size of the object that the user selects.
**Assume the object's center is at (OG_Inch, OG_Inch), and use this point as
**the anchor.  The following button procedure will double the size of the object:
*/

PROCEDURE double (buttonobj IN OG_Object, hitobj IN
  OG_Object, win IN OG_Window, eventinfo IN OG_Event) IS
   anchor OG_Point;
   newpt OG_Point;
   oldpt OG_Point;
BEGIN
   anchor.x:=OG_Inch;
   anchor.y:=OG_Inch;
   oldpt.x:=OG_Inch+1;
   oldpt.y:=OG_Inch+1;
   newpt.x:=OG_Inch+2;
   newpt.y:=OG_Inch+2;
   OG_Scale(Hitobj, anchor, oldpt, newpt);
END;


OG_Set_Edgecolor

  Examples	  Related Topics

Description  This procedure sets the edge color of the specified object.  It sets the edge pattern to 'transparent', and the background edge color to the specified color.

Syntax

PROCEDURE OG_Set_Edgecolor
  (object       OG_Object,
   color        VARCHAR2
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

object	Is the handle to the object to change.
color	Is the name of the color.
Damage	Is the damage flag
update_bbox	Is the bounding box update flag.


OG_Set_Edgecolor Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the edge color of the specified object:
*/

PROCEDURE example(object OG_Object) IS
BEGIN
  OG_Set_Edgecolor(Object, 'red');
END;


OG_Set_Fillcolor

  Examples	  Related Topics

Description  This procedure sets the fill color of the specified object.  It sets the fill pattern to 'transparent', and the background fill color to the specified color.

Syntax

PROCEDURE OG_Set_Fillcolor
  (object       OG_Object,
   color        VARCHAR2
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

object	Is the handle to the object to change.
color	Is the name of the color.
Damage	Is the damage flag
update_bbox	Is the bounding box update flag.


OG_Set_Fillcolor Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure sets the fill color of the specified object:
*/

PROCEDURE example(object OG_Object) IS
BEGIN
  OG_Set_Fillcolor(Object, 'red');
END;


OG_Set_Property

  Examples	  Related Topics

Description  This procedure sets the value of an object's user-defined property.

Syntax

PROCEDURE OG_Set_Property                    date
  (object_hdl  OG_Object,
   prop_name   VARCHAR2,
   prop_value  VARCHAR2,
   date_fmt    VARCHAR2   := 'DD-MON-YY');

PROCEDURE OG_Set_Property                    number
  (object_hdl  OG_Object,
   prop_name   VARCHAR2,
   prop_value  NUMBER);

PROCEDURE OG_Set_Property                    char
  (object_hdl  OG_Object,:
   prop_name   VARCHAR2,
   prop_value  VARCHAR2,);

Parameters

object_hdl	Is the handle to the object whose property you want to set.
prop_name	Is the name of the property to set.
prop_value	Is the value to which the property will be set.
date_fmt	Is the date format mask for converting the prop_value character string into a date.
Usage Notes  If the property exists, this procedure changes its value.  If the property does not exist, this procedure creates it and sets its value without raising an error.


OG_Set_Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure gets the 'priority' property in each child object in a
**group, and then sets the priority to one greater than its current value:
*/

PROCEDURE example(group_name VARCHAR2) IS
  group_obj    OG_Object;
  child_count  NUMBER;
  child_obj    OG_Object;
  current_p    NUMBER;
BEGIN
  group_obj := OG_Get_Object(Group_Name);
  child_count := OG_Get_Childcount(Group_Obj);

  FOR i IN 0..child_count-1 LOOP
    child_obj := OG_Get_Child(Group_Obj, i);
    current_p := OG_Get_Num_Property(Child_Obj, 'priority');
    OG_Set_Property(Child_Obj, 'priority', current_p + 1);
  END LOOP;
END;


OG_Synchronize

  Examples	  Related Topics

Description  This procedure forces the damage regions in all windows to be redrawn.  It "synchronizes" the internal descriptions of all objects with their visual representations.

Syntax

PROCEDURE OG_Synchronize;

Parameters:

None.

Usage Notes  Note that in your own PL/SQL programs, an implicit OG_Synchronize is executed at the end of the highest level procedure or function that is invoked.


OG_Synchronize Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Suppose you want to move an object across the display in ten 1/4" increments.
**Instead of moving it multiple times and having it update visually only at the end
**of the procedure, you may want to "synchronize" the layout with the internal
**representation of the object after each move.
*/

PROCEDURE slide_across(the_object IN OG_Object) IS
   offset   OG_Point;
BEGIN
   offset.x:=(1/4)*OG_Inch;
   offset.y:=0;
   FOR i IN 1..10 LOOP
      move(the_object, offset);
      OG_Synchronize;
   END LOOP;
END;


OG_Update_Bbox

  Examples	  Related Topics

Description  This function updates an object's bounding box(es).  If the object is a group, the bounding boxes of all of its descendants are also updated.

Syntax

PROCEDURE OG_Update_Bbox
  (object_hdl  OG_Object,
   which_bbox  NUMBER);

Parameters

object_hdl	Is the handle to the object to update.
which_bbox	Specifies whether the inner or outer bounding box is updated.  The value of this argument may be one of the following built-in constants:  OG_Bothbbox   Means update both the inner and outer bounding boxes. OG_Innerbbox   Means update only the inner bounding box. OG_Outerbbox   Means update only the outer bounding box.


OG_Update_Bbox Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*Suppose you want to move an object.  The default behavior
**of the built-in procedure OG_Move is to update the bounding
**boxes of all of the modified object's antecedants, including
**the layer on which the object resides.  To update a layer's
**bounding boxes, Graphics Builder must examine every object on that layer.
**If the layer contains a large number of objects, this operation
**can be very time-consuming.*/

 /*To make your application more efficient, you can move the
**object while inhibiting this automatic bounding box update,
**then explicitly update only that object's bounding boxes.
**(Note that since the automatic bounding box update does not
**occur, the bounding boxes of the object's antecedants
**may be inaccurate.)
*/

/*When you modify an object with a FALSE bounding box update
**flag, you may also want to use a FALSE damage flag.  In this case,
**when you are through modifying the object, you would invoke
**OG_Damage to explicitly damage the object.
*/

PROCEDURE move_efficiently (the_object OG_Object) IS
   offset   OG_Point;
BEGIN
   offset.x:=OG_Inch;
   offset.y:=OG_Inch;
   OG_Move(The_Object, offset, FALSE, FALSE)
   OG_Update_Bbox(The_Object, OG_Bothbbox);
   OG_Damage(The_Object);

END;


Type Caption for New Topic Right Here
No built-in subprograms begin with this letter.


Alphabetic list of property built-in subprograms

Active Property (Timer)

Arrow Style Property (Line)

Auto Maximum Property (Axis, Continuous)

Auto Maximum Property (Axis, Date)

Auto Maximum Property (Axis, Discrete)

Auto Maximum Property (Frame, Table Chart)

Auto Minimum Property (Axis, Continuous)

Auto Minimum Property (Axis, Date)

Auto Minimum Property (Axis, Discrete)

Auto Minimum Property (Frame, Table Chart)

Auto Step Property (Axis, Continuous)

Auto Step Property (Axis, Date)

Auto Update Property (Chart)

Axis Label Property (Axis, Generic)

Axis Property (Field Template, Axis Chart)

Axis Property (Reference Line)

Axis Type Property (Axis, Generic)

Background Edge Color Property (Graphic)

Background Fill Color Property (Graphic)

Base Arc Property (Arc)

Base Rectangle Property (Rectangle)

Base Rectangle Property (Rounded Rectangle)

Baseline Axis Property (Frame, Axis Chart)

Baseline Value Property (Frame, Axis Chart)

Bevel Style Property (Graphic)

Bounding Box Width Property (Text)

Bounding Box Height Property (Text)

Button Procedure Property (Chart Element)

Button Procedure Property (Generic)

Cache Type Property (Query)

Cap Style Property (Graphic)

Categories Property (Frame, Pie Chart)

Category Date Format Property (Frame, Pie Chart)

Category Number Format Property (Frame, Pie Chart)

Category Width Property (Frame, Axis Chart)

Center Property (Symbol)

Character Set Property (Text)

Child Count Property (Group)

Clip Flag Property (Group)

Clip Rectangle Property (Image)

Close Trigger Property (Display)

Closure Property (Arc)

Closure Property (Polygon)

Color Property (Simple Text)

Color Property (Text)

Column Names Property (Frame, Table Chart)

Column Property (Generic)

Compound Text Count Property (Text)

Connection String Property (Application)

Connection String Property (Application)

Copies Property (Printer)

Corner Radii Property (Rounded Rectangle)

Cursor Property (Application)

Curve Fit Property (Field Template, Axis Chart)

Custom Date Format Property (Frame, Axis Chart)

Custom Format Property (Axis, Date)

Custom Label Property (Axis, Generic)

Custom Number Format Property (Frame, Axis Chart)

Custom Query Procedure Property (Query)

Custom Spacing Property (Text)

Dash Style Property (Graphic)

Data Values Property (Frame, Pie Chart)

Date Format Property (Axis, Discrete)

Date Format Property (Display)

Date Format Property (Query)

Date Value Property (Reference Line)

Day Format Property (Axis, Date)

Depth Size Property (Frame, Generic)

Direction Property (Axis, Generic)

Dither Property (Image)

Edge Pattern Property (Graphic)

Edge Width Property (Graphic)

End Page Property (Printer)

End Point Property (Line)

End Row Property (Chart)

Events Property (Chart Element)

Events Property (Generic)

Execute On Open Property (Query)

Execute On Timer Property (Query)

Execute Query Property (Generic)

Explosion Property (Chart Element)

Field Template Count Property (Frame, Generic)

Fill Pattern Property (Graphic)

Fill Property (Arc)

Filter Property (Chart)

First Month Property (Axis, Date)

Fixed Bounding Box Property (Text)

Foreground Edge Color Property (Graphic)

Foreground Fill Color Property (Graphic)

Font Property (Simple Text)

Format Trigger Property (Generic)

Frame Type Property (Frame, Generic)

Grid Count Property (Frame, Table Chart)

Height Property (Display)

Height Property (Image)

Height Property (Window)

Help Target Property (Window)

Horizontal Alignment Property (Text)

Horizontal Grid Property (Frame, Table Chart)

Horizontal Layout Resolution Property (Application)

Horizontal Origin Property (Text)

Horizontal Screen Resolution Property (Application)

Index Property (Symbol)

Inner Bounding Box Property (Generic)

Interval Property (Timer)

Invisible Property (Text)

Join Style Property (Graphic)

Kerning Property (Text)

Label Property (Reference Line)

Label Rotation Property (Field Template, Axis Chart)

Labels Property (Axis, Date)

Landscape Property (Printer)

Legend Column Count Property (Frame, Generic)

Legend Property (Frame, Generic)

Line Style Property (Field Template, Axis Chart)

Major Grid Property (Axis, Generic)

Major Ticks Property (Axis, Generic)

Maximum Number Of Categories Property (Axis, Discrete)

Maximum Number Of Rows Property (Frame, Table Chart)

Maximum Property (Axis, Continuous)

Maximum Property (Axis, Date)

Maximum Rows Property (Query)

Minimum Number Of Categories Property (Axis, Discrete)

Minimum Number Of Rows Property (Frame, Table Chart)

Minimum Property (Axis, Continuous)

Minimum Property (Axis, Date)

Minor Grid Property (Axis, Generic)

Minor Ticks Per Interval Property (Axis, Generic)

Minor Ticks Property (Axis, Generic)

Month Format Property (Axis, Date)

Name Property (Chart Element)

Name Property (Frame, Generic)

Name Property (Field Template, Generic)

Name Property (Field Template, Generic)

Name Property (Generic)

Name Property (Printer)

Name Property (Query)

Name Property (Sound)

Name Property (Timer)

Name Property (Window)

Nearest Property (Text)

No Overlap Property (Frame, Pie Chart)

Number Format Property (Axis, Discrete)

Number Format Property (Axis, Continuous)

Number Value Property (Reference Line)

Object Type Property (Generic)

Open Trigger Property (Display)

Origin Point Property (Text)

Other Property (Frame, Pie Chart)

Outer Bounding Box Property (Generic)

Overlap Property (Field Template, Axis Chart)

Page Size Property (Printer)

Parent Property (Generic)

Password Property (Application)

Percent By Property (Axis, Continuous)

Percent Of Property (Axis, Continuous)

Percent Values Property (Frame, Pie Chart)

Platform Property (Application)

Plot Frame Property (Frame, Generic)

Plot Order Property (Frame, Pie Chart)

Plot Position Property (Field Template, Axis Chart)

Plot Type Property (Field Template, Axis Chart)

Point Count Property (Polygon)

Point Size Property (Text)

Position Property (Axis, Generic)

Position Property (Image)

Position Property (Window)

Post-Query Trigger Procedure Property (Query)

Print File Property (Printer)

Procedure Property (Timer)

Quality Property (Image)

Quarter Format Property (Axis, Date)

Query Property (Chart)

Query Source Property (Query)

Query Type Property (Query)

Range Property (Chart)

Reference Line Count Property (Frame, Axis Chart)

Root Property (Frame, Generic)

Root Property (Field Template, Generic)

Rotation Angle Property (Graphic)

Scalable Bounding Box Property (Text)

Scalable Font Property (Text)

Scale Property (Axis, Continuous)

Second Y Axis Property (Frame, Axis Chart)

Set Parameter Property (Generic)

Shadow Direction Property (Frame, Generic)

Shadow Size Property (Frame, Generic)

Simple Text Count Property (Compound Text)

Size And Position Property (Chart)

Skip Weekends Property (Axis, Date)

Spacing Property (Text)

Start Page Property (Printer)

Start Point Property (Line)

Start Row Property (Chart)

Step Property (Axis, Continuous)

Step Property (Axis, Date)

Style Property (Text)

Symbol Size Property (Symbol)

Synthesize Property (Text)

Template Property (Chart)

Text String Property (Simple Text)

Tick Label Rotation Property (Axis, Generic)

Tick Labels Property (Axis, Generic)

Tick Position Property (Axis, Generic)

Ticks Property (Frame, Pie Chart)

Title Property (Chart)

Transfer Mode Property (Graphic)

Typeface Property (Text)

Usage Property (Frame, Pie Chart)

Usage Value Property (Frame, Pie Chart)

Username Property (Application)

Value Format Property (Frame, Pie Chart)

Vertical Alignment Property (Text)

Vertical Grid Property (Frame, Table Chart)

Vertical Layout Resolution Property (Application)

Vertical Origin Property (Text)

Vertical Screen Resolution Property (Application)

Weight Property (Text)

Width Property (Display)

Width Property (Image)

Width Property (Text)

Width Property (Window)

Wraparound Property (Text)


No built-in subprograms begin with this letter.


Axis (Date) Properties

Auto Maximum Property

Auto Minimum Property

Auto Step Property

Custom Format Property

Day Format Property

First Month Property

Labels Property

Maximum Property

Minimum Property

Month Format Property

Quarter Format Property

Skip Weekends Property

Step Property

Year Format Property


Auto Maximum Property

  Examples	  Related Topics

Description  Specifies whether the axis maximum is set to Auto.

Syntax

PROCEDURE OG_Set_Date_Automax
  (axis     OG_Axis,
   automax  BOOLEAN,
   maximun  DATE);

FUNCTION OG_Get_Date_Automax
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
automax	Specifies whether the axis maximum is set to Auto.
maximun	Specifies the maximum axis value (if automax is FALSE).


Auto Maximum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if axis
**Y1's date maximum is set to auto. If
**the return value is TRUE, it resets the
**value to FALSE with default_max;
**if the return value is FALSE, it resets
**the value to TRUE after reading the
**specified maximum axis value.
/*

PROCEDURE datemax IS
  template	og_template;
  axis 	og_axis;
  val1 	date;
  val2 	boolean;
  default_max date := '06-dec-99';
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val2 := og_get_date_automax(axis);
  if val2 = true then
    og_set_date_automax(axis, false, default_max);
    val1 := og_get_date_maximum(axis);
  elsif val2 = false then
   og_set_date_automax(axis, true, default_max);
  end if;
END;


Auto Minimum Property

  Examples	  Related Topics

Description  Specifies whether the axis minimum is set to Auto.

Syntax

PROCEDURE OG_Set_Date_Automin
  (axis     OG_Axis,
   automin  BOOLEAN,
   minimun  DATE);

FUNCTION OG_Get_Date_Automin
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
automin	Specifies whether the axis minimum is set to Auto.
minimun	Specifies the minimum axis value (if automin is FALSE).


Auto Minimum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if axis
**Y1's date minimum is set to auto. If the
**return value is TRUE, it resets the value
**to FALSE with default_min; if the return
**value is FALSE, it resets the value to
**TRUE after reading the specified minimum
**axis value.
*/

PROCEDURE datemin IS
  template 	og_template;
  axis 	og_axis;
  val1 	date;
  val2 	boolean;
 default_min	date := '01-dec-79';
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val2 := og_get_date_automin(axis);
  if val2 = true then
    og_set_date_automin(axis, false, default_min);
    val1 := og_get_date_minimum(axis);
  elsif val2 = false then
    og_set_date_automin(axis, true, default_min);
  end if;
END;


Auto Step Property

  Examples	  Related Topics

Description  Specifies whether the axis step value is set to Auto.

Syntax

PROCEDURE OG_Set_Date_Autostep
  (axis      OG_Axis,
   autostep  BOOLEAN,
   step      NUMBER);

FUNCTION OG_Get_Date_Autostep
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
autostep	Specifies whether the axis step value is set to Auto.
step	Specifies the axis step value (if autostep is FALSE).


Auto Step Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if axis
**Y1's date step is set to auto. If the
**return value is TRUE, it resets the value
**to FALSE with default_step; if the return
**value is FALSE, it resets the value
**to TRUE after reading the specified step
**value.
*/

PROCEDURE datestep IS
  template 	og_template;
  axis 	og_axis;
  val  	boolean;
  num  	number;
  default_step number := og_second_step;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val:= og_get_date_autostep(axis);
  if val = true then
    og_set_date_autostep(axis, false, default_step);
    num := og_get_date_step(axis);
  elsif val = false then
    og_set_date_autostep(axis, true, default_step);
  end if;
END;


Custom Format Property

  Examples	  Related Topics

Description  Is the custom date format for the axis tick labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.

Syntax

PROCEDURE OG_Set_Custfmt
  (axis     OG_Axis,
   custfmt  VARCHAR2);

FUNCTION OG_Get_Custfmt
  (axis  OG_Axis)
RETURN VARCHAR2;

Parameters

axis	Is the axis object being described.
custfmt	Is the custom date format for the axis tick labels.


Custom Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**Custom format value and compares it
**with the variable 'default_format';
**if the two value are not equal,
**it resets the current format to the
**value of the 'default_format'.
*/

PROCEDURE customfmt IS
  template 	og_template;
  axis 	og_axis;
  val  	varchar2(10);
  default_format varchar2(10) := 'DD_YY_MM';
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val := og_get_custfmt(axis);
  if val != default_format then
    og_set_custfmt(axis, default_format);
  end if;
END;


No built-in subprograms begin with this letter.


Day Format Property

  Examples	  Related Topics

Description  Determines the appearance of day-of-the-week labels along the axis.  The value of this property may be one of the following built-in constants:

OG_Firstletter_Fmt

OG_Threeletter_Fmt

Syntax

PROCEDURE OG_Set_Dayfmt
  (axis    OG_Axis,
   dayfmt  NUMBER);

FUNCTION OG_Get_Dayfmt
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
dayfmt	Determines the appearance of day-of-the-week labels along the axis.


Day Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks the
**day-of-week format.  If the current format
**is First-Letter format, it resets the value
**to Three-Letter format, and vice versa.
*/

PROCEDURE dayfmt IS
  template 	og_template;
  axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  num:= og_get_dayfmt(axis);
  if num = og_firstletter_fmt then
    og_set_dayfmt(axis, og_threeletter_fmt);
  elsif num = og_threeletter_fmt then
    og_set_dayfmt(axis, og_firstletter_fmt);
  end if;
END;


First Month Property

  Examples	  Related Topics

Description  Is the month that is considered to begin a new year.  The value of this property may be one of the following built-in constants:

OG_Jan_Month

OG_Feb_Month

OG_Mar_Month

OG_Apr_Month

OG_May_Month

OG_Jun_Month

OG_Jul_Month

OG_Aug_Month

OG_Sep_Month

OG_Oct_Month

OG_Nov_Month

OG_Dec_Month

Syntax

PROCEDURE OG_Set_Firstmon
  (axis      OG_Axis,
   firstmon  NUMBER);

FUNCTION OG_Get_Firstmon
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
firstmon	Is the month that is considered to begin a new year.


First Month Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following reads the first month
**value and resets the value to the next
**acceptable value.
*/

PROCEDURE firstmonth IS
  template 	og_template;
  axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  num:= og_get_firstmon(axis);
  if num = og_jan_month then
    og_set_firstmon(axis, og_feb_month);
  elsif num = og_feb_month then
    og_set_firstmon(axis, og_mar_month);
  elsif num = og_mar_month then
    og_set_firstmon(axis, og_apr_month);
  elsif num = og_apr_month then
    og_set_firstmon(axis, og_may_month);
  elsif num = og_may_month then
    og_set_firstmon(axis, og_jun_month);
  elsif num = og_jun_month then
    og_set_firstmon(axis, og_jul_month);
  elsif num = og_jul_month then
    og_set_firstmon(axis, og_aug_month);
  elsif num = og_aug_month then
    og_set_firstmon(axis, og_sep_month);
  elsif num = og_sep_month then
    og_set_firstmon(axis, og_oct_month);
  elsif num = og_oct_month then
    og_set_firstmon(axis, og_nov_month);
  elsif num = og_nov_month then
    og_set_firstmon(axis, og_dec_month);
  else og_set_firstmon(axis, og_jan_month);
  end if;
END;


Labels Property

  Examples	  Related Topics

Description  Specifies the major interval along the axis at which major tick marks and tick labels appear, as well as the appearance of the tick labels.  The value of this property may be one of the following built-in constants:

OG_No_Labels

OG_Second_Labels

OG_Minute_Labels

OG_Hour_Labels

OG_Ampm_Labels

OG_Day_Labels

OG_Dayofweek_Labels

OG_Week_Labels

OG_Month_Labels

OG_Quarter_Labels

OG_Year_Labels

OG_Custom_Labels   (If labels is set to this value, you must specify the custom date format in the Custom Format property.)

Syntax

PROCEDURE OG_Set_Labels
  (axis    OG_Axis,
   labels  NUMBER);

FUNCTION OG_Get_Labels
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
labels	Specifies the major interval along the axis at which major tick marks and tick labels appear, as well as the appearance of the tick labels.


Labels Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines
**if any label boxes are checked.
**If checked label boxes are found,
**it unchecks all labels; if no checked
**labels are found, it checks the 'Year'
**check box.
*/

PROCEDURE labels IS
  template 	og_template;
  axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);

  num:= og_get_labels(axis);
  if num != og_no_labels then
    og_set_labels(axis, og_no_labels);
  else og_set_labels(axis, og_year_labels);
  end if;
END;


Maximum Property

  Examples	  Related Topics

Description  Specifies the maximum axis value (if Auto Maximum is FALSE).

Syntax

(See OG_Set_Date_Automax, above.)

FUNCTION OG_Get_Date_Maximum
  (axis  OG_Axis)
RETURN DATE;

Parameters

axis	Is the axis object being described.


Maximum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if
**axis Y1's date maximum is set to auto.
**If the return value is TRUE,
**it resets the value to FALSE with
**default_max; if the return value is
**FALSE, it resets the value to
**TRUE after reading the specified
**maximum axis value.
/*

PROCEDURE datemax IS
  template	og_template;
  axis 	og_axis;
  val1 	date;
  val2 	boolean;
  default_max date := '06-dec-99';
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val2 := og_get_date_automax(axis);
  if val2 = true then
    og_set_date_automax(axis, false, default_max);
    val1 := og_get_date_maximum(axis);
  elsif val2 = false then
   og_set_date_automax(axis, true, default_max);
  end if;
END;


Minimum Property

  Examples	  Related Topics

Description  Specifies the minimum axis value (if Auto Minimum is FALSE).

Syntax

(See OG_Set_Date_Automin.)

FUNCTION OG_Get_Date_Minimum
  (axis  OG_Axis)
RETURN DATE;

Parameters

axis	Is the axis object being described.


Minimum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if
**axis Y1's date minimum is set to auto.
**If the return value is TRUE, it resets
**the value to FALSE with default_min;
**if the return value is FALSE, it resets
**the value to TRUE after reading the
**specified minimum axis value.
*/

PROCEDURE datemin IS
  template 	og_template;
  axis 	og_axis;
  val1 	date;
  val2 	boolean;
 default_min	date := '01-dec-79';
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val2 := og_get_date_automin(axis);
  if val2 = true then
    og_set_date_automin(axis, false, default_min);
    val1 := og_get_date_minimum(axis);
  elsif val2 = false then
    og_set_date_automin(axis, true, default_min);
  end if;
END;


Month Format Property

  Examples	  Related Topics

Description  Determines the appearance of month labels along the axis.  The value of this property may be one of the following built-in constants:

OG_Firstletter_Fmt

OG_Threeletter_Fmt

Syntax

PROCEDURE OG_Set_Monthfmt
  (axis      OG_Axis,
   monthfmt  NUMBER);

FUNCTION OG_Get_Monthfmt
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
monthfmt	Determines the appearance of month labels along the axis.


Month Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks the
**Month format. If the current format
**is First-Letter format, it
**resets the value to Three-Letter
**format, and vice versa.
*/

PROCEDURE monthfmt IS
  template 	og_template;
  axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  num:= og_get_monthfmt(axis);
  if num = og_firstletter_fmt then
    og_set_monthfmt(axis, og_threeletter_fmt);
  elsif num = og_threeletter_fmt then
    og_set_monthfmt(axis, og_firstletter_fmt);
  end if;
END;


Quarter Format Property

  Examples	  Related Topics

Description  Determines the appearance of quarter labels along the axis.  The value of this property may be one of the following built-in constants:

OG_Arabic_Fmt

OG_Roman_Fmt

Syntax

PROCEDURE OG_Set_Qtrfmt
  (axis    OG_Axis,
   qtrfmt  NUMBER);

FUNCTION OG_Get_Qtrfmt
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
qtrfmt	Determines the appearance of quarter labels along the axis.


Quarter Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks the
**Quarter format. If the current
**format is Arabic format, it resets
**the value to Roman format, and vice versa.
*/

PROCEDURE qtrfmt IS
  template 	og_template;
  axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  num:= og_get_qtrfmt(axis);
  if num = og_arabic_fmt then
    og_set_qtrfmt(axis, og_roman_fmt);
  elsif num = og_roman_fmt then
    og_set_qtrfmt(axis, og_arabic_fmt);
  end if;
END;


Skip Weekends Property

  Examples	  Related Topics

Description  Specifies whether weekends are ignored when calculating axis values.

Syntax

PROCEDURE OG_Set_Skipwknds
  (axis       OG_Axis,
   skipwknds  BOOLEAN);

FUNCTION OG_Get_Skipwknds
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
skipwknds	Specifies whether weekends are ignored when calculating axis values.


Skip Weekends Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks whether
**weekends are ignored when calculating
**axis values. If the value of weekend
**is set to TRUE (ignored), the procedure
**resets the value to FALSE (include
**in the calculation) and vice versa.
*/

PROCEDURE skipwknds IS
  template 	og_template;
  axis 	og_axis;
  val  	boolean;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val:= og_get_skipwknds(axis);
  if val = true then
    og_set_skipwknds(axis, false);
  elsif val = false then
    og_set_skipwknds(axis, true);
  end if;
END;


Step Property

  Examples	  Related Topics

Description  Specifies the axis step value (if Auto Step is FALSE).  The value of this property may be one of the following built-in constants:

OG_Second_Step

OG_Minute_Step

OG_Hour_Step

OG_Day_Step

OG_Week_Step

OG_Month_Step

OG_Quarter_Step

OG_Year_Step

Syntax

(See OG_Set_Date_Autostep.)

FUNCTION OG_Get_Date_Step
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.


Step Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if
**axis Y1's date step is set to auto.
**If the return value is TRUE, it resets
**the value to FALSE with default_step;
**if the return value is FALSE,
**it resets the value to TRUE
**after reading the specified step
**value.
*/

PROCEDURE datestep IS
  template 	og_template;
  axis 	og_axis;
  val  	boolean;
  num  	number;
  default_step number := og_second_step;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val:= og_get_date_autostep(axis);
  if val = true then
    og_set_date_autostep(axis, false, default_step);
    num := og_get_date_step(axis);
  elsif val = false then
    og_set_date_autostep(axis, true, default_step);
  end if;
END


Year Format Property

  Examples	  Related Topics

Description  Determines the appearance of year labels along the axis.  The value of this property may be one of the following built-in constants:

OG_Fourdigit_Fmt

OG_Twodigit_Fmt

Syntax

PROCEDURE OG_Set_Yearfmt
  (axis     OG_Axis,
   yearfmt  NUMBER);

FUNCTION OG_Get_Yearfmt
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
yearfmt	Determines the appearance of year labels along the axis.


Year Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks the Year
**format.  If the current format is Two-Digit
**format, it resets the value to
**Four-Digit format, and vice versa.
*/

PROCEDURE yearfmt IS
  template 	og_template;
  axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  num:= og_get_yearfmt(axis);
  if num = og_fourdigit_fmt then
    og_set_yearfmt(axis, og_twodigit_fmt);
  elsif num = og_twodigit_fmt then
    og_set_yearfmt(axis, og_fourdigit_fmt);
  end if;
END;


Application Properties

Connection String Property

Cursor Property

Horizontal Layout Resolution Property

Horizontal Screen Resolution Property

Password Property

Platform Property

Username Property

Vertical Layout Resolution Property

Vertical Screen Resolution Property


Connection String Property

  Examples	  Related Topics

Description  Is the database connection string for the current database connection.  If the user is not connected, this property is NULL.

Syntax

FUNCTION OG_Get_Ap_Connection
RETURN VARCHAR2;

Parameters

None.


Connection String Property Examples

  Alphabetic List      [image]  All Examples     [image]  Related Topics

 /*The following open trigger procedure
**displays the connection string for
**the current database connection
**to a text object.
*/

PROCEDURE connection IS
  connstr 	varchar2(10);
BEGIN
  connstr := og_get_ap_connection;
  if connstr = NULL then
    og_set_str(og_get_object('text object'), 'NULL', true, true);
  else
    og_set_str(og_get_object('text object'), connstr, true, true);
  end if;
END;


Cursor Property

  Examples	  Related Topics

Description  Is the name of the mouse cursor to use.  The value of this property may be one of the following strings:

default
insertion
crosshair
help
busy

The appearance of each cursor is system-specific.  For more information, refer to your system documentation.  If you set this property to an invalid value, it assumes the value `default.'

Syntax

PROCEDURE OG_Set_Ap_Cursor
  (cursor  VARCHAR2);

FUNCTION OG_Get_Ap_Cursor
RETURN VARCHAR2;

Parameters

cursor	Is the mouse cursor to use.


Cursor Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure changes
**the shape of the cursor depending on
**which layer the user selects.
*/

PROCEDURE ChangeCursor (buttonobj IN og_object,
  hitobj IN og_object, win IN og_window,
  eventinfo IN og_event) IS
  cur  	varchar2(10);
BEGIN
  mycur := og_get_ap_cursor;
  if cur = 'default' then
     og_set_ap_cursor('insertion');
  elsif cur = 'insertion' then
     og_set_ap_cursor('crosshair');
  elsif cur = 'crosshair' then
     og_set_ap_cursor('help');
  elsif cur = 'help' then
     og_set_ap_cursor('busy');
  elsif cur = 'busy' then
     og_set_ap_cursor('default');
  end if;
END;


Horizontal Layout Resolution Property

  Examples	  Related Topics

Description  Is the horizontal resolution of the layout.  This value is the number of layout units in one horizontal inch of the layout.

Syntax

FUNCTION OG_Get_Ap_Hlayout_Res
RETURN NUMBER;

Parameters

None.


Horizontal Layout Resolution Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure displays
**current horizontal layout resolution
**to a text object.
*/

PROCEDURE h_layout IS
  h_layout 	number;
BEGIN
  h_layout := og_get_ap_hlayout_res;
  og_set_str(og_get_object('text object'), h_layout, true, true);
END;


Horizontal Screen Resolution Property

  Examples	  Related Topics

Description  Is the horizontal resolution of the screen.  This value is the number of screen resolution units (i.e., pixels) in one horizontal inch of the screen.

Syntax

FUNCTION OG_Get_Ap_Hscreen_Res
RETURN NUMBER;

Parameters

None.


Horizontal Screen Resolution Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure displays
**current horizontal screen
**to a text object.
*/

PROCEDURE HRES IS
  h_res 	number;
BEGIN
  h_res := og_get_ap_vscreen_res;
  og_set_str(og_get_object('text object'), h_res, true, true);
END;


Password Property

  Examples	  Related Topics

Description  Is the password for the current database connection.  If the user is not connected, or the Keep_Password preference setting is set to No, this property is NULL.

Syntax

FUNCTION OG_Get_Ap_Password
RETURN VARCHAR2;

Parameters

None.


Password Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following open trigger procedure
** displays the password for the current
**database connection to a text object.
*/

PROCEDURE password IS
  pw 	varchar2(10);
BEGIN
  pw := og_get_ap_password;
  if pw = NULL then
    og_set_str(og_get_object('text object'), 'NULL', true, true);
  else
    og_set_str(og_get_object('text object'), pw, true, true);
  end if;
END;


Platform Property

  Examples	  Related Topics

Description  Is the platform on which Graphics Builder is running.  The value of this property may be one of the following built-in constants:

OG_Macintosh_Platform   Means the platform is the Apple Macintosh.

OG_Motif_Platform   Means the platform is OSF/MOTIF.

OG_Mswindows_Platform   Means the platform is Microsoft Windows.

OG_Pm_Platform   Means the platform is Presentation Manager.

OG_X_Platform   Means the platform is the X Window System.

Syntax

FUNCTION OG_Get_Ap_Platform
RETURN NUMBER;

Parameters

None.


Platform Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure displays
**the platform type on which Oracle
**Graphics is currently running to
**a text object.
*/

PROCEDURE platform IS
  ptform 	number;
BEGIN
  ptform := og_get_ap_platform;
  if ptform = og_macintosh_platform then
    og_set_str(og_get_object('text object'), 'og_macintosh_platform', true, true);
  elsif ptform = og_motif_platform then
    og_set_str(og_get_object('text object'), 'og_motif_platform', true, true);
  elsif ptform = og_mswindows_platform then
    og_set_str(og_get_object('text object'), 'og_mswindows_platform', true, true);
  elsif ptform = og_pm_platform  then
    og_set_str(og_get_object('text object'), 'og_pm_platform', true, true);
  elsif ptform = og_x_platform then
    og_set_str(og_get_object('text object'), 'og_x_platform', true, true);
  end if;
END;


Username Property

  Examples	  Related Topics

Description  Is the username for the current database connection.  If the user is not connected, this property is NULL.

Syntax

FUNCTION OG_Get_Ap_Username
RETURN VARCHAR2;

Parameters

None.


Username Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following open trigger procedure
**displays the username for the current
**database connection to a text object.
*/

PROCEDURE username IS
  usr  	varchar2(10);
BEGIN
  usr := og_get_ap_username;
  if usr = NULL then
    og_set_str(og_get_object('text object'), 'NULL', true, true);
  else
    og_set_str(og_get_object('text object'), usr, true, true);
  end if;
END;


Vertical Layout Resolution Property

  Examples	  Related Topics

Description  Is the vertical resolution of the layout.  This value is the number of layout units in one vertical inch of the layout.

Syntax

FUNCTION OG_Get_Ap_Vlayout_Res
RETURN NUMBER;

Parameters

None.


Vertical Layout Resolution Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure displays current
**vertical layout resolution to a text object.
*/

PROCEDURE v_layout IS
  v_layout 	number;
BEGIN
  v_layout := og_get_ap_vlayout_res;
  og_set_str(og_get_object('text object'), v_layout, true, true);
END;


Vertical Screen Resolution Property

  Examples	  Related Topics

Description  Is the vertical resolution of the screen.  This value is the number of screen resolution units (i.e., pixels) in one vertical inch of the screen.

Syntax

FUNCTION OG_Get_Ap_Vscreen_Res
RETURN NUMBER;

Parameters

None.


Vertical Screen Resolution Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure displays current
**vertical screen resolution to a text object:
/*

PROCEDURE VRES IS
  v_res	number;
BEGIN
  v_res := og_get_ap_vscreen_res;
  og_set_str(og_get_object('text object'), v_res, true, true);
END;


Arc Properties

Base Arc Property

Closure Property

Fill Property


Base Arc Property

  Examples	  Related Topics

Description  Is the x- and y-coordinates of the upper-left corner, and the height and width of the rectangle used as the basis for the ellipse from which the arc is cut.

Syntax

PROCEDURE OG_Set_Basearc
  (arc          OG_Object,
   basearc      OG_Arc,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Basearc
  (arc  OG_Object)
RETURN OG_Arc;

Parameters

arc	Is the arc object being described.
basearc	Is the x- and y-coordinates of the upper-left corner, and the height and width of the rectangle used as the basis for the ellipse from which the arc is cut.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Base Arc Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
**information from an existing arc,
**reduces all data by half, and
**updates the arc object.
*/

PROCEDURE base_arc IS
  arc  	og_arc;
BEGIN
  arc := og_get_basearc(og_get_object('arc'));
  arc.x := arc.x/2;
  arc.y := arc.y/2;
  arc.height :=arc.height/2;
  arc.width := arc.width/20;
  arc.sangle := arc.sangle/2;
  arc.eangle := arc.eangle/2;
  og_set_basearc(og_get_object('arc'), arc);
END;


Closure Property

  Examples	  Related Topics

Description  Is the closure of the arc.  The value of this property may be one of the following:

TRUE   Means the arc is closed.

FALSE   Means the arc is open.

Syntax

PROCEDURE OG_Set_Arc_Closed
  (arc          OG_Object,
   closed       BOOLEAN,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Arc_Closed
  (arc  OG_Object)
RETURN BOOLEAN;

Parameters

arc	Is the arc object being described.
closed	Is the closure of the arc.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Closure Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**closure of an existing arc.  If closure
**equals TRUE, it fills the arc with red
**and sets the closure value to FALSE;
**if closure equals FALSE, it fills the
**arc with blue and sets the value to TRUE.
*/

PROCEDURE closure IS
  cls  	BOOLEAN;
  arc  	og_object;
BEGIN
  arc := og_get_object('arc');
  cls := og_get_arc_closed(arc);
  if cls = TRUE  then
     og_set_bfcolor(arc, 'red');
     og_set_arc_closed(arc, FALSE);
  else
     og_set_bfcolor(arc, 'blue');
     og_set_arc_closed(arc, TRUE);
  end if;
END;


Fill Property

  Examples	  Related Topics

Description  Is the fill shape of the arc.  The value of this property may be one of the following built-in constants:

OG_Chord_Arcfill   Means the fill shape of the arc is that of a chord.

OG_Pie_Arcfill   Means the fill shape of the arc is that of a full pie slice.

Syntax

PROCEDURE OG_Set_Arcfill
  (arc          OG_Object,
   arcfill      NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Arcfill
  (arc  OG_Object)
RETURN NUMBER;

Parameters

arc	Is the arc object being described.
arcfill	Is the fill shape of the arc.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Fill Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**arcfill from an arc, prints the value to a
**text object, assigns a different value
** to the arcfill value.
*/

PROCEDURE fill IS

  text 	og_object;
  arc  	og_object;
  num  	NUMBER;
BEGIN
  text := og_get_object('text object');
  arc := og_get_object('arc');
  num := og_get_arcfill(arc);
  og_set_str(text, num);
  og_set_arcfill(arc, og_chord_arcfill);
END;


Axis (Generic) Properties

Axis Label Property

Axis Type Property

Custom Label Property

Direction Property

Major Grid Property

Major Ticks Property

Minor Grid Property

Minor Ticks Property

Minor Ticks Per Interval Property

Position Property

Tick Label Rotation Property

Tick Labels Property

Tick Position Property


Axis Label Property

  Examples	  Related Topics

Description  Specifies whether labels that identify values along the axis appear.

Syntax

PROCEDURE OG_Set_Axislabel
  (axis       OG_Axis,
   axislabel  BOOLEAN);

FUNCTION OG_Get_Axislabel
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
axislabel	Specifies whether labels that identify values along the axis appear.


Axis Label Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines if
**the Axis Label checkbox is checked.
**If the box is checked, it unchecks
**it, and vice versa.
*/

PROCEDURE GenAxisLbl IS
  template 	og_template;
  x_axis 	og_axis;
  val  	boolean;
BEGIN
  template := og_get_template('template0');
  x_axis := og_get_axis(template, og_x_axis);

  val := og_get_axislabel(x_axis);
  if val = true then
     og_set_axislabel(x_axis, false);
  else
     og_set_axislabel(x_axis, true);
  end if;
END;


Axis Type Property

  Examples	  Related Topics

Description  Specifies the type of axis to use.  The value of this property may be one of the following built-in constants:

OG_Continuous_Axistype

OG_Date_Axistype

OG_Discrete_Axistype

Syntax

PROCEDURE OG_Set_Axistype
  (axis      OG_Axis,
   axistype  NUMBER);

FUNCTION OG_Get_Axistype
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
axistype	Specifies the type of axis to use.


Axis Type Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**current axis type.  If the current type
**is CONTINUOUS, it resets the type
**to DISCRETE, or vice versa.  If the
**current type is DATE, it changes the
**year format.
*/

PROCEDURE GenAxisType IS
  template 	og_template;
  axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_x_axis);
  num := og_get_axistype(axis);
  if num = og_discrete_axistype then
     og_set_axistype(axis,og_continuous_axistype);
  elsif num = og_continuous_axistype then
     og_set_axistype(axis, og_discrete_axistype);
  elsif num = og_date_axistype then
     og_set_yearfmt(axis, og_twodigit_fmt);
  end if;
END;


Custom Label Property

  Examples	  Related Topics

Description  Specifies the text of the label that appears along the axis.

Syntax

PROCEDURE OG_Set_Custlabel
  (axis       OG_Axis,
   custlabel  VARCHAR2);

FUNCTION OG_Get_Custlabel
  (axis  OG_Axis)
RETURN VARCHAR2;

Parameters

axis	Is the axis object being described.
custlabel	Specifies the text of the label that appears along the axis.


Custom Label Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the current
**label of the specific axis, and changes
**the name of that label.
*/

PROCEDURE CustLabel IS
  template 	og_template;
  axis 	og_axis;
  label 	varchar2(20);
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_x_axis);
  label := og_get_custlabel(axis);
  og_set_custlabel(axis, 'Employee Number');
END;


Direction Property

  Examples	  Related Topics

Description  Specifies in which direction increasing values, or successive categories, are placed along the axis.  The value of this property may be one of the following built-in constants:

OG_Down_Direction

OG_Left_Direction

OG_Right_Direction

OG_Up_Direction

Syntax

PROCEDURE OG_Set_Direction
  (axis       OG_Axis,
   direction  NUMBER);

FUNCTION OG_Get_Direction
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
direction	Specifies in which direction increasing values, or successive categories, are placed along the axis.


Direction Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**directions of the x and y axis and sets
**them to the opposite directions.
*/

PROCEDURE GenDirection IS
  template 	og_template;
  x_axis 	og_axis;
  y_axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  x_axis := og_get_axis(template, og_x_axis);
  y_axis := og_get_axis(template, og_y1_axis);
  num := og_get_direction(x_axis);
  if num = og_left_direction then
     og_set_direction(x_axis, og_right_direction);
  elsif num = og_right_direction then
     og_set_direction(x_axis, og_left_direction);
  end if;
  num := og_get_direction(y_axis);
  if num = og_up_direction then
     og_set_direction(y_axis, og_down_direction);
  elsif num = og_down_direction then
     og_set_direction(y_axis, og_up_direction);
  end if;
END;


Major Grid Property

  Examples	  Related Topics

Description  Specifies whether a grid line appears at each major tick mark.

Syntax

PROCEDURE OG_Set_Majorgrid
  (axis       OG_Axis,
   majorgrid  BOOLEAN);

FUNCTION OG_Get_Majorgrid
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
majorgrid	Specifies whether a grid line appears at each major tick mark.


Major Grid Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if the
**Major Grid checkbox is checked.  If the
**box is checked, it unchecks it, and vice
**versa.
*/

PROCEDURE GenMajorGrids IS
  template 	og_template;
  x_axis 	og_axis;
  val  	boolean;
BEGIN
  template := og_get_template('template0');
  x_axis := og_get_axis(template, og_x_axis);

  val := og_get_majorgrid(x_axis);
  if val = true then
     og_set_majorgrid(x_axis, false);
  else
     og_set_majorgrid(x_axis, true);
  end if;
END;


Major Ticks Property

  Examples	  Related Topics

Description  Specifies whether major tick marks appear at each major interval.

Syntax

PROCEDURE OG_Set_Majorticks
  (axis        OG_Axis,
   majorticks  BOOLEAN);

FUNCTION OG_Get_Majorticks
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
majorticks	Specifies whether major tick marks appear at each major interval.


Major Ticks Property  Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if the
**Major Ticks checkbox is checked.  If
**the box is checked, it unchecks it,
**and vice versa.
*/

PROCEDURE GenMajorTicks IS
  template 	og_template;
  x_axis 	og_axis;
  val  	boolean;
BEGIN
  template := og_get_template('template0');
  x_axis := og_get_axis(template, og_x_axis);

  val := og_get_majorticks(x_axis);
  if val = true then
    og_set_majorticks(x_axis, false);
  else
     og_set_majorticks(x_axis, true);
  end if;
END;


Minor Grid Property

  Examples	  Related Topics

Description  Specifies whether a grid line appears at each minor tick mark.

Syntax

PROCEDURE OG_Set_Minorgrid
  (axis       OG_Axis,
   minorgrid  BOOLEAN);

FUNCTION OG_Get_Minorgrid
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
minorgrid	Specifies whether a grid line appears at each minor tick mark


Minor Grid Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if
**the Minor Grid checkbox is checked.
**If the box is checked, it unchecks it,
**and vice versa.
*/

PROCEDURE GenMinorGrids IS
  template 	og_template;
  x_axis 	og_axis;
  val  	boolean;
BEGIN
  template := og_get_template('template0');
  x_axis := og_get_axis(template, og_x_axis);

  val := og_get_minorgrid(x_axis);
  if val = true then
     og_set_minorgrid(x_axis, false);
  else
     og_set_minorgrid(x_axis, true);
  end if;
END;


Minor Ticks Property

  Examples	  Related Topics

Description  Specifies whether minor tick marks appear, as specified by the value set for Minor Ticks per Interval.

Syntax

PROCEDURE OG_Set_Minorticks
  (axis        OG_Axis,
   minorticks  BOOLEAN);

FUNCTION OG_Get_Minorticks
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
minorticks	Specifies whether minor tick marks appear as set by the value of Minor Ticks per Interval.


Minor Ticks Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if the
**Minor Ticks checkbox is checked.  If
**the box is checked, it unchecks it, and
**vice versa.
*/

PROCEDURE GenMinorTicks IS
  template 	og_template;
  x_axis 	og_axis;
  val  	boolean;
BEGIN
  template := og_get_template('template0');
  x_axis := og_get_axis(template, og_x_axis);

  val := og_get_minorticks(x_axis);
  if val = true then
     og_set_minorticks(x_axis, false);
  else
     og_set_minorticks(x_axis, true);
  end if;
END;


Minor Ticks Per Interval Property

  Examples	  Related Topics

Description  Is the number of minor ticks defined within each major tick interval.

Syntax

PROCEDURE OG_Set_Minorct
  (axis     OG_Axis,
   minorct  NUMBER);

FUNCTION OG_Get_Minorct
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
minorct	Is the number of minor ticks defined within each major tick interval.


Minor Ticks Per Interval Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the number
**of minor ticks per interval and resets
**the value to triple the original value.
*/

PROCEDURE GenMinorCt IS
  template 	og_template;
  x_axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  x_axis := og_get_axis(template, og_x_axis);
  num := og_get_ticklabelrot(x_axis);
  og_set_minorct(x_axis, 3*num);
END;


Position Property

  Examples	  Related Topics

Description  Specifies along which edge of the chart the axis appears.  The value of this property may be one of the following built-in constants:

OG_Bottom_Position

OG_Left_Position

OG_Right_Position

OG_Top_Position

Syntax

PROCEDURE OG_Set_Position
  (axis      OG_Axis,
   position  NUMBER);

FUNCTION OG_Get_Position
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
position	Specifies along which edge of the chart the axis appears.


Position Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines
**which edge of the chart the axis
**appears on, and resets the axis to
**the opposite edge.
*/

PROCEDURE GenPosition IS
  template 	og_template;
  axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_x_axis);
  num := og_get_position(axis);
  if num = og_bottom_position then
     og_set_position(axis, og_top_position);
  elsif num = og_left_position then
     og_set_position(axis, og_right_position);
  elsif num = og_right_position then
     og_set_position(axis, og_left_position);
  elsif num = og_top_position then
     og_set_position(axis, og_bottom_position);
  end if;
END;


Tick Label Rotation Property

  Examples	  Related Topics

Description  Specifies the direction in which the tick labels are rotated.  The value of this property may be one of the following built-in constants:

OG_Ccw_Rotation   Means counter-clockwise rotation.

OG_Cw_Rotation   Means clockwise rotation.

OG_No_Rotation   Means no rotation.

Syntax

PROCEDURE OG_Set_Ticklabelrot
  (axis          OG_Axis,
   ticklabelrot  NUMBER);

FUNCTION OG_Get_Ticklabelrot
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
ticklabelrot	Specifies the direction in which the tick labels are rotated.


Tick Label Rotation Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**tick label rotation and changes it
**to a different value.
*/

PROCEDURE GenTickLbl IS
  template 	og_template;
  x_axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  x_axis := og_get_axis(template, og_x_axis);

  num := og_get_ticklabelrot(x_axis);
  if num = og_ccw_rotation then
     og_set_ticklabelrot(x_axis, og_cw_rotation);
  elsif num = og_cw_rotation then
     og_set_ticklabelrot(x_axis, og_no_rotation);
  elsif num = og_no_rotation then
     og_set_ticklabelrot(x_axis, og_ccw_rotation);
  end if;
END;


Tick Labels Property

  Examples	  Related Topics

Description  Specifies whether labels that identify values along the axis appear.

Syntax

PROCEDURE OG_Set_Ticklabels
  (axis        OG_Axis,
   ticklabels  BOOLEAN);

FUNCTION OG_Get_Ticklabels
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
ticklabels	Specifies whether labels that identify values along the axis appear.


Tick Labels Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if
**Tick Label checkbox is checked.
**If the box is checked, it unchecks it,
**and vice versa.
*/

PROCEDURE GenTickLbl IS
  template 	og_template;
  x_axis 	og_axis;
  val  	boolean;
BEGIN
  template := og_get_template('template0');
  x_axis := og_get_axis(template, og_x_axis);
  val := og_get_ticklabels(x_axis);
  if val = true then
     og_set_ticklabels(x_axis, false);
  else
     og_set_ticklabels(x_axis, true);
  end if;
END;


Tick Position Property

  Examples	  Related Topics

Description  Specifies how the major and minor tick marks appear.  The value of this property may be one of the following built-in constants:

OG_Cross_Tickpos

OG_Inside_Tickpos

OG_Outside_Tickpos

Syntax

PROCEDURE OG_Set_Tickpos
  (axis     OG_Axis,
   tickpos  NUMBER);

FUNCTION OG_Get_Tickpos
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.
tickpos	Specifies how the major and minor tick marks appear.


Tick Position Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the tick
**position of the x-axis, and sets it to
**a different value.
*/

PROCEDURE GenTickPos IS
  template 	og_template;
  x_axis 	og_axis;
  num  	number;
BEGIN
  template := og_get_template('template0');
  x_axis := og_get_axis(template, og_x_axis);
  num := og_get_tickpos(x_axis);
  if num = og_cross_tickpos then
     og_set_tickpos(x_axis, og_inside_tickpos);
  elsif num = og_inside_tickpos then
     og_set_tickpos(x_axis, og_outside_tickpos);
  elsif num = og_outside_tickpos then
     og_set_tickpos(x_axis, og_cross_tickpos);
  end if;
END;


Axis (Discrete) Properties

Auto Maximum Property

Auto Minimum Property

Date Format Property

Maximum Number Of Categories Property

Minimum Number Of Categories Property

Number Format Property


Auto Maximum Property

  Examples	  Related Topics

Description  Specifies whether the maximum number of categories that appear on the axis is set to Auto.

Syntax

PROCEDURE OG_Set_Disc_Automax
  (axis     OG_Axis,
   automax  BOOLEAN,
   maxcat   NUMBER);

FUNCTION OG_Get_Disc_Automx
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
automax	Specifies whether the maximum number of categories that appear on the axis is set to Auto.
maxcat	Specifies the maximum number of categories that appear on the axis (if automax is FALSE).


Auto Maximum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if the
**X-axis's maximum is set to auto.  If
**true, it resets the value to false with
**default_maxcat; if false, it reads the
**current value and resets it to true.
*/

PROCEDURE datemax IS
  template 	og_template;
  axis 	og_axis;
  val  	boolean;
  maxcat 	number;
  default_maxcat 	number := 3;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_x_axis);
  val := og_get_disc_automax(axis);
  if val = true then
     og_set_disc_automax(axis, false, default_maxcat);
  elsif val = false then
    maxcat := og_get_disc_maxcat(axis);
    og_set_disc_automax(axis,true,default_maxcat);
  end if;
END;


Auto Minimum Property

  Examples	  Related Topics

Description  Specifies whether the minimum number of categories that appear on the axis is set to Auto.

Syntax

PROCEDURE OG_Set_Disc_Automin
  (axis     OG_Axis,
   automin  BOOLEAN,
   mincat   NUMBER);

FUNCTION OG_Get_Disc_Automin
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	Is the axis object being described.
automin	Specifies whether the minimum number of categories that appear on the axis is set to Auto.
mincat	Specifies the minimum number of categories that appear on the axis (if automin is FALSE.)


Auto Minimum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if the
**X-axis's minimum is set to auto.  If
**true, it resets the value to false with
*default_mincat;  if false, it reads the
**current value and resets the value to
**true.
*/

PROCEDURE datemin IS
  template 	og_template;
  axis 	og_axis;
  val  	boolean;
  mincat 	number;
  default_mincat 	number := 50;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_x_axis);
  val := og_get_disc_automin(axis);
  if val = true then
    og_set_disc_automin(axis,false,default_mincat);
  elsif val = false then
    mincat := og_get_disc_mincat(axis);
    og_set_disc_automin(axis,true,default_mincat);
  end if;
END;


Date Format Property

  Examples	  Related Topics

Description  Specifies the date format for the axis tick labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.

Syntax

PROCEDURE OG_Set_Disc_Datefmt
  (axis      OG_Axis,
   date_fmt  VARCHAR2);

FUNCTION OG_Get_Disc_Datefmt
  (axis  OG_Axis)
RETURN VARCHAR2;

Parameters

axis	Is the axis object being described.
date_fmt	Specifies the date format for the axis tick labels.


Date Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the current
**date format of the axis.  If the current
**format is not equal to variable
**'default_date', it resets the value to
**'default_date.'
*/

PROCEDURE datefmt IS
  template 	og_template;
  axis 	og_axis;
  val 	varchar2(10);
  default_date 	varchar2(10) := 'DD_YY_MM';
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_x_axis);
  val := og_get_disc_datefmt(axis);
  if val != default_date then
     og_set_disc_datefmt(axis, default_date);
  end if;
END;


Maximum Number of Categories Property

  Examples	  Related Topics

Description  Specifies the maximum number of categories that appear on the axis (if automax is FALSE).

Syntax

(See OG_Set_Disc_Automax, above.)

FUNCTION OG_Get_Disc_Maxcat
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.


Maximum Number of Categories Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*
** The following procedure checks if the
**X-axis's maximum is set to auto.  If
**true, it resets the value to false with
**default_maxcat; if false, it reads the
**current value and resets
**it to true.
*/

PROCEDURE datemax IS
  template 	og_template;
  axis 	og_axis;
  val  	boolean;
  maxcat 	number;
  default_maxcat 	number := 3;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_x_axis);
  val := og_get_disc_automax(axis);
  if val = true then
     og_set_disc_automax(axis, false, default_maxcat);
  elsif val = false then
    maxcat := og_get_disc_maxcat(axis);
    og_set_disc_automax(axis,true,default_maxcat);
  end if;
END;


Minimum Number of Categories Property

  Examples	  Related Topics

Description  Specifies the minimum number of categories that appear on the axis (if automin is FALSE).

Syntax

(See OG_Set_Disc_Automin, above.)

FUNCTION OG_Get_Disc_Mincat
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	Is the axis object being described.


Minimum Number of Categories Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if the
**X-axis's minimum is set to auto.  If
**true, it resets the value to false with
**default_mincat;  if false, it reads the
**current value and resets the value to
**true.
*/

PROCEDURE datemin IS
  template 	og_template;
  axis 	og_axis;
  val  	boolean;
  mincat 	number;
  default_mincat 	number := 50;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_x_axis);
  val := og_get_disc_automin(axis);
  if val = true then
    og_set_disc_automin(axis,false,default_mincat);
  elsif val = false then
    mincat := og_get_disc_mincat(axis);
    og_set_disc_automin(axis,true,default_mincat);
  end if;
END;


Number Format Property

  Examples	  Related Topics

Description  Specifies the number format for the axis tick labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.

Syntax

PROCEDURE OG_Set_Disc_Numfmt
  (axis     OG_Axis,
   num_fmt  VARCHAR2);

FUNCTION OG_Get_Disc_Numfmt
  (axis  OG_Axis)
RETURN VARCHAR2;

Parameters

axis	Is the axis object being described.
num_fmt	Specifies the number format for the axis tick labels.


Number Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the current
**number format of the axis.  If the current
**format is not equal to variable
**'default_format', it resets the value to
**'default_format'
*/

PROCEDURE discnumfmt IS
  template 	og_template;
  axis 	og_axis;
  val 	varchar2(10);
  default_format 	varchar2(10) := '9,9,9,9';
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_x_axis);
  val := og_get_disc_numfmt(axis);
  if val != default_format then
     og_set_disc_numfmt(axis, default_format);
  end if;
END;


Axis (Continuous) Properties

Auto Maximum Property

Auto Minimum Property

Auto Step Property

Maximum Property

Minimum Property

Number Format Property

Percent By Property

Percent Of Property

Scale Property

Step Property


Auto Maximum Property

  Examples	  Related Topics

Description  Specifies whether the axis maximum is set to Auto.

Syntax

PROCEDURE OG_Set_Cont_Automax
  (axis     OG_Axis,
   automax  BOOLEAN,
   maximun  NUMBER);

FUNCTION OG_Get_Cont_Automax
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	The axis object being described.
automax	Specifies whether the axis maximum is set to Auto.
maximun	Specifies the maximum axis value (if automax is FALSE).


Auto Maximum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if axis
**Y1's maximum is set to auto. If return
**value is TRUE, reset the value to FALSE
**with default_max; if return value is
**FALSE, it resets the value to TRUE
**after reading the specified maximum
**axis value.
*/

PROCEDURE automin IS
  axis 	og_axis;
  template 	og_template;
  val  	boolean;
  num  	number;
  default_max 	number := 3000;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val := og_get_cont_autostep(axis);
  if val = TRUE then
    og_set_cont_autostep(axis, FALSE, default_max);
  else
    num := og_get_cont_step(axis);
    og_set_cont_autostep(axis, TRUE, default_max);
  end if;
END;


Auto Minimum Property

  Examples	  Related Topics

Description  Specifies whether the axis minimum is set to Auto.

Syntax

PROCEDURE OG_Set_Cont_Automin
  (axis     OG_Axis,
   automin  BOOLEAN,
   minimun  NUMBER);

FUNCTION OG_Get_Cont_Automin
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	The axis object being described.
automin	Specifies whether the axis minimum is set to Auto.
minimun	Specifies the minimum axis value (if automin is FALSE).


Auto Minimum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if axis
**Y1's minimum is set to auto. If the
**value is TRUE, it resets the value to
**FALSE with default_min; if the return
**value is FALSE, it resets the value to
**TRUE after reading the specified minimum
**axis value.
*/

PROCEDURE automin IS
  axis 	og_axis;
  template	og_template;
  val 	boolean;
  num  	number;
  default_min 	number := 500;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val := og_get_cont_automin(axis);
  if val = TRUE then
    og_set_cont_automin(axis, FALSE, default_min);
  elsif val = FALSE then
    num := og_get_cont_minimum(axis);
    og_set_cont_automin(axis, TRUE, default_min);
  end if;
END;


Auto Step Property

  Examples	  Related Topics

Description  Specifies whether the axis step value is set to Auto.

Syntax

PROCEDURE OG_Set_Cont_Autostep
  (axis      OG_Axis,
   autostep  BOOLEAN,
   step      NUMBER);

FUNCTION OG_Get_Cont_Autostep
  (axis  OG_Axis)
RETURN BOOLEAN;

Parameters

axis	The axis object being described.
autostep	Specifies whether the axis step value is set to Auto.
step	Specifies the axis step value (if autostep is FALSE).


Auto Step Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if axis
**Y1's step is set to auto. If the return
**value is TRUE, it resets the value to
**FALSE with default step value; if
**return value is FALSE, it resets
**the value to TRUE after reading
**the specified step value.
*/

PROCEDURE autostep IS
  axis 	og_axis;
  template 	og_template;
  val  	boolean;
  num  	number;
  step 	number := 500;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val := og_get_cont_autostep(axis);
  if val = TRUE then
    og_set_cont_autostep(axis, FALSE, step);
  else
    num := og_get_cont_step(axis);
    og_set_cont_autostep(axis, TRUE, step);
  end if;
END;


Maximum Property

  Examples	  Related Topics

Description  Specifies the maximum axis value (if Auto Maximum is FALSE).

Syntax

(See OG_Set_Cont_Automax, above.)

FUNCTION OG_Get_Cont_Maximum
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	The axis object being described.


Maximum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if axis
**Y1's maximum is set to auto. If return
**value is TRUE, reset the value to
**FALSE with default_max; if return value
**is FALSE, it resets the value to
**TRUE after reading the specified
**maximum axis value.
*/

PROCEDURE automin IS
  axis 	og_axis;
  template 	og_template;
  val  	boolean;
  num  	number;
  default_max 	number := 3000;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val := og_get_cont_autostep(axis);
  if val = TRUE then
    og_set_cont_autostep(axis, FALSE, default_max);
  else
    num := og_get_cont_step(axis);
    og_set_cont_autostep(axis, TRUE, default_max);
  end if;
END;


Minimum Property

  Examples	  Related Topics

Description  Specifies the minimum axis value (if Auto Minimum is FALSE).

Syntax

(See OG_Set_Cont_Automin, above.)

FUNCTION OG_Get_Cont_Minimum
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	The axis object being described.


Minimum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if axis
**Y1's minimum is set to auto. If the
**return value is TRUE, it resets the
**value to FALSE with default_min;
**if the return value is FALSE, it resets
**the value to TRUE after reading the
**specified minimum axis value.
*/

PROCEDURE automin IS
  axis 	og_axis;
  template	og_template;
  val  	boolean;
  num  	number;
  default_min 	number := 500;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val := og_get_cont_automin(axis);
  if val = TRUE then
    og_set_cont_automin(axis, FALSE, default_min);
  elsif val = FALSE then
    num := og_get_cont_minimum(axis);
    og_set_cont_automin(axis, TRUE, default_min);
  end if;
END;


Number Format Property

  Examples	  Related Topics

Description  Specifies the number format for the axis tick labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.

Syntax

PROCEDURE OG_Set_Cont_Numfmt
  (axis     OG_Axis,
   num_fmt  VARCHAR2);

FUNCTION OG_Get_Cont_Numfmt
  (axis  OG_Axis)
RETURN VARCHAR2;

Parameters

axis	The axis object being described.
num_fmt	Specifies the number format for the axis tick labels.


Number Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the current
**number format of the axis and resets it to
**a different value.
*/

PROCEDURE numFormat IS
  axis 	og_axis;
  template 	og_template;
  val  	varchar2(10);
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val := og_get_cont_numfmt(axis);
  og_set_cont_numfmt(axis,'9,9,9,9,9');
END;


Percent by Property

  Examples	  Related Topics

Description  Specifies how the Percent Of scaling values are calculated.  The value of this property may be one of the following built-in constants:

OG_Category_Pctby   Means the percentage for each data value is calculated relative to data values for the same field in other categories.

OG_Field_Pctby   Means the percentage for each data value is calculated relative to data values in the same category for other fields.

Syntax

PROCEDURE OG_Set_Pct_By
  (axis    OG_Axis,
   pct_of  NUMBER);

FUNCTION OG_Get_Pct_By
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	The axis object being described.
pct_of	Specifies how the Percent Of scaling values are calculated.


Percent by Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

*/The following procedure reads the
**calculating method for the
**Percent Of scaling values
**(with Scale is set for OG_PCT_SCALE)
**from the axis and resets the value to
**the next available value.
/*

PROCEDURE pctby IS
  axis 	og_axis;
  template 	og_template;
  val  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val := og_get_pct_by(axis);
  if val = OG_category_pctby then
    og_set_pct_by(axis, og_field_pctby);
  elsif val = og_field_pctby then
    og_set_pct_by(axis, og_category_pctby);
  end if;
END;


Percent of Property

  Examples	  Related Topics

Description  Specifies the relative scaling factor (if Scale is set to OG_Pct_Scale).  The value of this property may be one of the following built-in constants:

OG_Maximum_Pctof   Meanseach data value is plotted as a percentage of the largest data value.

OG_Minimum_Pctof   Means each data value is plotted as a percentage of the smallest data value.

OG_Sum_Pctof   Means each data value is plotted as a percentage of the sum of all data values.

Syntax

PROCEDURE OG_Set_Pct_Of
  (axis    OG_Axis,
   pct_of  NUMBER);

FUNCTION OG_Get_Pct_Of
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	The axis object being described.
pct_of	Specifies the relative scaling factor (if Scale is set to OG_Pct_Scale).


Percent of Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**relative scaling factor (with Scale
**set to OG_PCT_SCALE)from the axis
**and resets the value to the next
**available value.
*/

PROCEDURE pctof  IS
  axis 	og_axis;
  template 	og_template;
  val  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val := og_get_pct_of(axis);
  if val = OG_maximum_pctof then
     og_set_pct_of(axis, og_minimum_pctof);
  elsif val = og_minimum_pctof then
    og_set_pct_of(axis, og_sum_pctof);
  elsif val = og_sum_pctof then
    og_set_pct_of(axis, og_maximum_pctof);
  end if;
END;


Scale Property

  Examples	  Related Topics

Description  Specifies the algorithm used for scaling the axis.  The value of this property may be one of the following built-in constants:

OG_Linear_Scale   Means the axis is scaled using a fixed interval between the minimum and maximum axis values.

OG_LOG_Scale   Means the axis is scaled using a logarithmic algorithm (based on powers of 10) to determine the intervals between the minimum and maximum axis values.

OG_Pct_Scale   Means the axis is scaled so that data values will be plotted relative to the amount specified by Percent Of.

Syntax

PROCEDURE OG_Set_Scale
  (axis   OG_Axis,
   scale  NUMBER);

FUNCTION OG_Get_Scale
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	The axis object being described.
scale	Specifies the algorithm used for scaling the axis.


Scale Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
**the method used for scaling from
**the axis and resets the value
**to the next available value.
*/

PROCEDURE  scale IS
  axis 	og_axis;
  template 	og_template;
  val  	number;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);

  val := og_get_scale(axis);
  if val = OG_linear_scale then
    og_set_scale(axis, og_log_scale);
  elsif val = og_log_scale then
    og_set_scale(axis, og_pct_scale);
  elsif val = og_pct_scale then
    og_set_scale(axis, og_linear_scale);
  end if;
END;


Step Property

  Examples	  Related Topics

Description  Specifies the axis step value (if Auto Step is FALSE).

Syntax

(See OG_Set_Cont_Autostep, above.)

FUNCTION OG_Get_Cont_Step
  (axis  OG_Axis)
RETURN NUMBER;

Parameters

axis	The axis object being described.


Step Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if axis
**Y1's step is set to auto. If the return
**value is TRUE, it resets the value to
**FALSE with default step value; if return
**value is FALSE, it resets the value to
**TRUE after reading the specified step value.
*/

PROCEDURE autostep IS
  axis 	og_axis;
  template 	og_template;
  val 	boolean;
  num 	number;
  step 	number := 500;
BEGIN
  template := og_get_template('template0');
  axis := og_get_axis(template, og_y1_axis);
  val := og_get_cont_autostep(axis);
  if val = TRUE then
    og_set_cont_autostep(axis, FALSE, step);
  else
    num := og_get_cont_step(axis);
    og_set_cont_autostep(axis, TRUE, step);
  end if;
END;


Chart Element Properties

Button Procedure Property

Events Property

Explosion Property

Name Property


Button Procedure Property

  Examples	  Related Topics

Description  Is the handle to the button procedure that should be associated with this chart element.  Note that the Events property must be set properly in order to ensure that this procedure receives the desired mouse events. The Events property may be one of the following built-in constants:

OG_No_Events

OG_Mouse_Up

OG_Mouse_Down

OG_Mouse_Move_Down

To enable the procedure to receive multiple event types, set Events to be the sum of the constants for the desired events.

Syntax

PROCEDURE OG_Set_Button
  (chart        OG_Object,
   row_num      NUMBER,
   col_name     VARCHAR2,
   button_proc  OG_Buttonproc,
   events       NUMBER);

Parameters

chart	Is the chart object being described.
row_num	Is the query row number represented by the chart element.
col_name	Is the query column represented by the chart element.
button_proc	Is the handle to the button procedure that should be associated with this chart element.
events	Is the type of mouse events that the button procedure should receive.


Button Procedure Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure assigns
**a button procedure to chart
**element MGR_bars.
*/

PROCEDURE  AssignButtonProc IS
  chart og_object;
  mgrbar og_object;
  button og_buttonproc;
BEGIN
  chart := og_get_object('chart');
  mgrbar := og_get_object('MGR_bars');
  button := og_get_buttonproc('button');
  og_set_button(chart, og_get_row(mgrbar), 'MGR', button, og_mouse_down);
END;


Events Property

  Examples	  Related Topics

Description  Is the type of mouse events that the button procedure should receive.  The value of this

property may be one of the built-in constants:

OG_No_Events

OG_Mouse_Up

OG_Mouse_Down

OG_Mouse_Move_Down

To enable the procedure to receive multiple event types, set Events to be the sum of the constants for the desired events.

Syntax

(See OG_Set_Button.)

Parameters

None


Events Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure assigns
**a button procedure to
**chart element MGR_bars.
*/

PROCEDURE  AssignButtonProc IS
  chart og_object;
  mgrbar og_object;
  button og_buttonproc;
BEGIN
  chart := og_get_object('chart');
  mgrbar := og_get_object('MGR_bars');
  button := og_get_buttonproc('button');
  og_set_button(chart, og_get_row(mgrbar), 'MGR', button, og_mouse_down);
END;


Explosion Property

  Examples	  Related Topics

Description  Is the distance that the chart element (i.e., pie slice) should be exploded, in terms of the percentage of the chart's x- and y-radii (e.g., 25).  This property is meaningful only when used with a pie chart.  In addition, all of the pie slices for a given category will be exploded the same amount.  Therefore, the specified column name should be for a value column, not a category column.

Syntax

PROCEDURE OG_Set_Explosion
  (chart        OG_Object,
   row_num      NUMBER,
   col_name     VARCHAR2,
   explode_pct  NUMBER);

Parameters

chart	Is the chart object being described.
row_num	Is the query row number represented by the chart element.
col_name	Is the query column represented by the chart element.  It should be the name of a value column
explode_pct	Is the distance that the chart element (i.e., pie slice) should be exploded, in terms of the percentage of the chart's x- and y-radii (e.g., 25).


Explosion Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure assigns the
**distance the chart element should be
** exploded to to 50.
*/

PROCEDURE Explosion IS
  pie og_object;
  mgr_slice og_object;
BEGIN
  pie := og_get_object('pie');
  mgr_slice := og_get_object('MGR_slices');
  og_set_explosion(pie, og_get_row(mgr_slice), 'MGR', 50);
END;


Name Property

  Examples	  Related Topics

Description  Is the name of the chart element.

Syntax

PROCEDURE OG_Set_Name
  (chart     OG_Object,
   row_num   NUMBER,
   col_name  VARCHAR2,
   name      VARCHAR2);

Parameters

chart	Is the chart object being described.
row_num	Is the query row number represented by the chart element.
col_name	Is the query column represented by the chart element.
name	Is the name of the chart element.


Name Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure sets
**the name of the chart element.
*/

PROCEDURE Name IS
  chart og_object;
  mgr_bar og_object;
BEGIN
  chart := og_get_object('chart');
  mgr_bar := og_get_object('Mgr_bars');
  og_set_name(chart, og_get_row(mgr_bar), 'MGR', 'NewName');
END;


Chart Properties

Auto Update Property

End Row Property

Filter Property

Query Property

Range Property

Size And Position Property

Start Row Property

Template Property

Title Property


Auto Update Property

  Examples	  Related Topics

Description  Specifies that the chart is automatically be updated when the query is executed.

Syntax

PROCEDURE OG_Set_Autoupdate
  (chart       OG_Object,
   autoupdate  BOOLEAN);

FUNCTION OG_Get_Autoupdate
  (chart  OG_Object)
RETURN BOOLEAN;

Parameters

chart	Is the chart being described.
autoupdate	Specifies that the chart is automatically be updated when the query is executed.


Auto Update Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following reads the value of
**autoupdate in Chart properties, and
**resets the value to its opposite value
*/

PROCEDURE ChartAutoUpdate IS
  chart og_object;
  autoupdate boolean;
BEGIN
  chart := og_get_object('chart');
  autoupdate := og_get_autoupdate(chart);
  if autoupdate = true then
     og_set_autoupdate(chart, false);
  else
    og_set_autoupdate(chart, true);
   end if;
END;


End Row Property

  Examples	  Related Topics

Description  Is the last row from the query that appears on the chart.

Syntax

(See OG_Set_Rows.)

FUNCTION OG_Get_Endrow
  (chart  OG_Object)
RETURN NUMBER;

Parameters

chart	Is the chart object being described.


End Row Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**startrow and endrow value from chart
**(provided the Plot rows box is checked),
**and resets the range to startrow -1 and
**endrow -1.)
*/

PROCEDURE ChartStartEnd IS
  chart og_object;
 startrow number;
  endrow number;
BEGIN
  chart := og_get_object('chart');
  startrow := og_get_startrow(chart);
  endrow := og_get_endrow(chart);
  og_set_rows(chart,true, startrow-1, endrow-1);
END;


Filter Property

  Examples	  Related Topics

Description  Is the name of the query's filter trigger procedure.

Syntax

PROCEDURE OG_Set_Filter
  (chart   OG_Object,
   filter  VARCHAR2);

FUNCTION OG_Get_Filter
  (chart  OG_Object)
RETURN VARCHAR2;

Parameters

chart	Is the chart object being described.
filter	Is the name of the query's filter trigger procedure.


Filter Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
**the name of the current filter trigger
**of the chart, and assigns a different
**filter trigger to the chart
*/

PROCEDURE ChartFilter IS
  chart og_object;
  current_filter varchar2(30);
  new_filter varchar2(30):='MyFilter';
BEGIN
  chart := og_get_object('chart');
  current_filter := og_get_filter(chart);
  og_set_filter(chart, new_filter);
END;


Query Property

  Examples	  Related Topics

Description  Is the handle to the query to be used for the chart.

Syntax

PROCEDURE OG_Set_Query
  (chart        OG_Object,
   query        OG_Query,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Query
  (chart  OG_Object)
RETURN OG_Query;

Parameters

chart	Is the chart object being described.
query	Is the handle to the query to be used for the chart.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Query Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**query handle from the current chart
**(qry0)and resets the handle value to
**qry1.
*/

PROCEDURE ChartQuery IS
  chart og_object;
  qry0 og_query;
  qry1 og_query;
BEGIN
  chart := og_get_object('chart');
  qry0 := og_get_query(chart);
  qry1 := og_get_query('query1');
  og_set_query(chart, qry1);
END;


Range Property

  Examples	  Related Topics

Description  Specifies whether the number of query rows that appear on the chart is restricted to the range specified by startrow and endrow.

Syntax

PROCEDURE OG_Set_Rows
  (chart      OG_Object,
   rangeflag  BOOLEAN,
   startrow   NUMBER,
   endrow     NUMBER);

FUNCTION OG_Get_Rangeflag
  (chart  OG_Object)
RETURN BOOLEAN;

Parameters

chart	Is the chart object being described.
rangeflag	Specifies whether the number of query rows that appear on the chart is restricted to the range specified by startrow and endrow.
startrow	Is the first row from the query that appears on the chart.  The first query row is 0, the second row is 1, and so on.
endrow	Is the last row from the query that appears on the chart.


Range Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if
**the number of query rows that appear
**on the chart is range restricted.
**If true, it resets the value to false
**(i.e. plots all rows); if false, it
**resets the value to true with a
**restricted range specified by
**startrow and endrow.
*/

PROCEDURE ChartRange IS
  chart og_object;
  rangeflag boolean;
  startrow number := 3;
  endrow number := 9;
BEGIN
  chart := og_get_object('chart');
  rangeflag := og_get_rangeflag(chart);
  if rangeflag = true then
     og_set_rows(chart,false, startrow, endrow);
  else
    og_set_rows(chart, true, startrow, endrow);
  end if;
END;


Size and Position Property

  Examples	  Related Topics

Description  Is the x- and y-coordinates, height, and width of the chart's frame (in layout units).

Syntax

PROCEDURE OG_Set_Frame
  (chart        OG_Object,
   frame        OG_Rectangle,
   damage       BOOLEAN       :=  TRUE,
   update_bbox  BOOLEAN       :=  TRUE);

FUNCTION OG_Get_Frame
  (chart  OG_Object)
RETURN OG_Rectangle;

Parameters

chart	Is the chart object being described.
frame	Is the x- and y-coordinates, height, and width of the chart's frame (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Size and Position Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the frame
**size of the chart, and reduces it by half.
*/

PROCEDURE SizeAndPos IS
  chart og_object;
  rect og_rectangle;
BEGIN
  chart := og_get_object('chart');
    rect := og_get_frame(chart);
  rect.x := rect.x/2;
  rect.y := rect.y/2;
  rect.height := rect.height/2;
  rect.width := rect.width/2;
  og_set_frame(chart, rect);
END;


Start Row Property

  Examples	  Related Topics

Description  Is the first row from the query that appears on the chart.  The first query row is 0, the second row is 1, and so on.

Syntax

(See OG_Set_Rows, above.)

FUNCTION OG_Get_Startrow
  (chart  OG_Object)
RETURN NUMBER;

Parameters

chart	Is the chart object being described.


Start Row Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**startrow and endrow value from chart
**(provided the Plot rows box is checked),
**and resets the range to startrow -1 and
**endrow -1.)
*/

PROCEDURE ChartStartEnd IS
  chart og_object;
 startrow number;
  endrow number;
BEGIN
  chart := og_get_object('chart');
  startrow := og_get_startrow(chart);
  endrow := og_get_endrow(chart);
  og_set_rows(chart,true, startrow-1, endrow-1);
END;


Template Property

  Examples	  Related Topics

Description  Is the handle to the template to be used for the chart.

Syntax

PROCEDURE OG_Set_Template
  (chart        OG_Object,
   template     OG_Template,
   damage       BOOLEAN      :=  TRUE,
   update_bbox  BOOLEAN      :=  TRUE);

FUNCTION OG_Get_Template
  (chart  OG_Object)
RETURN OG_Template;

Parameters

chart	Is the chart object being described.
template	Is the handle to the template to be used for the chart.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Template Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**template handles template1 and template2
**from chart1 and chart2 respectively, and
**assigns template1 to chart2, template2
**to chart1.
*/

PROCEDURE ChartTemplate IS
  chart1 og_object;
  chart2 og_object;
  template1 og_template;
  template2 og_template;
BEGIN
  chart1 := og_get_object('chart1');
  chart2 := og_get_object('chart2');
  template1 := og_get_template(chart1);
  template2 := og_get_template(chart2);
  og_set_template(chart1, template2);
  og_set_template(chart2, template1);
END;


Title Property

  Examples	  Related Topics

Description  Is the title of the chart.

Syntax

PROCEDURE OG_Set_Title
  (chart  OG_Object,
   title  VARCHAR2);

FUNCTION OG_Get_Title
  (chart  OG_Object)
RETURN VARCHAR2;

Parameters

chart	Is the chart object being described.
title	Is the title of the chart.


Title Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
**the title of a chart; compare
**the value with new_title. If
**they are not equal, change the
**title to new_title.
*/

PROCEDURE ChartTitle IS
  chart og_object;
  title varchar2(30);
  new_title varchar2(30) := 'New title';
BEGIN
  chart := og_get_object('chart');
  title := og_get_title(chart);
  if title != new_title then
    og_set_title(chart, new_title);
  end if;
END;


Display Properties

Close Trigger Property

Date Format Property

Height Property

Open Trigger Property

Width Property


Close Trigger Property

  Examples	  Related Topics

Description  Is the name of display's Close Display trigger.

Syntax

PROCEDURE OG_Set_Closetrigger
  (trigger  VARCHAR2);

FUNCTION OG_Get_Closetrigger
RETURN VARCHAR2;

Parameters

trigger	Is the name of display's Close Display trigger.


Close Trigger Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the name
**of the close trigger of the current
**display.  If the current trigger is not
**new_trigger, it sets new_trigger to be the
**current close trigger procedure.
*/

PROCEDURE CloseTrigger IS
  val varchar2(20);
  new_trigger varchar2(20) := 'CURSORDEFAULT';
BEGIN
   val := og_get_closetrigger;
   if val != new_trigger then
     og_set_closetrigger('CursorDefault');
   end if;
END;


Date Format Property

  Examples	  Related Topics

Description  Specifies the date format for parameters.  This must be a valid SQL format string.  For more information, see yourOracle7 Server SQL Reference.

Syntax

OG_Set_Dateformat
  (dateformat  VARCHAR2);

OG_Get_Dateformat
RETURN VARCHAR2;

Parameters

dateformat	Specifies the date format for parameters.  This must be a valid SQL format string.


Date Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the date
**format of display.  If the format is not
**the same as new_datefmt, it sets the current
**format to new_format.
*/

PROCEDURE datefmt IS
  datefmt varchar2(20);
  new_datefmt varchar2(20) := 'DD/MM/YYYY';
BEGIN
  datefmt := og_get_dateformat;
  if datefmt != new_datefmt then
    og_set_dateformat('DD/MM/YYYY');
  end if;
END;


Height Property

  Examples	  Related Topics

Description  Is the height of the layout (in layout units).

Syntax

(See OG_Set_Display_Size.)

FUNCTION OG_Get_Display_Height
RETURN NUMBER;

Parameters

None


Height Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

/*The following procedure reads the width
**and height of the current display and
**reduces the display size by half.
*/

PROCEDURE dimension0 IS
  width number;
  height number;
BEGIN
  width := og_get_display_width;
  height := og_get_display_height;
  og_set_display_size(width/2, height/2);
END;


Open Trigger Property

  Examples	  Related Topics

Description  Is the name of display's Open Display trigger.

Syntax

PROCEDURE OG_Set_Opentrigger
  (trigger  VARCHAR2);

FUNCTION OG_Get_Opentrigger
RETURN VARCHAR2;

Parameters

trigger	Is the name of display's Open Display trigger.


Open Trigger Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the name of
**the open trigger of the current display.
**If the current trigger is not new_trigger,
**it sets new_trigger to be the current open
**trigger procedure.
*/

PROCEDURE OpenTrigger IS
  val varchar2(20);
  new_trigger varchar2(20) := 'TOBLUE';
BEGIN
  val := og_get_opentrigger;
  if val != 'TOBLUE' then
    og_set_opentrigger('toblue');
  end if;
END;


Width Property

  Examples	  Related Topics

Description  Is the width of the layout (in layout units).

Syntax

PROCEDURE OG_Set_Display_Size
  (width   NUMBER,
   height  NUMBER);

FUNCTION OG_Get_Display_Width
RETURN NUMBER;

Parameters

width	Is the width of the layout (in layout units).
height	Is the height of the layout (in layout units).


Width Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the width
**and height of the current display and
**reduces the display size by half.
*/

PROCEDURE dimension0 IS
  width number;
  height number;
BEGIN
  width := og_get_display_width;
  height := og_get_display_height;
  og_set_display_size(width/2, height/2);
END;


Frame (Axis Chart) Properties

Baseline Axis Property

Baseline Value Property

Category Width Property

Custom Date Format Property

Custom Number Format Property

Reference Line Count Property

Second Y Axis Property


Baseline Axis Property

  Examples	  Related Topics

Description  Specifies the axis to which the baseline value is compared to determine its position.  The value of this property may be one of the following built-in constants:

OG_Template

OG_Y1_Axis

OG_Y2_Axis

Syntax

PROCEDURE OG_Set_Baseaxis
  (template  OG_Template,
   baseaxis  NUMBER);

FUNCTION OG_Get_Baseaxis
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
baseaxis	Specifies the axis to which the baseline value is compared to determine its position.


Baseline Axis Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

*/The following procedure specifies the
**date format for the baseline label.
*/

PROCEDURE CusDateFmt IS
  chart og_object;
  template og_template;
  custDate date;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  custDate := og_get_cust_date(template);
  if custDate != '06-DEC-88' then
    og_set_cust_date(template, '06-DEC-96');
  end if;
END;


Baseline Value Property

  Examples	  Related Topics

Description  Is the value used as the starting point for plotting fields along the value axis.  The value of this property may be one of the following built-in constants:

OG_Custom_Baseline

OG_Min_Baseline

OG_Zero_Baseline

Syntax

PROCEDURE OG_Set_Basevalue
  (template   OG_Template,
   basevalue  NUMBER);

FUNCTION OG_Get_Basevalue
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
basevalue	Is the value used as the starting point for plotting fields along the value axis.


Baseline Value Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
**the baseline value of the field
**template of a chart.If the current
** baseline value is ZERO,
**the procedure resets the value to
**MAX; If the current baseline value
**is any value other than ZERO, the
**procedure resets the value to ZERO.
*/

PROCEDURE BaseLine IS
  chart og_object;
  template og_template;
  value number;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  value := og_get_basevalue(template);
  if value = og_zero_baseline then
    og_set_basevalue(template, og_max_baseline);
  else
    og_set_basevalue(template, og_zero_baseline);
  end if;
  og_update_chart(chart);
END;


Category Width Property

  Examples	  Related Topics

Description  Is the width of the bars in a bar or column chart, as a percentage of the "strip width."  The strip width is the widest the bars can be without overlapping each other, and it is determined by dividing the length of the category axis by the number of bars to be plotted.

Syntax

PROCEDURE OG_Set_Catwidth
  (template  OG_Template,
   catwidth  NUMBER);

FUNCTION OG_Get_Catwidth
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
catwidth	Is the width of the bars in a bar or column chart, as a percentage of the "strip width."  The strip width is the widest the bars can be without overlapping each other, and it is determined by dividing the length of the category axis by the number of bars to be plotted.


Category Width Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure reduces the
** category width of the bars by half of
**its original width.
*/

PROCEDURE CatWidth IS
  chart og_object;
  template og_template;
  width number;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  width := og_get_catwidth(template);
  og_set_catwidth(template, width/2);
END;


Custom Date Format Property

  Examples	  Related Topics

Description  Specifies the custom date to set the custom date value to.  This will also automatically set the base value to OG_CUSTOM_BASELINE.

Syntax

PROCEDURE OG_Set_Cust_Date
  (template   OG_Template,
   cust_date  DATE);

FUNCTION OG_Get_Cust_Date
  (template  OG_Template)
RETURN DATE;

Parameters

template	Is the chart template.
cust_date	Specifies the date value for a date axis type.  This value is used as a reference for drawing the data points along the value axis.


Custom Date Format Property Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /*The following procedure specifies
**the date format for the baseline label.
*/

PROCEDURE CusDateFmt IS
  chart og_object;
  template og_template;
  custDate date;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  custDate := og_get_cust_date(template);
  if custDate != '06-DEC-88' then
    og_set_cust_date(template, '06-DEC-96');
  end if;
END;


Custom Number Format Property

  Examples	  Related Topics

Description  Specifies the custom number to set the baseline to.  This will also automatically set the base value to OG_CUSTOM_BASELINE.

Syntax

PROCEDURE OG_Set_Cust_Num
  (template  OG_Template,
   cust_num  NUMBER);

FUNCTION OG_Get_Cust_Num
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
cust_num	Specifies the baseline value for a number axis type.  This value is used as a reference for drawing the data points along the value axis.


Custom Number Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure specifies
**the number format for the baseline label.
*/

PROCEDURE CusNumFmt IS
  chart og_object;
  template og_template;
  num number;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  num := og_get_cust_num(template);
  og_set_cust_num(template, num/2);
END;


Reference Line Count Property

  Examples	  Related Topics

Description  Is the number of reference lines that belong to the chart template.

Syntax

FUNCTION OG_Get_Reflinect
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.


Reference Line Count Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**reference line count and prints the
**number to a text object.
*/

PROCEDURE RefLineCnt IS
  text og_object;
  chart og_object;
  template og_template;
  cnt number;
BEGIN
  text := og_get_object('text object');
  chart := og_get_object('chart');
  template := og_get_template(chart);
  cnt := og_get_reflinect(template);
  og_set_str(text, cnt);
END;


Second Y Axis Property

  Examples	  Related Topics

Description  Specifies whether a second Y axis appears in the chart.

Syntax

PROCEDURE OG_Set_Second_Y
  (template  OG_Template,
   second_y  BOOLEAN);

FUNCTION OG_Get_Second_Y
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
second_y	Specifies whether a second Y axis appears in the chart.


Second Y Axis Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure determines if
**a second Y axis appears on the chart.
**If not, it adds a second one.
*/

PROCEDURE SecondY IS
  chart og_object;
  template og_template;
  axis boolean;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  axis := og_get_second_y(template);
    if axis = false then
      og_set_second_y(template, true);
   end if;
  og_update_chart(chart);
END;


Frame (Generic) Properties

Depth Size Property

Field Template Count Property

Frame Type Property

Legend Property

Legend Column Count Property

Name Property

Plot Frame Property

Root Property

Shadow Direction Property

Shadow Size Property


Depth Size Property

  Examples	  Related Topics

Description  Specifies the amount of depth with which the chart frame and elements are drawn to provide them with a 3-dimensional look.  The value of this property may be one of the following built-in constants:

OG_None_Depthsize

OG_Small_Depthsize

OG_Medium_Depthsize

OG_Large_None_Depthsize

OG_Xlarge_Depthsize

Syntax

PROCEDURE OG_Set_Depthsize
  (template   OG_Template,
   depthsize  NUMBER);

FUNCTION OG_Get_Depthsize
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
depthsize	Specifies the amount of depth with which the chart frame and elements are drawn to provide them with a 3-dimensional look.


Depth Size Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following reads the depth size
**of the chart, and changes the depth
**to a different value.
*/

PROCEDURE FrameDepth IS
  chart og_object;
  template og_template;
  depth number;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  depth := og_get_depthsize(template);
  if depth = og_none_depthsize then
     og_set_depthsize(template, og_small_depthsize);
  elsif depth = og_small_depthsize then
     og_set_depthsize(template, og_medium_depthsize);
  elsif depth = og_medium_depthsize then
     og_set_depthsize(template, og_large_depthsize);
  elsif depth = og_large_depthsize then
     og_set_depthsize(template, og_xlarge_depthsize);
  elsif depth = og_xlarge_depthsize then
     og_set_depthsize(template, og_none_depthsize);
  end if;
END;


Field Template Count Property

  Examples	  Related Topics

Description  Is the number of field templates that belong to the chart template.

Syntax

FUNCTION OG_Get_Ftempct
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.


Field Template Count Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the number of
**the field template that belongs to the current
**template,and prints the value to a text object.
*/

PROCEDURE FTempCnt IS
  text og_object;
  chart og_object;
  template og_template;
  num number;
BEGIN
  text := og_get_object('text object');
  chart := og_get_object('chart');
  template := og_get_template(chart);
  num := og_get_ftempct(template);
  og_set_str(text, num);
 END;


Frame Type Property

  Examples	  Related Topics

Description  Is the type of chart represented by this template  The value of this property may be one of the following built-in constants:

OG_Axis_Frametype

OG_Pie_Frametype

OG_Table_Frametype

Syntax

FUNCTION OG_Get_Frametype
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.


Frame Type Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following reads the frame type
**and prints the value to a text object.
*/

PROCEDURE FrameType IS
  text og_object;
  chart og_object;
  template og_template;
  num number;
BEGIN
  text := og_get_object('text object');
  chart := og_get_object('chart');
  template := og_get_template(chart);
  num := og_get_frametype(template);
  if num = og_axis_frametype then
    og_set_str(text, 'axis');
  elsif num = og_pie_frametype then
    og_set_str(text ,'pie');
  elsif num = og_table_frametype then
    og_set_str(text, 'table');
  end if;
END;


Legend Property

  Examples	  Related Topics

Description  Specifies whether the chart's legend should be shown.  (Not applicable to table charts.)

Syntax

PROCEDURE OG_Set_Legend
  (template  OG_Template,
   show      BOOLEAN);

FUNCTION OG_Get_Legend
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
show	Specifies whether the chart's legend should be shown.  (Not applicable to table charts.)


Legend Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines
**if a legend is shown.  If a legend
**is shown, it hides it; if a legend
**is hidden, it shows it.
*/

PROCEDURE FrameLegend IS
  chart og_object;
  template og_template;
  val boolean;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  val := og_get_legend(template);
  if val = true then
     og_set_legend(template, false);
  else
     og_set_legend(template, true);
  end if;
END;


Legend Column Count Property

  Examples	  Related Topics

Description  Is the number of columns used to display the labels that appear in the legend.

Syntax

PROCEDURE OG_Set_Legendcolct
  (template  OG_Template,
   colct     NUMBER);

FUNCTION OG_Get_Legendcolct
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
colct	Is the number of columns used to display the labels that appear in the legend.


Legend Column Count Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the number of
**columns in the legend box.  If there is more
**than one column in the box, it changes the
**number of the columns to one; if there is
**one column, it changes the number of columns
**to two.
*/

PROCEDURE FrameLegendCol IS
  chart og_object;
  template og_template;
  num number;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  num := og_get_legendcolct(template);
  if num > 1 then
     og_set_legendcolct(template, 1);
  else
     og_set_legendcolct(template, 2);
  end if;
END;


Name Property

  Examples	  Related Topics

Description  Is the name of the chart template.

Syntax

PROCEDURE OG_Set_Frame_Name
  (template  OG_Template,
   name      VARCHAR2);

FUNCTION OG_Get_Frame_Name
  (template  OG_Template)
RETURN VARCHAR2;

Parameters

template	Is the chart template.
name	Is the name of the chart template.


Name Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following reads the frame name.
**If the name is not 'template1', it sets
**it to 'template1'.
*/

PROCEDURE FrameName IS
  chart og_object;
  template og_template;
  name varchar2(30);
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  name := og_get_frame_name(template);
  if name != 'template1' then
    og_set_frame_name(template, 'template1');
  end if;
END;


Plot Frame Property

  Examples	  Related Topics

Description  Specifies whether the rectangle that surrounds the chart should be shown.  (Not applicable to pie charts.)

Syntax

PROCEDURE OG_Set_Plotframe
  (template  OG_Template,
   show      BOOLEAN);

FUNCTION OG_Get_Plotframe
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
show	Specifies whether the rectangle that surrounds the chart should be shown.


Plot Frame Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines
**whether a plot frame is drawn.  If
**true, it removes the plot frame;
**if false, it adds a plot frame to
**the current chart.
*/

PROCEDURE FramePlot IS
  chart og_object;
  template og_template;
  val boolean;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  val := og_get_plotframe(template);
  if val = true then
     og_set_plotframe(template, false);
  else
     og_set_plotframe(template, true);
  end if;
END;


Root Property

  Examples	  Related Topics

Description  Is the handle to the chart template.

Syntax

FUNCTION OG_Get_Root
  (template  OG_Template)
RETURN OG_Object;

Parameters

template	Is the chart template.


Root Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The procedure gets the handle
**(root)of the chart object.
*/

PROCEDURE FrameRoot IS
  chart og_object;
  template og_template;
  root og_object;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  root := og_get_root(template);
END;


Shadow Direction Property

  Examples	  Related Topics

Description  Specifies the direction of the shadow with which the chart frame and elements are drawn.  The value of this property may be one of the following built-in constants:

OG_Upperright_Shadowdir

OG_Upperleft_Shadowdir

OG_Lowerright_Shadowdir

OG_Lowerleft_Shadowdir

Syntax

PROCEDURE OG_Set_Shadowdir
  (template   OG_Template,
   shadowdir  NUMBER);

FUNCTION OG_Get_Shadowdir
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
shadowdir	Specifies the direction of the shadow with which the chart frame and elements are drawn.


Shadow Direction Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

*/The following reads the shadow direction of
**the chart, and changes it to a different
**value.
*/

PROCEDURE FrameShadowDir IS
  chart og_object;
  template og_template;
  shadow number;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  shadow := og_get_shadowdir(template);
  if shadow = og_upperright_shadowdir then
     og_set_shadowdir(template, og_lowerleft_shadowdir);
  elsif shadow = og_lowerleft_shadowdir then
     og_set_shadowdir(template, og_upperleft_shadowdir);
  elsif shadow = og_upperleft_shadowdir then
     og_set_shadowdir(template, og_lowerright_shadowdir);
  elsif shadow = og_lowerright_shadowdir then
     og_set_shadowdir(template, og_upperright_shadowdir);
  end if;
END;


Shadow Size Property

  Examples	  Related Topics

Description  Specifies the size of the shadow with which the chart frame and elements are drawn.  The value of this property may be one of the following built-in constants:

OG_None_Shadowsize

OG_Small_Shadowsize

OG_Medium_Shadowsize

OG_Large_Shadowsize

OG_Xlarge_Shadowsize

Syntax

PROCEDURE OG_Set_Shadowsize
  (template    OG_Template,
   shadowsize  NUMBER);

FUNCTION OG_Get_Shadowsize
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
shadowsize	Specifies the size of the shadow with which the chart frame and elements are drawn.


Shadow Size Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

/*The following procedure reads the shadow size
**of the chart, and changes the size to a
**different value.
*/

PROCEDURE FrameShadow IS
  chart og_object;
  template og_template;
  shadow number;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  shadow := og_get_shadowsize(template);
  if shadow = og_none_shadowsize then
     og_set_shadowsize(template, og_small_shadowsize);
  elsif shadow = og_small_shadowsize then
     og_set_shadowsize(template, og_medium_shadowsize);
  elsif shadow = og_medium_shadowsize then
     og_set_shadowsize(template, og_large_shadowsize);
  elsif shadow = og_large_shadowsize then
     og_set_shadowsize(template, og_xlarge_shadowsize);
  elsif shadow = og_xlarge_shadowsize then
     og_set_shadowsize(template, og_none_shadowsize);
  end if;
END;


Frame (Pie Chart) Properties

Categories Property

Category Date Format Property

Category Number Format Property

Data Values Property

No Overlap Property

Other Property

Percent Format Property

Percent Values Property

Plot Order Property

Ticks Property

Usage Property

Usage Value Property

Value Format Property


Categories Property

  Examples	  Related Topics

Description  Specifies whether each pie slice is labeled with the name of the category it represents.

Syntax

PROCEDURE OG_Set_Categs
  (template  OG_Template,
   categs    BOOLEAN);

FUNCTION OG_Get_Categs
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
categs	Specifies whether each pie slice is labeled with the name of the category it represents.


Categories Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure gets
**information about the relationship
**between individual pie slices and
**the complete chart.  If the current
**relationship is TOTALVALUE, the
**procedure resets the relationship
** to PERCENTAGE with a value of  50;
**If the current relationship is
**PERCENTAGE, the procedure resets
**the relationship to TOTALVALUE with
**a value of 400000.
*/

PROCEDURE PieUsage IS
  pie og_object;
  template og_template;
  usage number;
  usagevalue number;
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  usage := og_get_usage(template);
  if usage = og_totalvalue_usage then
     usagevalue := og_get_usagevalue(template);
     og_set_usage(template, og_pct_usage, 50);
   elsif usage = og_pct_usage then
     usagevalue := og_get_usagevalue(template);
     og_set_usage(template, og_totalvalue_usage, 400000);
  end if;
  og_update_chart(pie);
END;


Category Date Format Property

  Examples	  Related Topics

Description  Specifies the date format for the category labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.

Syntax

PROCEDURE OG_Set_Catdatefmt
  (template    OG_Template,
   catdatefmt  VARCHAR2);

FUNCTION OG_Get_Catdatefmt
  (template  OG_Template)
RETURN VARCHAR2;

Parameters

template	Is the chart template.
catdatefmt	Specifies the date format for the category labels.  This must be a valid SQL format string.


Category Date Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure changes the
**pie slice label's date format if the
**format is not currently
**'DD-MM-YY'.
*/

PROCEDURE CatDateFmt IS
  pie og_object;
  template og_template;
  format varchar2(20);
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  format := og_get_catdatefmt(template);
  if format != 'MM-DD-YY' then
   og_set_catdatefmt(template, 'MM-DD-YY');
  end if;
  og_update_chart(pie);
END;


Category Number Format Property

  Examples	  Related Topics

Description  Specifies the number format for the category labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.

Syntax

PROCEDURE OG_Set_Catnumfmt
  (template   OG_Template,
   catnumfmt  VARCHAR2);

FUNCTION OG_Get_Catnumfmt
  (template  OG_Template)
RETURN VARCHAR2;

Parameters

template	Is the chart template.
catnumfmt	Specifies the number format for the category labels.  This must be a valid SQL format string.


Category Number Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure changes the
**pie slice label's number format if
**the format is not currently
**'9,9,9,9'.
*/

PROCEDURE CatNumFmt IS
  pie og_object;
  template og_template;
  format varchar2(20);
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  format := og_get_catnumfmt(template);
  if format != '9,9,9,9' then
    og_set_catnumfmt(template, '9,9,9,9');
  end if;
  og_update_chart(pie);
END;


Data Values Property

  Examples	  Related Topics

Description  Specifies whether each pie slice is labeled with its data value.

Syntax

PROCEDURE OG_Set_Datavals
  (template  OG_Template,
   datavals  BOOLEAN);

FUNCTION OG_Get_Datavals
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
datavals	Specifies whether each pie slice is labeled with its data value.


Data Values Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure hides/shows
** the data value for each pie slice.
*/

PROCEDURE DataVals IS
  pie og_object;
  template og_template;
  val boolean;
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  val := og_get_datavals(template);
  if val = true then
   og_set_datavals(template, false);
  elsif val = false then
   og_set_datavals(template, true);
  end if;
  og_update_chart(pie);
END;


No Overlap Property

  Examples	  Related Topics

Description  Specifies that the labels for the pie slices should not overlap each other.

Syntax

PROCEDURE OG_Set_Nooverlap
  (template   OG_Template,
   nooverlap  BOOLEAN);

FUNCTION OG_Get_Nooverlap
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
nooverlap	Specifies that the labels for the pie slices should not overlap each other.


No Overlap Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines if
**pie slice labels are allowed to overlap.
**If overlapping is allowed, the procedure
**disallows it.
*/

PROCEDURE NoOverlap IS
  pie og_object;
  template og_template;
  val boolean;
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  val := og_get_nooverlap(template);
  if val = false then
     og_set_nooverlap(template, true);
  end if;
  og_update_chart(pie);
END;


Other Property

  Examples	  Related Topics

Description  Specifies the minimum percentage of the chart that a data value must represent in order for it to appear as an individual slice in the pie chart.  Data values that represent percentages below this number are combined into a single pie slice with the label "Other".

Syntax

PROCEDURE OG_Set_Other
  (template  OG_Template,
   other     NUMBER);

FUNCTION OG_Get_Other
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
other	Specifies the minimum percentage of the chart that a data value must represent in order for it to appear as an individual slice in the pie chart.  Data values that represent percentages below this number are combined into a single pie slice with the label "Other".


Other Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure doubles
**the percentage value for which
**any chart slice with a value
**less than or equal to the
**percentage value will be labeled
**”other.”
*/

PROCEDURE Other IS
  pie og_object;
  template og_template;
  num number;
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  num := og_get_other(template);
  og_set_other(template, num*2);
  og_update_chart(pie);
END;


Percent Format Property

  Examples	  Related Topics

Description  Specifies the number format for the percent value labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.

Syntax

PROCEDURE OG_Set_Pctfmt
  (template  OG_Template,
   pctfmt    VARCHAR2);

FUNCTION OG_Get_Pctfmt
  (template  OG_Template)
RETURN VARCHAR2;

Parameters

template	Is the chart template.
pctfmt	Specifies the number format for the percent value labels.  This must be a valid SQL format string.


Percent Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure hides/shows the
**percent value for each pie slice.
*/

PROCEDURE PctVals IS
  pie og_object;
  template og_template;
  val boolean;
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  val := og_get_pctvalues(template);
  if val = true then
   og_set_pctvalues(template, false);
  elsif val = false then
   og_set_pctvalues(template, true);
  end if;
  og_update_chart(pie);
END;


Percent Values Property

  Examples	  Related Topics

Description  Specifies whether each pie slice is labeled with the percentage of the complete chart it represents.

Syntax

PROCEDURE OG_Set_Pctvalues
  (template   OG_Template,
   pctvalues  BOOLEAN);

FUNCTION OG_Get_Pctvalues
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
pctvalues	Specifies whether each pie slice is labeled with the percentage of the complete chart it represents.


Percent Values Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure hides/shows
**the percent value for each pie slice.
*/

PROCEDURE PctVals IS
  pie og_object;
  template og_template;
  val boolean;
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  val := og_get_pctvalues(template);
  if val = true then
   og_set_pctvalues(template, false);
  elsif val = false then
   og_set_pctvalues(template, true);
  end if;
  og_update_chart(pie);
END;


Plot Order Property

  Examples	  Related Topics

Description  Specifies the direction in which the data values are plotted.  The value of this property may be one of the following built-in constants:

OG_Ccw_Plotorder   Means values are plotted in a counter-clockwise direction.

OG_Cw_Plotorder   Means values are plotted in a clockwise direction.

Syntax

PROCEDURE OG_Set_Plotorder
  (template   OG_Template,
   plotorder  NUMBER);

FUNCTION OG_Get_Plotorder
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
plotorder	Specifies the direction in which the data values are plotted.


Plot Order Property Examples

  Alphabetic List           [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**direction in which the data values
**are plotted, and reverses the
**plotting direction.
*/

PROCEDURE plotOrder IS
  pie og_object;
  template og_template;
  porder number;
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  porder := og_get_plotorder(template);
  if porder = og_cw_plotorder then
     og_set_plotorder(template, og_ccw_plotorder);
  else
     og_set_plotorder(template, og_cw_plotorder);
  end if;
  og_update_chart(pie);
END;


Ticks Property

  Examples	  Related Topics

Description  Specifies whether the tick marks that connect each pie slice to its label are shown.

Syntax

PROCEDURE OG_Set_Ticks
  (template  OG_Template,
   ticks     BOOLEAN);

FUNCTION OG_Get_Ticks
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
ticks	Specifies whether the tick marks that connect each pie slice to its label are shown.


Ticks Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure hides/
**shows the ticks for each pie
**slice.
*/

PROCEDURE ticks IS
  pie og_object;
  template og_template;
  val boolean;
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  val := og_get_ticks(template);
  if val = true then
   og_set_ticks(template, false);
  else
   og_set_ticks(template, true);
  end if;
  og_update_chart(pie);
END;


Usage Property

  Examples	  Related Topics

Description  Specifies the relationship between the individual pie slices and the complete chart.  The value of this property may be one of the following built-in constants:

OG_Totalvalue_Usage

OG_Pct_Usage

Syntax

PROCEDURE OG_Set_Usage
  (template  OG_Template,
   usage       NUMBER,
   usagevalue  NUMBER);

FUNCTION OG_Get_Usage
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
usage	Specifies the relationship between the individual pie slices and the complete chart.
usagevalue	Each pie slice is plotted as if its data value is a percentage of the total value specified here.  (Valid only is usage is set to OG_TOTALVALUE_USAGE.


Usage Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure gets
**information about the relationship
**between individual pie slices and
**the complete chart.  If the current
**relationship is TOTALVALUE, the procedure
**resets the relationship to PERCENTAGE
**with a value of  50.  If the current
**relationship is PERCENTAGE, the procedure
**resets the relationship to TOTALVALUE
**with a value of 400000.
*/

PROCEDURE PieUsage IS
  pie og_object;
  template og_template;
  usage number;
  usagevalue number;
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  usage := og_get_usage(template);
  if usage = og_totalvalue_usage then
     usagevalue := og_get_usagevalue(template);
     og_set_usage(template, og_pct_usage, 50);
   elsif usage = og_pct_usage then
     usagevalue := og_get_usagevalue(template);
     og_set_usage(template, og_totalvalue_usage, 400000);
  end if;
  og_update_chart(pie);
END;


Usage Value Property

  Examples	  Related Topics

Description  Each pie slice is plotted as if its data value is a percentage of the total value specified here.

Syntax

(See OG_Set_Usage, above.)

FUNCTION OG_Get_Usagevalue
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.


Usage Value Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure gets
**information about the relationship
**between individual pie slices and
**the complete chart.  If the current
**relationship is TOTALVALUE, the procedure
**resets the relationship to PERCENTAGE
**with a value of  50.  If the current
**relationship is PERCENTAGE, the procedure
**resets the relationship to TOTALVALUE
**with a value of 400000.
*/

PROCEDURE PieUsage IS
  pie og_object;
  template og_template;
  usage number;
  usagevalue number;
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  usage := og_get_usage(template);
  if usage = og_totalvalue_usage then
     usagevalue := og_get_usagevalue(template);
     og_set_usage(template, og_pct_usage, 50);
   elsif usage = og_pct_usage then
     usagevalue := og_get_usagevalue(template);
     og_set_usage(template, og_totalvalue_usage, 400000);
  end if;
  og_update_chart(pie);
END;


Value Format Property

  Examples	  Related Topics

Description  Specifies the number format for the data value labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.

Syntax

PROCEDURE OG_Set_Valuefmt
  (template     OG_Template,
   valuenumfmt  VARCHAR2);

FUNCTION OG_Get_Valuefmt
  (template  OG_Template)
RETURN VARCHAR2;

Parameters

template	Is the chart template.
valuenumfmt	Specifies the number format for the data value labels.


Value Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure changes the pie
**slice label's value format if the format
**is not currently '0999'.
*/

PROCEDURE ValFmt IS
  pie og_object;
  template og_template;
  format varchar2(20);
BEGIN
  pie := og_get_object('pie');
  template := og_get_template(pie);
  format := og_get_valuefmt(template);
  if format != '0999' then
    og_set_valuefmt(template, '0999');
  end if;
  og_update_chart(pie);
END;


Frame (Table Chart) Properties

Auto Maximum Property

Auto Minimum Property

Column Names Property

Grid Count Property

Horizontal Grid Property

Maximum Number Of Rows Property

Minimum Number Of Rows Property

Vertical Grid Property


Auto Maximum Property

  Examples	  Related Topics

Description  Specifies whether the maximum number of rows that appear on the chart is set to Auto.

Syntax

PROCEDURE OG_Set_Automax
  (template  OG_Template,
   automax   BOOLEAN,
   maxrows   NUMBER);

FUNCTION OG_Get_Automax
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
automax	Specifies whether the maximum number of rows that appear on the chart is set to Auto.
maxrows	Specifies the maximum number of rows that appear on the chart (if automax is FALSE).


Auto Maximum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines if
**there is a maximum number of rows to
**be displayed in the table or if the
**number of rows is automatically
**determined.  If the number of
**rows is not automatically determined,
**the procedure reads the number of rows
**the table displays currently and resets
**it to be automatically determined.
*/

PROCEDURE AutoMax IS
  table1 og_object;
  template og_template;
  val boolean;
  maxrows number := 2;
BEGIN
  table1 := og_get_object('table');
  template := og_get_template(table1);
  val := og_get_automax(template);
  if val = false then
     maxrows := og_get_maxrows(template);
     og_set_automax(template, true, maxrows/2);
  end if;
  og_update_chart(table1);
END;


Auto Minimum Property

  Examples	  Related Topics

Description  Specifies whether the minimum number of rows that appear on the chart is set to Auto.

Syntax

PROCEDURE OG_Set_Automin
  (template  OG_Template,
   automin   BOOLEAN,
   minrows   NUMBER);

FUNCTION OG_Get_Automin
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
automin	Specifies whether the minimum number of rows that appear on the chart is set to Auto.
minrows	Specifies the minimum number of rows that appear on the chart (if automin is FALSE).


Auto Minimum Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*"The following procedure
**determines if there is a
**minimum number of rows that
**must be displayed in the
**table or whether the number of
**rows is automatically determined.
**If the number of rows is not
**automatically determined, the procedure
**reads the number of rows the table
**currently displays and resets it to
**be automatically determined.
 */

PROCEDURE AutoMax IS
  table1 og_object;
  template og_template;
  val boolean;
  maxrows number := 2;
BEGIN
  table1 := og_get_object('table');
  template := og_get_template(table1);
  val := og_get_automax(template);
  if val = false then
     maxrows := og_get_maxrows(template);
     og_set_automax(template, true, maxrows/2);
  end if;
  og_update_chart(table1);
END;


Column Names Property

  Examples	  Related Topics

Description  Specifies whether the names of the columns appear as the first row in the chart.

Syntax

PROCEDURE OG_Set_Cname
  (template  OG_Template,
   cname     BOOLEAN);

FUNCTION OG_Get_Cname
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
cname	Specifies whether the names of the columns appear as the first row in the chart.


Column Names Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure hides/shows the
**table’s column names.
*/

PROCEDURE ColNames IS
  table1 og_object;
  template og_template;
  val boolean;
BEGIN
  table1 := og_get_object('table');
  template := og_get_template(table1);
  val := og_get_cname(template);
  if val = true then
    og_set_cname(template, false);
  elsif val = false then
    og_set_cname(template, true);
  end if;
  og_update_chart(table1);
END;


Grid Count Property

  Examples	  Related Topics

Description  Is the number of rows of data plotted before each horizontal grid line is drawn (if Horizontal Grid is set to TRUE).

Syntax

PROCEDURE OG_Set_Gridct
  (template  OG_Template,
   gridct    NUMBER);

FUNCTION OG_Get_Gridct
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.
gridct	Is the number of rows of data plotted before each horizontal grid line is drawn (if Horizontal Grid is set to TRUE).


Grid Count Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure doubles
**the grid count of the table.
*/

PROCEDURE gridcnt IS
  table1 og_object;
  template og_template;
  cnt number;
BEGIN
  table1 := og_get_object('table');
  template := og_get_template(table1);
  cnt := og_get_gridct(template);
  og_set_gridct(template, cnt*2);
  og_update_chart(table1);
END;


Horizontal Grid Property

  Examples	  Related Topics

Description  Specifies whether horizontal grid lines appear between the rows.

Syntax

PROCEDURE OG_Set_Hgrid
  (template  OG_Template,
   hgrid     BOOLEAN);

FUNCTION OG_Get_Hgrid
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
hgrid	Specifies whether horizontal grid lines appear between the rows.


Horizontal Grid Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure hides/shows
**horizontal grid lines.
*/

PROCEDURE HoriGrid IS
  table1 og_object;
  template og_template;
  val boolean;
BEGIN
  table1 := og_get_object('table');
  template := og_get_template(table1);
  val := og_get_hgrid(template);
  if val = true then
     og_set_hgrid(template, false);
  elsif val = false then
     og_set_hgrid(template, true);
  end if;
  og_update_chart(table1);
END;


Maximum Number of Rows Property

  Examples	  Related Topics

Description  Specifies the maximum number of rows that appear on the chart (if Auto Maximum is FALSE).

Syntax

(See OG_Set_Automax, above.)

FUNCTION OG_Get_Maxrows
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.


Maximum Number of Rows Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines
**if there is a maximum number of rows to
**be displayed in the table or if the
**number of rows is automatically
**determined.  If the number of rows is
**automatically determined, the procedure
**reads the number of rows the table
**displays currently and resets it to be
**automatically determined.
*/

PROCEDURE AutoMax IS
  table1 og_object;
  template og_template;
  val boolean;
  maxrows number := 2;
BEGIN
  table1 := og_get_object('table');
  template := og_get_template(table1);
  val := og_get_automax(template);
  if val = false then
     maxrows := og_get_maxrows(template);
     og_set_automax(template, true, maxrows/2);
  end if;
  og_update_chart(table1);
END;


Minimum Number of Rows Property

  Examples	  Related Topics

Description  Specifies the maximum number of rows that appear on the chart (if Auto Minimum is FALSE).

Syntax

(See OG_Set_Automin, above.)

FUNCTION OG_Get_Minrows
  (template  OG_Template)
RETURN NUMBER;

Parameters

template	Is the chart template.


Minimum Number of Rows Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

/*"The following procedure
**determines if there is a
**minimum number of rows that
**must be displayed in the
**table or whether the number of
**rows is automatically determined.
**If the number of rows is not
**automatically determined, the procedure
**reads the number of rows the table
**currently displays and resets it to
**be automatically determined.
 */

PROCEDURE AutoMax IS
  table1 og_object;
  template og_template;
  val boolean;
  maxrows number := 2;
BEGIN
  table1 := og_get_object('table');
  template := og_get_template(table1);
  val := og_get_automax(template);
  if val = false then
     maxrows := og_get_maxrows(template);
     og_set_automax(template, true, maxrows/2);
  end if;
  og_update_chart(table1);
END;


Vertical Grid Property

  Examples	  Related Topics

Description  Specifies whether vertical grid lines appear between the columns.

Syntax

PROCEDURE OG_Set_Vgrid
  (template  OG_Template,
   vgrid     BOOLEAN);

FUNCTION OG_Get_Vgrid
  (template  OG_Template)
RETURN BOOLEAN;

Parameters

template	Is the chart template.
vgrid	Specifies whether vertical grid lines appear between the columns.


Vertical Grid Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure hides/shows
**vertical grid lines.
*/

PROCEDURE VertGrid IS

  table1 og_object;

  template og_template;

  val boolean;

BEGIN

  table1 := og_get_object('table');

  template := og_get_template(table1);

  val := og_get_vgrid(template);

  if val = true then

     og_set_vgrid(template, false);

  elsif val = false then

     og_set_vgrid(template, true);

  end if;

  og_update_chart(table1);

END.


Field Template (Generic) Properties

Color Rotation Property

Date Format Property

Name Property

Number Format Property

Root Property


Color Rotation Property

  Examples	  Related Topics

Description  Specifies whether Graphics Builder automatically rotates through the color or pattern palette to select a unique shading for each field that uses this field template.  The value of this property may be one of the following built-in constants:

OG_None_Colorrot

OG_Auto_Colorrot

OG_Color_Colorrot

OG_Pattern_Colorrot

OG_Both_Colorrot

Syntax

PROCEDURE OG_Set_Colorrot
  (ftemp     OG_Ftemp,
   colorrot  NUMBER);

FUNCTION OG_Get_Colorrot
  (ftemp  OG_Ftemp)
RETURN NUMBER;

Parameters

ftemp	Is the field template being described.
colorrot	Specifies whether Graphics Builder automatically rotates through the color or pattern palette to select a unique shading for each field that uses this field template.


Color Rotation Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads if any
**color rotation is applied to the chart.
**If none has been applied, it applies
**AUTO color rotation.  If another method
**of color rotation is currently applied,
**it changes the rotation to NONE.
*/

PROCEDURE fieldColRot IS
  ftemp og_ftemp;
  color number;
BEGIN
  ftemp := og_get_ftemp(og_get_template(og_get_object('chart')),0);
  color := og_get_colorrot(ftemp);
  if color = og_none_colorrot then
     og_set_colorrot(ftemp, og_auto_colorrot);
  else
     og_set_colorrot(ftemp, og_none_colorrot);
 end if;
     og_update_chart(og_get_object('chart'));
END;


Date Format Property

  Examples	  Related Topics

Description  Specifies the date format for the field labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.

Syntax

PROCEDURE OG_Set_Datefmt
  (ftemp     OG_Ftemp,
   date_fmt  VARCHAR2);

FUNCTION OG_Get_Datefmt
  (ftemp  OG_Ftemp)
RETURN VARCHAR2;

Parameters

ftemp	Is the field template being described.
date_fmt	Specifies the date format for the field labels.  This must be a valid SQL format string.


Date Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 */The following procedure
**determines if label number
**formats are all'9,9,9,9'.
**If not, it changes them all
**to '9,9,9,9'.
*/

PROCEDURE fieldDateFmt IS
  ftemp og_ftemp;
  datefmt varchar2(20);
BEGIN
  ftemp := og_get_ftemp(og_get_template(og_get_object('chart')),0);
  datefmt := og_get_datefmt(ftemp);
  if datefmt != 'DD-MM-YYYY' then
    og_set_datefmt(ftemp, 'DD-MM-YYYY');
  end if;
END;


Name Property

  Examples	  Related Topics

Description  Is the name of the field template.

Syntax

PROCEDURE OG_Set_Ftemp_Name
  (ftemp  OG_Ftemp,
   name   VARCHAR2);

FUNCTION OG_Get_Ftemp_Name
  (ftemp  OG_Ftemp)
RETURN VARCHAR2;

Parameters

ftemp	Is the field template being described.
name	Is the name of the field template.


Name Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure
**appends a '1' to the current
**field template's name.
*/

PROCEDURE fieldname IS
  ftemp og_ftemp;
  chart og_object;
  name varchar2(20);
BEGIN
  ftemp := og_get_ftemp(og_get_template(og_get_object('chart')),0);
  name := og_get_ftemp_name(ftemp);
  og_set_ftemp_name(ftemp, name||'1');
END;


Number Format Property

  Examples	  Related Topics

Description  Specifies the number format for the field labels.  This must be a valid SQL format string.  For more information, see your Oracle7 Server SQL Reference.

Syntax

PROCEDURE OG_Set_Numfmt
  (ftemp    OG_Ftemp,
   num_fmt  VARCHAR2);

FUNCTION OG_Get_Numfmt
  (ftemp  OG_Ftemp)
RETURN VARCHAR2;

Parameters

ftemp	Is the field template being described.
num_fmt	Specifies the number format for the field labels.  This must be a valid SQL format string.


Number Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

*/The following procedure
**determines if the labels' number
**format is '9,9,9,9'.  If
**not, it changes the format
**to '9,9,9,9'.
*/

PROCEDURE fieldNumFmt IS
  ftemp og_ftemp;
  numfmt varchar2(20);
BEGIN
  ftemp := og_get_ftemp(og_get_template(og_get_object('chart')),0);
  numfmt := og_get_numfmt(ftemp);
  if numfmt != '9,9,9,9' then
    og_set_numfmt(ftemp, '9,9,9,9');
  end if;
END;


Root Property

  Examples	  Related Topics

Description  Is a handle to the chart template to which the field template belongs.

Syntax

FUNCTION OG_Get_Root
  (ftemp  OG_Ftemp)
RETURN OG_Object;

Parameters

ftemp	Is the field template being described.


Root Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure gets
**a chart’s field template handles.
*/

PROCEDURE fieldname IS
  ftemp og_ftemp;
  root og_object;
BEGIN
  ftemp := og_get_ftemp(og_get_template(og_get_object('chart')),0);
  root := og_get_root(ftemp);
END;


Field Template (Axis Chart) Properties

Axis Property

Curve Fit Property

Label Rotation Property

Line Style Property

Overlap Property

Plot Position Property

Plot Type Property


Axis Property

  Examples	  Related Topics

Description  Specifies the axis to which data values are compared to determine how the field is plotted.  The value of this property may be one of the following built-in constants:

OG_Y1_Axis

OG_Y2_Axis

Syntax

PROCEDURE OG_Set_Axis
  (ftemp  OG_Ftemp,
   axis   NUMBER);

FUNCTION OG_Get_Axis
  (ftemp  OG_Ftemp)
RETURN NUMBER;

Parameters

ftemp	Is the field template being described.
axis	Specifies the axis to which data values are compared to determine how the field is plotted.


Axis Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure
**rotates the main Y axis the
**chart currently refers to
**(if there is more than one
**Y axis)and switches the main
**Y axis to a different Y axis.
*/

PROCEDURE axis IS
  axis number;
  ftemp og_ftemp;
  chart og_object;
BEGIN
  chart := og_get_object('chart');
  ftemp := og_get_ftemp(og_get_template(chart),0);
  axis := og_get_axis(ftemp);
  if axis = og_y1_axis then
     og_set_axis(ftemp, og_y2_axis);
  elsif axis = og_y2_axis then
     og_set_axis(ftemp, og_y1_axis);
  end if;
  og_update_chart(chart);
END;


Curve Fit Property

  Examples	  Related Topics

Description  Specifies whether a curve fit is applied to the chart and, if so, which algorithm is used.  The value of this property may be one of the following built-in constants:

OG_No_Curvefit

OG_Linear_Curvefit

OG_LOG_Curvefit

OG_Exp_Curvefit

OG_Power_Curvefit

Syntax

PROCEDURE OG_Set_Curvefit
  (ftemp     OG_Ftemp,
   curvefit  NUMBER);

FUNCTION OG_Get_Curvefit
  (ftemp  OG_Ftemp)
RETURN NUMBER;

Parameters

ftemp	Is the field template being described.
curvefit	Specifies whether a curve fit is applied to the chart and, if so, which algorithm is used.


Curve Fit Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines
**if a curve fit is applied to the chart.
**If not, it applies a Linear CurveFit
**to the chart.  If a curve fit is currently
**applied to the chart, it removes it.
*/

PROCEDURE CurveFit IS
  curve number;
  ftemp og_ftemp;
  chart og_object;
BEGIN
  chart := og_get_object('chart');
  ftemp := og_get_ftemp(og_get_template(chart),0);
  curve := og_get_curvefit(ftemp);
  if curve = og_no_curvefit then
    og_set_curvefit(ftemp,og_linear_curvefit);
  else
    og_set_curvefit(ftemp,og_no_curvefit);
  end if;
  og_update_chart(chart);
END;


Label Rotation Property

  Examples	  Related Topics

Description  Specifies the rotation angle of the labels for a field with a label plot type.  The value of this property may be one of the following built-in constants:

OG_Ccw_Rotation   Means counter-clockwise rotation.

OG_Cw_Rotation   Means clockwise rotation.

OG_No_Rotation

Syntax

PROCEDURE OG_Set_Labelrot
  (ftemp    OG_Ftemp,
   linesty  NUMBER);

FUNCTION OG_Get_Labelrot
  (ftemp  OG_Ftemp)
RETURN NUMBER;

Parameters

ftemp	Is the field template being described.
linesty	Specifies the rotation angle of the labels for a field with a label plot type.


Label Rotation Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure rotates a
**chart's rotation labels.
*/

PROCEDURE lblrot IS
  rot number;
  ftemp og_ftemp;
  chart og_object;
BEGIN
  chart := og_get_object('chart');
  ftemp := og_get_ftemp(og_get_template(chart),0);
  rot := og_get_labelrot(ftemp);
  if rot = og_no_rotation then
    og_set_labelrot(ftemp,og_cw_rotation);
  elsif rot = og_cw_rotation then
    og_set_labelrot(ftemp, og_ccw_rotation);
  elsif rot = og_ccw_rotation then
    og_set_labelrot(ftemp, og_no_rotation);
  end if;
  og_update_chart(chart);
END;


Line Style Property

  Examples	  Related Topics

Description  Specifies the line style used to connect the data points of a field with a line plot type.  The value of this property may be one of the following built-in constants:

OG_Spline_Linestyle

OG_Step_Linestyle

OG_Straight_Linestyle

Syntax

PROCEDURE OG_Set_Linesty
  (ftemp    OG_Ftemp,
   linesty  NUMBER);

FUNCTION OG_Get_Linesty
  (ftemp  OG_Ftemp)
RETURN NUMBER;

Parameters

ftemp	Is the field template being described.
linesty	Specifies the line style used to connect the data points of a field with a line plot type.


Line Style Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure rotates
**the line style of a chart.
*/

PROCEDURE linesty IS
  style number;
  ftemp og_ftemp;
  chart og_object;
BEGIN
  chart := og_get_object('chart');
  ftemp := og_get_ftemp(og_get_template(chart),0);
  style := og_get_linesty(ftemp);
  if style = og_spline_linestyle then
     og_set_linesty(ftemp, og_step_linestyle);
  elsif style = og_step_linestyle then
     og_set_linesty(ftemp, og_straight_linestyle);
  elsif style = og_straight_linestyle then
     og_set_linesty(ftemp, og_spline_linestyle);
  end if;
  og_update_chart(chart);
END;


Overlap Property

  Examples	  Related Topics

Description  Specifies the percentage by which bars representing data values from multiple fields in a bar or column chart overlap each other.

Syntax

PROCEDURE OG_Set_Overlap
  (ftemp    OG_Ftemp,
   overlap  NUMBER);

FUNCTION OG_Get_Overlap
  (ftemp  OG_Ftemp)
RETURN NUMBER;

Parameters

ftemp	Is the field template being described.
overlap	Specifies the percentage by which bars representing data values from multiple fields in a bar or column chart overlap each other.


Overlap Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
**the overlap percentage that has
**been specified. If the specified
**percentage is between 0 to 50,
**it redraws the column using
**90% overlap, if the percentage is
**over 90%,it redraws the columns
**with 0% overlap.
*/

PROCEDURE overlap IS
  percent number;
  ftemp og_ftemp;
  chart og_object;
BEGIN
  chart := og_get_object('chart');
  ftemp := og_get_ftemp(og_get_template(chart),0);
  percent := og_get_overlap(ftemp);
  if percent between 0 and 50 then
     og_set_overlap(ftemp, 90);
  else
     og_set_overlap(ftemp, 0);
  end if;
END;


Plot Position Property

  Examples	  Related Topics

Description  Specifies for each category the relationship between the data values of two or more fields.  The value of this property may be one of the following built-in constants:

OG_Normal_Plotpos

OG_Fromprev_Plotpos

OG_Stacked_Plotpos

Syntax

PROCEDURE OG_Set_Plotpos
  (ftemp    OG_Ftemp,
   plotpos  NUMBER);

FUNCTION OG_Get_Plotpos
  (ftemp  OG_Ftemp)
RETURN NUMBER;

Parameters

ftemp	Is the field template being described.
plotpos	Specifies for each category the relationship between the data values of two or more fields.


Plot Position Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure rotates
**the plot position of columns in a chart.
*/

PROCEDURE plotpos IS
  pos number;
  ftemp og_ftemp;
  chart og_object;
BEGIN
  chart := og_get_object('chart');
  ftemp := og_get_ftemp(og_get_template(chart),0);
  pos := og_get_plotpos(ftemp);
   if pos = og_normal_plotpos then
     og_set_plotpos(ftemp,og_fromprev_plotpos);
   elsif pos = og_fromprev_plotpos then
     og_set_plotpos(ftemp, og_stacked_plotpos);
   elsif pos = og_stacked_plotpos then
     og_set_plotpos(ftemp, og_normal_plotpos);
   end if;
  og_update_chart(chart);
END;


Plot Type Property

  Examples	  Related Topics

Description  Specifies the elements used to plot this field on the chart.  The value of this property may be one of the following built-in constants:

OG_None_Plottype

OG_Bar_Plottype

OG_Line_Plottype

OG_Symbol_Plottype

OG_Fill_Plottype

OG_Spike_Plottype

OG_Label_Plottype

Syntax

PROCEDURE OG_Set_Plottype
  (ftemp     OG_Ftemp,
   plottype  NUMBER);

FUNCTION OG_Get_Plottype
  (ftemp  OG_Ftemp)
RETURN NUMBER;

Parameters

ftemp	Is the field template being described.
plottype	Specifies the elements used to plot this field on the chart.


Plot Type Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*On a mouse click, the following
**procedure rotates the plot type
**of a chart.
*/

PROCEDURE Plottype (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
chart og_object;
template og_template;
ftemp og_ftemp;
num number;
BEGIN
chart := og_get_object('chart');
template := og_get_template(chart);
ftemp := og_get_ftemp(template, 0);
num := og_get_plottype(ftemp);
if num = og_none_plottype then
   og_set_plottype(ftemp, og_bar_plottype);
elsif num = og_bar_plottype then
   og_set_plottype(ftemp, og_line_plottype);
elsif num = og_line_plottype then
   og_set_plottype(ftemp, og_symbol_plottype);
elsif num = og_symbol_plottype then
   og_set_plottype(ftemp, og_fill_plottype);
elsif num = og_fill_plottype then
   og_set_plottype(ftemp, og_spike_plottype);
elsif num = og_spike_plottype then
   og_set_plottype(ftemp, og_label_plottype);
elsif num = og_label_plottype then
   og_set_plottype(ftemp, og_none_plottype);
end if;
og_update_chart(chart);
END;


Generic Properties

Button Procedure Property

Column Property

Events Property

Execute Query Property

Format Trigger Property

Hide Object Property

Inner Bounding Box Property

Name Property

Object Type Property

Outer Bounding Box Property

Parent Property

Set Parameter Property


Button Procedure Property

  Examples	  Related Topics

Description  Is the handle to the button procedure to be associated with this object.  Note that the Events property must also be set properly in order to ensure that this procedure receives the desired mouse events.

Syntax

PROCEDURE OG_Set_Button
  (object          OG_Object,
   buttonproc      OG_Buttonproc,
   damage          BOOLEAN        :=  TRUE,
   update_bbox     BOOLEAN        :=  TRUE);

FUNCTION OG_Get_Button
  (object  OG_Object)
RETURN OG_Buttonproc;

Parameters

object	Is the object being described.
buttonproc	Is the handle to the button procedure to be associated with this object.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Button Procedure Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the button
**procedure from a rectangle object, and adds
**the same procedure to a circle object.
*/

PROCEDURE transfer (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  rect og_object;
  circle og_object;
  proc og_buttonproc;
BEGIN
  rect := og_get_object('rect');
  circle := og_get_object('circle');
  proc := og_get_button(rect);
  og_set_button(circle, proc);
END;


Column Property

  Examples	  Related Topics

Description  Is the column value to which the parameter is set when the object is selected.  This property applies only to chart elements.

Syntax

PROCEDURE OG_Set_Keycol
  (object  OG_Object,
   keycol  VARCHAR2);

FUNCTION OG_Get_Keycol
  (object  OG_Object)
RETURN VARCHAR2;

Parameters

object	Is the object being described.
keycol	Is the column value to which the parameter is set when the object is selected.


Column Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
**the column value of a parameter
**and assigns a different value to it
*/

PROCEDURE GenColumn IS
  rect og_object;
  param varchar2(20);
BEGIN
  rect := og_get_object('rect');
  param := og_get_keycol(rect);
  og_set_keycol(rect, 'init');
END;


Events Property

  Examples	  Related Topics

Description  Is the type of mouse events that the procedure specified by the button property should receive.  The value of this property may be one of the built-in constants listed below.  To enable the procedure to receive multiple event types, set this property to be the sum of the constants for the desired events.  Note that OG_Mouse_Move_Up and OG_Mouse_Move_Down are only used for traversing display layers.

OG_No_Events

OG_Mouse_Down

OG_Mouse_Up

OG_Mouse_Move_Down

Syntax

PROCEDURE OG_Set_Events
  (object       OG_Object,
   events       NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Events
  (object  OG_Object)
RETURN NUMBER;

Parameters

object	Is the object being described.
events	Is the type of mouse events that the procedure specified by the button property should receive.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Events Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
**the current mouse event in an object,
**and assigns a different event to it.
*/

PROCEDURE Events IS
  rect og_object;
  events number;
BEGIN
  rect := og_get_object('rect');
  events := og_get_events(rect);
  if events = og_no_events then
     og_set_events(rect, og_mouse_down);
  elsif events = og_mouse_down then
     og_set_events(rect, og_mouse_up);
  elsif events = og_mouse_up then
     og_set_events(rect, og_mouse_move_down);
  elsif events = og_mouse_move_down then
     og_set_events(rect, og_no_events);
  end if;
END;


Execute Query Property

  Examples	  Related Topics

Description  Specifies the query to execute when the object is selected.

Syntax

PROCEDURE OG_Set_Execquery
  (object     OG_Object,
   execquery  OG_Query);

FUNCTION OG_Get_Execquery
  (object  OG_Object)
RETURN OG_Query;

Parameters

object	Is the object being described.
execquery	Specifies the query to execute when the object is selected.


Execute Query Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the specified
**query of the object, and assigns a different
**query to it.
*/

PROCEDURE GenQuery IS
  rect og_object;
  query og_query;
  query1 og_query;
BEGIN
  rect := og_get_object('rect');
  query := og_get_execquery(rect);
  query1 := og_get_query('query1');
  og_set_execquery(rect, query1);
END;


Format Trigger Property

  Examples	  Related Topics

Description  Is the object's format trigger.  This property applies only to chart elements.

Syntax

PROCEDURE OG_Set_Fmttrig
  (object   OG_Object,
   fmttrig  VARCHAR2);

FUNCTION OG_Get_Fmttrig
  (object  OG_Object)
RETURN VARCHAR2;

Parameters

object	Is the object being described.
fmttrig	Is the object's format trigger.  This property applies only to chart elements.


Format Trigger Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the specified
**format trigger from an object, and assigns a
**different format trigger to it.
*/

*/PROCEDURE GenFmtTrigger IS
  rect og_object;
  fmttrig varchar2(20);
BEGIN
  rect := og_get_object('rect');
  fmttrig := og_get_fmttrig(rect);
  og_set_fmttrig(rect, 'fmttrig1');
END;


Hide Object Property

  Examples	  Related Topics

Description  Hides the object.

Syntax

PROCEDURE OG_Set_Hide
  (object  OG_Object)
   hide BOOLEAN);

FUNCTION OG_Get_Hide
  (object  OG_Object)
RETURN BOOLEAN;

Parameters

object	Is the object being described.
hide	Hides the object.


Hide Object Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button
**procedure hides or
**shows an object as it
**is selected.
*/

PROCEDURE OGBUTTONPROC0 (buttonobj IN og_object,

                         hitobj IN og_object,

                         win IN og_window,

                         eventinfo IN og_event) IS

val boolean;

BEGIN

val := og_get_hide(hitobj);

if val then

   og_set_hide(hitobj, false);

 og_set_bfcolor(hitobj, 'red');

else

   og_set_hide(hitobj, true);

 og_set_bfcolor(hitobj, 'red');

end if;

END;


Inner Bounding Box Property

  Examples	  Related Topics

Description  Is the object's inner bounding box.  This is the rectangle that constitutes the object's ideal shape (i.e., connects the object's four control points), regardless of edge thickness or other property settings.

Syntax

FUNCTION OG_Get_Ibbox
  (object  OG_Object)
RETURN OG_Rectangle;

Parameters

object	Is the object being described.


Inner Bounding Box Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following reads the dimensions
**of the inner bounding and outer
**bounding boxes and calculates
**the size of the actual bounding box.
*/

PROCEDURE GenIOBox IS
  obj og_object;
  ibox og_rectangle;
  obox og_rectangle;
  num number;
BEGIN
  obj := og_get_object('rect');
  ibox := og_get_ibbox(obj);
  obox := og_get_obbox(obj);
  num := (obox.height * obox.width)-(ibox.height*ibox.width);
END;


Name Property

  Examples	  Related Topics

Description  Is the object's name.

Syntax

PROCEDURE OG_Set_Name
  (object       OG_Object,
   name         VARCHAR2
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Name
  (object  OG_Object)
RETURN VARCHAR2;

Parameters

object	Is the object being described.
name	Is the object's name.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Name Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
**the name of the object and assigns
**another name to it.
*/

PROCEDURE GenName IS
  obj og_object;
  name varchar2(20);
BEGIN
  obj := og_get_object('circle');
  name := og_get_name(obj);
  og_set_name(obj, 'teresa');
END;


Object Type Property

  Examples	  Related Topics

Description  Is the object's type.  The value of this property may be one of the following built-in constants:

OG_Arc_Objtype

OG_Chart_Objtype

OG_Group_Objtype

OG_Image_Objtype

OG_Line_Objtype

OG_Poly_Objtype

OG_Rect_Objtype

OG_Rrect_Objtype

OG_Symbol_Objtype

OG_Text_Objtype

Syntax

FUNCTION OG_Get_Objtype
  (object  OG_Object)
RETURN NUMBER;

Parameters

object	Is the object being described.


Object Type Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure checks
**the type of object being selected by
**the mouse, and prints the type name to
**a text object.
*/

PROCEDURE GenObjType2 (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  text og_object;
  objtype number;

BEGIN
  text := og_get_object('text object');
  objtype := og_get_objtype(hitobj);
  if objtype = og_arc_objtype then
     og_set_str(text, 'arc');
  elsif objtype = og_chart_objtype then
     og_set_str(text, 'chart');
  elsif objtype = og_group_objtype then
     og_set_str(text, 'group');
  elsif objtype = og_image_objtype then
     og_set_str(text, 'image');
  elsif objtype = og_line_objtype then
     og_set_str(text, 'line');
  elsif objtype = og_poly_objtype then
     og_set_str(text, 'poly');
  elsif objtype = og_rect_objtype then
     og_set_str(text, 'rect');
  elsif objtype = og_rrect_objtype then
     og_set_str(text, 'rrect');
  elsif objtype = og_symbol_objtype then
     og_set_str(text, 'symbol');
  elsif objtype = og_text_objtype then
     og_set_str(text, 'text');
  end if;

END;


Outer Bounding Box Property

  Examples	  Related Topics

Description  Is the object's outer bounding box.  This is the smallest rectangle that completely surrounds the object.  This may differ from the inner bounding box if the object has a thick edge.  While the inner bounding box traces only the ideal shape of the object, the outer bounding box surrounds the entire object.

Syntax

FUNCTION OG_Get_Obbox
  (object  OG_Object)
RETURN OG_Rectangle;

Parameters

object	Is the object being described.


Outer Bounding Box Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following reads the dimensions of the
**inner bounding and outer bounding boxes and
**calculates the size of the actual bounding box.
*/

PROCEDURE GenIOBox IS
  obj og_object;
  ibox og_rectangle;
  obox og_rectangle;
  num number;
BEGIN
  obj := og_get_object('rect');
  ibox := og_get_ibbox(obj);
  obox := og_get_obbox(obj);
  num := (obox.height * obox.width)-(ibox.height*ibox.width);
END;


Parent Property

  Examples	  Related Topics

Description  Is the handle to the object's parent object.

Syntax

FUNCTION OG_Get_Parent
  (object  OG_Object)
RETURN OG_Object;

Parameters

object	Is the object being described.


Parent Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure gets the
**parent of the current object, and
**prints the name of the parent object
**to a text object.
*/

PROCEDURE GenParent IS
  text og_object;
  obj og_object;
  parent og_object;
  name varchar2(20);
BEGIN
text := og_get_object('text object');
  obj := og_get_object('circle');
  parent := og_get_parent(obj);
  name := og_get_name(parent);
  og_set_str(text, name);
END;


Set Parameter Property

  Examples	  Related Topics

Description  Is the parameter whose value is set when the object is selected.

Syntax

PROCEDURE OG_Set_Setparam
  (object   OG_Object,
  setparam  VARCHAR2);

FUNCTION OG_Get_Setparam
  (object  OG_Object)
RETURN VARCHAR2;

Parameters

object	Is the object being described.
setparam	Is the parameter whose value is set when the object is selected.


Set Parameter Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**parameter of a rectangle object, and
**assigns a new parameter to it.
*/

PROCEDURE SetParam IS
  rect og_object;
  param varchar2(20);
BEGIN
  rect := og_get_object('rect');
  param := og_get_setparam(rect);
  og_set_setparam(rect, 'PARAM1');
END;


Graphic Properties

Background Edge Color Property

Background Fill Color Property

Bevel Style Property

Cap Style Property

Dash Style Property

Edge Pattern Property

Edge Width Property

Fill Pattern Property

Foreground Edge Color Property

Foreground Fill Color Property

Join Style Property

Rotation Angle Property

Transfer Mode Property


Background Edge Color Property

  Examples	  Related Topics

Description  Is the object's background edge color.

Syntax

PROCEDURE OG_Set_Becolor
  (object       OG_Object,
   becolor      VARCHAR2,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Becolor
  (object  OG_Object)
RETURN VARCHAR2;

Parameters

object	Is the object being described.
becolor	Is the object's background edge color.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Background Edge Color Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* /*The following procedure swaps the foreground
**and background edge colors.
*/

PROCEDURE FBEdgeColor IS
  obj og_object;
  fcolor varchar2(20);
  bcolor varchar2(20);
BEGIN
  obj := og_get_object('rect');
  fcolor := og_get_fecolor(obj);
  bcolor := og_get_becolor(obj);
  og_set_fecolor(obj, bcolor);
  og_set_becolor(obj, fcolor);
END;


Background Fill Color Property

  Examples	  Related Topics

Description  Is the object's background fill color.

Syntax

PROCEDURE OG_Set_Bfcolor
  (object       OG_Object,
   bfcolor      VARCHAR2,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Bfcolor
  (object  OG_Object)
RETURN VARCHAR2;

Parameters

object	Is the object being described.
bfcolor	Is the object's background fill color.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Background Fill Color Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

/*The following procedure swaps the foreground
**and background fill colors.
*/

PROCEDURE FBFillColor IS
  obj og_object;
  fcolor varchar2(20);
  bcolor varchar2(20);
BEGIN
  obj := og_get_object('rect');
  fcolor := og_get_ffcolor(obj);
  bcolor := og_get_bfcolor(obj);
  og_set_ffcolor(obj, bcolor);
  og_set_bfcolor(obj, fcolor);
END;


Bevel Style Property

  Examples	  Related Topics

Description  Is the object's bevel style.  The value of this property may be one of the following built-in constants:

OG_Inset_Bstyle

OG_Lowered_Bstyle

OG_Outset_Bstyle

OG_Plain_Bstyle

OG_Raised_Bstyle

Syntax

PROCEDURE OG_Set_Bevelstyle
  (object       OG_Object,
   bevelstyle   NUMBER,
   damage       BOOLEAN    := TRUE,
   update_bbox  BOOLEAN    := TRUE);

FUNCTION OG_Get_Bevelstyle
  (object  OG_Object)
RETURN NUMBER;

Parameters

object	Is the object being described.
bevelstyle	Is the object's bevel style.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Bevel Style Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure rotates
**the bevel style of a selected object.
*/

PROCEDURE bevel (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  obj og_object;
  num number;
BEGIN
  obj := og_get_object('rect');
  num := og_get_bevelstyle(obj);
  if num = og_inset_bstyle then
     og_set_bevelstyle(obj, og_lowered_bstyle);
  elsif num = og_lowered_bstyle then
     og_set_bevelstyle(obj, og_outset_bstyle);
  elsif num = og_outset_bstyle then
     og_set_bevelstyle(obj, og_plain_bstyle);
  elsif num = og_plain_bstyle then
     og_set_bevelstyle(obj, og_raised_bstyle);
  elsif num = og_raised_bstyle then
     og_set_bevelstyle(obj, og_inset_bstyle);
  end if;
END;


Cap Style Property

  Examples	  Related Topics

Description  Is the cap style of the object's edge.  The value of this property may be one of the following built-in constants:

OG_Butt_Cstyle

OG_Projecting_Cstyle

OG_Round_Cstyle

Syntax

PROCEDURE OG_Set_Capstyle
  (object        OG_Object,
   capstyle      NUMBER,
   damage        BOOLEAN    :=  TRUE,
   update_bbox   BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Capstyle
  (object  OG_Object)
RETURN NUMBER;

Parameters

object	Is the object being described.
capstyle	Is the cap style of the object's edge.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Cap Style Property Examples

  Alphabetic List         [image]  All Examples     [image]  Related Topics

 /*The following button procedure rotates
**the cap style of an object's edge.
*/

PROCEDURE CapStyle (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  num number;
BEGIN
  num := og_get_capstyle(hitobj);
  if num = og_butt_cstyle then
     og_set_capstyle(hitobj, og_projecting_cstyle);
  elsif num = og_projecting_cstyle then
     og_set_capstyle(hitobj,og_round_cstyle);
  elsif num = og_round_cstyle then
     og_set_capstyle(hitobj,og_butt_cstyle);
  end if;
END;


Dash Style Property

  Examples	  Related Topics

Description  Is the dash style of the object's edge.  The value of this property may be one of the following built-in constants:

OG_Solid_Dstyle

OG_Dot_Dstyle

OG_Long_Dstyle

OG_Dashdot_Dstyle

OG_Dotdot_Dstyle

OG_Short_Dstyle

OG_Dashdotdot_Dstyle

Syntax

PROCEDURE OG_Set_Dashstyle
  (object         OG_Object,
   dashstyle      NUMBER,
   damage         BOOLEAN    :=  TRUE,
   update_bbox    BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Dashstyle
  (object  OG_Object)
RETURN NUMBER;

Parameters

object	Is the object being described.
dashstyle	Is the dash style of the object's edge.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Dash Style Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

*/The following button procedure rotates
**the dash style on hit object.
*/

PROCEDURE DashStyle (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
    num number;
BEGIN
  num := og_get_dashstyle(hitobj);
  if num = og_solid_dstyle then
     og_set_dashstyle(hitobj, og_dot_dstyle);
  elsif num = og_dot_dstyle then
     og_set_dashstyle(hitobj,og_long_dstyle);
  elsif num = og_long_dstyle then
     og_set_dashstyle(hitobj,og_dashdot_dstyle);
  elsif num = og_dashdot_dstyle then
     og_set_dashstyle(hitobj,og_dotdot_dstyle);
  elsif num = og_dotdot_dstyle then
     og_set_dashstyle(hitobj,og_short_dstyle);
  elsif num = og_short_dstyle then
     og_set_dashstyle(hitobj,og_dashdotdot_dstyle);
  elsif num = og_dashdotdot_dstyle then
     og_set_dashstyle(hitobj,og_solid_dstyle);
  end if;
END;


Edge Pattern Property

  Examples	  Related Topics

Description  Is the object's edge pattern.

Syntax

PROCEDURE OG_Set_Edgepatt
  (object        OG_Object,
   edgepatt      VARCHAR2,
   damage        BOOLEAN    :=  TRUE,
   update_bbox   BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Edgepatt
  (object  OG_Object)
RETURN VARCHAR2;

Parameters

object	Is the object being described.
edgepatt	Is the object's edge pattern.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Edge Pattern Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure swaps the edge
**and fill patterns of an object.
*/

PROCEDURE EdgePattern IS
  obj og_object;
  edgepatt varchar2(20);
  fillpatt varchar2(20);
BEGIN
  obj := og_get_object('rect');
  edgepatt := og_get_edgepatt(obj);
  fillpatt := og_get_fillpatt(obj);
  og_set_edgepatt(obj, fillpatt);
  og_set_fillpatt(obj, edgepatt);
END;


Edge Width Property

  Examples	  Related Topics

Description  Is the width of the object's edge (in layout units).

Syntax

PROCEDURE OG_Set_Ewidth
  (object       OG_Object,
   ewidth       NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Ewidth
  (object  OG_Object)
RETURN NUMBER;

Parameters

object	Is the object being described.
ewidth	Is the width of the object's edge (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Edge Width Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the edge
**width of a selected object.  If the width
**is 0, it resets the width to value 800.
*/

PROCEDURE EdgeWidth IS
  obj og_object;
  width number;
BEGIN
  obj := og_get_object('rect');
  width := og_get_ewidth(obj);
  if width = 0 then
    og_set_ewidth(obj, 800);
  end if;
END;


Fill Pattern Property

  Examples	  Related Topics

Description  Is the object's fill pattern.

Syntax

PROCEDURE OG_Set_Fillpatt
  (object        OG_Object,
   fillpatt      VARCHAR2,
   damage        BOOLEAN    :=  TRUE,
   update_bbox   BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Fillpatt
  (object  OG_Object)
RETURN VARCHAR2;

Parameters

object	Is the object being described.
fillpatt	Is the object's fill pattern.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Fill Pattern Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* Examples

 /*The following procedure swaps the edge
**and fill patterns of an object.
*/

PROCEDURE EdgePattern IS
  obj og_object;
  edgepatt varchar2(20);
  fillpatt varchar2(20);
BEGIN
  obj := og_get_object('rect');
  edgepatt := og_get_edgepatt(obj);
  fillpatt := og_get_fillpatt(obj);
  og_set_edgepatt(obj, fillpatt);
  og_set_fillpatt(obj, edgepatt);
END;


Foreground Edge Color Property

  Examples	  Related Topics

Description  Is the object's foreground edge color.

Syntax

PROCEDURE OG_Set_Fecolor
  (object       OG_Object,
   fecolor      VARCHAR2,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Fecolor
  (object  OG_Object)
RETURN VARCHAR2;

Parameters

object	Is the object being described.
fecolor	Is the object's foreground edge color.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Foreground Edge Color Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure swaps the foreground
**and background edge colors.
*/

PROCEDURE FBEdgeColor IS
  obj og_object;
  fcolor varchar2(20);
  bcolor varchar2(20);
BEGIN
  obj := og_get_object('rect');
  fcolor := og_get_fecolor(obj);
  bcolor := og_get_becolor(obj);
  og_set_fecolor(obj, bcolor);
  og_set_becolor(obj, fcolor);
END;


Foreground Fill Color Property

  Examples	  Related Topics

Description  Is the object's foreground fill color.

Syntax

PROCEDURE OG_Set_Ffcolor
  (object       OG_Object,
   ffcolor      VARCHAR2,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Ffcolor
  (object  OG_Object)
RETURN VARCHAR2;

Parameters

object	Is the object being described.
ffcolor	Is the object's foreground fill color.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Foreground Fill Color Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure swaps the foreground
**and background fill colors.
*/

PROCEDURE FBFillColor IS
  obj og_object;
  fcolor varchar2(20);
  bcolor varchar2(20);
BEGIN
  obj := og_get_object('rect');
  fcolor := og_get_ffcolor(obj);
  bcolor := og_get_bfcolor(obj);
  og_set_ffcolor(obj, bcolor);
  og_set_bfcolor(obj, fcolor);
END;


Join Style Property

  Examples	  Related Topics

Description  Is the join style of the object's edge.  The value of this property may be one of the following built-in constants:

OG_Mitre_Jstyle

OG_Bevel_Jstyle

OG_Round_Jstyle

Syntax

PROCEDURE OG_Set_Joinstyle
  (object         OG_Object,
   joinstyle      NUMBER,
   damage         BOOLEAN    :=  TRUE,
   update_bbox    BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Joinstyle
  (object  OG_Object)
RETURN NUMBER;

Parameters

object	Is the object being described.
joinstyle	Is the join style of the object's edge.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Join Style Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure rotates
**the join style of an object's edge.
*/

PROCEDURE JoinStyle (mitreonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  num number;
BEGIN
  num := og_get_joinstyle(hitobj);
  if num = og_mitre_jstyle then
     og_set_joinstyle(hitobj, og_bevel_jstyle);
  elsif num = og_bevel_jstyle then
     og_set_joinstyle(hitobj,og_round_jstyle);
  elsif num = og_round_jstyle then
     og_set_joinstyle(hitobj,og_mitre_jstyle);
  end if;
END;


Rotation Angle Property

  Examples	  Related Topics

Description  Is the object's rotation angle.  The angle at which the object is initially created is considered to be 0, and this property is the number of degrees clockwise the object currently differs from that initial angle.  You can rotate an object to an absolute angle by setting this property, or use the OG_Rotate procedure to rotate an object by a relative amount.  (Note that when you use OG_Rotate to rotate an object, the Rotation Angle property will automatically be updated to reflect the new absolute angle.)

Syntax

PROCEDURE OG_Set_Rotang
  (object       OG_Object,
   rotang       NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Rotang
  (object  OG_Object)
RETURN NUMBER;

Parameters

object	Is the object being described.
rotang	Is the object's rotation angle.  The angle at which the object is initially created is considered to be 0, and this property is the number of degrees clockwise the object currently differs from that initial angle.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Rotation Angle Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the rotation
**angle from a selected object, and rotates
**the object another 45 degrees to the right.
*/

PROCEDURE RotAngle IS
  obj og_object;
  rotang number;
BEGIN
  obj := og_get_object('rect');
  rotang := og_get_rotang(obj);
  og_set_rotang(obj, rotang+45);
END;


Transfer Mode Property

  Examples	  Related Topics

Description  Is the object's transfer mode.  The value of this property may be one of the following built-in constants:

OG_Copy_Transfer

OG_Revcopy_Transfer

OG_Or_Transfer

OG_Revor_Transfer

OG_Clear_Transfer

OG_Revclear_Transfer

OG_Invert_Transfer

OG_Backinvert_Transfer

Syntax

PROCEDURE OG_Set_Transfer
  (object        OG_Object,
   transfer      NUMBER,
   damage        BOOLEAN    := TRUE,
   update_bbox   BOOLEAN    := TRUE);

FUNCTION OG_Get_Transfer
  (object  OG_Object)
RETURN NUMBER;

Parameters

object	Is the object being described.
transfer	Is the object's transfer mode.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Transfer Mode Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure rotates the
**transfer mode of a selected object.
*/

PROCEDURE transher (copyonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  num number;
BEGIN
  num := og_get_transfer(hitobj);
  if num = og_copy_transfer then
     og_set_transfer(hitobj, og_revcopy_transfer);
  elsif num = og_revcopy_transfer then
     og_set_transfer(hitobj,og_or_transfer);
  elsif num = og_or_transfer then
     og_set_transfer(hitobj,og_revor_transfer);
  elsif num = og_revor_transfer then
     og_set_transfer(hitobj,og_clear_transfer);
  elsif num = og_clear_transfer then
     og_set_transfer(hitobj,og_revclear_transfer);
  elsif num = og_revclear_transfer then
     og_set_transfer(hitobj,og_invert_transfer);
  elsif num = og_invert_transfer then
     og_set_transfer(hitobj,og_backinvert_transfer);
  elsif num = og_backinvert_transfer then
     og_set_transfer(hitobj,og_copy_transfer);
  end if;
END;


Group Properties

Child Count Property

Clip Flag Property


Child Count Property

  Examples	  Related Topics

Description  Is the number of children that belong to the group object.  If another group object is a child of the group being checked, that object will be counted only as one object.

Syntax

FUNCTION OG_Get_Childcount
  (object  OG_Object)
RETURN NUMBER;

Parameters

object	Is the object being described.


Child Count Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure gets the number
**of children in a group object.
*/

PROCEDURE GrpChildCnt IS
  grp og_object;
  cnt number;
BEGIN
  grp := og_get_object('group');
  cnt := og_get_childcount(grp);
END;


Clip Flag Property

  Examples	  Related Topics

Description  Specifies whether the first object in the group is a rectangle object that should be used as a clipping rectangle.  If TRUE, the only members of the group that appear on the layout are those objects-or portions of those objects-that appear within the bounds of the clipping rectangle.  The rectangle object itself also appears.

Syntax

PROCEDURE OG_Set_Clipflag
  (object        OG_Object,
   clipflag      BOOLEAN,
   damage        BOOLEAN    :=  TRUE,
   update_bbox   BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Clipflag
  (object  OG_Object)
RETURN BOOLEAN;

Parameters

object	Is the object being described.
clipflag	Specifies whether the first object in the group is a rectangle object that should be used as a clipping rectangle.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Clip Flag Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if
**clipflag is true.  If not, it sets the
**flag to true.
*/

PROCEDURE GrpClipFlg IS
  grp og_object;
  flag boolean;
BEGIN
  grp := og_get_object('group');
  flag := og_get_clipflag(grp);
  if flag = false then
     og_set_clipflag(grp, true);
  end if;
END;


Image Properties

Clip Rectangle Property

Dither Property

Height Property

Position Property

Quality Property

Width Property


Clip Rectangle Property

  Examples	  Related Topics

Description  Is the x- and y-coordinates, height, and width of the image's clipping rectangle (in layout units).  Only the portion of the image that falls within this clipping rectangle will be displayed.  If this property is not specified, the clipping rectangle will equal the full dimensions of the image.

Syntax

PROCEDURE OG_Set_Cliprect
  (image         OG_Object,
   cliprect      OG_Rectangle,
   damage        BOOLEAN       :=  TRUE,
   update_bbox   BOOLEAN       :=  TRUE);

FUNCTION OG_Get_Cliprect
  (image  OG_Object)
RETURN OG_Rectangle;

Parameters

image	Is the image object being described.
cliprect	Is the x- and y-coordinates, height, and width of the image's clipping rectangle (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Clip Rectangle Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reduces the
**size of the clipping rectangle by half.
*/

PROCEDURE ClipRect IS
  image og_object;
  rect og_rectangle;
BEGIN
  image := og_get_object('image');
  rect := og_get_cliprect(image);
  rect.height := rect.height/2;
  rect.width := rect.width/2;
  og_set_cliprect(image, rect);
  og_set_clipflag(image, true);
END;


Dither Property

  Examples	  Related Topics

Description  Specifies whether Graphics Builder dithers the image when displaying it.  The value of this property may be one of the following:

Syntax

PROCEDURE OG_Set_Image_Dither
  (image   OG_Object,
   dither  BOOLEAN);

FUNCTION OG_Get_Image_Dither
  (image  OG_Object)
RETURN BOOLEAN;

Parameters

image	Is the image object being described.
dither	Specifies whether Graphics Builder dithers the image when displaying it.


Dither Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure
**dithers an image or removes
**dithering.
*/

PROCEDURE SetDither (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
val boolean;
image og_object;
BEGIN
  image := og_get_object('image');
  val := og_get_image_dither(image);
  if val then
    og_set_image_dither(og_get_object('image'), false);
  else
    og_set_image_dither(og_get_object('image'), true);
  end if;
END;


Height Property

  Examples	  Related Topics

Description  Is the image's height (in layout units).  If you set this property to some value other than the image's default height, the image will be scaled to fit within the new height.

Syntax

(See OG_Set_Image_Size, above.)

FUNCTION OG_Get_Image_Height
  (image  OG_Object)
RETURN NUMBER;

Parameters

image	Is the image object being described.


Height Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reduces
**an image's size by half.
*/

PROCEDURE SizeWidthHeight IS
  image og_object;
  height number;
  width number;
BEGIN
  image := og_get_object('image');
  width := og_get_image_width(image);
  height := og_get_image_height(image);
  og_set_image_size(image, width/2, height/2);
END;


Position Property

  Examples	  Related Topics

Description  Is the x- and y-coordinates of the image's upper-left corner (in layout units).

Syntax

PROCEDURE OG_Set_Upperleft
  (image          OG_Object,
   upperleft      OG_Point,
   damage         BOOLEAN    :=  TRUE,
   update_bbox    BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Upperleft
  (image  OG_Object)
RETURN OG_Point;

Parameters

image	Is the image object being described.
upperleft	Is the x- and y-coordinates of the image's upper-left corner (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Position Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**(x,y) coordinates of the image's
**upper-left corner.  If the coordinate
**is not (0,0), the procedure
**moves the image’s upper-left
**corner to the (0,0) coordinate.
*/

PROCEDURE Position IS
  image og_object;
  pos og_point;
BEGIN
  image := og_get_object('image');
  pos := og_get_upperleft(image);
  if pos.x != 0 and pos.y != 0 then
    pos.x := 0;
    pos.y := 0;
    og_set_upperleft(image, pos);
  end if;
END;


Quality Property

  Examples	  Related Topics

Description  Specifies with what  quality the image is drawn.  Higher quality images look better, but require more processing time to manipulate (e.g., draw, move, scale, etc.).  The value of this property may be one of the following built-in constants:

OG_High_Iquality

OG_Medium_Iquality

OG_Low_Iquality

Syntax

PROCEDURE OG_Set_Image_Quality
  (image    OG_Object,
   quality  NUMBER);

FUNCTION OG_Get_Image_Quality
  (image  OG_Object)
RETURN NUMBER;

Parameters

image	Is the image object being described.
quality	Specifies with what  quality the image is drawn.


Quality Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks image
**quality.  If the image is currently drawn
**with high quality, the procedure redraws
**it with low quality.
*/

PROCEDURE GetQuality (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  image og_object;
  qty number;
BEGIN
  image := og_get_object('image');
  qty := og_get_image_quality(image);
  if qty = og_high_iquality then
    og_set_image_quality(image, og_low_iquality);
  end if;
END;


Width Property

  Examples	  Related Topics

Description  Is the image's width (in layout units).  If you set this property to some value other than the image's default width, the image will be scaled to fit within the new width.

Syntax

PROCEDURE OG_Set_Image_Size
  (image        OG_Object,
   width        NUMBER,
   height       NUMBER,
   damage       BOOLEAN    := TRUE,
   update_bbox  BOOLEAN    :=   TRUE);

FUNCTION OG_Get_Image_Width
  (image  OG_Object)
RETURN NUMBER;

Parameters

image	Is the image object being described.
width	Is the image's width (in layout units).
height	Is the image’s height (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Width Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure reduces
**an image's size by half.
*/

PROCEDURE SizeWidthHeight IS
  image og_object;
  height number;
  width number;
BEGIN
  image := og_get_object('image');
  width := og_get_image_width(image);
  height := og_get_image_height(image);
  og_set_image_size(image, width/2, height/2);
END;


Line Properties

Arrow Style Property

End Point Property

Start Point Property


Arrow Style Property

  Examples	  Related Topics

Description  Is the line's arrow style.  The value of this property may be one of the following built-in constants:

OG_Noarrow_Astyle   Means the line has no arrow.

OG_Start_Astyle   Means the line has an arrow at its starting point.

OG_End_Astyle   Means the line has an arrow at its end point.

OG_Both_Astyle   Means the line has an arrow at both ends.

OG_Midtostart_Astyle   Means the line has an arrow at its middle, pointing toward its starting point.

OG_Midtoend_Astyle   Means the line has an arrow at its middle, pointing toward its end point.

Syntax

PROCEDURE OG_Set_Arrowstyle
  (line         OG_Object,
   arrowstyle   NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Arrowstyle
  (line  OG_Object)
RETURN NUMBER;

Parameters

line	Is the line object being described.
arrowstyle	Is the line's arrow style.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Arrow Style Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines a
*line’s current arrow style.  If the line
**does not include arrows, the procedure adds
**arrows to both ends of the line.  If the
**line does include arrows, the
**procedure removes them.
*/

PROCEDURE Arrow (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  arrow og_object;
  num number;
BEGIN
  arrow := og_get_object('arrow');
  num := og_get_arrowstyle(arrow);
  if num = og_noarrow_astyle then
    og_set_arrowstyle(arrow, og_both_astyle);
  else
    og_set_arrowstyle(arrow, og_noarrow_astyle);
  end if;
END;


End Point Property

  Examples	  Related Topics

Description  Is the x- and y-coordinates of the line's end point (in layout units).

Syntax

PROCEDURE OG_Set_Endpt
  (line         OG_Object,
   endpt        OG_Point,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Endpt
  (line  OG_Object)
RETURN OG_Point;

Parameters

line	Is the line object being described.
endpt	Is the x- and y-coordinates of the line's end point (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


End Point Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**coordinates of the line's ending point.
**If the line does not end at the upper-left
**corner of the display, the procedure resets
**the end point to (0,0).
*/

PROCEDURE OGBUTTONPROC0 (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  arrow og_object;
  pos og_point;
BEGIN
  arrow := og_get_object('a');
  pos := og_get_endpt(arrow);
  if pos.x != 0 and pos.y != 0 then
    pos.x := 0;
    pos.y := 0;
    og_set_endpt(arrow, pos);
  end if;
END;


Start Point Property

  Examples	  Related Topics

Description  Is the x- and y-coordinates of the line's starting point (in layout units).

Syntax

PROCEDURE OG_Set_Startpt
  (line         OG_Object,
   startpt      OG_Point,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Startpt(line OG_Object)
RETURN OG_Point;

Parameters

line	Is the line object being described.
startpt	Is the x- and y-coordinates of the line's starting point (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Start Point Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* /*The following procedure reads
**the coordinates of a line's
**starting point.  If the line does
**not start from the upper-left corner
**of the display, the procedure resets
**the start point to (0,0).
*/

PROCEDURE  StartPt (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  arrow og_object;
  pos og_point;
BEGIN
  arrow := og_get_object('a');
  pos := og_get_startpt(arrow);
  if pos.x != 0 and pos.y != 0 then
    pos.x := 0;
    pos.y := 0;
    og_set_startpt(arrow, pos);
  end if;
END;


Polygon Properties

Closure Property

Point Count Property


Closure Property

  Examples	  Related Topics

Description  Is the closure of the polygon.  The value of this property may be one of the following:

TRUE   Means the polygon is closed.

FALSE   Means the polygon is open.

Syntax

PROCEDURE OG_Set_Poly_Closed
  (poly         OG_Object,
   closed       BOOLEAN,
   damage       BOOLEAN    := TRUE,
   update_bbox  BOOLEAN    := TRUE);

FUNCTION OG_Get_Poly_Closed
  (poly  OG_Object)
RETURN BOOLEAN;

Parameters

poly	Is the polygon being described.
closed	Is the closure of the polygon.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Closure Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines
**whether a polygon is closed.
**If the polygon is open, the procedure
**closes it.
*/

PROCEDURE closure IS
  polygon og_object;
  val boolean;
BEGIN
  polygon := og_get_object('polygon');
  val := og_get_poly_closed(polygon);
  if val = false  then
     og_set_poly_closed(polygon, true);
  end if;
END;


Point Count Property

  Examples	  Related Topics

Description  Is the number of points that compose the polygon object.

Syntax

FUNCTION OG_Get_Pointct
  (poly  OG_Object)
RETURN NUMBER;

Parameters

poly	Is the polygon being described.


Point Count Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**number of points that compose the
**polygon object and prints the number
**to a text object.
*/

PROCEDURE PntCnt IS
  text og_object;
  polygon og_object;
  cnt number;
BEGIN
text := og_get_object('text object');
  polygon := og_get_object('polygon');
  cnt := og_get_pointct(polygon);
  og_set_str(text, cnt);
END;


Printer Properties Property

Copies Property

End Page Property

Landscape Property

Name Property

Page Size Property

Print File Property

Start Page Property


Copies Property

  Examples	  Related Topics

Description  Is the number of copies to print.

Syntax

PROCEDURE OG_Set_Copies
  (copies  NUMBER);

FUNCTION OG_Get_Copies
RETURN NUMBER;

Parameters

copies	Is the number of copies to print.


Copies Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
**the number of copies and adds two more
**copies to print.
*/

PROCEDURE PrinterCopies IS
  copies number;
BEGIN
  copies := og_get_copies;
  og_set_copies(copis+2);
END;


End Page Property

  Examples	  Related Topics

Description  Is the last page to print.

Syntax

PROCEDURE OG_Set_Endpage
  (endpage  NUMBER);

FUNCTION OG_Get_Endpage
RETURN NUMBER;

Parameters

endpage	Is the last page to print.


End Page Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**end page number and resets it to the
**original number plus two.
*/.

PROCEDURE PrinterEndPage IS
  ep number;
BEGIN
  ep := og_get_endpage;
  og_set_endpage(ep+2);
END;


Landscape Property

  Examples	  Related Topics

Description  Specifies whether the display is printed in landscape or portrait mode.

Syntax

PROCEDURE OG_Set_Landscape
  (landscape  BOOLEAN);

FUNCTION OG_Get_Landscape
RETURN BOOLEAN;

Parameters

landscape	Specifies whether the display is printed in landscape or portrait mode.


Landscape Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines
**if the display is printed in landscape
**or portrait mode, and prints the mode
**type to a text object.
*/

PROCEDURE PrinterLandscape IS

  landscape boolean;

BEGIN

  landscape := og_get_landscape;
  if landscape then
     og_set_str(og_get_object('text object'), 'landscape');
  else
     og_set_str(og_get_object('text object'), 'portrait');
  end if;
END;


Name Property

  Examples	  Related Topics

Description  Is the name of the current printer.

Syntax

PROCEDURE OG_Set_Printer_Name
  (name  VARCHAR2);

FUNCTION OG_Get_Printer_Name
RETURN VARCHAR2;

Parameters

name	Is the name of the current printer.


Name Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure sets the
**printer name and prints the name to
**a text object.
*/

PROCEDURE PrinterName IS
  name varchar2(30);
BEGIN
  name := og_get_printer_name;
  og_set_str(og_get_object('text object'), name);
END;


Page Size Property

  Examples	  Related Topics

Description  Is the page size (in inches).

Syntax

PROCEDURE OG_Set_Pagesize
  (width   NUMBER,
  (height  NUMBER);

Parameters

width	Is the width of the page (in inches).
height	Is the height of the page (in inches).


Page Size Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure sets the
**page size.
*/

PROCEDURE PrinterPageSize IS
  height number := 10*og_inch;
  width number := 10*og_inch;
  printfile varchar2(20);
BEGIN
  og_set_pagesize(height, width);
END;


Print File Property

  Examples	  Related Topics

Description  Is the name of the PostScript file to print to.  If this property is NULL, the output is sent to the printer.

Syntax

PROCEDURE OG_Set_Printfile
  (filename  VARCHAR2);

FUNCTION OG_Get_Printfile
RETURN VARCHAR2;

Parameters

filename	Is the name of the PostScript file to print to.  If this property is NULL, the output is sent to the printer.


Print File Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*.The following procedure sets the
**PostScript file name and prints it
**to a text object.
*/

PROCEDURE PrinterPrintFile IS
  printfile varchar2(20);
BEGIN
  og_set_printfile('myfile');
  printfile := og_get_printfile;
  og_set_str(og_get_object('text object'), printfile);
END;


Start Page Property

  Examples	  Related Topics

Description  Is the first page to print.

Syntax

PROCEDURE OG_Set_Startpage
  (startpage  NUMBER);

FUNCTION OG_Get_Startpage
RETURN NUMBER;

Parameters

startpage	Is the first page to print.


Start Page Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the start
**page number and resets the page number
**to the original number plus two.
*/

PROCEDURE PrinterStartPage IS
  sp number;
BEGIN
  sp := og_get_startpage;
  og_set_startpage(sp+2);
END;


Query Properties

Cache Type Property

Custom Query Procedure Property

Date Format Property

Execute On Open Property

Execute On Timer Property

Maximum Rows Property

Name Property

Post-Query Trigger Procedure Property

Query Source Property

Query Type Property


Cache Type Property

  Examples	  Related Topics

Description  Determines how the newly retrieved data from a query execution is treated.  The value of this property may be one of the following built-in constants:

OG_Append_Cachetype   Means all of the existing rows of data are retained, and the new rows of data are added to the bottom of the existing data set.

OG_Copy_Cachetype   Means all of the data from the previous execution is copied to a special buffer, and the newly retrieved data replaces it.

OG_None_Cachetype   Means all of the data from the previous execution is discarded, and the newly retrieved data replaces it.

Syntax

PROCEDURE OG_Set_Cachetype
  (query      OG_Query,
   cachetype  NUMBER);

FUNCTION OG_Get_Cachetype
  (query  OG_Query)
RETURN NUMBER;

Parameters

query	Is the query being described.
cachetype	Determines how the newly retrieved data from a query execution is treated.


Cache Type Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure rotates the query
**cache type of a query.
*/

PROCEDURE QryCacheType (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  qry og_query;
  num number;
BEGIN
  qry := og_get_query('query0');
  num := og_get_cachetype(qry);
  if num = og_append_cachetype then
     og_set_cachetype(qry, og_copy_cachetype);
  elsif num = og_copy_cachetype then
     og_set_cachetype(qry, og_none_cachetype);
  elsif num = og_none_cachetype then
     og_set_cachetype(qry, og_append_cachetype);
  end if;
END;


Custom Query Procedure Property

  Examples	  Related Topics

Description  Is the PL/SQL procedure that is invoked when a Custom query is executed.

Syntax

PROCEDURE OG_Set_Customproc
  (query       OG_Query,
   customproc  VARCHAR2);

FUNCTION OG_Get_Customproc
  (query  OG_Query)
RETURN VARCHAR2;

Parameters

query	Is the query being described.
customproc	Is the PL/SQL procedure that is invoked when a Custom query is executed.


Custom Query Procedure Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure swaps the two PL/SQL
**procedures which are invoked when a custom query is

**executed.
*/

PROCEDURE CustQry (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  proc varchar2(20);
  qry og_query;
BEGIN
  qry := og_get_query('query0');
  proc := og_get_customproc(qry);
  if proc = 'CUSTQRY1' then
    og_set_customproc(qry, 'CUSTQRY2');
  elsif proc = 'CUSTQRY2' then
     og_set_customproc(qry, 'CUSTQRY1');
  end if;
  og_execute_query(qry);
END;


Date Format Property

  Examples	  Related Topics

Description  Is the date format mask for the query.

Syntax

PROCEDURE OG_Set_Dateformat
  (query       OG_Query,
   dateformat  VARCHAR2);

FUNCTION OG_Get_Dateformat
  (query  OG_Query)
RETURN VARCHAR2;

Parameters

query	Is the query being described.
dateformat	Is the date format mask for the query.


Date Format Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads and sets
**the Date Format mask for the query.
*/

PROCEDURE QueryDateFmt IS
  qry og_query;
  DateFmt varchar2(20);
BEGIN
  qry := og_get_query('query0');
  DateFmt := og_get_dateformat(qry);
  og_set_dateformat(qry, 'DD-MM-YYYY');
  DateFmt := og_get_dateformat(qry);
END;


Execute on Open Property

  Examples	  Related Topics

Description  Specifies whether the query is automatically executed when the display is opened at runtime.

Syntax

PROCEDURE OG_Set_Execopen
  (query     OG_Query,
   execopen  BOOLEAN);

FUNCTION OG_Get_Execopen
  (query  OG_Query)
RETURN BOOLEAN;

Parameters

query	Is the query being described.
execopen	Specifies whether the query is automatically executed when the display is opened at runtime.


Execute on Open Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if the Execute
**on Open checkbox is checked.  If it is checked,
**it unchecks it, or vice versa.
*/

PROCEDURE ExecOpen IS
  execOpen boolean;
  qry og_query;
BEGIN
  qry := og_get_query('query0');
  execOpen := og_get_execopen(qry);
  if execOpen then
     og_set_execopen(qry, false);
  else
     og_set_execopen(qry, true);
  end if;
END;


Execute on Timer Property

  Examples	  Related Topics

Description  Is the name of the timer on which the query executes.  If NULL, the query is not executed on a timer.

Syntax

PROCEDURE OG_Set_Exectimer
  (query      OG_Query,
   exectimer  VARCHAR2);

FUNCTION OG_Get_Exectimer
  (query  OG_Query)
RETURN VARCHAR2;

Parameters

query	Is the query being described.
exectimer	Is the name of the timer on which the query executes.  If NULL, the query is not executed on a timer.


Execute on Timer Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the name of
**the timer on which the query executes and
**assigns a new timer to the query.
*/

PROCEDURE ExecTimer IS
  exectimer varchar2(20);
  qry og_query;
BEGIN
  qry := og_get_query('query0');
  exectimer := og_get_exectimer(qry);
  og_set_exectimer(qry, 'timer1');
END;


Maximum Rows Property

  Examples	  Related Topics

Description  Specifies the maximum number of rows of data that are retained in the query's data set.  If NULL, all rows are retained.

Syntax

PROCEDURE OG_Set_Maxrows
  (query    OG_Query,
   maxrows  NUMBER);

FUNCTION OG_Get_Maxrows
  (query  OG_Query)
RETURN NUMBER;

Parameters

query	Is the query being described.
maxrows	Specifies the maximum number of rows of data that are retained in the query's data set.  If NULL, all rows are retained.


Maximum Rows Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the maximum
**number of rows of data that are retained
**in the query's data set, and adds two rows to
**the original number.
*/

PROCEDURE QueryMaxRow IS
  qry og_query;
  num number;
BEGIN
  qry := og_get_query('query0');
  num := og_get_maxrows(qry);
  og_set_maxrows(qry, num+2);
END;


Maximum Rows Flag Property

  Examples	  Related Topics

Description  Specifies whether a limit is placed on the number of rows contained in the data set.  This is only used when the cachetype is of type OG_APPEND_CACHETYPE.

Syntax

PROCEDURE OG_Set_Maxflag
  (query    OG_Query,
   maxflag  BOOLEAN);

FUNCTION OG_Get_Maxflag
  (query  OG_Query)
RETURN BOOLEAN;

Parameters

query	Is the query being described.
maxflag	Specifies the maximum number of rows of data that can be contained in the query's data set.


Maximum Rows Flag Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the maximum
**number of rows of data that are retained
**in the query's data set, and adds two rows to
**the original number.  If the incremented number
**is greater than 1024, then it disables the
**maximum rows flag, thus allowing the query to get
**all the rows of data.
*/

PROCEDURE MaxFlagToggle IS
  qry og_query;
  num number;
BEGIN
  qry := og_get_query('query0');
  num := og_get_maxrows(qry);

  num := num+2;
  og_set_maxrows(qry, num);

  IF ((num > 1024) AND (og_get_maxflag(qry)=TRUE)) THEN

    og_set_maxflag(qry,FALSE);

  END IF;
END;


Name Property

  Examples	  Related Topics

Description  Is the name of the query.

Syntax

PROCEDURE OG_Set_Name
  (query  OG_Query,
   name   VARCHAR2);

FUNCTION OG_Get_Name
  (query  OG_Query)
RETURN VARCHAR2;

Parameters

query	Is the query being described.
name	Is the name of the query.


Name Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure swaps
** the name of two queries.
*/

PROCEDURE QueryName IS
  qry0 og_query;
  qry1 og_query;
  name0 varchar2(30);
  name1 varchar2(30);
BEGIN
  qry0 := og_get_query('query0');
  qry1 := og_get_query('query1');
  name0 := og_get_name(qry0);
  name1 := og_get_name(qry1);
  og_set_name(qry1, 'tmp');
  og_set_name(qry0, name1);
  og_set_name(qry1, name0);
END;


Post-Query Trigger Procedure Property

  Examples	  Related Topics

Description  Is the PL/SQL procedure that is invoked after the query is executed.

Syntax

PROCEDURE OG_Set_Postproc
  (query     OG_Query,
   postproc  VARCHAR2);

FUNCTION OG_Get_Postproc
  (query  OG_Query)
RETURN VARCHAR2;

Parameters

query	Is the query being described.
postproc	Is the PL/SQL procedure that is invoked after the query is executed.


Post-Query Trigger Procedure Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure swaps the two PL/SQL
**procedures which are invoked after the query is
**executed.
*/

PROCEDURE PostTrigger (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  proc varchar2(20);
  qry og_query;
BEGIN
  qry := og_get_query('query0');
  proc := og_get_postproc(qry);
  if  proc = 'POST1' then
      og_set_postproc(qry, 'POST2');
  elsif proc = 'POST2' then
      og_set_postproc(qry, 'POST1');
  end if;
  og_execute_query(qry);
END;


Query Source Property

  Examples	  Related Topics

Description  Is the source of the query's data.  If the data comes from a database, this property should contain the text of the query's SQL SELECT statement.  If the data is stored in the filesystem, this property should contain the path and name of the data file.

Syntax

PROCEDURE OG_Set_Querysource
  (query        OG_Query,
   querysource  VARCHAR2);

FUNCTION OG_Get_Querysource
  (query  OG_Query)
RETURN VARCHAR2;

Parameters

query	Is the query being described.
querysource	Is the source of the query's data.


Query Source Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure swaps the source
**of two queries.
*/

PROCEDURE QuerySource IS
  qry0 og_query;
  qry1 og_query;
  source0 varchar2(50);
  source1 varchar2(50);
BEGIN
  qry0 := og_get_query('query0');
  qry1 := og_get_query('query1');
  source0:= og_get_querysource(qry0);
  source1:= og_get_querysource(qry1);
  og_set_querysource(qry0, source1);
  og_set_querysource(qry1, source0);
END;


Query Type Property

  Examples	  Related Topics

Description  Is the type of query.  The value of this property may be one of the following built-in constants:

OG_Custom_Qtype   Means the query is a Custom query.

OG_Exsql_Qtype   Means  the query retrieves its data from a text file that contains a SQL SELECT statement.

OG_Prn_Qtype   Means the query is based on a PRN file.

OG_Sql_Qtype   Means the query is a SQL SE.LECT statement.

OG_Sylk_Qtype   Means the query is based on a SYLK file.

OG_Wks_Qtype   Means the query is based on a WKS file.

Syntax

PROCEDURE OG_Set_Querytype
  (query      OG_Query,
   querytype  NUMBER);

FUNCTION OG_Get_Querytype
  (query  OG_Query)
RETURN NUMBER;

Parameters

query	Is the query being described.
querytype	Is the type of query.


Query Type Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure rotates the
**query type of a query.
*/

PROCEDURE QryType (buttonobj IN og_object,

                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  qry og_query;
  num number;
BEGIN
  qry := og_get_query('query0');
  num := og_get_querytype(qry);

  if num = og_custom_qtype then
     og_set_querytype(qry, og_exsql_qtype);
  elsif num = og_exsql_qtype then
     og_set_querytype(qry, og_prn_qtype);
  elsif num = og_prn_qtype then
     og_set_querytype(qry, og_sql_qtype);
  elsif num = og_sql_qtype then
     og_set_querytype(qry, og_sylk_qtype);
   elsif num = og_sylk_qtype then
     og_set_querytype(qry, og_wks_qtype);
 elsif num = og_wks_qtype then
     og_set_querytype(qry, og_custom_qtype);
  end if;
END;


Rectangle Properties Property

Base Rectangle Property


Base Rectangle Property

  Examples	  Related Topics

Description  Is the x- and y-coordinates of the upper-left corner, and the height and width of the rectangle used as the basis for the rectangle object (in layout units).

Syntax

PROCEDURE OG_Set_Rect_Baserect
  (rect         OG_Object,
   baserect     OG_Rectangle,
   damage       BOOLEAN       :=  TRUE,
   update_bbox  BOOLEAN       :=  TRUE);

FUNCTION OG_Get_Rect_Baserect
  (rect  OG_Object)
RETURN OG_Rectangle;

Parameters

rect	Is the rectangle object being described.
baserect	Is the x- and y-coordinates of the upper-left corner, and the height and width of the rectangle used as the basis for the rectangle object (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Base Rectangle Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines the size
**of the rectangle base and doubles it.
*/

PROCEDURE baseRect IS
  rect og_rectangle;
  obj og_object;
BEGIN
  obj := og_get_object('rect');
  rect := og_get_rect_baserect(obj);
  rect.x := rect.x * 2;
  rect.y := rect.y * 2;
  rect.height := rect.height * 2;
  rect.width := rect.width * 2;
  og_set_rect_baserect(obj, rect);
END;);
  source0:= og_get_querysource(qry0);
  source1:= og_get_q?_


Reference Line Properties

Axis Property

Date Value Property

Label Property

Number Value Property


Axis Property

  Examples	  Related Topics

Description  Specifies which axis the reference value is compared to determine its position.  The value of this property may be one of the following built-in constants:

OG_X_Axis

OG_Y1_Axis

OG_Y2_Axis

Syntax

PROCEDURE OG_Set_Axis
  (refline  OG_Refline,
   axis     NUMBER);

FUNCTION OG_Get_Axis
  (refline  OG_Refline)
RETURN NUMBER;

Parameters

refline	Is the reference line being described.
axis	Specifies which axis the reference value is compared to determine its position.


Axis Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure maps
**the reference line against the
**Y1-axis if the line is currently
**mapped against Y2-axis.
*/

PROCEDURE Axis IS
  chart og_object;
  axis number;
  refline og_refline;
  template og_template;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  refline := og_get_refline(template, 0);
  axis := og_get_axis(refline);
  if axis = og_y2_axis then
    og_set_axis(refline, og_y1_axis);
  end if;
  og_update_chart(chart);
END;


Date Value Property

  Examples	  Related Topics

Description  Is the date value at which the reference line appears.

Syntax

PROCEDURE OG_Set_Datevalue
  (refline    OG_Refline,
   datevalue  DATE);

FUNCTION OG_Get_Datevalue
  (refline  OG_Refline)
RETURN DATE;

Parameters

refline	Is the reference line being described.
datevalue	Is the date value at which the reference line appears.


Date Value Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure increases
**reference line value by 30 days.
*/

PROCEDURE DateVal IS
  chart og_object;
  dateval date;
  refline og_refline;
  template og_template;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  refline := og_get_refline(template, 0);
  dateval := og_get_datevalue(refline);
  og_set_datevalue(refline, dateval+30);
  og_update_chart(chart);
END;


Label Property

  Examples	  Related Topics

Description  Is the text label that identifies the reference line in the legend.

Syntax

PROCEDURE OG_Set_Label
  (refline  OG_Refline,
   label    VARCHAR2);

FUNCTION OG_Get_Label
  (refline  OG_Refline)
RETURN VARCHAR2;

Parameters

refline	Is the reference line being described.
label	Is the text label that identifies the reference line in the legend.


Label Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure changes
**the reference line name to 'New Label'
**if this is not the current name of the
**label.
*/

PROCEDURE label IS
  chart og_object;
  label varchar2(20);
  refline og_refline;
  template og_template;
BEGIN
chart := og_get_object('chart');
  template := og_get_template(chart);
  refline := og_get_refline(template, 0);
  label := og_get_label(refline);
  if label != 'New Label' then
    og_set_label(refline, 'New label');
  end if;
  og_update_chart(chart);
END;


Number Value Property

  Examples	  Related Topics

Description  Is the number value at which the reference line appears.

Syntax

PROCEDURE OG_Set_Numvalue
  (refline   OG_Refline,
   numvalue  NUMBER);

FUNCTION OG_Get_Numvalue
  (refline  OG_Refline)
RETURN NUMBER;

Parameters

refline	Is the reference line being described.
numvalue	Is the number value at which the reference line appears.


Number Value Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure increases reference
**line value by 500.
*/

PROCEDURE NumVal IS
  chart og_object;
  num number;
  refline og_refline;
  template og_template;
BEGIN
  chart := og_get_object('chart');
  template := og_get_template(chart);
  refline := og_get_refline(template, 0);
  num := og_get_numvalue(refline);
  og_set_numvalue(refline, num+500);
  og_update_chart(chart);
END;


Rounded Rectangle Properties

Base Rectangle Property

Corner Radii Property


Base Rectangle Property

  Examples	  Related Topics

Description  Is the x- and y-coordinates of the upper-left corner, and the height and width of the rectangle used as the basis for the rectangle object (in layout units).

Syntax

PROCEDURE OG_Set_Rrect_Baserect
  (rrect        OG_Object,
   baserect     OG_Rectangle,
   damage       BOOLEAN       :=  TRUE,
   update_bbox  BOOLEAN       :=  TRUE);

FUNCTION OG_Get_Rrect_Baserect
  (rrect  OG_Object)
RETURN OG_Rectangle;

Parameters

rrect	Is the rounded rectangle being described.
baserect	Is the x- and y-coordinates of the upper-left corner, and the height and width of the rectangle used as the basis for the rectangle object (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Base Rectangle Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure reduces
**the size of the base rectangle or the
**rounded rectangle.
*/

PROCEDURE baserect (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  brect og_rectangle;
  rrect og_object;
BEGIN
  rrect := og_get_object('rrect');
  brect := og_get_rrect_baserect(rrect);
  brect.x := brect.x/2;
  brect.y := brect.y/2;
  brect.height := brect.height/2;
  brect.width := brect.width/2;
  og_set_rrect_baserect(rrect, brect);
END;


Corner Radii Property

  Examples	  Related Topics

Description  Is the x- and y-radii (in layout units) of the ellipse that would result if the arcs that form the rounded corners were continued to follow a full 360 degree path.

Syntax

PROCEDURE OG_Set_Corner
  (rrect        OG_Object,
   corner       OG_Point,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Corner
  (rrect  OG_Object)
RETURN OG_Point;

Parameters

rrect	Is the rounded rectangle being described.
corner	Is the x- and y-radii (in layout units) of the ellipse that would result if the arcs that form the rounded corners were continued to follow a full 360 degree path.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Corner Radii Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure doubles
**the x and y radii of the ellipse used to
**create the corners of a rounded rectangle
*/.

PROCEDURE corner (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  pt og_point;
  rrect og_object;
BEGIN
  rrect := og_get_object('rrect');
  pt := og_get_corner(rrect);
  pt.x := pt.x*2;
  pt.y := pt.y*2;
  og_set_corner(rrect, pt);
END;


Sound Properties Property

Name Property


Name Property

  Examples	  Related Topics

Description  Is the name of the sound.

Syntax

PROCEDURE OG_Set_Name
  (sound  OG_Sound,
   name   VARCHAR2);

FUNCTION OG_Get_Name
  (sound  OG_Sound)
RETURN VARCHAR2;

Parameters

sound	Is the sound object being described.
name	Is the name of the sound.


Name Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure gets the
**name of sound from the sound handler
**and assigns a new name to it.
*/

PROCEDURE SoundName (sound in og_sound) IS

name varchar2(10);

BEGIN

  name := og_get_name(sound);

  og_set_name(sound, name||'2');

END;


Simple Text Properties

Color Property

Font Property

Text String Property


Color Property

  Examples	  Related Topics

Description  Is the color in which the character string's text should be displayed.  Note that this is the color for the text itself.  To set the text object's edge or fill colors, change the text object's graphic properties.

Syntax

FUNCTION OG_Get_Color
  (text           OG_Object,
   cmptext_index  NUMBER,
   smptext_index  NUMBER)
RETURN VARCHAR2;

Parameters

text	Is the text object being described.
cmptext_index	Is the index number of the compound text element being described.
smptext_index	Is the index number of the simple text element being described.


Color Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure reads the color
**of the current text object.  If the
**current color is not red, it changes
**it to red.
*/

PROCEDURE color (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
color varchar2(20);
BEGIN
   color := og_get_color(hitobj, 0, 0);
   if color != 'red' then
     og_set_gcolor(hitobj, 'red');
   end if;
END;


Font Property

  Examples 	  Related Topics

Description  Is the font in which the character string's text is displayed.

Syntax

FUNCTION OG_Get_Font_Typeface
  (text           OG_Object,
   cmptext_index  NUMBER,
   smptext_index  NUMBER)
RETURN VARCHAR2;

FUNCTION OG_Get_Font_Ptsize
  (text           OG_Object,
   cmptext_index  NUMBER,
   smptext_index  NUMBER)
RETURN NUMBER;

FUNCTION OG_Get_Font_Style
  (text           OG_Object,
   cmptext_index  NUMBER,
   smptext_index  NUMBER)
RETURN NUMBER;

FUNCTION OG_Get_Font_Weight
  (text           OG_Object,
   cmptext_index  NUMBER,
   smptext_index  NUMBER)
RETURN NUMBER;

FUNCTION OG_Get_Font_Width
  (text           OG_Object,
   cmptext_index  NUMBER,
   smptext_index  NUMBER)
RETURN NUMBER;

FUNCTION OG_Get_Font_Kerning
  (text           OG_Object,
   cmptext_index  NUMBER,
   smptext_index  NUMBER)
RETURN BOOLEAN;

FUNCTION OG_Get_Font_Charset
  (text           OG_Object,
   cmptext_index  NUMBER,
   smptext_index  NUMBER)
RETURN NUMBER;

Parameters

text	Is the text object being described.
cmptext_index	Is the index number of the compound text element being described.
smptext_index	Is the index number of the simple text element being described.


Font Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 */The following procedure reads
**the current typeface from the
**selected text object.  If the
**current style is not the same
**as the typeface from the argument,
**it assigns a new typeface to the
**text object.
*/

PROCEDURE fonttypeface (text og_object, typeface varchar2)IS

style varchar2(10);

BEGIN

  style := og_get_font_typeface(text, 0,0);

  if style != typeface then

    og_set_font_typeface(text, typeface);

  end if;

END;


Text String Property

  Examples	  Related Topics

Description  Is the character string containing the actual text for the simple text element.

Syntax

PROCEDURE OG_Set_Str
  (text         OG_Object,
   str          VARCHAR2,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Str
  (text           OG_Object,
   cmptext_index  NUMBER,
   smptext_index  NUMBER)
RETURN VARCHAR2;

Parameters

text	Is the text object being described.
str	Is the character string containing the actual text for the simple text element.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.
cmptext_index	Is the index number of the compound text element being described.
smptext_index	Is the index number of the simple text element being described.


Text String Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads a text string from
**a display and appends numbers to it.
*/

PROCEDURE TextString IS

  text og_object;

BEGIN

  text := og_get_object('text object');

  og_set_str(text,og_get_str(text,0,0)||'123');

END;


Symbol Properties Property

Center Property

Index Property

Symbol Size Property


Center Property

  Examples	  Related Topics

Description  Is the x- and y-coordinates of the symbol's center (in layout units).

Syntax

PROCEDURE OG_Set_Center
  (symbol       OG_Object,
   center       OG_Point,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Center
  (symbol  OG_Object)
RETURN OG_Point;

Parameters

symbol	Is the symbol object being described.
center	Is the x- and y-coordinates of the symbol's center (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Center Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure moves
**the symbol from its original
**coordinate (x,y) to (x/2, y/2).
*/

PROCEDURE Center IS
  center og_point;
  symbol og_object;
BEGIN
  symbol := og_get_object('symbol');
  center := og_get_center(symbol);
  center.x := center.x/2;
  center.y := center.y/2;
  og_set_center(symbol, center);

END;


Index Property

  Examples	  Related Topics

Description  Is the index (or number) of the symbol's position as it appears in the symbol palette in the Builder.

Syntax

PROCEDURE OG_Set_Indx
  (symbol       OG_Object,
   indx         NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Indx
  (symbol  OG_Object)
RETURN NUMBER;

Parameters

symbol	Is the symbol object being described.
indx	Is the index (or number) of the symbol's position as it appears in the symbol palette in the Builder.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Index Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure gets the
**index of an object's symbol position
**in the symbol palette, and replaces
**the current symbol with the symbol
**which has an index value equal to the
**current index value + 1.
*/

PROCEDURE get_index IS
  sym_index number;
  symbol og_object;
BEGIN
  symbol := og_get_object('symbol');
  sym_index := og_get_indx(symbol);
  og_set_indx(symbol, sym_index+1);
END;


Symbol Size Property

  Examples	  Related Topics

Description  Is the symbol's size.  The value of this property may be one of the following built-in constants:

OG_Large_Symsize

OG_Medium_Symsize

OG_Small_Symsize

Syntax

PROCEDURE OG_Set_Symsize
  (symbol       OG_Object,
   symsize      NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Symsize
  (symbol  OG_Object)
RETURN NUMBER;

Parameters

symbol	Is the symbol object being described.
symsize	Is the symbol's size.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Symbol Size Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads a symbol's
**size.  If the symbol’s size is not LARGE,
**the procedure changes it to LARGE;
**if a symbol’s size is LARGE, the procedure
**changes it to small.
*/

PROCEDURE get_size IS
  sym_size number;
  symbol og_object;
BEGIN
  symbol := og_get_object('symbol');
  sym_size := og_get_symsize(symbol);
  if sym_size != og_large_symsize then
     og_set_symsize(symbol, og_large_symsize);
  else
     og_set_symsize(symbol, og_small_symsize);
  end if;
END;


Timer Properties

Active Property

Interval Property

Name Property

Procedure Property


Active Property

  Examples	  Related Topics

Description  Specifies whether the timer is active.

Syntax

PROCEDURE OG_Set_Active
  (timer   OG_Timer,
   active  BOOLEAN);

FUNCTION OG_Get_Active
  (timer  OG_Timer)
RETURN BOOLEAN;

Parameters

timer	Is the timer object being described.
active	Specifies whether the timer is active.


Active Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following sets the timer to inactive if it
**is currently in active mode.
*/

PROCEDURE TimerActive IS

  val boolean;

  timer og_timer;

BEGIN

  timer := og_get_timer('timer2');

  val := og_get_active(timer);

  if val then

    og_set_active(timer, false);

  end if;

END;


Interval Property

  Examples	  Related Topics

Description  Is the number of seconds that will pass between each execution of the timer procedure.

Syntax

PROCEDURE OG_Set_Interval
  (timer     OG_Timer,
   interval  NUMBER);

FUNCTION OG_Get_Interval
  (timer  OG_Timer)
RETURN NUMBER;

Parameters

timer	Is the timer object being described.
interval	Is the number of seconds that will pass between each execution of the timer procedure.


Interval Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure adds two
**seconds to the original timer
**interval.
*/

PROCEDURE TimerInterval IS

  interval number;

  timer og_timer;

BEGIN

  timer := og_get_timer('timer2');

  interval := og_get_interval(timer);

  og_set_interval(timer, interval+2);

END;


Name Property

  Examples	  Related Topics

Description  Is the name of the timer.

Syntax

PROCEDURE OG_Set_Name
  (timer  OG_Timer,
   name   VARCHAR2);

FUNCTION OG_Get_Name
  (timer  OG_Timer)
RETURN VARCHAR2;

Parameters

timer	Is the timer object being described.
name	Is the name of the timer.


Name Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure appends
**a '1' to the name of a timer.
*/

PROCEDURE TimerName IS

  name varchar2(10);

  timer og_timer;

BEGIN

  timer := og_get_timer('timer1');

  name := og_get_name(timer);

  og_set_name(timer, name||'1');

END;


Procedure Property

  Examples	  Related Topics

Description  Is the name of the procedure that will be executed when the timer is fired.

Syntax

PROCEDURE OG_Set_Timerproc
  (timer      OG_Timer,
   timerproc  VARCHAR2);

FUNCTION OG_Get_Timerproc
  (timer  OG_Timer)
RETURN VARCHAR2;

Parameters

timer	Is the timer object being described.
timerproc	Is the name of the procedure that will be executed when the timer is fired.


Procedure Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure changes the
**timer procedure to "NewProc" if it is
** current timer procedure.
*/

PROCEDURE TimerProc IS

  name varchar2(20);

  timer og_timer;

BEGIN

  timer := og_get_timer('timer2');

  name := og_get_timerproc(timer);

  if name != 'NewProc' then

    og_set_timerproc(timer, 'NewProc');

  end if;

END;


Text Properties

Bounding Box Height Property

Bounding Box Width Property

Character Set Property

Color Property

Compound Text Count Property

Custom Spacing Property

Fixed Bounding Box Property

Horizontal Alignment Property

Horizontal Origin Property

Invisible Property

Kerning Property

Nearest Property

Origin Point Property

Point Size Property

Scalable Bounding Box Property

Scalable Font Property

Spacing Property

Style Property

Synthesize Property

Typeface Property

Vertical Alignment Property

Vertical Origin Property

Weight Property

Width Property

Wraparound Property


Bounding Box Height Property

  Examples	  Related Topics

Description  Is the height of the bounding box (in layout units).  Whenever the bounding box changes, this property will automatically be updated to reflect the new height.  This property is used to set the height only if the Fixed Bounding Box property is TRUE.

Syntax

(See OG_Set_Text_Size.)

FUNCTION OG_Get_Text_Height
  (text  OG_Object)
RETURN NUMBER;

Parameters

text	Is the text object being described.


Bounding Box Height Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure doubles the size of the
**text object's bounding box.
*/

PROCEDURE BBoxSize IS

  width number;
  height number;
  text og_object;
BEGIN
   text := og_get_object('text object');
   width := og_get_text_width(text);
   height := og_get_text_height(text);
   og_set_text_size(text, width*2, height*2);
END;


Bounding Box Width Property Property
Bounding Box Width Property

  Examples	  Related Topics

Description  Is the width of the bounding box (in layout units).  Whenever the bounding box changes, this property will automatically be updated to reflect the new width.  This property is used to set the width only if the Fixed Bounding Box property is TRUE.

Syntax

PROCEDURE OG_Set_Text_Size
  (text         OG_Object,
   width        NUMBER,
   height       NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Text_Width
  (text  OG_Object)
RETURN NUMBER;

Parameters

text	Is the text object being described.
width	Is the width of the bounding box (in layout units).
height	Is the height of the bounding box (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Bounding Box Width Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure doubles the size of the
**text object's bounding box.
*/

PROCEDURE BBoxSize IS

  width number;
  height number;
  text og_object;
BEGIN
   text := og_get_object('text object');
   width := og_get_text_width(text);
   height := og_get_text_height(text);
   og_set_text_size(text, width*2, height*2);
END;


Character Set Property

  Examples	  Related Topics

Description  Is the font's character set.  Values for this field specify character sets such as U.S. ASCII, Kanji, and Arabic.  Not all character sets are available on all systems.  For more information, consult your system administrator or your system documentation.  The value of this field may be one of the following built-in constants:

OG_Us7ascii_Charset

OG_We8dec_Charset

OG_We8hp_Charset

OG_Us8pc437_Charset

OG_We8ebcdic37_Charset

OG_We8ebcdic500_Charset

OG_We8pc850_Charset

OG_D7dec_Charset

OG_F7dec_Charset

OG_S7dec_Charset

OG_E7dec_Charset

OG_Sf7ascii_Charset

OG_Ndk7dec_Charset

OG_I7dec_Charset

OG_Nl7dec_Charset

OG_Ch7dec_Charset

OG_Sf7dec_Charset

OG_We8iso8859p1_Charset

OG_Ee8iso8859p2_Charset

OG_Se8iso8859p3_Charset

OG_Nee8iso8859p4_Charset

OG_Cl8iso8859p5_Charset

OG_Ar8iso8859p6_Charset

OG_El8iso8859p7_Charset

OG_Iw8iso8859p8_Charset

OG_We8iso8859p9_Charset

OG_Ar8asmo708plus_Charset

OG_Ar7asmo449plus_Charset

OG_We8macroman8_Charset

OG_Jvms_Charset

OG_Jeuc_Charset

OG_Jdec_Charset

OG_Sjis_Charset

OG_Jdbcs_Charset

OG_Jhp_Charset

OG_Ksc5601_Charset

OG_Kibm5540_Charset

OG_Kdbcs_Charset

OG_Cgb231380_Charset

OG_Cdbcs_Charset

OG_Big5_Charset

OG_Cns1164386_Charset

Syntax

PROCEDURE OG_Set_Font_Charset
  (text         OG_Object,
   charset      NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text	Is the text object being described.
charset	Is the font's character set.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Character Set Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure checks
**if the selected text object's font set
**is in US ASCII Character Set.  If not,
**it assigns ASCII Character Set to the object.
*/

PROCEDURE CharSet (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
setNo number;
BEGIN

     SetNo := OG_get_Font_charset(hitobj,0,0);
     if SetNo != og_US7ASCII_Charset then
        og_set_font_charset(hitobj, og_US7ASCII_charset);
     end if;
END;


Color Property

  Examples	  Related Topics

Description  Is the text object's color.

Syntax

PROCEDURE OG_Set_Gcolor
  (text         OG_Object,
   gcolor       VARCHAR2,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text	Is the text object being described.
gcolor	Is the text object's color.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Color Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads
** the color of the current text object.
**If the current color is not red,
**it changes it to red.
*/

PROCEDURE color (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
color varchar2(20);
BEGIN
   color := og_get_color(hitobj, 0, 0);
   if color != 'red' then
     og_set_gcolor(hitobj, 'red');
   end if;
END;


Compound Text Count Property

  Examples	  Related Topics

Description  Is the number of compound text elements that compose the text object.

Syntax

FUNCTION OG_Get_Ctcount
  (text  OG_Object)
RETURN NUMBER;

Parameters

text	Is the text object being described.


Compound Text Count Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure counts the number of
**compound text elements in a text object.
/*

PROCEDURE CompoundTextCnt IS
  num number;
  text og_object;

BEGIN
  text := og_get_object;
  num := og_get_ctcount(text);
END;


Custom Spacing Property

  Examples	  Related Topics

Description  Is the custom spacing for the text object (in layout units).  This property is used to specify spacing only if the Spacing property is set to custom spacing.

Syntax

PROCEDURE OG_Set_Custom
  (text         OG_Object,
   custom       NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Custom
  (text  OG_Object)
RETURN NUMBER;

Parameters

text	Is the text object being described.
custom	Is the custom spacing for the text object (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Custom Spacing Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure resets the
**custom spacing to twice its original setting.
*/

PROCEDURE CustomSpacing (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
num number;
BEGIN
   num := og_get_custom(hitobj);
   og_set_str(hitobj, 'abc'||num);
   og_set_custom(hitobj, num*2);
END;


Fixed Bounding Box Property

  Examples	  Related Topics

Description  Specifies whether the text object's bounding box should remain a fixed size.  If this property is TRUE, the values of the Width and Height properties should specify the size of the bounding box.

Syntax

PROCEDURE OG_Set_Fixed
  (text         OG_Object,
   fixed        BOOLEAN,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Fixed
  (text  OG_Object)
RETURN BOOLEAN;

Parameters

text	Is the text object being described.
fixed	Specifies whether the text object's bounding box should remain a fixed size.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Fixed Bounding Box Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if the text object's bounding box
**remains a fixed size.
*/

PROCEDURE FixBBox IS
  val boolean;
  text og_object;
BEGIN
   text := og_get_object('text object');
   val := og_get_fixed(text);
   if val  then
      og_set_fixed(text, false);
   else
      og_set_fixed(text, true);
   end if;
END;


Horizontal Alignment Property

  Examples	  Related Topics

Description  Is the horizontal alignment of the text object.  The value of this property may be one of the following built-in constants:

OG_Left_Halign

OG_Center_Halign

OG_Right_Halign

Syntax

PROCEDURE OG_Set_Halign
  (text         OG_Object,
   halign       NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Halign
  (text  OG_Object)
RETURN NUMBER;

Parameters

text	Is the text object being described.
halign	Is the horizontal alignment of the text object.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Horizontal Alignment Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

Horizontal Alignment

 /*The following procedure reads the horizontal
**alignment and readjusts it.
*/

PROCEDURE Halign IS
  num number:=og_right_halign;
  text og_object;
BEGIN
   text := og_get_object('text object');
   num := og_get_halign(text);
   if num = og_left_halign then
     og_set_halign(text, og_center_halign);
   elsif num = og_center_halign then
     og_set_halign(text, og_right_halign);
   elsif num = og_right_halign then
     og_set_halign(text, og_left_halign);
   end if;
END;


Horizontal Origin Property

  Examples	  Related Topics

Description  Is the horizontal position of the text object relative to its origin point.  The value of this property may be one of the following built-in constants:

OG_Left_Horigin   Means the origin point lies along the left edge of the bounding box.

OG_Center_Horigin   Means the origin point lies equally between the left and right edges of the boundingbox.

OG_Right_Horigin   Means the origin point lies along the right edge of the bounding box.

Syntax

PROCEDURE OG_Set_Horigin
  (text         OG_Object,
   horigin      NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Horigin
  (text  OG_Object)
RETURN NUMBER;

Parameters

text	Is the text object being described.
horigin	Is the horizontal position of the text object relative to its origin point.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Horizontal Origin Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

/*The following procedure reads the horizontal
**origin and readjusts it.
*/

PROCEDURE Horigin IS

  num number;

  text og_object;

BEGIN

   text := og_get_object('text object');
   num := og_get_horigin(text);
   if num = og_left_horigin then
     og_set_horigin(text, og_center_horigin);
   elsif num = og_center_horigin then
     og_set_horigin(text, og_rightr_horigin);
   elsif num = og_right_horigin then
     og_set_horigin(text, og_left_horigin);
   end if;
END;


Invisible Property

  Examples	  Related Topics

Description  Specifies whether the text in the text object should be invisible.  This is useful for text fields in which a user enters a password, if you don't want the password to be seen.

Syntax

PROCEDURE OG_Set_Invisible
  (text       OG_Object,
   invisible  BOOLEAN,
   damage         BOOLEAN    :=  TRUE,
   update_bbox    BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Invisible
  (text  OG_Object)
RETURN BOOLEAN;

Parameters

text	Is the text object being described.
invisible	Specifies whether the text in the text object should be invisible.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Invisible Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure determines if
** text in a text object is invisible. If it
** is invisible it makes it visible; if it is
** visible it makes it invisible.
*/

PROCEDURE Invisible IS
  val boolean;
  text og_object;
BEGIN
   text := og_get_object('text object');
   val := og_get_invisible(text);
   if val  then
      og_set_invisible(text, false);
   else
      og_set_invisible(text, true);
   end if;
END;


Kerning Property

  Examples	  Related Topics

Description  Specifies whether the font should be kerned.  Kerning is the adjustment of the space between adjacent letters to improve the readability of the text.

Syntax

PROCEDURE OG_Set_Font_Kerning
  (text         OG_Object,
   kerning      BOOLEAN,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text	Is the text object being described.
kerning	Specifies whether the font should be kerned.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Kerning Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure turns font
**kerning on and off for a selected text object.

PROCEDURE kerning (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  val boolean;
BEGIN
  val := og_get_font_kerning(hitobj,0,0);
  if val then
     og_set_font_kerning(hitobj, false);
  else
     og_set_font_kerning(hitobj, true);
  end if;
END;


Nearest Property

  Examples	  Related Topics

Description  Specifies whether Graphics Builder should substitute the nearest matching font if the exact font specified cannot be found.  The precedence for finding the nearest font is typeface, point size, style, weight, and width (meaning that Graphics Builder first tries to find the specified typeface, then size, etc.).

Syntax

PROCEDURE OG_Set_Font_Nearest
  (text         OG_Object,
   nearest      BOOLEAN,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text	Is the text object being described.
nearest	Specifies whether Graphics Builder should substitute the nearest matching font if the exact font specified cannot be found.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Nearest Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure sets nearest
**properties to true.
*/

PROCEDURE nearest (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS

BEGIN
     OG_Set_Font_Nearest(hitobj, true);
END;


Origin Point Property

  Related Topics

Description  Is the x- and y-coordinates of the text object's upper-left corner (in layout units).

Syntax

PROCEDURE OG_Set_Origin
  (text         OG_Object,
   origin       OG_Point,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Origin
  (text  OG_Object)
RETURN OG_Point;

Parameters

text	Is the text object being described.
origin	Is the x- and y-coordinates of the text object's upper-left corner (in layout units).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Point Size Property

  Examples	  Related Topics

Description  Is the font's point size.  Values for this field are system-specific.  For more information, consult your system administrator or your system documentation.

Syntax

PROCEDURE OG_Set_Font_Ptsize
  (text         OG_Object,
   ptsize       NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text	Is the text object being described.
ptsize	Is the font's point size.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Point Size Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the point size of the
**current object and enlarges the text object to double
** its original size.
*/

PROCEDURE ptsize (text og_object)IS
num number;
BEGIN
  num := og_get_font_ptsize(text,0,0);
  og_set_font_ptsize(text, num*2);
END;


Scalable Bounding Box Property

  Examples	  Related Topics

Description  Specifies whether the text object's bounding box should be scaled when the text object is scaled.

Syntax

PROCEDURE OG_Set_Bbscale
  (text         OG_Object,
   bbscale      BOOLEAN,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Bbscale
  (text  OG_Object)
RETURN BOOLEAN;

Parameters

text	Is the text object being described.
bbscale	Specifies whether the text object's bounding box should be scaled when the text object is scaled.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Scalable Bounding Box Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if the text
**object's bounding box is scaled when the
**text object is scaled.
*/

PROCEDURE Scalebox IS
  val boolean;
  text og_object;
BEGIN
   text := og_get_object('text object');
   val := og_get_bbscale(text);
   if val  then
      og_set_bbscale(text, false);
   else
      og_set_bbscale(text, true);
   end if;
END;


Scalable Font Property

  Examples	  Related Topics

Description  Specifies whether the point size of the font should be scaled when the text object is scaled.  The value of this property may be one of the following:

Syntax

PROCEDURE OG_Set_Fontscale
  (text         OG_Object,
   fontscale    BOOLEAN,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Fontscale
  (text  OG_Object)
RETURN BOOLEAN;

Parameters

text	Is the text object being described.
fontscale	Specifies whether the point size of the font should be scaled when the text object is scaled.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Scalable Font Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure checks if the point size is
** scaled when the text object is scaled.
*/

PROCEDURE Scalable IS
  val boolean;
  text og_object;
BEGIN
   text := og_get_object('text object');
   val := og_get_fontscale(text);
   if val  then
      og_set_fontscale(text, false);
   else
      og_set_fontscale(text, true);
   end if;
END;


Spacing Property

  Examples	  Related Topics

Description  Is the line spacing for the text object.  The value of this property may be one of the built-in constants listed below.  If custom spacing is set, the value of the Custom Spacing property should specify the exact spacing amount.

OG_Single_Space

OG_Onehalf_Space

OG_Double_Space

OG_Custom_Space   Means the text uses custom line spacing.   The actual spacing used is defined in the Custom Spacing property.

Syntax

PROCEDURE OG_Set_Spacing
  (text         OG_Object,
   spacing      NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Spacing
  (text  OG_Object)
RETURN NUMBER;

Parameters

text	Is the text object being described.
spacing	Is the line spacing for the text object.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Spacing Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following button procedure
**rotates the spacing setting of a
**text object.
*/

PROCEDURE Spacing (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
num number;
BEGIN
   num := og_get_spacing(hitobj);
   if num = og_single_space then
      og_set_spacing(hitobj, og_onehalf_space);
   elsif num = og_onehalf_space then
   og_set_spacing(hitobj, og_double_space);
   elsif num = og_double_space then
   og_set_spacing(hitobj, og_custom_space);
   elsif num = og_custom_space then
   og_set_spacing(hitobj, og_single_space);
   end if;
END;


Style Property

  Examples	  Related Topics

Description  Is the font's style.  Not all styles are available on all systems.  For more information, consult your system administrator or your system documentation.  The value of this field may be one of the following built-in constants:

OG_Blink_Fontstyle

OG_Inverted_Fontstyle

OG_Italic_Fontstyle

OG_Oblique_Fontstyle

OG_Outline_Fontstyle

OG_Overstrike_Fontstyle

OG_Plain_Fontstyle

OG_Shadow_Fontstyle

OG_Underline_Fontstyle

OG_Unknown_Fontstyle   Means the style is unknown.  You cannot set a style to this value; however, if you get a font and Graphics Builder cannot determine its style, this value is returned.

Syntax

PROCEDURE OG_Set_Font_Style
  (text         OG_Object,
   style        NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text	Is the text object being described.
style	Is the font's style.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Style Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure
**rotates the text style
*/

PROCEDURE style (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
text og_object;
num number;
BEGIN
  text := og_get_object('text object');
  num := og_get_font_style(text,0,0);
  if num = og_blink_fontstyle then
    og_set_font_style(text, og_inverted_fontstyle);
  elsif num = og_inverted_fontstyle then
    og_set_font_style(text, og_italic_fontstyle);
  elsif num = og_italic_fontstyle then
    og_set_font_style(text, og_oblique_fontstyle);
  elsif num = og_oblique_fontstyle then
    og_set_font_style(text, og_outline_fontstyle);
  elsif num = og_outline_fontstyle then
    og_set_font_style(text, og_overstrike_fontstyle);
  elsif num = og_overstrike_fontstyle then
    og_set_font_style(text, og_plain_fontstyle);
  elsif num = og_plain_fontstyle then
    og_set_font_style(text, og_shadow_fontstyle);
  elsif num = og_shadow_fontstyle then
    og_set_font_style(text, og_underline_fontstyle);
  elsif num = og_underline_fontstyle then
    og_set_font_style(text, og_unknown_fontstyle);
  elsif num = og_unknown_fontstyle then
    og_set_font_style(text, og_blink_fontstyle);
  end if;
END;


Synthesize Property

  Examples	  Related Topics

Description  Specifies whether Graphics Builder should try to synthesize the desired font (if the specified font cannot be found) by transforming the nearest-matching font.

Syntax

PROCEDURE OG_Set_Font_Synthesize
  (text         OG_Object,
   synthesize   BOOLEAN,
   damage       BOOLEAN  :=  TRUE,
   update_bbox  BOOLEAN  :=  TRUE);

Parameters

text	Is the text object being described.
synthesize	Specifies whether Graphics Builder should try to synthesize the desired font (if the specified font cannot be found) by transforming the nearest-matching font.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Synthesize Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure sets synthesize
** properties to true.
*/

PROCEDURE synthesize (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS

BEGIN
     OG_Set_Font_Synthesize(hitobj, true);
END;


Typeface Property

  Examples	  Related Topics

Description  Is the font's typeface (font name).  Values for this field are system-specific, and may include typefaces such as times, courier, and helvetica.  For more information, consult your system administrator or your system documentation.

Syntax

PROCEDURE OG_Set_Font_Typeface
  (text         OG_Object,
   typeface     VARCHAR2,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text	Is the text object being described.
typeface	Is the font's typeface (font name).
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Typeface Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

*/The following procedure reads
**the current typeface from the
**selected text object.  If the
**current style is not the same
**as the typeface from the argument,
**it assigns a new typeface to the
**text object.

PROCEDURE fonttypeface (text og_object, typeface varchar2)IS
style varchar2(10);
BEGIN
  style := og_get_font_typeface(text, 0,0);
  if style != typeface then
    og_set_font_typeface(text, typeface);
  end if;
END;


Vertical Alignment Property

  Examples	  Related Topics

Description  Is the vertical alignment of the text object.  The value of this property may be one of the following built-in constants:

OG_Top_Valign

OG_Middle_Valign

OG_Bottom_Valign

Syntax

PROCEDURE OG_Set_Valign
  (text         OG_Object,
   valign       NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Valign
  (text  OG_Object)
RETURN NUMBER;

Parameters

text	Is the text object being described.
valign	Is the vertical alignment of the text object.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Vertical Alignment Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* The following procedure reads the vertical
** alignment and readjusts it.
*/

PROCEDURE VAligin IS
  num number;
  text og_object;
BEGIN
   text := og_get_object('text object');
   num := og_get_valign(text);
   if num = og_top_valign then
     og_set_valign(text, og_middle_valign);
   elsif num = og_middle_valign then
     og_set_valign(text, og_bottom_valign);
   elsif num = og_bottom_valign then
     og_set_valign(text, og_top_valign);
   end if;
END;


Vertical Origin Property

  Examples	  Related Topics

Description  Is the vertical position of the text object relative to its origin point.  The value of this property may be one of the following built-in constants:

OG_Top_Vorigin   Means the origin point lies along the top edge of the bounding box.

OG_Middle_Vorigin   Means the origin point lies equally between the top and bottom edges of the bounding box.

OG_Bottom_Vorigin   Means the origin point lies along the bottom edge of the bounding box.

Syntax

PROCEDURE OG_Set_Vorigin
  (text         OG_Object,
   vorigin      NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Vorigin
  (text  OG_Object)
RETURN NUMBER;

Parameters

text	Is the text object being described.
vorigin	Is the vertical position of the text object relative to its origin point.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Vertical Origin Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure reads the
**vertical origin and readjusts it.
*/

PROCEDURE Vorigin IS
  num number;
  text og_object;
BEGIN
   text := og_get_object('text object');
   num := og_get_vorigin(text);
   if num = og_top_vorigin then
     og_set_vorigin(text, og_middle_vorigin);
   elsif num = og_middle_vorigin then
     og_set_vorigin(text, og_bottom_vorigin);
   elsif num = og_bottom_vorigin then
     og_set_vorigin(text, og_top_vorigin);
   end if;
END;


Weight Property

  Examples	  Related Topics

Description  Is the font's weight.  Not all weights are available on all systems.  For more information, consult your system administrator or your system documentation.  The value of this field may be one of the following built-in constants:

OG_Bold_Fontweight

OG_Demibold_Fontweight

OG_Demilight_Fontweight

OG_Extrabold_Fontweight

OG_Extralight_Fontweight

OG_Light_Fontweight

OG_Medium_Fontweight

OG_Ultrabold_Fontweight

OG_Ultralight_Fontweight

OG_Unknown_Fontweight   Means the weight is unknown.  You cannot set a weight to this value; however, if you get a font and Graphics Builder cannot determine its weight, this value is returned.

Syntax

PROCEDURE OG_Set_Font_Weight
  (text         OG_Object,
   weight       NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text	Is the text object being described.
weight	Is the font's weight.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Weight Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure
**rotates the font weight for a
**selected text object.
*/

PROCEDURE weight (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  num number;
  text og_object;
BEGIN
  text := og_get_object('text object');
  num := og_get_font_weight(text,0,0);
  if num = og_bold_fontweight then
    og_set_font_weight(text, og_demibold_fontweight);
  elsif num = og_demibold_fontweight then
    og_set_font_weight(text, og_demilight_fontweight);
  elsif num = og_demilight_fontweight then
    og_set_font_weight(text, og_extrabold_fontweight);
  elsif num = og_extrabold_fontweight then
    og_set_font_weight(text, og_extralight_fontweight);
  elsif num = og_extralight_fontweight then
    og_set_font_weight(text, og_light_fontweight);
  elsif num = og_light_fontweight then
    og_set_font_weight(text, og_medium_fontweight);
  elsif num = og_medium_fontweight then
    og_set_font_weight(text, og_ultrabold_fontweight);
  elsif num = og_ultrabold_fontweight then
    og_set_font_weight(text, og_ultralight_fontweight);
  elsif num = og_ultralight_fontweight then
    og_set_font_weight(text, og_unknown_fontweight);
  elsif num = og_unknown_fontweight then
    og_set_font_weight(text, og_bold_fontweight);
  end if;
END;


Width Property

  Examples	  Related Topics

Description  Is the font's width.  Not all widths are available on all systems.  For more information, consult your system administrator or your system documentation.  The value of this field may be one of the following built-in constants:

OG_Dense_Fontwidth

OG_Expand_Fontwidth

OG_Extradense_Fontwidth

OG_Extraexpand_Fontwidth

OG_Normal_Fontwidth

OG_Semidense_Fontwidth

OG_Semiexpand_Fontwidth

OG_Ultradense_Fontwidth

OG_Ultraexpand_Fontwidth

OG_Unknown_Fontwidth   Means the width is unknown.  You cannot set a weight to this value; however, if you get a font and Graphics Builder cannot determine its width, this value is returned.

Syntax

PROCEDURE OG_Set_Font_Width
  (text         OG_Object,
   width        NUMBER,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

Parameters

text	Is the text object being described.
width	Is the font's width.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Width Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following button procedure
**rotates the font width for a
**selected test object.
*/

PROCEDURE width (buttonobj IN og_object,
                         hitobj IN og_object,
                         win IN og_window,
                         eventinfo IN og_event) IS
  num number;
  text og_object;
BEGIN
  text := og_get_object('text object');
  num := og_get_font_width(text,0,0);
  if num = og_dense_fontwidth then
    og_set_font_width(text, og_expand_fontwidth);
  elsif num = og_expand_fontwidth then
    og_set_font_width(text, og_extradense_fontwidth);
  elsif num = og_extradense_fontwidth then
    og_set_font_width(text, og_extraexpand_fontwidth);
  elsif num = og_extraexpand_fontwidth then
    og_set_font_width(text, og_normal_fontwidth);
  elsif num = og_normal_fontwidth then
    og_set_font_width(text, og_semidense_fontwidth);
  elsif num = og_semidense_fontwidth then
    og_set_font_width(text, og_semiexpand_fontwidth);
  elsif num = og_semiexpand_fontwidth then
    og_set_font_width(text, og_ultradense_fontwidth);
  elsif num = og_ultradense_fontwidth then
    og_set_font_width(text, og_ultraexpand_fontwidth);
  elsif num = og_ultraexpand_fontwidth then
    og_set_font_width(text, og_unknown_fontwidth);
  elsif num = og_unknown_fontwidth then
    og_set_font_width(text, og_dense_fontwidth);
  end if;
END;


Wraparound Property

  Examples	  Related Topics

Description  Specifies whether the text should "wrap" to fit into the text object's bounding box.  As described below, a compound text element represents a line of text, and is made up of simple text elements.

Syntax

PROCEDURE OG_Set_Wrap
  (text         OG_Object,
   wrap         BOOLEAN,
   damage       BOOLEAN    :=  TRUE,
   update_bbox  BOOLEAN    :=  TRUE);

FUNCTION OG_Get_Wrap
  (text  OG_Object)
RETURN BOOLEAN;

Parameters

text	Is the text object being described.
wrap	Specifies whether the text should "wrap" to fit into the text object's bounding box.
damage	Is the damage flag.
update_bbox	Is the bounding box update flag.


Wraparound Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure checks if the text is 'wrapped'
** into the text's bounding box.
*/

PROCEDURE wrap IS
  val boolean;
  text og_object;
BEGIN
   text := og_get_object('text object');
   val := og_get_wrap(text);
   if val  then
      og_set_wrap(text, false);
   else
      og_set_wrap(text, true);
   end if;
END;


No entries begin with this letter.


Window Properties

Description

The position and dimensions of windows are expressed in "screen resolution units," more commonly known as pixels.  You can obtain the horizontal and vertical values of the screen resolution using the built-ins OG_Get_Ap_Hscreen_Res and OG_Get_Ap_Vscreen_Res.

You should use these built-ins instead of an actual numeric value so that your application will maintain a consistent look on systems with different screen resolutions.

Height Property

Help Target Property

Name Property

Position Property

Width Property


Height Property

  Examples	  Related Topics

Description  Is the height of the window (in screen resolution units).

Syntax

(See OG_Set_Window_Size.)

FUNCTION OG_Get_Window_Height
  (window  OG_Window)
RETURN NUMBER;

Parameters

window	Is the window being described.


Height Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /* /*The following procedure resizes
**the window to half its original size.
*/

PROCEDURE WinSize IS
  window og_window;
  width number;
  height number;
BEGIN
  window := og_get_window('Main Layout');
  width := og_get_window_width(window);
  height := og_get_window_height(window);
  og_set_window_size(window, width/2,height/2);
END;


Help Target Property

  Examples	  Related Topics

Description  Is the hypertext target in the runtime Help document that is displayed when the Help system is invoked while the window is active.

Syntax

PROCEDURE OG_Set_Helptarget
  (window      OG_Window,
   helptarget  VARCHAR2);

FUNCTION OG_Get_Helptarget
  (window  OG_Window)
RETURN VARCHAR2;

Parameters

window	Is the window being described.
helptarget	Is the hypertext target in the runtime Help document that is displayed when the Help system is invoked while the window is active.


Help Target Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure sets the help
**target to 'NewTarget' if "New Target" is not
** the current help target.
*/

PROCEDURE Help IS
  window og_window;
  help varchar2(20);
BEGIN
  window := og_get_window('Main Layout');
  help :=  og_get_helptarget(window);
  if help != 'NewTarget' then
    og_set_helptarget(window, 'NewTarget');
  end if;
END;


Name Property

  Examples	  Related Topics

Description  Is the window's name.  At runtime, the default name of the layout window is "Main Layout".

Syntax

PROCEDURE OG_Set_Name
  (window  OG_Window,
   name    VARCHAR2);

FUNCTION OG_Get_Name
  (window  OG_Window)
RETURN VARCHAR2;

Parameters

window	Is the window being described.
name	Is the window's name.


Name Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure resets
**the name of the window if its name
**is not 'Main Layout'.
*/

PROCEDURE Name IS
  window og_window;
  name varchar2(20);
BEGIN
  window := og_get_window('Main Layout');
  name :=  og_get_name(window);
  if name != 'Main Layout' then
    og_set_name(window, 'Main Layout');
  end if;
END;


Position Property

  Examples	  Related Topics

Description  Is the x- and y-coordinates of the window's upper left corner (in screen resolution units).

Syntax

PROCEDURE OG_Set_Position
  (window    OG_Window,
   position  OG_Point);

FUNCTION OG_Get_Position
  (window  OG_Window)
RETURN OG_Point;

Parameters

window	Is the window being described.
position	Is the x- and y-coordinates of the window's upper left corner (in screen resolution units).


Position Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure repositions
**the window.
*/

PROCEDURE Position IS
  window og_window;
  pos og_point;
BEGIN
  window := og_get_window('Main Layout');
  pos := og_get_position(window);
  pos.x := pos.x*2;
  pos.y := pos.y*2;
  og_set_position(window, pos);
END;


Width Property

  Examples	  Related Topics

Description  Is the width of the window (in screen resolution units).

Syntax

PROCEDURE OG_Set_Window_Size
  (window  OG_Window,
   width   NUMBER,
   height  NUMBER);

FUNCTION OG_Get_Window_Width
  (window  OG_Window)
RETURN NUMBER;

Parameters

window	Is the window being described.
width	Is the width of the window (in screen resolution units).
height	Is the height of the window (in screen resolution units).


Width Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

 /*The following procedure resizes the window
** to half its original size.
*/

PROCEDURE WinSize IS
  window og_window;
  width number;
  height number;
BEGIN
  window := og_get_window('Main Layout');
  width := og_get_window_width(window);
  height := og_get_window_height(window);
  og_set_window_size(window, width/2,height/2);
END;


 Troubleshooting

This topic explains how to handle error messages and exceptions, and lists them in numeric sequence.  It covers the following topics:

abnormal conditions

Graphics Builder error messages

Graphics Builder exceptions

error message codes

calling Oracle customer support


Graphics Builder error messages

This section describes the Graphics Builder error messages.  The errors are listed in order by their error code number.

OG-00001:	Batch compilation error(s)

 Cause:	You tried to run a display in the PL/SQL debugger, but Graphics Builder detected an error while performing a batch compilation of the display's program units.

 Action:	Show the Batch Compiler, then correct the listed PL/SQL errors.

OG-00002:	Button procedure not found

 Cause:	You associated a button procedure with an object or a layer, but Graphics Builder could not find a procedure with that name.

 Action:	If the procedure does not exist, create it.  Also, verify that you typed the procedure name correctly.

OG-00005:	Program unit consistency error(s)

 Cause:	You tried to run a display that contains consistency errors.

 Action:	Show the Consistency Checker, and perform a consistency check.  Then correct the listed errors.

OG-00006:	Parameter truncation occurred

 Cause:	You assigned a value that is longer than 2000 bytes to a parameter of type CHAR.

 Action:	The maximum length of a CHAR parameter is 2000 bytes.

OG-00030:	Invalid program unit specification

 Cause:	You tried to apply a program unit that has an invalid specification.

 Action:	Insert a valid header, then try again.

OG-00032:	Duplicate PL/SQL program unit name

 Cause:	You tried to create a program unit with the same name as that of an existing program unit.

 Action:	Give your program units unique names.

OG-00057:	Trigger procedure not found

 Cause:	You associated a procedure with a trigger, but Graphics Builder could not find a procedure with that name.

 Action:	If the procedure does not exist, create it.  Also, verify that you typed the procedure name correctly.

OG-00064:	Program unit parameter extraction failed

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00066:	Database connection setting in PL/SQL failed

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00068:	Save of PL/SQL attached library list failed

 Cause:	Graphics Builder encountered an error while trying to save the list of attached PL/SQL libraries.

 Action:	If saving to a database, verify that the Graphics Builder tables are installed correctly.  If saving to a file, verify that you have write privileges, that you have not run out of disk space, and that no other situations exist in which you would not be able to write a file.

OG-00069:	Load of PL/SQL attached library list failed

 Cause:	Graphics Builder encountered an error while trying to load the list of attached PL/SQL libraries.

 Action:	If loading from a database, verify that the Graphics Builder tables are installed correctly.  If loading from a file, verify that you have read privileges, that you have access to the libraries in question (e.g., they are in the current directory or the directory specified by the ORAPLSQLLOADPATH environment variable), and that no other situations exist in which you would not be able to read a file.

OG-00070:	Delete of PL/SQL attached library list failed

 Cause:	Graphics Builder encountered an error while trying to delete the list of attached PL/SQL libraries.

 Action:	Verify that the Graphics Builder tables are installed correctly.

OG-00071:	Display contains uncompiled program unit(s)

 Cause:	You tried to run a display that contains program units that have not been compiled.

 Action:	Compile all of the program units, then save or generate the display before running it.

OG-00072:	Program unit load failed

 Cause:	Graphics Builder encountered an error while trying to load a program unit.

 Action:	Verify that all database tables or other program units that the program unit references are accessible, and that the Graphics Builder tables are installed correctly.

OG-00076:	One or more PL/SQL program units is too big for encoding

 Cause:	You tried to save a display that contains one or more program units that exceed the maximum contiguous memory size allowed for your system.

 Action:	Break your large program units into smaller ones.  For more information on your system's memory constraints, see the Graphics Builder documentation for your operating system.

OG-00078:	Unable to create breakpoints.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00079:	Runtime simulation aborted.

 Cause:	You canceled an operation before entering runtime simulation.

OG-00077:	One or more PL/SQL program units is too big to be decoded

 Cause:	You tried to open a display that contains one or more program units that exceed the maximum contiguous memory size allowed for your system.

 Action:	Open the display on the system on which it was created, and break your large program units into smaller ones.  For more information on your system's memory constraints, see the Graphics Builder documentation for your operating system.

OG-00401:	No timer name specified

 Cause:	You tried to apply changes in the Timer Triggers dialog box, but the selected timer's name in the Rename text field is blank.

 Action:	Type a name in the Rename text field, or delete the timer.

OG-00402:	Duplicate timer name specified

 Cause:	You tried to apply changes in the Timer Triggers dialog box, but the selected timer's name is the same as that of another timer.

 Action:	Give the timer a unique name by typing it in the Rename text field.

OG-00403:	Duplicate document name specified

 Cause:	You tried to do one of the following in a single Graphics Builder session:

A.	Open a display in the Builder that is already open in the Builder.

B.	Open a display in runtime simulation that is already open in runtime simulation.

C.	Open a display in the Runtime executable that is already open in the Runtime executable.

 Action:	In a single Graphics Builder session, you can perform one of the above Open operations on a specific display only once.

OG-00406:	No sound name specified

 Cause:	You tried to apply changes in the Sounds dialog box, but the selected sound's name in the Rename text field is blank.

 Action:	Type a name in the Rename text field, or delete the sound.

OG-00407:	Duplicate sound name

 Cause:	You tried to apply changes in the Sounds dialog box, but the selected sound's name is the same as that of another sound.

 Action:	Give the sound a unique name by typing it in the Rename text field.

OG-00408:	Timer interval of zero specified

 Cause:	You tried to apply changes in the Timer Triggers dialog box, but the selected timer's interval is set to 0 minutes and 0 seconds.

 Action:	Type valid numbers in the Interval text fields, or delete the timer.

OG-00409:	No procedure specified for timer

 Cause:	You tried to apply changes in the Timer Triggers dialog box, but the selected timer's trigger procedure in the Procedure text field is blank.

 Action:	Type the name of a PL/SQL trigger procedure in the Procedure text field, or delete the timer.

OG-00410:	Could not create timer

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00411:	Designer display not found.

 Cause:	You tried to synchronize program units from a runtime simulation display to the Builder display, but the Builder display could not be found.

 Action:	Ensure the Builder display is open, and that you have not changed its name since running it.

OG-00412:	More than one node is selected.

 Cause:	You selected multiple nodes in the Object Navigator, and then attempted an operation that requires that only one node is selected.

 Action:	Select only one node, then try again.

OG-00413:	No display is selected.

 Cause:	You attempted an operation that requires that a display is selected, but no display is selected.

 Action:	Select a display, then try again.

OG-00414:	This display is already running.

 Cause:	You attempted to run a display in runtime simulation, but that display is already running.

 Action:	Select another display, or close the display that is running.

OG-00415:	Duplicate parameter name specified.

 Cause:	You attempted to create a parameter with a name already in use by another parameter.

 Action:	Use a unique name for the parameter.

OG-00416:	No parameter name specified.

 Cause:	You attempted to create a parameter, but you did not specify its name.

 Action:	Specify a name for the parameter.

OG-00505:	List count error

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00507:	Invalid query type

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00508:	Chart template not found

 Cause:	You tried to update a chart, but the chart template on which it is based could not be found.  The possible causes of this error include:

A.	You deleted the chart template.

B.	You renamed the chart template.

 Action:	You can change the template on which the chart is based by selecting a new template in the chart's Chart Properties dialog box.  In addition, you can take the following action(s) to correct this error:

If A.	Create a new chart template with the same name as the deleted template.

If B.	Rename the chart template so it matches the name expected by the chart.

OG-00511:	No chart template specified

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00512:	No query specified

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00513:	Query has no data.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00514:	No document pointer specified

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00516:	Communications context load failure

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00517:	Communications interface load failure

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00518:	Inter-product data transmission failed

 Cause:	Another Oracle product invoked Graphics Builder and requested that Graphics Builder provide it with the contents of a display, but Graphics Builder encountered an error while trying to communicate with that product.

 Action:	Verify that Graphics Builder was invoked in the synchronous communication mode.  Also, verify that a system error did not occur that would prevent the products from communicating with each other.

OG-00519:	Date to string conversion failed

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00520:	Integration error - <message>

 Cause:	An error occurred while trying to integrate with another product.

 Action:	Review the error message returned, then refer to the documentation for the other product.

OG-00521:	Help not initialized.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00522:	Invalid printer name.

 Cause:	An error occurred while trying to locate a printer.

 Action:	Verify that the printer is connected and working.

OG-00524:	No query name specified.

 Cause:	You attempted to create a query, but you did not specify its name.

 Action:	Specify a name for the query.

OG-00525:	Duplicate query name specified.

 Cause:	You attempted to create a query with a name already in use by another query.

 Action:	Use a unique name for the query.

OG-00528:	Duplicate column name.

 Cause:	You attempted to create a column with a name already in use by another column.

 Action:	Use a unique name for the column.

OG-00529:	No column name specified.

 Cause:	You attempted to create a column, but you did not specify its name.

 Action:	Specify a name for the column.

OG-00532:	Cannot update chart while update in progress.

 Cause:	You attempted to update a chart while it is already being updated.  Most likely, you attempted operation within a chart-related trigger that causes another chart update.

 Action:	Verify that you are not doing anything that will update the chart while it is already being updated.

OG-00533:	Drill-down parameter does not exist.

 Cause:	Graphics Builder tried to set a parameter used by a drill-down chart, but the parameter does not exist.

 Action:	Verify that the parameter exists, and is correctly assigned to the chart.

OG-00602:	Accept of program unit failed

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00604:	Cancel of program unit failed

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00608:	Unable to execute PL/SQL procedure

 Cause:	Graphics Builder encountered an error while trying to execute a PL/SQL procedure.

 Action:	Make sure the procedure has not been uncompiled inadvertently.

OG-00609:	Internal PL/SQL execution error

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00622:	Invalid parameter position

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00630:	Internal PL/SQL library attach failure

 Cause:	Graphics Builder encountered an error while trying to attach an internal library.

 Action:	If the display is stored in the database, verify that the Graphics Builder tables are installed correctly.  If the display is stored in a file, verify that the file your are trying to open is a valid display file.

OG-00632:	Internal PL/SQL library insert error

 Cause:	Graphics Builder encountered an error while trying to insert a program unit into a library.

 Action:	If the display is stored in the database, verify that the Graphics Builder tables are installed correctly.  If the display is stored in a file, verify that your file system has enough free space.

OG-00633:	Internal PL/SQL library deletion failure

 Cause:	Graphics Builder encountered an error while trying to delete an internal library.

 Action:	Verify that the Graphics Builder tables are installed correctly.

OG-00637:	Unhandled PL/SQL exception <exception_number>

 Cause:	Graphics Builder encountered a PL/SQL exception while executing a program unit.

 Action:	Take note of the exception number listed at the end of the error message, then refer to the following table for more information about the exception:

Exception range	Exception type	Refer to

----------------------------------------------------------------------------------------

0-99999	Oracle/PL/SQL	Oracle7 Server Messages

and Codes Manual

102000-102499	Graphics Builder built-in	PL/SQL Exceptions

104500-104999	TOOL_INT package	PL/SQL Exceptions

105000-105499	TOOL_RES package	Oracle Procedure Builder

Developer's Guide

105500-105999	ORA_NLS package	Oracle Procedure Builder

Developer's Guide

300000-300499	DEBUG package	Oracle Procedure Builder

Developer's Guide

300500-300999	LIST package	Oracle Procedure Builder

Developer's Guide

302000-302499	TOOL_ERR package	Oracle Procedure Builder

Developer's Guide

302500-302999	TEXT_IO package	Oracle Procedure Builder

Developer's Guide

OG-00801:	Data query execution error

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00802:	SQL query execution error

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-00901:	Invalid parameter name entered

 Cause:	You typed an invalid parameter name in the Name column of the Parameter Table.

 Action:	Use a valid parameter name.

OG-00902:	Invalid parameter type entered

 Cause:	You typed an invalid parameter type in the Type column of the Parameter Table.

 Action:	Type one of the following valid parameter types: CHAR, DATE, or NUMBER.

OG-00903:	Invalid parameter value entered

 Cause:	You typed an invalid parameter value in the Value column of the Parameter Table.

 Action:	Type a value that is valid for the parameter type you specified.

OG-01001:	Unable to find expected resource.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01002:	Unable to find expected resource.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01103:	High-level sound dialog failed

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01105:	Unable to load display

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01106:	Record cache read initialization failure

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01107:	Sound conversion failed

 Cause:	You tried to import or create a sound, but the conversion of the sound from its original sample rate and encoding scheme failed.  This is most likely to happen if your sound is too large.

 Action:	Import or create a smaller sound.

OG-01108:	Unable to read from sound import file

 Cause:	You tried to import a sound, but the file to be imported does not contain valid sound data.

 Action:	Verify that the file contains valid sound data.

OG-01109:	Could not create cursor.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01110:	Could not find printer.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01301:	Unable to open data file

 Cause:	You tried to execute a query that retrieves its data from a file, but Graphics Builder could not open the file.  The possible causes of this error include:

A.	The file does not exist.

B.	You do not have the necessary privileges to open the file.

C.	A system error prevented Graphics Builder from opening the file.

 Action:	You can take the following action(s) to correct this error:

If A.	Create the necessary file.

If B.	Change-or have your system administrator change-your privileges accordingly.

If C.	Consult your system documentation or contact your system administrator.

OG-01304:	Unable to create cache for data.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01305:	Invalid SYLK data file format

 Cause:	You defined a query to reference a SYLK file, but the specified file is not in that format.

 Action:	Verify that you specified the correct format and file.

OG-01306:	Invalid PRN data file format

 Cause:	You defined a query to reference a PRN file, but the specified file is not in that format.

 Action:	Verify that you specified the correct format and file.

OG-01307:	Invalid WKS data file format

 Cause:	You defined a query to reference a WKS file, but the specified file is not in that format.

 Action:	Verify that you specified the correct format and file.

OG-01601:	Unable to create cax at startup

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01603:	Unable to create DE context

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01604:	Unable to create DE UI context

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01605:	Unable to create main layout window

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01606:	Unable to startup resource manager

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01607:	Unable to init ZOM.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01610:	Unable to create PL/SQL batch compiler

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01613:	Unable to create PL/SQL editor window

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01614:	PL/SQL program unit creation failed

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01615:	Unable to create DE execution context

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01616:	Unable to create cav at startup

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01617:	Unable to create non-modal interpreter

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01618:	Unable to create modal interpreter

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01619:	Could not initialize error handler

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01620:	Could not initialize object store

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01621:	Could not initialize Oracle Image

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01622:	Could not initialize Oracle Sound

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01623:	Could not initialize Oracle Help

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01625:	Could not set batch window attributes

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01626:	Too many arguments for command line option

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01627:	Duplicate specification for command line option

 Cause:	You invoked a Graphics Builder executable from a command line and passed it command line arguments, but you used the same command line keyword more than once.

 Action:	You can specify a command line keyword no more than once in a single command line.  To specify multiple values for a keyword, use a value list.

For more information, see "Value Lists" in the chapter "Executables" of the Graphics Builder Reference Manual.

OG-01629:	Positional input after command line keyword

 Cause:	You invoked a Graphics Builder executable from a command line and specified a keyword and its value, followed by a value with no keyword.

 Action:	If you use a keyword on a command line, you must use keywords in all subsequent command line arguments.  You may omit keywords only if their values are listed in the order specified by the executable's syntax, and if they do not follow another command line argument that explicitly uses its keyword.

OG-01630:	Invalid value for command line option

 Cause:	You invoked a Graphics Builder executable from a command line and specified an invalid value for a command line keyword.

 Action:	You must specify valid command line values.

For more information, see "Value Lists" in the chapter "Executables" of the Graphics Builder Reference Manual.

OG-01631:	Improperly-formed list in command line

 Cause:	You invoked a Graphics Builder executable from a command line and specified multiple values for a command line keyword; however, the value list is improperly formed.

 Action:	You must surround a value list with parentheses, and place a comma between each value.  Note that your system may have special restrictions on using parentheses and commas on a command line.

For more information, see "Value Lists" in the chapter "Executables" of the Graphics Builder Reference Manual.

OG-01632:	Illegal list input in command line

 Cause:	You specified a list of values for an executable keyword for which multiple values are not allowed.

 Action:	Do not specify multiple values for keywords that accept only one value.

OG-01633:	Command file not found

 Cause:	Graphics Builder could not find the command file specified by the CMDFILE executable keyword.

 Action:	Verify that the file exists and is in a readable format.

OG-01635:	Could not create PL/SQL browser

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01636:	Could not create library browser

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01638:	SQLLIB initialization failed

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01639:	Tools integration initialization failed

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01640:	Unable to create data table window

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01641:	Unable to create parameter table window

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01643:	Unable to create chart template window.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01644:	Unable to create data table window.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01642:	Unable to create chart template window

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01901:	Generic object store error

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01902:	Cannot find layer to be saved.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01903:	Unexpected empty layer list in layout view

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01904:	Could not open the database store

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-01905:	Cannot fetch user name.

 Cause:	Graphics Builder encountered an error while trying to resolve an unknown or unspecified username by requesting resolution from the server.  For example, if you do not enter a username in the Connect dialog box, Graphics Builder asks the server to resolve an OPS$ username.

 Action:	Verify that the username is registered and appears in the USER_USERS table.

OG-02205:	These objects do not belong to the same group.

 Cause:	You tried to simultaneously select two objects that are not children of the same group object.

 Action:	You can select multiple objects only if they are members of the same group.

OG-02207:	Must select exactly one group.

 Cause:	You selected one or more single objects, or more than one group object, and then attempted to ungroup, select the children, or an an object to a group.

 Action:	These operations require that exactly one group object be selected.

OG-02212:	Object selected is not a group.

 Cause:	You selected a single object, then attempted to selecte its children.

 Action:	By definition, a single object has no children.  This operation requires that you select exactly one group object.

OG-02213:	Object has no parent.

 Cause:	You selected an object, then attempted to select its parent, but the object is not a member of a group, and therefore has no parent.

 Action:	You can select the parent only of an object that is a member of a group.

OG-02215:	Object is not editable

 Cause:	You selected the Reshape tool, then selected a control point of an object that cannot be reshaped.

 Action:	You cannot reshape a symbol, chart, or group object.

OG-02313:	Select exactly one image to export.

 Cause:	You tried to export an image, but there are either no images or more than one image selected.

 Action:	Select only one image to export.

OG-02502:	Cannot find file or cannot read file.

 Cause:	You tried to open a file, but Graphics Builder could not find or read the file.  The possible causes of this error include:

A.	The file does not exist.

B.	You do not have the necessary privileges to open the file.

C.	A system error prevented Graphics Builder from opening the file.

 Action:	You can take the following action(s) to correct this error:

If A.	Create the necessary file.

If B.	Change-or have your system administrator change-your privileges accordingly.

If C.	Consult your system documentation or contact your system administrator.

OG-02503:	Cannot open file for writing.

 Cause:	You tried to write to a file, but Graphics Builder encountered an error.  The possible causes of this error include:

A.	You do not have the necessary privileges to write to the file.

B.	A system error prevented Graphics Builder from writing the file.

 Action:	You can take the following action(s) to correct this error:

If A.	Change-or have your system administrator change-your privileges accordingly.

If B.	Consult your system documentation or contact your system administrator.

OG-02505:	Cannot open database store. Database may not be configured properly.

 Cause:	Graphics Builder encountered an error while trying to store a module in the database (e.g., save a display, export a drawing, etc.).

 Action:	Verify that you have the necessary access privileges to store data in the Graphics Builder tables.

OG-02506:	Cannot print.  Check printer settings.

 Cause:	Graphics Builder encountered an error while trying to print.

 Action:	Verify that your printer and printing environment are configured correctly.  For more information, refer to your system documentation.

OG-02507:	Cannot open file or file is not in the format specified.

 Cause:	You tried to import a file, but either Graphics Builder encountered an error while trying to open the file, or the file is not in the specified format.

 Action:	Verify that you can access the file, and that it is in the correct format.

OG-02508:	Cannot find document in database.

 Cause:	You tried to open a module that is stored in the database, but Graphics Builder could not find a module with that name.

 Action:	Verify that the module you specified exists in the database, and that the current user has the appropriate privileges.

OG-02701-2718:	Error while reading CGM file.

 Cause:	You tried to import a CGM file, but Graphics Builder encountered an error while trying to read it.  It is likely that the file is either damaged, or it is not a valid CGM file.

 Action:	Verify that the file is a valid CGM file.

OG-02801-2806:	File I/O error

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-03003:	Cannot display image.

 Cause:	You are attempting to open a display containing an image within the Builder, but you do not have sufficient memory to display the image.

 Action:	Save your display and quit Graphics Builder, then, if possible, free up memory and try again.  For information on memory requirements, see the Graphics Builder documentation for your operating system.

OG-03101:	Oracle Toolkit error

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-03501:	Cannot find resource file.  Check your environment settings.

 Cause:	Graphics Builder could not locate a necessary resource file.

 Action:	Verify that your environment settings are correct.  For more information, see the Graphics Builder documentation for your operating system.

OG-03507:	Cannot find color palette file.  Check your environment settings.

 Cause:	Graphics Builder could not locate the default color palette file named vgid.ros.

 Action:	Verify that your environment settings are correct.  For more information, see the Graphics Builder documentation for your operating system.

OG-03701-3702:	Not enough memory.

 Cause:	Graphics Builder ran out of memory.

 Action:	Save your display and quit Graphics Builder.  For information on memory requirements, see the Graphics Builder documentation for your operating system.

OG-03704:	Object store error.

 Cause:	This is an abnormal condition.

 Action:	For more information, see Abnormal Conditions.

OG-03800-3812:	Could not write CGM file.

 Cause:	You tried to export a drawing as CGM, but Graphics Builder encountered an error.  The possible causes of this error include:

A.	You do not have the necessary privileges to write to the file.

B.	A system error prevented Graphics Builder from writing the file.

 Action:	You can take the following action(s) to correct this error:

 	If A.	Change-or have your system administrator change-your privileges accordingly.

If B.	Consult your system documentation or contact your system administrator.

OG-04001:	Field template not found in chart template

Cause:	Corrupted template.

Action:	Update or recreate the chart.

OG-04002:	Column not found in query data.

 Cause:	You created a chart based on a query that contained certain data columns, then you changed the query such that one or more of those columns were no longer present.  When you tried to update the chart, it looked for those columns, but couldn't find them.

 Action:	Update the chart's field mapping so that it plots only columns that exist in the query.

OG-04003:	User-specified axis minimum/maximum/step is invalid.

 Cause:	You entered a Minimum axis value that is greater than the Maximum value.

 Action:	Enter a Minimum value that is less than the Maximum, or select Auto for one or both values.

OG-04004:	Column data type invalid for corresponding axis.

Cause:	Data type specified in Chart->Axis Properties does not

match with actual data type.

Action:	Verify data type of plotting data and axis property.

OG-04005:	Cannot plot negative value in stacked data.

 Cause:	The Plot Position of a field in the chart is set to Stacked, but the query contains negative data.

 Action:	You can plot only positive data values in a Stacked chart.

OG-04006:	Cannot plot negative or zero data in log chart.

 Cause:	You created an axis chart in which one of the axes uses a logarithmic scale, but the field that maps to that axis contains negative data values.

 Action:	You can plot only positive data values in along a logarithmic axis.

OG-04007:	Cannot plot negative data in percent chart.

 Cause:	The query on which a percent chart is based contains negative data values.

 Action:	You can plot only positive data values in a percent chart.

OG-04008:	Zero sum/minimum/maximum in percent chart.

 Cause:	You created a chart whose data values are plotted as a percentage of the sum/minimum/maximum of all data values, but the sum/minimum/maximum is zero.

 Action:	A percentage cannot be computed if the sum/minimum/maximum is zero.

OG-04010:	Cannot plot negative data in pie chart.

 Cause:	The query on which a pie chart is based contains negative data values.

 Action:	You can plot only positive data values in a pie chart.

OG-04011:	Sum of data greater than total value specified.

 Cause:	You specified a Total Value for the pie chart that is less than the query's actual sum of data.

 Action:	Set the Total Value for the pie chart to be greater than or equal to the actual sum of data returned by the query.

OG-04012:	Data overflow:: try a different axis precision.

 Cause:	You created or updated a chart that contains a date axis, but the range of its data is too big.   For example, if the data spans many years, and the axis step size is seconds, this error occurs.

 Action:	Set the axis step size to a larger unit, resulting in fewer subdivisions of the axis.

OG-04013:	Legend columns cannot be zero.

 Cause:	You set the number of columns that appear in the legend to 0.

 Action:	Set the number of columns that appear in the legend to at least 1.

OG-04014:	No data available to chart.

 Cause:	You tried to update a chart whose associated query has not been executed.  This can happen if the query references the database, but the database is not connected, or if a SYLK, WKS, or PRN file cannot be found.

 Action:	Verify the database is connected or the file exists.

OG-04015:	Too many rows of data.

 Cause:	You tried to execute a query, but the query returned more rows of data than Graphics Builder can process on your system.

 Action:	Limit your query so that fewer rows are returned.


Graphics Frequently Asked Questions
 Graphics Builder Frequently Asked Questions

For Building Charts

For PL/SQL

For Debugging

For Performance

For Integration

For General Design


 For Building Charts

How do I get the chart to update properly?

Can I reuse settings from one chart to create another chart?

How do I customize the colors of my pie chart?

When I import a drawing into Graphics Builder, why can't I select any objects?

How do I remove the legend?

Is there some way of exporting a layout as an image?

Can I rotate the labels?

How do I make the edges of objects look 3-D?

How do I select a tool so that it stays selected?

How do I scale the text?

How do I edit my color palette?

How do I modify my default labels?


How do I get the chart to update properly?

When I create a display with a chart and run it, the display doesn't show any runtime data.  It only shows the data I got the last time I saved from the Graphics Builder Designer.  How do I get it to update properly?

Make sure that Update Chart on Query Execution is checked on the Data page of the Chart Properties dialog.  Also make sure that Execute on Opening Display is checked on the Data page of the Query Properties dialog.


Can I reuse settings from one chart to create another chart?

If I create a chart that I’d like to reuse with minor modifications, what’s the best way to do it?

All charts are based upon chart templates.  When you select the type and subtype for a chart you are creating, you are actually selecting one of the over fifty default chart templates provided by Graphics Builder, which then creates a copy of it for your chart.

Although you can’t modify the default templates provided, you can modify the copy created during chart creation and save it as a customized chart template.  To do so, edit the chart template in the Chart Template editor.


How do I customize the colors of my pie chart?

I want to have control over the colors of my pie chart, but Graphics Builder seems to be choosing all the colors for me except the initial one.  Is there a way I can do this?

This coloring cannot be set in the designer.  You can, however,  programmatically loop through the data and modify the associated pie slice, changing the color, fill pattern, etc.  You might want to look at the name_the_bars procedure listed in various places throughout the Graphics Builder Reference (for example, p.316) for a related example.

Another option is to use the Graphics Builder Reusable Component called color ramp by attaching the PL/SQL library colorrmp.pll.  For more information, see the Graphics Builder Reusable Component help.


When I import a drawing into Graphics, why can't I select any objects?
When I import a drawing into Graphics Builder, why can't I select any objects?

When I import a drawing into Graphics Builder, and select the drawing on the layout, why can't I select any of the objects?

When you use Edit [image] Import [image] Drawing, your new drawing is not imported into your current layer.  Graphics Builder automatically creates a new layer for your drawing.  Use the Arrange [image] Layers dialog to activate your newly imported layer.


How do I remove the legend?

If I want to create a chart without a legend, how do I delete the legend created by default?

Deselect the Show Legend checkbox on the Frame property sheet.  (This can be reached via either the right mouse menu or the Chart menu.)


Is there some way of exporting a layout as an image?

I’d like to include an image of my chart in a web page.  How do I export the layout of my chart to an image?

You have three options for exporting your chart’s layout to an image.  You can do so on the command line, using the command line option exportimage, as follows:

g25run openfile=c:\test.ogd
userid=scott/tiger
exportimage=c:\test.gif quit=yes

This runs the display and exports the layout, including charted data, to the GIF file test.gif.

The same can be done using the Export Image dialog reached via Edit [image] Export [image] Image.

Finally, Graphics Builder provides the OG_EXPORT_IMAGE built-in subprogram for the same purpose.  For example:

og_export_image(‘C:\test.gif’, OG_FILESYSTEM, OG_GIF_IFORMAT, og_root_object, OG_LZWHDIFF_ICOMPRESSION);

This statement also sets compression type.


Can I rotate the labels?

If I’d like to change the orientation of my labels, can I?

Yes, using the following trigger:

PROCEDURE Rotate_Label(chartname   VarChar2, labelname    VarChar2,  rotationangle    Number) IS
axislabel	og_object;
theoffset	og_point

BEGIN

axislabel := og_get_object(labelname);
og_set_horigin(axislabel, OG_CENTER_HORIGEN, false, false);
og_rotate(axislabel, og_get_origin(axislabel), rotationangle, false, false);
og_draw(og_get_object(chartname);

END

--Updating chart will invalidate label rotation!!!
--Call this procedure after you have updated the chart.
--Rotation angle is clockwise.

You must execute this trigger after all other operations, including updating the chart.  (However, if you use a Graphics Builder Reusable Component, or register one of your .ogd files as a Reusable Component, any modifications to the display taking place after chart update will be preserved.)


How do I make the edges of objects look 3-D?

I’d like the objects in my display to look raised or depressed.  How do I do that?

Select the object or objects in the layout, then select Format [image] Bevel and select how you want your edge to look:  raised, lowered, with an inset bevel, or with an outset bevel.  If the bevel isn’t immediately apparent, the edge of your object might be too narrow to show it effectively.  Select Format [image] Line and choose a greater width for the object’s edge.


How do I select a tool so that it stays selected?

If I want to draw several instances of one type of object--say, circles, or rectangles--in my layout, how do I keep that tool from reverting back to the Select tool after I draw each object?

If you double-click on a tool when initially selecting it, you will note that the tool icon in the tool palette appears to remain depressed, and the image of a push pin seems to be holding it down.  This means you have activated the mode for that tool, and it will remain selected until you select another tool.


How do I scale the text?

I’d like to be able to just drag my text objects out to the proper size.  Can I do this?

Under Format [image] Drawing Options, select Text… and in the Text Drawing Options dialog, select Scalable Fonts.  This will enable you to scale the text in your text objects.


How do I edit my color palette?

I don’t like the colors in my color palette.  How do I change them or use a new one?

To change the colors in your color palette, select Tools [image] Tools Options… and on the Default page, under Color Palette select a Mode of Editable.  Save your new preference.  You will need to close and reopen your  display for this new preference to take effect.  Then you can select Format [image] Color Palette, and create your own custom colors for the default Graphics Builder color palette.

If you’d like to use a different color palette, Graphics Builder provides several, including a gray-scale palette, a VGA palette, and a 16-color VGA palette.  After making sure that your color palette is editable, as explained above, simply select Edit [image] Import [image] Color Palette, and use the Import dialog to chose a .pal or color palette file.  For the exact location of the available color palette files, see your Installation and User’s Guide.


How do I modify my default labels?

I’d like to add a percentage symbol to my pie chart labels.  How do I do it?

To add a percentage symbol to your pie chart labels, simply attach a format trigger to the pie chart label group.  For example:

--Chart Element format trigger.
--Called for each member of a
--specified chart element group.
--Arguments:
--	ELEM	The current chart element.
--	QUERY	The query associated with
--	this chart.  The current row
--	of the query is the one
--	associated with ELEM.
--	Use OG_GET_xxxCELL to get at
--	column values for the current row.

PROCEDURE FTRIG(elem IN og_object, query IN og_query) IS

BEGIN

og_set_str(elem, og_get_str(elem, 0, 0) || ‘%’);

END

Use this method to modify chart labels as desired.


 For PL/SQL

Why does my display contain a button when I didn't define one?

How do I handle PL/SQL exceptions?

Is there some way of exporting a layout as an image?

Can I update information in the database from Graphics Builder?

Can I explode a pie slice?


Why does my display contain a button when I didn't define one?

When generating my display, I get an error like "Procedure 'my_buttonproc' associated with object 'my_button' must have exactly four parameters."  Why?

If you associate a procedure with an object that object becomes a button that fires the procedure when selected.  Graphics Builder automatically passes four arguments to the procedure when called, including the handle to the object that was activated.  If the procedure is not defined to accept four arguments, you will get this consistency error when generating.

The easy solution to this is to make sure that when you define a button procedure you start its definition by choosing File [image] New Button instead of starting the procedure from scratch.  By doing this, Graphics Builder will give you the four default arguments and their datatypes; then all you need to do is modify the procedure's name and body.


How do I handle PL/SQL exceptions?

I'm getting an "OG-637: Unhandled PL/SQL exception error 102003" when executing a procedure to update my chart.  What does it mean?

The OG-637 error is a generic error which is raised by a number of PL/SQL or ORACLE errors.  Refer to Graphics Builder Built-in Exceptions for a description of what the 6-digit error numbers represent; the description should be more clear as to why the error occurs.


Can I update information in the database from Graphics?
Can I update information in the database from Graphics Builder?

I’d like to actually commit changes to the database from within Graphics Builder.  Is there any way I can do this?

Yes, in PL/SQL procedures associated with the display.  You can execute DML statements from within your PL/SQL program units, and also execute DDL statements using the DO_SQL built in procedure.


Can I explode a pie slice?

If I want to place particular emphasis on one slice in a pie chart, how do I detach it from the rest of the pie?

You can use a PL/SQL procedure to explode a pie slice.  To do so, take the following steps:

1. 	In the Chart Properties dialog, go to the Data page and make sure “Update on query execution” is 	deselected.

2. 	Select Tools [image] Display and select the New button to the right of the Open Trigger drop-down list.

3. 	Enter the body of the procedure which will explode the pie slice.  For example:

PROCEDURE explode IS
pie	OG_OBJECT;
pieq	OG_QUERY;
mrows	NUMBER;
msal	NUMBER;
csal	NUMBER;
rowsq	NUMBER;

BEGIN
--Assign initial variable values
msal := 0;
mrows :=0;
pie := OG_GET_OBJECT (‘sal_chart’);
pieq := OG_GET_QUERY (‘query0’);
--Where ‘sal_chart’ is the name of the chart and
--and where ‘query0’ is the name of the query.

--Execute the chart query to get new data.
OG_EXECUTE_QUERY(pieq);

--Count the number of rows returned by the query
rowsq := OG_NUMROWS(pieq, OG_NEWDATA);

--Determine the maximum value by looping through the query rows
OG_START_FROM(pieq, OG_NEWDATA, 0);
FOR I IN 0 .. rowsq -1 LOOP
csal := OG_GET_NUMCELL (peiq, OG_NEWDATA, ‘sal’);
IF csal > msal THEN
msal := csal;
mrows := i;
END IF;
OG_NEXT_ROW(pieq, OG_NEWDATA);
END LOOP;

--Set the pie explosion
OG_SET_EXPLOSION(pie, OG_ALL_CHUPDA);

--Update the chart

OG_UPDATE_CHART(pie, OG_ALL_CHUPDA);

END;

4. 	Compile the trigger and close the Program Unit editor.

You can also use the Graphics Builder Reusable Component called pie explosion  by attaching the PL/SQL library explode.pll.  For more information, see the Graphics Builder Reusable Component help.


 For Debugging

How can I get a listing of the PL/SQL in my display?

How can I save changes to PL/SQL made during runtime simulation?


How can I get a listing of the PL/SQL in my display?

How can I get a text file that has a source code listing for all the PL/SQL program units in my Graphics Builder display?

You can do this by running the display from within Graphics Builder Designer and invoking the PL/SQL Interpreter.  At the PL/SQL prompt type the command

export prog * file <my_text_file>


How can I save changes to PL/SQL made during runtime simulation?

If I’m testing a display and see changes I need to make to a procedure, how can I make the change right then and there and then make sure the change also takes effect in the design-time version of the procedure?

You can either CUT/COPY/PASTE the source text between the runtime simulation program units and the design time program units or you can invoke the PL/SQL Interpreter from runtime simulation and type the command:

og_save_display;

Please note: This command will write out everything in your current runtime simulation state.  Current changes to the graphical objects in your display will be saved as well.  Thus, the next time you invoke your display, objects might not be in their original initial state.  From your current designer session, you will need to choose File [image] Revert to pick up the changes.


 For Performance

How can I improve the performance of an embedded display?

Should I use attached libraries, or local PL/SQL?

Where should I store my PL/SQL program units?

What if my display charts a large number of data points?

When should I use DO_SQL?


What's the best way to maximize Graphics performance?

The best way to maximize Graphics performance is by monitoring the damage and update flags that are the last two arguments to most Graphics PL/SQL built-ins.  By default, these flags are set to TRUE, and redrawing occurs every time the Graphics display list is modified.  To improve performance, make sure that your PL/SQL program units (including button  procedures, triggers, etc.) update the display only once.  For example, consider the following code example:

Begin

   for i in 1 .. 100 loop

     og_set_fillcolor(og_get_object('obj' || to_char(i)),
        'red');

   end loop;

End;

To improve performance, you could modify the code as follows:

Begin

   for i in 1 .. 100 loop

     og_set_fillcolor(og_get_object('obj' || to_char(i)),
        'red', false, false);

   end loop;

   og_draw(og_root_object);

End;

In this example, no portion of the screen is updated until the end of the procedure.

This technique makes significant performance improvements in displays in which several objects are created or destroyed on the fly at runtime, or in those that make use of a lot of PL/SQL code.  (Remember that a three line loop can contain a lot of code.)

How can I improve the performance of an embedded display?

What steps can I take to improve the performance of a display embedded in a form or a report?

In general, to ensure that your display executes as efficiently as possible when it is called from a form or a report, try to use as many common elements as possible in the initial design of both the form and the display.  For example, when charting data already fetched by Forms, pass the same data to the display in record groups instead of having the display re-query the database.  Use the same color palette in your form and in your display.  Make the same fonts available.

Another option for improving the performance of any display is to make sure that your PL/SQL program units (including button procedures, triggers, etc.) only update the chart once.  To do so, make sure that each time the damage flag and the bounding box are set to TRUE, you reset them to FALSE, then only execute a single OG_UPDATE_CHART and a OG_DRAW as the last actions.

For more information on improving the performance of Graphics Builder, see the following section:

What's the best way to maximize Graphics performance?

For more information on the damage flag and the bounding box, see the following sections:

Using the Damage Flag

Using the Bounding Box Update Flag


Should I use attached libraries, or local PL/SQL?

Should my PL/SQL remain external to my display?

Whenever possible, include PL/SQL in libraries attached to your display, instead of using PL/SQL that is local to the display.

The program units contained in external libraries can be used by any number of documents, including displays, forms, and reports, while local program units can only be accessed by the documents to which they belong.

In addition, local program units load when the document is opened, whether they are executed or not.  Libraries are only loaded when called.


Where should I store my PL/SQL program units?

Is it better to store program units on the client, or on the server?

The performance of some procedures can be improved by locating them on the client; others function more efficiently when stored on the server.  For information on determining the best place to store a particular procedure, see the Procedure Builder documentation.


What if my display charts a large number of data points?

How can I offset a performance degradation in my display if it has to chart a large number of data points?

While Graphics Builder has no built-in limit to the number of points it can plot in a display, practical considerations offer some guidelines.  Your machine may not have sufficient memory to plot large numbers of points in a reasonable amount of time.

One strategy for circumventing this problem is to plot only a subset of all points at any one time and design the display so that the user can either scroll the display or select and drill down on currently plotted points to access more information.


When should I use DO_SQL?

If I want to add DDL or DML to a display, do I need DO_SQL?

Use the packaged procedure DO_SQL only when necessary.  It’s necessary if you want to execute DDL statements, since PL/SQL will not do so, but if you want to use DML in your display, you can include them within program units.

While DO_SQL enables you to add any DDL or DML operation to your display--a very valuable function indeed--it can be very expensive if used unwisely.  Just like a query, a DO_SQL statement is parsed, opens a cursor to the database, and executes.  Unlike a query, however, a DO_SQL statement will execute each time its owner (e.g., a break) fetches data.  (For example, if your DO_SQL statement is owned by a break that fetches 10 records, the statement will be parsed 10 times, 10 cursors will be opened, and the statement will be executed 10 times.)


 For Integration

How do I use record groups to pass data from Forms to Graphics Builder?

How do I shut down Graphics Builder Batch from Forms?

When my chart is embedded in a form, why does it appear clipped?

Why can't Graphics Builder find the display I want to open from Forms?

Why isn't the display embedded in my form updating?

I can't get my display to appear in my report.  What's wrong?


How do I use record groups to pass data from Forms to Graphics?
How do I use record groups to pass data from Forms to Graphics Builder?

I'd like to pass a record group into Graphics Builder and have the chart be based on the data in the group.  But I'm unclear as to how to do this.

The key to this is to make sure the name of the parameter being passed in is the same as the name of the query in the display.  Make sure you call Graphics Builder via RUN_PRODUCT in SYNCHRONOUS mode (you can't pass record groups otherwise) passing in that parameter list as an argument.  Be sure you follow the steps detailed in the question above to re-execute the query and update the chart.  For an example of this type of Forms trigger please refer to the Forms User's Guide.


How do I shut down Graphics Batch from Forms?
How do I shut down Graphics Builder Batch from Forms?

When I start up Graphics Builder from Forms, the Graphics Builder batchmode icon appears on my Windows desktop.  Even after I exit my Form, that icon still remains.  Is there anyway of getting rid of it automatically?

To optimize performance, the Graphics Builder batch process stays active once it is called from Forms.  This is the default behavior. Otherwise, the user would have to wait for Graphics Builder to start up every time a chart is updated from within Forms.  If you want to shutdown Graphics Builder when you exit your form, you can write a Post-Form trigger that explicitly shuts down the Graphics Builder batchmode process.

declare

pl paramlist;

begin

pl := create_parameter_list('paramlist');

add_parameter(pl, 'oracle_shutdown', text_parameter, 'YES');

run_product(graphics, '<your_display_name>',

synchronous, batch, filesystem,

pl, '<chart_item_name>);

destroy_parameter_list(pl);

end;


When my chart is embedded in a form, why does it appear clipped?

If I embed a chart in a form and then run the form, often my display won’t look right.  How do I fix it?

By default, the call to OG.OPEN that starts Graphics Builder and opens your display clips the display to fit into the area you define for it in the chart.  You have two choices – you can scale the display by specifying

clip=no

in your initial call, or you can resize the chart object you’ve created in the form to more closely match the actual size of the display.


Why can't Graphics find the display I want to open from Forms?
Why can't Graphics Builder find the display I want to open from Forms?

When I create a chart object in a form and specify the display to open in my call to OG.OPEN, Graphics Builder still can’t find it.  Why?

You need to make sure that your .ogd file is located in the directory specified by the Graphics Builder path environment variable (not the Forms path environment variable).  The name of this environment variable varies according to platform, so check your platform-specific Graphics Builder documentation.


Why isn't the display embedded in my form updating?

If I run a form with an embedded display, then close the form and run it again, even though the data has changed the display hasn’t updated.  Why is this?

Closing a form and exiting Forms runtime does not automatically close Graphics Builder batchmode, which is the Graphics Builder executable called to run displays embedded in forms.  As long as the same session of Graphics Builder batchmode remains open, it will continue to run the same iteration of the display, using the same data.  To make sure you close Graphics Builder batchmode when you exit Forms, include, in a Forms trigger, a call to OG.CLOSE closing your display.


I can't get my display to appear in my report.  What's wrong?

Even though I’m creating a chart display item in my report layout and associating it to a display, my chart does not appear in my report and I get an error.  What’s going on?

You may have associated a display with your report, but you may have neglected to make a one-to-one correspondence between report columns and chart columns.


 For General Design

Can I create applications with native controls?

Related Publications


Can I create applications with native controls?

Will Graphics Builder allow me to create applications with native controls such as push buttons, menus, pop-lists, etc.?

No.  However, by using Forms 4.5 and embedding Graphics Builder objects such as charts or diagrams, you can achieve the desired application.


Related Publications

Books

Oracle PL/SQL Programming by Steven Feuerstein, O’Reilly and Associates, Inc.

800-998-9938, (707) 829-0515

http://www.ora.com

Learning Oracle Forms 4.5 by Stephen Edelstein, Relationship Business Systems

(212) 956-3670

74160.645@compuserve.com

Mastering Oracle in Client Server Computing by Steve Bobrowski, Sybex

Journals

Oracle Technical Journal (OTJ), Miller Freeman

pchapnickel@nfi.com


Select Data Tables dialog box

  Related Topics

Description  The Select Data Tables dialog box enables you to include datasource objects from the connected database into your query.

This dialog box contains:

Show	Specifies whether or not to display tables, views, queries, snapshots, and/or synonyms in the list box.
Drop-down box	Specifies from which datasource to display the objects.  You can also select a table from a separate account or database .
Select Data Tables	Lists the available datasource objects you can include in your query.  Tip
Info	Displays information on the selected object:  the kind, name, owner, date it was created, and comments.
Include	Includes the selected item into the Query Builder workspace.
Close	Closes the dialog box without including a datasource object.


Accessing other accounts in the current database

  Related Topics

To access tables in other accounts in the current database:

1	Click the current database name.  The Include button becomes an Open button, and the list box displays a list of accounts in the current database.

2	Click the name of the account you want to open.

3	Click Open, or simply double-click the account name.  Query Builder displays a list of tables in that account, and the Open button again becomes the Include button, enabling you to include tables in the usual manner.


Opening other accounts

  Related Topics

If the table you want is not listed in the current database, you can navigate to other accounts and databases and select tables from those accounts.

To navigate to other accounts and databases:

1	Click the box above the list of tables.  You will see two selections:  the name of the current database and the word Databases.

2	To access tables in other accounts in the current database, click here.

If you are unable to connect to a listed database, it may be due to an invalid link caused by a network problem or a changed remote password.  Contact your database administrator for assistance.


Including a table more than once

  Related Topics

If you include the same table more than once in a query, duplicate tables are automatically assigned system-generated alias names composed of the name for the base table, followed by an underscore and an alphanumeric sequence.


Select Related Tables dialog box

Description  The Select Related Tables dialog box enables you to include tables that are related to the selected table in the Query window.

This dialog box contains:

Show	This option is not available.
Drop-down box	Specifies whether or not to display all related tables.
Select Data Tables	Lists the available related tables.  Tip
Info	Displays information on the selected table:  the kind, name, owner, date it was created, and comments.
Include	Includes the selected table.
Close	Closes the dialog box without including a related table.


Rename Table dialog box

  Related Topics

Description  The Rename Table dialog box enables you to rename the currently active table.

This dialog box contains:

Default Table Name	Specifies the current name of the table.
List box	Lists the tables you have open to rename.
New Name	Specifies the new table name.
Define	Updates the table name while keeping the dialog box open.


Identifying a renamed table

In a stored query, it is not immediately apparent whether a particular table has a user-defined name or its original name.

To find out if a particular table has been renamed:

1	Click [image] in the Icon bar.

2	Click the table in question in the list of Available Tables.

If the table has been renamed, the alias name appears in the New Name: field and a different name (the original table name) in the Default Table Name: field.

SQL users can also identify renamed tables by clicking [image] in the Icon bar. This brings up the Show SQL dialog box, where any name changes appear in the SELECT statement in standard SQL syntax for table aliases.


Set Relationship dialog box

  Related Topics

Description  The Set Relationship dialog box enables you to create simple, self, composite, unmatched, and non-equal relationships between two tables.

This dialog box contains:

Relationship	Specifies the origin (in A->) and target (in B->) column names.
Operator	Specifies the type of relationship between the columns.
Use Relationship in Query	Specifies if your relationship will be used in the query.  Default is checked.
A not found in B radio button	Specifies that the data retrieved is all data common to both tables, in addition to data that is in table A, but not in table B.
B not found in A radio button	Specifies that the data retrieved is all data common to both tables, in addition to data that is in table B, but not in table A.
Suppress Mismatches radio button	Default.  Specifies that the data retrieved is common for both tables.


About relationships

  Related Topics

A relational database consists of a number of related tables.  Each table is made up of columns (sometimes called fields) which are arranged vertically.  Each column has a name, and contains a unique type of data.

Relationships, or joins, define how a column in one table relates to a column in another table.  In many cases, the relationships you need are already defined in the database.  Relationships also reduce data redundancy.  Whenever there is a relationship between columns in different tables, you can use the tables together in a query.  Note

Related columns do not always share the same names.  You can always relate columns that share the same datatype, and in some instances you can relate columns of different datatypes, if the relationship makes sense.  For example, you can always relate a Number datatype column with a Character column, since a number can also be interpreted as a character.  In fact, almost any column (except long text columns) can be related to Character columns.

Relationships can be user-defined (temporary) or established in the underlying data dictionary  Relationships in the data dictionary automatically appear when you include related tables (tables that have a primary/foreign key relationship).  You do not have to do anything to use these relationships, since they are always valid.  These can be created or modified using the Schema Builder.

User-defined relationships are valid only for the query in which you create them.  Creating a user-defined relationship does not establish a corresponding permanent relationship in the underlying table.  The main difference between the two is that in the case of a user-defined relationship, you must draw the relationship line; in a relationship stored in the database, Query Builder draws it for you.

Note (Report Builder only):  Report Builder data links are not the same as Query Builder relationships.  Data links are created between two or more queries, where Query Builder relationships (or joins) are created within a single query.  For more information, see the Report Builder online help.


Activating and deactivating a relationship

  Related Topics

Relationships that you create using the mouse are automatically activated and deactivated as they are needed in a query.  Active relationships are displayed with a heavy black line; inactive relationships are shown as grey lines.

To manually activate a relationship using the mouse:

  Double-click an inactive relationship line.

To deactivate a relationship:

  Double-click the active relationship line.


Define Column dialog box

Description  The Define Column dialog box enables you to create a new column in your query based on values in another column. Defined columns appear in both the Datasource panel and the Results window.

This dialog box contains:

Defined Columns	Specifies the name of the column you want to create.
List box	Lists existing defined columns.
Defined as	Specifies the expression of the selected column.
Define	Applies the definition to the column.
Remove	Deletes the selected column.
Paste Column	Displays the Paste Column dialog box.
Paste Func	Displays the Paste Function dialog box.
Note:  The defined column is only a part of your query and will not modify the table definition saved in the database.


Sort dialog box

Description  The Sort dialog box enables you to sort the data in your query according to columns in your table.

This dialog box contains:

Available Columns	Lists the table columns you can sort in the Results window.
Sorted Columns	Lists the table columns that are currently sorted in the Results window.
Copy	Copies the selected column from the Available Columns list to the Sorted Columns list.
Remove	Removes the selected column from the Sorted Columns list.
Sorting Order	Sorts the selected column in Ascending or Descending order. Default is Ascending.


Query Builder Help

  Related Topics

Building a new query

Adding conditions to a query

Creating a simple relationship

Defining a column

Sorting query data


About Query Builder

  Related Topics

Query Builder is an easy-to-use data access tool designed for analysts, managers, and other business professionals.  It provides a logical and intuitive means to access information from your organization's databases for analysis and reporting.

Query Builder is designed for professionals who do not have a computer programming or database background.  Because of its powerful query features and its support of Structured Query Language (SQL) statements, experienced database users and programmers will find that Query Builder serves many of their needs as well.

In Query Builder's graphical Query window , you can specify a request for data from your organization's database(s).  The request for data is called a query.

You can use Query Builder to define almost any query that you would build using a SQL SELECT statement.  Query Builder automatically generates the appropriate SELECT FROM [table.column] clause based on columns displayed in the Query Builder workspace.


Column Sequence dialog box

Description  The Column Sequence dialog box enables you to adjust your query results in the Query Builder workspace.

This dialog box contains:

Available Columns	Lists the table columns you can display in the Query Builder workspace.  Tip
Displayed Columns	Lists the table columns that are currently displayed in the Query Builder workspace.
Copy	Copies the selected column from the Available Columns list to the Displayed Columns list.
Remove	Removes the selected column from the Displayed Columns list.
Format	Displays the Format dialog box.
Totals	Displays the Totals dialog box.
Execute	Runs the query.


Paste Column dialog box

  Related Topics

Description  The Paste Column dialog box enables you to paste an existing column from a selected table into your query.

This dialog box contains:

List box	Lists the columns you can paste.  Tip


Paste Function dialog box

Description  The Paste Function dialog box enables you to paste a function into your condition or query.

This dialog box contains:

Show Categories	Specifies the types of functions that display in the list box:  number, character, date, conversion, group, other.
List box	Lists the available functions under the selected category.
Paste Arguments	Specifies whether or not to include the argument (the expression within the parentheses of a function that supplies information for the function to use).


Show SQL dialog box

  Related Topics

The Show SQL dialog box displays the SQL statements for your query thus far. You cannot edit or copy the SQL statements in the Show SQL dialog box.


The column or columns that uniquely identify each row of a table.  Primary keys appear in bold.


A column that refers to the primary key values in another table. Foreign keys appear in italics.


The sources from which a query retrieves data, including tables, views, queries, synonyms, and snapshots.


A datasource made up of columns from one or more database tables combined into one logical table.


A string consisting of a function or operation and the database column(s) to be operated on (for example, SALARY+COMMISSION).


To conform to naming conventions, each query name must begin with a letter and can contain up to 30 letters and numbers.  If you don't use naming conventions when naming database queries, Query Builder will convert the name to a "literal" value (enclosed in double quotes).


About the Conditions panel

The Conditions panel is a section of the Query window that contains the Condition field, where you enter expressions and conditions.  Query Builder conditions automatically generate WHERE or HAVING clauses, as appropriate.

The table and column names indicate which columns will be filtered in the condition.  You may omit the table name if the column name is unique.  Tip

Note:  When you activate the Condition field, the cursor will have  a (+) sign, indicating that any item you click on will be added to your condition.  To deactivate this, you can click [image] in the Icon Bar.


About the Query window

When you open a query, Query Builder displays it in the Query window, split into two panels:

•	the Conditions panel, where the Condition field is located.  It is used to refine the query.

•	the Datasource panel, which displays the tables (views, snapshots, and so forth) used in the query.

Depending on your preferences, the panels may be split vertically or horizontally.

Each table is displayed in a box containing the name of the table and the names of columns in that table.  There are a number of icons that help identify the current database object.  The icons indicate whether descriptive comments are attached, the type of datasource, the column's datatype, and whether indexes have been defined for tables in the query.

Lines are drawn to indicate the relationships between columns.  Relationships are set up between tables to identify how a column in one table relates to a column in another table.

A check mark to the left of the column name indicates the column has been included in the query.  This means that Query Builder will search for data corresponding to the column name when you run the query.  No check mark indicates that column's data will not be included.


About the Datasource panel

  Related Topics

The Datasource panel is the section of the Query window where items, such as tables and relationships, display.


About the Icon Bar

  Related Topics

The Icon Bar displays at the top of the Query Builder window.  Click on each icon to view a description.


Save icon

Saves your query to the specified file.


Cut icon

Cuts the selected text and places it on your operating system's clipboard.


Copy icon

Copies the selected text onto your operating system's clipboard while the original text remains intact.


Paste icon

Pastes the current clipboard items into the active location.  If there is nothing on the clipboard, nothing will be pasted.  You can paste any text that you have cut or copied.


Clear icon

Removes the selected item (i.e., text, table).  Unlike the Cut command, Clear does not place the removed item(s) on your operating system's clipboard.


Select All icon

Selects every item in the active window.  For example, if the Conditions panel is active, all conditions in the panel will be selected.


Select Data Tables icon

Displays the Select Data Tables dialog box.


Select Related Tables icon

Displays the Select Related Tables dialog box.  This icon is available only when the table you have selected has a related table in the connected database.


Rename Table icon

Displays the Rename Table dialog box.  This icon is available only when there is at least one table in the Query Builder workspace.


Get Info icon

Displays the Info dialog box and information on the selected database object.  This icon is available only if a datasource object is active.


Set Table Relationship icon

Displays the Set Relationship dialog box.  This icon is available only when there is more than one table in the Datsource panel to relate.


Show SQL icon

Displays the Show SQL dialog box and the SQL for the active query.


Column Sequence icon

Displays the Display dialog box.


Define Column icon

Displays the Define Column dialog box.


Sort icon

Displays the Sort dialog box.


And icon

Inserts the AND operator into your condition.  This icon is available only when the Condition field is active.  You can also type AND directly into the Condition field.


Or icon

Inserts the OR operator into your condition.  This icon is available only when the Condition field is active.  You can also type OR directly into the Condition field.


Not icon

Inserts the NOT operator into your condition to negate your condition.  This icon is available only when the Condition field is active.  You can also type NOT directly into the Condition field.


Ungroup Conditions icon

Ungroups conditions that are combined with logical operators, such as AND, OR, NOT.  This icon is available only when you have selected a logical operator in the Conditions panel.


Accept icon

Validates and accepts the active condition.  This icon is available only when the Condition field is active.  You can also press the Enter or Return key when the Condition field is active to accept and validate your condition.


Cancel icon

Cancels the current condition.  This icon is available only when the Condition field is active.


Paste Column icon

Displays the Paste Column dialog box.  This icon is available only when the Condition field is active.


Paste Function icon

Displays the Paste Function dialog box.  This icon is available only when the Condition field is active.


About datatypes

  Related Topics

The most common datatypes in Query Builder are:

CHAR or VARCHAR2	CHAR is used for fixed length character data, to a maximum size of 255 bytes and a default size of 1 byte.  VARCHAR2 is for variable length character strings to a maximum size of 2000 bytes.  You must specify size for VARCHAR2.
NUMBER	NUMBER indicates that the database column contains numbers (integers, decimals, or any other type of numeric values).  You can perform calculations on numbers represented in the NUMBER datatype, but not on numbers represented by the CHAR datatype.
DATE	DATE indicates that the database column contains date values.  Valid dates ranging from January 1, 9999 BC to December 31, 9999 AD.  Default format is DD-MON-YY as in '01-JAN-92'.
NUMBER(p,s)	The range of p (decimal precision) is 1 to 38. The range of s (scale) is -84 to 127.  Decimal precision is the number of digits to store.  The scale is the number of digits to the right of the decimal point.  If the scale is negative, the actual data is rounded to the specified number of places to the left of the decimal point.  For example, a specification of (10, -2) means round to the hundreds.
Additionally, Query Builder provides limited support for the following Oracle datatypes:

LONG	A LONG column contains alphanumeric data of variable length up to 2 gigabytes (or 231-1).  When you include a LONG column in a Query Builder query, the first 2000 characters are displayed.
RAW	Raw binary data.  Maximum size is 255 bytes.  Values must be inserted as character strings in hexadecimal notation.  Values are displayed in hexadecimal.  You must specify size for RAW datatypes.
LONG RAW	LONG RAW displays raw binary data up to 2 gigabytes (this appears in hexadecimal in the Results window).  LONG RAW datatypes are subject to the same limits as RAW datatype.
Note:  Query Builder supports datatype conversions in cases where conditions and expressions reference different datatypes in their comparison.  Refer to the Oracle8 Server SQL Language Reference Manual for additional information.


Datatype icons

  Related Topics

The following supported datatypes for all the columns in a datasource object are represented by icons located in the right hand column of the object in the Query Builder workspace.

Datatype	Icon	Description
Character		Use the Character datatype for fixed length character data, to a maximum size of 255 bytes and a default size of 1 byte. Note:  You can represent numbers using the Character datatype, but you can only perform calculations with numeric datatypes.
Varchar2		Use the Varchar2 datatype for variable length character strings, to a maximum size of 2000 bytes.  You must specify a size for the Varchar2 datatype.
Number		Use the Number datatype for integer or floating data. You must enter a precision length (number of digits) for integer data. Floating datatype is for decimal numbers. When you assign this datatype to a column, you must specify both the precision and the scale. The precision (total number of digits in the number) can range from 1 to 38.  The scale (number of digits to the right of the decimal point) can range from -84 to 127.  If the scale is negative, the actual data is rounded to the specified number of places to the left of the decimal point.  For example, a specification of (10,2) means 10 digits with 2 to the right of the decimal point.  A specification of (10,-2) effectively means a 10-digit integer, rounded to the nearest hundred.
Date		Use the Date datatype for any type of date.  Valid dates range from January 1, 4712 BC to December 31,4712 AD.  The default date format is DD-MON-YY, as in ‘01-JAN-97.’
Long		Use the Long datatype for long text fields of alphanumeric data of variable length, up to 2 gigabytes.
Raw		Use the Raw datatype for raw binary data.  The maximum size is 255 bytes.  Values must be inserted as character strings in hexadecimal notation, and values are displayed in hexadecimal.  You must specify a size for raw data.
Long Raw		The Long Raw datatype is for storing up to 2 gigabytes of raw binary data (which is entered and displayed in hexidecimal form).  Long Raw datatypes do not require a specified size.
MLSLABEL		Use the MLSLABEL datatype for storing the binary format of a label used on a secure operating system.  Labels are used by Trusted ORACLE to mediate access to information.  You can also define columns with this datatype if you are using the standard ORACLE Server.  For more information on Trusted ORACLE, including this datatype and labels, see the Trusted ORACLE8 Server Administrator's Guide.


Datasource object notation

  Related Topics

Shown below is an example of two datasource objects, linked by a relationship.

Click any icon, indicator, or part of these objects to display a description.


Object type indicator

The icon in the upper left corner of any datasource object indicates its type:

  Table

  View

  Query

  Snapshot

  Synonym


Object title

This is the name of the datasource object.  You can change the name by clicking on the object title.


Comment indicator

This icon indicates that this object (or column) has a comment associated with it.  Double-click this icon to open the Info dialog box, where you can view the comments.


Column Name

This is the name of one of the columns in this object.  If you double-click a column name, the column will be included in your query.


Datatype indicators

These icons indicate the datatypes of their respective columns. If you click and hold on one of these icons, a pop-up menu appears, and you can choose a different datatype.


Relationship line

A gray line drawn between two columns indicates that a relationship has been created between the columns at either end of the line. The line is drawn from the foreign key to the primary key.


Self-relationship indicator

This icon indicates that a self-relationship has been created between this column (foreign key) and another column (primary key) in the same table.


Primary key

A column name displayed in boldface indicates that this column has been defined as a primary key for the object.


Foreign key

A column name displayed in italics indicates that this column is a foreign key, related to a primary key in another column.  Setting up a relationship between two columns is the only way to define a foreign key.


The Database Trigger editor interface

  Related Topics

The Database Trigger editor enables you to create and edit BEFORE/AFTER triggers for tables, and INSTEAD OF triggers for views and object views (if connected to Oracle8).

To define a new trigger:

1	Choose a user name (schema) from the Table Owner drop-down list.

2	Choose a table name from the Table: drop-down list.

The Table drop-down list shows a list of table names owned by the user shown in the Table Owner field.  If you select a user name other than your own in the Table Owner field, the Table drop-down list shows only the tables to which you have been granted access.

(For views only.) To define an INSTEAD OF trigger for an object view, click the arrow next to Table: to display a drop-down list and choose View:. Then choose a view name from the View drop-down list.

3	Click New to create a new database trigger.

A unique trigger name (with respect to other triggers in the same schema) is automatically assigned to the new trigger in the Name drop-down list.  You can modify the trigger name.

The Name drop-down list displays a list of trigger names associated with the table (or view) shown in the Table (or View) field.  The Name drop-down list displays only the names of the database triggers associated with the tables to which you have access.

4	Specify the trigger options.

The sections that follow provide information on the various options you can use in the Database Trigger editor to define a database trigger.

5	After specifying the trigger options and action, click Save to compile the trigger.

Triggering options:

Before/After	(For tables only.) Corresponds to the BEFORE or AFTER option of the SQL command CREATE TRIGGER. Indicates when the trigger body is fired in relation to the triggering statement (e.g., UPDATE, INSERT, or DELETE) that is being executed. BEFORE triggers are fired before the triggering statement. AFTER triggers are fired after the trigger statement is executed. BEFORE and AFTER triggers apply to both row and statement triggers.
Instead Of	(For views only.) Corresponds to the INSTEAD OF option of the SQL command CREATE TRIGGER. Oracle fires the trigger instead of executing the triggering statement. The trigger performs the insert, update, or delete actions directly on the base tables of the view.

Statement check boxes:

UPDATE INSERT DELETE	Specifies the type of SQL statement (triggering statement) that fires the trigger body. The possible options are UPDATE, INSERT, and DELETE.  Check one or more of the check boxes to include the option in the triggering statement. If the triggering statement specifies UPDATE, an optional list of columns can be included in the triggering statement. See the Of Columns option next. If more than one option is checked, you can use the conditional predicates UPDATING, INSERTING, and DELETING to execute specific blocks of code in the trigger body. See Trigger Body later.

Of Columns option:

Of Columns	(For tables only.) Corresponds to the OF clause in the UPDATE triggering statement of the SQL command CREATE TRIGGER. Displays a list of columns for the table selected in the Table field. This list is active only if the triggering statement specifies UPDATE. Click one or more columns in this list box to specify that the trigger fires only when one of the selected columns is updated.  If you want the trigger to fire when any column in the table is updated, do not click any column names in the list. Not available with INSTEAD OF triggers. Oracle fires INSTEAD OF triggers whenever an UPDATE changes a value in any column of the view. Oracle8 objects: You cannot specify nested table columns or LOB columns here.

For Each Statement option:

Statement	Corresponds to the FOR EACH STATEMENT option of the SQL command CREATE TRIGGER.  Designates the trigger to be a statement trigger. Oracle fires a statement trigger only once when the triggering statement is issued (regardless of the number of rows affected), if the optional trigger constraint defined in the WHEN clause is satisfied. Not available with INSTEAD OF triggers.

For Each Row options:

Row	Corresponds to the FOR EACH ROW option of the SQL command CREATE TRIGGER.  Designates the trigger to be a row trigger. Oracle fires a row trigger once for each row that is affected by the triggering statement and meets the optional trigger constraint defined in the WHEN clause.
Referencing	Specifies correlation names. You can use correlation names in the trigger body and WHEN clause of a row trigger to refer specifically to old and new values of the current row. The default correlation names are OLD and NEW. If your row trigger is associated with a table named OLD or NEW, use this option to specify different correlation names to avoid confusion between the table name and the correlation name. For row triggers only.
OLD As	Specifies a correlation name to avoid a name conflict between the correlation name and a table that is named OLD.
NEW As	Specifies a correlation name to avoid a name conflict between the correlation name and a table that is named NEW.
When	(For tables only.) Corresponds to the Boolean SQL expression in the WHEN clause of the SQL command CREATE TRIGGER. For row triggers only. Specifies an optional trigger restriction. If included, the SQL expression is evaluated for each row that the trigger affects.  If the expression evaluates to TRUE for a row, the trigger body is fired.  If the expression evaluates to FALSE or NOT TRUE for a row (i.e., unknown, as with nulls), the trigger body is not fired. Oracle8 objects: You can reference object columns or their attributes, VARRAY, nested table, or LOB columns. You cannot invoke PL/SQL functions or methods in the trigger restriction.

Specify the trigger action in:

Trigger Body	The PL/SQL block Oracle executes to fire the trigger. A scrollable, multi-line text box where you can type and edit a PL/SQL block.  Trigger bodies can include SQL and PL/SQL statements. BEGIN and END keywords are required. The trigger body for row triggers can include correlation names and the REFERENCING option, and the conditional predicates INSERTING, DELETING, and UPDATING. If more than one type of triggering statement is specified for the row trigger, e.g., INSERT and UPDATE, you can include the following conditions to execute specific blocks of code in the trigger body: IF INSERTING THEN…END IF; IF UPDATING THEN…END IF;

The buttons in the editor are:

New	Creates a new database trigger. Click New to start defining a new trigger.
Save	Saves the trigger options and compiles the source appearing in the Trigger Body field.  Any error messages generated as a result of the compilation will display in a message box.
Revert	Restores the database trigger to its state at the last save or revert operation.
Drop	Drops the current database trigger from the database, with confirmation.
Close	Exits the Database Trigger editor.
Help	Displays this help topic.


About database triggers

Database triggers are procedures that are stored in the database and implicitly executed when a triggering statement such as INSERT, UPDATE, or DELETE is issued against the associated table.  Triggers can be defined only on tables, not on views.  However, triggers on the base table of a view are fired if an INSERT, UPDATE, or DELETE statement is issued against a view.

A trigger can include SQL and PL.SQL statements that execute as a unit, and can invoke other stored procedures.  Use triggers only when necessary.  Excessive use of triggers can result in cascading or recursive triggers.  For example,  when a trigger is fired, a SQL  statement in the trigger body potentially can fire other triggers.

By using database triggers, you can enforce complex business rules and ensure that all applications behave in a uniform manner. Use the following guidelines when designing triggers:

•	Use triggers to guarantee that when a specific operation is performed, related actions are performed.

•	Use database triggers only for centralized, global operations that should be fired for the triggering statement, regardless of which user or database application issues the statement.

•	Do not define triggers that duplicate the functionality already built into Oracle. For example, do not define triggers to enforce data integrity rules that can be easily enforced using declarative integrity constraints.

•	Limit the size of triggers (60 lines or fewer is a good guideline). If the logic for your trigger requires much more than 60 lines of PL/SQL code, it is better to include most of the code in a stored procedure, and call the procedure from the trigger.

•	Be careful not to create recursive triggers. For example, creating an AFTER UPDATE statement trigger on the EMP table that itself issues an UPDATE statement on EMP causes the trigger to fire recursively until it has run out of memory.

For additional information about how triggers are used in applications, see the Oracle8 Application Developer's Guide. See the Oracle8 Concepts Manual for more information about the different types of triggers.


Displays the user ID of the owner of the current database table.  Click the arrow to the right of this field to display a drop-down list of users.


Displays the name of the current database table or view.  Click the arrow to the right of this field to display a drop-down list of tables or views owned by the user shown in the Table Owner field.  Click a table or view in the list to select it.  The list displays only the names of the database tables or views to which you have access. (Views are for Oracle8 only)


Displays the name of the current database trigger.  Click the arrow to the right of this field to display a drop-down list of trigger names for the table or view shown in the Table/View field.  The Name list displays only the names of the database triggers to which you have access.


Indicates when the trigger body is fired in relation to the triggering statement (e.g., UPDATE, INSERT, or DELETE) being executed.  This set of radio buttons correspond to the BEFORE, AFTER and INSTEAD OF options of the SQL command CREATE TRIGGER.


Specifies that the trigger is fired before the triggering statement.


Specifies that the trigger body is fired after the triggering statement.


Specifies that Oracle fires the trigger instead of executing the triggering statement.  For views only.


Specifies the type of SQL statement that fires the trigger body.  The possible options are UPDATE, INSERT, and DELETE.  Click one or more of the check boxes to activate the option. For tables only.


Specifies that the trigger is fired upon an INSERT event.


Specifies that the trigger is fired upon a DELETE event.


Specifies that the trigger is fired upon an UPDATE event.


Displays a list of columns for the table selected in the Table field.  This list is only active if the UPDATE option is activated in the Statement field. For tables only.


Specifies a row trigger.  Corresponds to the FOR EACH ROW option of the CREATE TRIGGER command.


Specifies a statement trigger.  Corresponds to the FOR EACH STATEMENT option of the CREATE TRIGGER command.


Specifies a correlation name to avoid a name conflict between the correlation name and a table or view that is named OLD.


Specifies a correlation name to avoid a name conflict between the correlation name and a table or view  that is named NEW.


Specifies a Boolean SQL expression in a WHEN clause.  If included, the expression in the WHEN clause is evaluated for each row that the trigger affects.  If the expression evaluates to TRUE for a row, the trigger body is fired.  If the expression evaluates to FALSE or NOT TRUE (i.e., unknown, as with nulls), for a row, the trigger body is not fired. For tables only.


A scrollable, multi-line text box where you can enter and edit a PL/SQL database trigger body.  Trigger bodies are PL/SQL blocks that can include SQL and PL/SQL statements.


Creates a new, unnamed database trigger.


Saves the trigger options and compiles the source appearing in the Trigger Body field.  Any error messages generated as a result of the compilation will appear in a message box.


Restores the database trigger to its state at the last save or revert operation.  If no save or revert operations have occurred, the database trigger is returned to its original state.


Drops the current database trigger from the database, with confirmation.


The PL/SQL Interpreter interface

The PL/SQL Interpreter is your debugging workspace, where you can display source code, create debug actions, run program units, and execute Interpreter commands, PL/SQL, and SQL statements.

By default, two panes are always open in the PL/SQL Interpreter: Source pane and Interpreter pane.

Standard toolbar buttons  All panes in the Interpreter share one toolbar.  With the exception of Close, the following buttons are only activated during suspended execution of a program unit and are used for debugging.

Step Into		Resumes execution of the suspended program unit to the next executable statement.
Step Over		Resumes execution of the suspended program unit to the next executable statement, stepping over any calls to nested subprograms.
Step Out		Resumes execution of a nested subprogram, suspending execution at the next executable statement in the calling program unit.
Go		Resumes execution of the suspended program unit to the end of the program unit, or to the next debug action.
Reset		Exits the current debug level.  If the current debug level is 1, suspended execution is abandoned.
Close		Closes the PL/SQL Interpreter window.
Help		Displays this help topic.
Source pane  The Source pane displays a read-only copy of the currently selected program unit.  Keywords, comments, strings, and symbols are colored differently.  The first column in the left margin is reserved for icons or symbols.  Source lines are numbered in the second column.

The following icons may appear:

yellow arrow		Specifies the current execution location or PC (program counter).
red ball		Specifies enabled breakpoint or trigger.
green ball		Specifies disabled breakpoint or trigger.

The following symbols may also display in the Source pane:

|	Specifies the current source location.  The current source location changes as a result of Interpreter commands (e.g., LIST) or when program unit execution is interrupted by a debug action (e.g., a breakpoint).
B(n)	Specifies the location of a breakpoint, where n is the corresponding debug action ID.
T(n)	Specifies the location of a debug trigger, where n is the corresponding debug action ID.

The Source pane provides the following commands from a pop-up menu (right-click in Windows):

Break	Displays the Breakpoint dialog box, where you can define a new breakpoint.
Trigger	Displays the Trigger dialog box, where you can define a new debug trigger.
Edit	Displays the Program Unit editor, where you can edit the current program unit.
Note:  Not all systems provide support for pop-up menus.  The above commands are also available from the Debug menu.

Split bars  Split bars enable you to change the relative amount of space occupied by each pane in the Interpreter.  When the Interpreter initially appears, a split bar is located between the Source pane and the Interpreter pane.  If you are using the modal Interpreter, or have inserted the Navigator pane in the modeless Interpreter, a second split bar appears.

Interpreter pane  The Interpreter pane provides a command line interface to PL/SQL, Procedure Builder, and SQL.  You can enter PL/SQL statements or blocks, Procedure Builder Interpreter commands, or SQL statements after the PL/SQL> prompt.  (SQL*Plus statements and syntax are not supported.)

Multi-line commands  While entering PL/SQL syntax at the PL/SQL> prompt, you can press the Enter key at any time to get a secondary prompt in the form +>.  You can display as many subsequent secondary prompts as you need before executing the code with a terminating semicolon (;).

Debug levels  When program execution is suspended by a debug action, the Interpreter establishes a debug level.  At a debug level you can enter commands and PL/SQL statements, which may in turn be interrupted, resulting in nested debug levels.  The current debug level is reflected by a new prompt in the Interpreter pane, which includes a prefix containing the current debug level number.  For example, the Interpreter prompt at debug level 1 appears as:

(debug 1)PL/SQL>

Pop-up menu  The Interpreter pane provides the following commands from a pop-up menu (right-click in Windows):

Clear	Discards all text in the Interpreter pane and issues a new prompt.
New Prompt	Issues a new prompt in the Interpreter pane.  Any input after the previous prompt is ignored.
Note:  Not all systems provide support for a pop-up menu.

Navigator pane  The Navigator pane allows you to view the current call stack, as well as view and optionally modify the values of local variables and parameters at the current scope location while you are debugging.

You can insert a Navigator pane between the Source pane and the Interpreter pane if you want to work entirely in the Interpreter while debugging your program units.  To insert a Navigator pane, choose View [image] Navigator Pane from the menu.  To hide the Navigator pane, choose the same command again.  You can also hide any other pane by selecting the appropriate command from the View menu.

Navigator toolbar  If the Navigator pane is displayed, the following also appear in the button bar:

Create		Creates a new instance of the currently selected object or node.
Delete		Deletes the selected object with confirmation.
Expand		Expands the first level of subnode for the currently selected node.
Collapse		Collapses the current level of subnode of the currently selected node.
Expand All		Expands all levels of subnodes for the currently selected node. However, it does not expand Oracle8 datatype and attribute nodes recursively.
Collapse All		Collapses all levels of subnodes for the currently selected node.
Find (text box)		Allows you to search for an object in the Navigator by typing a partial or full name of the object.
Search forward		Finds the next occurrence of the search criteria specified in the Find text box.
Search backward		Finds the previous occurrence of the search criteria specified in the Find text box.


Resumes execution of the suspended program unit to the next executable statement.


Resumes execution of the suspended program unit to the next executable statement, stepping over any calls to nested subprograms.


Resumes execution of a nested subprogram, suspending execution at the next executable statement in the calling program unit


Resumes execution of the suspended program unit to the end of the program unit, or to the next debug action.


Exits the current debug level.  If the current debug level is 1, suspended execution is abandoned.


Creates a new instance of the currently selected object or node.


Deletes the selected object with confirmation.


Expands the first level of subnode for the currently selected node.


Collapses the current level of subnode of the currently selected node.


Expands all level of subnodes for the currently selected node. Oracle8 datatype and attribute nodes are not expanded recursively.


Collapses all level of subnode for the currently selected node.


Type the name of an object you wish to search for in the Navigator.


Specifies the name of the current program unit, and indicates if it is located on the client or the server.


Displays a read-only copy of the currently selected program unit, with source lines numbered in the second column.


Enables you to change the relative amount of space occupied by each pane in the Interpreter.  When the Interpreter initially appears, a split bar is located between the Source pane and the Interpreter pane.  If you are using the modal Interpreter, or have inserted the Navigator pane in the modeless Interpreter, a second split bar appears.


Allows you to view the current call stack, as well as view and optionally modify the values of local variables and parameters at the current scope location while you are debugging.


Provides a command line interface to PL/SQL, Procedure Builder, and SQL.  You can enter PL/SQL statements or blocks, Procedure Builder Interpreter commands, or SQL statements after the PL/SQL> prompt.


About error messages

Each component has a unique error message prefix:

Prefix	Component
FRM	Form Builder
OG	Graphics Builder
PDE	Procedure Builder
REP	Report Builder
BRW	Query Builder
BRS	Schema Builder
NX, XBD	Translation Builder
Note:  On UNIX, Report Builder sets the value of the $status variable that appears in some messages to be 0 (successful completion) or 1 (unsuccessful completion).

In addition to the Forms Developer or Reports Developer error messages, you may encounter error messages from other sources:

Prefix	Source	Help
ORA	Oracle Server	Oracle8 Error Messages manual
PLS	PL/SQL	Oracle8 Error Messages manual
NET	SQL*Net	Oracle Network Products Messages manual
The Oracle8 Error Messages manual contains error message codes and descriptions for all database utilities such as SQL*DBA, SQL*Loader,SQL*Module,Export, Import, and the Oracle Precompilers.

System-specific error messages are documented in your operating system documentation.


Calling Oracle Support Services

Some errors (that is, internal errors) will require that you call Oracle Support Services to report the error.  When you call Support Services, please have the following information at hand:

1	Your name, company, and Oracle Support ID number.

2	The hardware, operating system, and release number of the operating system you are using.

3	The complete version number of the component you were using when you encountered the error, including revision number and port release number, if any.  (If you are unsure of the component's version number, choose Help [image] About.)

4	All other products (and version numbers) in use when you encountered the error (for example, Oracle 8.0.4).

5	If you encountered one or more error messages, the exact message numbers and descriptions, in the order they appeared.

6	A description of the problem, including any unusual conditions.

7	The problem severity, according to the following codes:

•	1:  Program not usable.  Critical impact on operations.

•	2:  Program usable.  Operations severely restricted.

•	3:  Program usable with limited functions.  Not critical to overall operations.

•	4:  Problem circumvented by customer.  Minimal effect, if any, on operations.


Abnormal conditions

Sometimes you may encounter an error that is known as an abnormal condition, which may arise from one of the following causes:

•	Someone has done something that prevented your application from completing the requested task.  For example, if someone bypassed the user interface and changed data in a database table, they might have typed an invalid value.

•	A software bug prevented the requested task from completing.

Action   First contact your system administrator to determine if the message was caused by something other than Forms Developer or Reports Developer.  If you determine that the message was not the result of user error or a system problem, then contact Oracle Support Services.


About the PL/SQL V1 conversion utility

  Related Topics

The PL/SQL V1 conversion utility helps automate the process of upgrading applications written in PL/SQL V1 or V2.

If the triggers, program units, and PL/SQL blocks in your forms, reports, and displays are written in PL/SQL V1 or V2, your code must be upgraded.  If it isn’t, two types of problems can occur:

•	Some PL/SQL V1 or V2 code is not syntactically valid in later versions and produces a compiler error.

•	Some PL/SQL V1 or V2 code is syntactically correct in later versions, but has a different meaning, causing unexpected or incorrect behavior.

The conversion utility addresses both types of problems.


How does the PL/SQL V1 conversion utility work?

  Related Topics

You can use the conversion utility interactively or in batch mode.  In either case, you control whether or not the utility actually updates your code.  Interactive mode provides a greater degree of flexibility, as you can let the utility make some changes and make others manually.  In batch mode, the utility either makes all of the conversions it can or none of them.  Regardless of whether the conversion occurs in interactive or batch mode, a summary of the conversion process is written to a log file called module.plg.

To run the utility interactively , open a saved form, report, display, or library containing PL/SQL V1 or V2 code in the associated Builder.

To run the utility in batch mode, refer to these topics:

•	Converting forms in batch mode

•	Converting reports in batch mode

•	Converting displays in batch mode

Tip

While the conversion utility can upgrade your code to resolve several V1 or V2 incompatibilities, there are some situations it can’t address.  These result in compiler errors, which are listed in the PL/SQL V1 Conversion Summary dialog box (interactive mode) or in the log file so you can address them manually.  See What can’t the utility convert?  for more information.

After the conversion utility converts and saves an application-even if you choose to ignore all suggested conversions-the utility is never again re-invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.


Before deciding which mode to use, try converting a few modules of each type interactively.  That will give you an idea of the kinds of issues you’re facing in each type of module, and may help you decide how to proceed.  For example, you might discover that your forms require the close monitoring that interactive mode provides, while your reports and PL/SQL libraries can be safely converted in batch mode.


Using the PL/SQL V1 conversion utility interactively

  Related Topics

To run the conversion utility interactively, open a form, report, display, or library containing PL/SQL V1 or V2 code in the associated Builder, then save the application.

Important:

•	After the conversion utility converts and saves an application-even if you choose to ignore all suggested conversions-the utility can never again be invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.

Each PL/SQL V1 or V2 statement in your trigger, PL/SQL block, or program unit is presented in the Conversion dialog box.  The dialog box also contains the action the conversion utility will take if you choose to convert.  You have complete control over whether you accept the proposed change, ignore it, convert the entire application , or stop the process entirely.  (You can also use the PL/SQL V1 Conversion Options dialog box to set parameters that control the conversion process behind the scenes.)

The utility keeps track of the changes you have made (and those you chose not to make) and summarizes them at the end of the conversion process in a log file called module.plg.   You can then invoke the PL/SQL editor to manually update the application.


Using the PL/SQL V1 conversion utility in batch mode

  Related Topics

To run the utility in batch mode, refer to these topics:

•	Converting forms in batch mode

•	Converting reports in batch mode

•	Converting displays in batch mode


Converting forms in batch mode

  Related Topics

To convert a form in batch mode:

1	Make sure you have converted all PL/SQL libraries attached to the form.

2	Do one of the following:

•	Run the GUI version of the Forms Compiler

•	Run the Forms Compiler from the command line

Regardless of the method you choose, a summary of the conversion process is automatically written to the log file module.plg, where module is the name of the form module converted.

Usage Note:

•	After the conversion utility converts and saves an application-even if you choose to ignore all suggested conversions-the utility can never again be invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.


Converting forms using the GUI version of the Forms Compiler

To convert a form using the GUI version of the Form Compiler:

1	Double-click the Form Compiler icon.

2	Select the appropriate module type and module access.

3	Select the box Upgrade PL/SQL from V1 to V2.3?

4	Click OK.


Converting forms from the command line

  Related Topics

To convert a form using the Form Compiler on the command line:

  From the command line, issue:

<Form Compiler> MODULE=form BATCH=yes UPGRADE_PLSQL=yes UPGRADE=yes

where:

<Form Compiler>	Is the name of the Form Compiler executable on your platform.
form	Is the name of the form you want to convert.
Usage Notes:

•	If you specify UPGRADE_PLSQL=YES without also specifying UPGRADE=YES, an error message is generated.  Because you cannot convert the PL/SQL in a form without upgrading the entire form to 6.0, UPGRADE=YES must be specified when UPGRADE_PLSQL= YES.

•	To convert many displays at once, use Project Builder.  See the Project Builder help topic Choosing an upgrade method.


Converting PL/SQL libraries attached to a form

To convert a PL/SQL library interactively:

  Open the library in Form Builder, then save it.

To convert a PL/SQL library using the GUI version of the Form Compiler:

1	Double-click the Form Compiler icon.

2	In the File field, select the PL/SQL Library you want to convert.

3	In the Write output to file field, make sure the target file has the extension .PLL.

4	Click OK.

To convert a PL/SQL library using the Form Compiler on the command line:

  From the command line, issue:

<Form Compiler> MODULE=library BATCH=yes UPGRADE_PLSQL=yes UPGRADE=yes

where:

<Form Compiler>	Is the name of the Form Compiler executable on your platform.
library	Is the name of the library you want to convert.
Usage Note:

•	If you specify UPGRADE_PLSQL=YES without also specifying UPGRADE=YES, an error message is generated.  Because you cannot convert the PL/SQL in a form without upgrading the entire form to 6.0, UPGRADE=YES must be specified when UPGRADE_PLSQL= YES.

•	To convert many displays at once, use Project Builder.  See the Project Builder help topic Choosing an upgrade method.


Specifying Form Builder Compiler parameters

This table describes how different combinations of the BATCH, UPGRADE, and UPGRADE_PLSQL parameters affect the conversion process:

BATCH	UPGRADE_PLSQL	UPGRADE	Behavior
NO	YES	YES	PL/SQL in form is converted in batch mode (even though BATCH=NO).  The utility cannot be invoked interactively outside the Builder.
YES	YES	YES	PL/SQL in form is converted in batch mode.
NO	NO	YES	PL/SQL in form is not converted, but a list of suggested conversions is written to module.plg. The rest of the form is upgraded to Forms 6i.
YES	NO	YES	PL/SQL in form is not converted, but a list of suggested conversions is written to module.plg. The rest of the form is upgraded to Forms 6i.
NO	NO	NO	Used to compile a new FMX without modifying the FMB.  If the form contains 1.3 PL/SQL, you may see compiler errors, or the behavior of the code may be different.
YES	NO	NO	Used to compile a new FMX without modifying the FMB. If the form contains 1.3 PL/SQL, you may see compiler errors, or the behavior of the code may be different.
Important:

If you are upgrading from 45FMT to 60FMB and you do not specify the UPGRADE_PLSQL option, the PL/SQL in the form is not converted, but a list of suggested conversions is written to a log file. This log file is placed in the current working directory, which may be different from the directory in which the FMT file is located.


Converting reports in batch mode

To convert a report in batch mode:

1	Make sure you have converted all PL/SQL libraries attached to the report.

2	Do one of the following:

•	Run the GUI version of the Report Compiler

•	Run the Report Compiler from the command line

Regardless of the method you choose, a summary of the conversion process is automatically written to the log file module.plg, where module is the name of the report module converted.  A separate log is generated for each module.

Usage Note:

•	After the conversion utility converts and saves an application-even if you choose to ignore all suggested conversions-the utility can never again be invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.


Converting reports using the GUI version of the Report Compiler

To convert one or more reports using the GUI version of the Report Compiler:

1	Double-click the Report Compiler icon.

2	In the Document Type field, select Report.

3	Choose the appropriate Source and Destination types.

4	Use the Source field Browse button to locate the report(s) you want to convert.

5	Use the Destination field Browse button to select the destination for the converted report.

6	Click OK.


Converting reports from the command line

To convert one or more reports from the command line:

  From the command line, issue:

<Report Compiler> SOURCE=rep1,rep2, UPGRADE_PLSQL=yes

where:

<Report Compiler>	Is the name of the Report Compiler executable on your platform.
rep1,rep2,	Is the name of the report(s) you want to convert.


Converting PL/SQL libraries attached to a report

To convert a PL/SQL library interactively:

  Open the library in Report Builder, then save it.

To convert a PL/SQL library using the GUI version of the Report Compiler:

1	Double-click the Report Compiler icon.

2	In the Document Type field, specify PL/SQL Library.

3	In the Source Type field, specify .PLL.

4	In the Destination Type field, specify .PLL or .PLX.  If you specify .PLD, the V1 or V2 PL/SQL will not be converted.

To convert a PL/SQL library using the Report Compiler on the command line:

  From the command line, issue:

<Report Compiler> SOURCE=lib1,lib2, UPGRADE_PLSQL=yes

where:

<Report Compiler>	Is the name of the Report Compiler executable on your platform.
lib1, lib2	Is the name of the library(s) you want to convert.
Usage Note:

•	To convert many displays at once, use Project Builder.  See the Project Builder help topic Choosing an upgrade method.


Converting displays in batch mode

To convert displays in batch mode:

1	Make sure you have converted all PL/SQL libraries attached to the display .

2	Issue this command:

<Graphics Builder> openfile=temp.ogd upgrade_plsql=yes savefile=temp1.ogd quit=yes

where:

<Graphics Builder>	Is the name of the Graphics Builder executable on your platform.
openfile=temp.ogd	Opens the display temp.ogd in Graphics Builder.
upgrade_plsql=yes	Converts the V1 or V2 PL/SQL.
savefile=temp1.ogd	Saves the converted display in temp1.ogd.
quit=yes	Closes Graphics Builder after the display is converted.
Usage Notes:

•	A summary of the conversion process is automatically written to the log file module.plg, where module is the name of the display converted.

•	To convert many displays at once, use Project Builder.  See the Project Builder help topic Choosing an upgrade method.

•	After the conversion utility converts an application-even if you choose to ignore all suggested conversions-the utility can never again be invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.


Converting PL/SQL libraries attached to a display

To convert a PL/SQL library interactively:

  Open the library in Graphics Builder, then save it.

To convert a PL/SQL library in batch mode:

  Issue this command:

<Graphics Builder> openfile=temp.lib upgrade_plsql=yes savefile=temp1.lib quit=yes

where:

<Graphics Builder>	Is the name of the Graphics Builder executable on your platform.
openfile=temp.lib	Opens the library temp.lib in Graphics Builder.
upgrade_plsql=yes	Converts the V1 or V2 PL/SQL.
savefile=temp1.lib	Saves the converted library in temp1.lib.
quit=yes	Closes Graphics Builder after the library is converted.
Usage Notes:

•	A summary of the conversion process is automatically written to the log file module.plg, where module is the name of the library converted.

•	After the conversion utility converts an application-even if you choose to ignore all suggested conversions-the utility can never again be invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.

•	To convert many displays at once, use Project Builder.  See the Project Builder help topic Choosing an upgrade method.


What does the PL/SQL V1 conversion utility convert?

  Related Topics

The situations that the conversion utility can resolve within your application are:

CHAR replaced by VARCHAR2

String length required for VARCHAR2

Default expressions for OUT and IN OUT disallowed

RETURN requires an expression

Obsolete built-ins replaced

Length function returns NULL for zero-length strings

Passing NULL to an overloaded subprogram does not resolve properly

Missing RETURN statement in function causes runtime error

Length constraints removed


CHAR replaced by VARCHAR2

In PL/SQL V1, the datatypes CHAR and VARCHAR2 could be used interchangeably.  In versions after V1, the CHAR datatype is right padded with blanks.

In PL/SQL V1, this statement:

var1 CHAR(10) := ‘hello’;

. . .is equal to ‘hello’.

In versions after V1, however, this statement resolves to ‘hello     ‘, (a total of ten characters).

To preserve the V1 behavior of CHAR variables, the conversion utility replaces all CHAR(n) declarations with the equivalent VARCHAR2(n) statement.  In the example above, var1 becomes VARCHAR2(10).

The conversion utility also replaces all VARCHAR statements with the equivalent VARCHAR2 expression.


String length required for VARCHAR2

Versions after PL/SQL V1 require a length for all VARCHAR2 variables.  If a length is already specified for a CHAR datatype, the conversion utility uses that length when replacing the declaration with VARCHAR2 (see CHAR replaced by VARCHAR2 for more information).  For example:

var1 CHAR(10);

. . .is converted to:

var1 VARCHAR2(10);

When the converter detects a CHAR or VARCHAR2 statement without a string length, it suggests a length of one character.  For example:

var2 CHAR;

. . .is converted to:

var2 VARCHAR2(1);

Similarly,

var3 VARCHAR2;

. . .is converted to:

var3 VARCHAR2(1);

If you do not supply a length for a VARCHAR2 declaration, the compiler generates this error message:

ERROR 215:  String length constraint must be in range (1 . . 32767)


Default expressions for OUT and IN OUT disallowed

  Example

In PL/SQL V1, OUT and IN OUT parameters could be followed by a default expression, although that expression was always ignored.  The conversion utility removes the default expressions for OUT and IN OUT parameters.

If you compile existing code that includes OUT and IN OUT parameters with default expressions, this error message is generated:

ERROR 230:  OUT and IN OUT formal parameters may not have default expressions


Removing default expressions example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

PROCEDURE p (p1 IN OUT NUMBER DEFAULT 25,
             p2 OUT NUMBER DEFAULT 16) IS

BEGIN
. . .
END;

. . . to this:

PROCEDURE p (p1 IN OUT NUMBER, p2 OUT NUMBER) IS

BEGIN
. . .
END;


RETURN requires an expression

  Example

In PL/SQL V1, you could use a RETURN statement without an expression to return a NULL value.  Since all functions should return values, versions after V1 consider the RETURN statement mandatory.  The conversion utility replaces all RETURN statements not followed by an expression with RETURN NULL.

If you compile existing code that includes a RETURN statement without an expression, this error message is generated:

ERROR 503:  RETURN statement required for this return from function


Adding NULL to RETURN example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

FUNCTION f RETURN NUMBER IS
x NUMBER;
BEGIN
x :=13;
IF . . . THEN
RETURN;
END IF;
RETURN x;
END;

. . . to this:

FUNCTION f RETURN NUMBER IS
x NUMBER;
BEGIN
x :=13;
IF . . . THEN
RETURN NULL;    NULL added here
END IF;
RETURN x;
END;


Obsolete built-ins replaced

  Example

The TO_PLS_INTEGER built-in, which converts character strings to PL/SQL integers, is obsolete in versions after V1.  The conversion utility replaces TO_PLS_INTEGER with the built-in TO_NUMBER.

If you do not replace the TO_PLS_INTEGER built-in, this compiler error is generated:

ERROR 201:  Identified TO_PLS_INTEGER must be declared

Note:  Other obsolete built-ins must be replaced manually.


Replacing obsolete built-in example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

PROCEDURE foo IS
     v INTEGER;
BEGIN
     v := TO_PLS_INTEGER(24);
END;

. . .to this:

PROCEDURE foo IS
     v INTEGER;
BEGIN
     v := TO_NUMBER(24);     TO_PLS_INTEGER replaced with TO_NUMBER
END;


Length function returns NULL for zero-length strings

  Example

In PL/SQL V1, the LENGTH function applied to a null expression resolves to zero.  In versions after V1, the LENGTH function applied to a null expression resolves to null.

To preserve V1 behavior, the PL/SQL conversion utility adds the NVL SQL predicate to ensure that the LENGTH function applied to a null expression resolves to zero.


Length function example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

c:=null;
l=LENGTH( c );         In V1, this resolves to 0

. . . to this:

c:=null;
l=NVL(LENGTH( c ),0);  Converter wraps LENGTH function
                                                      with NVL( ) built-in, forcing the
                                                      expression to resolve to 0


Passing NULL to an overloaded subprogram does not resolve properly

  Example

In PL/SQL V1, you could define the same subprogram in a package as two different data types: VARCHAR2 and a RECORD type.  This is called overloading the subprogram. If you then passed a NULL value to an overloaded subprogram, PL/SQL assumed a data type of VARCHAR2.  However, versions after V1, a NULL value passed to an overloaded subprogram within a package must have a defined type.

To preserve V1 behavior, the PL/SQL conversion utility takes one of the following actions, as appropriate, when it encounters a NULL passed to an overloaded subprogram:

•	Wrap NULL with TO_CHAR( )

•	Wrap NULL with TO_NUMBER( )

•	Wrap NULL with TO_DATE( )

•	Wrap NULL with NOT

If you pass a NULL value to an overloaded program unit without defining the desired data type, the compiler generates this error message:

ERROR 307:  Too many declarations of ‘PU name’ match this call . . .


Passing NULL to overloaded subprogram example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

PACKAGE ps1 IS
  TYPE foo IS RECORD(id PLS_INTEGER);
                              Subprogram p is overloaded::
  PROCEDURE p(a VARCHAR2);    a is defined as a variable of type VARCHAR2
  PROCEDURE p(a FOO);         a is also defined as another data type
END;

PROCEDURE foo2 IS
BEGIN
  ps1.p(NULL);                In PL/SQL V1, the VARCHAR2
                                                                      datatype is assumed.
END;

. . . to this:

PACKAGE ps1 IS
  TYPE foo IS RECORD(id PLS_INTEGER);

  PROCEDURE p(a VARCHAR2);
  PROCEDURE p(a FOO);

END;

PROCEDURE foo2 IS
BEGIN
  ps1.p(TO_CHAR(NULL));      Since a is type VARCHAR2, the NULL
                             value is wrapped with TO_CHAR( )
END;


Missing RETURN statement in function causes runtime error

  Example

Omitting the RETURN statement in a function in PL/SQL V1 does not cause a problem at runtime.  However, in versions after V1, this will cause a runtime error.

To preserve V1 behavior, the PL/SQL conversion utility adds a RETURN statement with a NULL argument to functions that are missing a RETURN statement.

Note:  A missing RETURN statement in a function will not generate a compiler error, but it will generate a runtime error in versions after V1.


Missing RETURN example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

FUNCTION noreturn (arg IN NUMBER) RETURN char IS
BEGIN
  IF (arg > 100000) THEN
    TEXT_IO.PUT_LINE ('The point of no return.');
  ENDIF;
                         RETURN statement is missing
END;

. . . to this:

FUNCTION noreturn (arg IN NUMBER) RETURN char IS
BEGIN
  IF (arg > 100000) THEN
    TEXT_IO.PUT_LINE ('The point of no return.');
  ENDIF;
  RETURN NULL;            RETURN NULL added by converter
END;


Length constraints removed

  Example

In PL/SQL V2, the length constraints on DATE, BOOLEAN, MLSLABEL, and ROWID are ignored.  However, this causes compilation errors in V8.

To preserve V2 behavior, the PL/SQL conversion utility removes the constraints.


Removing length constraints example

  Related Topics 	   All Examples

The conversion utility converts this code:

PROCEDURE badconstraint IS
d DATE(5);
b BOOLEAN(5);
d MLSLABEL(5); --V2 only
r ROWID(5); --V2 only
BEGIN
  null;
END;

. . . to this:

PROCEDURE badconstraint IS
d DATE;
b BOOLEAN;
d MLSLABEL; --V2 only
r ROWID; --V2 only
BEGIN
  null;
END;


What can't the PL/SQL V1 conversion utility convert?

  Related Topics

While the conversion utility can convert many of the PL/SQL incompatibilities it encounters, some situations require you to address them manually:

Unique names required within a package

Standard package function no longer used

New reserved words in PL/SQL V2.3 or later

%ROWTYPE or %TYPE required in variable declarations

The warning "Encountered a non-recoverable error; conversion aborted at line <line number> column <column>" displays when there is a fatal compiler error and the conversion process cannot continue.


Unique names required within a package

  Example

In PL/SQL V1, when you created a variable with the same name as a procedure or function in the same package, the variable was always used; the identically named procedure or function was ignored.  In versions after V1, variables, functions, and procedures within the same package must be unique.

To avoid an error, make sure all procedures within a package have unique names, either by doing so explicitly, or by appending the word Unused to the procedure name.

Note:  In V1, Procedure Builder erroneously allowed you to create a program unit with the same name as a built-in package.  In versions after V1, this is not allowed.  If Procedure Builder detects a program unit with the same name as a built-in package, Procedure Builder changes the name of the program unit during load time by appending two dollar signs to the end of the program unit name.  Thus, DEBUG becomes DEBUG$$.


Renaming procedure names uniquely in a package example

  Related Topics 	   All Examples

This example first presents V1 PL/SQL code that will generate a compiler error, then shows how you might edit the code to avoid the error.

Change this code:

PACKAGE pk1 IS
  v1 NUMBER;           v1 is established as a variable
  PROCEDURE v1;        v1 is also established as a procedure
  PROCEDURE p2 (x OUT NUMBER);
END;

PACKAGE BODY pk1 IS
  PROCEDURE v1 IS
  BEGIN
   . . .
  END;

  PROCEDURE p2 (x OUT NUMBER) IS
  BEGIN
x := pk1.v1;
  END;

END;

. . . to this:

PACKAGE pk1 IS
  v1 NUMBER;
  PROCEDURE v1Unused;	  The procedure v1 is declared Unused
  PROCEDURE p2 (x OUT NUMBER);
END;

PACKAGE BODY pk1 IS
  PROCEDURE v1Unused IS
  BEGIN
   . . .
  END;

  PROCEDURE p2 (x OUT NUMBER) IS
  BEGIN
x := pk1.v1;
  END;

END;


Standard package function no longer used

  Example

In PL/SQL V1, you could call the FLOOR function from your own package, p1, like this:

v : = p1.FLOOR(x).

If the p1 package did not have a function called FLOOR, PL/SQL used the FLOOR function in the standard package.  This was actually a PL/SQL coding error that has been fixed in PL/SQL V2.3 or later.  Therefore, in PL/SQL V2.3, the compiler does not check the standard package for the function name, but correctly reports the situation as an error:

ERROR 302:  component ‘CCCCC’ must be declared

. . . where ‘CCCCC’ is the function or procedure name that exists in a standard package or standard package extension.

The message "Incorrect references will resolve to built-in package V1" is written to the log.

To direct the compiler to the standard package, remove the incorrect package name.


Removing the package prefix example

  Related Topics 	   All Examples

This example first presents V1 PL/SQL code that will generate a compiler error, then shows how you might edit the code to avoid the error.

Change this code:

PACKAGE pk1 IS a NUMBER;
END;

PROCEDURE p IS v NUMBER;
BEGIN
v := pk1.FLOOR(20.5);
END;

. . . to this:

PACKAGE pk1 IS a NUMBER;
END;

PROCEDURE p IS v NUMBER;
BEGIN
v := FLOOR(20.5);     Prefix removed
END;


New reserved words in PL/SQL V2.3 or later

  Examples

The word VARIANCE is reserved in PL/SQL V2.3 or later and, if used, generates a compiler error.

See the example for information on how to use VARIANCE without generating an error.


Reserved word examples

  Related Topics 	   All Examples

The example first presents PL/SQL V1 code that will generate a compiler error, then shows how you might edit the code to avoid the error.

Example 1:

Change this code:

FUNCTION variance (y IN NUMBER)
RETURN NUMBER IS

BEGIN
     . . .
     RETURN . . .;
END;

. . .to this:

FUNCTION varianceUniqueName (y IN NUMBER)
     /* A unique name was appended to Variance. */
RETURN NUMBER IS

BEGIN
     . . .
     RETURN . . .;
END;

Example 2:

When calling a subprogram, change the code:

PROCEDURE foo IS
     x NUMBER;
     y NUMBER;
BEGIN
     . . .
     x := variance(someNumber);
END;

. . .to this:

PROCEDURE foo IS
     x NUMBER;
     y NUMBER;
BEGIN
     . . .
     x := varianceUniqueName(someNumber);
END;


%ROWTYPE or %TYPE required in variable declarations

  Examples

The PL/SQL V8 compiler will issue an error on the following illegal syntax (which the PL/SQL V2 compiler incorrectly allows):

return variable-expression

procedure (parameter IN <table_name>)

procedure (parameter IN <table_name>.<column_name>)

The correct syntax should be:

return variable-type

procedure (parameter IN <table_name>%ROWTYPE)

procedure (parameter IN <table_name>.<column_name>%TYPE)

To avoid an error, use the datatype of the expression, append %ROWTYPE to the table name, or append %TYPE to the column name.


Variable declarations examples

  Related Topics 	   All Examples

These examples first present PL/SQL V2 code that will generate a compiler error, then show how you might edit the code to avoid the error.

Example 1:

Change this code:

FUNCTION return_column RETURN dept.dname IS
. . .

. . .to this:

FUNCTION return_column RETURN dept.dname%TYPE IS
. . .

Change this code:

PROCEDURE foo (name IN dept.dname) IS
. . .

. . .to this:

PROCEDURE foo (name IN dept.dname%TYPE) IS
. . .

Example 2:

Change this code:

FUNCTION return_table RETURN dept IS
. . .

. . .to this:

FUNCTION return_table RETURN dept.%ROWTYPE IS
. . .

Change this code:

PROCEDURE foo (name IN dept) IS
. . .

. . .to this:

PROCEDURE foo (name IN dept%ROWTYPE) IS
. . .

Example 3:

This example shows an exception where you cannot use %TYPE.

When declaring parameters, change this code:

FUNCTION return_parm (x IN NUMBER)
  RETURN x IS
. . .

. . .to this:

FUNCTION return_parm (x IN NUMBER)
  RETURN number IS
. . .


Database Libraries dialog
Database Libraries dialog box

The Database Libraries dialog box displays a list of libraries currently stored in the database.

Library	Is the list of libraries available from the database you're connected to.  Only the libraries you have GRANT access to are displayed in the list.  Click a library name to select it.


Is the list of libraries available from the database to which you're connected.  Only the libraries you have GRANT access to are displayed in the list.  Click a library name to select it.


New Program Unit dialog
New Program Unit dialog box

The New Program Unit dialog box allows you to specify a name and type of program unit to create.

Name	Type the name of the program unit.
Types	Specify the type of program unit you will create.  You can create the following:
Procedure	A PL/SQL subprogram that performs a specified sequence of actions.
Function	A PL/SQL subprogram that performs a specified sequence of actions, and then returns a value.
Package Spec	Datatypes and subprograms that can be referenced by other program units.
Package Body	Implementation of the package.  May include private subprograms and datatypes.  Is optional if the package consists only of declarations.
Type Spec	Declares the name, variables (attributes) and member subprograms (methods) for an object type or collection type.
Type Body	Implementation of the member methods (functions and procedures) defined in the type specification for an object type.  For each method specified in an object type, there must be a corresponding method body.
Note:  Type Spec and Type Body are enabled only if you are connected to Oracle8.


Type the name of the program unit.


Specifies the type of program unit you will create.


Open Library dialog
Open Library dialog box

The Open Library dialog box allows you to open existing libraries from the file system or the database, and provides a graphical user interface for the Interpreter's OPEN command.

Library	Type the name (and location) of the library you wish to open.
Browse	If File System or Either is selected in the From field, displays your operating system file select dialog box.  If Database is selected in the From field, displays the Database Libraries dialog box.
From	Indicates whether the library is stored on the file system or in the database.


Type the name (and location) of the library you wish to open.


If File System or Either is selected in the From field, displays your operating system file dialog box.  If Database is selected in the From field, displays the Database Libraries dialog box.


Indicates whether the library is stored on the file system or in the database.


Attach Library dialog
Attach Library dialog box

The Attach Library dialog box allows you to attach libraries to your current session, and provides a graphical user interface for the Interpreter's ATTACH command.

Library	Type the name (and location) of the library to attach.
Browse	If File System or Either is selected in the From field, displays your operating system file select dialog box.  If Database is selected in the From field, displays the Database Libraries dialog box.
From	Indicates whether the library is stored on the file system or in the database.
Attach	Confirms your selections, attaches the library, and closes the dialog box.


Type the name (and location) of the library to attach.


If File System or Either is selected in the From field, displays your operating system file dialog box.  If Database is selected in the From field, displays the Database Libraries dialog box.


Indicates whether the library is stored on the file system or in the database.


Confirms your selections, attaches the library, and closes the dialog box.


Log Interpreter dialog
Log Interpreter dialog box

The Log Interpreter dialog box allows you to manage logging activities and provides a graphical user interface for the Interpreter's LOG command.

File	Type the name of the file in which you want the logging session recorded.
Browse	Displays your operating system File dialog box where you can browse and select a location or existing file name.
Append	If selected, activates the APPEND option, meaning the current log session is appended to the end of the existing log file you specified in the File text box.  Otherwise, any current log information in the specified file will be overwritten by the new logging session.
Disabled	If selected, activates the DISABLED option, meaning logging to the specified file is temporarily suspended until enabled again.
Show Log	If selected, displays the Interpreter Log browser when the Log Interpreter dialog box is accepted.  You can also display the Interpreter Log browser by choosing View [image] Interpreter Log in the Interpreter.


Type the name of the file in which you want the logging session recorded.


Displays your operating system File dialog box where you can browse and select a location or existing file name.


If selected, activates the APPEND option, meaning the current log session is appended to the end of the existing log file you specified in the File text box.  Otherwise, any current log information in the specified file will be overwritten by the new logging session.


If selected, activates the DISABLED option, meaning logging to the specified file is temporarily suspended until enabled again.


IIf selected, displays the Interpreter Log browser when the Log Interpreter dialog box is accepted.  You can also display the Interpreter Log browser by choosing View-->Interpreter Log in the Interpreter.


Interpreter Log browser
PL/SQL Interpreter Log browser

The PL/SQL Interpreter Log browser displays the recorded messages from the most recent logging session.

Disable/Enable	Toggles the active state of the current logging session.
Off	Terminates the current logging session and closes the browser.
Messages list box	A read-only, scrollable area that displays a record of input and output in the Interpreter pane.  You can select, copy, and search the text shown in the list box.


Toggles the active state of the current logging session.


Terminates the current logging session and closes the browser.


A read-only, scrollable area that displays a record of input and output in the Interpreter pane.  You can select, copy, and search the text shown in the list box.


Connect dialog
Connect dialog box

The Connect dialog box allows you to establish a connection to a database instance and provides a graphical user interface for the Interpreter's CONNECT command.

User Name	Type your database user ID.  You can type  your whole connect string in this text box, but your password will be echoed.
Password	Type your database password.  There is no echo in this field to protect password security.
Database	Type the database connect string for the database you wish to connect to.  This is generally in the form:
	network_protocol:network_node[:database_name]
	Each field is separated by a colon (:).  See your database administrator for the correct connect string for your database. Note that if you are connecting to an ODBC datasource, the syntax is:
	username/password@ODBC:datasource[:dbname] If dbname is not specified, the current database for the ODBC connection is used.
Connect	Confirms the information you have supplied and attempts a connection.  If the database connection is successful, the dialog box closes.  If the database connection is not successful, an error is issued.


Type your database user ID.  You can type your whole connect string in this text box, but your password will be echoed.


Type your database password.  There is no echo in this field to protect password security.


Type the database connect string for the database to which you wish to connect.


Confirms the information you have supplied and attempts a connection.  If the database connection is successful, the dialog box closes.  If the database connection is not successful, an error is issued.


Grant Access List dialog
Grant Access List dialog box

The Grant Access List dialog box allows you to view and modify access to the currently selected library or stored program unit on the database server, and provides a graphical user interface for the Interpreter's GRANT and REVOKE commands.  You must have GRANT access for the library in order to grant or revoke access to other users.

User list box	Lists the users who currently have access to the selected library or stored program unit.  Click a user name to place it in the User text box.
User	Type in the user name that you wish to grant or revoke access to for the selected library or stored program unit.  This user name must be a valid user name for the current database.  If the user already appears in the User list box, simply click the name.
Add	Adds the user name to the list of those with GRANT access to the library or stored program unit.
Remove	Removes the user name from the list of those with GRANT access to the library or stored program unit.


Lists the users who currently have access to the selected library.  Click a user name to place it in the User text box.


Type in the user name that you wish to grant or revoke access to for the selected library.  This user name must be valid user name for the current database.  If the user already appears in the User list box, simply click the name.


Adds the user name to the list of those with GRANT access to the library.


Removes the user name from the list of those with GRANT access to the library.


Save Library dialog
Save Library dialog box

The Save Library dialog box allows you to save a library to the file system or the database, and provides a graphical user interface for the Interpreter's SAVE command.

Library	Type the name (and location) of the library you wish to save.
Browse	If File System is selected in the To field, displays your operating system file dialog box.  If Database is selected in the To field, displays the Database Libraries dialog box.
To	Indicates whether the library will be saved on the file system or in the database.


Type the name (and location) of the library you wish to save.


If File System is selected in the To field, displays your operating system file dialog box.  If Database is selected in the To field, displays the Database Libraries dialog box.


Indicates whether the library will be saved on the file system or in the database.


Find and Replace dialog box

The Find and Replace dialog box allows you to search for and replace character strings or regular expressions in the program unit source that is currently displayed in the Program Unit or Stored Program Unit editor.

Find What	Type the string you want to find.  If you want this string to be treated as a regular expression, click the Regular Expressions check box.
Replace With	Type the string to replace any matches found.
Regular Expression	If checked, specifies whether the search string should be treated as a regular expression instead of a string.
Case Sensitive	Indicates whether the search should be upper- and lower-case sensitive to the letters in the search string.  If this check box is not checked, the search will find all matches of the search string, regardless of case.
Find Next	Finds the next match of the search string starting from your cursor position.
Replace	Changes the most recently found string to the string specified in the Replace with text box.  If a match is not currently selected, finds the next occurrence of the search string and replaces it.
Replace All	Replaces all matches with the replace string (from the cursor position to the end of the searchable area).


Type the string you want to find.  If you want this string to be treated as a regular expression, click the Regular Expressions check box.


Type the string to replace any matches found.


Indicates whether the search should be upper- and lower-case sensitive to the letters in the search string.  If this check box is not checked, the search will find all matches of the search string, regardless of case.


If checked, specifies whether the search string should be treated as a regular expression instead of a string.


Finds the next match of the search string starting from your cursor position.


Changes the most recently found string to the string specified in the Replace with text box.  If a match is not currently selected, finds the next occurrence of the search string and replaces it.


Replaces all matches with the replace string (from the cursor position to the end of the searchable area).


PL/SQL Breakpoint dialog box

The PL/SQL Breakpoint dialog box provides a graphical user interface for the BREAK command.  It allows you to create or modify breakpoints and break triggers.

Breakpoint	Identifies the breakpoint and is of the form Breakpoint: New or Breakpoint: number.  The label value is "New" when specifying a new breakpoint, or a number when modifying an existing breakpoint.
Enabled	Indicates whether the breakpoint is enabled or disabled.
Program Unit	Identifies the target program unit or where the existing breakpoint is or where the new breakpoint will be created.
Line	Identifies the source location of the breakpoint in the program unit.
Trigger	If required, type the PL/SQL statements that will fire when the breakpoint is hit.  BEGIN and END keywords are not required in the trigger. For example, you can use DEBUG.INTERPRET to execute an Interpreter command. DEBUG.INTERPRET('.SHOW LOCALS');


Identifies the breakpoint and is of the form Breakpoint:  New or Breakpoint:  number.  The label value is "New" when specifying a new breakpoint, or a number when modifying an existing breakpoint.


Indicates whether the breakpoint is enabled or disabled.


Identifies the target program unit where the existing breakpoint is or where the new breakpoint will be created.


Identifies the source location of the breakpoint in the program unit.


Type the PL/SQL statements that will fire when the breakpoint is hit.  BEGIN and END keywords are not required.


PL/SQL Trigger dialog box

The PL/SQL Trigger dialog box allows you to create a debug trigger, and provides a graphical user interface for the TRIGGER command.

Trigger	Identifies the debug trigger and is of the form Trigger: New or Trigger: number.  The label value is New when specifying a new debug trigger, or a number when modifying an existing debug trigger.
Enabled	Indicates whether the debug trigger is enabled or disabled.
Location	Specifies the source location of the debug trigger.
	The Program Unit option (the default) indicates the debug trigger is located at a specific source location in the program unit.
	The Debug Entry option indicates the trigger is fired as soon as program unit execution is suspended.
	The Every Statement option indicates the debug trigger is fired just prior to every executable statement in the program unit.
Program Unit	Identifies the target program unit.
Line	Identifies the source location of the debug trigger in the program unit.
Trigger Body	Type the PL/SQL statements to be used as the body of the debug trigger.  BEGIN and END keywords are not required. A debug trigger works like a conditional break trigger.  If you specify conditions for when a debug action should take place, the trigger is fired only if the conditions are true.   For example, you can raise DEBUG.BREAK if a variable is equal to a certain value, say 100.  IF DEBUG.GETC('vnumber') = 100 THEN   RAISE DEBUG.BREAK; END IF;


Identifies the debug trigger and is of the form Trigger:  New or Trigger:  number.  The label value is New when specifying a new debug trigger, or a number when modifying an existing debug trigger.


Indicates whether the debug trigger is enabled or disabled.


Specifies the source location of the debug trigger.


Identifies the target program unit.


Identifies the source location of the debug trigger in the program unit.


Type the PL/SQL statements to be used as the body of the debug trigger.


PL/SQL Step dialog box

The PL/SQL Step dialog box allows you to set options for stepping through suspended program unit code while debugging, and provides a graphical user interface for the Interpreter's STEP command.

Mode	Specifies which Step option to use.
	INTO resumes execution until the next executable statement.
	OVER resumes execution until the next executable statement in the current program unit, skipping over any subprogram calls.
	OUT resumes execution through a nested subprogram and halts at the next executable statement in the calling program unit.
	TO resumes execution until the specified location is reached.
Program Unit	Identifies the target program unit body for the STEP TO command option.
Line	Identifies the location within the target program unit body for the STEP TO command option.
Count	Specifies the number of times the STEP command is repeated.  The count defaults to one.
Apply	Accepts the specified options and resumes program unit execution accordingly.  Since step operations are usually repeated one after another, the Step dialog box remains displayed until you explicitly close it, or as long as there is an active debug level.


Specifies which Step option to use.


Identifies the target program unit body for the STEP TO command option.


Identifies the location within the target program unit body for the STEP TO command option.


Specifies the number of times the STEP command is repeated.  The count defaults to one.


Accepts the specified options and resumes program unit execution accordingly.  Since step operations are usually repeated one after another, the Step dialog box remains displayed until you explicitly close it, or as long as there is an active debug level.


Load Program Unit dialog
Load Program Unit dialog box

The Load Program Unit dialog box allows you to import and compile a program unit stored on the file system, and provides a graphical user interface for the Interpreter's LOAD command.

File	Type the name (and location) of the file containing the program unit source text.
Browse	Displays your operating system file dialog box.
Suppress Confirmations	Suppresses all confirmation messages during the load and compile-for example, when overwriting an existing program  unit.  The default is disabled, meaning confirmations are not suppressed.
Load	Confirms your selections, loads the program unit, and closes the dialog box.


Type the name (and location) of the file containing the program unit source text.


Displays your operating system file dialog box.


Suppresses all confirmation messages during the load and compile-for example, when overwriting an existing program unit.  The default is disabled, meaning confirmations are not suppressed.


Confirms your selections, loads the program unit, and closes the dialog box.


Interpret Debug Script dialog
Interpret Debug Script dialog box

The Interpret Debug Script dialog box allows you to import and run a script containing any combination of Interpreter commands, PL/SQL source, or SQL statements, and provides a graphical user interface for the INTERPRET command.

File	Type the name (and location) of the file containing the debug script to be interpreted.
Browse	Displays your operating system file dialog box.
Echo	Enables or disables echo mode.  The default is disabled, meaning that each line of the script is not echoed on the Interpreter command line as the script is loaded.
Silent	Enables or disables silent mode.  The default is disabled, meaning that status messages are displayed while the script is loading.
Suppress Confirmations	Suppresses all confirmations during the operation-for example, when overwriting an existing program  unit.  The default is disabled, meaning confirmations are not suppressed.
Interpret	Confirms your selections, runs the script, and closes the dialog box.


Type the name (and location) of the file containing the debug script to be interpreted.


Displays your operating system file dialog box.


Enables or disables echo mode.  The default is disabled, meaning that each line of the script is not echoed on the Interpreter command line as the script is loaded.


Enables or disables silent mode.  The default is disabled, meaning that status messages are displayed while the script is loading.


Suppresses all confirmations during the operation--for example, when overwriting an existing program  unit.  The default is disabled, meaning confirmations are not suppressed.


Confirms your selections, runs the script, and closes the dialog box.


Compile dialog
Compile dialog box

The Compile dialog box displays compilation error messages during batch compilation and allows you to halt and resume compilation as well as navigate to an error source.

Status Line	Specifies the following information while program units are being compiled:
	name and type of the program unit currently being compiled
	[INTERRUPTED] when you click Interrupt
	percentage of program units that have been compiled
Compilation Errors list box	A scrollable, mouse-sensitive area that displays errors encountered during compilation of the selected program units. Click an error in the Compilation Errors list box to display the Program Unit editor and the program unit where the error is located. If you click an error in the Compilation Errors list box while in an interrupted state of compilation (as a result of clicking Interrupt) a message box displays, warning you that going to the source of an error will abandon the batch compilation.
Interrupt	Temporarily stops compilation-for example, when too many errors are being generated.
Resume	Resumes compilation after an interrupt.
Goto Error	Displays the Program Unit editor containing the program unit source at the location of the first error. If you click this button while in an interrupted state of compilation (as a result of clicking Interrupt) a message box displays, warning you that going to the source of an error will abandon the batch compilation. Also displays the PL/SQL Compilation Messages dialog box-a scrollable, mouse-sensitive list box where you can browse all errors encountered during compilation of the selected program units.  Click an error in the list box to display the Program Unit editor and the program unit where the error is located.

If compilation ends with no errors detected, the message Compilation completed successfully is displayed on the status line.  If compilation ends with errors detected, the message Compilation completed with errors is displayed.

The PL/SQL Compilation Messages dialog box is a scrollable, mouse-sensitive list box where you can browse all errors encountered during compilation of the selected program units.  Click an error in the list box to display the Program Unit editor and the program unit where the error is located.


Specifies the following information while program units are being compiled: name and type of the program unit currently being compiled, and percentage of program units that have been compiled.


Temporarily stops compilation-for example, when too many errors are being generated.  Clicking Interrupt displays [INTERRUPTED] on the status line.


Resumes compilation after an interrupt.


Presents the PL/SQL Compilation Messages browser and displays the Program Unit editor containing the program unit source at the location of the first error.


Regular expressions

Regular expressions are strings that can contain any of the following special wildcard characters:

.	Matches any single character.  For example, .he would match both the and she.
( )	Used to force precedence of operators (e.g., +) when the default precedence is not desired.  For example, concatenation of characters (e.g., the) precedes other operators such as +, so that the+A is equivalent to (the)+A.  If instead you wished to match theeeeeeA, you can force + to precede concatenation using parentheses:  th(e+)A.
[ ]	Matches any one of the single characters in the brackets.  The brackets are a logical OR operator.  For example, t[hr]e would match the in other and tre in trend.
|	Used between two regular expressions.  Matches if either regular expression matches.
\	Matches the special character that follows the backslash.  For example, \* would match *.  The backslash is the escape character.  Any special character following it is not treated as a special character. Below are some special uses of the escape character:
	\n matches a newline character
	\t matches a tab character
	\b matches a blank character
	\w matches \n, \t, \b or \0
*	Matches 0 or more instances of the regular expression.  For example, (the)*A would match A, theA, and thetheA.
+	Matches 1 or more instances of the regular expression.  For example, (the)+A would match both theA and thetheA, but it would not match A by itself as (the)*A would.

These characters have special meaning between square brackets:

~	As the first character, matches any characters not found in the characters or ranges inside the brackets.  For example, t[~hr]e would match toe, but not the.
-	Between character pairs, matches any characters in the range.  For example, [A-E] would match the letters A, B, C, D, and E.  Character range pairs can be either of the following:
	• same case alphabetics, in which the first character comes before (or is equal to) the second character in the alphabet
	• digits, in which the first digit is less than or equal to the second digit  (e.g., [4-9] or [0-3]).
	You can also use the escape character between brackets.
Rules:  The order of precedence of the regular expression special characters is as follows:  ( ), [ ], concatenated characters (e.g., abc), *, +, ~,  , |, .

The following examples show some of the implications of the order of precedence:

•	Start|Finish is equivalent to (Start)|(Finish)

•	Start* is equivalent to (Start)*

•	Start|Finish* is equivalent to (Start)|((Finish)*)


PL/SQL Table Elements Selection dialog box

The PL/SQL Table Elements Selection dialog box contains indexes to rows in a selected table, and enables you to select the rows you wish to examine fully expanded in the Object Navigator.

Record Index list box	A scrollable, mouse-sensitive area that contains a list of indexes to all rows in the table.
Select All	Selects all elements in the table.
Deselect All	Deselects all elements in the table.
By default, all indexes are selected.  Deselect individual selections by Ctrl-clicking on them in the list.


Find and Replace in Program Units dialog box

The Find and Replace in Program Units dialog box allows you to perform a global search and replace across multiple program units.

Find What	Type the string you want to find.   If you want the string to be treated as a regular expression, check the Use Expressions check box.
Expression	Display a list of regular expressions you can use in your search criteria.  Click an expression to insert it in the Find What box.
Replace With	Type the string you want to replace the search string with.
Use Expression	Check this box if you are using regular expressions in your search criteria. Uncheck this box if you are not using regular expressions in your search criteria.
Match Case	Check this box to specify that the search be case sensitive. Uncheck this box to find all matches of the search string, regardless of case.
Look Where	Specify where you want to perform the search or search/replace. In Procedure Builder standalone, / represents the topmost Program Units node in the Object Navigator.  All open PL/SQL libraries in the current session are listed below /.   All nodes are selected by default.  If you wish to search in a specific node only, click the node.
Find All	Find all matches of the search string you specified.  No replacement is performed.
Replace All	Replace all matches of the search string with the replacement string you specified.  A message box displays, prompting you for confirmation before the batch replacement is performed.
Close	Close the dialog box.
Help	Display this help topic.
Results list box	Display the occurrences of the matched string found.  The location of each match is indicated by the node, program unit name, and line and column numbers of the source line. The status bar above the list box shows the number of matches found. Click a match to select it for editing or replacing.  You can select more than one match.
Replace	Replace the search string with the replacement string in the matches selected in the Results list box only.
Edit	Open the source of the selected match in the Program Unit editor.


PL/SQL V1 Conversion Options dialog box

Use the PL/SQL V1 Conversion Options dialog box to control how the utility should proceed when it encounters each type of supported PL/SQL V1 or V2 syntax.  Your preferences are saved across multiple invocations of the conversion utility: in either the registry for Microsoft Windows or in a UNIX profile.

Problem type	List of PL/SQL V1 or V2 syntax type situations supported by the conversion utility:  CHAR replaced by VARCHAR2   String length required for VARCHAR2  OUT and IN OUT default expressions removed  NULL added to RETURN in functions  Obsolete built-in  LENGTH function returns NULL for zero-length string  Passing NULL to overloaded subprogram does not resolve properly  Missing RETURN statement in function
Convert	All instances of the selected problem type are automatically converted without confirmation.
Convert All	Fast path for setting all problem types to Convert.  The utility automatically converts all PL/SQL V1 or V2 without confirmation.
Ignore	All instances of the selected problem type are ignored.  To avoid compiler errors, you must modify the V1 or V2 code manually.
Ignore All	Fast path for setting all problem types to Ignore.  The utility ignores all problem types and does not perform any conversion.  To avoid compiler errors, you must modify the V1 or V2 code manually.
Ask me	Displays each instance of the selected problem type individually in the Conversion dialog box.  From the dialog box you can either Convert or Ignore.
Ask All	Fast path for setting all problem types to Ask Me.  The utility prompts you for confirmation (in the Conversion dialog box) before converting a PL/SQL V1 or V2 string.
OK	Confirms your selections and closes the dialog box.
Cancel	Cancels any changes to the module and closes the dialog box.


Conversion dialog box

The Conversion dialog box allows you to interactively control the PL/SQL V1 or V2 conversion process.  To set options for subsequent conversions, click Options.

Source pane	Displays the program unit source where the conversion condition is detected.  The syntax to be converted is highlighted.  You can scroll up or down within this pane to review the conversion accomplished so far.
Condition:	The PL/SQL V1 or V2 statement that requires conversion.
Action:	What the conversion utility will do if you click Convert.
Explain. . .	Displays more details about the problem and what will happen if you decide to ignore the conversion.
Convert	Accepts the recommended default action; moves to the next statement.
Convert All	Converts all PL/SQL V1 or V2 syntax problems in the entire module, which may contain multiple program units.  All default actions are accepted.
Ignore	Does not convert the PL/SQL V1 or V2 statement described in the Problem field; moves to the next statement.
Ignore All	Bypasses the conversion process for the entire module, which may contain multiple program units.
Options. . .	Displays the PL/SQL V1 Conversion Options dialog box, in which you can specify options to control the conversion process.


PL/SQL V1 Conversion Summary dialog box

The PL/SQL V1 Conversion Summary dialog box provides information such as:

•	source lines that were converted successfully

•	source lines that were ignored

•	source lines that generated PL/SQL compiler errors.

Toolbar buttons:

X icon	Closes the dialog box.
? icon	Displays dialog box help.
Summary pane:

Find	Provides standard search capabilities for both expanded and collapsed nodes.
node	One for each program unit in the module. If the node contains a plus sign, click it to display a summary of what was converted (and how) and what was ignored. If a node is empty (no plus or minus sign), the program unit did not require conversion. To address compiler errors-or to review the converted source or the items you ignored-double click a line in an expanded node. (Or select the line and select Program [image] Program Unit Editor.)  The editor opens with the cursor positioned at the selected line. Note:  After you change the source using the Program Unit editor,  the cursor may not be correctly positioned the next time you double-click a line or use the Edit button.
Menu items:

The Program menu provides two options:

Program Unit Editor	Opens the source in the Program Unit editor. The cursor is positioned at the line you select.
Conversion Options	Displays the Conversion Options dialog box so you can view or modify the options you specified.
Pop-up menu:

Click the right mouse button to display a pop-up menu.

Edit	Opens the source in the Program Unit editor.  The cursor is positioned at the line you select.
Explain	Displays online help about the type of conversion for the selected line.


The Program Unit editor interface

  Related Topics

The buttons and drop-down list box are:

Compile	Compiles the current program unit.  Any error messages generated as a result of the compilation will appear in the scrollable Compilation Messages pane.
Apply	Saves any changes made to the program unit since it was first opened or since the last apply or revert operation.  The program unit is not recompiled.  The editor remains open.  The undo/redo stack is cleared.
Revert	Restores the program unit to its state at the last apply or revert operation.  If no apply or revert operations have occurred, the program unit is returned to its original state.
New	Displays the New Program Unit dialog box, where you can specify the type and name of the program unit you wish to create.
Delete	Deletes the current program unit.  A message box displays to prompt you for confirmation.
Close	Closes the Program Unit editor.
Help	Displays this help topic.
Name	Displays the name of the current program unit.  Click the arrow to the right of the box to display a drop-down list of existing program units in the current session.  Click a program unit on this list to display that program unit in the Source pane.

In addition, the following elements make up the editor:

Source pane	Area for typing and editing PL/SQL program unit source text.   Split bars enable you to create up to four separate views of the current program unit.  Each view can be scrolled independently.   To create horizontal views in the Source pane, place the cursor on the split bar at the top of the vertical scroll bar, and double-click.  This splits the Source pane horizontally into two equal-sized views.  Alternatively, you can click and drag the split bar down to create the view sizes that you want.  To create vertical views, place the cursor on the split bar at the far left of the horizontal scroll bar, and double-click.  This splits the Source pane vertically into two equal-sized views.  Alternatively, you can click and drag the split bar to the right to create the view sizes that you want. To resize views, click and drag the split bar that separates the views. To remove a horizontal or vertical view, double-click the split bar that separates the views, or drag it to the edge of the pane. To remove all four views at once, place the cursor on the intersection of the split bars and double-click, or drag it to any corner of the pane. To select a line of code, place the cursor on the left margin and click.
Compilation Messages pane	Displays error messages, if any, generated as a result of compilation.  Clicking on an error message highlights it, scrolls the Source pane to the source statement that is producing the error, and positions the text cursor at the location of the error in the statement. By default, the Compilation Messages pane displays only when there are error messages generated during compilation. To manually display the Compilation Messages pane at any time, move the cursor to the bottom right corner of the editor window until the cursor changes to cross-hairs.  Then click and drag the cursor up.  This moves the split bar up, revealing the Compilation Messages pane below.
Split bar (separating panes)	Separates the Source pane and the Compilation Messages pane.  Enables you to change the relative size of the panes.  Click and drag the split bar to resize the panes. If the Compilation Messages pane is not displayed, the split bar is actually near the bottom of the editor window.
Status bar	Displays information about the current state of the program unit at the bottom of the editor.


Compiles the program unit appearing in the Source pane.  Any error messages generated as a result of the compilation will appear in the scrollable Compilation Messages pane.


Saves any changes made to the program unit in the editor since it was first opened or since the last apply or revert operation.  The program unit is not recompiled.  The editor remains open.


Restores the program unit to its state at the last apply or revert operation.  If no apply or revert operations have occurred, the program unit is returned to its original state.


Displays the New Program Unit dialog box, where you can specify the type and name of the program unit you wish to create.


Deletes the displayed program unit, with confirmation.


Attempts to close the editor.  If any changes have been made but not applied, a message box displays, prompting you to apply or revert the changes or cancel the operation.  Once all changes have been applied or reverted, the Program Unit editor is closed.


Specifies the type of program unit (trigger, procedure, etc.) currently displayed in the editor.


Specifies with what object the program is associated.


Displays the name of the current program unit.  Press the arrow to the right of the field to display a drop-down list of other existing program units.  Click a program unit on this list to display that program unit in the editor.


Type and edit PL/SQL program unit source text.


Displays syntax errors encountered during compilation.  Click on an error to navigate to its source in the program unit.


Enables you to change the relative amount of space occupied by the two panes (source and compilation messages) in the Program Unit editor.  Note that by default, the Compilation Messages pane is displayed only when error messages are generated during compilation.


The left side of the status bar displays the following messages:

Not Modified	No changes have been made to the program unit since it was first displayed or last applied.
Modified	One or more changes have been made to the program unit since it was first displayed or last applied.

The right side of the status bar displays the following messages:

Not Compiled	The program unit source text currently displayed has not been compiled.
Successfully Compiled	The program unit source text currently displayed compiled with no errors.
Compiled with Errors	The program unit source text currently displayed compiled with errors.  The errors appear in the Compilation Messages pane.


Editing features

  Related Topics

The editing features in the Program Unit editor (and Stored Program Unit editor) include:

Automatic indent	When you press the Enter key at the end of a line, the next line is automatically indented.
Color syntax highlighting	Keywords, comments, strings, and symbols such as := and || are colored differently.
Column and line selection	You can select columns of text as well as lines of source code. To select a column, press the ALT key, then click and drag horizontally. To select a line, click on the extreme left margin of the line in the Source pane.
Drag and drop text manipulation	Selected text may be copied or moved by dragging and dropping. To copy text, press the CTRL key and drag the selected text. To move text, simply drag the selected text.
Indent/Outdent lines	The  Indent/Outdent commands in the Edit menu enable you to indent or outdent selected source lines.
Multiple split views	You can create up to four separate views of the current program unit. To create horizontal views, place the cursor on the split bar at the top of the vertical scroll bar. Then click and drag the split bar down. To create vertical views, place the cursor on the split bar at the far left of the horizontal scroll bar.  Then click and drag the split bar to the right. To remove a horizontal or vertical view, double-click the split bar that separates the views.
Printing	Choose File [image] Print to print the current program unit.
Unlimited undo/redo	The Undo/Redo commands on the Edit menu enable you to undo or redo changes as far back as the last save operation.

Note: These features are available in Microsoft Windows only.  In UNIX, you can do the following only:

•	print the current program unit

•	use TAB and Shift-TAB to indent and outdent selected lines

•	move selected text by dragging and dropping


Using the mouse in the editor

  Related Topics

The following mouse actions are supported when using the Program Unit editor (and Stored Program Unit editor) in Microsoft Windows:

To do this:	Mouse action:
Select characters in a range	Click and drag the cursor from the first character to the last character in the range you wish to select. (also supported in UNIX) Or, Click the first character, then press the Shift key, and click the last character in the range you wish to select.
Select word under cursor	Double-click the word. (also supported in UNIX) Or,  Press the Ctrl key, then click the word you wish to select.
Select words in a range	Press the Ctrl key, then click and drag the cursor from the first word to the last word in the range you wish to select.
Select a line	Place the cursor on the the left margin of the line you wish to select.  Click when the cursor changes to an arrow.
Select multiple lines	Place the cursor on the the left margin of the first line you wish to select.  When the cursor changes to an arrow, click and drag the cursor to the last line you wish to select.
Select columns of text	Press the Alt key, then click and drag the cursor from the first column to the last column in the range you wish to select.
Move selected text	Select the text first. Then click and drag the selected text to its new position. (also supported in UNIX)
Copy selected text	Select the text first.  Then press the Ctrl key, and drag the selected text to the location where you want to place a copy and release the mouse.
Split window into two horizontal views	Double-click the split bar at the top of the vertical scroll bar. Or, Click and drag the split bar at the top of the vertical scroll bar.
Split window into two vertical views	Double-click the split bar at the extreme left of the horizontal scroll bar. Or, Click and drag the split bar at the extreme left of the horizontal scroll bar.
Adjust relative size of split views	Click and drag the split bar that separates the views.
Remove split views	Double-click the split bar that separates the views. Or, Click and drag the split bar to the edge of the window. To remove all four views at once, double-click the intersection where the split bars meet or drag it to any corner of the window.


Using the keyboard in the editor

  Related Topics

The following keyboard actions are supported when using the Program Unit editor (and Stored Program Unit editor) in Microsoft Windows and UNIX:

To do this:	Keystroke:
Move cursor left one character	Left arrow key
Select character as cursor moves left	Shift + Left arrow key
Move cursor right one character	Right arrow key
Select character as cursor moves right	Shift + Right arrow key
Copy selected characters or words	Ctrl + C
Cut selected characters or words	Ctrl + X
Paste from the clipboard	Ctrl + V
Delete character on the right of current cursor position, or delete selected characters or words	Delete key
Delete character on the left of current cursor position	Backspace
Move cursor to the end of the program unit	Ctrl + End	(Windows only)
Move cursor to the start of the program unit	Ctrl + Home	(Windows only)
Select source lines from the current cursor position to the end of the program unit	Ctrl + Shift + End	(Windows only)
Select source lines from the current cursor position to the start of the program unit	Ctrl + Shift + Home	(Windows only)
Move cursor to the end of current line	End	(Windows only)
Move cursor to the start of current line	Home	(Windows only)
Select characters from the current cursor position to the end of the current line	Shift + End	(Windows only)
Select characters from the current cursor position to the start of the current line	Shift + Home	(Windows only)
Indent selected line, or indent characters on the right of current cursor position	Tab key
Outdent selected line	Shift + Tab key
Move cursor down one line	Down arrow key
Select line as cursor moves down	Shift + Down arrow key
Move cursor up one line	Up arrow key
Select line as cursor moves up	Shift + Up arrow key
Scroll down the program unit by the number of lines that are shown in the Source pane	PageDown key
Scroll down the program unit by the number of lines that are shown in the Source pane and selects the lines at the same time	Shift + PageDown key
Scroll up the program unit by the number of lines that are shown in the Source pane	PageUp key
Scroll up the program unit by the number of lines that are shown in the Source pane and selects the lines at the same time	Shift + PageUp key
Undo most recent action	Ctrl + Z	(Windows only)
Revert most recent undo action	Ctrl + Y	(Windows only)


The Stored PL/SQL editor interface
The Stored Program Unit editor interface

  Related Topics

The buttons and drop-down list boxes are:

New	Displays the New Program Unit dialog box, where you can specify the type and name of the stored program unit you wish to create.
Save	Compiles the current stored program unit.  Any error messages generated as a result of the compilation will appear in the scrollable Compilation Messages pane. The undo/redo stack is cleared.
Revert	Restores the stored program unit to its state at the last save or revert operation.  If no save or revert operations have occurred, the program unit is returned to its original state.
Drop	Drops the current stored program unit from the database. A message box displays to prompt you for confirmation.
Close	Closes the Stored Program Unit editor.
Help	Displays this help topic.
Owner	Displays the database user ID of the owner of the current program unit.  Click the arrow to the right of this box to display a drop-down list of user names.  The Owner list displays only the names of those users whose stored program units you have access to.
Name	Displays the name of the current stored program unit.  Click the arrow to the right of this box to display a drop-down list of stored program units owned by the user ID shown in the Owner field.  The Name list displays only the names of the stored program units to which you have been granted access.

In addition, the following elements make up the editor:

Source pane	Area for typing and editing PL/SQL program unit source text.   Split bars enable you to create up to four separate views of the current program unit.  Each view can be scrolled independently.   To create horizontal views in the Source pane, place the cursor on the split bar at the top of the vertical scroll bar, and double-click.  This splits the Source pane horizontally into two equal-sized views.  Alternatively, you can click and drag the split bar down to create the view sizes that you want.  To create vertical views, place the cursor on the split bar at the far left of the horizontal scroll bar, and double-click.  This splits the Source pane vertically into two equal-sized views.  Alternatively, you can click and drag the split bar to the right to create the view sizes that you want. To resize views, click and drag the split bar that separates the views. To remove a horizontal or vertical view, double-click the split bar that separates the views, or drag it to the edge of the pane. To remove all four views at once, place the cursor on the intersection of the split bars and double-click, or drag it to any corner of the pane. To select a line of code, place the cursor on the left margin and click.
Compilation Messages pane	Displays error messages, if any, generated as a result of compilation.  Clicking on an error message highlights it, scrolls the Source pane to the source statement that is producing the error, and positions the text cursor at the location of the error in the statement. By default, the Compilation Messages pane displays only when there are error messages generated during compilation. To manually display the Compilation Messages pane at any time, move the cursor to the bottom right corner of the editor window until the cursor changes to cross-hairs.  Then click and drag the cursor up.  This moves the split bar up, revealing the Compilation Messages pane below.
Split bar	Separates the Source pane and the Compilation Messages pane.  Enables you to change the relative size of the panes.  Click and drag the split bar to resize the panes. If the Compilation Messages pane is not displayed, the split bar is actually near the bottom of the editor window.
Status bar	Displays information about the current state of the stored program unit at the bottom of the editor.


Displays the New Program Unit dialog box, where you can specify the type and name of the program unit you wish to create.


Compiles the stored program unit appearing in the Source pane.  Any error messages generated as a result of the compilation will appear in the scrollable Compilation Messages pane.


Restores the stored program unit to its state at the last save or revert operation.  If no save or revert operations have occurred, the program unit is returned to its original state.


Drops the current stored program unit from the database, with confirmation.


Displays the database user ID of the owner of the current program unit.  Click the arrow to the right of this field to display a drop-down list of user names whose stored program units to which you have access.


Displays the name of the current stored program unit.  Click the arrow to the right of this field to display a drop-down list of stored program units owned by the user ID shown in the Owner field.  The Name list displays only the names of the stored program units to which you have been granted access.


Used to enter and edit PL/SQL stored program unit source text.


Displays syntax errors encountered during compilation.  Click on an error to navigate to its source location in the program unit.


Enables you to change the relative amount of space occupied by the two panes in the Stored Program Unit editor.  Note that by default, the Compilation Messages pane is displayed only when error messages are generated during compilation.


The Syntax Palette interface

The Syntax Palette enables you to display the constructs of PL/SQL language elements and built-in packages, and allows you to copy selected syntax into the Program Unit editor or Stored Program Unit editor.

The Syntax Palette has the following components:

PL/SQL page	Allows you to display and select a PL/SQL language element for copying.  The PL/SQL language elements are grouped by categories such as Control Flow, Cursors, Exceptions and so on.
Built-ins page	Allows you to display and select a PL/SQL construct (function or procedure) from a built-in package for copying.
Drop-down list	Displays a PL/SQL category name or a built-in package name.   Click the arrow on the right to choose a PL/SQL category or built-in package.
List area	Displays the individual language elements in a selected PL/SQL category or the constructs in a selected built-in package.  The first item in the list is highlighted (selected) by default.   Click a language element or construct to select it and to show its full syntax in the display area.   Double-clicking an item inserts the syntax of the PL/SQL language element or construct into the active editor window at the current cursor position.
Display area	Shows the full syntax of a selected PL/SQL language element or construct.
Insert	Click to copy the selected item in the list area to the current cursor position in the active editor window.
Close	Click to close the Syntax Palette.
Help	Displays this help topic.


Displaying the Syntax Palette

To display the Syntax Palette:

  Choose Program [image] Syntax Palette.


Closing the Syntax Palette

To close the Syntax Palette:

  Click the Close button.


Inserting syntax into an editor

  Related Topics

To copy syntax into an editor:

1	Make sure the Program Unit editor or Stored Program Unit editor is the current (most recently selected) window.

2	Place the cursor in the editor where you want to insert the syntax.

3	In the Syntax Palette, click the PL/SQL tab or the Built-ins tab.

4	Choose a PL/SQL category or a built-in package from the drop-down list.

When you click a category or a package, the PL/SQL language elements or PL/SQL constructs that are available for selection appear in the list area below.

5	Choose a PL/SQL language element or construct in the list area.

When you click a PL/SQL language element or construct, the syntax appears in the display area that is below the list area.

6	Click Insert to copy the selected syntax.

The selected PL/SQL language element or construct is inserted into the active editor at the current cursor position.

Replace all lowercase items that are not comments with the appropriate values.  Items within comments are optional.  Reserved words are in uppercase.

Note:  You can also double-click a PL/SQL language element or construct in the list area to insert the syntax into the editor.


About source control

  Related Topics

Source control is the process of managing and maintaining multiple revisions of the same file in an archive.

An archive is a user-defined directory that contains a text version of the file as well as information about each revision of the file, including a description of all file changes and when they were made.

Using an archive, a member of your development team can retrieve, modify, and return any revision of a file in a safe and consistent manner.

Components (e.g., Form Builder) provides source control in via a generic interface to any source control provider you want to use.  Plug-in modules are currently available for the Polytron Version Control System (PVCS) from INTERSOLV and Pure-Atria Clearcase, with others forthcoming.

For information on installing and using PVCS, refer to your INTERSOLV documentation.

PVCS also supports file locking and archive reporting.


About configuration files

There are four environment variables that should be set for optimum performance of the source control interface.  Under Windows 3.1 these are set in oracle.ini, while under Windows NT or Windows 95/98 these are set in the registry, in the SOFTWARE/ORACLE key.

DEV2000_SOURCECONTROL specifies which source control system to use.  This should be set to "PVCS".  Since components (e.g., Form Builder) defaults to use PVCS, omitting this variable will not have any noticeable effect in this release.  However, as support for more source control systems is added, setting this variable will ensure that the source control interface functions as intended.

DEV2000_PROJECT  replaces the TVCCFG variable from Forms Developer release 1.0 and 1.1, and identifies the PVCS project configuration (.CFG) file that should be used.  If you do not specify a project configuration file via an environment variable, you will need to choose one from the Source Control Options dialog box in each session.

DEV2000_SCVIEWER controls what program is used to view the results of a source control log or difference report operation.  To disable viewing the results, set this variable to null (no value).

DEV2000_SCCONVERT controls whether files are converted to ASCII before checking them in to PVCS, and converted back to binary before checking them out.  Unless you are upgrading from using PVCS with a prior version of Forms Developer, and want to preserve this behavior, you should leave this entry set to its default of FALSE.

A sample fragment of oracle.ini might be:

...

DEV2000_SOURCECONTROL=PVCS

DEV2000_PROJECT=C:\PROJECTS\MYPROJ\MYPROJ.CFG

DEV2000_SCVIEWER=NOTEPAD.EXE

DEV2000_SCCONVERT=FALSE

...


About PVCS implementation

When you check in certain objects (forms, menus, reports, displays, PL/SQL libraries) the binary file is automatically converted to the text-file equivalent, and the text file is checked in to the source control.  For example, if you checked in MYFORM.FMB, MYFORM.FMB would automatically convert to MYFORM.FMT (the text equivalent) and then check MYFORM.FMT in to source control.

Similarly, when you check out an archived file, it converts the text version of the file to the equivalent binary format that can be read by the designer interfaces.  If you were to check out MYFORM.FMT, it would be converted to MYFORM.FMB so that you could edit it.

Archiving is done on the text version of the file to permit more meaningful Difference Reports to be generated between different revisions of a file.  While PVCS does support archiving binary files, difference reporting between revisions of binary files is not possible.

This file conversion can lead to extra files being left in your working directory, depending on PVCS settings.  If your project is configured to make working files read-only after check-in, you will have both the binary file, and a read-only text-format file, present in your directory.  However, if your project is configured to delete working files after check-in, only the binary file will remain present in your working directory.


About checking in a file

  Related Topics

Each time you modify a file and check it into an archive, it becomes a new revision.  When you check in a file (e.g., a PL/SQL library file with an extension of .pll), PVCS performs a binary-to-text conversion automatically and archives the file in the specified location as a text file with the appropriate file extension (e.g., .pld).  PVCS uses the text file to generate archive reports.

A version label identifies a revision as one of a group of revisions that typically make up a complete version of your application.  Version labels enable you to operate on all of the files associated with a particular version at the same time by referencing a single name.  If you have already archived a version of the current module, the appropriate information automatically enters in the Archive field.


About checking out a file

  Related Topics

Checking a file out of an archive gives you access to it for browsing, editing, or printing.  By default, only one user at a time can check out a particular revision with a lock.

When you check out a file, the file automatically converts from the archived text version to the proper format (for example, the conversion of a PL/SQL library file from pld to .pll).  The file you check out of an archive is called a workfile.  Each time you check in a new variation of a workfile, it becomes a revision.


About creating archive reports

  Related Topics

PVCS enables you to generate reports that summarize the following archive activities:

•	creation of archives

•	attributes of archived files

•	successive revisions

•	label names

•	lines changed in the last revision

•	description of the workfile


About promotion models

A promotion model is a hierarchy of milestones in a development cycle.  You use promotion to control the development of source code from the design phase to final release.  Each milestone is represented by a promotion group.  Examples of promotion groups include Development, Quality Assurance, and Production.  A promotion model is an advanced feature, and is recommended for sites with formal software turnover procedures.

A promotion model can have one ore more lowest-level, or development, groups.  When a promotion model is in effect, users can only modify revisions that are associated with a development group.  To edit a revision associated with a higher group, a user must check it out and reassociate it with a development group at check out, then repromote it to a higher group after checking it back in.

If the promotion model only includes one development group, only one revision in the archive can be locked at a time.  To design a promotion model for parallel development, you must include at least two development groups.

You can define any number of intermediate promotion groups above the development group(s) for various stages of testing or preliminary releases.  At the highest level is the production group, which usually indicates that revisions are ready for final release.

Using a promotion model enables you to:

•	Quickly determine project status.  You can run an archive report on project in a project to immediately determine which modules have not reached a particular milestone in the development cycle.

•	Control revision access on non-development levels.  Because users cannot modify revisions associated with post-development promotion groups, you ensure that all revisions are thoroughly tested.

•	Custom-design your own model.  You can custom-design a promotion structure that is uniquely suited for each project, with any number of milestones in the promotion structure.


Creating an archive directory

  Next Step	  Related Topics

To create an archive directory:  Note:

1	Choose File [image] Administration [image] Source Control Options to display the Source Control:  Options dialog.

2	If it is not already selected, select the Project tab.

3	Specify the name and location of your archive directory In the New Archive Directory field.

4	Click Add new directory to list and then click Close to close the dialog.


You cannot add archive directories unless you have already defined the DEV2000_PROJECT parameter in the oracle.ini file.  On Microsoft Windows, define the DEV2000_PROJECT parameter as follows:

DEV2000_PROJECT=C:\PVCS\PROJECT1\PROJECT1.CFG

You edit the DEV2000_PROJECT parameter using the Oracle.ini file for Windows 3.1 and the Registry for Windows 95/98 and NT.


Checking in a file

  Next Step	  Related Topics

To check in a file:

1	Choose File [image] Administration [image] Check-In to display the Source Control: Check-In dialog.

2	Type the name of the file to archive in the Work File text box.

3	Specify the location of your archive in the To Archive field.

4	(Optional)  Provide a Version Label, Promotion Group, and Description.

5	(Optional)  Click the Retain lock after checkin check box if you want a writable copy of the archive file to remain locally even after the file is checked in.  Having a writable copy of the file allows you to modify and check in subsequent changes to the file without having to first check the file out.

6	Click OK to check in your file.

PVCS archives your file.


Checking out a file

  Next Step	  Related Topics

To check out a file:

1	Choose File [image] Administration [image] Check-Out to display the Source Control:  Check-Out dialog.

2	Specify the location of the source archive in the Source Archive field.

3	Type the name of the file you want to check out in the File Name text box.

4	Select the desired file revision in the Revisions field.

5	(Optional)  Specify the desired destination by entering a path in the Destination field.

6	(Optional)  If you intend to lock the file you are checking out, you must choose the Development-level Promotion Group that will be assigned to the revision you are checking out.

7	(Optional)  Click the Lock file at checkout check box.  Note:

8	(Optional)  Click the Open file after checkout check box.  If this box is checked, the file you checked out will be opened in the designer after it has been checked out of PVCS.

9	Click OK to check out your file.


If you intend to modify an archive file, you must enable the Lock file at checkout check box in order to check in your changes.  Otherwise, a read-only version of the file will be checked out.


Creating an archive report

  Related Topics

To create an archive report:

1	Choose File [image] Administration [image] Source Control Options.

2	Click the Reporting tab to display the Source Control:  Reporting Options page.

3	Specify the location of the archive in the Archive field.

4	Specify the name of the desired archive file in the Source File field.  PVCS will generate a report based on the comparison between this file and the target file.

5	Specify the name of a target file In the Target File field.  Note

6	Select the desired file revisions in the Source Revision and Target Revision fields, respectively.

7	Specify the name and location of your report in the Output File field, then click Run Report.

PVCS creates your report.  If a viewing program is specified via the DEV2000_SCVIEWER environment variable or oracle.ini parameter, it will be called to display the output.  Otherwise, use an editor to open your report file.


If you are comparing two revisions within the same archive, enter the name of the archive file that you entered in step 4.  If you are comparing different archive files, specify a different archive file in the Target File field.


Source control: Check In dialog

  Related Topics

Merges the desired file into the specified archive.

The Check-In dialog includes the following options:

Work File	Specifies the name of the file you are checking in.  Choose Browse to invoke a file dialog from which you can select a file.
To Archive	A drop-list of all available archives for the current project.  Select an archive from the list where the file is to be checked in.
Version Label	(Optional)  Specifies the file version label.
Promotion Group	If a promotion model is defined for your PVCS project, this list is enabled.  Choose the Development-level promotion group that is to be assigned to the revision you are checking in.
Description	Specifies a description of the changes made for this revision.  Although optional, it is recommended that you enter a change description to make it easier to identify revisions at check-out.
Retain lock after checkin	Specifies whether a writable copy of the archive file should remain locally even after it is checked in.  Having a writable copy of the file allows you to make subsequent changes to the file without having to first check the file out.


Source control: Check Out dialog

  Related Topics

Retrieves the specified file from an archive so you can edit it.

The Check-Out dialog includes the following options:

Source Archive	Specifies the directory name of the archive from which the file should be checked out.
File Name	Specifies the name of the file you want to retrieve from source control.  Choose Browse to invoke a file dialog from which you can select a file.
Revisions	Displays the available revisions and version labels of the file selected in the File Name field.
Description	Lists descriptions of the available revisions listed in the Revisions list.
Destination	(Optional)  Specifies the destination directory for the file being checked out.
Promotion Group	If a promotion model is defined for your PVCS project, this list is enabled.  If you intend to lock the file you are checking out, you must choose the Development-level promotion group that will be assigned to the revision that you are checking out.
Lock file at checkout	Specifies whether the file being checked out should be marked as locked.  A locked file is protected against update by other users.
Open file after checkout	If you check this box, the file you checked out will be opened in the designer after it has been checked out of PVCS.


Source control: Options dialog

  Related Topics

The Options dialog includes three tabs:

Project Options

Files Options

Reporting Options


Source control: Project Options page

  Related Topics

Enables you to add and remove archive directories from your project configuration file.

The Project Options page includes the following settings:

Current project	The name of the current PVCS project configuration file.  Its initial value is the value of DEV2000_PROJECT in the oracle.ini  file.  You can enter a file name directly, or click Browse to display your operating system file dialog.
New Archive Directory	Specifies a new archive directory to add to the list of available archive directories in the current project.  You can type a directory name or click Browse to display your operating system file dialog.
Archive Directory List	Shows the archive directories available in the current project.
Add new directory to list	After entering an archive directory in the New Archive Directory text box, click Add new directory to list to add the directory to the current project.  The directory will appear in the list once added.
Remove selected directory from list	Select an archive directory from the list and click Remove selected directory from list to remove the directory from the project.


Source control: Files Options page

  Related Topics

Enables you to lock or unlock an archive, or generate a log of activity on that archive.

The Files Options page includes the following settings:

Archive	A drop-down list of all archive directories in the current project configuration file.
File Name	Specifies the archive file to access.  You can enter the name directly, or choose a file with Browse.  If your PVCS project is configured to ignore workfile paths, you can specify either a work file or an archive file.  Otherwise, be sure to specify an archive file only.
Revision	This drop-down list shows all available revisions and version labels of the selected file, as well as having an empty entry indicating no selection.  If you select a specific revision, that revision will be locked or unlocked.  If you do not select a revision, the behavior for locking depends on whether there is a promotion model defined.  If no model is defined, the tip revision will be locked.  If a model is defined, the revision currently assigned to the designated promotion group will be locked.  The behavior for unlock with no revision selected is always to release all locks you own on the file.
Promotion Group	If a promotion model is defined for your PVCS project, this list is enabled, and displays all Development-level promotion groups in your promotion model.  When you lock a revision, the promotion group shown in this list will be assigned to it.
Log File Name	Specifies the name of the log file
Log Type	Specifies the type of updates that should be entered in the specified log file when a check-in our check-out occurs.
Lock Revision	Locks the file specified in the File Name field, without retrieving it from source control.  A locked file is protected against update by other users.  If you selected a specific revision from the Revision list, that revision will be locked.  If you did not select a revision, the tip revision (or the revision currently assigned to the designated promotion group) will be locked.  If a promotion model is defined for your PVCS project, the designated promotion group will be assigned to the revision being locked.
Unlock Revision	Unlocks the file specified in the File Name field, allowing other users to check out and modify the archive file.  If you selected a specific revision from the Revision list, that revision will be unlocked.  If you did not select a revision, all locks that you own on any revisions of the file will be released.
Generate Log	Generates a log file with the specified name.  The type of entries in the log file are determined by the setting of the Log Type option.  If a viewing program is specified via the DEV2000_SCVIEWER environment variable or oracle.ini parameter, it will be called to display the output.


Source control: Reporting Options page

  Related Topics

Enables you to define and create archive reports.

The Reporting Options page includes the following settings:

Archive	A drop-down list of all archive directories in the current project configuration file.
Source File	Specifies the first file to use for difference reporting.  You can enter the name directly, or choose a file with the adjacent Browse button.  If your PVCS project is configured to ignore workfile paths, you can specify either a work file or an archive file.  Otherwise, be sure to specify an archive file only.
Source Revision	A drop-down list of all available revisions and version labels of the source file.
Target File	Specifies the name of the target file.  PVCS generates a report based on a comparison of the source file and the target file.
Target Revision	A drop-down list of all available revisions and version labels of the target file.
Output File	Specifies the destination directory and file name that the differences report should be written to when comparing one file to another.
Run Report	Creates a report according to the options specified.  If a viewing program is specified via the DEV2000_SCVIEWER environment variable or oracle.ini parameter, it will be called to display the output.


Error messages

The following are error messages you may encounter while using the Source Control Interface Dialogs:

D2SCP-001:	File access denied by File System

 Cause:	You do not have file system access privileges to either read the archive file, write the work file, or write log or report output.

 Action:	If you believe you should have file system access to these files, contact your system administrator.

D2SCP-002:	Insufficient Version Manager access privileges

 Cause:	You do not have PVCS privileges to access the archive you had specified.  You will also see this error if changing archive directories has been disabled in the Master Project and you attempt to change them in the Project Options tab of the Options dialog.

 Action:	If you believe you should have access to that archive, contact your PVCS administrator.

D2SCP-003:	Archive already exists

 Cause:	This indicates an internal error and should not be encountered.

 Action:	If it persists after repeating the operation you attempted, contact Oracle Customer Support.

D2SCP-004:	Cannot find the specified archive

 Cause:	You entered or selected a file that was not an archive, when an archive file is required.  A common cause of this is selecting the work file instead of the archive file (for example, MYFORM.FMB instead of MYFORM.FMV).

 Action:	Use the Browse button to choose an archive file.

D2SCP-005:	Invalid filename: Drive or path is nonexistent, or filename contains invalid characters

 Cause:	The filename you entered is not a valid operating system file name.

 Action:	Check the file name syntax for errors.

D2SCP-006:	File is in use by another process

 Cause:	The file you are trying to access is in use by another PVCS user.

 Action:	If you retry the operation after a short wait, it will generally succeed.

D2SCP-007:	Conversion Failed.  Workfile may be read-only or an unsupported type.

 Cause:	The possible causes of this error include:

A.	Your work file may be read only.  This will happen if you check out the file without locking it, and then later lock it from the Options Dialog.

B.	You attempted to check in or out a file that is of a type that  is not recognized.

 Action:	You can take the following action(s) to correct this error:

If A.	Use the Windows File Manager or Explorer to make the file writeable before proceeding.

If B.	Check the file in or out using the stand-alone PVCS interface.

Note that you can check out any file, but can only check in files that are recognized.  This is because Forms Developer can only determine if it’s a supported file type from the workfile.  When checking in, you have the workfile. so Forms Developer tests the file before check-in.  When checking out, the file is first checked out to obtain the workfile.  Only then can Forms Developer test the file.  So you can safely ignore this error on checkout if you know that you are checking out a non-Forms Developer file type.

D2SCP-008:	Invalid or insufficient values

 Cause:	This indicates an internal error and should not be encountered.

 Action:	If it persists after repeating the operation you attempted, contact Oracle Customer Support.

D2SCP-010:	Specified version label already exists

 Cause:	You specified a version label in the Check-In dialog that already exists for the file you are checking in.  PVCS requires version labels to be unique.

 Action:	Change the label.  To see labels in use, use the Log feature from the File Options tab of the Options Dialog.

D2SCP-011:	Specified revision does not exist

 Cause:	This indicates an internal error and should not be encountered.

 Action:	If it persists after repeating the operation you attempted, contact Customer Support.

D2SCP-012:	Invalid configuration file specified

 Cause:	The possible causes of this error include:

A.	The file you chose in the Project Options tab of the Options Dialog is not a valid PVCS configuration file.

B.	If you encounter this error when attempting to access the Check-In or Check-Out dialogs, it means that the configuration file specified in the DEV2000_PROJECT environment variable is invalid.

 Action:	You can take the following action(s) to correct this error:

If A.	Select another, valid, file.

If B.	Modify the variable, or use the Project Options tab of the Options Dialog to set a valid configuration file.

D2SCP-013:	You must first choose a project from 'Source Control Options'

 Cause:	You tried to access the Check-In or Check-Out dialogs, but had not specified a project, either through the DEV2000_PROJECT variable in the ORACLE.INI file, or on the Project Options tab of the Options Dialog.

 Action:	You need to go to the Project Options tab and select a project before continuing.

D2SCP-014:	Unable to update project configuration file.

 Cause:	You tried to add or remove archive directories from the project configuration file, but do not have write permission to the file or directory where the file is located.

 Action:	Consult your PVCS or system administrator if you believe you should have this access permission.

D2SCP-015:	Revision is not locked.

 Cause:	You tried to check in a revision you do not have locked, or unlock a revision that you have not locked (from the File Options tab).

 Action:	If you have made modifications, lock the revision from the File Options tab before checking it in.

D2SCP-016:	Unable lock specified Revision.

 Cause:	You tried to check out a revision with a lock from the Check-Out dialog, or lock a revision from the File Options tab, but PVCS was unable to grant you the lock.  Possible causes for this error include:

A.	The revision is already locked by you or someone else.

B. 	Your project does not allow multiple locks, and the revision is already locked.

C. 	If your project has a promotion model, the promotion group you specified may already be assigned to a locked revision.

 Action:	You can take the following action(s) to correct this error:

If A.	Use the Log feature to see who has the lock, and if you have already locked the revision, check it out without requesting a lock.  If someone else has locked the file, wait for them to release the lock before checking out the file for modification.

If B.	Either wait for the revision or file to become available, or consider allowing multiple locks per file in the project.

If C.	Either wait for that promotion group to become available (not assigned to a locked revision) or use another development-level promotion group.

D2SCP-017:	Specified directory does not exist.

 Cause:	You specified a directory that does not exist.  A common cause of this error is checking out a file where the location from which it was checked in does not exist on your workstation.

 Action:	If this is the case, edit the destination field to point to an existing directory.

D2SCP-018:	Unable to redirect output to file

 Cause:	The file name you specified for the log or difference report output is invalid, or the file could not be opened for writing.

 Action:	Specify a valid, writeable file.

D2SCP-100:	PVCS Error number - keyword

 Cause:	An error was returned from PVCS that the source control interface could not process.

Action:	Consult your PVCS documentation using the error number or error keyword to look up the error, and take action accordingly.


Why doesn't the PVCS configuration manager interface show the new files or revisions?

After I check in files and assign version labels, the PVCS configuration manager interface doesn’t show the new files or revisions.  What do I do?

The project folder needs to be updated with the new information that’s in the archives (new files and revisions).  To do this, choose Update Project Folder... from the PVCS top-level Project menu.  The new files and revisions should then be visible in PVCS’ "Folders" window.


Why are the source control menu options only enabled in one product?

If I run more than one product simultaneously, the source control menu options are only enabled in one of them.  Why?

PVCS on Windows is not reentrant.  This means that only one program (either a PVCS-enabled program like Report Builder, or the PVCS interface itself) can access PVCS services at a time.  You will need to exit both the program that has the menus enabled, and the one from which  you wish to access PVCS services.  Then re-start the one in which you need PVCS access.


Why do I get an error that PVCS is unable to find the archive?

When trying to check out a Report, I chose the .RDV (archive file) but I still get an error that PVCS is unable to find the archive.  What’s going on?

Even though you have chose an .RDV file, it may not have been the archive. Report Builder writes its intermediate (ASCII) files to an extension .RDV before checking them in.  (See About PVCS Implementation for details.)  Be sure that you are selecting an .RDV file from the archive directory, and not the working directory.  There are three ways to help prevent this confusion:

•	Set the PVCS project option to delete work files after check-in.  This will prevent the Reports intermediate .RDV files from remaining on your disk.

•	Change the suffix rule, so that when an .RDV file is checked in, it is given a different suffix, say .VRD.  Then you can be sure to look for .VRD’s, not .RDV’s, when checking out.

•	Configure your project to ignore workfile paths when searching for archives.  This will allow you to specify the work file (in this case, .RDF) , and not the archive, at checkout.

These options are available from the PVCS configuration manager user interface, from the Configure Project... menu choice.


How can I make sure the proper username is used when I lock a file?

Whenever I lock a file (or check out with a lock) the User ID is set to “UNKNOWN”.  This lets other people check in or unlock the file.  How can I make sure the proper username is used?

There is a PVCS project configuration option, "Login Source" in the "network" section of the PVCS project configuration options (in the PVCS Version Manager Interface) which you can use to prevent this from happening.  With  this option, you’ll be able to define how PVCS determines the current user ID.  For example, if you use a NETWARE network, you can instruct PVCS to use the current NETWARE Login ID. On Windows NT, you can use the NT Login ID by choosing the "HOST" Login source.  Consult your PVCS documentation for further details.


Is there anything I can do to allow me to select work files for check-out?

Is there anything I can do to allow me to select work files, not archive files, for check-out?

There is a PVCS project configuration option, "Ignore Workfile Path" in the "Archive Searching" section of the PVCS project configuration options (in the PVCS Version Manager Interface) which you can use.  If you turn on this option, you’ll be able to select either work files or archive files in Check Out and Source Control Options dialogs.


Why did  I receive an error that VCSDIR is not allowed in the project configuration file?

I have configured my Master Project to disallow changing archive directories.  In the PVCS Version Manager interface, I can’t change archive directories in a sub-project, which is correct.  But in Forms Developer, I was able to.  Afterwards, from the PVCS version manager interface, I received an error that VCSDIR is not allowed in the project configuration file.  What’s going on?

The PVCS Version Manager interface looks for a default MASTER.CFG file in its root directory, and that’s probably what it found, and why it raised the error after you’ve changed archive directories. To make the master configuration file recognizable, you must configure PVCS using the VCONFIG command.  This encodes the name of your master configuration file in the PVCS libraries, and ensures that no one will be able to accidentally change the archive directory list.  Refer to the sections on "Master Configuration Files" and "VCONFIG command" in your INTERSOLV PVCS Command-Line Reference Guide.


• 9


Accessing non-Oracle datasources

  Related Topics

Through the Oracle Open Client Adapter (OCA), your application can connect to any ODBC datasource.  For the datasources listed below, we provide specific information.

Click the datasource you want to access:

Personal Oracle Lite

Microsoft SQL Server  (Versions 4.2, 6.0, and 6.5)

Microsoft Access  (Version 2.0 and higher)

Oracle Rdb  (Versions 5.1, 6.1, and 7.0)

Sybase   (SQL Server Version 4.9, System 10, and System 11)

Tandem NonStop SQL

Informix   (SE and Online Versions 5.x, 6.x, and 7.x)


Preparing to use the Open Client Adapter
Preparing to use the Open Client Adapter (OCA)

  Related Topics

To set up your system to use the OCA:

1	Install the necessary database server and client software, including network libraries. Configure your database, create database accounts, grant the appropriate access privileges to the users.  Note that for some single-user, single-machine datasources, such as Microsoft Access, there is no notion of a database server and database client, and no special setup is required (you do, however, need to create the database file to store database tables).

2	Install the necessary ODBC drivers on your client machine and configure the datasource using the Microsoft ODBC Administrator (which is automatically installed with the drivers).  ODBC drivers from Intersolv (for SQL Server, Rdb, Sybase, Informix, Ingres and many other databases) are installable from the your installation CD.  You can also use drivers from Microsoft, IBM, and other ODBC driver vendors.


Accessing Personal Oracle Lite

  Related Topics 	  Open oca_info.pdf

To access Personal Oracle Lite:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that allow design-time components to display database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

7	When you are ready to connect to the Personal Oracle Lite datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Personal Oracle Lite, see oca_info.pdf.


Init_Form is the OPENDB routine that automatically modifies your form-level properties so that your form can communicate with an ODBC datasource.


OCA.PLL is located in your ORACLE_HOME\oca20 directory.  For Form Builder to locate OCA.PLL, you must add the ORACLE_HOME\oca20 directory to the FORMS50_PATH environment variable in the registry.


Accessing Miscrosoft SQL Server
Accessing Microsoft SQL Server

  Related Topics	  Open oca_info.pdf

To access Microsoft SQL Server:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that enable the display of database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

7	When you are ready to connect to the Microsoft SQL Server datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Microsoft SQL Server, see oca_info.pdf.


Accessing Rdb
Accessing Oracle Rdb

  Related Topics 	  Open oca_info.pdf

To access Oracle Rdb:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that enable the display of database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only).  Attach the OCA.PLL library to your application, then create a Pre-Form or When-New-Form-Instance trigger that includes the OPENDB.Init_Form routine.

7	When you are ready to connect to the Oracle Rdb datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Oracle Rdb, see oca_info.pdf.


Accessing Microsoft Access

  Related Topics	  Open oca_info.pdf

To access Microsoft Access:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	(Optional) Run the.SQL scripts to create and populate demo tables using the UBT utility:

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

6	When you are ready to connect to the Microsoft Access datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Microsoft Access, see oca_info.pdf.


Accessing Sybase

  Related Topics 	  Open oca_info.pdf

To access Sysbase:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that enable the display of database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

7	When you are ready to connect to the Sybase datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Sybase, see oca_info.pdf.


Accessing Tandem NonStop SQL

  Related Topics 	  Open oca_info.pdf

To access Tandem NonStop SQL:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that enable the display of database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

7	When you are ready to connect to the Tandem NonStop SQL datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Tandem NonStop SQL, see oca_info.pdf.


Accessing Informix

  Related Topics 	  Open oca_info.pdf

To access Informix:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that enable the display of database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

7	When you are ready to connect to the Informix datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Informix, see oca_info.pdf.


About the Open Client Adapter (OCA)

  Open oca_info.pdf

The Oracle Open Client Adapter (OCA) for ODBC allows applications on Microsoft Windows 3.1, Windows 95/98, and Windows NT to access ODBC-compliant datasources through ODBC drivers.  The OCA requires the ODBC driver to be ODBC level 1-compliant.  OCA also uses certain level 2 ODBC functionality to achieve greater performance if that capability is provided by the ODBC driver.

Using the OCA, an application can access different datasources in a consistent manner.  This allows an application developer to build an application that can run unmodified against one of several datasources.  Alternatively, the application can be targeted at a specific datasource, and take advantage of features particular to that system.

The OCA is installed through the Oracle Installer, which copies all necessary files to your ORACLE_HOME directory.  One of these files is oca.pll, which is a PL/SQL library of functions that you can use from within applications to:

•	Open auxiliary connections to other datasources in addition to the application's main connection.

•	Execute arbitrary SQL statements and Stored Procedure calls on any connection.

•	Retrieve results sets from non-Oracle stored procedures.

•	Obtain the DBMS and ODBC driver names and versions for a given connection.

•	Automatically adjust Form and Data Block properties at runtime to suit the datasource.

Click the [image] button at the top of this topic to learn more about these functions.

For details about other installed files, refer to the release notes.


By default, oca_info.pdf is installed in ORACLE_HOME\TOOLS\DOC60\US.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


About the UBT utility

The Oracle Open Client Adapter (OCA) for ODBC includes a SQL*Plus-like utility called Universal Backend Tester (UBT).  UBT enables you to manipulate SQL commands within the interpreter or through command files.

The UBT executable (UBT32.EXE for Windows NT and Windows 95/98, and UBT.EXE for Windows 3.1) is installed in ORACLE_HOME\BIN.

For more information about Oracle Client Adapater, see oca_info.pdf (includes UBT utility information)..


The OCA release notes are included in RELNOTES.TXT on the installation CD.


By default, information about accessing  Personal Oracle Lite is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf


This is optional for application development, and not required for runtime. For some databases (for example, Microsoft Access), data dictionary views cannot be created due to inadequate exposure of database catalog information and lack of support for creating views.  In this case, you can type in database object names at design time, rather than select them from a list.


By default, the SQL scripts for creating data dictionary views for Personal Oracle Lite are installed in ORACLE_HOME\OCA20\SQL\POLITE:

polvudrp.sql	removes any old versions of the views.

polvubld.sql	creates necessary views.


UBT32.EXE scott/tiger@ODBC:polite_ds @polvubld.sql


By default, the SQL script for creating demo tables for Personal Oracle Lite is installed in ORACLE_HOME\OCA20\SQL\POLITE:

poldmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:polite_ds @poldmbld.sql


scott/tiger@ODBC:polite_ds


By default, information about accessing Microsoft SQL Server is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL scripts for creating data dictionary views for Microsoft SQL Server are installed in ORACLE_HOME\OCA20\SQL\SQLSRV:

sqsvudrp.sql	removes any old versions of the views.

sqsvubld.sql	for SQL Server Version 4.2, creates necessary views.

sqs60bld.sql	for SQL Server Version 6.0, creates necessary views.


UBT32.EXE scott/tiger@ODBC:sqlserver_ds @sqsvubld.sql


By default, the SQL script for creating demo tables for Microsoft SQL Server is installed in ORACLE_HOME\OCA20\SQL\SQLSRV:

sqsdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:sqlserver_ds @sqsdmbld.sql


scott/tiger@ODBC:sqlserver_ds


By default, information about accessing Microsoft Access is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL script for creating demo tables for Microsoft Access is installed in ORACLE_HOME\OCA20\SQL\ACCESS:

accdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:access_ds @accdmbld.sql


scott/tiger@ODBC:access_ds


By default, information about accessing Oracle Rdb is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL scripts for creating data dictionary views for Oracle Rdb are installed in ORACLE_HOME\OCA20\SQL\RDB:

rdbvudrp.sql	removes any old versions of the views.

rdbvubld.sql	creates necessary views.

rdbdual.sql	creates view dual (to support SYSDATE).


UBT32.EXE scott/tiger@ODBC:rdb_ds @rdbvubld.sql


By default, the SQL script for creating demo tables for Oracle Rdb is installed in ORACLE_HOME\OCA20\SQL\RDB:

rdbdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:rdb_ds @rdbdmbld.sql


scott/tiger@ODBC:rdb_ds


By default, information about accessing Sybase is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL scripts for creating data dictionary views for Sybase are installed in ORACLE_HOME\OCA20\SQL\SYBASE:

sybvudrp.sql	removes any old versions of the views.

sybvubld.sql	creates necessary views.


UBT32.EXE scott/tiger@ODBC:sybase_ds @sybvubld.sql


By default, the SQL script for creating demo tables for Sybase is installed in ORACLE_HOME\OCA20\SQL\SYBASE:

sybdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:sybase_ds @sybdmbld.sql


scott/tiger@ODBC:sybase_ds


By default, information about accessing Tandem NonStop SQL is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL scripts for creating data dictionary views for Tandem NonStop SQL are installed in ORACLE_HOME\OCA20\SQL\NONSTOP:

nssvudrp.sql	removes any old versions of the views.

nssvubld.sql	creates necessary views.


UBT32.EXE scott/tiger@ODBC:nonstop_ds @nssvubld.sql


By default, the SQL script for creating demo tables for Tandem NonStop SQL is installed in ORACLE_HOME\OCA20\SQL\NONSTOP:

nssdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:nonstop_ds @nssdmbld.sql


scott/tiger@ODBC:nonstop_ds


By default, information about accessing Informix is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL scripts for creating data dictionary views and demo tables for Informix are installed in ORACLE_HOME\OCA20\SQL\INFORMIX:

infvudrp.sql	removes any old versions of the views.

infvubld.sql	creates necessary views.


UBT32.EXE scott/tiger@ODBC:informix_ds @infvubld.sql


By default, the SQL script for creating demo tables for Informix is installed in ORACLE_HOME\OCA20\SQL\INFORMIX:

infdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:informix_ds @infdmbld.sql


scott/tiger@ODBC:informix_ds


Troubleshooting

If an application that used to work against Oracle now fails against an ODBC datasource, the most likely explanation is that you have encountered a restriction or limitation of either ODBC or the datasource.

To view the SQL statements issued by OCA and the messages generated by the ODBC driver or the database:

1	Verify that the following entry is set in the ORACLE.INI file on Windows 3.1 or in the registry on Windows NT and Windows 95/98:

•	UB=ORACLE_HOME\OCA20

2	Add the following entries to the ORACLE.INI file on Windows 3.1 or to the registry under SOFTWARE\ORACLE on Windows NT and Windows 95/98:

•	OCA_DEBUG_SQL=TRUE

•	OCA_DEBUG_ERROR=TRUE

3	Run your application against the ODBC datasource to view SQL statements or error messages in the debug window.  Click OK to close the debug window and continue processing.

4	If you are unable to resolve the error, call Oracle Support Services.


OCA Messages

Code	Message Description

30000	General OCA error.

30001	NULL hostdef.

30002	Function not supported.

30003	NULL username in connect string.

30004	NULL hostname in connect string.

30005	All cursors are in use.

30006	Error creating parse tree.

30007	NULL SQL statement.

30008	Memory allocation failed.

30009	Error processing bind variables.

30010	Oracle to ODBC datatype conversion error.

30011	ODBC to Oracle datatype conversion error.

30012	Error binding reference value.

30013	No parameters to bind.

30014	Hostname too long.

30015	Stored procedures not supported for this datasource.

30016	Sequences not supported by this database.

30017	Error logging on to non-Oracle database.

30018	Username or password too long.

30019	Error handling non-Oracle stored procedures.

30020	Stored procedure name is missing.

30021	Error preparing/executing SQL statement.

30022	Error retrieving column.

30023	Error fetching result set.

30024	Error retrieving column descriptors.

30025	Error getting number of columns in result set.

30026	Error retrieving procedure descriptors.

30027	Error setting ODBC connection/statement option.

30028	Error at commit/rollback.

30029	Error binding column.

30030	Error binding parameter.

30031	Error retrieving information about driver/database.

30032	Error freeing memory.

30033	Row status error.

30034	Table not found.

30035	Column not found.

30036	Invalid authorization specification.

30037	Data source not available.

30038	Invalid column number.

30039	Illegal bundled operation combination.

30040	Invalid cursor context.

30041	Bind variable does not exist.

30042	No data found.

30043	Fetched column value is NULL.

30044	Fetched column value was truncated.

30045	Error returning result data.

30046	No data source name specified.

30047	Unsupported transaction isolation level.

30048	Binding arrays not supported.

30049	Not logged on.

30050 	Error freeing SQL statement.

30051	Error fetching data.  You must re-execute after a commit for this datasource.

30052	Parameter value was truncated at execution.

31000	General ODBC error issued by the ODBC driver in use.

If an error occurs and the application is unable to read the message from the message file, verify that the following entry is set in the ORACLE.INI file on Windows 3.1 or in the registry on Windows NT and Windows 95/98:

•	UB=ORACLE_HOME\OCA20


PDF file
PDF document

To view the PDF document,  you will need to start your PDF viewer and open oca_info.pdf from the directory in which it is installed.


Glossary

A

    action
    active window/view
    ActiveX
    Ada
    aggregation
    alert
    alignment
    alias
    All tool
    ancestor
    ancestor group
    anchor
    anchor point
    anonymous block
    antecedent
    applet
    application
    argument
    ASCII
    attached library
    attribute
    attribute columns
    attribute mask
    Attribute tool
    attribute value
    axis chart

 B

    background element
    background process
    baseline value
    Batch
    batch compile
    bind reference
    bind variable
    block
    body
    boilerplate
    border
    bounding box
    break chart
    break column
    break group
    break report
    break trigger
    breakpoint
    builder
    built-in datatype
    built-ins
    built-in macro
    buffer
    button
    button procedure

C

    cache (memory)
    call interface
    call stack
    canvas
    canvas view
    cartridge
    cascading style sheet
    category
    category axis
    cell
    CGI
    CGM
    CHAR datatype
    chart element
    chart item
    chart template
    check box
    checksum
    child
    child query
    classification
    clause
    client
    client/server architecture
    Clipboard
    CMDFILE
    collection type
    color palette
    column
    column object
    command line
    comment
    commit
    comparison operators
    compile
    component
    concurrency
    condition
    confine mode
    connect
    connect string
    constraint
    construct
    context area
    continuous axis
    control point
    coordinate plane
    coordinate system
    coordinates (x, y)
    copy
    correlated subquery
    cross product
    crosstab
    cursor
    custom measure
    cut

D

    damage
    data dictionary
    data link
    data model
    data structure node
    database
    database trigger
    datasource
    datatype
    DATE
    date axis
    debug
    debug action
    debug trigger
    Debugger
    deconstructed object
    default
    deliver
    dependency tree
    dependency view
    dependent data
    descendant
    designer
    Designer (Oracle)
    detail query
    dialog box
    DIANA
    dimension
    dimension hierarchy
    dimension value
    disabled
    discrete axis
    display
    display item
    downward-growing
    drag
    drill
    duplicate
    dynamic saved selection

E

    EBCDIC
    edge
    Edge/Fill/Text Display
    editor
    element
    element type
    Ellipsis button
    enabled
    enclosing object
    encryption
    environment
    exception
    Exception tool
    executable argument
    execute
    export
    export file
    expression
    external PL/SQL library
    external query

F

    family
    Family tool
    field
    field template
    file node
    fill area
    filter
    firewall
    flattened object
    flex mode
    focus
    foreground element
    foreign key
    form layout
    form letter layout
    format mask
    format trigger
    formula
    formula column
    frame
    function

G

    generate
    Generate
    Global Registry
    global variable
    grant
    gridlines
    group
    group filter
    group tree
    GUI

H

    handle
    header
    heading node
    hidden
    hierarchy
    HTML
    HTTP
    hyperlink
    hypertext

I

    ICD
    icon
    image
    implied item
    import
    independent data
    index
    inherit
    inner bounding box
    input item
    insert mode
    internet
    Interpreter script
    intranet
    IP (Internet Protocol) Address
    item
    item node

J

    JAR
    Java
    join
    justification

K

    keyword

L

    label
    Launcher
    level
    Level tool
    layout
    layout unit
    lexical reference
    library
    link
    link file
    list box
    list item
    list of values
    List tool
    local database
    local registry
    local variable
    logical operators
    logical page
    loop

M

    macro
    mailing label layout
    margin
    master/detail layout
    Match tool
    matrix cell
    matrix layout
    matrix report
    measure
    megabyte (Mb)
    message box
    method
    modal window
    modeless window
    module
    multi-line field

N

    NA value
    nested matrix
    NOCACHE
    node
    non-caching column
    NULL value
    numeric operators

O

    object
    object column
    object group
    object handle
    Object Navigator
    object table
    object type
    ODBC
    OLE
    OLE container
    OLE Server
    Oracle datatype
    Oracle Designer
    ORACLE_HOME
    organization node
    origin
    outer bounding box
    overflow

P

    packaged function
    package
    package body
    package specification
    page
    page break
    palette
    pane
    panel
    parameter
    parameter list
    parent
    paste
    pattern
    Pcode
    PDF
    physical page
    placeholder username
    plot type
    PL/SQL
    pld file
    pll file
    pls file
    plx file
    pop-up list
    port
    pre-defined action
    pre-defined type
    preference
    preview
    Previewer
    primary key
    primitive
    printer control code
    prt file
    procedure
    program unit
    project
    project file
    project item
    Project Navigator
    project node
    project registry
    project view
    Project Wizard
    property
    property class
    protocol

Q

    qualifying dimension
    query
    query filter function
    quit

R

    radio button
    radio group
    Range tool
    RC4
    RDBMS
    rdf file
    rep file
    read consistency
    record
    record group
    REF column
    reference line
    refresh
    register
    registry
    relational operator
    remote database
    repeating frame
    replace mode
    report-level objects
    Reports Background Engine (RWRBE60)
    Reports Queue Manager (RWRQM60)
    Reports Server (RWMTS60)
    Reports Web Cartridge
    Reports Web CGI (RWCGI60)
    rex file
    RGB
    root
    root node
    row
    row object
    RTF
    run
    runfile
    Runtime
    Runtime Parameter Form

S

    saved selection
    Saved Selection tool
    schema
    scope
    script
    section
    SELECT statement
    selection
    selection script
    Selector
    Selector tool
    session
    sibling
    socket
    Sort tool
    source
    specification
    split bar
    SQL
    sql file
    SQL script
    SQL statement
    stack
    statement
    static saved selection
    stored program unit
    stored subprogram
    style sheet
    subprogram
    subproject
    subproject node
    summary column
    SYLK
    syntax
    system variable

T

    table
    table type
    tabular
    target
    target node
    TCP
    tear-off menu
    text item
    title bar
    title page
    toggle
    tool
    toolbar
    tool palette
    Top/Bottom tool
    trailer
    transaction
    trigger
    type

U

    update
    URL
    user exit
    user-defined action
    user-defined type
    user-defined macro
    user registry

V

    valid XML
    value axis
    value construct
    variable
    varying array type
    VBX
    VBX control
    view
    virtual directory
    virtual file system
    visual attribute

W

    Web
    Web browser
    Web cartridge
    Web link
    Web server
    well-formed XML
    wildcard
    window
    WKS
    WRB
    WWW

X

    XML

Y

Z

    zoom


In Project Builder, a command string supplied either by Project Builder or by the user that applies to files of a given type.  An action is not restricted to a single file type; for example, if the action "Compile" is defined for both forms and C source files, selecting "Compile Project" will compile all .fmb and .c files using the appropriate tools.  See also:  pre-defined action, user-defined action.


A high-level programming language developed by the U.S. Department of Defense for use in embedded computer systems.


A window or view that can receive user input.


(Oracle Express) The consolidation of data for several dimension values into a single value, such as the total units sold for all the cities, or into a smaller set of values, such as the average units sold for cities in each region. Data is often collected at the lowest level of detail and is aggregated into higher level totals for analysis.


A modal window that notifies you of a condition that occurred because of your last action.  You must respond to an alert.


The way in which data is positioned in a field.  It may be positioned to the left, right, center, flush/left, flush/right, or flush/center of the defined width of a field.


A secondary name used in a SQL statement to reference a table, view, or column.


(Oracle Express) A Selector dialog box tool that allows you to select all of the values in a dimension, or all of the values in a dimension for a specific hierarchy.


(Oracle Express) A dimension value at any level above a particular value in a hierarchy. The ancestor value is the aggregated total of the values of its descendants.  The following example shows the dimension value "Europe" as the ancestor of "France," "Lyon," and "Paris" in the GEOGRAPHY dimension.


A group that owns another group, either directly or indirectly.


A layout object used to fix a spot on one object to a spot on another object, ensuring the position of the first object in relation to the second object.


(Oracle Express) A specific dimension value that is used when selecting dimension values based on their family relationship or when navigating through a hierarchy.


A PL/SQL program unit that has no name and does not require the explicit presence of the BEGIN and END keywords to enclose the executable statements.  Since they are unnamed, anonymous blocks cannot be referenced by other program units.


An object that appears in another object's group tree at any position above that other object.  Every object is an antecedent of its descendants.


A Java term for small programs that can be dynamically imported into Web pages or applications as needed.


One or more program modules used to achieve a specific result.  Applications can be nested within other applications.  For example, an application to control a company's inventory could consist of various Form Builder applications for input of data, and various Graphics Builder applications to display the data visually.


1. An optional expression passed to a program unit for the program unit to operate on.
2. Clauses containing keywords and their specified values.


Acronym for American National Standard Code for Information Interchange.


A read only collection of PL/SQL subprograms, usually provided with an application to supply necessary PL/SQL source.  Program units in an attached library are implicitly loaded when they are first called by another program unit at compile-time or runtime.  They remain loaded for quick reuse, which reduces runtime memory requirements and improves the performance of an application.  See also:  library .


1. See property.
2.  A part or component of an Oracle8 object type definition.  Each attribute has a name and an Oracle8 datatype.  When an object table is created based on the object type, the columns in the table correspond to the attributes in the object type definition.  When a column object in a relational table is created based on the object type, the column object contains the equivalent of sub-columns, each of which corresponds to an attribute in the object type definition.  Each Oracle8 object attribute in a table is treated as a separate data item, as if it were a separate column.  This is true for both object tables and column objects in relational tables.
3. (Oracle Express) A descriptive characteristic that is shared by dimension values. Attributes represent logical groupings that allow users to select data based on like characteristics. For example, in a database representing footwear, you can use a shoe color attribute to select all boots, sneakers, and slippers that share the same color.


The columns that compose a column object (Oracle8).


In Graphics Builder, the first element in an attribute descriptor.  It is a 32-bit mask that informs the toolkit of the attributes that will be set or retrieved by a subsequent function call.  Only those elements that have their corresponding bits set in the attribute mask are set or retrieved.


(Oracle Express) A Selector dialog box tool that allows you to select dimension values based on attributes and attribute values. For example, in a database representing soft drinks, you might select all products whose size is 1 liter. In this example, Size is an attribute and 1 liter is an attribute value.


(Oracle Express) The values in the database that make up an attribute. For example, in a database representing ice cream products, the following attribute values might belong to a flavor attribute in a Product dimension: vanilla, chocolate, and strawberry. Dimension values at various levels in the Product dimension -- brand, form, and size, for instance -- might share the same value for flavor.


A type of chart in which the data is plotted according to where it lies along the chart's edges, called axes.  An axis chart may contain two or three axes, each of which may be one of the following types:  discrete, continuous, or date.


The white part of a pattern.  You apply color to the background element using the Fill Color palette.


A non-interactive process that runs in an operating system environment and performs some service or action.  Certain Oracle products use background processes for different tasks, such as performing and coordinating tasks on behalf of concurrent users of the database, processing and delivering electronic messages, and managing printing services.


The value used as the starting point for plotting fields on the continuous axis of a chart.


The executable that executes an application in batch mode, without using a windowing system.


To translate, at once, several PL/SQL program units into a machine executable form.


A reference to a parameter used to replace a single literal value (e.g., a character string, number, or date) appearing anywhere in a PL/SQL construct or a SQL SELECT statement.  For a bind reference, you must precede the parameter name with a colon (:).


A global variable you can create and use outside of a PL/SQL package.


1. The basic program unit in PL/SQL, defined by the keywords DECLARE, BEGIN, EXCEPTION, and END.
2. In Form Builder, a logical container that relates to a database table or view.


1. Contains the same information as the program unit specification, and also includes the actual implementation of the subprogram (i.e., its sequence of actions).  In most cases, only a body must be defined for a subprogram.
2. In Report Builder, a region that contains the bulk of the report layout (text, graphics, data, and computations).  The report body appears between the report header and trailer pages.


Text and/or graphics that appear in a report every time it is run.  In some products this is called "constant" text or graphics.


A user-defined outline around a layout object, usually used to highlight its contents.  Borders are drawn such that half the width of the border lies outside the edge of the object, and half inside the edge.


See inner bounding box, outer bounding box.


An axis chart that displays two categories of data along one axis.


A query column assigned to a break group.


A group used to break or categorize report data.  All data in query columns assigned to a break group appear above the data in columns belonging to other groups.  Each record fetched for a break group appears only once, while multiple related records in other groups can be displayed.


A report that contains categories that break the report data into sets.


A PL/SQL block that executes each time a breakpoint is reached.  See also:  breakpoint.


A debug action you can place at any executable source line in a PL/SQL subprogram.  A breakpoint interrupts execution of the program unit and passes control to the PL/SQL Interpreter.  Breakpoints allow you to incrementally execute a subprogram and search for runtime errors.  See also:  break trigger.


Refers to a component used to create a specific type of document. For example, Form Builder is used to create forms, while Report Builder is used to create reports.


A datatype defined and supported by the Oracle Server.


A collection of extensions to the PL/SQL language that are designed to be used with the software.  Built-ins include datatypes, procedures, functions, exceptions, and constants.


In Project Builder, macro shipped with Project Builder.  See also:  macro.


A temporary storage area for data during the transfer of that data between the computer and a peripheral, or between parts of a computer.  A buffer prevents loss of information due to differences in the speed or timing of the transfer and speeds up certain functions.


1. An interface element used to select an action item, display a dialog box, or acknowledge the current condition.
2. An object in an application that has a PL/SQL procedure associated with it.  The procedure is generally executed upon a user mouse event.


A PL/SQL procedure associated with an application object, that is executed when a specific mouse event occurs on the item at runtime (e.g. clicking the button).  It does this by establishing a hierarchy for the fetched data containing a break group.


A temporary storage place for database data that is currently being accessed or changed by users, or for data that Oracle Server requires to support users. The terms are often used interchangeably.


An interface that enables you to invoke Forms Developer or Reports Developer component executables from other Oracle products, or a 3GL program.


A chain of subprogram calls, from the initial entry point down to the currently executing subprogram.  Each subprogram call is represented by a frame on the downward-growing call stack, in which newly entered subprograms are added to the bottom of the stack.


  See editor.


In Form Builder, the background object on which you place the interface objects that users will interact with in the runtime application.  A canvas view is usually associated with a window.


Manageable objects that plug in to the client, application server, or database through an open API.


See style sheet.


A label component that allows differentiation between information on the basis of non-hierarchical delineation or compartments rather than sensitivity levels.  With classification, they are used as a means of restricting access to information.


See discrete axis.


An instance of data in a spreadsheet (e.g., Microsoft Excel).


Acronym for Common Gateway Interface. The industry-standard technique for running applications on a Web server.  Whereas standard HTML documents retrieved from a Web server are static (the exact same text is retrieved every time) CGI enables a program running on the Web server to communicate with another computer to generate "dynamic" HTML documents in response to user-entered information.


Acronym for Computer Graphics Metafile.  A file format recognized internationally and used to store and transport object-oriented graphics from one system or program to another.


An Oracle datatype provided for ANSI/ISO compatibility.  A CHAR column is a fixed-length column and can contain any printable characters, such as A, 3, &, or blanks, and can have from 1 to 255 characters or can be null.


A bar, line, symbol, or other graphical object that represents a single value for a field.


A bordered rectangle of any size used to embed Graphics Builder charts in a form or report.


A collection of attributes and properties that defines the format of a chart.


A interface element, appearing as a small square, that a user can toggle on or off.


An error-checking algorithm.


1. An object that is a member of a group, and is immediately below that group object in its group tree.  The objects that compose a group object are children of that group.  Every object is a child of its parent.
2. (Oracle Express) A dimension value at the level immediately below a particular value in a hierarchy. Values of children are included in the calculation that produces the aggregated total for a parent.  A dimension value may be a child for more than one parent if the dimension has more than one hierarchy.  The following example shows the dimension values "Lyon" and "Paris" as the children of "France" in the GEOGRAPHY dimension.


See detail query.


A hierarchical level that denotes the sensitivity of the information that is labeled.  Classifications are used as a means of restricting access to information.


A part of a SQL statement that does not constitute the full statement; for example, a "WHERE clause."


A user, software application, or computer that requests the services, data, or processing of another application or computer (the "server").  In a two-task environment, the client is the user process.  In a network environment, the client is the local user process and the server may be local or remote.


Separation of processing between two CPUs, one acting as the server that provides services in a transaction and the other as the client in the transaction, requesting and receiving services.  All responsibilities of shared data management can be processed by the computer running the database management system while the workstations running the database application concentrate on the interpretation and display of data.


A memory buffer.  An object remains on the Clipboard until you cut or copy another object, or until you quit the application.


A user-defined datatype that describes a data unit made up of an indefinite number of elements, all of the same datatype.  Varying array types and table types are collection types.  (Oracle8)


An argument that allows you to specify a file that contains a set of command line arguments for Forms Developer executables.


Contains all the colors available to the windowing system, the drawing surface, or a window and its views.


1. A vertical space in a database table that represents a particular domain of data.  A column has a column name (e.g., ENAME) and a specific datatype (e.g., CHAR).  For example, in a table of employee information, all of the employees' names would constitute one column.  A record group column represents a database column.
2. In Report Builder, a data model object created automatically for each column expression in a query's SELECT list, or created manually to perform summaries, formulas, or act as a placeholder.


In an Oracle8 relational table or object table, a column whose definition is based on an object type.  The column is a composite, the parts of which correspond to the attributes of the object type.


An operating-system command line.  Most Oracle products can be invoked from a command line using a number of executable arguments.


A language construct for the inclusion of explanatory text in a program, the execution of which remains unaffected.


To make changes to data in the database permanent.  Before changes are stored, both the old and new data exist so that changes can be stored or the data can be restored to its prior state.


(Oracle Express)

>	Greater than

<	Less than

=	Equal to

<=	Less than or equal to

>=	Greater than or equal to

<>	Not equal to

For numbers, the operands are widened to the least common type (Integer is preferred over Long, which is preferred over Single, which is preferred over Double). For Strings, the comparison is case-sensitive and is based on the collating sequence used by the language specified in the Windows Control Panel. The result is 0 for FALSE and -1 for TRUE.


To translate a source program into a binary, executable format.  PL/SQL program units must be compiled before they can be executed.


A specific target object that is a part of a larger application; e.g. a form in an order entry system, or a library that is shared among many other elements.  See also:  target.


The simultaneous access of the same data by multiple users executing different database applications or the same application.  In database software concurrency requires additional logic to ensure that all users see consistent data and that all changes are made in the proper order.


An expression whose value is either true or false, such as X> 100.  For example, you can set a condition in a query when you want the query to display only those rows that evaluate as true in your expression.


Layout editor mode that prevents child objects from being moved or resized on or outside their parent objects.


To log on to a database.  You must connect if you want to create or modify queries or access an application stored in a database.


The set of parameters, including a protocol, that SQL*Net uses to connect to a specific Oracle instance on the network.


A rule or restriction concerning a piece of data (such as a NOT NULL restriction on a column) that is enforced at the database level, rather than the object or application level.


A PL/SQL code structure.  There are two types of constructs: non-value constructs do not return a value; value constructs return a value.


A work area in which Oracle Server stores the current SQL statement, and if the statement is a query, the result's column headings and one row of the result.  Also referred to as cursor.


An axis that plots values that begin with one value and continue until they reach another value.  Thus, these values are mathematically related.  Dependent data is usually plotted along this axis, also called the value axis.


The four corner points of the virtual rectangle that constitutes an object's ideal shape.  When you select an object on the layout, its control points appear.  Depending on the object selected, you may be able to modify it by dragging a control point.


The two-dimensional grid on which drawing takes place.


The type of x, y units used to place and size objects in the Layout Editor view.  The coordinate systems available are 1) character, which uses the platform's native character cell size, and 2) real, which can be in units of pixels, centimeters, inches, or points.


The location points for objects appearing in the layout.  x and y coordinates determine the horizontal (x) and vertical (y) placement of objects.


To store a replica of a selected object on the Clipboard, so that it may be pasted elsewhere in an editor if desired.


A subquery based on the same tables as the parent query (i.e., references columns in the tables included in its parent query).


Group that owns two or more other groups and performs a mathematical cross product (i.e., correlates values between them).


See matrix cell.


1. A small icon representing the position of the mouse.  The shape of the cursor varies, depending on the selected tool.
2. An internal pointer to data retrieved by a query.  A cursor points only to one row of data at a time; however, you can use built-in subprograms to move the cursor to any row in the data set.


(Oracle Express) A formula created by a user, which allows fine-tuning of data analysis. You create custom measures using base measures in the database. For example, if the database contains the existing measure Volume Share, you can use this measure to create a custom measure named Volume Share Year Ago. This custom measure would allow you to look at a product's absolute share from the previous year.


To delete one or more objects and store them in the Clipboard, so that they may be pasted elsewhere in an editor, if desired.


A view is damaged when it is totally or partially occluded by another view.


A set of tables and views owned by the database administrator.  It is a central source of information for Oracle Server and other relational databases.


A data model object used to define a master/detail (parent-child) relationship between a group and a query.


A relational model that defines what data should be fetched from the database, what values should be computed, and how data should be ordered in a report.  Report Builder objects that define the data model are queries, groups, columns, parameters, and links.


A source for data returned by a query, including database objects such as tables, views, synonyms, snapshots, and queries stored as views.


In Project Builder, a node in the Project Navigator denoting a project item that governs the structure of an open project.  For example, the Global Registry node denotes the Global Registry, which contains a list of local registries and a list of global type definitions.


A set of dictionary tables and user tables that are treated as a unit.


A stored PL/SQL block that is implicitly executed when a triggering INSERT, UPDATE, or DELETE statement is issued against the associated table in the database.  See also:  debug trigger.


A standard form of data.  Some common Oracle datatypes are CHAR, VARCHAR2, DATE, NUMBER, LONG, RAW, and LONG RAW.


An Oracle Server datatype.  A date column may contain a date and time between January 1, 9999 BC and December 31, 9999 AD.


An axis that plots date values that begin at one date and continue until they reach another date.


To detect, diagnose, and eliminate runtime errors in programs.


A user-specified event placed in a PL/SQL subprogram, usually for the purpose of troubleshooting runtime errors.


A conditional debug action you can place at any executable source line in a PL/SQL subprogram.  If the specified condition is met, the specified action is taken before execution of the subprogram resumes.  See also:  database trigger.


The Procedure Builder functionality within the software component used for testing and debugging.


In Oracle8, object types and objects are composites, built of parts or attributes.  Forms Developer or Reports Developer treats each part/attribute as an independent, individually-selectable data item.  This treatment results in a deconstructed object (sometimes also known as a flattened object).  The object is not an homogeneous entity within the Developer environment.


A piece of data that depends on other data for its value.  For example, an employee's  years of service may have the value 10, which is dependent upon the value of the employee's name.  Also called value data.


A value supplied by the system when a user does not specify a required command parameter or attribute.


To prepare and provide a completed application for distribution and deployment.


In Project Builder, the mechanism used by Project Builder to determine how to compile files that are referenced in projects.  Items toward the top left of the tree depend on items toward the lower right; so, for example, if a header file is either out of date or more recent than the executable file it is used to build, then the Project Builder will rebuild the executable file, given a Build command.  Dependencies also extend to subprojects.  For example, if a subproject consisting of a function library has been rebuilt, the Project Builder "knows" the dependent project will need to be rebuilt in order to use the updated library functions.  See also:  dependency view.


In Project Builder, shows files in the Project Navigator in the order in which they depend on each other, with project nodes at the highest point in the hierarchy, followed by target nodes, which are followed by buildable components of those targets.  For example, an executable form depends on and will be followed by an .fmb file, which may depend on and be followed by a library used for a USEREXIT procedure, and so on.  See also: project view, target.


1. An object that appears in another object's group tree at any position below that other object.  Every object is a descendant of its antecedents.
2. (Oracle Express) A dimension value at any level below a particular value in a hierarchy. Values of descendants are included in the calculation that produces the aggregated total for an ancestor.  The following example shows the dimension values "France," "Lyon," and "Paris" as descendants of "Europe" in the GEOGRAPHY dimension.


The interface used to design different components of a Forms Developer or Reports Developer application.


See Oracle Designer.


An application modeling, design and generation toolset.  Using Oracle Designer, you can generate forms and menus from module definitions recorded in the Oracle Repository.


When defining a master/detail report, the detail query retrieves all related records for each record retrieved by the master, or parent, query.


A partial screen or window that prompts you to enter information necessary to complete an operation.


An intermediate representation of a program unit, generated by the compiler.  The DIANA includes all of the syntactic and semantic information for a compiled program unit.  In order to compile a reference to a program unit, the compiler must have access to the referenced program unit's DIANA.  For example, if program unit A calls program unit B, the DIANA for B must be available before A can be compiled.


(Oracle Express) A type of database object that is a list of values that provide categories for data. A dimension acts as an index for identifying values of a variable. For example, if you have sales data with a separate sales figure for each month, then the data has a MONTH dimension; that is, the data is organized by month. A dimension is similar to a key in a relational database.

Any item of data within a multidimensional variable can be uniquely and completely selected by specifying one member from each of the variable's dimensions. For example, if a sales variable is dimensioned by MONTH, PRODUCT, and MARKET, specifying "January" for the MONTH dimension, "Stereos" for the PRODUCT dimension, and "Eastern Region" for the MARKET dimension uniquely specifies a single cell in the variable. Thus, dimensions offer a concise and intuitive way of organizing and selecting data for retrieval, updating, and performing calculations.

A dimension can be simple, with values that are single text or integer values, or it can be conjoint, with values that are combinations of values in other dimensions. A composite is not a dimension, but it is a conjoint-like internal object that Express treats like a dimension for the purpose of handling sparse data.


(Oracle Express) One element in the list that makes up a dimension. For example, a computer company might have dimension values in the PRODUCT dimension called "LAPPC" and "DESKPC." Values in the GEOGRAPHY dimension might include "Boston" and "Paris." Values in the TIME dimension might include "MAY96" and "JAN97."


An interface element state that means a menu item, button, etc., cannot be used in the current context; i.e., it does not respond to keyboard or mouse input.


An axis that plots distinct values at fixed intervals.  These values are not mathematically related.  Independent data is usually plotted along this axis, also called the category axis.


A Graphics Builder document containing any combination of charts, images, text objects and shapes.


In Form Builder, an item that stores or displays information that must be fetched or assigned programmatically with PL/SQL.


As it pertains to the call stack, in which newly entered subprograms are added to the bottom of the stack.  The earliest frame, corresponding to the initial program entry point, is at the top of the stack, while the latest frame, associated with the most deeply nested subprogram call, is at the bottom of the stack.


Press and hold down a mouse button while you slide the mouse pointer to a particular location in a window.


(Oracle Express) To navigate up and down through the levels of aggregation in a dimension that has a hierarchy. When selecting dimension values or viewing data, you can expand or collapse a dimension hierarchy by drilling down or up in it. Drilling down expands the view to include child values that are associated with parent values in the dimension hierarchy. Drilling up collapses the list of descendant values associated with a parent value in the dimension hierarchy.

You can click on a plus icon ( [image]) to drill down on (expand) the hierarchy or on a minus icon ( [image]) to drill up on (collapse) the hierarchy.

In the Selector, you can click on the drill icon ( [image]) to display the Drill dialog box so you can select a level of detail for the entire dimension.


An option that allows you to copy objects directly on the layout without affecting the contents of the Clipboard.


(Oracle Express) A saved selection that can have different dimension values each time it is evaluated. The selected dimension values might differ from use to use. In contrast, a static saved selection is an unchanging list of dimension values. A dynamic saved selection script might include "Select the last three Months", while the script for a static saved selection might have "Select February 1996, March 1996, and April 1996".


Acronym for Extended Binary-Coded Decimal Interchange Code.


The boundary of an object.


A display box on the Layout Editor tool palette that shows the current settings for the edge, fill, and text patterns and colors.


A work area in which you perform a specific set of tasks, such as creating a program unit or designing an application.


A thing of significance about which you may need to record information.  Elements are described by attributes and associations to other elements.


Any element held in the dictionary is classified as being of a particular type.  Examples of element type are entity, attribute, program module, table, diagram, text, softbox.  Occurrences or instances of these are called elements.


(Oracle Express) Displays a dialog box related to the task you are performing, usually so you can select one or more values that you need.


An interface element state that means that a menu item, button, etc., can be used in the current context, that is, it responds to keyboard or cursor/mouse input.


An object that contains another object.  An object is considered to be enclosed by another object only if all of the following are true:  both objects belong to the same region (Body, Margin, Header, or Trailer);  the outermost of the two objects is a frame or repeating frame;  the outermost of the two objects is behind the other object;  the innermost of the two objects lies entirely within the borders of the other object.


The practice of scrambling (encrypting) data in such a way that only an intended recipient can unscramble (decrypt) and read the data.


The user's computer-based workplace, including the tools typically used and their configurations. For Project Builder, this refers to the subset of tools that are used to complete various tasks related to developing Forms Developer applications.


A warming or error condition generated from a PL/SQL subprogram.


(Oracle Express) A Selector dialog box tool that allows the user to select dimension values associated with data that meets cutoff terms that the user specifies. For example, the user can select all products whose dollar sales were greater than $10,000 for the week ending December 23, 1995 in the Boston market.


An argument you can pass to a product executable, such as 'OPENFILE=my_disp' and 'PRINT=YES'.  These arguments usually are specified when the executable is invoked from a command line.


See run.


To store a copy of an object, module, selected text or image to a file or database.  In Project Builder, the process of writing out a file containing project, type, action, and/or macro definitions in a portable format for distribution to others who may work on heterogeneous platforms.  See also:  export file, import.


In Project Builder, the shareable, portable file created by exporting a project.


1. A PL/SQL construct combining variables, constants, literals, and operations on their values.
2. (Oracle Express) One or more data values that are specified in an Express language program. For example, you can specify expressions as arguments to programs or functions. An expression can be any of the following:

•	A single, literal value (for example, 10)

•	A variable or formula that contains one or more values

•	A function that returns one or more values

•	A calculation that combines values, such as variables, formulas, or functions, with arithmetic or Boolean operators


See library.


An ANSI-standard SQL SELECT statement that can be referenced by other Oracle products.


(Oracle Express) A group of related dimension values that correspond to the levels of the dimension hierarchy. Dimension values within a family can relate to each other as ancestor, parent, child, and descendant.  The following example shows family relationships for the dimension value "France" in the GEOGRAPHY dimension.


(Oracle Express) A Selector dialog box tool that allows the user to select a family of dimension values for a particular hierarchy. A family includes a parent and all of its descendant dimension values. For example, the user can select all of the family members below the Chicago market level in the Geography dimension.


1. An interface element in which you enter, edit, or delete data.  2. In Graphics Builder or Report Builder, a layout object that define how the data for a specific query column appears.


In Graphics Builder, a collection of attributes and properties that determines how dependent data (values) are represented as chart fields, such as bars or lines.


In Project Builder, a node in the Project Navigator denoting a file stored in the file system.  For example, the global and local registry nodes correspond to global and local registry files.


The area within an object to which a fill (color or pattern) should be applied.


A PL/SQL function or anonymous function that restricts the data displayed by a group.


A computer that regulates access to computers on a local area network from outside, and regulates access to outside computers from within the local area network.


See deconstructed object.


Layout Editor mode that automatically resizes or shrinks parent objects when child objects are moved or resized, and adjusts the positions of other layout objects that might otherwise be affected by the repositioning or resizing of the objects.


The state of an entity that is able to respond to input from the user or the client.  If an entity has the keyboard focus, it can receive events when the user presses a key.  If a drawn view has the drawing focus, it can respond to client routines that affect drawing.


The black part of a pattern.  You apply color to the foreground element using the Edge Color palette.


A value or column in one table that refers to a primary key in another table.


In Report Builder, a default layout style in which labels appear to the left of fields, and each record prints on a separate logical page.


In Report Builder, a default layout style that intermixes boilerplate and fields, wrapping lines at "word" breaks.


(Field Properties)  A setting that defines the appearance of the value of a field.  For example, a format mask is used to specify the display of currency amounts and dates.


A PL/SQL function that allows you to dynamically change the formatting attributes of an object.


(Oracle Express) A type of database object that represents a stored calculation, expression, or procedure that produces a value. A formula provides a way to define and save complex or frequently used relationships within the data without resaving the data itself. Each time you use a formula, Express performs the calculation or procedure that is required to produce the value.


A user-created column that gets its data from a PL/SQL function or expression, a user exit, a SQL statement, or any combination of these.


In Graphics Builder, the part of a chart template that defines the basic structure of a chart, but does not determine the way the data is plotted.
2. In Report Builder, a layout object used to enclose other layout objects and control the formatting, frequency, and positioning of several objects simultaneously.


A PL/SQL subprogram that performs a specified sequence of actions, and then returns a value.  Can reside and execute on the client and the database server.


To save an application to a file or database in a binary format that can be executed by Runtime and Batch executables.


The Form Builder executable used to save an application to a file or database in a binary format.


A Project Builder registry that stores information common to an entire Forms Developer or Reports Developer installation.  This information is restricted to type definitions, and their associated actions and pre-defined or user-defined properties.  The use of the Global Registry is optional; its functions can be performed by individual user registries.  See also: registry, user registry.


A logical container that exists across an application.  When an application uses a global variable, the application maintains the variable until the application is exited, or until another object explicitly removes it.


To give a user access to a module.  Only a module's creator can grant its access to other users.


In Graphics Builder, the lines that separate rows and columns in the Layout Editor.


1. An object that is composed of several other objects.
2. In Report Builder, a data model object that is created automatically to contain all the columns selected by a query, or created by the user to modify the hierarchy of the data appearing in a report;  it is used primarily for creating breaks in a report, as well as for resetting computations.
3. In Project Builder, collections of related items available via submenus off the Launcher.  Groups allow users to set up the Launcher much like the Windows 95 Start menu, with arbitrary "groups" as entries that pop up to reveal other items and/or groups.  For example, a user could define a group named "Project Docs", containing a project schedule, to-do list, component specifications, etc.; some files may be .TXT files, other .DOC files.


A PL/SQL function that restricts the data fetched by a group.


A hierarchical model-similar to a "family tree"-that describes the relationships between group objects and the objects that compose them.


Acronym for graphical user interface. The use of pictures rather than just words to represent the input and output of a program.  Programs with GUIs run under a windowing system (such as  X Windows, Microsoft Windows, Apple Macintosh, and so on).  GUI programs display icons, buttons, and so on, in windows on the screen;  users control the GUI programs mainly by moving a pointer on the screen (typically controlled by a mouse).  Also known as a bitmapped interface.


An internal pointer to an application object.  In order to reference an object in a PL/SQL program unit, you must pass its handle as an argument to the appropriate subprogram.


An optional report region that can contain introductory material for the report, including text, graphics, data, and computations.  The report header appears first, before the body and trailer.


A node in the Object Navigator denoting a type of object which can be contained within or associated with a report.  Selecting a heading node does not select an object in the report.


(Field Properties)  A property that specifies whether Report Builder will suppress the indicated field at its location in the layout.  If Hidden is specified, the field's value will appear only where referenced in text objects (using &fieldname).


(Oracle Express) A means of organizing and structuring data. A hierarchy exists when values within a dimension are arranged in levels, with each level representing the aggregated total of the data from the level below. Some dimensions have multiple hierarchies based on them.

The following example shows a hierarchy based on the GEOGRAPHY dimension, in which dimension values are arranged in five levels. Data at the Customers level is aggregated into the Cities level, which, in turn, is aggregated into the Countries/Areas, Continents/Regions, and Global levels.


Acronym for Hypertext Markup Language.  A tag-based ASCII language used to specify the content and links to other documents on Web servers on the Internet.  End users with Web browsers view HTML documents and follow links to display other documents.


Acronym for Hypertext Transfer Protocol. The protocol used to carry WWW traffic between a WWW browser computer and the WWW server being accessed.


A reference (link) from some point in one document to (some point in) another document or another place in the same document.  A Web browser usually displays a hyperlink in some distinguishing way (in a different color, font or style).  When users activate hyperlinks (by clicking on them with a mouse) the browser displays the target of the link.


A collection of documents containing cross-references which, with the aid of a Web browser, allow readers to move easily from one document to another.


Cross-references which, with the aid of a Web browser, allow readers to move easily from one document to another.


Acronym for interface C definition-a PL/SQL application programming interface to functionality implemented in C.


A graphic representation of a window or tool.


A bitmapped object that can be stored and loaded into an application.  The client cannot modify an imported image.


In Project Builder, a project item, usually the result of automatic generation, that Project Builder recognizes and for which it automatically creates entries in the Project Navigator.  For example, Project Builder can recognize .OBJ files, generated as an intermediate step during the compilation of C source files, and create entries for them in the Project Navigator.  Although resetting the properties of an implied item is of limited use (the next compilation will destroy changes) such items can be useful, as they can be examined via actions such as Edit, View, and Print.  See also: item, action.


1. To read a module from the file system or database, and incorporate it into an application.
2. To read in a file containing project information.


A piece of data that does not depend on other data for its value.  For example, an employee's name may have the value Jones, which is independent of the values of other employee's names or associated data.  Also called category data.


An optional structure associated with a table that is used by Oracle Server to locate rows of the table quickly, and (optionally) to guarantee that every row is unique.


In Project Builder, to obtain information for an action, type, macro, or property definition from an ancestor node in the dependency tree.  If related attributes exist in an ancestor node, they may be inherited.  Thus, filesystem items like forms and documents may inherit action definitions from subprojects, projects, the user registry, or the Global Registry; projects may inherit type definitions from the local or the Global Registry; and so on.


The virtual rectangle that constitutes an object's ideal shape and connects its four control points, regardless of edge thickness or other attribute settings.


The file used to build a target: for instance, an .FMB is the input for an .FMX.  Also called source.


A mode in which each character you enter is inserted at the cursor, pushing the following characters to the right.  The opposite of replace mode.


A worldwide TCP/IP-based network of computers.


A file containing any mixture of PL/SQL source, Procedure Builder commands, and SQL statements.


An internal TCP/IP network, access to which is restricted (via a firewall) to individuals inside the company or organization.  An intranet provides similar services within an organization to those provided by the Internet, but is not necessarily connected to the Internet.  A common example of an intranet is when a company sets up one or more Web servers on an internal network for distribution of information or applications within the company.


A four-part number with no more than three digits in each part that uniquely identifies a computer on the Internet.


In Project Builder, an object in the file system associated with the project, such as a form or a document, pointed to or represented by a node in the Project Navigator.


In Project Builder, an entry in the Project Navigator window, consisting of an icon and a descriptive title.  Nodes point to actual items in the filesystem, such as Form Builder files and documents.  See also: node, item.


Acronym for Java ARchive.  A file used for aggregating many files (Java class files, images, and so on)  into one file.


A computer language that supports programming for the Internet in the form of platform-independent "applets".


Combining data from two (or more) tables in a single SELECT statement.


  See alignment.


1. Part of a command line syntax that must be supplied with a corresponding argument.  2. A required part of a PL/SQL construct.


Text identifying the values or meaning of an application's visual objects.


(Oracle Express) A position in a dimension hierarchy. Each level above the base level represents the aggregated total of the data from the level below. For example, the TIME dimension might have ascending levels such as Month, Quarter, and Year. Within a dimension hierarchy, a dimension value at one level has a family relationship with the dimension values at the levels above and below that level.


(Oracle Express) A Selector dialog box tool that allows the user to select dimension values based on their level in a particular hierarchy. For example, the user can select all of the dimension values at the Key Account level in the Geography dimension.


The area of an editor in which you can create, modify, position, or delete objects.


A unit of measurement for ensuring a consistent measurement system across different display devices.  Used to specify a position on the layout, or the dimensions of an object.


A reference to a parameter used to represent a string of text in a SQL SELECT statement.  For a lexical reference, you must precede the parameter name with an ampersand (&).


A collection of one or more PL/SQL program units that are stored together in a file on the client file system or in the database.  Program units stored in a library can be referenced by several applications at once.  Unlike stored program units, which reside and execute in the database, program units in libraries always load and execute within the PL/SQL engine on the client side.  To reference program units that are stored in a library, you must first attach the library.  See also:  attached library.


A data model object used to define a master/detail (parent-child) relationship between a group and a query.


The name of a file to which a boilerplate object is associated.  At runtime, Report Builder imports the file's contents into your report layout.


A list of items within a dialog box.  Usually, the list box offers choices for selection, and it is scrollable.


In Form Builder, an item that displays a list of choices.


Also called LOV. A scrollable popup window that provides the user with a single or multi-column selection list.


(Oracle Express) A Selector dialog box tool that allows you to select dimension values from a list of the currently selected values in the dimension.


1. The database on the computer running the application.  2. The database to which an application is connected.  This database parses and executes all SQL statements generated by the application.


See user registry.


A PL/SQL variable declared only within the scope of the current program unit.


(Oracle Express)

Not	Unary Not -- Operand can be integer or long. The operation is performed bitwise (one's complement).

And	And -- Operands can be integer or long. The operation is performed bitwise.

Or	Inclusive Or -- Operands can be integer or long. The operation is performed bitwise.

Xor	Exclusive Or -- Operands can be integer or long. The operation is performed bitwise.

Eqv	Equivalence -- Operands can be integer or long. The operation is performed bitwise. (A Eqv B) is the same as (Not (A Xor B)).

Imp	Implication -- Operands can be integer or long. The operation is performed bitwise. (A Imp B) is the same as ((Not A) OR B).


One page of your actual report (it may be displayed on one or more physical pages).


In a PL/SQL subprogram, a conditional statement that is repeated until the condition is no longer met.


In Project Builder, a type-specific variable that may be used to customize and extend actions.  A macro may be either a constant or a simple expression (which, in turn, may contain other constants and/or expressions).  The use of macros adds great flexibility in issuing command options, and in allowing the user to modify sets of commands by changing one property definition.


A default layout that displays records in one or more columns on the page.  Fields appear directly beneath each other in a single repeating frame.


An optional report region that appears at the top and bottom of each logical page in the body region.  The margin may include any layout object, but typically contains boilerplate and fields (for page numbers, page totals, grand totals, and current date and time).


A default layout in which the detail records appear below the master records.  Master records appear in form layout style, while detail records appear in tabular layout style.


(Oracle Express) A Selector dialog box tool that allows the user to select dimension values by matching characters in dimension value names to characters that the user specifies. For example, the user can select all dimension values in the Product dimension at the Brand level that contain the characters "new."


A repeat direction that displays each record of a repeating frame as a cell of a matrix.


A default layout, resembling a grid, that formats the four sets of data necessary for a matrix report; one set of data displays as a row of labels, one as a column of labels, one set creates the grid, and one set fills the cells of the grid.


A cross-tabulation of four sets of data:  one set of data displays across the page; one set of data displays down the page; one set of data is the cross-product, determining all possible locations in which the across and down data relate and placing a cell in those locations; and one set of data displays as the "filler" of the cells.


(Oracle Express) Data that can be examined and analyzed, such as sales or cost data. You can select and display the data in a measure. Measures can be stored as variables or relations, or measures can be calculated by means of formulas.


A unit of memory equal to 1,048,576 bytes (1024 x 1024). Often rounded to one million bytes.


A modal window that notifies you of a condition that occurred because of your last action.  You must respond to a message box.


Executable code attached to an Oracle8 object through its object type definition.


A window that elicits a response from the operator before the application can continue.


An unrestricted window that can have as much functionality as the runtime window manager can support.


1. An object that can be shared by multiple applications.  External queries and PL/SQL libraries are examples of modules.  2. In Form Builder, a major component of an application (i.e., a menu module).


A field in a window or dialog that extends for several lines, allowing you to scroll vertically through the information.


(Oracle Express) A special data value that indicates that data is "not available" (NA). NA is the value of any cell to which a specific data value has not been assigned or for which data cannot be calculated.


Matrix report in which either the across and/or down dimension contains one or more master/detail relationships.  There is no limit to the amount of nesting allowed.


A datatype indicating that the data will be fetched when the page on which it appears is formatted (instead of fetched and cached until formatted).


1.  A specific location in the Object Navigator object hierarchy.  Nodes can be expanded to reveal information about an object, such as cross references to other objects.  2.  In Project Builder, an entry in the Project Navigator.  See also:  item, item node, organization node.


A report column that references a database column of datatype NOCACHE.


The absence of a value.


(Oracle Express)

^	Exponentiation,

-,+	Unary minus and plus,

*, /	Numeric multiplication or division. For division, the result is a double.

\	Integer division. The operands can be integer or long.

Mod	Modulus or Remainder. The operands can be integer or long,

-, +	Numeric addition and subtraction. The + operator can also be used for string concatenation.


1.  An item that can be placed on the layout.  The following are examples of objects:  rectangle, line, ellipse, arc, polygon, polyline, rounded rectangle, freehand, chart, text, symbol, and text field.  2.  In Oracle8, an instance of an object type.  An object can be a row in an object table, or the portion of a row contained in a column object in a relational table.


See column object.


A container for a group of objects, used to provide the ability to copy or reference related objects.


See handle.


The window containing a hierarchical list of objects for the current session.  The list appears in outline form, and enables the user to accomplish several tasks such as creating, editing, renaming, and deleting objects.


In Oracle8, a table whose definition is based on an object type.  Each attribute in the object type becomes a column in the object table.  Each row in the table is an individual Oracle8 object.


In Oracle8, a user-supplied definition or template, upon which objects can be built.  An object type is a composite, whose parts are attributes.  Each attribute has a name and a datatype, and the object type as a whole has a name.  An object type may also include one or more methods.


Acronym for Open Database Connectivity.  A standard for accessing different database systems.  An application can submit statements to ODBC using the ODBC flavor of SQL.  ODBC then translates these to whatever flavor the database understands.  Using the Oracle Open Client Adapter (OCA), an application can access different database management systems in one consistent manner.  This allows an application developer to develop, compile, and ship an application without targeting a specific DBMS.


Object Linking and Embedding.


An application that can store and display OLE objects.


An application that creates OLE objects.


See built-in datatype.


An environment variable that indicates the root directory of Oracle products.


An entry in the Project Navigator, such as "Types", "Projects", "Form Files", etc., used to help organize the Navigator and indicate the filetypes of child items.  It may also correspond to a data structure within certain types of filesystem objects.


Represented in x and y coordinates.  The origin of a view indicates the location of the view on its parent's canvas.  The origin of a canvas indicates the position of drawing on a drawn view.


The smallest virtual rectangle that completely surrounds an object.


When an object's contents cannot fit on the current logical page.  In the event of overflow, some of the contents are moved to the next logical page.


A PL/SQL function provided with the software that can be referenced anywhere within a program unit.


A method of encapsulating and storing related procedures, functions, variables, and other package constructs together as a unit in the database or on the client.  While packages provide the database administrator or application developer organizational benefits, they also offer increased functionality and database performance.  The software provides several built-in packages which contain PL/SQL constructs that can be referenced by client-side program units (e.g., TEXT_IO package).  Several packages are also supplied with the Oracle database server for referencing by stored program units (e.g., DBMS_OUTPUT package).


Includes the actual implementation of the package, which may include private subprograms and datatypes.  The body is optional if the package consists only of declarations.


Declares the public interface to the package-that is, the datatypes and subprograms that can be referenced by other program units.


(Oracle Express) 1. A slice of data included in a report. Additional pages display additional slices of data.

The following figure shows three pages of data.

2. In Express, a page can also refer to a unit of storage in an Express database.


(Oracle Express) A representation of how data selected for a query will appear in your spreadsheet. The page layout shows three edges -- Across, Down, and Page. The edges indicate how the multi-dimensional datacube defined by the query will appear in the two-dimensional spreadsheet. Dimension tiles display the names and positions of the dimensions. A dimension tile on the Across edge indicates that this dimension will appear as a column. A dimension tile on the Down edge indicates that this dimension will appear as a row. A dimension on the Page edge indicates that this dimension will appear in a page box at the top of the results.


A setting that controls whether to move the current object and its children to the next logical page.  You can set page breaks to occur before or after the current object appears in the report output.


An interface element that displays tools, colors, or patterns available in an editor.


A distinct portion of an editor where work is performed, usually resizeable.


The number of physical pages needed to print one logical page.


1. A PL/SQL construct used to pass information to a subprogram.  For example, in the subprogram call MYPROC (x),x is a parameter.  2. In Forms Developer, parameters are used to pass information between components such as Form Builder and Graphics Builder.  3. A variable you can change at runtime.


A group of parameter names and associated values used to pass information between Forms Developer components.


1. An object that is immediately above another object in its group tree.  A group object is the parent to each of the objects that compose it.  Every object is the parent of its children.
2. (Oracle Express) A dimension value at the level immediately above a particular value in a hierarchy. The parent value is the aggregated total of the values of its children.  The following example shows the dimension value "France" as the parent of "Lyon" and "Paris" in the GEOGRAPHY dimension.


To place the contents of the Clipboard (cut or copied objects) at the current cursor location.


A graphical property you can apply to the edge or fill of most objects.


The machine code or instruction list for a compiled program unit.


Acronym for Portable Document Format.  A file format (native for Adobe Acrobat) for representing documents in a manner that is independent of the original application software, hardware, and operating system used to create the documents.  A PDF file can describe documents containing any combination of text, graphics, and images in a device-independent and resolution independent format.


The size of a page that is output by your printer.


The type of element used to plot a field on a chart, such as bar, line, or symbol.


Oracle's proprietary extension to the SQL language.  Adds procedural and other constructs to SQL that make it suitable for writing applications.


A Procedure Builder Interpreter script file.


A PL/SQL library file that contains source code and compiled code. The file can be opened in Procedure Builder for editing.


A text file that contains the PL/SQL source of a single program unit.


A runtime PL/SQL library file that contains executable code only.  The file cannot be opened in Procedure Builder for editing.


A list that pops up when the user performs a particular action.


A number that TCP uses to route transmitted data to and from a particular program.


An action shipped with Project Builder and automatically available to the user via a menu item and/or a toolbar button.  Pre-defined actions include Build, Deliver, and several source control options.  When a pre-defined action is defined for a supported file type, the action is invoked for any selected item of that type when the user calls the action from Project Builder.  See also:  action, user-defined action.


See built-in datatype.


A setting that affects the behavior of the application's interface.


(Oracle Express) View the script that would be generated if you accept the current criteria. In the dialog box for any Selector tool you can preview your selection by choosing the Preview button.


The interface with which you view and scroll through report output online.


A column in a database table whose members consist of unique values that can be used to identify a row in a table.


See built-in datatype.


In a printer definition file, an escape sequence to which you assign a printer code that can be referenced in a report.


A file that contains a printer definition in text (e.g., ASCII or EBCDIC) format.


A PL/SQL subprogram that performs a specified sequence of actions. .  Can reside and execute on the client and the database server.


A PL/SQL code structure that can be independently recognized and processed by the PL/SQL compiler.  Anonymous blocks, subprogram specifications and bodies (procedures and functions), and package specifications and bodies are types of program units.  Program units can reside and execute on the client and the database server.  See also:  stored program unit.


The basic data structure created by Project Builder.  Projects are collections of pointers to all the files you consider part of your application, or otherwise want to group together conceptually.  You can define the editors, compilers, and other tools you use to work with the items contained within a project.  All project information is stored within a project registry.  See also:  project item, project file, export.


In Project Builder, project files are all the files associated with an application.  Project files can be of any type, including forms, reports, displays, 3GL modules, documentation, and test scripts. See also:  project, project item.


In Project Builder, anything for which properties may be defined, including all entities stored under the Projects node, types, actions, and macros. See also: project, project file.


The window containing a hierarchical list of project items for the current session.  The list appears in outline form, and enables the user to accomplish several tasks such as creating, editing, renaming, and deleting objects.  Although only one is visible at any time, the user can choose from two different schema by which to organize the objects.


The top-level node for a project.  It represents or points to the project file.  See also: project, project file.


In Project Builder, the file that stores all the information associated with a project:  files belonging to the project, types, actions, and macros defined for the project, and so on.


The project view shows objects organized by their type, and by their project/subproject relationships.  The projects are organized alphabetically by project file, then alphabetically by category.  See also:  dependency view, project, project file, view.


A dialog that assists the user in accomplishing the steps necessary to create a new project or sub project.


A characteristic of an object that determines the behavior or appearance of that object.


A named object that contains a list of properties and their settings used to globally control the appearance and functionality of objects based on that class.


A string you can enter when connecting to a database or server that allows you to connect to a remote database or server.


(Oracle Express) When you select values for one of the dimensions in a measure, the other dimensions that make up that measure are known as qualifying dimensions.

Suppose your Sales measure is dimensioned by Product, Month, and Geography. If you select the top ten cities based on Sales, you must also specify which product and month you want to consider when you compare Sales values. In this case, Product and Month are the qualifying dimensions.


A SQL SELECT statement that specifies the data you wish to retrieve from one or more tables or views of a database.


A PL/SQL function that, when executed, filters data retrieved by a query.  Only the data that meet the conditions in the function are charted.


An option that terminates the current session and returns the user to the operating system.  On some systems, Quit is Exit.


A control (similar to a check box), appearing in sets of two or more, only one of which may be either "on" or "off" at any given time.


A set of two or more radio buttons, only one of which may be either "on" or "off" at any given time.


(Oracle Express) A Selector dialog box tool that allows the user to select consecutive time periods as dimension values. These time periods can be based on any of the following:

•	A specific number of the most recent time periods

•	A beginning time period and a most recent time period

•	A beginning and ending time period

For example, the user can select dimension values for the range from the week ending November 25, 1996 through the week ending December 30, 1996.


A cipher designed by RSA Data Security, Inc. which can accept keys of arbitrary length, and is essentially a pseudo random number generator with the output of the generator being XORed with the data stream to produce the encrypted data.  For this reason, it is very important that the same RC4 key never be used to encrypt two different data streams.


Acronym for Relational Database Management System.  A database that allows the definition of data structures, storage and retrieval operations, and integrity constraints.  In such a database, data and relations between them are organized in tables.


A file that contains a single report definition in binary format.  .RDF files are used to both run and edit reports.


A file that contains a single report definition in binary format.  .rep files are used solely to run reports; you cannot edit a .rep file.


The ability to query the data throughout a database as of a single point in time.


One row fetched by a SQL SELECT statement.


An internal data structure object with a column/row framework, that belong to the form module in which they are defined.


A type of column that points to data in other column objects or object tables (Oracle8).


A line that appears at a specified value on a chart.


(Oracle Express) Fetch the most recent data from an Express database after query results are displayed in your report. When you open a saved Express query, the results are refreshed automatically.


To add the definition of a type or a new project to either the global or local registry.  Upon being registered, a new type can have actions defined for it, while a new project can have its referenced files identified as specific types, so that actions can be invoked against them.  See also:  registry.


A global and/or user-specific configuration file used to store project definitions and environment information.  See also:  Global Registry, user registry.


A symbol used in search criteria to indicate a comparison between two values, such as the equal sign in "WHERE DEPTNO = 10." Rows in which the comparison results in "true" are returned in the result (fetched), while rows in which the comparison returns "false" are rejected from the result.


A database on a computer other than the local database.  Usually a computer on the same network, but at a different node (i.e., a database that you use through a database link).


A layout object used to display rows of data that are fetched for a group.


A mode in which each character you type replaces the current character at the cursor.  The opposite of insert mode.


The objects that are used to define a report's data model and layout.  Report-level objects are assigned to a single report, and cannot be shared by other reports or other Oracle products. Objects include reports, queries, external queries, external PL/SQL libraries, groups, columns, parameters, links, frames, repeating frames, fields, boilerplate, and anchors.


Available on Windows NT and Windows 95 only, waits for any command lines to run a report, then places that report in its queue to run in the background on the local server.  Typically command lines are received from Form Builder or Graphics Builder via RUN_PRODUCT, or from another report via SRW.RUN_REPORT.  You can also use RWISV60 to submit a report to the Reports Background Engine.


Maintains timestamp and status information about reports managed by the Reports Server.


Available on Windows NT, Windows 95, and UNIX, enables running reports on a remote server.  Queues job requests and allows you to schedule when to run reports.  Use RWCLI60 to send a report to the Reports Server.


Provides an interface between your Web Server and Reports Runtime, enabling you to run reports dynamically from your Web browser.


Provides a connection between a Web Server and the Reports Server.


A file that contains a report definition stored in text (e.g., ASCII or EBCDIC) format.  .REX files are used to port reports from one platform to another. Note that .REX files are no longer required. They are available for backward compatibility.


Refers to the intensities of the red, green, and blue components of a color.


The group object to which all other objects in an application belong.


Top-level node for a project representing user's environment.  May correspond to the user registry or the Global Registry, depending on which registry has been chosen to set defaults.


1. One set of field values in a table; for example, the fields representing one employee in the example table EMP.  2.  To generate a runtime version of an application.


An object in an Oracle8 object table.  Each row in the table is an object.  However, in Forms Developer an object table is deconstructed into individual columns, so that the row object no longer exists as a single entity (only as its separate attributes).


To execute a runtime version of an application or program unit.


Acronym for Rich Text Format.  A non-platform-specific file format based on control words used to represent unformatted text and images in various applications and operating systems.  RTF uses the ANSI, PC-8, Macintosh, or IBM PC character set to control the representation and formatting of a document, both on the screen and in print.


See rep file.


The interface in which users view and interact with a runtime application.


A screen or window appearing optionally at runtime in which a user can modify print options and parameters prior to report execution.


(Oracle Express) A set of dimension values that has been saved either as a list of values or as a script. You can save selections that you build, or your database administrator can create saved selections and make them available to you.

Saved selections are a timesaving feature: each time that you need to re-use a selection, you can simply retrieve a saved selection without having to recreate it.


(Oracle Express) A Selector tool that allows you to retrieve a selection of dimension values that has been saved.


A collection of related database objects, usually grouped by database userid.  Schema objects includes tables, views, sequences, stored program units, synonyms, indexes, clusters, and database links.


The level at, or range in which, an object operates.  For Project Builder:  1.  Describes the range of files affected by Compile and Compile All commands invoked against compilable project items.  2:  Describes the range of files influenced by inheritable definitions.


See SQL script, Interpreter script.


In Report Builder, one of multiple layouts in the same report, each with a different target audience, output format, page layout, page size, or orientation.  For example, a single report can include an executive summary for senior management in one section and also a detailed breakdown for  individual managers in another section.


A SQL statement that specifies which rows and columns to fetch from one or more tables or views.


(Oracle Express) The set of dimension values currently chosen for a dimension, or the script that contains conditions or criteria to specify those values.


(Oracle Express) As shown on various dialog boxes in the Selector, a description of the choices that a user has made in selecting dimension values. It is a translation, in ordinary language, of the Express Language script.


(Oracle Express) A set of tools that you use to choose the dimension values to include, for instance, in a report, table, graph, or dimension list box. For example, you can use the Selector to choose the top 10 cities based on Sales or those cities whose Sales exceeded Quota by 15 percent. The Selector also allows you to sort dimension values and to create and retrieve saved selections.


(Oracle Express) A dialog box or group of dialog boxes that provides a particular way of selecting or sorting dimension values. Each Selector tool is part of the Selector. You can use Selector tools to select dimension values based on their level in the hierarchy, their attributes, the characters in the value name, and so on. You can also use Selector tools to sort the dimension values.


The period between invoking and quitting the executable.


One of two or more objects that have the same parent object in its group tree.  All objects that belong to one group object are siblings.


The combination of an IP address and a port number.


(Oracle Express) A Selector dialog box tool that allows you to rearrange the order of dimension values in a displayed selection. You can sort a selection in ascending or descending order by the following:

•	Alphabet

•	Order in the database

•	Data value

•	Order or level in the hierarchy

•	Time period

You can also sort a selection manually, by dragging and dropping dimension values.


In PL/SQL:  Statements provided in a subprogram or package.  You must have the source code for a program unit before you can compile it into executable form.  In Project Builder:  The input types required to build target types.


Defines only the names, parameters, and return type (applies to functions only) of the subprogram.


A small rectangle at the bottom of the vertical scrollbar and to the left of the horizontal scrollbar in an editor.  Dragging and releasing the mouse button creates a new pane, and divides the scroll bar into separate scroll bars for each pane.


A standard interface for storing and retrieving information in a relational database.  SQL is an acronym for Structured Query Language.


A that contains a query stored in text (e.g., ASCII or EBCDIC) format.


A file containing SQL statements that you can run to perform database administration quickly and easily.  Several SQL scripts are shipped with Oracle products.


A SQL instruction to Oracle.  A SELECT statement is one type of SQL statement.


See call stack.


A PL/SQL construct used for conditional, iterative, and sequential control, and for error handling.  A semi-colon (;) must terminate every PL/SQL statement.


(Oracle Express) A saved selection that contains the same dimension values every time it is evaluated. Static saved selections list the dimension values that are to be selected, rather than the selection criteria. For example, a static saved selection script might include "Select February 1996, March 1996, and April 1996", while the script for a dynamic saved selection might have "Select the last three Months".


A procedure, function, or package that resides and executes in the Oracle database server.


A procedure or function that resides and executes in the Oracle database server.


HTML extensions that provide powerful formatting flexibility in HTML documents.  To view an HTML document that takes advantage of style sheets, display it in a browser that supports style sheets.


A PL/SQL procedure or function.


In Project Builder, a project contained within another project file, rather than being stored in its own file.  See also:  project.


In Project Builder, a node denoting a subproject.  See also:  project, project node, subproject node.


A column, with a type of summary, which computes subtotals, grand totals, running totals, and other summaries of the data in a report, using one of the packaged summary functions provided by Report Builder.


The file format used by the Microsoft Excel program.


The orderly system by which commands, qualifiers, and parameters are combined to form valid command strings.


One of the variables that are provided with Reports Developer (e.g., &Logical Page, DESTYPE).


A named collection of related information, stored in a relational database or server, in a two-dimensional grid that is made up of rows and columns.


A collection type, which defines a data unit made up of an unordered set of elements, all of the same data type.  The corresponding data unit is a single column nested table, the column type of which is a built-in type or an object type.  (Oracle8)


A default layout displaying labels at the top of the page and rows of data underneath the labels.


In Project Builder, any item in the middle of the dependency tree; for example, an executable is a (compile) target for a library; while a library is a target for a group of objects; and an object is a target for a source file.


A node denoting a target.  See also: target.


Acronym for Transmission Control Protocol. The underlying communication protocol for exchanging HTTP requests between clients and Web servers.


A submenu that the user can remove from its source using a mouse or other pointing device and drag to another part of the display screen.


In Form Builder, an item that displays a character string value.


The horizontal area at the top of a window that displays the name of the application or interface element in that window.


See header.


To turn a setting alternately on or off.  For example, you can hide or show the Object Navigator.


An iconic button used to create and manipulate objects in an application.


Collection of iconic buttons that perform product commands.  Usually aligned horizontally along the top, or vertically down the side of a window.


A collection of tools.


(Oracle Express) A Selector dialog box tool that allows the user to select dimension values based on the top x, bottom y, or top x and bottom y data values. For example, the user can produce a dimension selection that contains products whose Volume Sales were among the top 10 percent of products in the Total U.S. for the four-week time period ending December 30, 1995.


A optional report region that can contain closing material for the report, including text, graphics, data, and computations.  The report trailer appears last, following the header and body.


A sequence of SQL statements treated as a single unit.


A PL/SQL procedure that is executed, or "fired," upon a specific event.


A description of a file type, such as a form, a document, etc., containing such information as type name and description. Each description applies to a single file type.  In addition, there are four meta-types: "updtext", which applies to all text files, “updproj” which applies to all project files, “updlink”, which applies to all project links, and "all" which applies to any file type.  Types are the foundation for defining actions and macros.


To change the values for table data, in particular, by altering data values using the SQL command UPDATE, but also by deleting values using the SQL command DELETE or by inserting values using the command INSERT.


Acronym for Uniform Resource Locator. The "address" used to specify a WWW server and home page.  For example:
http://www.acme.com/
which indicates that the host's address is www.acme.com. An URL most often is a filename (possibly with a long path to it and usually with an extension of .HTML, or .HTM (for PC-DOS filenames).


A way in which to pass control (and possibly arguments) from Forms Developer to another Oracle product or 3GL, and then return control (and possibly arguments) back to Forms Developer.


A custom action defined by a Project Builder user.  Such actions may apply to any single file type, or to all file types.  See also:  action, pre-defined action.


See object type.


A custom macro defined by a Project Builder user.  Such macros may be used to modify both built-in actions and user-defined actions.  See also:: macro, built-in macro, action, pre-defined action.


A project file storing configuration information on a per-user basis.  This enables users to customize their individual development environments.  The user registry inherits type information from the Global Registry, and may define new types as well as override aspects of type definitions stored in the Global Registry.  It also stores environment and preference information, such as the user's preferred connection string, UI settings such as "Display Toolbar" and certain general project information such as "Author."  See also:  registry, Global Registry.


See continuous axis.


A PL/SQL code structure that returns a value.  Value constructs include functions and expressions.


A named object that can be assigned a value and whose assigned value may change over time.


A collection type, which defines a data unit made up of an ordered set of elements, all of the same datatype.  The corresponding data unit is a varying array or VARRAY.  The number of elements in a VARRAY (size) is variable.  However, you must specify a maximum size when you declare a varying array type.


Visual Basic extension.  Used as the file extension for special dynamic link libraries distributed on files that contain predefined VBX controls.


A widget, built with the Microsoft Visual Basic language, used to enhance the user interface, obtain user input, and display output  (e.g. sliders, grids, and control knobs).


A virtual table whose rows do not actually exist in the database, but which is based on a table that is physically stored in the database.


A directory mnemonic (essentially a shortcut or synonym) that the virtual file system uses to map files stored in the file system on the host machine.


A mapping that associates the pathnames used in URL to the file system maintained by the host machine's operating system.


The font, color, and pattern properties that you set for objects that appear in your application interface.


See WWW.


A program that end users utilize to read HTML documents and programs stored on a computer (serviced by a Web server).


A program executed on a Web server via the Web Request Broker.


A server process (HTTP daemon) running at a Web site which sends out Web pages in response to HTTP requests from remote Web browsers.


A character used to mean 'any one character' or 'a contiguous set of characters' within a word or phase.


1. A rectangular area of the desktop that contains an application.  Each window has an area where you can interact with the application.  Windows can be opened, resized, moved, reduced to an icon, or enlarged to fill the entire desktop.  2. In Form Builder, an object type you can associate with a canvas view.


The file format used by some spreadsheet programs, such as SQL*Calc, or by Lotus 1-2-3 programs.


Acronym for Oracle Web Request Broker.  Provides a powerful distributed runtime environment for developing and deploying applications for the Web.  The WRB runtime platform enables application developers to write applications that are independent of, and work with a number of, Web servers.


Acronym for World Wide Web.  The network of servers on the Internet, each of which has one or more home pages, which provide information and links to other documents on that and (usually) other servers.


To expand an object to allow more room for editing the contents of the field.


The secondary toolbar docked (by default) to the left of the Project Navigator.  It provides simple organization and application launching abilities.


 the latest version of OLE controls (OCX)


XML output complying with general XML principles such as proper tagging, nesting, and the inclusion of an XML declaration, e.g. <?xml version="1.0" encoding="UTF-8"?>.


A placeholder username enables users to log on to the database using their personal username rather than the Oracle database username (e.g., $user_name@database) when running reports from a Web browser.


Extensible Markup Language -- a metalanguage using SGML to define and structure data. Report Builder supports XML output to enable Web publishing as well as electronic data exchange with third-party applications. You can also use XML to build report definitions that can be merged with other report definitions at runtime or run separately


XML output with structure and element content conforming to a document type definition (DTD). Valid XML is also well-formed.


Using the online help

The following guidelines will help you to make effective use of the online help system:

•	Familiarize yourself with the Contents tab to get an idea of the scope of the topics covered in the online help.

•	Click the Related Topics button directly below topic titles for a list of topics related to the current topic.

•	Click the Options button at the top of any topic to set Keep Help on Top, so that help topics remain on your screen as you develop applications.

•	Click the Glossary button at the top of any topic for definitions of unfamiliar terms.


Documentation roadmap

To get started and become proficient with building applications:

1	Review the Quick Tour for a brief overview of each component:

•	Choose Help [image] Quick Tour.

2	Step through the Cue Cards to learn how to perform the most common tasks:

•	Choose Help [image] Cue Cards.

3	Display the online manuals (also available in hardcopy form):

•	Choose Help [image] Manuals.

4	Access the online help system:

•	Choose Help [image] Help Topics.

•	For context-sensitive help, press [Help] (this is usually the F1 key on most platforms).


National Language Support in Forms Developer

  Related Topics

When you design applications for international use, you want those applications to interact with users in their native language, using their specific local conventions for displaying data. Oracle’s National Language Support (NLS) includes three main layers:

•	Support for national language character encoding schemes.

•	Support for language and territory conventions.

•	Interface translation.

This combination of support at the character level, the data display level, and the interface level ensures that your applications will be usable in most European, Middle Eastern, and Asian languages, including multi-byte character encoding schemes and bidirectionality.


NLS architecture

  Related Topics

NLS architecture has two main parts:

•	language independent functions

•	language dependent data

Language-independent functions handle manipulation of data in an appropriate manner, depending on the language and territory of the runtime operator, and automatically format that data according to local date and time conventions.

Isolating the language-dependent data enables your application to deal only with translating the strings that are unique to your application.


National Language Support environment variables

  Related Topics

You can use the following parameters as environment variables to specify the language settings used by Forms Developer:

Parameter	Specifies:
NLS_CALENDAR	the calendar system used.
NLS_CREDIT	the string used to indicate a positive monetary value.
NLS_CURRENCY	the local currency symbol.
NLS_DATE_FORMAT	the default format used for dates.
NLS_DATE_LANGUAGE	the default language used for dates.
NLS_DEBIT	the string used to indicate a negative monetary value.
NLS_ISO_CURRENCY	the ISO currency symbol.
NLS_LANG	the language settings used by Forms Developer.
DEVELOPER_NLS_LANG	the language for the Forms Developer Builders.
USER_NLS_LANG	the language for the Forms Developer Runtime component.
NLS_LIST_SEPARATOR	the character used to separate items in a list.
NLS_MONETARY_CHARACTERS	the decimal character and thousands separator for monetary values.
NLS_NUMERIC_CHARACTERS	the decimal character and grouping separator for numeric values.
NLS_SORT	the type of sort used for character data.

For more information about these parameters, see the Oracle8 Reference manual.


NLS_LANG environment variable

  Examples	  Related Topics

The NLS_LANG environment variable determines the language settings used by Forms Developer.

NLS_LANG specifies:

•	the language used to display messages to the user, for example the 'Working...' message.

•	the default format masks used for dates and numbers.

•	the sorting sequence.

•	the characters that make up the character set.

The syntax of NLS_LANG is:

NLS_LANG=language_territory.charset

where:

language	specifies the language and its conventions for displaying messages and day and month names. If language is not specified, the value defaults to American.
territory	specifies the territory and its conventions for default date format, decimal character used for numbers, currency symbol, and calculation of week and day numbers. If territory is not specified, the value defaults to America.
charset	specifies the character set in which the data is represented. This should be a character set that matches your language and platform. This argument also controls the character set used for displaying messages.

For more information about NLS_LANG, see the Oracle8 Reference manual.


DEVELOPER_NLS_LANG and USER_NLS_LANG environment variables

  Examples	  Related Topics

In most cases, setting a single value for NLS_LANG will meet your needs. However, if you need to use two sets of resource and message files on the same machine at the same time, two other environment variables are available:

•	DEVELOPER_NLS_LANG specifies the language for the product's Builder.

•	USER_NLS_LANG specifies the language for the product's Runtime component.

The syntax of DEVELOPER_NLS_LANG and USER_NLS_LANG is the same as NLS_LANG.

Use these two variables, instead of the single NLS_LANG, in the following circumstances:

•	You prefer to use the Builder in English, but you are developing an application for another language.

•	You are creating an application to run in a language that uses a bidirectional character set.

•	You are creating an application to run in a language for which a local language version of the Builder is not available.

Note  If these environment variables are not specifically set, they take their default values from NLS_LANG.

For more information about NLS_LANG, see the Oracle8 Reference manual.


Setting NLS_LANG variables
Setting NLS_LANG environment variables

  Examples	  Related Topics

To set NLS_LANG environment variables:

  Define values for these variables in the same way you define other environment variables on your base operating system, keeping in mind platform-specific rules such as path length, etc.

For example, to set NLS_LANG for Microsoft Windows NT:

1	From the Start Menu choose Run.

2	Type 'regedit' and click OK to open the Registry Editor.

Note  The Windows registry is highly sensitive to changes. Only change environment variables if absolutely necessary. If you make a mistake, click Cancel and restart.

1	Expand the HKEY_LOCAL_MACHINE node, then expand the SOFTWARE node.

2	Click ORACLE to display the Oracle environment variables in the right panel of the Registry Editor.

3	Double-click the NLS_LANG environment variable.

4	Type the new value for NLS_LANG in the Value data text box and click OK.

Note  If you want to use any NLS feature, you must at least set NLS_LANG so that the product can locate the NLS components.


Font aliasing on Windows platforms

  Related Topics

There may be situations where you create an application with a specific font but find that a different font is being used when you run that application. You are most likely to encounter this problems when using an English font (such as MS Sans Serif or Arial) in a non-Western European environment. This occurs because Forms Developer checks to see if the character set associated with the font matches the character set specified by the language environment variable. If the two do not match, Forms Developer automatically substitutes the font with another font whose associated character set matches the character set specified by the language environment variable. This automatic substitution assures that the data being returned from the database gets displayed correctly in the application.

Note  If you enter local characters using an English font, Windows does an implicit association with another font.

There may be cases, however, where you do not want this substitution to take place. You can avoid this substitution by mapping all desired fonts to the WE8ISO8859P1 character set in the font alias file. For example, if you are unable to use the Arial font in your application, add the following line to your font alias file:

Arial.....=Arial...WE8ISO8859P1


Supported Microsoft Windows character sets

Character set name	Description
AR8MSWIN1256	MS Windows Code Page 1256 8-bit Latin/Arabic
BG8MSWIN	MS Windows 8-bit Bulgarian Cyrillic
CL8MSWIN1251	MS Windows Code Page 1251 8-bit Latin/Cyrillic
EE8MSWIN1250	MS Windows Code Page 1250 8-bit East European
EL8MSWIN1253	MS Windows Code Page 1253 8-bit Latin/Greek
ET8MSWIN923	MS Windows Code Page 923 8-bit Estonian
IW8MSWIN1255	MS Windows Code Page 1255 8-bit Latin/Hebrew
JA16SJIS	Shift-JIS 16-bit Japanese
KO16KSC5601	KSC5601 16-bit Korean
LT8MSWIN921	MS Windows Code Page 921 8-bit Lithuanian
TH8TISASCII	Thai Industrial Standard 620-2533 - ASCII 8-bit
WE8ISO8859P1	ISO 8859-1 West European
ZHS16CGB231280	CGB2312-80 16-bit Simplified Chinese
ZHT16BIG5	BIG5 16-bit Traditional Chinese


Supported Arabic display character sets

Id	Character set name	Description
61	AR8ASMO708PLUS	ASMO 708 Plus Client 8-bit Latin/Arabic
72	AR8XBASIC	EBCDIC XBASIC Client 8-bit Latin/Arabic
504	AR8NAFITHA711T	Nafitha Enhanced 711 Client 8-bit Latin/Arabic
505	AR8SAKHR707T	SAKHR 707 Client 8-bit Latin/Arabic
506	AR8MUSSAD768T	Mussa'd Alarabi/2 768 Client 8-bit Latin/Arabic
507	AR8ADOS710T	Arabic MS-DOS 710 Client 8-bit Latin/Arabic
508	AR8ADOS720T	Arabic MS-DOS 720 Client 8-bit Latin/Arabic
509	AR8APTEC715T	APTEC 715 Client 8-bit Latin/Arabic
511	AR8NAFITHA721T	Nafitha International 721 Client 8-bit Latin/Arabic
514	AR8HPARABIC8T	HP ARABIC8 Client 8-bit Latin/Arabic
567	AR8ARABICMACT	Mac Client 8-bit Latin/Arabic


Language and territory conventions

  Related Topics

While the character encoding schemes ensure that the individual characters needed for each language are available, support for national conventions provides correct localized display of data items.

The specified language determines the default conventions for the following characteristics:

•	language for server messages

•	language for day and month names and their abbreviations (specified in the SQL functions TO_CHAR and TO_DATE)

•	symbols for equivalents of AM, PM, AD, and BC

•	default sorting sequence for character data when ORDER BY is specified (GROUP BY uses a binary sort, unless ORDER BY is specified)

•	writing direction

•	affirmative/negative response strings

For example, if the language is set to French, the messages:

ORA-00942:  table or view does not exist
FRM-10043:  Cannot open file.

will appear as:

ORA-00942: table ou vue inexistante
FRM-10043: Ouverture de fichier impossible.

The specified territory determines the conventions for the following default date and numeric formatting characteristics:

•	date format

•	decimal character and group separator

•	local currency symbol

•	ISO currency symbol

•	week start day

•	credit and debit symbol

•	ISO week flag

•	list separator

For example, if the territory is set to France, numbers will be formatted using a comma as the decimal character.


Supported languages

Abbreviation	Language
us	American
ar	Arabic
bn	Bengali
ptb	Brazilian Portuguese
bg	Bulgarian
frc	Canadian French
ca	Catalan
hr	Croatian
cs	Czech
dk	Danish
nl	Dutch
eg	Egyptian
gb	English
et	Estonian
sf	Finnish
f	French
d	German
din	German DIN
el	Greek
iw	Hebrew
hu	Hungarian
is	Icelandic
in	Indonesian
i	Italian
ja	Japanese
ko	Korean
esa	Latin American Spanish
lv	Latvian
lt	Lithuanian
ms	Malay
esm	Mexican Spanish
n	Norwegian
pl	Polish
pt	Portuguese
ro	Romanian
ru	Russian
zhs	Simplified Chinese
sk	Slovak
sl	Slovenian
e	Spanish
s	Swedish
th	Thai
zht	Traditional Chinese
tr	Turkish
uk	Ukrainian
vn	Vietnamese

Note  The fact that a particular language is supported does not necessarily mean that a translation for that language is available.


Supported territories

Algeria	Greece	Portugal
America	Hong Kong	Qatar
Austria	Hungary	Romania
Bahrain	Iceland	Saudi Arabia
Bangladesh	Iraq	Slovakia
Brazil	Israel	Slovenia
Bulgaria	Italy	Somalia
Canada	Japan	Spain
Catalonia	Jordan	Sudan
China	Korea	Sweden
CIS	Kuwait	Switzerland
Croatia	Latvia	Syria
Cyprus	Lebanon	Taiwan
Czech Republic	Libya	Thailand
Czechoslovakia	Lithuania	The Netherlands
Denmark	Malaysia	Tunisia
Djibouti	Mauritania	Turkey
Egypt	Mexico	Ukraine
Estonia	Morocco	United Arab Emirates
Finland	Norway	United Kingdom
France	Oman	Vietnam
Germany	Poland	Yemen


Bidirectional support in Forms Developer

  Related Topics

NLS support for Middle Eastern and North African languages includes bidirectional support for languages whose natural writing direction is right-to-left.

Bidirectional support enables developers to control:

•	layout direction, which includes displaying items with labels at the right of the item and correct placement of check boxes and radio buttons.

•	reading order, which includes right-to-left or left-to-right text direction.

•	alignment, which includes switching point-of-origin from upper left to upper right.

•	initial keyboard state, which controls whether Local or Roman characters will be produced automatically when the end user begins data entry in forms (the end user can override this setting).

In addition to the NLS_LANG environment variable, bidirectional applications may use two additional environment variables:

•	DEVELOPER_NLS_LANG

•	USER_NLS_LANG

For example, if you want to use an American interface while developing an Arabic application in a Windows environment, set these environment variables as follows:

DEVELOPER_NLS_LANG=AMERICAN_AMERICA.AR8MSWIN1256
USER_NLS_LANG=ARABIC_territory.charset


Bidirectional support in Form Builder

  Related Topics

Five properties are used to specify the appearance of objects in bidirectional applications: Direction, Justification, Reading Order, Keyboard State, and Initial Keyboard State.

Direction is an umbrella property that provides as much functionality for each object as possible. For all objects except text items and display items, the Direction property is the only bidirectional property, and its setting controls the other aspects of bidirectional function. (List items, however, include Initial Keyboard State and Keyboard State properties.)

Text items and display items do not have a Direction property; instead, you can specifically set Justification, Reading Order, Initial Keyboard State, and Keyboard State properties for these items.

You may restrict the keyboard state to one language. For example, setting Keyboard State to Local prevents the end user from switching the keyboard to another language.

When the bidirectional properties are set to Default, those properties inherit their values from the natural writing direction specified by the language environment variable.  In most cases, this will provide the desired functionality.  You only need to specify the bidirectional properties when you want to override the inherited default values.

Inheritance for bidirectional properties is as follows:

	Default setting derives value from this object
Form	language environment variable
All objects, such as Alert, Block, LOV, Window, and Canvas-view	Form
All items, such as Text Item, Display Item, Check Box, Button, Radio Group, and List Item	Canvas-view

Most properties related to bidirectional function can be retrieved and set programmatically. For more information, see the appropriate built-in subprogram description. For example, for information about getting the value of the Direction property for buttons, see the description for GET_ITEM_PROPERTY.


Bidirectional support in Report Builder

  Related Topics

Four properties are used to specify the appearance of objects in bidirectional applications: Justify, Direction (for an object), and Direction (for the report).  The bidirectional properties are added to objects in the following hierarchy:

Module

Boilerplate

Field

External Boilerplate

Button

Parameter Form Boilerplate

Objects not in this list either do not require bidirectional support (for example, images) or they are defaulted from one of the above object’s properties.


Unicode support in Forms Developer

  Related Topics

Unicode is a global character set that allows multilingual text to be displayed in a single application. This enables multinational corporations to develop a single multilingual application and deploy it worldwide.

Global markets require a character set that:

•	allows a single implementation of a product for all languages, yet is simple enough to be implemented everywhere.

•	contains all major living scripts.

•	supports multilingual users and organizations.

•	enables worldwide interchange of data via the Internet.

Forms Developer provides Unicode support. If you use Unicode, you will be able to display multiple languages, both single-byte languages such as Western European, Eastern European, Bidirectional Middle Eastern, etc. and multi-byte Asian languages such as Chinese, Japanese, and Korean (CJK) in the same application.

Use of a single character set that encompasses all languages eliminates the need to have various character sets for various languages.

For example to display a multi-byte language such as Japanese, the NLS_LANG environment variable must be set to (for Windows platform):

Japan_Japanese.JA16SJIS

To display a single-byte language such as German, NLS_LANG must be set to (for Windows platform):

German_Germany.WE8ISO8859P1

The obvious disadvantage of this scheme is that applications can only display characters from one character set at a time. Mixed character set language data is not possible.

With the Unicode character set, you can set the character set portion of NLS_LANG to UTF8 instead of a specific language character set. This allows characters from different languages and character sets to be displayed simultaneously.

For instance to display Japanese and German together on the screen the NLS_LANG variable setting must be:

Japanese_Japan.UTF8

or

German_Germany.UTF8

The Unicode capability of Forms Developer gives the application developer and end user the ability to display multilingual text in a form. This includes text from a database containing Unicode, multilingual text, text in GUI objects (for example, button labels), text input from the keyboard, and text from the clipboard. Forms Developer currently supports Unicode on Windows NT 4.0 and Windows 95/98 (limited support).

Note  If you develop applications for the Web, you can use Unicode because of the Unicode support provided by Java.


Configuration considerations

  Related Topics

UNIX servers can support multiple ORACLE_HOMEs (where ORACLE_HOME is the directory created by and for Oracle software) and can therefore support multiple NLS settings. This means a single UNIX server can support multiple languages.

Windows NT however, can only support a single ORACLE_HOME and therefore can only have one NLS setting. This means Windows NT can only support one language.


Unicode font support

  Related Topics

To display Unicode multilingual text, a font must be used that contains the glyphs, or characters of the languages to be displayed. On Windows NT and Windows 95/98, you must use either TrueType 'Big Fonts' supplied by Microsoft, or a third party Unicode font. If you try to type, display, or print multilingual text and see unexpected characters, you are probably not using a Big Font. Big Fonts provided by Microsoft under NT 4.0 are:

•	Arial

•	Courier New

•	Lucida Console

•	Lucida Sans Unicode

•	Times New Roman

A third party font may be used if Windows Big Fonts do not meet the display requirements.


Enabling Unicode support

  Related Topics

To enable Unicode support in Forms Developer, set NLS_LANG as follows:

NLS_LANG=language_territory.UTF8


Converting between character sets

  Related Topics

When you begin to design applications for use in multiple languages, you need to consider both the character sets used by application end users, and those used by application developers. While conversion at the character set level at runtime is automatic, this conversion impacts performance.

For example, if you build an application in one character set and run it in another character set, you may notice a degradation in performance. In addition, if a character set does not contain an equivalent for a particular character, it will display a replacement character instead, for example a question mark (?). However, even if you don’t see any visible difference, as a developer you will want to pay attention to the character sets you use to generate, because of performance issues.

Note  Forms Developer only converts between character sets for the same language, for example AR8MSWIN and AR8ISO, or IW8MSWIN and IW8ISO.

If you are designing applications to run in more than one language, or even in the same language with different character sets, for best performance you will want to match your generate environment to your runtime environment:

•	Determine the character set most widely used at runtime.

•	Generate with the language environment variable set to that character set.

Note  For Form Builder, the character set used when generating is used at runtime, regardless of the character set specified in the runtime environment.


The Forms Developer user interface

  Related Topics

Oracle uses a single executable approach for software internationalization. This means that you do not need a separate executable (for example f60des.exe) to process single-byte European languages or multi-byte Asian languages. The same set of tools can be used to create both English and non-English applications.

Note  Forms Developer relies on the Microsoft Windows operating system for the font and input method for the different languages. To enter and display text in any particular language, you must be running a version of Windows that supports that language (that is, to display Thai, you must be running Thai Windows).

When you install Forms Developer, you select the language of the message files you want to install. When you use an Forms Developer component (for example Form Builder), the appropriate message file, based on the language environment variable, is used to display the interface, including:

•	messages

•	menus and menu items

•	dialog boxes

•	prompts and hints

•	alerts

If Forms Developer does not find a message file that corresponds to the current language setting, it defaults to the American message files.

Note  During installation you can only specify one language to install message files for in addition to American. If you later want to use Forms Developer with a different language, you will need to reinstall Forms Developer with the appropriate message files.

Message file names specify both the Forms Developer component and the language, using the following file naming convention:

<product_id><language_id>.MSB

For example, for Form Builder:

FMDUS.MSB contains default (American) Builder messages

FMGUS.MSB contains default (American) Generate messages

FMFUS.MSB contains default (American) Runform messages

FMFI.MSB contains Italian Runform messages

FMFD.MSB contains German Runform messages

For more information about installation of language dependent message file, see the Installation and User Guide for your platform.

Note  Language supplements are not forward compatible, they are only meant to work with the version of Forms Developer they were released with. If you already have language supplements from previous releases, these must be removed from your system.


Using CONVERT to convert data

You can use the SQL function CONVERT to convert data between character sets. This function converts the binary representation of a character string in one character set to another. For information about converting, see Converting between character sets.

For a complete description of CONVERT, see the Oracle8 SQL Reference manual.


Default format masks

  Examples	  Related Topics

The language environment variable establishes not only the language used for the Forms Developer interface (both Builders and Runtime), but also the set of default format masks used to display that data, unless explicit format masks override the default. As an application developer, you also have additional NLS-related format mask characters available if you choose to override the default display masks.

All data input into Forms Developer or the application will use the default format masks associated with the specified territory, so you can change languages when building an application as well as when running it, without needing to change the date and number formats.

Specifically, Forms Developer uses the default format masks:

•	in the Builder: When the Builder displays default values for items, ranges, or parameters

•	at runtime: If a user enters data into a text item whose type is territory specific, such as DATE or NUMBER

While working with date and currency fields for multilingual applications, you will want to consider:

•	Whether to make all displayed items (boilerplate, text items, interface objects such as buttons and lists of values) longer to accommodate text translation and language-specific conventions for numeric display.

•	Whether you need to use the NLS-related format mask characters to create special format masks, or if the default format masks invoked by NLS_LANG are sufficient.


Tip
For implicit datatype conversions, PL/SQL always expects items in the America default format (such as DD-MON-YY), so if you use an item whose type is territory-specific in PL/SQL, you will need to specify the correct format masks. Oracle recommends that you use TO_DATE to translate territory-specific items in PL/SQL.

IF :emp.hiredate < TO_DATE(’30-12-1996’,’DD-MM-YYYY’) THEN
   ...


Format mask characters

  Examples	  Related Topics

The following format mask characters allow you to override the default format masks.

Date format mask characters

Character	Returns
D	Digit for the day (1-7)
DY	Name of the day (abbreviated)
DAY	Name of the day (padded with blanks to the length of 9 characters)
WW	Digit for the week, calculated by the algorithm int((day-jan1)/7)
IW	Digit of the ISO week
MON	Name of the month (abbreviated)
MONTH	Name of the month (padded with blanks to the length of 9 characters)
RM	Character for the Roman numeral month
I,IY,IYY,IYYYY	Last one, two, or three digits of the ISO year or the ISO year, respectively
BC,AD,B.C.,A.D.	BC or AD indicator (with or without periods)
AM,PM,A.M.,P.M.	AM or PM indicator (with or without periods)
For more information on ISO and its date format masks, see the Oracle Server SQL Reference.

Number format mask characters

Character	Returns
C	International currency symbol
L	Local currency symbol
D	Decimal separator
G	Group (thousands) separator


Sorting character data

  Restrictions	  Examples	  Related Topics

Conventionally, when character data is sorted, the sort sequence is based on the numeric values of the characters defined by the character encoding scheme. Such a sort is called a binary sort and produces reasonable results for the English alphabet because the ASCII and EBCDIC standards define the letters A to Z in ascending numeric value.  Note

However, when characters used in other languages are present, a binary sort generally does not produce reasonable results. For example, an ascending ORDER BY query would return the character strings ABC, ABZ, BCD, ÄBC, in that sequence, when the Ä has a higher numeric value than B in the character encoding scheme.

To produce a sort sequence that matches the alphabetic sequence of characters for a particular language, another sort technique must be used that sorts characters independently of their numeric values in the character encoding scheme. This technique is called a linguistic sort. A linguistic sort operates by replacing characters with other binary values that reflect the character's proper linguistic order so that a binary sort returns the desired result.

Linguistic special cases  Linguistic special cases are character sequences that need to be treated as a single character when sorting. Such special cases are handled automatically when using a linguistic sort. For example, one of the linguistic sort sequences for Spanish specifies that the double characters ch and ll are sorted as single characters appearing between c and d and between l and m respectively.

Another example is the German language sharp s (ß). The linguistic sort sequence German can sort this sequence as the two characters SS, while the linguistic sort sequence American sorts it as SZ.

Special cases like these are also handled when converting uppercase characters to lowercase, and vice versa. For example, in German the uppercase of the sharp s is the two characters SS. Such case-conversion issues are handled by the NLS_UPPER, NLS_LOWER, and NLS_INITCAP functions, according to the conventions established by the linguistic sort sequence. (The standard functions UPPER, LOWER, and INITCAP do not handle these special cases.)

NLSSORT function  You can use the SQL function NLSSORT to sort character data. This function replaces a character string with the equivalent sort string used by the sort mechanism. For a binary sort, the sort string is the same as the input string. When a linguistic sort is being used, NLSSORT returns the binary values used to replace the original string.


Note
In the ASCII standard all uppercase letters appear before any lowercase letters. In the EBCDIC standards, the opposite is true: all lowercase letters appear before any uppercase letters.


Linguistic sorting restrictions

  Related Topics

Linguistic sorting is not supported on multi-byte character sets.


Comparing strings in a WHERE clause

  Examples	  Related Topics

Character strings in a WHERE clause are compared using the characters’ binary values: a character is 'greater than' another if it has a higher binary value in the database character set. Because the sequence of characters based on their binary values may not match the alphabetic sequence for a language, the comparisons often do not follow alphabetic conventions. Use the NLSSORT function to perform a linguistic sort instead of a binary sort.


Controlling an ORDER BY clause

  Related Topics

If a linguistic sorting sequence is in use, then NLSSORT is implicitly used on each character item in the ORDER BY clause. As a result, the sort mechanism (linguistic or binary) used for an ORDER BY is transparent to the application.

However, if the NLSSORT function is explicitly specified for a character item in an ORDER BY item, then the implicit NLSSORT is not done. In other words, the NLSSORT linguistic replacement is only applied once, not twice.

The NLSSORT function is generally not needed in an ORDER BY clause, when the default sort mechanism is a linguistic sort. However, when the default sort mechanism is binary, then a query such as:

SELECT ENAME FROM EMP

ORDER BY ENAME

will use a binary sort. A linguistic sort (for German in the example below) can be obtained using:

SELECT ENAME FROM EMP

ORDER BY NLSSORT(ENAME, ’NLS_SORT = GERMAN’)


Using ALTER SESSION

  Examples	  Related Topics

You can use the ALTER SESSION SQL command to override the NLS defaults. For example, suppose you create some parameters (such as language, territory, etc.), and a user specifies values for them: you could then alter the session as they specified.

Note  At runtime, the server executes an ALTER SESSION command on behalf of the client based on the values specified in NLS_LANG. If NLS_LANG is not defined, the ALTER SESSION statement is not executed.

In Form Builder, you can specify any of the following NLS parameters for the ALTER SESSION command. However, for Report Builder and Graphics Builder, you can only specify the NLS_SORT parameter.

Parameter	Description
NLS_LANGUAGE	Language used by the server to return messages and errors
NLS_TERRITORY	Territory used for default date and currency masks
NLS_DATE_FORMAT	Default format used for dates
NLS_DATE_LANGUAGE	Default language used for dates
NLS_NUMERIC_CHARACTERS	Decimal character and group separator
NLS_ISO_CURRENCY	ISO international currency symbol
NLS_CURRENCY	Local currency symbol
NLS_SORT	Character sort sequence
NLS_CALENDAR	Current calendar system

For details on these parameters, see the Oracle8 SQL Reference manual.


Using NLS parameters in SQL functions

  Related Topics

Wherever you use SQL, you can use the following NLS parameters to override default NLS behavior.

SQL Function	NLS Parameter(s)
TO_DATE	NLS_DATE_LANGUAGE NLS_CALENDAR
TO_NUMBER	NLS_NUMERIC_CHARACTERS NLS_CURRENCY NLS_ISO_CURRENCY
TO_CHAR	NLS_DATE_LANGUAGE NLS_NUMERIC_CHARACTERS NLS_CURRENCY NLS_ISO_CURRENCY NLS_CALENDAR
NLS_UPPER	NLS_SORT
NLS_LOWER	NLS_SORT
NLS_INITCAP	NLS_SORT
NLSSORT	NLS_SORT

For details on these parameters, see the Oracle8 SQL Reference manual.


Form Builder NLS parameters

  Related Topics

You can use Form Builder built-in functions to obtain the current value of the NLS environment variables for use in PL/SQL code:

	DEVELOPER_NLS_LANG	USER_NLS_LANG
Built-in	GET_FORM_PROPERTY	GET_APPLICATION_PROPERTY
Parameter	MODULE_NLS_LANG	USER_NLS_LANG

Because both USER_NLS_LANG and DEVELOPER_NLS_LANG default to the value of NLS_LANG, the Form Builder NLS parameters will hold the value of NLS_LANG if either variable is not specifically set.

Both Form Builder NLS parameters have four variations, to allow you to retrieve either the complete environment variable or a specific portion of it. This table shows the four parameters of the GET_APPLICATION_PROPERTY built-in that returns the USER_NLS_LANG environment variable:

Parameter	Returns
USER_NLS_LANG	Entire USER_NLS_LANG variable
USER_NLS_LANGUAGE	Language portion only
USER_NLS_TERRITORY	Territory portion only
USER_NLS_CHARACTER_SET	Character set portion only

To retrieve the DEVELOPER_NLS_LANG environment variable, call GET_FORM_PROPERTY, using the MODULE_NLS_LANG parameter.


Printer definition files and National Language Support

  Related Topics

When using reports in character mode, you should define the physical page width of a report as one character less than the page width defined in the printer definition file (.PRT file). Otherwise, multi-byte characters might start on the last character space of a line and have to overflow to the next line in order to complete. For example, if the physical page width is 80 characters and the width in the printer definition is 80 characters, a multi-byte character might start on the 80th character. Since multi-byte characters may not be separated, the line would have to overflow to an 81st character in order to complete the multi-byte character. To avoid this, the physical page width should be set to 79 for the report.

The following Arabic and Hebrew specific NLS parameters can be set in the printer definition file:

Use:	To:	Values:
nls locale	set the locale of printing engine.	hebrew or arabic
nls datastorageorder	set logical or visual data storage.	logical or visual
nls contextuallayout	perform pre contextual layout for Arabic printers.	no or yes
nls contextualshaping	perform pre contextual shaping for Arabic printers.	no or yes
nls pcharset	specify the character set of the printer.	any character set

For more information about printer definition files, see the Report Builder help system.


Translating applications

  Related Topics

All error messages and boilerplate text should be in the same language. When running an application, an end user views messages and boilerplate text from three sources:

•	error messages from the server

•	runtime error messages produced by Forms Developer

•	messages and boilerplate text defined as part of the application

Oracle's NLS handles translation for the first two sources. You, as the application developer are responsible for translating the messages and boilerplate text for the third source.

In general, there are two types of application-specific text you will need to translate:

•	translatable text, such as menus, boilerplate text, item labels, messages, and hints

•	strings in triggers and procedures, including alerts and messages defined in triggers

Translation Builder helps you translate the 'translatable text' strings in the user interface into multiple languages. You can use Translation Builder to assist with translation for almost all multilingual Forms Developer applications by generating separate binary files for each language.

While Translation Builder helps you find and translate strings in the user interface, it cannot pull out string constants in PL/SQL triggers and procedures. Manual translation is required for constant text within PL/SQL block, because that text is not clearly delimited, but is often built up from variables and pieces of strings.

For a complete description of Translation Builder, refer to the Translation Builder help system.


Design considerations

  Related Topics

When designing an application that will be translated, remember to leave extra space for widgets and boilerplate labels. To accommodate multiple character sets and allow for expansion caused by translation, a rule-of-thumb is to leave 30% white space around fields, borders, and boilerplate text.

For example:

Prompt on left of field	Allow 30% expansion room to left of prompt.
Prompt above field	Allow 30% expansion room to right of prompt.
Buttons, check boxes, radio groups and poplists	Allow for 30% expansion.
Titles	Size any bounding box so the title can expand to the right by 30%.
Display-only fields	Size 30% wider than needed for the base language.
All widgets	Make widgets large enough to accommodate translation. For example, buttons need to be large enough to hold translated labels. Check button height as well as length, to be sure the height of the button will accommodate the tallest character you need to use. For example, calculate pixels needed to render Kanji characters.


Using the Translation Builder approach

  Related Topics

You can use Translation Builder to assist with translation for almost all multilingual Forms Developer applications. Unless your application requires end users to toggle between languages at runtime, you can use Translation Builder and then generate separate binary files for each language.

To change from one language to another at runtime, the user exits the application, changes the language environment variable, and then restarts the application.

Using the Translation Builder approach, you would develop your application in the following stages:

•	Create one basic application definition (for example .FMB, .RDF) in the source language.

•	Use Translation Builder to extract strings for translation, allow translation into one or several languages, and then store the strings back into the application definition.

•	Manually translate standard messages in PL/SQL libraries.

•	Use the Generator to generate a binary version of the application for each target language.

Advantages  This is the simplest way to implement multiple language applications quickly. With this approach, you can use Translation Builder for maximum efficiency. If you have a stable application, this approach will work well for you.

For example, if you created an application in four languages and then needed to change the text of a field label, you would make the change in the Builder, save the change in the definition file, use Translation Builder to translate the new field label, and then insert the new messages into the definition file and regenerate to create a binary file containing the new label.

Disadvantages  If your applications must support multiple languages simultaneously, you must use the runtime language switching approach instead.


Using the runtime language switching approach

  Related Topics

A small number of applications must support multiple languages simultaneously. For example, the application may begin by displaying a window in English which must stay up throughout the application, while an end user may press a button on that window to toggle the prompts into French, and then back into English.

If your application requires runtime language switching, you can include more than one language in a single application as long as they share the same character set, but you cannot use Translation Builder to locate translatable text if you are dynamically populating the text at runtime. Instead, you would build case structures (IF...THEN...ELSIF) to change the application to another language by checking the value of the NLS environment variable using the GET_FORM_PROPERTY built-in.

Using the runtime language switching approach, you would develop your application in the following stages:

•	Develop the entire application for one language, including libraries.

•	Manually translate each library.

•	Design boilerplate labels as appropriately sized display items that are dynamically populated at runtime.

Form Builder supports attaching multiple libraries, so you can use one library specifically for messages that will be translated, and other libraries for other purposes.

Advantages  The main advantage of this approach is it allows you to support sophisticated applications in which the forms may be highly dynamic. In these cases, this approach avoids some maintenance problems, because you do not have to generate separate files for each language each time the form changes.

Disadvantages  This approach is more complicated, because it involves considerable effort to create the language-specific message storage, population, and maintenance involved and to perform the translation manually. For example, you would set up a WHEN-NEW-FORM-INSTANCE trigger to set the labels for each button, pulling the correct labels from an attached library, based on the value of the NLS environment variable.


Using PL/SQL libraries for strings in code

  Examples	  Related Topics

While Translation Builder assists in translating messages that are part of the standard Builder interface, messages that are displayed programmatically require special treatment. You can use the PL/SQL libraries to implement a flexible message structure for messages in triggers or procedures.

For application-specific messages—those displayed programmatically to the screen by the built-in routines MESSAGE or CHANGE_ALERT_MESSAGE, or by assigning a message to a display item from a trigger or procedure—you can use the attachable PL/SQL libraries to implement a flexible message function. The library can be stored on the host, then dynamically attached at runtime. At runtime, based on a search path, you can pull in the library attached to the form. (For example, a library might hold only the Italian messages.)


National Language Support examples

  Related Topics 	  All examples

Comparing strings examples

Format mask examples

NLS_LANG examples

PL/SQL libraries example


ALTER SESSION examples

  Related Topics

The following statement changes the decimal character to a comma and the group separator to a period:

ALTER SESSION
   SET NLS_NUMERIC_CHARACTERS = ',.'

These new characters are returned when you use their number format elements D and G:

SELECT TO_CHAR(SUM(sal), 'L999G999D99') Total FROM emp

TOTAL
--------------
   FF29.025,00

The next statement changes the ISO currency symbol to the ISO currency symbol for the territory America:

ALTER SESSION
   SET NLS_ISO_CURRENCY = America

The ISO currency symbol defined for America is used:

SELECT TO_CHAR(SUM(sal), 'C999G999D99') Total FROM emp

TOTAL
---------------
   USD29.025,00

The next statement changes the local currency symbol to DM:

ALTER SESSION
   NLS_CURRENCY = 'DM'

The new local currency symbol is returned when you use the L number format element:

SELECT TO_CHAR(SUM(sal), 'L999G999D99') Total FROM emp

TOTAL
--------------
   DM29.025,00


Comparing strings examples

  Related Topics 	  All examples

Suppose you have a column (COL1) that contains the values ABC, ABZ, BCD and ÄBC in the ISO 8859/1 8-bit character set. Suppose also, that you wrote the following query:

SELECT COL1 FROM TAB1 WHERE COL1 > 'B'

The query would return both BCD and ÄBC since Ä has a higher numeric value than B.

You can perform linguistic comparisons using NLSSORT in the WHERE clause, as follows:

WHERE NLSSORT(column) operator NLSSORT(string)

Notice that NLSSORT has to be used on both sides of the comparison operator.

SELECT COL1 FROM TAB1 WHERE NLSSORT(COL1) > NLSSORT('B')

If a German linguistic sort is being used, this will not return strings beginning with Ä, because Ä comes before B in the German alphabet. If a  Swedish linguistic sort is being used, those strings would be returned, because Ä comes after Z in the Swedish alphabet.


Format mask examples

  Related Topics 	  All examples

For NLS-compliant applications, avoid hard-coding a string containing a month name. However, if a hard coded month name is essential, avoid using the COPY built-in. If you use COPY, the month name may be incorrect, depending on which language is specified. (To specify a date in a library, use a variable for the date and COPY will work.)

Language-dependent example (not recommended):

:emp.hiredate := '30-DEC-96';

copy ('30-DEC-96','emp.hiredate');

Instead, use TO_DATE, as shown in the following example.

Language-independent example (recommended):

:emp.hiredate := to_date(’30-12-1996’,’DD-MM-YYYY’);


NLS_LANG examples

  Related Topics 	  All examples

Suppose you want your application to run in French. The application will be used in France and data will be displayed using the WE8ISO8895P1 character set. You would set NLS_LANG as follows:

NLS_LANG=French_France.WE8ISO8895P1

Now, suppose you still want your application to run in French, but this time it will be used in Switzerland. You would set NLS_LANG as follows:

NLS_LANG=French_Switzerland.WE8ISO8895P1

More examples:

NLS_LANG=Norwegian_Norway.NDK7DEC
NLS_LANG=Norwegian_Norway.WE8ISO8895P1
NLS_LANG=Japanese_Japan.JA16SJIS
NLS_LANG=Arabic_Egypt.AR8MSWIN1256
NLS_LANG=American_America.AR8MSWIN1256
NLS_LANG=American_America.WE8ISO8859P1


PL/SQL libraries example

  Related Topics 	  All examples

FUNCTION nls_appl_mesg(index_no NUMBER)

RETURN CHAR

IS

   msg CHAR(80);

BEGIN

   IF index_no = 1001 THEN

      msg := 'L''impiegato che Voi cercate non esiste...';

   ELSIF index_no = 1002 THEN

      msg := 'Lo stipendio non puo essere minore di zero.';

   ELSIF ...

   :

   ELSE

      msg := 'ERRORE: Indice messaggio inesistente.';

   END IF;

   RETURN msg;

END;

A routine like this could be used anywhere a character expression would normally be valid: for example, to display an alert with the appropriately translated application message you might include the following code in your form:

Change_Alert_Message('My_Error_Alert', nls_appl_mesg(1001));

n := Show_Alert('My_Error_Alert');

To change the application to another language, simply replace the PL/SQL library containing the nls_appl_mesg function with a library of the same name containing the nls_appl_mesg function with translated text.

If the application needs to support multiple languages simultaneously, the function above could accept an additional parameter indicating the desired language and the code would then contain an additional level of IF...THEN...ELSIF...ELSE...END IF to handle the various languages.


Help topic not found.  Check the online help for related topics.


Oracle8 objects examples

  Related Topics 	   All Examples

Object Type

Table Type

Varying Array Type

Column Object

Object Table

Object View


Oracle8 Server support

  Related Topics

The Oracle8 Server provides a number of new features.  In general, the features are in these categories:

•	Greater scalability.  For example, Oracle8 databases can contain tens of terabytes of data, and can support simultaneous access by up to 10000 users.  Tables themselves can now contain up to 1000 columns.  CHAR and VARCHAR2 datatypes can now be up to 2000 and 4000 bytes, respectively.

•	Greater performance and efficiency.  Use of these Oracle8 features is handled for you and requires no actions on your part.  You automatically receive the speed and reliability benefits of having your data on the Oracle8 Server.

•	Large objects (sometimes called LOBs)

•	User-defined objects.

Continued support for Oracle7

Oracle7 Server features are still supported (Release 7.3.4 and later).


Oracle8 datatypes supported

  Related Topics

This release continues to support the following Oracle8 datatypes:

Large objects (LOBs)

In Oracle8, programmers can define large objects, often called LOBs.  These can store such things as text, images, sound, or video.

This release supports the following Oracle8 large object datatypes:

•	BLOB, or binary large object

•	CLOB, or single-byte character large object

•	BFILE, or binary file (sometimes referred to as an external file).

User-defined objects

In Oracle8, programmers can define object types (also called user-defined types), which are composites based on the existing single-element datatypes supported by Oracle8.  Using these object definitions, programmers can then create various kinds of tables.

Currently supported Oracle8 objects include:

•	An object table, where the entire table is based on a single object type.

•	A column object in a relational table, where that column is based on an object type.

•	A REF column in either an object or relational table, where that column's values are pointers to rows in another object table.

New scalar datatypes

This release supports the new Oracle8 FLOAT datatype.  It maps this datatype to its own NUMBER datatype.


About Oracle8 large objects (LOBs)

You can access the Oracle8 large object datatypes: binary large objects (BLOBs), character large objects (CLOBs), and binary files (BFILEs).

On an Oracle8 server, these datatypes can store objects of up to 4 gigabytes in size.  They are similar in purpose to the familiar Oracle7 LONG and LONG RAW datatypes, but offer a number of additional advantages.

Comparison of LOBs with LONGs

LOBs	LONGs
Up to 4 gigabytes	Up to 2 gigabytes
Multiple LOB columns allowed in a single table	Only one LONG column allowed per table
Replication supported	No replication
Random data access supported	Only sequential access supported
Better table space management (only LOB locator is stored)	Less efficient (data is stored directly in table)
Allowed in user-defined object types	Not allowed
Easily passed to procedures and external calls	Not easily passed
LOBs in detail:

BLOBs are used to store large objects in binary format.  CLOBs are used to store character data.  These two types are also known as internal LOBs, because their data is stored within the server.  The data participates in transactions and integrity control, including commits and rollbacks.

BFILEs, in contrast, are stored outside of the server. The server stores only the operating system address of the file.  As a consequence, BFILEs can not participate in database transactions.

Compatibility

Because of the various advantages offered by LOBs (see the table above), you should used LOBs instead of LONGs in any new application.

However, for backward compatibility, LONGs are still fully supported.

Forms Types

Within a form, the LOB would usually be given a control type of Text, Image, or Sound, depending on its nature and usage.

Restrictions

•	BFILEs are read-only.

•	Although Forms will attempt to load the entire BFILE or BLOB when it is read at runtime, it is limited by the amount of runtime virtual memory available.

•	For CLOBs, Forms has a size limitation of 65534 bytes.


About Oracle8 user-defined objects

  Related Topics  [image]  Examples

In its support for the Oracle8 Server, this release provides you with access to Oracle8 user-defined objects.  These include object tables, column objects in relational tables, and the special kind of column object known as a REF column.

Object tables

In Oracle8, an object table is based on a user's object type definition.  This definition is itself a composite, each attribute or component of which is based on a familiar Oracle8 built-in datatype.  (An object type definition can be based on another object type definition, but ultimately the definitions rest on known Oracle8 built-in datatypes.)

Because of this, each column in an object table is treated as an individual data item, in a manner similar to the way it treats the columns of a relational table.

Column objects in relational tables

A database programmer can also base a column in a relational table on an object type definition.  This has the effect of embedding a composite object in the relational table.

The embedded column object is expanded into its composite parts, and each part is treated as a column in itself.

For example, if the Oracle8 Server held a 3-column relational table, and one of those columns was a column object, and that column object was based on an object definition having four parts or attributes, then the table would be treated as a 6-column table (the 2 relational columns plus the 4 columns that comprise the object).

In the event one of the individual attributes of the column object's definition was based on yet another object type, then that part is further expanded and treated as a set of individual columns.

REF columns

A column in either an object or relational table can be defined as having a type of REF.  A REF column does not hold data directly, but rather has pointers (references) to another object table that holds the actual data.

The reference can be resolved at runtime, so that the user sees the actual referenced data.


Oracle8 user-defined objects: examples

  Related Topics

To create objects in the Oracle8 Server, a database programmer first defines an object type, and then creates a specific object based on that type definition.  The resulting object can be either an object table or a column object in a relational table.

Examples

Consider the following definitions.  The first creates an object type.  The second creates a table of that type.

         CREATE TYPE  emp_type  AS OBJECT

                      (name     CHAR(30),

                       title    CHAR(20),

                       idnum    NUMBER);

         CREATE TABLE  emp  OF emp_type;

In the above example, we create an object table named emp.  It has three columns, and those columns have the names and datatypes that are established in the attributes of the emp_type object type definition.

The following is an example of a column object in a relational table:

         CREATE TYPE  address_type  AS OBJECT

                      (street    VARCHAR2(40),

                       city      VARCHAR2(25),

                       state     VARCHAR2(2)

                       zip       NUMBER);

         CREATE TABLE  customers

                       (cust_id  NUMBER,

                        name     VARCHAR(40),

                        address  address_type);

In this example, we create a relational table named customers.  The table has three columns.  The first two columns (cust_id and name) are the usual relational columns.  The third column (named address) is a column object.  It is built on the object type definition named address_type.  This address column has the structure and datatypes established by that object definition.  The address column can be thought of as having four parts or components (street, city, state, and zip).  Each of these components is of the datatype that was established in the address_type object type definition.  (In this case, all are of VARCHAR2 except for zip, which is of datatype NUMBER).

In the following illustration, the third column of a three-column relational table is based on an object type that itself has three parts or components.

Note that an Oracle8 object is a composite, built from parts or components.  Each of its parts has a name and is of a known Oracle8 datatype.  If the object is a table (actually, a row in an object table), it has as many columns or parts as there are attributes in the object type definition.  If a column in a relational table is based on an object, then each of the object's parts can be thought of an additional column in that table.  Because each of these parts is based on an attribute in the object type definition, these parts are sometimes called attribute columns.

How Developer treats objects

An object table is treated very much like a relational table.  Each column is individually selectable.  Although all columns may be selected, each is treated as a separate item within the application.  The table itself does not have any particular identity as an object within the environment.

Similarly, a column object in a relational table is not treated as a single, homogeneous entity.  Instead, it treats each of the column object's components as an individual, independent data item.  Each component of the column object is selectable.  Once selected, each is treated as an independent data item.  Even if all of the column object's components are selected, the column object itself does not have any particular identity as an object within the development environment.

Data items selected from an object are given the default name ColumnObjectName_ItemName.  Thus, if we select the component named zip from the column object named address in the above example, the data item will have the name address_zip within the application.


About Oracle8 REFs

  Related Topics

REF is a new datatype in Oracle8.  It establishes a column object as a pointer to data in another object table.  The REF column itself does not hold the data.

For example:

           CREATE TYPE  dept_type  AS OBJECT

                        (deptname     VARCHAR2(24),

                         deptnumber   NUMBER);

           CREATE TABLE  dept_table OF dept_type;

           CREATE TABLE  emp

                         (empname    VARCHAR2(50),

                          empnumber  NUMBER,

                          empdept    REF  dept_type);

In the relational table named emp, the column empdept is a REF column.  It points to an object of type dept_type.

Types versus tables

When a REF column is defined, it identifies an object type -- not a particular object table.  It is possible for a database to contain more than one object table based on a single object type definition.  Thus, the REF column definition itself does not identify the target table(s).

Pointer resolution

When the table holding the REF column is initialized, the values placed in the REF column will be pointers to rows in the specific table or tables that have the desired data.  Later at runtime, when users look at the REF column, they will see the pointed-to data (not the pointers).

How Developer displays REFs at design time

At design time, when you ask to see a table that contains a REF column, the REF column displays in its expanded form.  That is, it shows the attributes in the object type pointed to by the original REF definition.

In the above example, the empdept REF column would show as holding two components or attribute columns:  deptname and deptnumber.  These were the two attributes in the object type (dept_type) identified in the REF definition.

Just as with a regular column object, you can select any or all of the referred-to components/attribute columns to become data items in the application.  However, in contrast to regular column objects, you can also select the REF name itself to become a manipulatable item within your application.  That is, you can use the REF in your PL/SQL coding.  By default, the REF becomes part of the null canvas.

How you can display REF data to your users

As an application designer, you have a choice in how the runtime user will see the referenced data (the resolved REF):

•	data displayed in the data block in which the REF exists (sometimes called the look-up method)

•	data displayed in the data block pointed to by the REF (the master-detail method)

The first choice (displaying the data as part of the data block in which the REF exists) is the simplest.  You select the desired REF components as items into your data block, and at runtime Developer and Oracle8 will resolve the references and place the actual referred-to data in the display items.  The user need see only the one block.

The other choice (displaying the data in the pointed-to data block) requires setting up a master-detail link.  This is very similar to setting up a master-detail link for two blocks having a primary-key foreign-key relationship.  In this case, the REF creates the link between the two blocks.  The user will see both blocks, but will  see the REF data only in the referred-to block.

The Form Builder Data Block Wizard can be used to set up this master-detail relationship.


Icons for Oracle8 objects

The object navigator and wizards use icons to help you see what type of Oracle8 data you are accessing.   These icons, and their meanings, are as follows:

             normal table

             object type

             object view

             object table

             nested object

             nested table

             referenced object

             varying array

             method

             unknown type

             server-side stack mode

             server-side program unit

             file

             datatype of Date

             datatype of Number

             datatype of Character

             datatype of Raw

             datatype of BLOB

             datatype of BFILE

             datatype of CLOB

             rowid

             MLS label


Scalability and performance with Oracle8

Oracle8 Server gives you a number of scalability and performance improvements.  For the most part, you obtain these advantages automatically.

For example, you can access Oracle8's:

•	Larger sizes.  The database itself, the number of concurrent users, and its table column limits (now up to 1000 columns) have all increased.

•	Table and index partitioning

•	Client-side object caching

You can also make direct use of several other Oracle8 functions that provide it with improved performance:

•	Prefetch.  Forms uses this Oracle8 feature (along with the existing Array Size mechanism) to reduce both database round-trips and memory usage.  This is done automatically, without any need for user involvement.

•	Returning values clause.  Forms uses this new DML feature when doing inserts and updates.  The Returning clause eliminates the need for a second database query (to obtain any server-side trigger changes to the data), thus speeding up processing.  Users can control it with the DML Returning Value property.

•	INSTEAD-OF trigger for updating views.  This server-side trigger provides a mechanism for updating both relational and object views that would not otherwise be updatable.


Support for PL/SQL 8

  Related topics

This release uses PL/SQL 8 on the client and the server.  Client-side program units currently cannot support Oracle8 object-related functionality.  However, stored program units can use all the new PL/SQL 8 features.

Appendix A in the PL/SQL User's Guide and Reference Release 8 manual describes the new PL/SQL 8 features.  This manual is available online.  Choose Help -> Manuals, and navigate to Reference Manuals under Online Manuals.


Compatibility with earlier releases of PL/SQL

If you have client-side program units written in PL/SQL 1 or PL/SQL 2, you must convert the code to the new level.  The PL/SQL 1 conversion utility is provided to help automate the upgrading process.

Stored program units created with previous releases will run against the PL/SQL 8 engine on the database server, but may compile with errors.  These errors arise in some situations where there is syntax incompatibility between PL/SQL 8 and PL/SQL 2.  A compatibility flag in PL/SQL 8 allows you to choose a PL/SQL 2 compatibility mode, so that the PL/SQL 8 engine does not issue such errors when it compiles PL/SQL 2 code in the server.  Chapter 6 in the Oracle8 Server Migration manual describes the situations that are covered by this compatibility flag.


Oracle8 features not yet supported

  Related Topics

Not all Oracle8 features are currently supported across this release.  The major unsupported features are:

•	Collection types (nested tables and varying arrays, or varrays)

•	Stored procedures that return object values

•	Scalar datatypes NCHAR and NVARCHAR2.

You should also be aware that, although this release does support PL/SQL 8, client-side PL/SQL 8 does not yet fully support all the features in the Oracle8 Server.  (Server-side PL/SQL 8 support is complete.)


Oracle8 Object Support in the Object Navigator

Oracle8 functionality in the Object Navigator provides access to object datatypes, enabling you to program against Oracle8 data more easily. The added Oracle8 object support allows you to view user-defined datatypes in a hierarchical format, and to find and display tables, views, columns, triggers, attributes and methods associated with the user-defined datatypes.

The Database Objects node contains the schemas and their objects that you can access in the currently connected database. When connected to an Oracle8 database, the Object Navigator displays available user-defined datatypes (with their attributes and methods) in the Types node within each schema. Tables, views, columns and triggers associated with the user-defined datatypes are displayed in the Tables and Views nodes.

Specifically, Oracle8 functionality in the Object Navigator enables you to display and find:

•	object tables and column objects in the Tables node

•	object views in the Views node

•	Instead Of triggers for views in the Views node

•	object types, table types and varying array types in the Types node

•	attributes and methods of object types in the Types node

Icons are used to differentiate relational objects and Oracle8 objects in the Object Navigator. For example, separate icons are used to represent normal, relational tables and object tables, and normal views and object views.

For information about Oracle8 user-defined datatypes, see your Oracle8 documentation.

Learn more about

Object Type nodes

Table Type nodes

Varying Array Type nodes

Column Object nodes

Object Table nodes

Object View nodes

Expanding All

Oracle8 objects icons


Object Type nodes

  Example	  Related Topics

Object types appear within the Types node in the Object Navigator. An object type node represents a type created by the SQL statement, CREATE TYPE AS OBJECT. The object type is displayed in the Object Navigator as:

object-type-name ( Object Type [ * ] & Body [ * ] )

The Object Type label appears when a CREATE TYPE AS OBJECT statement has been issued to the database. An asterisk ( * ) appears when the type specification is invalid or if the type is incomplete. An incomplete type is a placeholder for defining types recursively.

The Object Body label appears when a type body has been created using the CREATE TYPE BODY statement. An asterisk ( * ) appears when the type body is invalid.

When both object type and object body have been successfully created, then the label appears as Object Type & Body.

Object type nodes are composite nodes; they have two subnodes, Attributes and Methods. An object type node can be expanded only if a valid type specification exists.

The attributes of an object type are represented as nodes under the Attributes subnode.

The methods of an object type are represented as nodes under the Methods subnode. The methods appear as procedures and functions. The method labels are displayed in the Object Navigator as:

method-name (Procedure)

and

method-name (Function)

If a map method or order method is specified for an object type, then the method label is displayed as:

method-name (Map Function)

or

method-name (Order Function)

Note:  The argument list of a method is not displayed.


Object Type node example

  Related Topics 	   All Examples

The following SQL statement creates the object type emp_typ.

CREATE TYPE emp_typ AS OBJECT
  (ename VARCHAR2(30), esalary NUMBER(5,2),
  MEMBER PROCEDURE raise(amount NUMBER),
  MEMBER FUNCTION get_salary RETURN NUMBER,
  MAP MEMBER FUNCTION compare RETURN NUMBER);

The subtree for emp_typ is:


Table Type nodes

  Example	  Related Topics

Table types appear within the Types node in the Object Navigator. A table type node represents a type created by the SQL statement, CREATE TYPE AS TABLE. The table type is displayed in the Object Navigator as:

table-type-name (TABLE OF table-subtype-name)

The table type node is not expandable if the subtype is a built-in type. If the subtype is an object type or REF object, the attributes of the object appear as subnodes.


Table Type node example

  Related Topics 	   All Examples

The following SQL statements create the object type emp_typ and the table type emp_tbl.

CREATE TYPE emp_typ AS OBJECT
  (ename VARCHAR2(30), esalary NUMBER(5,2),
  MEMBER PROCEDURE raise(amount NUMBER),
  MEMBER FUNCTION get_salary RETURN NUMBER,
  MAP MEMBER FUNCTION compare RETURN NUMBER);

CREATE TYPE emp_tbl AS TABLE OF emp_typ;

The subtree for emp_tbl is:


Varying Array Type nodes

  Example	  Related Topics

Varying array types appear within the Types node in the Object Navigator. A varying array type node represents a type created by the SQL statement CREATE TYPE AS VARYING ARRAY. The varying array type is displayed in the Object Navigator as:

varying-array-type-name (VARRAY (size) varying-array-subtype-name)

The varying array type node is not expandable if the subtype is a built-in type. If the subtype is an object type or REF object, the attributes of the object appear as subnodes.


Varying Array Type node example

  Related Topics 	   All Examples

The following SQL statements create the object type emp_typ and the varying array type emp_ary.

CREATE TYPE emp_typ AS OBJECT
  (ename VARCHAR2(30), esalary NUMBER(5,2),
  MEMBER PROCEDURE raise(amount NUMBER),
  MEMBER FUNCTION get_salary RETURN NUMBER,
  MAP MEMBER FUNCTION compare RETURN NUMBER);

CREATE TYPE emp_ary AS VARRAY(7) OF emp_typ;

The subtree for emp_ary is:


Column Object nodes

  Examples	  Related Topics

Column objects appear as nodes within the Columns node. Each object is labeled with a name and its type in parentheses. Column object nodes are composite nodes, with the attributes of the type appearing as subnodes.

There can be four subtypes of column objects-nested object type, table type, varying array type and REF object type. Column objects are labeled in the Object Navigator as follows:

column-name (nested-object-type)

column-name (table-type-name:TABLE OF table-subtype-name)

column-name (varying-array-type-name: VARRAY(size) OF varying-array-subtype-name)

column-name (REF reference-type-name)


Column Object node examples

  Related Topics 	   All Examples

In the following example, the emp_col column of table emp_tab is a nested object of type emp_typ.

CREATE TYPE emp_typ AS OBJECT (ename VARCHAR2(30), esalary NUMBER(5,2));
CREATE TABLE emp_tab (emp_col emp_typ, dept VARCHAR2(2));

The subtree for emp_tab is:

In the next example, the emps column of table dept_tab is a nested table with subtype emp_tbl. The nested table contains rows of type emp_typ.

CREATE TYPE emp_typ AS OBJECT (ename VARCHAR2(30), esalary NUMBER(5,2));
CREATE TYPE emp_tbl AS TABLE OF emp_typ;
CREATE TABLE dept_tab (dname VARCHAR2(20), emps emp_tbl)
  NESTED TABLE emps STORE AS emps_tab;

The subtree for dept_tab is:

In the following example, the emps column of table dept_tab_ary is a varying array with subtype emp_ary. The varying array contains rows of type emp_typ.

CREATE TYPE emp_typ AS OBJECT (ename VARCHAR2(30), esalary NUMBER(5,2));
CREATE TYPE emp_ary AS VARRAY(7) OF emp_typ;
CREATE TABLE dept_tab_ary (dname VARCHAR2(20), emps emp_ary);

The subtree for dept_tab_ary is:

In the next example, the manager column of table dept_ref is a referenced object with type emp_typ.

CREATE TYPE emp_typ AS OBJECT (ename VARCHAR2(30), esalary NUMBER(5,2));
CREATE TABLE dept_ref (dname VARCHAR2(20), manager REF emp_typ);

The subtree for dept_ref is:


Object Table nodes

  Example	  Related Topics

Object tables appear within the Tables node in the Object Navigator. An object table node represents a table created by the SQL statement CREATE TABLE OF. Object table nodes are labeled in the Object Navigator as:

object-table-name (object-type-name)

Each object table node has two subnodes, Triggers and Columns. The Triggers subnode contains all triggers associated with the object table. These triggers are displayed in the same manner as triggers associated with normal, relational tables. The Columns node contains all relational columns and column objects associated with a given object table. Each column is labeled with a name and its type in parentheses.


Object Table node example

  Related Topics 	   All Examples

The following SQL statements create the object type person_typ and the object table person_tab.

CREATE TYPE person_typ AS OBJECT
  (name VARCHAR2(30), address VARCHAR2(60));

CREATE TABLE person_tab OF person_typ;

The subtree for person_tab is:


Object View nodes

  Example	  Related Topics

Object views appear within the Views node in the Object Navigator. An object view node represents a view created by using the OF object_type clause. Object view nodes are labeled with a name and its type in parentheses. The attributes of the object are not displayed.

Each object view node has two subnodes, Triggers and Columns. The Triggers subnode contains all triggers associated with the object view, including Instead Of triggers. When an Instead Of trigger is associated with a view, the label is displayed as:

trigger-name (INSTEAD OF trigger-statements)


Object View node example

  Related Topics 	   All Examples

The following SQL statements create an object view.

CREATE TYPE emps_typ AS OBJECT (ename VARCHAR2(30), esalary number(5,2), deptno NUMBER(2));
CREATE TABLE emps (ename VARCHAR2(30), esalary number(5,2), deptno NUMBER(2));
CREATE VIEW dev_emps OF emps_typ
  WITH OBJECT OID (ename)
  AS SELECT ename, esalary, deptno FROM emps WHERE deptno = 10;

The subtree for the object view dev_emps is:


Expanding all Oracle8 object nodes

  Related Topics

The Expand All operation in the Object Navigator does not expand Oracle8 datatype and attribute nodes recursively.

For example, if an attribute called manager with type emp_typ appears as a descendent from another type emp_typ, then the manager attribute would not be expanded by Expand All.


Environment variables

  Related Topics

CA_GPREFS

CA_UPREFS

CUE_PREFS

DEV2000_PROJECT

DEV2000_SOURCECONTROL

DOC60

FORMS60_DEFAULTFONT

FORMS60_EDITOR

FORMSnn_ERROR_DATE/DATETIME_FORMAT

FORMS60_JAVADIR

FORMS60_MAPPING

FORMS60_OUTPUT

FORMSnn_OUTPUT_DATE/DATETIME_FORMAT

FORMS60_PATH

FORMSnn_PLSQLV1_NAME_RESOLUTION

FORMS60_REPFORMAT

FORMS60_TIMEOUT

FORMSnn_USER_DATE/DATETIME_FORMAT

FORMS60_USEREXITS

GRAPHICS60_PATH

INTERRUPT (DOS SQL*Net users only)

LOCAL

NLS_LANG

OleCreateObjPoolInMemory

OleDoNotUpdateLinks

OleUpdateLinksPrompt

ORACLE_HOME

ORACLE_PATH

ORAINFONAV_DOCPATH

REPORTS60_CGIDIAGBODYTAGS

REPORTS60_CGIDIAGHEADTAGS

REPORTS60_CGIHELP

REPORTS60_CGIMAP

REPORTS60_CGINODIAG

REPORTS60_CGIPATHONLYURL

REPORTS60_COOKIE_EXPIRE

REPORTS60_DB_AUTH

REPORTS60_ENCRYPTION_KEY

REPORTS60_OWSDIAGBODYTAGS

REPORTS60_OWSDIAGHEADTAGS

REPORTS60_OWSHELP

REPORTS60_OWSMAP

REPORTS60_OWSNODIAG

REPORTS60_OWSPATHONLYURL

REPORTS60_PATH

REPORTS60_REPORTS_SERVER

REPORTS60_SYS_AUTH

REPORTS60_TERMINAL

REPORTS60_TMP

REPORTS60_USEREXIT

REMOTE

UI_ICON

USERNAME

WIN_REMOTE_SESSIONS

XMITTR(DOS users only)


The Registry (Windows 95 and Windows NT)

  Environment Variables

The Oracle Installer creates a new ORACLE section in your registry.  The Oracle registry contains configuration parameters that control such things as the name of the Oracle home directory, the location of the product preference file, and the location of the help files.

Viewing and modifying the Registry

You can view and optionally edit the Microsoft Windows Registry by using the Registry Editor.  This editor is located in the directory where your Windows software is installed.  To start the editor, choose Start [image] Run, then type REGEDIT and click OK.

In the Registry Editor, expand the HKEY_LOCAL_MACHINE node, then expand the SOFTWARE node.  Click the ORACLE key to display the Oracle configuration parameters.

You can modify any parameter value by double-clicking the parameter name to display the Edit String dialog.  Change the value in the Value data text box, then click OK to accept the new value.


Configuration parameters

  Environment Variables

The Oracle Installer automatically sets many parameters.  Some of these parameters are required by Oracle products, and other parameters allow you to customize the products' behavior.

Required parameters

The parameters listed in this section are automatically set or removed by the Oracle Installer.  They are required by various Oracle products to function properly.

Caution: Do not change the settings of parameters listed in this section.  Doing so may cause one or more Oracle products to stop functioning correctly.

The appearance of nn in the parameters listed below specifies a product or component release number.  This number may change when you upgrade to a new release of an Oracle product.

Parameter	Default Value
BROWSERnn	ORACLE_HOME\BROWSE25
DEnn	ORACLE_HOME\TOOLS\COMMON60
FORMSnn	ORACLE_HOME\FORMS60
GRAPHICSnn	ORACLE_HOME\GRAPH60
MMnn	ORACLE_HOME\TOOLS\COMMON60
OCLnn	ORACLE_HOME\GRAPH60
PROnn	ORACLE_HOME\PRO18
RDBMSnn	ORACLE_HOME\RDBMS73
RWnn	ORACLE_HOME\REPORT60
TKnn	ORACLE_HOME\TOOLS\COMMON60
VGSnn	ORACLE_HOME\TOOLS\COMMON60
Customizeable parameters

The parameters listed in this section control various aspects of your Oracle products.  You may change the settings of these parameters to customize the product's behavior.

The sections below list the default setting (if any) of each parameter that is automatically set by the Oracle Installer.  Those parameters that aren't automatically set are also noted.  Descriptions of the valid values and examples of settings are also provided.


CA_GPREFS

Default:  ORACLE_HOME

Valid Values:  any directory on any drive

Example:

CA_GPREFS=C:\orawin95

This parameter specifies the location of the global preferences file, CAGPREFS.ORA.  Global preferences are shared among networked users.  In addition to searching the directory specified by the CA_GPREFS parameter, products will also search the current directory for the CAGPREFS.ORA file.

The CAGPREFS.ORA file is automatically created by the Oracle Installer.  To modify the global preference settings, use a text editor such as Notepad to manually edit this file.  Global preferences set in CAGPREFS.ORA can be overridden by the local preference file, CAUPREFS.ORA, which is defined by the parameter CA_UPREFS.


CA_UPREFS

Default:  ORACLE_HOME

Valid Values:  any directory on any drive

Example:

CA_UPREFS=C:\orawin95

This parameter specifies the location of the user preferences file, CAUPREFS.ORA.  The CAUPREFS.ORA file maintains the preferences that you set via Tools [image] Tools Options within your products.  In addition to searching the directory specified by the CA_UPREFS parameter, the product will also search the current directory for the CAUPREFS.ORA file.

Several Oracle products write their preference information to the CAUPREFS.ORA file.  To manually modify the user preference settings, use a text editor such as Notepad to edit this file.  User preferences set in CAUPREFS.ORA override global preferences set in the CAGPREFS.ORA file, which is defined by the parameter CA_GPREFS.


CUE_PREFS

Default:  ORACLE_HOME

Valid Values:  any directory on any drive

Example:

CUE_PREFS=C:\orawin95

This parameter specifies the location of the Cue Cards preferences file, CUEPREF.RES.  The CUEPREF.RES file maintains the Cue Card preferences that you can set from the Cue Cards Options dialog.

Your preferences are saved to the CUEPREF.RES file each time you exit from an application.  You cannot modify this file manually.


DEV2000_SOURCECONTROL

Default:  none

Valid Values:  keywords that specify which source control system should be used with Forms Developer or Reports Developer

Example:

DEV2000_SOURCECONTROL=PVCS

This parameter specifies which source control system you plan to use with with Forms Developer or Reports Developer.  Currently, you can either specify no source control system, or you can set this parameter to the value 'PVCS.'  As support for additional source control systems is added, you will be able to specify keywords for additional source control systems, as well.


DEV2000_PROJECT

Default:  none

Valid Values:  keywords that specify the project file of the source control system to be used with with Forms Developer or Reports Developer

Example:

DEV2000_PROJECT=c:\pvcs\project1\project1.cfg

This parameter specifies the name of the project file for the source control system you selected on the DEV2000_SOURCECONTROL parameter.


DOC60

Default:  Oracle_Home\tools\doc60

Valid Values:  any directory on any drive

Example:

DOC60=c:\orawin95\tools\doc60

This parameter specifies the location of the online documentation files, including online help, Cue Cards, and Quick Tours.


FORMS60_DEFAULTFONT

Default:  none

Valid Values:  A text string specifying any valid font.

Example:

FORMS60_DEFAULTFONT="MS Sans Serif.8"

This parameter specifies the default font used for boilerplate in the Form Builder Layout editor.


FORMS60_EDITOR

Default:  none

Valid Values:  the name and path of a system editor

Example:

FORMS60_EDITOR=C:\windows\notepad.exe

This parameter defines the editor that can be invoked by Form Builder multi-line items in the Designer or Runform components.  No user-defined editor will be launched unless this parameter is defined.

Note:  When exiting the editor, the file must be saved back as an "ASCII Only" file.  No native word processor formats are supported.


FORMSnn_ERROR_DATE/DATETIME_FORMAT

Purpose:  These two environment variables establish the format masks that Forms will use in producing runtime error messages that are issued when an end user enters an invalid value into a date or datetime item.

Default:  See the help topic About Format Masks for Dates.

Valid Values:  any valid date/datetime format mask.

Example:

FORMS65_ERROR_DATE_FORMAT YYYY/MM/DD


FORMS60_JAVADIR

Default:  Oracle_Home\forms60\java

Valid Values:  the name and path of the Oracle Java runtime environment

Example:

FORMS60_JAVADIR=C:\orant\forms60\java

This parameter defines the location of the Oracle Java runtime environment files required to use Java Bean areas and to preview web-based forms from Form Builder.


FORMS60_MAPPING

Default:  none

Valid Values: the virtual location of your temporary work directory

Example:

FORMS60_MAPPING=http://myhost.com/webtemp

To process images on the Web, the Forms Server transmits temporary compressed JPEG files. If you use images or icons in your Web Forms applications, you must create a temporary directory and a virtual directory (for example, C:\ORANT\WEBTEMP) that the Forms Server will use for images and other work files. You must also create the FORMS60_OUTPUT and FORMS60_MAPPING environment variables on the machine on which your Forms Server is running.


FORMS60_OUTPUT

Default:  none

Valid Values:  any directory on any drive on the machine on which the Forms Server is running

Example:

FORMS60_OUTPUT=C:\ORANT\WEBTEMP\

To process images on the Web, the Forms Server transmits temporary compressed JPEG files. If you use images or icons in your Web Forms applications, you must create a temporary directory (for example, C:\ORANT\WEBTEMP) that the Forms Server will use for images and other work files. You must also create the FORMS60_OUTPUT and FORMS60_MAPPING environment variables on the machine on which your Forms Server is running.


FORMSnn_OUTPUT_DATE/DATETIME_FORMAT

Purpose:  These two environment variables establish the format masks that Forms will use for runtime ouput operations on any date and datetime items that do not have their own individual, specific masks.

Default:  See the help topic About Format Masks for Dates.

Valid Values:  any valid date/datetime format mask.

Example:

FORMS65_OUTPUT_DATETIME_FORMAT YYYY/MM/DD HH24:MI:SS


FORMS60_PATH

Default:  ORACLE_HOME\FORMS60\PLSQLLIB

Valid Values:  any directory on any drive

Example:

FORMS60_PATH=C:\oracle\apps\forms;C:\myfiles

This parameter specifies the search path for files used in a Form Builder runtime application.  These include form files (.fmx), menu files (.mmx), PL/SQL libraries (.pll), and other objects that the application attempts to load from a file at runtime.  For example, if you import the image file scooter.tif, Form Builder searches in the directories specified by FORMS60_PATH to find that file.

FORMS60_PATH can specify multiple directories.  Use a semi-colon (;) to separate directory names in a list of paths.


FORMSnn_PLSQLV1_NAME_RESOLUTION

Default:  OFF

Valid Values:  ON, OFF

Example:

FORMS6i_PLSQLV1_NAME_RESOLUTION=ON

This environment variable allows you to choose between R4.5 behavior and R5-and-later behavior for runtime program unit name resolution.  A value of ON selects R4.5 behavior.  A value of OFF (or not including this environment variable at all) selects R5-and-later behavior.

R4.5 Behavior:

When Forms encounters a call to a program unit, it first looks for the program unit in the current form or menu, then searches the attached libraries.  This behavior provides a simple style of dynamic name resolution, as the program unit that is called is not the same as the one which was resolved at compile time.  In addition, in situations where the same library is attached to multiple forms, each form maintains its own unique set of library information, including instantiations, package state, and dependencies.  This means that dependency information is not shared across forms.

R4.5 behavior has the following disadvantages:

•	No sharing of information across forms.  SHARE_LIBRARY_STATE will have no effect.

•	Increases in execution time and memory usage (as compared to R5+).

R5+ Behavior:

When Forms encounters a call to a program unit, it also first looks for the program unit in the current form or menu, then searches the attached libraries.  However, in those situations where the same library is attached to multiple forms, each form does not maintain its own unique set of library information.  Instead, the program unit instantiations are shared across forms.  This means that dependency information can be shared across forms.

Recommendation:

Because of the disadvantages noted above, and because this environment variable will not always be supported in future releases, it is recommended that you not choose the R4.5 behavior.

Instead, to obtain dynamic name resolution, use the Execute-Trigger built-in.  If arguments are needed, use global variables.


FORMS60_REPFORMAT

Default:  none

Valid Values:  HTML, PDF

Example:

FORMS60_REPFORMAT=HTML

If you are invoking a browser to run a report from a form via RUN_PRODUCT, you must set the FORMS60_REPFORMAT environment variable.  This parameter specifies the report format.


FORMS60_TIMEOUT

Default:  15

Valid Values:  1-1440 (1 day)

Example:

FORMS60_OUTPUT=1440

This parameter specifies the amount of time in elapsed minutes before the Forms server process is terminated if there is no client communication with the Forms server.


FORMSnn_USER_DATE/DATETIME_FORMAT

Purpose:  These two environment variables establish the format masks that Forms will use at runtime to extract values from items of type DATE and DATETIME, when those items do not have their own individual, specific masks.

Default:  See the help topic About Format Masks for Dates.

Valid Values:  any valid date/datetime format mask.  Multiple format masks may be specified, separated by vertical bars.  During runtime item conversion, the format masks are used in the order specified, until a conversion succeeds (or the masks are exhausted).

Example:

FORMS65_USER_DATE_FORMAT  FXFMDD-MM-RRRR


FORMS60_USEREXITS

Default:  none

Valid Values:  Any user exit dynamic link library (along w/ absolute path).

This parameter allows you to define multiple DLLs to contain foreign functions that can be invoked from a user exit interface.  The FORMS60_USEREXITS parameter includes a semicolon-delimited list of user interface DLLs.

FORMS60_USEREXITS can specify multiple DLLs.  Use a backslash (\) to separate directories in a path, and a semicolon (;) to separate complete paths.

If this value is not explicitly set, Form Builder assumes it to be ORACLE_HOME\BIN\F45XTB.DLL.

Example:

FORMS60_USEREXITS = C:\mathlib\add.dll;C:\mathlib\mult.dll


GRAPHICS60_PATH

Default:  none

Valid Values:  any directory on any drive

Example:

GRAPHICS60_PATH=C:\oracle\apps\graphics;C:\myfiles

This parameter specifies the search path for files used in a Graphics runtime application.  These include display files (.ogr), images, external queries, and other objects that the application attempts to load from a file at runtime.  For example, if you import the image file scooter.tif, Graphics Builder searches in the directories specified by GRAPHICS60_PATH to find that file.

GRAPHICS60_PATH can specify multiple directories.  Use a backslash (\) to separate directories in a path, and a semicolon (;) to separate complete paths.


INTERRUPT (DOS SQL*Net users only)

Default:  none

Valid Values:  same value specified in your DOS CONFIG.ORA file

This parameter specifies the interrupt vector address that DOS Oracle products will use.  If you use a DOS SQL*Net driver for Windows, check your CONFIG.ORA file located in the DOS Oracle home directory.  If the INTERRUPT parameter is set in CONFIG.ORA, you must set it to the same value in registry.  If this variable is not set in your DOS CONFIG.ORA files, you do not need to set it in the registry.

Note:  Do not set INTERRUPT to 103 when using a third-party memory management product such as QEMM, 386MAX, CEMM, or EMM386.  Doing so will result in unexpected behavior after you start SQLPME and SQL*Net.


LOCAL

Default:  none

Valid Values:  any valid SQL*Net driver prefix, including database string parameters.  For more information, see the Oracle Network Administrator's Guide.

This parameter specifies the SQL*Net driver and complete connect string that the product will use if you do not specify a communications driver when you connect to the database within the product.

If you add the LOCAL parameter, do not add the parameter to the end of the file.  Oracle products will not recognize the LOCAL parameter if it appears as the last parameter.

Note:  If you use a DOS SQL*Net driver for Windows, check to see whether the LOCAL parameter is set in your CONFIG.ORA file located in the DOS Oracle home directory.  If LOCAL is set in CONFIG.ORA, you must set it to the same value in the registry.


NLS_LANG

Default:  AMERICAN_AMERICA.WE8ISO8859P1

Valid Values:  See the NLS Reference Manual for a current list of available values, or see the following file on your CD: \bonus\nls\nlsd2r1.wri

Example:

NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1

This parameter sets the language in which message files appear.  The syntax for NLS_LANG is as follows:

NLS_LANG=<language>_<territory>.<char_set>

where:

language	specifies the language and its conventions for displaying messages and day and month names.
territory	specifies the territory and its conventions for calculating week and day numbers.
char_set	specifies the character set used for the UPPER, LOWER, and INITCAP functions, and the type of sort used by an ORDER BY query.  This argument also controls the character set used for displaying messages.


OleCreateObjPoolInMemory

Default:  0

Valid Values:  0 or 1

Example:

OleCreateObjPoolInMemory=0

For Report Builder, this parameter specifies whether to create the OLE2 object pool in temporary files (0) or in memory (1).  Creating the pool in memory improves performance by reducing disk access.  If you have a large number of OLE2 objects or large OLE2 objects (e.g., images), the amount of memory needed may be high.  In determining how many OLE2 objects you have, note that an OLE2 boilerplate object in a repeating frame contains one OLE2 object.  An OLE2 field contains one OLE2 object for each instance of the field.


OleDoNotUpdateLinks

Default:  0

Valid Values:  0 or 1

Example:

OleDoNotUpdateLinks=0

For Report Builder, this parameter enables (0) or disables (1) the updating of links when you open the Layout editor or run the report.  Linked OLE2 objects contain cached presentations of their source objects.  These cached presentations are updated by the corresponding OLE2 server based upon the persistent object data.

These updates occur automatically or manually, depending upon the link type.  Since updating the cached presentations requires launching the OLE2 server, you may want to disable the updating to improve performance, if you know the source objects have not changed or if you don't need the latest changes.  Note that even if you do not specify this option, you can still cancel updates from the standard dialog box that appears as the OLE2 objects are being updated.


OleUpdateLinksPrompt

Default:  0

Valid Values:  0 or 1

Example:

OleUpdateLinksPrompt=0

For Report Builder, this parameter specifies to prompt (0) or not prompt (1) when the source of a linked object is not found.  If the source of an object is not found during an update attempt, a dialog box is displayed from which you can re-specify the link source or ignore the error.  If you will not be there to accept the dialog box (e.g., you are running the report overnight), you may want to disable this prompt to ensure that the report execution completes.


ORACLE_HOME

Default:  C:\ORAWIN95

Valid Values:  any directory on any drive

Example:

ORACLE_HOME=C:\orawin95

This parameter specifies the home directory in which Windows Oracle products are installed.  This directory is the "top" directory in the Oracle directory hierarchy.

Usage Notes

•	If you are using Reports Runtime, the combined length of ORACLE_HOME and ORACLE_PATH should not exceed 255 characters


ORACLE_PATH

Default:  none

Valid Values:  any directory on any drive

Example:

ORACLE_PATH=C:\oracle\apps\forms;C:\oracle\apps\graphics;
C:\oracle\apps\reports

This parameter specifies the search path for files referenced by a Forms, Graphics, or Reports Runtime.  Note that the directories specified by ORACLE_PATH are searched after those specified by a product-specific parameter:  FORMS60_PATH, GRAPHICS60_PATH, or REPORTS60_PATH.

ORACLE_PATH can specify multiple directories.  Use a semi-colon (;) to separate directory names in a list of paths.

Usage Notes

•	If you are using Reports Runtime, the combined length of ORACLE_HOME and ORACLE_PATH should not exceed 255 characters


ORAINFONAV_DOCPATH

Default:  none

Valid Values:  any directory on any drive

Example:

ORAINFONAV_DOCPATH=C:\orawin95\oin

This parameter specifies the location of the table of contents and index for your online documentation.


REMOTE

Default:  none

Valid Values:  any valid SQL*Net driver prefix and parameters

Example:

REMOTE=P:PIPER

This parameter specifies the default and remote SQL*Net driver to use when connecting via a local database.  The parameter can include the default SQL*Net parameters (complete database string).

where P: is the network prefix for Named Pipes, and Piper is the database name.

If a user logs on and specifies a connection with an explicit driver prefix matching the one specified in REMOTE, but specifies no SQL*Net parameters, the parameters specified in REMOTE are used.  This parameter enables the DBA to define a "normal" network connection for which the SQL*Net user need not specify connection parameters.  You can reset this parameter on the command line at any time.

Note:  If you use a DOS SQL*Net driver for Windows, check to see whether the REMOTE parameter is set in your CONFIG.ORA file located in the DOS Oracle home directory.  If REMOTE is set in CONFIG.ORA, you must set it to the same value in the registry.


REPORTS60_CGIDIAGBODYTAGS

For the Reports Web CGI, specifies the HTML tags that will be inserted as <BODY…> tags in the RWCGI60 diagnostic/debugging output.  For  example, you can use this environment variable to set up text/background color and image.


REPORTS60_CGIDIAGHEADTAGS

For the Reports Web CGI, specifies HTML tags which will be inserted between <HEAD> … </HEAD> tags in the RWCGI60 diagnostic/debugging  output. For example, you may want to use this environment variable to set up <TITLE> or <META…> tags.


REPORTS60_CGIHLP

For the Reports Web CGI, defines URL/URI of the RWCGI60 help file, which will be navigated to when RWCGI60 is invoked with the empty request:

http://your_webserver/your_virtual_cgi_dir/rwcgi60.exe?

For example, setting REPORTS60_CGIHLP to http://www.yahoo.com will go to that URL; setting it to myhelpfile.htm will display the file:

http://your_webserver/myhelpfile.htm

If this variable is not defined, a default help screen will be displayed.


REPORTS60_CGIMAP

For the Reports Web CGI, defines fully qualified filename/location of the RWCGI60 map file if map file configuration is used:

c:\orant\report60\mymap.dat


REPORTS60_CGINODIAG

For the Reports Web CGI, when defined, disables all debugging/diagnostic output from RWCGI60.

http://your_webserver/cgi-bin/rwcgi60.exe/help?

Usage Note:

The parameter will not work when REPORTS60_CGINODIAG is defined.


REPORTS60_CGIPATHONLYURL

For the Reports Web CGI, when defined (the value does not matter), forces RWCGI60 to return any URLs to the browser as partial, path-only URLs; i.e., instead of returning:

Location: http://your_webserver:port/path

it will return only:

Location: /path

This variable can be used to resolve problems with Web server setups that use multiple ports, including a default port.


REPORTS60_COOKIE_EXPIRE

Default:  30

Valid Values:  any number of minutes

Example:

REPORTS60_COOKIE_EXPIRE=30

For Reports Server security, determines the idle time of the cookie (e.g., REPORTS60_COOKIE_EXPIRE=30).  Cookies save encrypted user names and passwords on the client-side.  When CGI receives a cookie from the client, CGI compares the time saved in the cookie with the current system time.

If the time is longer than the number minutes defined in the REPORTS60_COOKIE_EXPIRE parameter (e.g., 30 minutes), CGI rejects the cookie and returns the database authentication form and an error message to the client.  The user must re-authenticate to run the report.


REPORTS60_DB_AUTH

Default:  dbauth.htm

Valid Values: any html file that contains special authentication actions. It is recommended that you keep the default.

Example:

REPORTS60_DB_AUTH=dbauth.htm

Specifies the database authentication template used to log on to the database.


REPORTS60_SYS_AUTH

Default:  sysauth.htm

Valid Values: any html file that contains special authentication actions. It is recommended that you keep the default.

Example:

REPORTS60_SYS_AUTH=sysauth.htm

Specifies the authentication template used to authenticate the username and password when users run report requests to a restricted Reports Server.


REPORTS60_ENCRYPTION_KEY

Default:  Reports6.0

Valid Values:  any encryption key

Example:

REPORTS60_ENCRYPTION_KEY=reports6.0

Specifies the encryption key used to encrypt the user name and password.


REPORTS60_REPORTS_SERVER

Valid Values:  any Reports Server service entry name

Example:

REPORTS60_REPORTS_SERVER=repserver

Specifies the default Reports Server for Web Cartridge or Web CGI requests. When this parameter is set, you can omit the SERVER command line argument in report requests to process them using the default server, or you can include the SERVER command line argument to override the default.


REPORTS60_OWSDIAGBODYTAGS

For the Reports Web Cartridge, specifies HTML tags which will be inserted as a <BODY…> tag in  the RWOWS60 diagnostic/debugging output. For instance, you may want to use this environment to set up text/background color, image, etc.


REPORTS60_OWSDIAGHEADTAGS

For the Reports Web Cartridge, specifies HTML tags which will be inserted between <HEAD> …</HEAD> tags in the RWOWS60 diagnostic/debugging output. For instance, you may want to use this environment to set up <TITLE> or <META…> tags, etc.


REPORTS60_OWSHELP

Valid Values:  any path and file name or URL

For the Reports Web Cartridge, defines URL/URI of the RWOWS60 help file, which will be navigated  to when RWOWS60 is invoked with the empty request:

http://your_webserver/rwows60?

e.g., setting it to http://www.yahoo.com will go to that URL; setting it to myhelpfile.htm will display the file:

http://your_webserver/myhelpfile.htm

If this parameter is not defined, a default help screen will be displayed.


REPORTS60_OWSMAP

For the Reports Web Cartridge, defines fully qualified filename/location of the RWOWS60 map file (if map file configuration is used):

C:\ORANT\REPORTS60\MYMAP.DAT


REPORTS60_OWSNODIAG

For the Reports Web Cartridge, when defined, disables all debugging/diagnostic output from RWOWS60:

http://your_webserver/rwows60/help?

will not work when REPORTS60_OWSNODIAG is defined.


REPORTS60_OWSPATHONLYURL

For the Reports Web Cartridge, when defined (the value does not matter), it causes RWOWS60 to use path-only URLs (e.g., "/rscache/..." instead of "http://mywebsrv.com:1550/rscache/..." ) in HTTP redirection to report output and in the RWOWS60-generated diagnostic output. This is useful to force the client browser to retain the original URL request in its "Location:" field after retrieving the report output. Normally, RWOWS60 will switch the URL to the location of the report output (i.e., the directory specified by REPORTS60_WEBLOC), and will show the name of the report output file which, just having been generated, has a rather uninformative name such as 12345679.htm. By setting this parameter, this "URL switching" can be avoided. This will work only if all URLs are using the default port (typically 80).

The drawback to setting this parameter, however, is that any subsidiary files (such as image files) dependent on the main report output file will not be retrieved by the browser (although they are created successfully in the pointed to by REPORTS60_WEBLOC). This can be worked around either by specifying a <BASE HREF="..."> or <META HREF="..."> tag (with the main file location as a full or partial URL) in the report definition so that it is included in the main report output file, or by setting REPORTS60_WEBLOC to point to the location of the RWOWS60 executable.

Setting REPORTS60_OWSPATHONLYURL can also be used to workaround certain Intranet/Internet configurations where the same machine may have several different IP addresses simultaneously (with several network cards), because it removes the dependence of the HTTP redirection on the machine name or IP address.


REPORTS60_PATH

Default:  ORACLE_HOME\REPORT60\DEMO;ORACLE_HOME\REPORT60\DEMO\BITMAP;ORACLE_HOME\REPORT60\DEMO\REQFILES

Valid Values:  any directory on any drive

Example:

REPORTS60_PATH=C:\oracle\apps\reports;C:\myfiles

This environment variable is used to locate reports and external objects that you use in your reports, such as PL/SQL libraries, external queries, and external boilerplate.  It enables you to create reports that are easily portable across operating systems by preventing the need to hard-code directory paths.

Note: REPORTSPATH is limited to 256 characters.

Define REPORTS60_PATH in the same fashion you define other environment variables on your operating system, keeping in mind such platform-specific rules as path length, etc.

In addition to directory paths, you can specify the keyword DB when you define REPORTS60_PATH.  This instructs Report Builder to search the database to which you are currently connected.

Suppose you specified the following on a Unix platform:

setenv REPORTS60_PATH
/home/tkostin/pay:/home/tkostin/receive:DB

Report Builder will first search the directory /home/tkostin/pay.  If it cannot find the file in question, it will search /home/tkostin/receive.  If it still cannot find the file, it will search the database to which you connected when you began your Report Builder session.


REPORTS60_TERMINAL

Default:  none

Valid Values:  any directory on any drive

Example:

REPORTS60_TERMINAL=C:\mytermdefs

This environment variable is used to locate terminal definitions that you use in your character-mode reports.  The path you specify for this variable takes precedence over the ORACLE_TERMINAL environment variable.

Define REPORTS60_TERMINAL in the same fashion you define other environment variables on your operating system, keeping in mind such platform-specific rules as path length, etc.


REPORTS60_TMP

Default:  none

Valid Values:  any directory on any drive

Example:

REPORTS60_TMP=C:\tmp

This environment variable establishes the directory in which you wish to store Report Builder temporary files.  Report Builder will use only one directory for this purpose; do not define more than one.

Define REPORTS60_TMP in the same fashion you define other environment variables on your base operating system, keeping in mind such platform-specific rules as path length, etc.  If you don't define REPORTS60_TMP, it will default to the current working directory.


REPORTS60_USEREXIT

Default:  none

Valid Values:  any user exit dynamic link library (along with its absolute path)

Example:

REPORTS60_USEREXIT=C:\mydll.dll;d:\mynew.dll;e:\bin\speed.dll

This parameter allows you to define multiple DLLs for use by Report Builder and its related executables (e.g., Reports Runtime).  These DLLs are program modules created by you to be called by the Report Builder executables.

REPORTS60_USEREXITS can specify multiple DLLs.  Use a backslash (\) to separate directories in a path, and a semicolon (;) to separate complete paths.

If this value is not explicitly set, Report Builder looks for 60xtb32.dll according to the path variable of the system.


UI_ICON

Default:  none

Valid Values:  any accessible directory on any drive

Example:

UI_ICON=C:\icon

This environment variable establishes the directory in which you wish to store icons used for buttons in your layout.  Report Builder will use only one directory for this purpose; do not define more than one.

Define UI_ICON in the same fashion you define other environment variables on your base operating system, keeping in mind such platform-specific rules as path length, etc..


USERNAME

Default:  none

Valid Values:  any valid Oracle username (without the OPS$ prefix)

Example:

USERNAME=dsanvita

This parameter specifies the variable part of a default logon account.  See your database documentation for more information on setting the USERNAME parameter.


WIN_REMOTE_SESSIONS

Default:  none

Valid Values:  0-33

If you receive an error in the ORA-3100 to ORA-3199 range when you try to log on, there may not be enough real-mode memory to establish a communication buffer with an Oracle server.  NETINIT7.EXE solves this problem by reserving memory for server connections.

This parameter sets the number of connections to a remote server for which NETINIT7 should reserve memory.  Note the following rules when setting the WIN_REMOTE_SESSIONS parameter:

•	If you set WIN_REMOTE_SESSIONS to 0, NETINIT7 will not reserve any memory for remote server connections.

•	Setting WIN_REMOTE_SESSIONS to the values 1 through 33 will reserve memory for the specified number of connections.  Note that NETINIT7 reserves 12K of real-mode memory for each remote server connection.

•	A suggested default value for WIN_REMOTE_SESSIONS is 5.  Setting WIN_REMOTE_SESSIONS to 5 should create enough sessions to allow you to run several products.

•	If you do not add the WIN_REMOTE_SESSIONS parameter, NETINIT7 will reserve memory for one remote server connection.

To use NETINIT7, complete the following steps:

1	Configure the number of sessions by adding the WIN_REMOTE_SESSIONS parameter.

2	Create the NETINIT7 icon in your Oracle program group.  (For more information about creating icons, see your Microsoft Windows documentation.)  Enter the following path in the Command Line field of the Windows Program Item Properties dialog box:

ORACLE_HOME\bin\netinit7.exe

3	Start NETINIT7 by double-clicking the icon in the Oracle program group.  Make sure that you start NETINIT7 before you start a product.  If you want NETINIT7 to run automatically at Windows startup, include the NETINIT7 icon in the Windows Startup program group.

NETINIT7 attempts to reserve real memory for the configured number of server connections.  If NETINIT7 cannot allocate the required memory, it displays a warning message and indicates the actual number of sessions for which it has allocated memory.

After allocating memory, NETINIT7 minimizes itself.  Restoring NETINIT7 displays the total number of sessions configured and the total amount of memory used.  Closing NETINIT7 releases all unused session memory.  If an application is still using session memory, NETINIT7 notifies you that applications must log off before session memory can be freed.

Note:  If you start a product before NETINIT7, it will allocate its own session memory, which is not recognized by NETINIT7.  NETINIT7 attempts to allocate the configured session memory in addition to memory already allocated by the product you started.


XMITTR(DOS users only)

Default:  none

Valid Values:  same value specified in your DOS CONFIG.ORA file

This parameter applies only to users of Oracle DOS protected mode executables.  Check your CONFIG.ORA file, located in the DOS Oracle home directory.  If the XMMITR parameter is set in CONFIG.ORA, you must set it to the same value in the registry.  If this variable is not set in your DOS CONFIG.ORA files, you do not need to set it in the registry.

XMMITR (Extended Memory Manager Interrupt Vector) is a variable that indicates the interrupt vector to be used for the extended memory manager/mode transition driver XMM/MTD interrupt services entry point.  To set a different vector, the new interrupt vector is expressed as a decimal number.  XMMITR should be used only if another program in your system needs to use interrupt 100 decimal, or 64 hexadecimal.

Note:  Do not set XMMITR to 103 when using a third-party memory management product such as QEMM, 386MAX, CEMM, or EMM386.  Doing so will result in unexpected behavior after you load SQLPME and SQL*Net.


PL/SQL V1 conversion examples

  Related Topics 	   All Examples

Removing default expressions

Adding NULL to RETURN

Replacing obsolete built-in

Length function

Passing NULL to overloaded subprogram

Missing RETURN

Renaming procedure names uniquely in a package

Removing the package prefix

Reserved word

Removing length constraints

Variable declarations


About Query Builder functions

  Examples 	  Related Topics

A function is similar to an operator in that it manipulates data items and returns a result.  Functions differ from operators in the format in which they appear with their arguments.  This format allows them to operate on any number of arguments, including none.  Every time you associate a column with a function name, Query Builder performs the defined operation on the value(s) in that column.

Functions that you can use with queries in Query Builder are:

•	number functions

•	character functions

•	character functions returning numeric values

•	conversion functions

•	date functions

•	group functions

•	other functions

Additional Information: For information about any of the other functions, refer to the Oracle8 Server SQL Language Reference Manual.


Functions and arguments

  Examples 	  Related Topics

A function is used to manipulate data in a particular column.  Each function can take one or more arguments.  An argument is an expression within the parentheses of a function supplying information for the function to use.

An example is the function ROUND, which rounds a number to the degree you specify.  If you enter the expression ROUND (CREDIT_LIMIT, -2), Query Builder would round each value for CREDIT_LIMIT to the nearest hundred.  If you enter ROUND(CREDIT_LIMIT, 1), Query Builder would round the values for CREDIT_LIMIT to the nearest 10th.

The values used within arguments are:

Argument Value	Description
char, set, search,	Character constant surrounded by single quotation
replace	marks or an expression returning character data.
d, e	Date constant surrounded by single quotation marks, or an expression returning date data.
m, n	Any number constant or expression returning numeric data.
x	Argument type depends on the context of the function.
expr	An expression of any type.
fmt	A format used to change the display of data or to enter data into a Query Builder field or condition in a format other than the default format.


Number functions

  Related Topics

Number functions accept numeric data and return numeric data.  You can use number functions when defining columns and conditions.

Function (arguments)	Description
ABS(n)	Absolute value of n.
CEIL(n)	Smallest integer greater than or equal to n.
COS(n)	Returns the cosine of n (an angle expressed in radians).
COSH(n)	Returns the hyperbolic cosine of n.
EXP(n)	Exponential notation.  Returns e (2.71828183...) raised to the nth power.
FLOOR(n)	Largest integer equal to or less than n.
LN(n)	Returns the natural log of n, where n is greater than 0.
LOG(m,n)	Returns the logarithm, base m, of n.  The base m can be any positive number other than 0 or 1, and n can be any positive number.
MOD(m,n)	Remainder of m divided by n.
POWER(m,n)	m raised to the nth power.  If n is not an integer, it will be truncated
ROUND(n[,m])	n rounded to m decimal places; if m is omitted, to 0 places.  m may be negative to round digits left of the decimal point.
SIGN(n)	If n<0, -1; if n=0, 0; if n>0, 1.
SIN(n)	Returns the SINE of n (an angle expressed in radians).
SINH(n)	Returns the hyperbolic sine of n.
SQRT(n)	Square root of n; if n<0, NULL.
TAN(n)	Returns the tangent of n (an angle expressed in radians).
TANH(n)	Returns the hyperbolic tangent of n.
TRUNC(n[,m])	n truncated to m decimal places; if m is omitted, to 0 places.  m may be negative to truncate (make zero) digits left of the decimal point.


Character functions

  Related Topics

You can use character functions that accept character data and return character data when defining columns and conditions.

Function (arguments)	Description
CHR(n)	The character with having the binary equivalent to n in the database character set.
CONCAT(char1,char2)	Returns char1 concatenated with char2.  This function is equivalent to the concatenation operator (||).
INITCAP(char)	char, with first letter of each word capitalized.  Words are delimited by white space or characters that are not alphanumeric.
LOWER(char)	char, with all letters forced to lowercase.
LPAD(char1,n[,char2])	char1, left-padded to length n with the sequence of characters in char2, replicated as many times as necessary; if char2 is omitted, with blanks.
LTRIM(char[,set])	char, with initial characters removed up to the first character not in set.  set defaults to ` ' (a single blank).
NLS_INITCAP(char [,nlsparams])	Returns char, with the first letter of each word capitalized.  Words are delimited by white space or characters that are not alphanumeric.  The parameters specified in nlsparams can have the form NLS_SORT=sort where sort is a linguistic sort sequence for your session or BINARY.  If you specify BINARY, this function returns char.  For information on sort sequences, refer to the Oracle8 Server Concepts Manual.
NLS_LOWER(char[,nlsparams])	Returns char, with all letters forced to lowercase. See NLS_INITCAP for the nlspa-rams argument.
NLS_UPPER(char[,nlsparams])	Returns char, with all letters forced to uppercase. See NLS_INITCAP for the nlspa-rams argument.
REPLACE(char,search[,replace])	char, with every occurrence of search replaced with replace. If replace is not supplied, all occurrences of search are removed.
RPAD(char1,n[,char2])	char1, right-padded to length n with the characters in char2, replicated as many times as necessary; if char2 is omitted, with blanks.
RTRIM(char[,set])	char, with final characters removed after the last character not in set.  set defaults to ` ' (a single blank).
SOUNDEX(char)	A char value representing the sound of the word(s) in char.
SUBSTR(char,m[,n])	A substring of char, beginning at character m, n characters long if n is omitted.
SUBSTRB(char,m[,n])	Same as SUBSTR, except that the arguments m and n are expressed in bytes, rather than characters.  For a single byte database character set, SUBSTRB is the same as SUBSTR.
UPPER(char)	char, with all letters forced to uppercase.


Character functions returning numeric data

  Related Topics

You can use character functions to return numeric data when defining columns and conditions.

Abbreviation	Description
ASCII (char)	ASCII value of first character of char.
INSTR(char1,char2[,n[,m]])	The position of the nth occurrence of char2 in char1, beginning search at position n.  If m is omitted, 1 is assumed.  If n is omitted, 1 is assumed.  Position is given relative to the first character of char1, even when n>1.
INSTRB(char1,char2[,n[,m]])	Same as INSTR, except that n and the returned value are expressed in bytes, rather than characters.  For a single-byte database character set, INSTRB is the same as INSTR.
LENGTH(char)	The length, in characters, of char.
LENGTHB(char)	Same as LENGTH, except that char is expressed in bytes, rather than characters.  If char is NULL, this function returns NULL.  For a single-byte database character set, LENGTHB is the same as LENGTH.
NLSSORT(char[,nlsparams])	Returns the string of bytes used to sort char.  The parameters specified in nlsparams can have the form NLS_SORT=sort where sort is a linguistic sort sequence for your session or BINARY.  If you specify BINARY, this function returns char.  For information on sort sequences, refer to the Oracle8 Server Concepts Manual.


Conversion functions

  Related Topics

You can use conversion functions to convert data from one datatype to another when defining columns and conditions.

Abbreviation	Description
TO_CHAR (d[,fmt])	Converts d to a char value in the format specified by the char value fmt.  If fmt is omitted, d is converted to a char value in Query Builder's default date format, DD-MON-YY.
TO_CHAR(n[,fmt])	Converts n to a char value in the format specified by the char value fmt.  If fmt is omitted, n is converted to a char value exactly long enough to hold the significant digits.
TO_DATE(char[,fmt])	Converts a date from a char value to a date value.  fmt is a char value specifying the format of char.  If fmt is omitted, char must have the Query Builder default date format, DD-MON-YY.
TO_DATE(n,[fmt])	Converts a number into a date.  fmt must be a format that, when used with TO_CHAR, produces a DATE (e.g., J or MM).
TO_LABEL(char[,fmt])	Converts char, a value of datatype CHAR or VARCHAR2 containing a label in the format fmt, to a value of MLSLABEL datatype.  If you omit fmt, char must be in the default label format.
TO_MULTI_BYTE (char)	Returns char with all of its single-byte characters converted to their corresponding multi-byte characters.  Any single-byte characters that have no multi-byte equivalents appear in the output string as single-byte.  (This function is only useful if your database character set contains both types.)
TO_NUMBER (char)	Converts char, character data containing a number, to numeric data.
TO_SINGLE_BYTE (char)	Returns char with all of its multi-byte characters converted to their corresponding single-byte characters.  Any multi-byte characters that have no single-byte equivalents appear in the output string as multi-byte.  (This function is only useful if your database character set contains both types.)


Date functions

  Related Topics

All date functions return date data except MONTHS_BETWEEN, which returns numeric data.  You can use these functions when defining columns and conditions.

Abbreviation	Description
ADD_MONTHS (d,n)	Date d plus n months.
LAST_DAY(d)	Date of last day of month containing d.
MONTHS_BETWEEN(d,e)	Number of months between dates d and e. If d is later than e, result is positive; if earlier, negative.
NEW_TIME(d,a,b)	Date and time in time zone b when date and time in time zone a are d.  a and b are char expressions with the following meaning:
AST, ADT:	Atlantic Standard or Daylight Time
BST, BDT:	Bering Standard or Daylight Time
CST, CDT:	Central Standard or Daylight Time
EST, EDT:	Eastern Standard or Daylight Time
GMT:	Greenwich Mean Time
HST, HDT:	Alaska-Hawaii Standard or Daylight Time
MST, MDT:	Mountain Standard or Daylight Time
NST:	Newfoundland Standard Time
PST, PDT:	Pacific Standard or Daylight Time
YST, YDT:	Yukon Standard or Daylight Time
NEXT_DAY(d,char)	Date of first day of week named by char that is equal to or later than d.
ROUND(d[,fmt])	d rounded as specified by the rounding unit fmt; if fmt omitted, the nearest day.
SYSDATE	Current date and time.  Requires no arguments.
TRUNC(d[,fmt])	d with time of day truncated up to the specified truncation unit, fmt; if fmt omitted, the time of day is removed.
Additional Information: Refer to the Oracle8 Server SQL Language Reference Manual for a table of format models to be used with the ROUND and TRUNC date functions.


Group functions

  Related Topics

Group functions retrieve data based on groups of rows rather than one result per row.  Group functions perform operations such as average, count, sum, and standard deviation.

You can also use group functions to define a new column, and the entire result is treated as one group when you display no other columns.  Displaying other columns will divide the result into smaller groups.  You can use group functions in conditions, but only with a comparison operator, so the entire result is treated as one group.  For example, the condition SALARY > AVG(SALARY) is true when the value of SALARY in the current row is greater than the average of SALARY in all of the rows.

Group functions can be used with the DISTINCT or ALL options.  DISTINCT makes a group function consider only distinct functions of an expression.  For example, the average of 1, 1, 1, and 3 is 1.5; the DISTINCT average is 2.  ALL causes a group function to consider all values, including duplicates.

All of the following group functions skip null values except COUNT(*). The datatype of the arguments may be character, number, or date where expr is listed.

Function (argument)	Description
AVG([DISTINCT|ALL]n)	Average value of n, ignoring null values.
COUNT([DISTINCT|ALL] expr)	Number of rows where expr is not null.
COUNT(*)	Number of rows in the table, including duplicates and those with nulls.
GLB([DISTINCT|ALL] label)	Returns the greatest lower bound of label.
LUB([DISTINCT|ALL] label)	Returns the least upper bound of label.
Additional Information:  GLB and LUB return values of the MLSLABEL datatype.  For more information about the GLB and LUB functions, refer to the Trusted Oracle8 Server Administrator's Guide.

Function (argument)	Description
MAX([DISTINCT|ALL] expr)	Maximum value of expr.
MIN([DISTINCT|ALL] expr)	Minimum value of expr.
STDDEV([DISTINCT|ALL]n)	Standard deviation of n, ignoring null values, based on an n-1 (sample) calculation.
SUM([DISTINCT|ALL] n)	Sum of values of n.
VARIANCE([DISTINCT|ALL] n)	Variance of n, ignoring null values.


Other functions

  Related Topics

Query Builder also accepts these functions:

Function (argument)	Description
USER	Returns the name of the current Oracle user.  Requires no arguments.
DECODE(expr,search1, replace1[,search2, replace2,] ... [default])	If expr equals any search, returns the following replace; if not, returns default.  If default is omitted and there is no match, NULL is returned. expr may be any datatype; search must be the same type.  The value returned is forced to the same datatype as the first return.
GREATEST(expr1,expr2,...)	Returns the greatest of a list of values.  All expr after the expr1 are converted to the type of the expr1 before the comparison is done.
GREATEST_LB(label[,label] ...)	Returns the greatest lower bound of the list of labels.  Each label must either have datatype MLSLABEL or RAW MLSLABEL or be a quoted literal in the default label format.  The return value has the datatype RAW MLSLABEL.
LEAST(expr1,expr2,...)	Returns the least of a list of values.  All expr after the expr1 are converted to the type of the expr1 before the comparison is done.
LEAST_UB(label[,label] ...)	Returns the least upper bound of the list of labels.  Each label must have datatype MLSLABEL or be a quoted literal in the default label format.  The return value has the datatype RAW MLSLABEL.
NVL(x,expr)	If x is null, returns expr; if x is not null, returns x.  x and expr may be of any type. The type of the returned value is the same as the type of x.
Additional Information:  For more information about the GREATEST_LB and LEAST_UB functions, refer to the Trusted Oracle8 Server Administrator's Guide.


 Instead of selecting a table and clicking Include, you can double-click each target table to move it into the Query Builder work area.  To include a range of tables, hold down the SHIFT key while clicking the first and last tables in the range.


Although you can set relationships using this dialog box, you should use the mouse method to create relationships wherever possible. For relationships created this way, Query Builder automatically activates and deactivates the relationship lines for you.


If a column has a highlighted check beside it, that means the column appears in the SELECT statement and will be displayed in the query results.  If the column has an gray check beside it, the column is used as sort or group criteria.


In general Query Builder allows you to relate any columns that can be interpreted using the implicit conversion feature of the Oracle database.  For technical information on implicit conversions, refer to the Oracle8 Server SQL Language Reference Manual.


The expression in the Defined As field typically consists of a function or operation and the database column(s) to be operated on.  If the column name occurs in more than one table, remember to reference the table name as well, and separate it from the column name with a period.  If the column name is unique, you can specify just the column name.


Renaming a table does not result in any corresponding change in its underlying name in the database.  The new name is valid only for the active query; it remains in the query if you save it.


To display the Set Relationship dialog box, click [image] in the Icon Bar.


To display the Select Tables dialog box, click [image] in the Icon Bar.


To display the Rename Table dialog box, click [image] in the Icon Bar.


When you select a column object from a table, Query Builder automatically uses the table alias in your query.  Likewise, if you include a column object in the Condition field and accept the condition, Query Builder automatically inserts the appropriate table aliases into your condition.


You can select (or deselect) a column in either of the following ways:

•	Check (or uncheck) the check box next to the column.

OR

Double-click on the column name.


About self-relationships
K  About self-relationships

  Related Topics

A self-relationship relates a table to itself.  Self-relationships have a limited, very specific use:  to establish a parent-child link between two columns that are contained in the same table.  For example, you could use a self-relationship to relate subsidiaries of a company to their parent company, or employees to their managers.

A self-relationship cannot be effective unless the columns in the table are counterparts of one another.  In the sample database Employee table, for example, the Manager ID is the same as the Employee ID for that manager.  So the self-relationship icon is displayed in the Manager ID column.


Creating a self-relationship

  Related Topics

To create a self-relationship:

1	In the Set Relationship dialog box, Query Builder displays a list of tables that have relationships defined with the selected table.

2	Click the table name.

3	Click Include.

4	Click OK.

5	Repeat the above procedure for the same table name.

6	Query Builder automatically names the copy of the related table with an alias.  Rename the table to match the name of the original.

Note:  If the self-relationship has already been identified in the underlying data dictionary, the two related columns in the table and the alias are connected with a relationship line.  If the self-relationship has not been identified in the data dictionary, you can create a self-relationship by drawing a temporary relationship line, to connect the two counterpart columns in the table and the alias.


 Creating a simple relationship

  Related Topics

To create a relationship using the mouse:

1	In the Query window, open the tables you want to relate.

2	While the table is displayed, select the column that you want to relate (the foreign key).

3	While holding down the mouse button, drag the cursor to the related column in the second table (the primary key) to draw a relationship line.

4	Once the target column is highlighted, release the mouse button to anchor the relationship line.  By default, the relationship is inactive (the line appears gray).

To create a relationship using the Set Relationship dialog box:

1	In the Set Relationship dialog box, type the origin (A->) and target (->B) column names.  Note Query Builder draws a relationship line between the two columns.

2	Click Close.

To create a relationship using a shortcut:

1	In the Set Relationship dialog box, click inside field A.

2	In the Query window, select the column.  Query Builder automatically places the table and column name in field A.

3	Repeat the procedure for field B.


Creating a composite relationship

  Related Topics

A composite relationship connects two or more columns in one table with columns in another table.   For example, you might relate the columns Order ID and Item ID in the Items table with identically named columns in the Item List table.

To create a composite relationship:

1	In the Query Builder workspace, click [image] in the Icon bar.

2	Include the two tables you want to join.

3	Select the column you want to relate (the foreign key).

4	While holding down the mouse button, drag the cursor to the related column in the second table (the primary key).  Notice that the cursor traces out a relationship line as you do so.

5	Once the target column is highlighted, release the mouse button to anchor the relationship line.  By default, the relationship is inactive (the line appears gray).

You can use as many composite relationships as are appropriate for your query. In addition, you can include columns in composite relationships regardless of whether they are used in other relationships.


You must type the complete table and column names (separate the table name from its column name with a period).  A-> represents the table's foreign key(s), and ->B represents the table's primary key(s).  Separate additional primary and foreign keys with commas.


Creating an unmatched relationship

  Related Topics

To create an unmatched, or outer, relationship:

1	In the Query window, click on the relationship line that connects your tables.  If there is no relationship line, create a simple relationship between the two tables.

2	In the Set Relationship dialog box, choose one of the display options to either retrieve all records included in a simple relationship or to retrieve only the rows where there is a corresponding value in both tables.

Note: A row that returns a value of 0 (zero) is not the same as an unmatched row.  Suppress Mismatched only works on rows that return null values, not 0 values.  Use this feature if you want to display data where one table has no values entered, such as orders with no line items, customers who have not made orders, sales representatives who do not have customers, and so forth.


Removing unmatched rows

  Related Topics

To remove an unmatched relationship:

1	In the Query Builder workspace, click on the relationship line that connects your target tables.

2	In the Set Relationship dialog box, select the Suppress Mismatches radio button.

3	Click OK.


Using a non-equal relationship

  Related Topics

To create a non-equal relationship in the Set Relationship dialog box:

  Select the operator.

When you set up a non-equal relationship, Query Builder places an icon (a not equal sign) on the relationship line.


Deleting a relationship

  Related Topics

To delete a relationship:

1	In the Query window, click on the relationship line that connects the two table columns.

2	When both the column names and the relationship line are highlighted, press the DELETE key.


About unmatched (null) rows

  Related Topics

Query Builder lets you choose whether to retrieve unmatched rows when you are using a relationship in a query.  An unmatched row occurs when the relationship connects tables where there are values on one side that have no corresponding values on the other side.  SQL users will be familiar with this as a query condition known as an outer join.  Unmatched rows usually return null values.

Note: A row that returns a value of 0 (zero) is not the same as an unmatched row.  The Suppress Unmatched Rows option in the Set Relationship dialog box works on rows that return null values, not 0 values.  Use this feature if you want to display data where one table has no values entered, such as orders with no line items.  When using an unmatched relationship, you can only choose one side on which to display unmatched records.


Building a new query

  Related Topics

To build a new query:

1	In the Query Builder workspace, click [image] in the Icon bar.

2	Double-click the table(s) from which you want to retrieve data.

3	Click Include to close the dialog box and display the table.

4	Select each column.   A check mark appears in the checkbox next to each selected column. To include all the columns, check the checkbox in the table title bar..  Tip

5	Type one or more conditions to refine your query.

6	Click OK to close the Query Builder.


Locating available tables

  Related Topics

To locate the tables you can use in your query:

1	In the Query Builder workspace, click [image] in the Icon bar.

2	Use the Show check boxes to sort the tables by type.


Clearing a table

To clear (erase) a table from the Query Builder work area:

1	Click on the table in the Query window.

2	Click [image] in the Icon bar.  Query Builder removes the table from the Query Builder work area. You can then click [image] to include it in your query again.

Cutting or clearing a table does not delete the table from the database, but merely removes it from the query.


Renaming a table

  Related topics

To rename a table:   Note

1	Click [image] in the Icon bar.

2	In the Rename Table dialog box, select the table whose name you want to change from the Available Tables list.

3	Click inside the New Name field.

4	Delete the unwanted information.

5	Enter the new name for your table. The new name can be up to 30 characters long.

6	Click Define.

7	Click OK.

Renaming a table in the Query Builder work area does not result in any corresponding name change in the underlying table.  The new name is valid only for the active query.


Displaying information and comments on tables and columns

To display the information and comments that have been stored in the database:

  In the Query Builder work area, double-click the far right icon in the table header to see information on the table; double-click the first icon in each column to see column information.


Removing a column from a query

  Related Topics

To remove a column from a query:

  Select the column in the Query Builder work area.  The check mark in the table disappears.


Counting rows in a query

To count how many rows a query will return before executing the query:

  In the Query Builder workspace, click [image] in the Icon bar.  An alert box appears displaying the number of rows that will be retrieved.


Adding conditions to a query

  Examples	  Related Topics

To add conditions to a query:

1	Click in the blank condition field in the Conditions panel to activate it.  A plus sign appears next to the cursor arrow.  Your mouse pointer can now be used for automatic point-and-click field selection.

2	Select the column you want to apply a condition to in the Query Builder work area.  To display a list of all available columns, click [image] in the Icon bar.  Tip

3	Click the appropriate operator on the Icon bar. To add functions to your condition, click [image] in the Icon bar.

4	Type the appropriate value for the right side of your condition expression after the operator.  To add another condition, press Shift-Enter to move the cursor to a new line.

5	If you’re satisfied with your expression, click outside the condition field but within the Conditions panel to deactivate it, or click [image] in the Icon bar.  To clear the Conditions panel and start over, click [image] in the Icon bar.


About conditions

  Examples 	  Related Topics

A condition is a text phrase you place in a query to target the information you want and filter out information you do not want.  Conditions can save you time and make your queries more focused, because they enable you to retrieve columns of the table.  Tip

For example, say you included the Employee table in your query, and selected the Name, Salary, and Job title columns.  Without conditions you've essentially said to the database "Select all the employee data from the Name, Salary, and Job columns in the Employee table."  Now you can add conditions to your original request, such as, "where...

•	the monthly salary is greater than $1000 and less than $2000."

•	the last name is Smith."

•	the job is not Manager."

Instead of typing all the words shown in the above examples into the condition, you use operators, so the condition almost looks like a formula.  For example, to specify employees whose salaries are greater than $3000, you might type:

SALARY > 3000

You can also use functions to help you create complex conditions.


Condition example

  Related Topics 	  All Examples

Suppose you want to create a query where you view data for the state of California only.

1	Click the condition field to activate it.

2	Select the State column in the appropriate table in the Query Builder work area.   The word STATE appears in the condition field.

3	Type the EQUALS (=) symbol.

4	Type in ‘CA’ to the right of the equal sign in the condition field.

The condition should now look like this:  STATE=’CA’


About operators

  Related Topics

An operator is a character or reserved word that is used to perform some operation.  The three principal types of operators used in Query Builder are:

•	comparison

•	arithmetic

•	logical

Note:  You can also create negating conditions based on these operators.


Comparison operators

  Related Topics

Comparison operators are used to compare two values.  When you insert the operator between a column name and a value in the Conditions panel, Query Builder will compare all items in that column against the value, and return only those rows where the condition statement is true

For example, to return only those rows where the value in the CREDIT_LIMIT column is less than $6,000, use the < (less than) operator:

CREDIT_LIMIT < 6000

The Query Builder comparison operators are:

Operator	Usage
=	Equal
<>	Not Equal
<	Less Than
<=	Less Than or Equal To
>	Greater Than
>=	Greater Than or Equal
BETWEEN...AND...	Between two values
IN (LIST)	Equal to any member of the following list
IS NULL	Is a NULL value.  A row without a value in one column is said to contain a NULL value.


Arithmetic operators

  Related Topics

Arithmetic operators are used to perform calculations on numeric and date columns.  In handling calculations, Query Builder first evaluates any multiplication or division, then evaluates any addition or subtraction.

•	For example, in the expression 1+2x3, first 2 is multiplied by 3, then the result is added to 1, yielding a final result of 7.

To override these precedence rules, place part of the expression in parentheses; Query Builder evaluates expressions in parentheses first.

•	For example, in the calculation (1+2)x3, (1+2) is evaluated first, then the result is multiplied by 3, yielding a final result of 9.

The Query Builder arithmetic operators are:

Operator	Usage
+	Addition
-	Subtraction
*	Multiplication
/	Division


Logical operators

  Related Topics

The logical (also called Boolean) operators are AND, OR, and NOT:

•	Use AND to retrieve only the data that meets all conditions.

•	Use OR to retrieve all data that meets at least one of the specified conditions.

•	Use NOT negate the operator(s) or condition(s).

The Icon Bar includes icons for the logical operators.  The operator icons are available when the Conditions panel is active, or when the Define Column dialog box is open.  You can insert an operator into the text of the condition or defined column by clicking the operator in the Icon Bar.


About defined (and computed) columns

  Examples 	  Related Topics

You can perform calculations on the data Query Builder retrieves from the database, then display the calculated data in the Results window as a new column (also known as a defined field).  You can name, define, and display these columns just as you would any other column in your query.

You can use defined columns in a Query Builder query to construct "what if" scenarios, forecasts, projections, and other analyses, such as variances and percent-to-total.

Note:  When you display a defined column (field) that contains an aggregate function, Query Builder automatically generates the corresponding GROUP BY clause for other displayed columns not involving aggregate functions.  Advanced users can also specify GROUP BY columns manually for grouping by non-displayed columns.

While columns are generally synonymous with the columns of data stored in your tables, they can also refer to new columns of data in a query that are derived or calculated from the values in another column.  These computed columns are sometimes known as derived or defined fields.  For example, the Employee table may include two columns that describe compensation: Salary and Commission.  You can create a defined column that combines the values in these columns into a new column called Net Pay that represents the summation of salary plus commission.

You can base your defined columns on any combination of single or multiple database columns, according to your needs.

Defined columns exist in your query, not in the database.  You can choose to display them in the Results window as columns, or keep them hidden (such as when using them to create other defined columns).

Note:  The defined column is only a part of your query and will not modify the table definition saved in the database.


Deleting a defined column

  Related Topics

To delete a defined column from a query:

1	In the Query Builder workspace, click [image] in the Icon bar.

2	Click the name of the column to be deleted.

3	Click Remove.


Defined (and computed) column example

  Related Topics 	  All Examples

Suppose you wanted to project a budget for next year's net pay (NET_PAY_NEXT) assuming a 10% salary increase.  You could enter the following in the Expression field:

(SALARY*1.1) + COMMISSION

Or, if you wanted to review a 10% increase in both salary and commission, you could enter:

(SALARY+COMMISSION) * 1.1

Since NET_PAY is SALARY+COMMISSION, this is the same as:

NET_PAY * 1.1

You can also create a defined column that displays the difference between the current net pay and next year's projections.  Call this column VARIANCE, and define it as:

NET_PAY_NEXT - NET_PAY

When you define new columns, the base columns described in your expression need not exist in the underlying database, although they should ultimately be derived from columns in the underlying table.  VARIANCE, for example, is the same as:

((SALARY+COMMISSION) * 1.1) - (SALARY+COMMISSION)


Deleting a sort column

  Related Topics

To delete a sort column:

1	In the Query Builder workspace, click the Sort icon.

2	Double-click the name of the column to be deleted in the Sorted Columns list.


Sorting query data

  Related Topics

To sort the data your query retrieves:

1	In the Query Builder workspace, click [image] in the Icon bar.

2	Double-click the column(s) you want to sort by in the Available Columns list.  A sort column does not have to be included in the query.

To change the sort order of a column from the default (ascending):

1	Click to highlight the column in the Sorted Columns list.

2	Click the Descending radio button.

3	Click OK.


Defining a column

  Related Topics

To define a new column in a table:

1	Open the table in which you want to define a column.

2	Click [image] in the Icon bar.

3	Click inside the Defined Columns box.

4	Type the name for your new column.

5	Click inside the Defined as box.

6	Type the expression that defines your column.

7	Click OK.


Pasting a function

  Examples 	  Related Topics

To paste a function into a condition:

1	Activate the Condition field and place your cursor where you want to insert the function.

2	Click [image] in the Icon bar.

3	Use the Show Categories check boxes to filter the types of functions shown.

4	Select a function from the list box.

5	Click the Paste Arguments check box if you want to include default arguments.

6	Click OK.

7	In the Condition field, type over the default arguments with the arguments you want to use.


Function example (retrieving names greater than 30 characters)

  Related Topics 	  All Examples

Suppose you want to list the names of all customers whose names are more than 30 characters long because these names are too long for your mailing labels.  To list these names, you create a condition using the LENGTH function.  LENGTH counts the number of characters in a character string.

In this example, the argument in the LENGTH function is the NAME column in the customer table.  So your function appears in the condition as:

LENGTH (NAME) > 30

Using this condition, Query Builder will evaluate all names in the NAME column and return those where the length of the field is greater than 30 characters.


Creating a nested condition

  Related Topics

To create a nested condition:

1	In the Condition field, type the first expression using a comparison operator, such as:  TOTAL<1000. Tip

2	Type the next expression, using another comparison operator, such as: EMP.LAST_NAME=SMITH

3	Type a third expression, using the same comparison operator (=), such as:  EMP.LAST_NAME=JONES.

4	Select the second and third expressions.

5	Click [image] in the Icon Bar.

6	Click [image] in the Icon bar.


Sizing the Conditions panel

To size the Conditions panel:

1	Click the black rectangle at the bottom left of the Query Builder work area scroll bar and move the cursor up to the Query Builder work area.

2	Drag the thick black line to the left or right to widen or narrow the Conditions panel.  If the panel is hidden entirely, the split bar appears at the far left of the scroll bar.


Condition syntax

  Related Topics

The general format of a condition is:

[expression] [operator] [expression]

where

expression	specifies the values that define the condition; expressions can specify dates, characters, literal values, numbers, columns, functions, and database columns.
operator	specifies a comparison operator, such as greater than (>), less than (<), and equal to (=).  The most common operators are listed in the Data menu and the Icon Bar.  There are also a number of special comparison operators such as BETWEEN, LIKE, and IN.
Date values

When working with dates, the comparison operators refer to relative time.  So "less than" (<) means "before."

Date values must be enclosed in single quotes and specified in DD-MON-YY format, where DD represents the calendar day, MON represents the month, and YY represents the year.

Character values

With character columns, operators refer to alphanumeric order (A comes before B, so names that begin with A are "less than" names beginning with B, and so forth).

Literal values

Literal values must be enclosed in single quotes to distinguish them from column names.  Comparison between the database values and the values you specify are case-sensitive.

Number values

If the value you enter is a NUMBER datatype, type only the number.  That is, do not use formatting such as commas or the currency ($) symbol.  Numeric values in numeric columns do not need to be in quotes.

Note:  There are also three logical (Boolean) operators (AND, OR, NOT) that enable you to create multiple or negative conditions.

Additional Information:  For more information about Oracle syntax for various datatypes, refer to the Oracle8 Server SQL Language Reference Manual.


Creating a negating condition

  Related Topics

To create a negating condition:

1	Build a condition.

2	Click the Condition field to activate it.

3	Select a logical operator for the condition.

4	Click [image] in the Icon bar.

5	Press the Enter or Return key to accept the condition.

Note:  NOT AND returns all rows except where all the conditions are met; NOT OR returns all rows except where any of the conditions are met.


Saving a query's SQL statements
Saving a query’s SQL statements

  Related Topics

To save a query’s SQL statements:

  In the Query window, choose File [image] Save SQL to display the Save SQL dialog box, which allows you to specify a directory and file name.


Changing column order

  Related Topics

To change the order in which columns appear in your query results:

1	In the Query Builder workspace, click [image] in the Icon bar.

2	In the Column Sequence dialog box, click on a column in the Displayed Columns list and drag it up or down to the desired position.  The top column appears to the far left of the display; the bottom column, to the far right.


Displaying a query's SQL statements
Displaying a query’s SQL statements

  Related Topics

To display a query’s SQL statements:

  In the Query Builder workspace, click [image] in the Icon bar.

The Show SQL dialog box is read-only; you cannot edit or copy the SQL statements.


Adding a column to a query

  Related Topics

To add a column to a query:

 Select the column in a table in the Query window.  Tip

A checked column indicates that the column appears both in the SQL statement and the query results.  You cannot include a column in the SQL statement and hide it from the displayed results.


Examples

  Alphabetic List

Application property examples

Arc property examples

Axis (continuous) property examples

Axis (date) property examples

Axis (discrete) property examples

Axis (generic) property examples

Built-in examples

Chart built-ins examples

Chart element property examples

Chart property examples

Compound text property example

Database built-ins examples

Display built-ins examples

Display properties examples

Field template (axis chart) properties

Field template (generic) property examples

Frame (axis chart) property examples

Frame (generic) property examples

Frame (pie chart) property examples

Frame (table chart) property examples

Generic property examples

Graphic object built-in examples

Graphic property examples

Group property examples

Image property examples

Layer built-in examples

Line property examples

Miscellaneous built-in examples

Parameter built-in examples

Polygon property examples

Printer property examples

Property examples

Query built-in examples

Query property examples

Rectangle property example

Reference line property examples

Rounded rectangle property examples

Simple text property examples

Sound built-in examples

Sound property example

Symbol property examples

Template built-in examples

Text property examples

Timer built-in examples

Timer property examples

TOOLS_INT built-in examples

Window built-in examples

Window property examples


Property examples

  Alphabetic List      [image]  All Examples

Application property examples

Arc property examples

Axis (continuous) property examples

Axis (date) property examples

Axis (discrete) property examples

Axis (generic) property examples

Chart element property examples

Chart property examples

Compound text property example

Display properties examples

Field template (axis chart) properties

Field template (generic) property examples

Frame (axis chart) property examples

Frame (generic) property examples

Frame (pie chart) property examples

Frame (table chart) property examples

Generic property examples

Graphic property examples

Group property examples

Image property examples

Line property examples

Polygon property examples

Printer property examples

Query property examples

Rectangle property example

Reference line property examples

Rounded rectangle property examples

Simple text property examples

Sound property example

Symbol property examples

Text property examples

Timer property examples

Window property examples


Built-in examples

  Alphabetic List      [image]  All Examples

Chart built-ins examples

Database built-ins examples

Display built-ins examples

Graphic object built-in examples

Layer built-in examples

Miscellaneous built-in examples

Parameter built-in examples

Query built-in examples

Sound built-in examples

Template built-in examples

Timer built-in examples

TOOLS_INT built-in examples

Window built-in examples


Application property examples

  All Examples     [image]  Related Topics

Connection String Property Examples

Cursor Property Examples

Horizontal Layout Resolution Property Examples

Horizontal Screen Resolution Property Examples

Password Property Examples

Platform Property Examples

Username Property Examples

Vertical Layout Resolution Property Examples

Vertical Screen Resolution Property Examples


Arc property examples

  All Examples     [image]  Related Topics

Base Arc Property Examples

Closure Property Examples

Fill Property Examples


Axis (date) property examples

  All Examples     [image]  Related Topics

Auto Maximum Property Examples

Auto Minimum Property Examples

Auto Step Property Examples

Custom Format Property Examples

Day Format Property Examples

First Month Property Examples

Labels Property Examples

Maximum Property Examples

Minimum Property Examples

Month Format Property Examples

Quarter Format Property Examples

Skip Weekends Property Examples

Step Property Examples

Year Format Property Examples


Axis (generic) property examples

  All Examples     [image]  Related Topics

Axis Label Property Examples

Axis Type Property Examples

Custom Label Property Examples

Direction Property Examples

Major Grid Property Examples

Major Ticks Property  Examples

Minor Grid Property Examples

Minor Ticks Per Interval Property Examples

Position Property Examples

Tick Labels Property Examples

Tick Position Property Examples

Tick Label Rotation Property Examples


Axis (discrete) property examples

  All Examples     [image]  Related Topics

Auto Maximum Property Examples

Auto Minimum Property Examples

Date Format Property Examples

Maximum Number of Categories Property Examples

Minimum Number of Categories Property Examples

Number Format Property Examples


Axis (continuous) property examples

  All Examples     [image]  Related Topics

Auto Maximum Property Examples

Auto Minimum Property Examples

Auto Step Property Examples

Maximum Property Examples

Minimum Property Examples

Number Format Property Examples

Percent by Property Examples

Percent of Property Examples

Scale Property Examples

Step Property Examples


Chart built-ins examples

  All Examples    [image]  Related Topics

OG_Delete_Column Example

OG_Delete_Field Examples

OG_Get_Chart_Element Examples

OG_Get_Column Examples

OG_Get_Field Examples

OG_Get_Row Examples

OG_Insert_Field Examples

OG_Make_Chart Examples

OG_Update_Chart Examples


Chart element property examples

  All Examples     [image]  Related Topics

Button Procedure Property Examples

Events Property Examples

Explosion Property Examples

Name Property Examples


Chart property examples

  All Examples     [image]  Related Topics

Auto Update Property Examples

End Row Property Examples

Filter Property Examples

Query Property Examples

Range Property Examples

Size and Position Property Examples

Start Row Property Examples

Template Property Examples

Title Property Examples


Compound text property example

  All Examples     [image]  Related Topics

Simple Text Count Property Examples


Database built-ins examples

  All Examples     [image]  Related Topics

OG_Connect Examples

OG_Logged_On Examples

OG_Logoff Examples

OG_Logon Examples


Display built-ins examples

  All Examples     [image]  Related Topics

OG_Close_Display Examples

OG_Generate_Display Examples

OG_Get_Display Examples

OG_Isnull Examples

OG_Open_Display Examples

OG_Save_Display Examples


Display properties examples

  All Examples     [image]  Related Topics

Close Trigger Property Examples

Date Format Property Examples

Height Property Examples

Open Trigger Property Examples

Width Property Examples


Frame (axis chart) property examples

  All Examples     [image]  Related Topics

Baseline Axis Property Examples

Baseline Value Property Examples

Category Width Property Examples

Custom Date Format Property Examples

Custom Number Format Property Examples

Reference Line Count Property Examples

Second Y Axis Property Examples


Frame (generic) property examples

  All Examples     [image]  Related Topics

Depth Size Property Examples

Frame Type Property Examples

Field Template Count Property Examples

Legend Column Count Property Examples

Legend Property Examples

Name Property Examples

Plot Frame Property Examples

Root Property Examples

Shadow Direction Property Examples

Shadow Size Property Examples


Frame (pie chart) property examples

  All Examples     [image]  Related Topics

Categories Property Examples

Data Values Property Examples

Category Date Format Property Examples

No Overlap Property Examples

Category Number Format Property Examples

Other Property Examples

Percent Format Property Examples

Percent Values Property Examples

Plot Order Property Examples

Ticks Property Examples

Usage Property Examples

Usage Value Property Examples

Value Format Property Examples


Frame (table chart) property examples

  All Examples     [image]  Related Topics

Auto Maximum Property Examples

Auto Minimum Property Examples

Column Names Property Examples

Grid Count Property Examples

Horizontal Grid Property Examples

Maximum Number of Rows Property Examples

Minimum Number of Rows Property Examples

Vertical Grid Property Examples


Field template (generic) property examples

  All Examples     [image]  Related Topics

Color Rotation Property Examples

Date Format Property Examples

Name Property Examples

Number Format Property Examples

Root Property Examples


Field template (axis chart) properties

  All Examples     [image]  Related Topics

Axis Property Examples

Curve Fit Property Examples

Label Rotation Property Examples

Line Style Property Examples

Overlap Property Examples

Plot Position Property Examples

Plot Type Property Examples


Generic property examples

  All Examples     [image]  Related Topics

Button Procedure Property Examples

Column Property Examples

Events Property Examples

Execute Query Property Examples

Format Trigger Property Examples

Inner Bounding Box Property Examples

Name Property Examples

Outer Bounding Box Property Examples

Object Type Property Examples

Parent Property Examples

Set Parameter Property Examples

Hide Object Property Examples


Graphic property examples

  All Examples     [image]  Related Topics

Background Edge Color Property Examples

Bevel Style Property Examples

Background Fill Color Property Examples

Cap Style Property Examples

Dash Style Property Examples

Edge Pattern Property Examples

Edge Width Property Examples

Foreground Edge Color Property Examples

Foreground Fill Color Property Examples

Fill Pattern Property Examples

Join Style Property Examples

Rotation Angle Property Examples

Transfer Mode Property Examples


Group property examples

  All Examples     [image]  Related Topics

Child Count Property Examples

Clip Flag Property Examples


Image property examples

  All Examples     [image]  Related Topics

Clip Rectangle Property Examples

Dither Property Examples

Height Property Examples

Position Property Examples

Quality Property Examples

Width Property Examples


Layer built-in examples

  All Examples     [image]  Related Topics

OG_Activate_Layer Examples

OG_Get_Layer Examples

OG_Hide_Layer Examples

OG_Show_Layer Examples


Line property examples

  All Examples     [image]  Related Topics

Arrow Style Property Examples

End Point Property Examples

Start Point Property Examples


Miscellaneous built-in examples

  All Examples     [image]  Related Topics

OG_Append_Directory Examples

OG_Append_File Examples

OG_Center Examples

OG_Damage (Region) Examples

Do_Sql Examples

OG_Get_Attr (Application) Examples

OG_Get_Attr (Axis) Examples

OG_Get_Attr (Display) Examples

OG_Get_Attr (Field Template) Examples

OG_Get_Attr (Frame Template) Examples

OG_Get_Attr (Object) Examples

OG_Get_Attr (Printer) Examples

OG_Get_Attr (Query) Examples

OG_Get_Attr (Reference Line) Examples

OG_Get_Attr (Sound) Examples

OG_Get_Attr (Timer) Examples

OG_Get_Attr (Window) Examples

OG_Translate_Envvar Examples

OG_User_Exit Examples


Graphic object built-in examples

  All Examples     [image]  Related Topics

OG_Clone (Object) Examples

OG_Damage (Object) Examples

OG_Delete_Child Examples

OG_Delete_Cmptext Examples

OG_Delete_Point Examples

OG_Delete_Property Examples

OG_Delete_Smptext Examples

OG_Destroy (Object)  Examples

OG_Draw Examples

OG_Export_Drawing (Display)  Examples

OG_Export_Drawing (Object/Layer) Examples

OG_Export_Drawing (Window) Examples

OG_Export_Image Examples

OG_Get_Char_Property Examples

OG_Get_Child Examples

OG_Get_Cmptext Examples

OG_Get_Date_Property Examples

OG_Get_Num_Property Examples

OG_Get_Object Examples

OG_Get_Point Examples

OG_Get_Smptext Examples

OG_Import_Drawing Examples

OG_Import_Image Examples

OG_Insert_Child Examples

OG_Insert_Cmptext Examples

OG_Insert_Point Examples

OG_Insert_Smptext Examples

OG_Make_Ellipse Examples

OG_Make_Group Examples

OG_Make_Image Examples

OG_Make_Line Examples

OG_Make_Poly Examples

OG_Make_Rect Examples

OG_Make_Rrect Examples

OG_Make_Symbol Examples

OG_Make_Text Examples

OG_Move Examples

OG_Point_In Examples

OG_Point_Near Examples

OG_Property_Exists Examples

OG_Rotate Examples

OG_Same Examples

OG_Scale Examples

OG_Set_Edgecolor Examples

OG_Set_Fillcolor Examples

OG_Set_Property Examples

OG_Synchronize Examples

OG_Update_Bbox Examples


Parameter built-in examples

  All Examples     [image]  Related Topics

OG_Delete_Param Examples

OG_Get_Char_Param Examples

OG_Get_Date_Param Examples

OG_Get_Num_Param Examples

OG_Get_Param_Type Examples

OG_Param_Exists Examples

OG_Set_Param Examples


Polygon property examples

  All Examples     [image]  Related Topics

Closure Property Examples

Point Count Property Examples


Printer property examples

  All Examples     [image]  Related Topics

Copies Property Examples

End Page Property Examples

Print File Property Examples

Landscape Property Examples

Name Property Examples

Page Size Property Examples

Start Page Property Examples


Query built-in examples

  All Examples     [image]  Related Topics

OG_Append_Row Examples

OG_Clear_Query Examples

OG_Data_Changed Examples

OG_Data_Queried Examples

OG_Destroy (Query) Examples

OG_Execute_Query Examples

OG_Get_Charcell Examples

OG_Get_Datecell Examples

OG_Get_Newrows Examples

OG_Get_Numcell Examples

OG_Get_Query Examples

OG_Get_Schema Examples

OG_Insert_Column Examples

OG_Make_Query Examples

OG_Next_Row Examples

OG_Numcols Examples

OG_Numrows Examples

OG_Set_Charcell Examples

OG_Set_Datecell Examples

OG_Set_Numcell Examples

OG_Set_Schema Examples

OG_Start_From Examples


Query property examples

  All Examples     [image]  Related Topics

Cache Type Property Examples

Custom Query Procedure Property Examples

Date Format Property Examples

Execute on Open Property Examples

Execute on Timer Property Examples

Maximum Rows Flag Property Examples

Maximum Rows Property Examples

Name Property Examples

Post-Query Trigger Procedure Property Examples

Query Source Property Examples

Query Type Property Examples


Rectangle property example

  All Examples     [image]  Related Topics

Base Rectangle Property Examples


Reference line property examples

  All Examples     [image]  Related Topics

Axis Property Examples

Date Value Property Examples

Label Property Examples

Number Value Property Examples


Rounded rectangle property examples

  All Examples     [image]  Related Topics

Base Rectangle Property Examples

Corner Radii Property Examples


Sound property example

  All Examples     [image]  Related Topics

Name Property Examples


Sound built-in examples

  All Examples     [image]  Related Topics

OG_Destroy (Sound) Examples

OG_Export_Sound Examples

OG_Get_Sound Examples

OG_Import_Sound Examples

OG_Make_Sound Examples

OG_Play_Sound Examples

OG_Record_Sound Examples

OG_Stop_Sound Examples


Simple text property examples

  All Examples     [image]  Related Topics

Color Property Examples

Font Property Examples

Text String Property Examples


Symbol property examples

  All Examples     [image]  Related Topics

Center Property Examples

Index Property Examples

Symbol Size Property Examples


Template built-in examples

  All Examples     [image]  Related Topics

OG_Clone (Template) Examples

OG_Delete_Ftemp Examples

OG_Delete_Refline Examples

OG_Destroy (Template) Examples

OG_Export_Template Examples

OG_Get_Axis Examples

OG_Get_Ftemp Examples

OG_Get_Refline Examples

OG_Get_Template Examples

OG_Import_Template Examples

OG_Insert_Ftemp Examples

OG_Insert_Refline Examples

OG_Make_Template Examples


Timer property examples

  All Examples     [image]  Related Topics

Active Property Examples

Interval Property Examples

Name Property Examples

Procedure Property Examples


Timer built-in examples

  All Examples     [image]  Related Topics

OG_Activate_Timer Examples

OG_Deactivate_Timer Examples

OG_Destroy (Timer) Examples

OG_Get_Timer Examples

OG_Make_Timer Examples


TOOLS_INT built-in examples

  All Examples     [image]  Related Topics

Tool_Int.Add_Parameter Examples

Tool_Int.Create_Parameter_List Examples

Tool_Int.Delete_Parameter Examples

Tool_Int.Destroy_Parameter_List Examples

Tool_Int.Get_Parameter_Attr Examples

Tool_Int.Get_Parameter_List Examples

Tool_Int.Isnull Examples

Tool_Int.Run_Product Examples

Tool_Int.Set_Parameter_Attr Examples


Text property examples

  All Examples     [image]  Related Topics

Bounding Box Height Property Examples

Bounding Box Width Property Examples

Character Set Property Examples

Color Property Examples

Compound Text Count Property Examples

Custom Spacing Property Examples

Fixed Bounding Box Property Examples

Horizontal Alignment Property Examples

Horizontal Origin Property Examples

Invisible Property Examples

Kerning Property Examples

Nearest Property Examples

Point Size Property Examples

Scalable Bounding Box Property Examples

Scalable Font Property Examples

Spacing Property Examples

Style Property Examples

Synthesize Property Examples

Typeface Property Examples

Vertical Alignment Property Examples

Vertical Origin Property Examples

Weight Property Examples

Width Property Examples

Wraparound Property Examples


Window property examples

  All Examples     [image]  Related Topics

Height Property Examples

Help Target Property Examples

Name Property Examples

Position Property Examples

Width Property Examples


Window built-in examples

  All Examples     [image]  Related Topics

OG_Destroy (Window) Examples

OG_Get_Window

OG_Hide_Window Examples

OG_Make_Window Examples

OG_Show_Window Examples


Compound Text Properties

Simple Text Count Property

Compound Text Count Property


Simple Text Count Property

  Examples	  Related Topics

Description  Is the number of simple text elements that compose the compound text element.

Syntax

FUNCTION OG_Get_Stcount
  (text           OG_Object,
   cmptext_index  NUMBER)
RETURN NUMBER;

Parameters

text	Is the text element being described.
cmptext_index	Is the index number of the compound text element being described.


Simple Text Count Property Examples

  Alphabetic List          [image]  All Examples     [image]  Related Topics

*/The following procedure reads the count of
**simple text of the first compound
**text in a text object, and prints the count
**back to the text object.
*/

 PROCEDURE simpleText IS

  num number;

  text og_object;

BEGIN

  text := og_get_object('text');

  num := og_get_stcount(text,0);

  og_set_str(text, num);

END;