Copyright: Oracle Corporation© 1999


About alerts

  Related Topics

An alert is a modal window that displays a message notifying the operator of some application condition.

Use alerts to advise operators of unusual situations or to warn operators who are about to perform an action that might have undesirable or unexpected consequences.

There are three styles of alerts: Stop, Caution, and Note.  Each style denotes a different level of message severity.  Message severity is represented visually by a unique icon that displays in the alert window.

Form Builder has many built-in alerts that display pre-defined messages.  You can also create your own custom alerts that display in response to application-specific events.

When an event occurs that causes an alert to display, the operator must respond to the alert's message by selecting one of the predefined alert buttons.  Selecting any button immediately dismisses the alert.


About creating alerts

  Related Topics

When you create an alert, you need only specify basic information such as the message you want the alert to display and the text labels for the alert buttons.

Once you create an alert, you must write a trigger or user-named routine to display the alert in response to a particular event.  In addition, the action that each button initiates is determined by the PL/SQL code you write to invoke the alert.


Creating an alert

  Related Topics

To create an alert:

1	In the Object Navigator, click the Alerts node.

2	Click the Create button [image] in the toolbar.

3	Double-click the alert object icon to display the Property Palette.

4	Set the Alert Style property to the style that corresponds to the severity of your message: either Stop, Caution, or Note.

5	At runtime, an icon representing the style you select displays next to the message in the alert window.

6	Set the Message property by entering the message you want the alert to display at runtime.  You can enter up to 200 characters.

Note:  Not all runtime platforms can display the maximum number of characters.

7	Define one or more buttons for the alert by entering a text label in the Button 1 Label, Button 2 Label, and Button 3 Label fields.  (The default text labels are "OK" for Button 1 and "Cancel" for Button 2.)

Note:  At least one button must have a label.  Buttons that do not have labels are not displayed.  Buttons are displayed in the alert in the order that they appear in the Property Palette.  That is,  Button 2 is displayed to the right of Button 1, and so on.

8	Choose the Default Alert Button, either Button 1, Button 2, or Button 3.

The default button is the button that is selected implicitly when the operator presses [Accept].  On most window managers, the default button has a distinctive appearance.


Displaying an alert

 Examples   [image]  Related Topics

To display an alert, your application must execute the SHOW_ALERT built-in subprogram from a trigger or user-named subprogram.  SHOW_ALERT is a function that returns a numeric constant.

Show_Alert(alert_name) Return NUMBER;

The constant returned by the SHOW_ALERT function indicates which alert button the operator selected and is one of the following: ALERT_BUTTON1, ALERT_BUTTON2, ALERT_BUTTON3.

You can assign the return value of the SHOW_ALERT function to a variable, and then take different actions in your trigger depending on the value of that variable; that is, depending on which button the operator selected.


Displaying an alert examples

For example, you might create an alert that displays the following message:

"Product price must be entered. Show price list now?"

Button 1 is labeled OK and button 2 is labeled Cancel.  This alert is invoked from a When-Button-Pressed trigger attached to a button that calculates line-item totals for orders.

If the current price is entered for the item, the calculation executes successfully; if the price is missing, the alert displays.  The operator selects Button 1 (OK) to invoke a window that displays current product prices, or Button 2 (Cancel) to cancel the operation.

When-Button-Pressed Trigger:

-- Declare a NUMBER variable for the
-- constant returned by the Show_Alert function
DECLARE
   alert_button NUMBER;
BEGIN
   IF :item.price IS NOT NULL THEN
     -- call the user-named calculation subprogram
     calculate_totals;
   ELSE -- display the alert
     alert_button := Show_Alert('no_price_alert');
      IF alert_button = ALERT_BUTTON1 THEN
        -- invoke the price list window
        Go_Block('product_prices');
      END IF; -- do nothing if operator selects button 2
   END IF;
END;


Changing the alert message

 Examples   [image]  Related Topics

You can change an alert message at runtime by executing the SET_ALERT_PROPERTY built-in procedure.  Changing an alert's message allows you to reuse the same alert object, but display a different  message each time it is invoked.

For example, it is common to have several alerts in an application that all use the same two buttons (for example, OK and Cancel) but that display different messages depending on application context.

By programmatically changing an alert's message to fit the current context, you can save design overhead by reusing the same alert object instead of creating multiple alerts.  Changing the alert message also enables you to create dynamic alert messages that refer to specific objects or item values.


Changing the alert message examples

The following example changes the message of an alert named generic_alert.  This alert is informational only and has only one button, labeled "OK":

DECLARE
   alert_id   ALERT := Find_Alert('generic_alert');
   dummy_var  NUMBER;
BEGIN
   Set_Alert_Property(alert_id, ALERT_MESSAGE_TEXT, 'The product
     you selected is not in stock');
   -- now show the alert
   dummy_var := Show_Alert(alert_id);
END;

Notice that in this example, no action is taken when the operator selects a button.  This is because the alert is informational only, and has only one button (OK).  The return value of the SHOW_ALERT function is assigned to a dummy variable when the operator acknowledges the message, and processing continues normally.

Note also that the example uses the FIND_ALERT function to get the object ID for the alert named generic_alert. The ID is assigned to the variable alert_id.  The alert is then referenced by this ID in the subsequent procedure and function calls.


PL/SQL and Form Builder reserved words

The following table lists the reserved words defined in Form Builder and in PL/SQL.  PL/SQL reserved words appear with an asterisk (*).

_SELF

_PARENT

_TOP

_BLANK

ABORT*

ABORT_QUERY

ACCEPT*

ACCESS*

ACKNOWLEDGE

ACKNOWLEDGE_PREVIOUS

ACTIVATE

ADD*

ADD_GROUP_COLUMN

ADD_GROUP_ROW

ADD_LIST_ELEMENT

ADD_OLEARG

ADD_PARAMETER

ADJUST_TO_FIT

ALERT

ALERT_BUTTON1

ALERT_BUTTON2

ALERT_BUTTON3

ALERT_DEFAULT

ALERT_MESSAGE_TEXT

ALIGNMENT

ALL*

ALL_PARAMA

ALL_RECORDS

ALL_ROWS

ALTER*

ALTERABLE

ANCHOR_VIEW

AND*

ANY*

APPLICATION_CHARACTERISTIC

APPLICATION_INSTANCE

APPLICATION_MENU

APPLICATION_PARAMETER

ARRAY*

ARRAYLEN*

AS*

ASC*

ASK_COMMIT

ASSERT*

ASSIGN*

ASYNCHRONOUS

AT*

ATTR_OFF

ATTR_ON

AUTHORIZATION*

AUTOQUERY

AUTO_HELP

AUTO_HINT

AUTO_NAVIGATE

AUTO_REFRESH

AUTO_SKIP

AVG*

BACKGROUND_MENU1

BACKGROUND_MENU10

BACKGROUND_MENU2

BACKGROUND_MENU3

BACKGROUND_MENU4

BACKGROUND_MENU5

BACKGROUND_MENU6

BACKGROUND_MENU7

BACKGROUND_MENU8

BACKGROUND_MENU9

BALLOON_ATTRIBUTE

BALLOON_TEXT

BAR

BASE_TABLE*

BATCH

BEGIN*

BELL

BETWEEN*

BINARY_INTEGER*

BLOCK

BLOCK_CHARACTERISTIC

BLOCK_MENU

BLOCK_SCOPE

BODY*

BOOK

BOOK20

BOOLEAN*

BORDER_BEVEL

BREAK

BY*

CACHE

CALL

CALLING_FORM

CALLING_FORM_NAME

CALL_FORM

CALL_INPUT

CALL_OLE

CALL_OLE_CHAR

CALL_OLE_NUM

CALL_OLE_OBJ

CALL_OLE_VAR

CALL_QUERY

CANCEL_REPORT_OBJECT

CANVAS

CANVAS_SIZE

CASCADING

CASE*

CASE_INSENSITIVE_QUERY

CASE_RESTRICTION

CHANGED_STATUS

CHANGE_ALERT_MESSAGE

CHANGE_BLOCK

CHANGE_RECORD

CHAR*

CHARACTER_CELL_HEIGHT

CHARACTER_CELL_WIDTH

CHAR_BASE*

CHAR_COLUMN

CHECKBOX_CHECKED

CHECK*

CHECKED

CHECK_RECORD_UNIQUENESS

CLEAR_BLOCK

CLEAR_EOL

CLEAR_FIELD

CLEAR_FORM

CLEAR_ITEM

CLEAR_LIST

CLEAR_MESSAGE

CLEAR_RECORD

CLOSE*

CLOSE_AT_COMMIT

CLOSE_FORM

CLOSE_QUERY

CLUSTER*

CLUSTERS*

COLAUTH*

COLUMNS*

COLUMN_SECURITY

COMMIT*

COMMIT_FORM

COMPRESS*

COMPRESSION_OFF

COMPRESSION_ON

CONCEAL_DATA

CONNECT*

CONNECT_STRING

CONSTANT *

CONSTANTS

CONVERT_OTHER_VALUE

COORDINATED

COORDINATE_SYSTEM

COORDINATION_OPERATION

COORDINATION_STATUS

COPY

COPY_REGION

COPY_REPORT_OBJECT_OUTPUT

COPY_REPORT_OUTPUT

COUNT*

COUNT_QUERY

CRASH*

CREATE*

CREATE_GROUP

CREATE_GROUP_FROM_QUERY

CREATE_OLEOBJ

CREATE_PARAMETER_LIST

CREATE_QUERIED_RECORD

CREATE_RECORD

CREATE_TIMER

CREATE_VAR

CURRENT*

CURRENT_FORM

CURRENT_FORM_NAME

CURRENT_RECORD

CURRENT_RECORD_ATTRIBUTE

CURRVAL*

CURSOR*

CURSOR_MODE

CURSOR_STYLE

CUT_REGION

DATABASE*

DATA_BASE*

DATABASE_VALUE

DATASOURCE

DATATYPE

DATA_PARAMETER

DATE*

DATE_COLUMN

DB

DBA*

DBMS_ERROR_CODE

DBMS_ERROR_TEXT

DEBUGOFF*

DEBUGON*

DEBUG_MODE

DECIMAL*

DECLARE*

DEFAULT*

DEFAULT_SCOPE

DEFAULT_VALUE

DEFAULT_WHERE

DEFERRED_COORDINATION

DEFER_ON_VISIBILITY

DEFER_REQUIRED_ENFORCEMENT

DEFINITION*

DELAY*

DELAYED

DELETE*

DELETE_ALLOWED

DELETE_GROUP

DELETE_GROUP_ROW

DELETE_LIST_ELEMENT

DELETE_PARAMETER

DELETE_RECORD

DELETE_RECORDS

DELETE_SOURCE

DELETE_SOURCE_TYPE

DELETE_TIMER

DELTA*

DERIVED_COLUMN

DESC*

DESTROY_PARAMETER_LIST

DESTROY_VARIANT

DETAIL_NAME

DEVELOPER_NAMES

DIGITS*

DISABLED

DISABLE_ITEM

DISABLE_VALIDATION

DISPATCH_EVENT

DISPID_COLLECT

DISPID_CONSTRUCTOR

DISPID_DESTRUCTOR

DISPID_EVALUATE

DISPID_NEWENUM

DISPID_VALUE

DISPLAY

DISPLAYED

DISPLAY_ERROR

DISPLAY_FIELD

DISPLAY_HEIGHT

DISPLAY_ITEM

DISPLAY_LENGTH

DISPLAY_PAGE

DISPLAY_POSITION

DISPLAY_WIDTH

DISPLAY_X_POS

DISPLAY_Y_POS

DISPOSE*

DISTINCT*

DML_DATA_TARGET_NAME

DML_DATA_TARGET_TYPE

DOWN

DO*

DO_COMMIT

DO_KEY

DO_REPLACE

DROP*

DUMMY_REFERENCE

DUPLICATE_FIELD

DUPLICATE_ITEM

DUPLICATE_RECORD

ECHO

EDITOR

EDITOR_NAME

EDITOR_X_POS

EDITOR_Y_POS

EDIT_FIELD

EDIT_TEXTITEM

ELSE*

ELSIF*

ENABLED

ENABLE_ITEM

ENABLE_VALIDATION

END*

END_EDGE

END_OF_GROUP

ENFORCE_COLUMN_SECURITY

ENFORCE_KEY

ENTER

ENTERABLE

ENTER_QUERY

ENTRY*

ERASE

ERROR

ERROR_CODE

ERROR_NOTIFICATION

ERROR_TEXT

ERROR_TYPE

EXCEPTION*

EXCEPTION_INIT*

EXECUTE_QUERY

EXECUTE_TRIGGER

EXISTS*

EXIT*

EXIT_FORM

EXIT_MENU

FALSE*

FETCH*

FETCH_RECORDS

FIELD_CHARACTERISTIC

FIELD_LENGTH

FILE

FILESYSTEM

FILE_NAME

FIND_ALERT

FIND_BLOCK

FIND_CANVAS

FIND_COLUMN

FIND_EDITOR

FIND_FORM

FIND_GROUP

FIND_ITEM

FIND_LOV

FIND_MENU

FIND_MENU_ITEM

FIND_RELATION

FIND_REPORT_OBJECT

FIND_TAB_PAGE

FIND_TIMER

FIND_VIEW

FIND_WINDOW

FIRSTBLOCK

FIRSTFIELD

FIRST_BLOCK

FIRST_DETAIL_RELATION

FIRST_FIELD

FIRST_ITEM

FIRST_MASTER_RELATION

FIRST_NAVIGATION_BLOCK

FIRST_RECORD

FIRST_RELATION

FIXED_LENGTH

FLOAT*

FOR*

FORM*

FORMATTED_VALUE

FORMAT_MASK

FORMMODULE

FORMS

FORMS40

FORMS4C

FORMS4G

FORMS4W

FORMS_DDL

FORMS_OLE

FORM_CHARACTERISTIC

FORM_FAILURE

FORM_FATAL

FORM_NAME

FORM_OLE_FAILURE

FORM_SCOPE

FORM_SUCCESS

FOR_UPDATE

FROM*

FULL_ROLLBACK

FULL_SCREEN

FUNCTION*

GENERAL_EXCEPTION

GENERATE_SEQUENCE_NUMBER

GENERIC*

GET_APPLICATION_PROPERTY

GET_BLOCK_PROPERTY

GET_CANVAS_PROPERTY

GET_FILE_NAME

GET_FORM_PROPERTY

GET_GROUP_CHAR_CELL

GET_GROUP_DATE_CELL

GET_GROUP_NUMBER_CELL

GET_GROUP_ROW_COUNT

GET_GROUP_SELECTION

GET_GROUP_SELECTION_COUNT

GET_ITEM_INSTANCE_PROPERTY

GET_ITEM_PROPERTY

GET_LIST_ELEMENT_COUNT

GET_LIST_ELEMENT_LABEL

GET_LIST_ELEMENT_VALUE

GET_LOV_PROPERTY

GET_MENU_ITEM_PROPERTY

GET_MESSAGE

GET_OLEARG_CHAR

GET_OLEARG_NUM

GET_OLEARG_OBJ

GET_OLEARG_VAR

GET_OLE_CHAR

GET_OLE_MEMBERID

GET_OLE_NUM

GET_OLE_OBJ

GET_OLE_VAR

GET_PARAMETER_ATTR

GET_PARAMETER_LIST

GET_RADIO_BUTTON_PROPERTY

GET_RECORD_PROPERTY

GET_RELATION_PROPERTY

GET_REPORT_OBJECT_PROPERTY

GET_TAB_PAGE_PROPERTY

GET_VAR_BOUNDS

GET_VAR_DIMS

GET_VAR_TYPE

GET_VIEW_PROPERTY

GET_WINDOW_PROPERTY

GLOBAL_EVENT

GLOBAL_SCOPE

GOTO*

GO_BLOCK

GO_FIELD

GO_FORM

GO_ITEM

GO_RECORD

GRANT*

GRAPHICS

GRAYSCALE

GROUP*

GROUPCOLUMN

GROUP_NAME

HAVING*

HEIGHT

HELP

HIDDEN

HIDE

HIDE_MENU

HIDE_ON_EXIT

HIDE_PAGE

HIDE_VIEW

HIDE_WINDOW

HIGH_COMPRESSION

HIGHEST_SOUND_QUALITY

HIGH_SOUND_QUALITY

HINT_TEXT

HOLDER

HOST

ICONIC_BUTTON

ICON_NAME

IDENTIFIED*

IDENTIFIER

ID_NULL

IF*

IMAGE_ADD

IMAGE_AND

IMAGE_SCROLL

IMAGE_SUBTRACT

IMAGE_XOR

IMAGE_ZOOM

IMMEDIATE

IN*

INDEX*

INDEXES*

INDICATOR*

INITIAL_VALUE

INIT_OLEARGS

INSERT*

INSERT_ALLOWED

INSERT_RECORD

INSERT_RECORDS

INSERT_SOURCE

INSERT_SOURCE_TYPE

INSERT_STATUS

INTEGER*

INTERACTION_MODE

INTERSECT*

INTO*

INVALID_ARGUMENT

INVALID_TIMER_INTERVAL

IS*

ISNULL

ISOLATED

ISOLATION_MODE

ISSUE_ROLLBACK

ISSUE_SAVEPOINT

ITEM

ITEM_CANVAS

ITEM_DEFAULT_VALUE

ITEM_ENABLED

ITEM_IS_VALID

ITEM_LENGTH

ITEM_NAME

ITEM_SCOPE

ITEMS_IN_BLOCK

ITEM_SIZE

ITEM_TAB_PAGE

ITEM_TYPE

KEEP_POSITION

KEY_MODE

LABEL

LASTBLOCK

LASTFIELD

LAST_BLOCK

LAST_FIELD

LAST_ITEM

LAST_OLE_ERROR

LAST_OLE_EXCEPTION

LAST_QUERY

LAST_RECORD

LEVEL*

LIKE*

LIMITED*

LIST

LIST_VALUES

LOCATION

LOCKING_MODE

LOCK_RECORD

LOCK_RECORDS

LOCK_RECORD_ON_CHANGE

LOGON

LOGON_SCREEN

LOGOUT

LONG_COLUMN

LOOP*

LOV

LOV_NAME

LOV_SIZE

LOV_VALIDATION

LOV_X_POS

LOV_Y_POS

LOW_COMPRESSION

LOWEST_SOUND_QUALITY

LOW_SOUND_QUALITY

LOWERCASE

LOWERED

LUT

MACRO

MAIL

MAIN_MENU

MASTER_DELETES

MASTER_NAME

MAX*

MAXIMIZE

MAXIMIZE_COMPRESSION

MAX_LENGTH

MAX_QUERY_TIME

MAX_RECORDS_FETCHED

MEDIUM_COMPRESSION

MEDIUM_SOUND_QUALITY

MENU

MENUITEM

MENU_CLEAR_FIELD

MENU_FAILURE

MENU_HELP

MENU_MESSAGE

MENU_NEXT_FIELD

MENU_PARAMETER

MENU_PREVIOUS_FIELD

MENU_REDISPLAY

MENU_SHOW_KEYS

MENU_SUCCESS

MESSAGE

MESSAGE_CODE

MESSAGE_TEXT

MESSAGE_TYPE

MIN*

MINIMIZE

MINIMIZE_COMPRESSION

MINUS*

MLSLABEL*

MNEMONIC

MOD*

MODE

MODULE_NLS_CHARACTER_SET

MODULE_NLS_LANG

MODULE_NLS_LANGUAGE

MODULE_NLS_TERRITORY

MONOCHROME

MONOPHONIC

MOUSE_NAVIGABLE

MOUSE_NAVIGATE

MOVE_VIEW

MOVE_WINDOW

MULTI_LINE

MYTYPE

NAME_IN

NATURAL*

NAVIGABLE

NAVIGATION_STYLE

NEW*

NEW_APPLICATION

NEW_FORM

NEW_STATUS

NEW_USER

NEXTBLOCK

NEXTFIELD

NEXTITEM

NEXTVAL*

NEXT_BLOCK

NEXT_DETAIL_RELATION

NEXT_FIELD

NEXT_FORM

NEXT_ITEM

NEXT_KEY

NEXT_MASTER_RELATION

NEXT_MENU_ITEM

NEXT_NAVIGATION_BLOCK

NEXT_NAVIGATION_ITEM

NEXT_RECORD

NEXT_RELATION

NEXT_SET

NOCOMPRESS*

NO_COMPRESSION

NONE

NONE_PARAMA

NON_COORDINATED

NON_ISOLATED

NON_UPDATEABLE_PRIMARY_KEY

NORMAL

NO_SHARE_LIBRARY_DATA

NOT*

NO_ACKNOWLEDGE

NO_ACKNOWLEDGE_PREVIOUS

NO_ACTIVATE

NO_CHANGE

NO_COMMIT

NO_EXCEPTION

NO_HIDE

NO_OPERATION

NO_PROMPT

NO_QUERY_ONLY

NO_REMOVE_LIST

NO_REPEAT

NO_REPLACE

NO_RESTRICT

NO_ROLLBACK

NO_SCREEN

NO_SESSION

NO_SUCH_TIMER

NO_VALIDATE

NO_WAIT

NULL*

NULL_COMMAND

NUMBER*

NUMBER_BASE*

NUMBER_COLUMN

OF*

OHOST

OLEOBJ

OLEVAR

OLEVAR_NULL

OLE_SAFEARRAYBOUND

OLE_SAFEARRAYBOUNDS

OLE2_CLASSNAME

OLE2_FILENAME

ON*

OPEN*

OPEN_AT_COMMIT

OPEN_FILE

OPEN_FORM

OPERATING_SYSTEM

OPTIMIZER_HINT

OPTION*

OR*

ORDER*

ORDER_BY

ORIGINAL_DEPTH

ORIGINAL_QUALITY

ORIGINAL_SETTING

OS_COMMAND

OS_COMMAND1

OTHERS*

OUT *

PACKAGE*

PAGE

PARAMLIST

PARAMTYPE_PARAMA

PARAM_ATTR

PARTITION*

PASSWORD

PASTE_REGION

PAUSE

PCTFREE*

PECS

PLAY_SOUND

PLITBLM

PLSQL_TABLE

POPULATE_BLOCK

POPULATE_GROUP

POPULATE_GROUP_WITH_QUERY

POPULATE_LIST

POPULATE_TABLE

POPUPMENU_COPY_ITEM

POPUPMENU_CUT_ITEM

POPUPMENU_DELOBJ_ITEM

POPUPMENU_INSOBJ_ITEM

POPUPMENU_LINKS_ITEM

POPUPMENU_OBJECT_ITEM

POPUPMENU_PASTESPEC_ITEM

POPUPMENU_PASTE_ITEM

POSITION

POSITION_ON_CANVAS

POSITIVE*

POST

PRAGMA*

PREVENT_MASTERLESS_OPERATION

PREVIEW

PREVIOUSBLOCK

PREVIOUSFIELD

PREVIOUSITEM

PREVIOUS_BLOCK

PREVIOUS_FIELD

PREVIOUS_FORM

PREVIOUS_ITEM

PREVIOUS_MENU

PREVIOUS_MENU_ITEM

PREVIOUS_NAVIGATION_BLOCK

PREVIOUS_NAVIGATION_ITEM

PREVIOUS_RECORD

PRIMARY_KEY

PRINT

PRINTER

PRIOR*

PRIVATE*

PROCEDURE*

PROCEDURE_SOURCE

PROMPT_ALIGNMENT_OFFSET

PROMPT_ALL_RECORDS

PROMPT_DISPLAY_STYLE

PROMPT_EDGE

PROMPT_EDGE_ALIGNMENT

PROMPT_EDGE_OFFSET

PROMPT_FIRST_RECORD

PROMPT_HIDDEN

PROMPT_TEXT

PROMPT_TEXT_ALIGNMENT

PROMPT_VISUAL_ATTRIBUTE

PROPERTY_FALSE

PROPERTY_OFF

PROPERTY_ON

PROPERTY_TRUE

PTR_TO_VAR

PUBLIC *

PULL_DOWN

QUERYABLE

QUERY_ALLOWED

QUERY_DATA_SOURCE_NAME

QUERY_DATA_SOURCE_TYPE

QUERY_HITS

QUERY_LENGTH

QUERY_ONLY

QUERY_OPTIONS

QUERY_PARAMETER

QUERY_SOURCE

QUERY_SOURCE_TYPE

QUERY_STATUS

RAISE*

RAISED

RANGE*

RANGE_HIGH

RANGE_LOW

READ_IMAGE_FILE

READ_SOUND_FILE

REAL*

RECALCULATE

RECORD*

RECORDGROUP

RECORDS_DISPLAYED

RECORDS_TO_FETCH

RECORD_SCOPE

REDISPLAY

RELATION

RELEASE*

RELEASE_OBJ

REM*

REMOVE_LIST

REMOVE_ON_EXIT

RENAME*

REPEAT

REPLACE_CONTENT_VIEW

REPLACE_MENU

REPORT_COMM_MODE

REPORT_DESFORMAT

REPORT_DESNAME

REPORT_DESTYPE

REPORT_EXECUTION_MODE

REPORT_FILENAME

REPORT_OBJECT

REPORT_OBJECT_STATUS

REPORT_OTHER

REPORT_QUERY_NAME

REPORTS

REPORT_SERVER

REPORT_SOURCE_BLOCK

REQUIRED

RESET_GROUP_SELECTION

RESIZE_VIEW

RESIZE_WINDOW

RESOURCE*

RESTRICT

RESTRICTED

RESTRICTED_ALLOWED

RESTRICTED_FORBIDDEN

RETRIEVE_LIST

RETURN*

REVERSE*

REVOKE*

ROLLBACK*

ROLLBACK_FORM

ROLLBACK_NR

ROLLBACK_RL

ROLLBACK_SV

ROWID*

ROWLABEL*

ROWNUM*

ROWTYPE*

RUN*

RUN_PRODUCT

RUN_REPORT_OBJECT

RUNTIME

SAME_RECORD

SAVE_FILE

SAVEPOINT*

SAVEPOINT_MODE

SAVEPOINT_NAME

SCHEMA*

SCREEN

SCROLLBAR

SCROLL_DOWN

SCROLL_UP

SCROLL_VIEW

SECURE

SELECT*

SELECTION_RECTANGLE

SELECT_ALL

SELECT_RECORDS

SEPARATE*

SESSION

SET*

SET_ALERT_PROPERTY

SET_APPLICATION_PROPERTY

SET_BLOCK_PROPERTY

SET_CANVAS_PROPERTY

SET_FIELD

SET_FORM_PROPERTY

SET_GROUP_CHAR_CELL

SET_GROUP_DATE_CELL

SET_GROUP_NUMBER_CELL

SET_GROUP_SELECTION

SET_INPUT_FOCUS

SET_ITEM_INSTANCE_PROPERTY

SET_ITEM_PROPERTY

SET_LOV_PROPERTY

SET_MENU_ITEM_PROPERTY

SET_OLE

SET_PARAMETER_ATTR

SET_RADIO_BUTTON_PROPERTY

SET_RECORD_PROPERTY

SET_RELATION_PROPERTY

SET_REPORT_OBJECT_PROPERTY

SET_TAB_PAGE_PROPERTY

SET_TIMER

SET_VAR

SET_VIEW_PROPERTY

SET_WINDOW_PROPERTY

SHOWN

SHOW_ALERT

SHOW_BACKGROUND_MENU

SHOW_DOCUMENT

SHOW_EDITOR

SHOW_FAST_FORWARD_BUTTON

SHOW_KEYS

SHOW_LOV

SHOW_MENU

SHOW_PAGE

SHOW_PALETTE

SHOW_PLAY_BUTTON

SHOW_POPUPMENU

SHOW_RECORD_BUTTON

SHOW_REWIND_BUTTON

SHOW_SLIDER

SHOW_TIME_INDICATOR

SHOW_VIEW

SHOW_VOLUME_CONTROL

SHOW_WINDOW

SIZE*

SMALLINT*

SPACE*

SPECIFIC_EXCEPTION

SQL*

SQLCODE*

SQLERRM*

SQLFORMS

SQLMENU

STACKED

START*

START_EDGE

STATUS

STATEMENT*

STDDEV*

STEREOPHONIC

SUBTYPE*

SUM*

SYNCHRONIZE

SYNCHRONOUS

TABAUTH*

TABLE*

TABLE_FROM_BLOCK

TABLES*

TABLE_SOURCE

TAB_PAGE

TAB_PAGE_X_OFFSET

TAB_PAGE_Y_OFFSET

TAB_PLACEMENT

TASK*

TERMINATE*

TEXT_PARAMETER

THEN*

TIMER

TIMER_EXISTS

TIMER_NAME

TITLE

TO*

TOOLS

TOOLTIP_ATTRIBUTE

TOOLTIP_TEXT

TOP_EDGE

TOPMOST_TAB_PAGE

TOP_RECORD

TO_SAVEPOINT

TO_VARIANT

TRUE*

TYPE*

UNFORMATTED_VALUE

UNION*

UNIQUE*

UNIQUE_KEY

UNRESTRICTED

UNSET_GROUP_SELECTION

UP

UPDATE*

UPDATEABLE

UPDATEABLE_PRIMARY_KEY

UPDATE_ALLOWED

UPDATE_CHANGED_COLUMNS

UPDATE_CHART

UPDATE_COLUMN

UPDATE_NULL

UPDATE_PERMISSION

UPDATE_RECORD

UPDATE_RECORDS

UPDATE_SOURCE

UPDATE_SOURCE_TYPE

UPPERCASE

UPPER_CASE

USE*

USERNAME

USER_EXIT

USER_INTERFACE

USER_NLS_CHARACTER_SET

USER_NLS_LANG

USER_NLS_LANGUAGE

USER_NLS_TERRITORY

VALIDATE

VALIDATE_FROM_LIST

VALIDATION

VALIDATION_UNIT

VALUE

VALUES*

VALUE_PARAMA

VARCHAR*

VARCHAR2*

VARIANCE*

VARPTR_TO_VAR

VAR_TO_CHAR

VAR_TO_NUMBER

VAR_TO_OBJ

VAR_TO_TABLE

VAR_TO_VARPTR

VBX

VERSION

VIEW*

VIEWS*

VIEWPORT

VIEWPORT_X_POS

VIEWPORT_X_POS_ON_CANVAS

VIEWPORT_Y_POS

VIEWPORT_Y_POS_ON_CANVAS

VIEW_SIZE

VISIBLE

VISUAL_ATTRIBUTE

VT_BLOB

VT_BLOB_OBJECT

VT_BOOL

VT_BSTR

VT_BYREF

VT_CARRAY

VT_CF

VT_CLSID

VT_CY

VT_DATE

VT_DISPATCH

VT_EMPTY

VT_ERROR

VT_FILETIME

VT_HRESULT

VT_I1

VT_I2

VT_I4

VT_I8

VT_INT

VT_LPSTR

VT_LPWSTR

VT_NULL

VT_PTR

VT_R4

VT_R8

VT_SAFEARRAY

VT_STORAGE

VT_STORED_OBJECT

VT_STREAM

VT_STREAMED_OBJECT

VT_TYPE

VT_UI1

VT_UI2

VT_UI4

VT_UI8

VT_UINT

VT_UNKNOWN

VT_USERDEFINED

VT_VARIANT

VT_VOID

WHEN*

WHERE*

WHERE_DISPLAY

WHILE*

WIDTH

WINDOW

WINDOW_HANDLE

WINDOW_NAME

WINDOW_SIZE

WINDOW_STATE

WITH*

WORK*

WRAP_STYLE

WRITE_IMAGE_FILE

XOR*

X_POS

X_POS_ON_CANVAS

YES

Y_POS

Y_POS_ON_CANVAS

ZOOM_IN_FACTOR

ZOOM_OUT_FACTOR

ZOOM_PERCENT


About the AppletViewer

  Related Topics

The AppletViewer is an Oracle Developer component that client machines use to view applications running on the Forms Server.  The AppletViewer is a supported product--upgraded versions are available for download from the Oracle Developer web site.

When running your application in the AppletViewer, requests to show a URL - i.e. web.showDocument and RUN_PRODUCT - will be ignored by the AppletViewer.  In this case, you will need to follow the process to "trust" the Forms applet.

Note: The AppletViewer is only supported on Windows 95 and Windows NT 4.0.


Installing the AppletViewer

  Next Step	  Related Topics

To install the AppletViewer:

1	Use the Oracle Installer to install the JDK AppletViewer:

•	Shut down any active Windows applications.

•	From the Taskbar, choose Start [image] Run.

•	In the Run dialog, type the following (where D: is your CD-ROM drive letter): D:\setup.exe and click OK.

•	In the Language dialog, select a language and click OK.

•	In the Oracle Installation Settings dialog, check the default values for your company name and your ORACLE_HOME directory.  Accept or modify the values and click OK.

•	Click the Custom Installation or Removal radio button and click OK.

•	From the list of Available Products, select JDK AppletViewer.

•	Click Install.

2	From the Taskbar, choose Start [image] Programs [image] Oracle Developer [image] Install JDK AppletViewer.

3	In the Unzip to Folder field, type \ORACLE_HOME\JDK1.1 as the directory to unpack the files.  For example:  C:\ORANT\JDK1.1

4	Click Unzip.

5	Copy the file JDK_SETUP.BAT from \ORACLE_HOME\FORMS60\JAVA into your ORACLE_HOME directory (C:\ORANT, for example).

6	Modify the JDK_SETUP.BAT in your ORACLE_HOME directory:

  Open JDK_SETUP.BAT in a text editor.

  Modify the CLASSPATH and PATH environment variables to specify the
   ORACLE_HOME directory for your installation.  For example:

SET CLASSPATH=C:\ORANT\JDK1.1\JDK\LIB\CLASSES.ZIP
PATH C:\ORANT\JDK1.1\JDK\BIN;%PATH%

  Save your changes to JDK_SETUP.BAT.


Running the AppletViewer

  Next Step	  Related Topics

To run the AppletViewer:

1	Run JDK_SETUP.BAT:

•	Open a DOS Command Prompt and navigate to your ORACLE_HOME directory.

•	Type JDK_SETUP.BAT and press the Enter or Return key.

2	In the same DOS Command Prompt window, navigate to the AppletViewer executable (appletviewer.exe).  For example:  C:\ORANT\JDK1.1\JDK\BIN\.

3	Run the AppletViewer excutable, specifying the host name, HTML file virtual directory, and HTML file.  For example type:

appletviewer http://myhost.com/web_html/start.html

Note: If you are using a cartridge implementation, enclose the HTTP request in quotation marks.

4	Press the Enter or Return key.


Invoking a Web browser from within the AppletViewer

  Next Step	  Related Topics

To invoke a Web browser from within the AppletViewer:

1	"Trust" the Forms using one of two methods:

•	Register the Forms applet signature.

•	Install the Forms Java class files locally.

2	Add the clientBrowser parameter to your base HTML file.


About Trusting

  Related Topics

To use the clientBrowser parameter, you must have security permissions to issue a system call that "executes" the named application. In general, when loading Java class files, the Forms applet is not "trusted" and, as such, cannot issue such system calls.  However, when the Forms applet is "trusted," it is able to issue these calls. The Forms applet is considered "trusted" when one of the following is true:

•	The Forms applet signature is "registered" on the client machine, or

•	The Forms Java class files are installed locally on the client system and the CLASSPATH environment variable is set.


About Registering the Forms Applet Signature

  Related Topics

A signature allows client machines to verify that a file has been downloaded from a valid and trusted entity (a "signer") and thus protect themselves from malicious or malfunctioning Java archive (JAR) files.  In order for a JAR file to be validated by a client, the signature of that file must be registered on the client machine.  Javakey is a Sun Microsystems command-line tool that generates digital signatures for JAR files.

The Forms applet is itself a signed JAR file.  You have two options of registering the Forms applet signature:

•	Register the signature on your client machine(s) using the Forms applet signature we provide, or

•	Re-sign the Forms applet with your own signature and register that signature on your client machine(s).  If you choose this method, please refer to http://java.sun.com/security/usingJavakey.html for instructions on creating and signing JAR files.


Trusting the Forms Applet by Registering its Signature

  Next Step	  Related Topics

To trust the Forms applet by registering its signature:

1	Copy the Oracle Developer certificate to \ORACLE_HOME\FORMS60\JAVA on the client machine.

The certificate is a file named Dev2K.x509.  It is located in \ORACLE_HOME\FORMS60\JAVA on the server.

2	Open a DOS Command Prompt and navigate to \ORACLE_HOME\FORMS60\JAVA.

3	Type javakey -c Developer/2000 true

This command creates a trusted identity for the AppletViewer on the client's identity database using the exact name of the certificate provider.

javakey -c Developer/2000 true

4	Press the Enter or Return key.

5	Type javakey -ic Developer/2000 Dev2K.x509

This command imports the Dev2K.x509 certificate into the client's JDK identity database and associates the certificate with the trusted identity created in Step 3.

6	Press the Enter or Return key.


Trusting the Forms Applet by Installing the Forms Java Class Files Locally

  Next Step	  Related Topics

To trust the Forms applet by installing the Java class files locally:

1	Copy the \ORACLE_HOME\FORMS60\JAVA directory to a new directory on the client machine.

Note:  Copy this directory exactly; do not change the directory structure in any way.

2	Modify JDK_SETUP.BAT in your ORACLE_HOME directory:

•	Open JDK_SETUP.BAT in a text editor.

•	Modify the CLASSPATH environment variable to reference the new directory.

•	Save your changes to JDK_SETUP.BAT.


Adding the clientBrowser Parameter to Your Base HTML File

  Related Topics

To set the clientBrowser parameter, you have two options:

•	Add the clientBrowser parameter to your HTML file and have each client modify their JDK_SETUP.BAT file.  This option is best if there is a possibility that clients have installed their browser executables into different physical directories.  It does assume, however, that all clients are using the same browser.  For example the HTML file might look like this:

<APPLET CODEBASE="/web_code/"
CODE="oracle.forms.engine.Main"
ARCHIVE="/web_code/f60all.jar"
HEIGHT=20
WIDTH=20>
<PARAM NAME="serverArgs" VALUE="module=start.fmx userid=scott/tiger">
<PARAM NAME="clientBrowser" VALUE="netscape">
</APPLET>

And JDK_SETUP.BAT would look like this:

SET CLASSPATH=C:\ORANT\JDK1.1\JDK\LIB\CLASSES.ZIP
PATH C:\PROGRAM FILES\NETSCAPE\COMMUNICATOR\PROGRAM;
C:\ORANT\JDK1.1\JDK\BIN;%PATH%

•	Add the clientBrowser parameter to your HTML file.  This option assumes that every client has its browser executable installed into the same physical directory since the physical path of the browser is hardcoded in the HTML file. For example:

<APPLET CODEBASE="/web_code/"
CODE="oracle.forms.engine.Main"
ARCHIVE="/web_code/f60all.jar"
HEIGHT=20
WIDTH=20>
<PARAM NAME="serverArgs"
VALUE="module=start.fmx userid=scott/tiger">
<PARAM NAME="clientBrowser"
VALUE="c:\program files\netscape\communicator\program\netscape.exe">
<APPLET>

Note:  These HTML file examples assume that you trusted the Forms applet by registering its signature on your machine.  If you instead trusted the Forms applet by locally installing the Forms Java class files, you should not download the F60ALL.JAR file.  Therefore, remove the ARCHIVE="/.../f60all.jar" applet tag from your HTML file.


http://www.oracle.com/products/tools/dev2k/index.html


appletviewer “http://myhost.com/web_html/start.html”


About array processing

  Related Topics

Array processing is an option in Form Builder that alters the way records are processed.  The default behavior of Form Builder is to process records one at a time.  By enabling array processing, you can process groups of records at a time, reducing network traffic and thereby increasing performance.  With array processing, a structure (array) containing multiple records is sent to or returned from the server for processing.  Form builder supports both array fetch processing and array DML processing.  For both querying and DML operations, you can determine the array size to optimize performance for your needs.

Array processing is available for query and DML operations for blocks based on tables, views, procedures, and sub-queries; it is not supported for blocks based on transactional triggers.


About trigger processing during array DML processing

  Related Topics

All Pre-triggers fire prior to the execution of DML operations on the array of records; all Post-triggers fire after the execution of DML operations on the array of records.  For example, a Pre-Insert trigger and Post-Insert trigger exist for an item, and the DML Array Size property is 10.  If there are 25 records waiting to be processed, all 25 Pre-Insert triggers fire first.   An array of 10 records is inserted.  A second array of 10 records is inserted, and a third array containing the remaining 5 records is inserted.  Finally, all 25 Post-Insert triggers fire.

Array DML processing is disabled whenever the On-Insert, On-Update, or On-Delete trigger is present, because the On-triggers  remove default processing, including the array processing feature.


Enabling array processing for queries

  Related Topics

To enable array processing for a queries:

1	Choose Tools [image] Preferences…

2	Click the Runtime tab.

3	Check the Array Processing check box.

4	Click OK.

5	In the Object Navigator, click the Block object icon [image].

6	Double-click the Block object icon [image] to display the Property Palette.

7	Under the Records node, set the Query Array Size property to a number that represents the number of records in the array for array processing.


Enabling array processing for DML

  Related Topics

To enable array processing for DML:

1	Choose Tools [image] Preferences....

2	Click the Runtime tab.

3	Check the Array Processing check box.

4	In the Object Navigator, click the Block object icon [image].

5	Double-click the Block object icon [image] to display the Property Palette.

6	Under the Advanced Database node, set the DML Array Size property to a number that represents the number of records in the array for array processing.


DBMS_ERROR_CODE built-in

 Examples	  Related Topics	 All Built-ins

Description

Returns the error number of the last database error that was detected.

Syntax

FUNCTION DBMS_ERROR_CODE;

Built-in Type   unrestricted function

Enter Query Mode  yes

Parameters

none

Usage Notes

For recursive errors, this built-in returns the code of the first message in the stack, so the error text must be parsed for numbers of subsequent messages.


DBMS_ERROR_CODE examples

/*

** Built-in:  DBMS_ERROR_CODE,DBMS_ERROR_TEXT
** Example:   Reword certain Form Builder error messages by
**            evaluating the DBMS error code that caused them
** Trigger:   On-Error
*/
DECLARE
  errcode     NUMBER        := ERROR_CODE;
  dbmserrcode NUMBER;
  dbmserrtext VARCHAR2(200);
BEGIN
  IF errcode = 40508 THEN
    /*
    ** Form Builder had a problem INSERTing, so
    ** look at the Database error which
    ** caused the problem.
    */
    dbmserrcode := DBMS_ERROR_CODE;
    dbmserrtext := DBMS_ERROR_TEXT;

    IF dbmserrcode = -1438 THEN
      /*
      ** ORA-01438 is "value too large for column"
      */
      Message('Your number is too large. Try again.');
    ELSIF dbmserrcode = -1400 THEN
      /*
      ** ORA-01400 is "Mandatory column is NULL"
      */
      Message('You forgot to provide a value. Try again.');
    ELSE
      /*
      ** Printout a generic message with the database
      ** error string in it.
      */
      Message('Insert failed because of '||dbmserrtext);
    END IF;
  END IF;
END;


DBMS_ERROR_TEXT built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the message number (such as ORA-01438) and message text of the database error.

Syntax

FUNCTION DBMS_ERROR_TEXT;

Built-in Type   unrestricted function

Enter Query Mode  yes

Parameters

none

Usage Notes

You can use this function to test database error messages during exception handling routines.

DBMS_ERROR_TEXT returns the entire sequence of recursive errors.


DBMS_ERROR_TEXT examples

/*

** Built-in:  DBMS_ERROR_CODE,DBMS_ERROR_TEXT
** Example:   Reword certain Form Builder error messages by
**            evaluating the DBMS error code that caused them
** Trigger:   On-Error
*/
DECLARE
  errcode     NUMBER        := ERROR_CODE;
  dbmserrcode NUMBER;
  dbmserrtext VARCHAR2(200);
BEGIN
  IF errcode = 40508 THEN
    /*
    ** Form Builder had a problem INSERTing, so
    ** look at the Database error which
    ** caused the problem.
    */
    dbmserrcode := DBMS_ERROR_CODE;
    dbmserrtext := DBMS_ERROR_TEXT;

    IF dbmserrcode = -1438 THEN
      /*
      ** ORA-01438 is "value too large for column"
      */
      Message('Your number is too large. Try again.');
    ELSIF dbmserrcode = -1400 THEN
      /*
      ** ORA-01400 is "Mandatory column is NULL"
      */
      Message('You forgot to provide a value. Try again.');
    ELSE
      /*
      ** Printout a generic message with the database
      ** error string in it.
      */
      Message('Insert failed because of '||dbmserrtext);
    END IF;
  END IF;
END;


DEBUG_MODE built-in

 Restrictions	 All Built-ins

Description

Toggles debug mode on and off in a menu. When debug mode is on in a menu, Form Builder issues an appropriate message when a menu item command executes.

Syntax

PROCEDURE DEBUG_MODE;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


DEBUG_MODE restrictions

The DEBUG_MODE applies only to a menu module.  It does not place the form in Debug Mode.


DEFAULT_VALUE built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Copies an indicated value to an indicated variable if the variable's current value is NULL.  If the variable's current value is not NULL, DEFAULT_VALUE does nothing. Therefore, for text items this built-in works identically to using the COPY built-in on a NULL item.  If the variable is an undefined global variable, Form Builder creates the variable.

Syntax

PROCEDURE DEFAULT_VALUE
  (value_string  VARCHAR2,
   variable_name  VARCHAR2);

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

value_string	A valid VARCHAR2 string, variable, or text item containing a valid string.

variable_name	A valid variable, global variable, or text item name.  The data type of the variable_name is VARCHAR2.  Any object passed as an argument to this built-in must be enclosed in single quotes.


DEFAULT_VALUE restrictions

The DEFAULT_VALUE built-in is not related to the Initial Value item property.


DEFAULT_VALUE examples

/*

** Built-in:  DEFAULT_VALUE
** Example:   Make sure a Global variable is defined by
**           assigning some value to it with Default_Value
*/
BEGIN
  /*
  ** Default the value of GLOBAL.Command_Indicator if it is
  ** NULL or does not exist.
  */
  Default_Value('***','global.command_indicator');
  /*
  ** If the global variable equals the string we defaulted
  ** it to above, then it must have not existed before
  */
  IF :Global.Command_Indicator = '***' THEN
    Message('You must call this screen from the Main Menu');
    RAISE Form_Trigger_Failure;
  END IF;
END;


DELETE_GROUP built-in

  Examples	    Restrictions	  All Built-ins

Description

Deletes a programmatically created record group.

Syntax

PROCEDURE DELETE_GROUP
  (recordgroup_id  RecordGroup);

PROCEDURE DELETE_GROUP
  (recordgroup_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

recordgroup_id	The unique ID that Form Builder assigns when it creates the group.  The data type of the ID is RecordGroup.

recordgroup_name	The name you gave to the record group when creating it.  The data type of the name is VARCHAR2.


DELETE_GROUP restrictions

This built-in cannot be used to delete a record group that was created at design time.


DELETE_GROUP examples

/*

** Built-in:  DELETE_GROUP
** Example:   Delete a programmatically created record group
*/
PROCEDURE Remove_Record_Group( rg_name VARCHAR2 ) IS
  rg_id RecordGroup;
BEGIN
  /*
  ** Make sure the Record Group exists before trying to
  ** delete it.
  */
  rg_id := Find_Group( rg_name );
  IF NOT Id_Null(rg_id) THEN
    Delete_Group( rg_id );
  END IF;
END;


DELETE_GROUP_ROW built-in

  Examples	    Restrictions	  All Built-ins

Description

Deletes the indicated row or all rows of the given record group.  Form Builder automatically decrements the row numbers of all rows that follow a deleted row.  When rows are deleted, the appropriate memory is freed and available to Form Builder.

If you choose to delete all rows of the group by supplying the  ALL_ROWS constant, Form Builder deletes the rows, but the group still exists until you perform the DELETE_GROUP subprogram.

When a single row is deleted, subsequent rows are renumbered so that row numbers remain contiguous.

Syntax

PROCEDURE DELETE_GROUP_ROW
  (recordgroup_id  RecordGroup,
   row_number      NUMBER);

PROCEDURE DELETE_GROUP_ROW
  (recordgroup_name  VARCHAR2,
   row_number        NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

recordgroup_id	The unique ID that Form Builder assigns the group when it creates it.  The data type of the ID is RecordGroup.

recordgroup_name	The name you gave to the record group when you created it.  The data type of the name is VARCHAR2.

row_number	Specifies the row to be deleted from the record group.  Rows are automatically numbered from 1 to n.  Row number parameter data type is NUMBER.

ALL_ROWS  Specifies that Form Builder is to delete all rows without deleting the record group.  ALL_ROWS is a constant.


DELETE_GROUP_ROW restrictions

This built-in cannot be used to delete rows from a static record group.


DELETE_GROUP_ROW examples

/*

** Built-in:  DELETE_GROUP_ROW
** Example:   Delete certain number of records from the tail
**            of the specified record group.
*/
PROCEDURE Delete_Tail_Records( recs_to_del NUMBER,
                               rg_name VARCHAR2 ) IS
  rg_id     RecordGroup;
  rec_count NUMBER;
BEGIN
  /*
  ** Check to see if Record Group exists
  */
  rg_id := Find_Group( rg_name );
  /*
  ** Get a count of the records in the record group
  */
  rec_Count := Get_Group_Row_Count( rg_id );
  IF rec_Count < recs_to_del THEN
    Message('There are only '||TO_CHAR(rec_Count)||
           ' records in the group.');
    RAISE Form_Trigger_Failure;
  END IF;
  /*
  ** Loop thru and delete the last 'recs_to_del' records
  */
  FOR j IN 1..recs_to_del LOOP
    Delete_Group_Row( rg_id, rec_Count - j + 1 );
  END LOOP;
END;


DELETE_LIST_ELEMENT built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Deletes a specific list element from a list item.

Syntax

PROCEDURE DELETE_LIST_ELEMENT
  (list_name   VARCHAR2,
   list_index  NUMBER);

PROCEDURE DELETE_LIST_ELEMENT
  (list_id,    ITEM
   list_index  NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

list_id	Specifies the unique ID that Form Builder assigns when it creates the list item.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

list_name	The name you gave to the list item when you created it.  The data type of the name is VARCHAR2.

list_index	Specifies the list index value.  The list index is 1 based.

Usage Notes

•	Do not use the DELETE_LIST_ELEMENT built-in if the Mapping of Other Values property is defined and there are queried records in the block.  Doing so may cause Form Builder to be unable to display records that have already been fetched.

For example, assume that a list item contains the values A, B, and C and the Mapping of Other Values property is defined.  Assume also that these values have been fetched from the database (a query is open).  At this point, if you delete B from the list using DELETE_LIST_ELEMENT, an error will occur because Form Builder will attempt to display the previously fetched values (A, B, and C), but will be unable to because B was deleted from the list.

Before deleting a list element, close any open queries.  Use the ABORT_QUERY built-in to close an open query.

Note:  A list does not contain an other values element if none was specified at design time or if it was programmatically deleted from the list at runtime.


DELETE_LIST_ELEMENT restrictions

For a Poplist or T-list-style list item, Form Builder returns error FRM-41331: Could not delete element from <list_item> if you attempt to delete the default value element.

The default value element is the element whose label or value was specified at design time for the Initial Value property setting.

For a Combobox list item, you can delete the default value element only if the Initial Value property was set to an actual value, rather than an element label.

For a base table Poplist or T-list list item, Form Builder returns error FRM-41331: Could not delete element from <list_item> if you:

•	attempt to delete the other values element when the block contains queried or changed records.

•	attempt to delete any element from a list that does not contain an other values element when the block contains queried or changed records.

Note:  The block status is QUERY when a block contains queried records.  The block status is CHANGED when a block contains records that have been either inserted or updated (queried records have been modified).


DELETE_LIST_ELEMENT examples

/*

**  Built-in:  DELETE_LIST_ELEMENT
**  Example:   See ADD_LIST_ELEMENT
*/


DELETE_PARAMETER built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Deletes the parameter with the given key from the parameter list.

Syntax

PROCEDURE DELETE_PARAMETER
  (list  VARCHAR2,
   key   VARCHAR2);

PROCEDURE DELETE_PARAMETER
  (name  VARCHAR2,
   key   VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

list or name	Specifies the parameter list, either by list ID or name.  The actual parameter can be either a parameter list ID of type PARAMLIST, or the VARCHAR2 name of the parameter list.

key	The name of the parameter.  The data type of the key is VARCHAR2.


DELETE_PARAMETER restrictions

•	Deleting the last parameter from a list does not automatically delete the list itself.  To delete the parameter list, issue a call to the DESTROY_PARAMETER_LIST subprogram.


DELETE_PARAMETER examples

/*

** Built-in:  DELETE_PARAMETER
** Example:   Remove the 'NUMBER_OF_COPIES' parameter from the
**            already existing 'TEMPDATA' parameter list.
*/
BEGIN
  Delete_Parameter('tempdata','number_of_copies');
END;


DELETE_RECORD built-in

 Examples	     Related Topics	 All Built-ins

Description

When used outside an On-Delete trigger, removes the current record from the block and marks the record as a delete.  Records removed with this built-in are not removed one at a time, but are added to a list of records that are deleted during the next available commit process.

If the record corresponds to a row in the database, Form Builder locks the record before removing it and marking it as a delete.

If a query is open in the block, Form Builder fetches a record to refill the block if necessary.  See also the description for the CLEAR_RECORD built-in subprogram.

In an On-Delete trigger, DELETE_RECORD initiates the default Form Builder processing for deleting a record during the Post and Commit Transaction process, as shown in Example 2 below.

Syntax

PROCEDURE DELETE_RECORD;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


DELETE_RECORD examples

Example 1

/*

** Built-in:  DELETE_RECORD
** Example:   Mark the current record in the current block for
**            deletion.
*/
BEGIN
  Delete_Record;
END;

Example 2

/*

** Built-in:  DELETE_RECORD
** Example:   Perform Form Builder delete record processing
**            during commit-time. Decide whether to use this
**            Built-in or a user exit based on a global flag
**            setup at startup by the form, perhaps based on
**            a parameter.
** Trigger:   On-Delete
*/
BEGIN
  /*
  ** Check the global flag we set during form startup
  */
  IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
    User_Exit('my_delrec block=EMP');
  /*
  ** Otherwise, do the right thing.
  */
  ELSE
    Delete_Record;
  END IF;
END;


DELETE_TIMER built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Deletes the given timer from the form.

Syntax

PROCEDURE DELETE_TIMER
  (timer_id  Timer);

PROCEDURE DELETE_TIMER
  (timer_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

timer_id	Specifies the unique ID that Form Builder assigns when it creates the timer, specifically as a response to a successful call to the CREATE_TIMER built-in.  Use the FIND_TIMER built-in to return the ID to an appropriately typed variable.  That data type of the ID is Timer.

timer_name	Specifies the name you gave the timer when you defined it.  The data type of the timer_name is VARCHAR2.


DELETE_TIMER restrictions

•	If you delete a timer, you must issue a FIND_TIMER call before attempting to call ID_NULL to check on availability of the timer object.  For instance, the following example is incorrect because the call to DELETE_TIMER does not set the value of the ID.  In other words, the timer is deleted, but the ID continues to exist, yet points to a non-existent timer, hence, it is not null.

-- Invalid Example
   timer_id := Find_Timer('my_timer');
   Delete_Timer(timer_id);
   IF (ID_Null(timer_id))...


DELETE_TIMER examples

/*

** Built-in:  DELETE_TIMER
** Example:   Remove a timer after first checking to see if
**            it exists
*/
PROCEDURE Cancel_Timer( tm_name VARCHAR2 ) IS
  tm_id Timer;
BEGIN
  tm_id := Find_Timer( tm_name );

  IF NOT Id_Null(tm_id) THEN
    Delete_Timer(tm_id);
  ELSE
    Message('Timer '||tm_name||' has already been cancelled.');
  END IF;
END;


DELETE_TREE_NODE built-in

 Examples 	 All Built-ins

Description

Removes the data element from the tree.

Syntax

PROCEDURE DELETE_TREE_NODE

  (item_name VARCHAR2,

   node NODE);

PROCEDURE DELETE_TREE_NODE

  (item_id ITEM,

   node NODE);

Built-in Type   unrestricted procedure

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
node	Specifies a valid node.
Usage Notes

Removing a branch node also removes all child nodes.


DELETE_TREE_NODE examples

/*

** Built-in:  DELETE_TREE_NODE
*/

-- This code finds a node with the label "Zetie"

-- and deletes it and all of its children.

DECLARE

   htree         ITEM;

   delete_node   FTREE.NODE;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Find the node with a label of "Zetie".

   -- Start searching from the root of the tree.

   delete_node := Ftree.Find_Tree_Node(htree,

                                       'Zetie',

                                       Ftree.FIND_NEXT,

                                       Ftree.NODE_LABEL,

                                       Ftree.ROOT_NODE,

                                       Ftree.ROOT_NODE);

   -- Delete the node and all of its children.

   IF NOT Ftree.ID_NULL(delete_node) then

      Ftree.Delete_Tree_Node(htree, delete_node);

   END IF;

END;


DESTROY_PARAMETER_LIST built-in

 Examples	     Related Topics	 All Built-ins

Description

Deletes a dynamically created parameter list and all parameters it contains.

Syntax

PROCEDURE DESTROY_PARAMETER_LIST
  (list  VARCHAR2);

PROCEDURE DESTROY_PARAMETER_LIST
  (name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

list or name	Specifies the parameter list, either by list ID or name.  The actual parameter can be either a parameter list ID of type PARAMLIST, or the VARCHAR2 name of the parameter list.

Usage Notes:

When a parameter list is destroyed using DESTROY_PARAMETER_LIST the parameter list handle is NOT set to NULL.

Use the GET_PARAMETER_LIST built-in to return the ID to a variable of the  type PARAMLIST.


DESTROY_PARAMETER_LIST examples

/*

** Built-in:  DESTROY_PARAMETER_LIST
** Example:   Remove the parameter list 'tempdata' after first
**            checking to see if it exists
*/
DECLARE
  pl_id ParamList;
BEGIN
  pl_id := Get_Parameter_List('tempdata');
  IF NOT Id_Null(pl_id) THEN
    Destroy_Parameter_List(pl_id);
  END IF;
END;


DESTROY_VARIANT

 All Built-ins

Description

Destroys a variant that was created by the CREATE_VAR function.

Syntax

PROCEDURE DESTROY_VARIANT (variant OLEVAR);

Built-in Type  unrestricted procedure

Parameters

variant	The OLE variant to be destroyed.


DISPATCH_EVENT built-in

 Examples	 All Built-ins

Description

Specifies the dispatch mode for ActiveX control events. By default, all PL/SQL event procedures that are associated with ActiveX events are restricted. This means that go_item cannot be called from within the procedure code and OUT parameters are not observed.  However, there are instances when the same event may apply to multiple items and a go_item is necessary.  This requires that the event be dispatched as unrestricted.  Using the On-Dispatch-Event trigger, you can call DISPATCH_EVENT to specify the dispatch mode as either restricted or unrestricted. For more information about working with ActiveX control events, see Responding to ActiveX Control Events in the online help system.

Syntax

PROCEDURE DISPATCH_EVENT
  (sync NUMBER,
);

PROCEDURE DISPATCH_EVENT
);

Built-in Type  unrestricted procedure

Enter Query Mode yes

Parameters

sync	Specifies the dispatch mode as either restricted (RESTRICTED), or unrestricted (RESTRICTED_ALLOWED).


DISPATCH_EVENT examples

/*

ON-DISPATCH-EVENT trigger
*/
BEGIN
IF :SYSTEM.CUSTOM_ITEM_EVENT = 4294966696 THEN
/*when event occurs, allow it to apply to different items */
FORMS4W.DISPATCH_EVENT(RESTRICTED_ALLOWED);
ELSE
/*run the default, that does not allow applying any other 	item */
FORMS4W.DISPATCH_EVENT(RESTRICTED);
END IF;
END;


DISPLAY_ERROR built-in

 All Built-ins

Description

Displays the Display Error screen if there is a logged error.  When the operator presses a function key while viewing the Display Error screen, Form Builder redisplays the form.  If there is no error to display when you call this built-in, Form Builder ignores the call and does not display the DISPLAY ERROR screen.

Syntax

PROCEDURE DISPLAY_ERROR;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


DISPLAY_ITEM built-in

 Examples	     Related Topics	 All Built-ins

Description

Maintained for backward compatibility only. For new applications, you should use the SET_ITEM_INSTANCE_PROPERTY built-in. DISPLAY_ITEM modifies an item's appearance by assigning a specified display attribute to the item. DISPLAY_ITEM has the side-effect of also changing the appearance of any items that mirror the changed instance. SET_ITEM_INSTANCE_PROPERTY does not change mirror items.

You can reference any item in the current form.

Any change made by a DISPLAY_ITEM built-in is effective until:

•	the same item instance is referenced by another DISPLAY_ITEM built-in, or

•	the same item instance is referenced by the SET_ITEM_INSTANCE_PROPERTY built-in (with VISUAL_ATTRIBUTE property), or

•	the instance of the item is removed (e.g., through a CLEAR_RECORD or a query), or

•	you modify a record (whose status is NEW), navigate out of the record, then re-enter the record, or

•	the current form is exited

Syntax

PROCEDURE DISPLAY_ITEM
  (item_id    ITEM,
   attribute  VARCHAR2);

PROCEDURE DISPLAY_ITEM
  (item_name  VARCHAR2,
   attribute  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

 Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when it creates the item.  The data type of the ID is ITEM.

item_name	Specifies the VARCHAR2 string you gave to the item when you created it.

attribute	Specifies a named visual attribute that should exist.  You can also specify a valid attribute from your Oracle*Terminal resource file.  Form Builder will search for named visual attribute first.   Note:  You can specify Normal as a method for applying the default attributes to an item, but only if your form does not contain a visual attribute or logical (character mode or otherwise) called Normal.  You can also specify NULL as a method for returning an item to its initial visual attributes (default, custom, or named).


DISPLAY_ITEM examples

/*

** Built-in:  DISPLAY_ITEM
** Example:   Change the visual attribute of each item in the
**            current record.
*/
DECLARE
  cur_itm   VARCHAR2(80);
  cur_block VARCHAR2(80) := :System.Cursor_Block;
BEGIN
  cur_itm   := Get_Block_Property( cur_block, FIRST_ITEM );
  WHILE ( cur_itm IS NOT NULL ) LOOP
    cur_itm := cur_block||'.'||cur_itm;
    Display_Item( cur_itm, 'My_Favorite_Named_Attribute');
    cur_itm := Get_Item_Property( cur_itm, NEXTITEM );
  END LOOP;
END;


DOWN built-in

  Related Topics	 All Built-ins

Description

Navigates to the instance of the current item in the record with the next higher sequence number.  If necessary, Form Builder fetches a record.  If Form Builder has to create a record, DOWN navigates to the first navigable item in the record.

Syntax

PROCEDURE DOWN;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


DO_KEY built-in

 Examples	   Restrictions	 All Built-ins

Description

Executes the key trigger that corresponds to the specified built-in subprogram.  If no such key trigger exists, then the specified subprogram executes.  This behavior is analogous to pressing the corresponding function key.

Syntax

PROCEDURE DO_KEY
  (built-in_subprogram_name  VARCHAR2);

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

built-in_subprogram_name	Specifies the name of a valid built-in subprogram.

Built-in	Key Trigger	Associated Function Key
BLOCK_MENU	Key-MENU	[Block Menu]
CLEAR_BLOCK	Key-CLRBLK	[Clear Block]
CLEAR_FORM	Key-CLRFRM	[Clear Form]
CLEAR_RECORD	Key-CLRREC	[Clear Record]
COMMIT_FORM	Key-COMMIT	[Commit]
COUNT_QUERY	Key-CQUERY	[Count Query Hits]
CREATE_RECORD	Key-CREREC	[Insert Record]
DELETE_RECORD	Key-DELREC	[Delete Record]
DOWN	Key-DOWN	[Down]
DUPLICATE_ITEM	Key-DUP-ITEM	[Duplicate Item]
DUPLICATE_RECORD	Key-DUPREC	[Duplicate Record]
EDIT_TEXTITEM	Key-EDIT	[Edit]
ENTER	Key-ENTER	[Enter]
ENTER_QUERY	Key-ENTQRY	[Enter Query]
EXECUTE_QUERY	Key-EXEQRY	[Execute Query]
EXIT_FORM	Key-EXIT	[Exit/Cancel]
HELP	Key-HELP	[Help]
LIST_VALUES	Key-LISTVAL	[List]
LOCK_RECORD	Key-UPDREC	[Lock Record]
NEXT_BLOCK	Key-NXTBLK	[Next Block]
NEXT_ITEM	Key-NEXT-ITEM	[Next Item]
NEXT_KEY	Key-NXTKEY	[Next Primary Key Fld]
NEXT_RECORD	Key-NXTREC	[Next Record]
NEXT_SET	Key-NXTSET	[Next Set of Records]
PREVIOUS_BLOCK	Key-PRVBLK	[Previous Block]
PREVIOUS_ITEM	Key-PREV-ITEM	[Previous Item]
PREVIOUS_RECORD	Key-PRVREC	[Previous Record]
PRINT	Key-PRINT	[Print]
SCROLL_DOWN	Key-SCRDOWN	[Scroll Down]
SCROLL_UP	Key-SCRUP	[Scroll Up]
UP	Key-UP	[Up]


DO_KEY restrictions

DO_KEY accepts built-in names only, not key names: DO_KEY(ENTER_QUERY).  To accept a specific key name, use the EXECUTE_TRIGGER built-in: EXECUTE_TRIGGER('KEY_F11').


DO_KEY examples

/*

** Built-in:  DO_KEY
** Example:   Simulate pressing the [Execute Query] key.
*/
BEGIN
  Do_Key('Execute_Query');
END;


DUMMY_REFERENCE built-in

 Restrictions	    Related Topics	 All Built-ins

Description

Provides a mechanism for coding an explicit reference to a bind variable that otherwise would be referred to only indirectly in a formula (or in a function or procedure called by the formula).  Use DUMMY_REFERENCE to ensure that a formula calculated item (that contains indirect references to bind variables) will be marked for recalculation by Form Builder.

The expression can be an arbitrary expression of type Char, Number, or Date.  Typically the expression will consist of a single reference to a bind variable.

Note:  DUMMY_REFERENCE need not be executed for the referenced bind variable to be recognized by Form Builder (thereby causing the related formula calculated item to be marked for recalcuation).

Syntax

PROCEDURE DUMMY_REFERENCE(expression);

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


DUMMY_REFERENCE restrictions

none


DUPLICATE_ITEM built-in

 Restrictions	    Related Topics	 All Built-ins

Description

Assigns the current item the same value as the instance of this item in the previous record.

Syntax

PROCEDURE DUPLICATE_ITEM;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


DUPLICATE_ITEM restrictions

A previous record must exist in your current session, or Form Builder returns error FRM-41803: No previous record to copy value from.


DUPLICATE_RECORD built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Copies the value of each item in the record with the next lower sequence number to the corresponding items in the current record.  The current record must not correspond to a row in the database.  If it does, an error occurs.

Note:  The duplicate record does not inherit the record status of the source record; instead, its record status is INSERT.

Syntax

PROCEDURE DUPLICATE_RECORD;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


DUPLICATE_RECORD restrictions

A previous record must exist in your current session.


DUPLICATE_RECORD examples

/*

** Built-in:  DUPLICATE_RECORD;
** Example:   Make a copy of the current record and increment
**            the "line_sequence" item by one.
*/
DECLARE
  n NUMBER;
BEGIN
  /*
  ** Remember the value of the 'line_sequence' from the
  ** current record
  */
  n := :my_block.line_sequence;
  /*
  ** Create a new record, and copy all the values from the
  ** previous record into it.
  */
  Create_Record;
  Duplicate_Record;
  /*
  ** Set the new record's 'line_sequence' to one more than
  ** the last record's.
  */
  :my_block.line_sequence := n + 1;
END;


EDIT_TEXTITEM built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Invokes the Runform item editor for the current text item and puts the form in Edit mode.

Syntax

PROCEDURE EDIT_TEXTITEM;

PROCEDURE EDIT_TEXTITEM
  (x  NUMBER,
   y  NUMBER);
PROCEDURE EDIT_TEXTITEM
  (x       NUMBER,
   y       NUMBER,
   width,  NUMBER
   height  NUMBER);

Built-in Type  restricted procedure

Enter Query Mode  yes

Parameters

x	Specifies the x coordinate on the screen where you want to place the upper left corner of the pop-up item editor.

y	Specifies the y coordinate on the screen where you want to place the upper left corner of the pop-up item editor.

width	Specifies the width of the entire editor window, including buttons.

height	Specifies the height  of the entire editor window, including buttons.

If you specify a height less than 6 character cells, or its equivalent, Form Builder sets the height equal to 6.

You can use the optional EDIT_TEXTITEM parameters to specify the location and dimensions of the pop-up window with which the item editor is associated.  If you do not use these parameters, Form Builder invokes the item editor with its default location and dimensions.


EDIT_TEXTITEM restrictions

•	The Width must be at least wide enough to display the buttons at the bottom of the editor window.


EDIT_TEXTITEM examples

/*

** Built-in:  EDIT_TEXTITEM
** Example:   Determine the x-position of the current item
**            then bring up the editor either on the left
**            side or right side of the screen so as to not
**            cover the item on the screen.
*/
DECLARE
  itm_x_pos NUMBER;
BEGIN
  itm_x_pos := Get_Item_Property(:System.Cursor_Item,X_POS);
  IF itm_x_pos > 40 THEN
    Edit_TextItem(1,1,20,8);
  ELSE
    Edit_TextItem(60,1,20,8);
  END IF;
END;


ENFORCE_COLUMN_SECURITY built-in

 Restrictions	    Related Topics	 All Built-ins

Description

Executes default processing for checking column security on a database column.  This built-in is included primarily for applications that run against a non-ORACLE data source, and use transactional triggers to replace default Form Builder transaction processing.

Default Check Column Security processing refers to the sequence of events that occurs when Form Builder enforces column-level security for each block that has the Enforce Column Security block property set Yes.  To enforce column security, Form Builder queries the database to determine the base table columns to which the current form operator has update privileges.  For columns to which the operator does not have update privileges, Form Builder makes the corresponding base table items in the form non-updateable by setting the Update Allowed item property to No dynamically.  By default, Form Builder performs this operation at form startup, processing each block in sequence.

For more information, refer to Form Builder Advanced Techniques, Chapter 4, "Connecting to Non-Oracle Data Sources."

Syntax

PROCEDURE ENFORCE_COLUMN_SECURITY

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Usage Notes

You can include this built-in subprogram in the On-Column-Security trigger if you intend to augment the behavior of that trigger rather than completely replace the behavior.  For more information, refer to Chapter , "Triggers," in this manual.


ENFORCE_COLUMN_SECURITY restrictions

Valid only in an On-Column-Security trigger.


ENTER built-in

 Examples	     Related Topics	 All Built-ins

Description

Validates data in the current validation unit. (The default validation unit is Item.)

Syntax

PROCEDURE ENTER;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none


ENTER examples

/*

** Built-in:  ENTER
** Example:   Force Validation to occur before calling another
**            form
*/
BEGIN
  Enter;
  IF NOT Form_Success THEN
    RAISE Form_Trigger_Failure;
  END IF;
  Call_Form('newcust');
END;


ENTER_QUERY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

The behavior of ENTER_QUERY varies depending on any parameters you supply.

Syntax

PROCEDURE ENTER_QUERY;

PROCEDURE ENTER_QUERY
  (keyword_one  VARCHAR2);
PROCEDURE ENTER_QUERY
  (keyword_two  VARCHAR2);
PROCEDURE ENTER_QUERY
  (keyword_one  VARCHAR2,
   keyword_two  VARCHAR2);
PROCEDURE ENTER_QUERY
  (keyword_one  VARCHAR2,
   keyword_two  VARCHAR2,
   locking      VARCHAR2);

Built-in Type  restricted procedure

Enter Query Mode  yes (to redisplay the example record from the last query executed in the block)

Parameters

no parameters	ENTER_QUERY flushes the current block and puts the form in Enter Query mode.  If there are changes to commit, Form Builder prompts the operator to commit them during the ENTER_QUERY process.

keyword_one	ENTER_QUERY(ALL_RECORDS) performs the same actions as ENTER_QUERY except that when EXECUTE_QUERY is invoked, Form Builder fetches all of the selected records.

keyword_two	ENTER_QUERY(FOR_UPDATE) performs the same actions as ENTER_QUERY except that when EXECUTE_QUERY is invoked, Form Builder attempts to lock all of the selected records immediately.

keyword_one/ keyword_two	ENTER_QUERY(ALL_RECORDS, FOR_UPDATE) performs the same actions as ENTER_QUERY except that when EXECUTE_QUERY is invoked, Form Builder attempts to lock all of the selected records immediately and fetches all of the selected records.

locking	Can be set to NO_WAIT anytime that you use the FOR_UPDATE parameter.  When you use NO_WAIT, Form Builder displays a dialog to notify the operator if a record cannot be reserved for update immediately.

Without the NO_WAIT parameter, Form Builder keeps trying to obtain a lock without letting the operator cancel the process.

Use the NO_WAIT parameter only when running against a data source that supports this functionality.


ENTER_QUERY restrictions

Use the ALL_RECORDS and FOR_UPDATE parameters with caution.  Locking and fetching a large number of rows can result in long delays due to the many resources that must be acquired to accomplish the task.


ENTER_QUERY examples

/*

** Built-in:  ENTER_QUERY
** Example:   Go Into Enter-Query mode, and exit the form if
**            the user cancels out of enter-query mode.
*/
BEGIN
  Enter_Query;
  /*
  ** Check to see if the record status of the first record
  ** is 'NEW' immediately after returning from enter-query
  ** mode.  It should be 'QUERY' if at least one row was
  ** returned.
  */

  IF :System.Record_Status = 'NEW' THEN
    Exit_Form(No_Validate);
  END IF;
END;


ERASE built-in

 Examples	     Related Topics	 All Built-ins

Description

Removes an indicated global variable, so that it no longer exists, and releases the memory associated with the global variable.  Globals always allocate 255 bytes of storage.  To ensure that performance is not impacted more than necessary, always erase any global variable when it is no longer needed.

Syntax

PROCEDURE ERASE
  (global_variable_name  VARCHAR2);

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

global_variable_name	Specifies the name of a valid global variable.


ERASE examples

ERASE('global.var');


ERROR_CODE built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the error number of the Form Builder error.

Syntax

PROCEDURE ERROR_CODE;

Built-in Type   unrestricted function

Enter Query Mode  yes

Parameters

none


ERROR_CODE examples

/*

** Built-in:  ERROR_CODE,ERROR_TEXT,ERROR_TYPE
** Example:   Reword certain FRM error messages by checking
**            the Error_Code in an ON-ERROR trigger
** Trigger:   On-Error
*/
DECLARE
  errnum NUMBER       := ERROR_CODE;
  errtxt VARCHAR2(80) := ERROR_TEXT;
  errtyp VARCHAR2(3)  := ERROR_TYPE;
BEGIN
  IF errnum = 40301 THEN
    Message('Your search criteria identified no matches...
              Try Again.');
  ELSIF errnum = 40350 THEN
    Message('Your selection does not correspond to an employee.');
  ELSE
    /*
    ** Print the Normal Message that would have appeared
    **
    ** Default Error Message Text Goes Here
    */
    Message(errtyp||'-'||TO_CHAR(errnum)||': '||errtxt);
    RAISE Form_Trigger_Failure;
  END IF;
END;


ERROR_TEXT built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the message text of the Form Builder error.

Syntax

FUNCTION ERROR_TEXT;

Built-in Type   unrestricted function

Enter Query Mode  yes

Description

Returns the message text of the Form Builder error.

Parameters

none

Usage Notes

You can use this function to test error messages during exception handling subprograms.


ERROR_TEXT examples

/*

** Built-in:  ERROR_CODE,ERROR_TEXT,ERROR_TYPE
** Example:   Reword certain FRM error messages by checking
**            the Error_Code in an ON-ERROR trigger
** Trigger:   On-Error
*/
DECLARE
  errnum NUMBER       := ERROR_CODE;
  errtxt VARCHAR2(80) := ERROR_TEXT;
  errtyp VARCHAR2(3)  := ERROR_TYPE;
BEGIN
  IF errnum = 40301 THEN
    Message('Your search criteria identified no matches...
             Try Again.');
  ELSIF errnum = 40350 THEN
    Message('Your selection does not correspond to an employee.');
  ELSE
    /*
    ** Print the Normal Message that would have appeared
    **
    ** Default Error Message Text Goes Here
    */
    Message(errtyp||'-'||TO_CHAR(errnum)||': '||errtxt);
    RAISE Form_Trigger_Failure;
  END IF;


ERROR_TYPE built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the error message type for the action most recently performed during the current Runform session.

Syntax

FUNCTION ERROR_TYPE;

Built-in Type   unrestricted function

Returns  ERROR_TYPE returns one of the following values for the error message type:

FRM	Indicates an Form Builder error.

ORA	Indicates an ORACLE error.

Enter Query Mode  yes

Parameters

none

Usage Notes

You can use this function to do one of the following:

•	test the outcome of a user action, such as pressing a key, to determine processing within an On-Error trigger

•	test the outcome of a built-in to determine further processing within any trigger

To get the correct results in either type of test, you must perform the test immediately after the action executes, before any other action occurs.


ERROR_TYPE examples

/*

** Built-in:  ERROR_CODE,ERROR_TEXT,ERROR_TYPE
** Example:   Reword certain FRM error messages by checking
**            the Error_Code in an ON-ERROR trigger
** Trigger:   On-Error
*/
DECLARE
  errnum NUMBER       := ERROR_CODE;
  errtxt VARCHAR2(80) := ERROR_TEXT;
  errtyp VARCHAR2(3)  := ERROR_TYPE;
BEGIN
  IF errnum = 40107 THEN
    Message('You cannot navigate to this non-displayed item...
          Try again.');
  ELSIF errnum = 40109 THEN
    Message('If you want to leave this block,
          you must first cancel Enter Query mode.');
  ELSE
    /*
    ** Print the Normal Message that would have appeared
    **
    ** Default Error Message Text Goes Here
    */
    Message(errtyp||'-'||TO_CHAR(errnum)||': '||errtxt);
    RAISE Form_Trigger_Failure;
  END IF;
END;


EXEC_VERB

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Causes the OLE server to execute the verb identified by the verb name or the verb index. An OLE verb specifies the action that you can perform on an OLE object.

Syntax

PROCEDURE EXEC_VERB
  (item_id     Item,
   verb_index  VARCHAR2);

PROCEDURE EXEC_VERB
  (item_id    Item,
   verb_name  VARCHAR2);
PROCEDURE EXEC_VERB
  (item_name   VARCHAR2,
   verb_index  VARCHAR2);
PROCEDURE EXEC_VERB
  (item_name  VARCHAR2,
   verb_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  no

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is Item.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.

verb_index	Specifies the numeric index of a verb.  Use the Forms_OLE.Find_OLE_Verb built-in to obtain this value.  The data type of index is VARCHAR2 string.

verb_name	Specifies the name of a verb.  Use the Forms_OLE.Get_Verb_Name built-in to obtain this value.  The data type of the name is VARCHAR2 char.


EXEC_VERB restrictions

Valid only on Microsoft Windows and Macintosh.


EXEC_VERB examples

/*

** Built-in: EXEC_VERB
** Example:  Deactivates the OLE server associated with the object
**           in the OLE container.
** Trigger:  When-Button-Pressed
*/
DECLARE
 item_id  ITEM;
 item_name VARCHAR(25) := 'OLEITM';
 verb_cnt_str VARCHAR(20);
 verb_cnt NUMBER;
 verb_name VARCHAR(20);
 loop_cntr NUMBER;
BEGIN
 item_id := Find_Item(item_name);
 IF Id_Null(item_id) THEN
  message('No such item: '||item_name);
 ELSE
  verb_cnt_str := Forms_OLE.Get_Verb_Count(item_id);
  verb_cnt := TO_NUMBER(verb_cnt_str);
  FOR loop_cntr in 1..verb_cnt LOOP
    verb_name := Forms_OLE.Get_Verb_Name(item_id,loop_cntr);
    IF verb_name = 'Edit' THEN
   EXEC_VERB(item_id,verb_name);
    END IF;
  END LOOP;
 END IF;
END;


EXECUTE_QUERY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Flushes the current block, opens a query, and fetches a number of selected records.  If there are changes to commit, Form Builder prompts the operator to commit them before continuing EXECUTE_QUERY processing.

Syntax

PROCEDURE EXECUTE_QUERY;

PROCEDURE EXECUTE_QUERY
  (keyword_one  VARCHAR2);
PROCEDURE EXECUTE_QUERY
  (keyword_two  VARCHAR2);
PROCEDURE EXECUTE_QUERY
  (keyword_one  VARCHAR2,
   keyword_two  VARCHAR2);
PROCEDURE EXECUTE_QUERY
  (keyword_one  VARCHAR2,
   keyword_two  VARCHAR2,
   locking      VARCHAR2);

Built-in Type  restricted procedure

Enter Query Mode  yes

Parameters

no parameters	EXECUTE_QUERY flushes the current block, opens a query, and fetches a number of selected records.

keyword_one	EXECUTE_QUERY(ALL_RECORDS) performs the same actions as EXECUTE_QUERY except that Form Builder fetches all of the selected records.

keyword_two	EXECUTE_QUERY(FOR_UPDATE) performs the same actions as EXECUTE_QUERY except that Form Builder attempts to lock all of the selected records immediately.

keyword_one/ keyword_two	EXECUTE_QUERY(ALL_RECORDS, FOR_UPDATE) performs the same actions as EXECUTE_QUERY except that Form Builder attempts to lock all of the selected records immediately and fetches all of the selected records.

locking	Can be set to NO_WAIT anytime that you use the FOR_UPDATE parameter.  When you use NO_WAIT, Form Builder displays a dialog to notify the operator if a record cannot be reserved for update immediately.

Without the NO_WAIT parameter, Form Builder keeps trying to obtain a lock without letting the operator cancel the process.

Use the NO_WAIT parameter only when running against a data source that supports this functionality.


EXECUTE_QUERY restrictions

Oracle Corporation recommends that you use the ALL_RECORDS and FOR_UPDATE parameters with caution.  Fetching a large number of rows could cause a long delay.  Locking a large number of rows at once requires many resources.


EXECUTE_QUERY examples

/*

** Built-in:  EXECUTE_QUERY
** Example:   Visit several blocks and query their contents,
**            then go back to the block where original block.
*/
DECLARE
  block_before VARCHAR2(80) := :System.Cursor_Block;
BEGIN
  Go_Block('Exceptions_List');
  Execute_Query;
  Go_Block('User_Profile');
  Execute_Query;
  Go_Block('Tasks_Competed');
  Execute_Query;
  Go_Block( block_before );
END;


EXECUTE_TRIGGER built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

EXECUTE_TRIGGER executes an indicated trigger.

Syntax

PROCEDURE EXECUTE_TRIGGER
  (trigger_name  VARCHAR2);

Built-in Type   restricted procedure (if the user-defined trigger calls any restricted built-in subprograms)

Enter Query Mode  yes

Note:  EXECUTE_TRIGGER is not the preferred method for executing a user-named trigger:  writing a user-named subprogram is the preferred method.

Parameters

trigger_name	Specifies the name of a valid user-named trigger.

Usage Notes

Because you cannot specify scope for this built-in, Form Builder always looks for the trigger starting at the lowest level, then working up.

To execute a built-in associated with a key, use the DO_KEY built-in instead of EXECUTE_TRIGGER.  For example, rather than:

Execute_Trigger ('KEY-NEXT-ITEM');

Use instead:

Do_Key('NEXT_ITEM');


EXECUTE_TRIGGER restrictions

Although you can use EXECUTE_TRIGGER to execute a built-in trigger as well as a user-named trigger, this usage is not recommended, because the default fail behavior follows a different rule than when invoked automatically by Form Builder as part of default processing.  For example, in default processing, if the When-Validate-Item trigger fails, it raises an exception and stops the processing of the form.  However, if the When-Validate-Item trigger fails when it is invoked by EXECUTE_TRIGGER, that failure does not stop the processing of the form, but only sets Form_Failure to FALSE on return from the EXECUTE_TRIGGER built-in.


EXECUTE_TRIGGER examples

/*

** Built-in:  EXECUTE_TRIGGER
** Example:   Execute a trigger dynamically from the PL/SQL
**            code of a Menu item, depending on a menu
**            checkbox.
*/
DECLARE
  Cur_Setting   VARCHAR2(5);
  Advanced_Mode BOOLEAN;
BEGIN
  /*
  ** Check whether the 'Advanced' menu item under the
  ** 'Preferences' submenu is checked on or not.
  */
  Cur_Setting :=  Get_Menu_Item_Property
                    ('Preferences.Advanced',CHECKED);
  /*
  ** If it is checked on, then Advanced_Mode is boolean
  ** true.
  */
  Advanced_Mode := (Cur_Setting = 'TRUE');
  /*
  ** Run the appropriate trigger from the underlying form
  **
  */
  IF Advanced_Mode THEN
    Execute_Trigger('Launch_Advanced_Help');
  ELSE
    Execute_Trigger('Launch_Beginner_Help');
  END IF;
END;


EXIT_FORM built-in

 Examples	 All Built-ins

Description

Provides a means to exit a form, confirming commits and specifying rollback action.

•	In most contexts, EXIT_FORM navigates “outside” the form.  If there are changes in the current form that have not been posted or committed, Form Builder prompts the operator to commit before continuing EXIT_FORM processing.

•	If the operator is in Enter Query mode, EXIT_FORM navigates out of Enter Query mode, not out of the form.

•	During a CALL_INPUT, EXIT_FORM terminates the CALL_INPUT function.

Syntax

PROCEDURE EXIT_FORM;

PROCEDURE EXIT_FORM
  (commit_mode  NUMBER);
PROCEDURE EXIT_FORM
  (commit_mode   NUMBER,
   rollback_mode NUMBER);

Built-in Type  restricted procedure

Enter Query Mode  yes

Parameters

commit_mode	ASK_COMMIT  Form Builder prompts the operator to commit the changes during EXIT_FORM processing.

However, if RECORD_STATUS is INSERT but the record is not valid, Form Builder instead asks the operator if the form should be closed.  If the operator says yes, the changes are rolled back before the form is closed.

DO_COMMIT  Form Builder validates the changes, performs a commit, and exits the current form without prompting the operator.

NO_COMMIT  Form Builder validates the changes and exits the current form without performing a commit or prompting the operator.

NO_VALIDATE  Form Builder exits the current form without validating the changes, committing the changes, or prompting the operator.

rollback_mode	TO_SAVEPOINT  Form Builder rolls back all uncommitted changes (including posted changes) to the current form's savepoint.

FULL_ROLLBACK  Form Builder rolls back all uncommitted changes (including posted changes) that were made during the current Runform session.  You cannot specify a FULL_ROLLBACK from a form that is running in post-only mode.  (Post-only mode can occur when your form issues a call to another form while unposted records exist in the calling form.  To prevent losing the locks issued by the calling form, Form Builder prevents any commit processing in the called form.)

NO_ROLLBACK  Form Builder exits the current form without rolling back to a savepoint.  You can leave the top level form without performing a rollback, which means that you retain the locks across a NEW_FORM operation.  These locks can also occur when running Form Builder from an external 3GL program.  The locks remain in effect when Form Builder returns control to the program.

Usage Notes

Because the default parameters of EXIT_FORM are ASK_COMMIT for commit_mode  and TO_SAVEPOINT for rollback_mode, invoking EXIT_FORM without specifying any parameters in some contexts may produce undesired results.  For example, if the form is in POST only mode and EXIT_FORM is invoked without parameters, the user will be prompted to commit the changes.  However, regardless of the user’s input at that prompt, the default rollback_mode of TO_SAVEPOINT rolls back the changes to the form despite a message confirming that changes have been made.  To avoid conflicts explicitly specify parameters.


EXIT_FORM examples

/*

** Built-in:  EXIT_FORM and POST
** Example:   Leave the called form, without rolling back the
**            posted changes so they may be posted and
**            committed by the calling form as part of the
**            same transaction.
*/
BEGIN
  Post;

  /*
  ** Form_Status should be 'QUERY' if all records were
  ** successfully posted.
  */
  IF :System.Form_Status <> 'QUERY' THEN
    Message('An error prevented the system from posting changes');
    RAISE Form_Trigger_Failure;
  END IF;
  /*
  ** By default, Exit_Form asks to commit and performs a
  ** rollback to savepoint. We've already posted, so we do
  ** not need to commit, and we don't want the posted changes
  ** to be rolled back.
  */
  Exit_Form(NO_COMMIT, NO_ROLLBACK);
END;


FETCH_RECORDS built-in

 Examples	     Related Topics	 All Built-ins

Description

When called from an On-Fetch trigger, initiates the default Form Builder processing for fetching records that have been identified by SELECT processing.

Syntax

PROCEDURE FETCH_RECORDS;

Built-in Type   unrestricted procedure

Enter Query Mode  no

This built-in is included primarily for applications that will run against a non-ORACLE data source.

Parameters

none


FETCH_RECORDS examples

/*

** Built-in:  FETCH_RECORDS
** Example:   Perform Form Builder record fetch processing during
**            query time. Decide whether to use this built-in
**            or a user exit based on a global flag setup at
**            startup by the form, perhaps based on a
**            parameter. The block property RECORDS_TO_FETCH
**            allows you to know how many records Form Builder
**            is expecting.
** Trigger:   On-Fetch
*/
DECLARE
  numrecs NUMBER;
BEGIN
  /*
  ** Check the global flag we set during form startup
  */
  IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
    /*
    ** How many records is the form expecting us to
    ** fetch?
    */
    numrecs := Get_Block_Property('EMP',RECORDS_TO_FETCH);
    /*
    ** Call user exit to determine if there are any
    ** more records to fetch from its cursor. User Exit
    ** will return failure if there are no more
    ** records to fetch.
    */
    User_Exit('my_fetch block=EMP remaining_records');
    /*
    ** If there ARE more records, then loop thru
    ** and create/populate the proper number of queried
    ** records. If there are no more records, we drop through
    ** and do nothing. Form Builder takes this as a signal that
    ** we are done.
    */
    IF Form_Success THEN
      /* Create and Populate 'numrecs' records */
      FOR j IN 1..numrecs LOOP
        Create_Queried_Record;
        /*
        ** User exit returns false if there are no more
        ** records left to fetch. We break out of the
        ** if we've hit the last record.
        */
        User_Exit('my_fetch block=EMP get_next_record');
        IF NOT Form_Success THEN
          EXIT;
        END IF;
      END LOOP;
    END IF;
  /*
  ** Otherwise, do the right thing.
  */
  ELSE
    Fetch_Records;
  END IF;
END;


FIND_ALERT built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of valid alerts in Form Builder.  When the given alert is located, the subprogram returns an alert ID.  You must return the ID to an appropriately typed variable.  Define the variable with a type of Alert.

Syntax

FUNCTION FIND_ALERT
  (alert_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  Alert

Enter Query Mode  yes

Parameters

alert_name	Specifies the VARCHAR2 alert name.


FIND_ALERT examples

/*

** Built-in:  FIND_ALERT
** Example:   Show a user-warning alert. If the user presses
**            the OK button, then make REALLY sure they want
**            to continue with another alert.
*/
DECLARE
  al_id     Alert;
  al_button NUMBER;
BEGIN
  al_id := Find_Alert('User_Warning');
  IF Id_Null(al_id) THEN
    Message('User_Warning alert does not exist');
    RAISE Form_Trigger_Failure;
  ELSE
   /*
   ** Show the warning alert
   */
   al_button := Show_Alert(al_id);
   /*
   ** If user pressed OK (button 1) then bring up another
   ** alert to confirm -- button mappings are specified
   ** in the alert design
   */
   IF al_button = ALERT_BUTTON1 THEN
      al_id := Find_Alert('Are_You_Sure');

      IF Id_Null(al_id) THEN
        Message('The alert named: Are you sure? does not exist');
        RAISE Form_Trigger_Failure;
       ELSE
         al_button := Show_Alert(al_id);
         IF al_button = ALERT_BUTTON2 THEN
           Erase_All_Employee_Records;
         END IF;
       END IF;
     END IF;
   END IF;
END;


FIND_BLOCK built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of valid blocks and returns a unique block ID.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of Block.

Syntax

FUNCTION FIND_BLOCK
  (block_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  Block

Enter Query Mode  yes

Parameters

block_name	Specifies the VARCHAR2 block name.


FIND_BLOCK examples

/*

** Built-in:  FIND_BLOCK
** Example:  Return true if a certain blockname exists
*/
FUNCTION Does_Block_Exist( bk_name VARCHAR2 )
RETURN BOOLEAN IS
  bk_id Block;
BEGIN
  /*
  ** Try to locate the block by name
  */
  bk_id := Find_Block( bk_name );
  /*
  ** Return the boolean result of whether we found it.
  ** Finding the block means that its bk_id will NOT be NULL
  */
  RETURN (NOT Id_Null(bk_id));
END;


FIND_CANVAS built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of canvases and returns a canvas ID when it finds a valid canvas with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of Canvas.

Syntax

FUNCTION FIND_CANVAS
  (canvas_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  Canvas

Enter Query Mode  yes

Parameters

canvas_name	Specifies the VARCHAR2 canvas name you gave the canvas when defining it.


FIND_CANVAS examples

DECLARE
  my_canvas Canvas;
BEGIN
  my_canvas := Find_Canvas('my_canvas');
END;


FIND_COLUMN built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of record group columns and returns a groupcolumn  ID when it finds a valid column with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of GroupColumn.

Syntax

FUNCTION FIND_COLUMN
  (recordgroup.groupcolumn_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  GroupColumn

Enter Query Mode  yes

Parameters

recordgroup. groupcolumn_name	Specifies the fully qualified VARCHAR2 record group column name.


FIND_COLUMN examples

/*

** Built-in:  FIND_COLUMN
** Example:   Get column IDs for three columns in a record
**            group before performing multiple Get's or Set's
**            of the record group's column values
*/
PROCEDURE Record_Machine_Stats( mach_number NUMBER,
                          pph         NUMBER,
                          temperature NUMBER) IS
  rg_id  RecordGroup;
  col1   GroupColumn;
  col2   GroupColumn;
  col3   GroupColumn;
  row_no NUMBER;
BEGIN
  rg_id := Find_Group('machine');
  col1  := Find_Column('machine.machine_no');
  col2  := Find_Column('machine.parts_per_hour');
  col3  := Find_Column('machine.current_temp');
  /*
  ** Add a new row at the bottom of the 'machine' record
  ** group, and make a note of what row number we just
  ** added.
  */
  Add_Group_Row( rg_id, END_OF_GROUP);
  row_no := Get_Group_Row_Count(rg_id);
  Set_Group_Number_Cell(col1, row_no, mach_number);
  Set_Group_Number_Cell(col2, row_no, pph);
  Set_Group_Number_Cell(col3, row_no, temperature);
END;


FIND_EDITOR built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of editors and returns an editor ID when it finds a valid editor with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of Editor.

Syntax

FUNCTION FIND_EDITOR
  (editor_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  Editor

Enter Query Mode  yes

Parameters

editor_name	Specifies a valid VARCHAR2 editor name.


FIND_EDITOR examples

/*

** Built-in:  FIND_EDITOR
** Example:   Find and show a user-defined editor
*/
DECLARE
  ed_id  Editor;
  status BOOLEAN;
BEGIN
  ed_id := Find_Editor('Happy_Edit_Window');

  IF NOT Id_Null(ed_id) THEN
    Show_Editor(ed_id, NULL, :emp.comments, status);
  ELSE
    Message('Editor "Happy_Edit_Window" not found');
    RAISE Form_Trigger_Failure;
  END IF;
END;


FIND_FORM built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of forms and returns a form module ID when it finds a valid form with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of Formmodule.

Syntax

FUNCTION FIND_FORM
  (formmodule_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  FormModule

Enter Query Mode  yes

Parameters

formmodule_name	Specifies a valid VARCHAR2 form name.


FIND_FORM examples

/*

** Built-in:  FIND_FORM
** Example:   Find a form's Id before inquiring about several
**            of its properties
*/
DECLARE
  fm_id  FormModule;
  tmpstr VARCHAR2(80);
BEGIN
  fm_id := Find_Form(:System.Current_Form);
  tmpstr := Get_Form_Property(fm_id,CURSOR_MODE);
  tmpstr := tmpstr||','||Get_Form_Property(fm_id,SAVEPOINT_MODE);
  Message('Form is configured as: '||tmpstr);
END;


FIND_GROUP built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Searches the list of record groups and returns a record group ID when it finds a valid group with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of RecordGroup.

Syntax

FUNCTION FIND_GROUP
  (recordgroup_name VARCHAR2);

Built-in Type   unrestricted function

Returns  RecordGroup

Enter Query Mode  yes

Parameters

recordgroup_name	Specifies the valid VARCHAR2 record group name.


FIND_GROUP restrictions

Performance of this function depends upon the number of record groups.


FIND_GROUP examples

/*

** Built-in:  FIND_GROUP
** Example:  See CREATE_GROUP and DELETE_GROUP_ROW
*/


FIND_ITEM built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of items in a given block and returns an item ID when it finds a valid item with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of Item.

Syntax

FUNCTION FIND_ITEM
  (block.item_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  Item

Enter Query Mode  yes

Parameters

block_name. item_name	Specifies the fully qualified item name. The data type of the name is VARCHAR2.


FIND_ITEM examples

/*

** Built-in:  FIND_ITEM
** Example:   Find an item's Id before setting several
**            of its properties.
*/
PROCEDURE Hide_an_Item( item_name VARCHAR2, hide_it BOOLEAN) IS
  it_id   Item;
BEGIN
  it_id := Find_Item(item_name);
  IF Id_Null(it_id) THEN
    Message('No such item: '||item_name);
    RAISE Form_Trigger_Failure;
  ELSE
    IF hide_it THEN
      Set_Item_Property(it_id,VISIBLE,PROPERTY_FALSE);
    ELSE
      Set_Item_Property(it_id,VISIBLE,PROPERTY_TRUE);
      Set_Item_Property(it_id,ENABLED,PROPERTY_TRUE);
      Set_Item_Property(it_id,NAVIGABLE,PROPERTY_TRUE);
    END IF;
  END IF;
END;


FIND_LOV built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of LOVs and returns an LOV ID when it finds a valid LOV with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of LOV.

Syntax

FUNCTION FIND_LOV
  (LOV_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  LOV

Enter Query Mode  yes

Parameters

LOV_name	Specifies the valid VARCHAR2 LOV name.


FIND_LOV examples

/*

** Built-in:  FIND_LOV
** Example:   Determine if an LOV exists before showing it.
*/
DECLARE
  lv_id  LOV;
  status BOOLEAN;
BEGIN
  lv_id := Find_LOV('My_Shared_LOV');
  /*
  ** If the 'My_Shared_LOV' is not part of the current form,
  ** then use the 'My_Private_LOV' instead.
  */
  IF Id_Null(lv_id) THEN
    lv_id := Find_LOV('My_Private_LOV');
  END IF;
  status := Show_LOV(lv_id,10,20);
END;


FIND_MENU_ITEM built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of menu items and returns a menu item ID when it finds a valid menu item with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of MenuItem.

Syntax

FUNCTION FIND_MENU_ITEM
  (menu_name.menu_item_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  MenuItem

Enter Query Mode  yes

Parameters

menu_name. menu_item_name	Specifies a valid fully-qualified VARCHAR2 menu item name.


FIND_MENU_ITEM examples

/*

** Built-in:  FIND_MENU_ITEM
** Example:   Find the id of a menu item before setting
**            multiple properties
*/
PROCEDURE Toggle_AutoCommit_Mode IS
  mi_id MenuItem;
  val   VARCHAR2(10);
BEGIN
  mi_id := Find_Menu_Item('Preferences.AutoCommit');
  /*
  ** Determine the current checked state of the AutoCommit
  ** menu checkbox item
  */
  val := Get_Menu_Item_Property(mi_id,CHECKED);
  /*
  ** Toggle the checked state
  */
  IF val = 'TRUE' THEN
    Set_Menu_Item_Property(mi_id,CHECKED,PROPERTY_FALSE);
  ELSE
    Set_Menu_Item_Property(mi_id,CHECKED,PROPERTY_TRUE);
  END IF;
END;


FIND_OLE_VERB

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Returns an OLE verb index.  An OLE verb specifies the action that you can perform on an OLE object, and each OLE verb has a corresponding OLE verb index.  The OLE verb index is returned as a VARCHAR2 string and must be converted to NUMBER when used in FORMS_OLE.EXE_VERB.  You must define an appropriately typed variable to accept the return value.

Syntax

FUNCTION FIND_OLE_VERB
  (item_id    Item,
   verb_name  VARCHAR2);

FUNCTION FIND_OLE_VERB
  (item_name  VARCHAR2,
   verb_name  VARCHAR2);

Returns  VARCHAR2

Built-in Type  unrestricted function

Enter Query Mode  no

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is Item.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.

verb_name	Specifies the name of an OLE verb.  An OLE verb specifies the action that you can perform on an OLE object. Use the Forms_OLE.Get_Verb_Name built-in to obtain this value.  The data type of the name is VARCHAR2 string.


FIND_OLE_VERB restrictions

Valid only on Microsoft Windows and Macintosh.


FIND_OLE_VERB examples

/*

** Built-in: EXEC_VERB
** Example:  Finds an OLE verb index for use with the
**           Forms_OLE.Exec_Verb built-in.
** Trigger:  When-Button-Pressed
*/
DECLARE
 item_id  ITEM;
 item_name VARCHAR(25) := 'OLEITM';
 verb_index_str VARCHAR(20);
 verb_index NUMBER;
BEGIN
 item_id := Find_Item(item_name);
 IF Id_Null(item_id) THEN
  message('No such item: '||item_name);
 ELSE
  verb_index_str := Forms_OLE.Find_OLE_Verb(item_id,'Edit');
  verb_index := TO_NUMBER(verb_index_str);
  Forms_OLE.Exec_Verb(item_id,verb_index);
 END IF;
END;


FIND_RELATION built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of relations and returns a relation ID when it finds a valid relation  with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of Relation.

Syntax

FUNCTION FIND_RELATION
  (relation_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  Relation

Enter Query Mode  yes

Parameters

relation_name	Specifies a valid VARCHAR2 relation name.


FIND_RELATION examples

/*

** Built-in:  FIND_RELATION
** Example:   Find the id of a relation before inquiring about
**            multiple properties
*/
FUNCTION Detail_of( Relation_Name VARCHAR2 )
RETURN VARCHAR2 IS
  rl_id Relation;
BEGIN
  rl_id := Find_Relation( Relation_Name );

  /*
  ** Signal error if relation does not exist
  */
  IF Id_Null(rl_id) THEN
    Message('Relation '||Relation_Name||' does not exist.');
    RAISE Form_Trigger_Failure;
  ELSE
    RETURN Get_Relation_Property(rl_id,DETAIL_NAME);
  END IF;
END;


FIND_REPORT_OBJECT built-in

 Examples	 All Built-ins

Description

Returns the report_id for a specified report. You can use this ID as a parameter for other built-ins, such as RUN_REPORT_OBJECT .

Syntax

FUNCTION FIND_REPORT_OBJECT
  (report_name VARCHAR2
);

Built-in Type  unrestricted procedure

Returns	   report_id of data type REPORT

Enter Query Mode yes

Parameters

report_name	Specifies the unique name of the report to be found.


FIND_REPORT_OBJECT examples

DECLARE

repid REPORT_OBJECT;

v_rep  VARCHAR2(100);

BEGIN

repid := find_report_object('report4');

v_rep := RUN_REPORT_OBJECT(repid);

....

END;


FIND_TAB_PAGE built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of tab pages in a given tab canvas and returns a tab page ID when it finds a valid tab page with the given name.  You must define a variable of type TAB_PAGE to accept the return value.

Syntax

FUNCTION FIND_TAB_PAGE
  (tab_page_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  tab_page

Enter Query Mode  yes

Parameters

tab_page_name	The unique tab page name.  Datatype is VARCHAR2.  (Note:  if multiple tab canvases have tab pages with identical names, you must provide a fully-qualified name for the tab page (i.e., MY_TAB_CVS.TAB_PAGE_1).


FIND_TAB_PAGE examples

/* Use FIND_TAB_PAGE to find the ID of the top-most tab

** page on tab canvas TAB_PAGE_1, then use the ID to set
** properties of the tab page:
*/
DECLARE
  tp_nm   VARCHAR2(30);
  tp_id   TAB_PAGE;

BEGIN
  tp_nm := GET_CANVAS_PROPERTY('tab_page_1', topmost_tab_page);
  tp_id := FIND_TAB_PAGE(tp_nm);
  SET_TAB_PAGE_PROPERTY(tp_id, visible, property_true);
  SET_TAB_PAGE_PROPERTY(tp_id, label, 'Order Info');
END;


FIND_TIMER built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of timers and returns a timer ID when it finds a valid timer with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of Timer.

Syntax

FUNCTION FIND_TIMER
  (timer_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  Timer

Enter Query Mode  yes

Parameters

timer_name	Specifies a valid VARCHAR2 timer name.


FIND_TIMER examples

/*

** Built-in:  FIND_TIMER
** Example:   If the timer exists, reset it. Otherwise create
**            it.
*/
PROCEDURE Reset_Timer_Interval( Timer_Name VARCHAR2,
                          Timer_Intv NUMBER ) IS
  tm_id       Timer;
  tm_interval NUMBER;
BEGIN
  /*
  ** User gives the interval in seconds, the timer subprograms
  ** expect milliseconds
  */
  tm_interval := 1000 * Timer_Intv;
  /* Lookup the timer by name */
  tm_id := Find_Timer(Timer_Name);
  /* If timer does not exist, create it */
  IF Id_Null(tm_id) THEN
    tm_id := Create_Timer(Timer_Name,tm_interval,NO_REPEAT);
  /*
  ** Otherwise, just restart the timer with the new interval
  */
  ELSE
    Set_Timer(tm_id,tm_interval,NO_REPEAT);
  END IF;
END;


FIND_TREE_NODE built-in

 Examples 	 All Built-ins

Description

Finds the next node in the tree whose label or value matches the search string.

Syntax

FUNCTION FIND_TREE_NODE

  (item_name VARCHAR2,

   search_string VARCHAR2,

   search_type NUMBER,

   search_by NUMBER,

   search_root NODE,

   start_point NODE);

FUNCTION FIND_TREE_NODE

  (item_id ITEM,

   search_string VARCHAR2,

   search_type NUMBER,

   search_by NUMBER,

   search_root NODE,

   start_point NODE);

Built-in Type   unrestricted function

Returns  NODE

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
search_string	Specifies the VARCHAR2 search string.
search_type	Specifies the NUMBER search type. Possible values are: FIND_NEXT FIND_NEXT_CHILD  Searches just the children of the search_root node.
search_by	Specifies the NUMBER to search by. Possible values are: NODE_LABEL NODE_VALUE
search_root	Specifies the root of the search tree.
start_point	Specifies the starting point in the NODE search.


FIND_TREE_NODE examples

/*

** Built-in:  FIND_TREE_NODE
*/

-- This code finds a node with a label of "Doran"

-- within the subtree beginning with the a node

-- with a label of "Zetie".

DECLARE

   htree         ITEM;

   find_node     Ftree.NODE;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Find the node with a label "Zetie".

   find_node := Ftree.Find_Tree_Node(htree, 'Zetie', Ftree.FIND_NEXT,

                 Ftree.NODE_LABEL, Ftree.ROOT_NODE, Ftree.ROOT_NODE);

   -- Find the node with a label "Doran"

   -- starting at the first occurance of "Zetie".

   find_node := Ftree.Find_Tree_Node(htree, 'Doran', Ftree.FIND_NEXT,

                Ftree.NODE_LABEL, find_node, find_node);

   IF NOT Ftree.ID_NULL(find_node) then

      ...

   END IF;

END;


FIND_VA built-in

 All Built-ins

Description

Searches for the visual attributes of an item in a given block and returns the value of that attribute as a text string.

Syntax

FUNCTION FIND_VA

  (va_name PROPERTY);

Built-in Type   unrestricted function

Returns  Visual Attribute

Enter Query Mode  yes

Parameters

va_name	The name you gave the visual attribute when you created it. The data type is VARCHAR2.


FIND_VIEW built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of canvases and returns a view ID when it finds a valid canvas with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of ViewPort.

Syntax

FUNCTION FIND_VIEW
  (viewcanvas_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  ViewPort

Enter Query Mode  yes

Parameters

viewcanvas_name	Specifies the VARCHAR2 name of the canvas.


FIND_VIEW examples

/*

** Built-in:  FIND_VIEW
** Example:  Change the visual attribute and display position
**           of a stacked view before making it visible to
**           the user.
*/
DECLARE
  vw_id ViewPort;
BEGIN
  vw_id := Find_View('Sales_Summary');
  Set_Canvas_Property('Sales_Summary', VISUAL_ATTRIBUTE,
              'Salmon_On_Yellow');
  Set_View_Property(vw_id, VIEWPORT_X_POS, 30);
  Set_View_Property(vw_id, VIEWPORT_Y_POS, 5);
  Set_View_Property(vw_id, VISIBLE, PROPERTY_TRUE);
END;


FIND_WINDOW built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of windows and returns a window ID when it finds a valid window with the given name.  You must define an appropriately typed variable to accept the return value.  Define the variable with a type of Window.

Syntax

FUNCTION FIND_WINDOW
  (window_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  Window

Enter Query Mode  yes

Parameters

window_name	Specifies the valid VARCHAR2 window name.


FIND_WINDOW examples

/*

** Built-in:  FIND_WINDOW
** Example:   Anchor the upper left corner of window2 at the
**            bottom right corner of window1.
*/
PROCEDURE Anchor_Bottom_Right( Window2 VARCHAR2, Window1
VARCHAR2) IS
  wn_id1 Window;
  wn_id2 Window;
  x      NUMBER;
  y      NUMBER;
  w      NUMBER;
  h      NUMBER;
BEGIN
  /*   ** Find Window1 and get its (x,y) position, width,
       ** and height.
  */
  wn_id1 := Find_Window(Window1);
  x      := Get_Window_Property(wn_id1,X_POS);
  y      := Get_Window_Property(wn_id1,Y_POS);
  w      := Get_Window_Property(wn_id1,WIDTH);
  h      := Get_Window_Property(wn_id1,HEIGHT);
  /*
  ** Anchor Window2 at (x+w,y+h)
  */
  wn_id2 := Find_Window(Window2);
  Set_Window_Property(wn_id2,X_POS, x+w );
  Set_Window_Property(wn_id2,Y_POS, y+h );
END;


FIRST_RECORD built-in

 Examples	     Related Topics	 All Built-ins

Description

Navigates to the first record in the block's list of records.

Syntax

PROCEDURE FIRST_RECORD;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


FIRST_RECORD examples

/*

** Built-in:  FIRST_RECORD
** Example:   Have a button toggle between the first and last
**            records in a block.
** Trigger:  When-Button-Pressed
*/
BEGIN
  /*
  ** If we're not at the bottom, then go to the last record
  */
  IF :System.Last_Record <> 'TRUE' THEN
    Last_Record;
  ELSE
    First_Record;
  END IF;
END;


FORM_FAILURE built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns a value that indicates the outcome of the action most recently performed during the current Runform session.

Outcome	Returned Value
success	FALSE
failure	TRUE
fatal error	FALSE

 If no action has executed in the current Runform session, FORM_FAILURE returns FALSE.

Use FORM_FAILURE to test the outcome of a built-in to determine further processing within any trigger.  To get the correct results, you must perform the test immediately after the action executes.  That is, another action should not occur prior to the test.

Note:  "Another action" includes both built-ins and PL/SQL assignment statements.  If another action occurs, FORM_FAILURE may not  reflect the status of the built-in you are testing, but of the other, more recently executed action.  A more accurate technique is, for example, when performing a COMMIT_FORM, to check that the SYSTEM.FORM_STATUS variable is set to 'QUERY' after the operation is done.

Syntax

FUNCTION FORM_FAILURE;

Built-in Type   unrestricted function

Returns  BOOLEAN

Enter Query Mode  yes

Parameters

none


FORM_FAILURE examples

/*

** Built-in:  FORM_FAILURE
** Example:   Determine if the most recently executed built-in
**            failed.
*/
BEGIN
  GO_BLOCK('Success_Factor');
  /*
  ** If some validation failed and prevented us from leaving
  ** the current block, then stop executing this trigger.
  **
  ** Generally it is recommended to test
  **     IF NOT Form_Success THEN ...
  ** Rather than explicitly testing for FORM_FAILURE
  */
  IF Form_Failure THEN
    RAISE Form_Trigger_Failure;
  END IF;
END;


FORM_FATAL built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the outcome of the action most recently performed during the current Runform session.

Outcome	Returned Value
success	FALSE
failure	FALSE
fatal error	TRUE

 Use FORM_FATAL to test the outcome of a built-in to determine further processing within any trigger.  To get the correct results, you must perform the test immediately after the action executes.  That is, another action should not occur prior to the test.

Note:  "Another action" includes both built-ins and PL/SQL assignment statements.  If another action occurs, FORM_FATAL may not  reflect the status of the built-in you are testing, but of the other, more recently executed action.  A more accurate technique is, for example, when performing a COMMIT_FORM, to check that the SYSTEM.FORM_STATUS variable is set to 'QUERY' after the operation is done.

Syntax

FUNCTION FORM_FATAL;

Built-in Type   unrestricted function

Return Type:

BOOLEAN

Enter Query Mode  yes

Parameters

none


FORM_FATAL examples

/*

** Built-in:  FORM_FATAL
** Example:   Check whether the most-recently executed built-in
**            had a fatal error.
*/
BEGIN
  User_Exit('Calculate_Line_Integral control.start control.stop');
  /*
  ** If the user exit code returned a fatal error, print a
  ** message and stop executing this trigger.
  **
  ** Generally it is recommended to test   **
  **     IF NOT FORM_SUCCESS THEN ...   **
  ** Rather than explicitly testing for FORM_FATAL
  */

  IF Form_Fatal THEN
    Message('Cannot calculate the Line Integral due to internal
             error.');
    RAISE Form_Trigger_Failure;
  END IF;
END;


FORM_SUCCESS built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the outcome of the action most recently performed during the current Runform session.

Outcome	Returned Value
success	TRUE
failure	FALSE
fatal error	FALSE
Syntax

FUNCTION FORM_SUCCESS;

Built-in Type   unrestricted function

Return Type:

BOOLEAN

Enter Query Mode  yes

Parameters

none

Usage Notes

•	Use FORM_SUCCESS to test the outcome of a built-in to determine further processing within any trigger.  To get the correct results, you must perform the test immediately after the action executes.  That is, another action should not occur prior to the test. "Another action" includes both built-ins and PL/SQL assignment statements.   If another action occurs, FORM_SUCCESS may not reflect the status of the built-in you are testing, but of the other, more recently executed action.

•	FORM_SUCCESS should not be used to test whether a COMMIT_FORM or POST built-in has succeeded.  Because COMMIT_FORM may cause many other triggers to fire, when you evaluate FORM_SUCCESS it may not reflect the status of COMMIT_FORM but of some other, more recently executed built-in.  A more accurate technique is to check that the SYSTEM.FORM_STATUS variable is set to 'QUERY' after the operation is done.

•	On Microsoft Windows NT, when using HOST to execute a 16-bit application, the FORM_SUCCESS built-in will return TRUE whether the application succeeds or fails.  This is a Microsoft a Win32 issue.  32-bit applications and OS commands will correctly return TRUE if executed sucessfully and FALSE if failed.  Invalid commands will return FALSE.

•	On Windows 95 platforms the FORM_SUCCESS built-in will always return TRUE for HOST commands which fail.  This includes calls to command.com or OS functions, any 16-bit DOS or GUI application, or an invalid command.  FORM_SUCCESS will return TRUE for 32-bit applications executed sucessfully and FALSE if failed.


FORM_SUCCESS examples

/*

** Built-in:  FORM_SUCCESS
** Example:   Check whether the most-recently executed built-in
**            succeeded.
*/
BEGIN
  /*
  ** Force validation to occur
  */
  Enter;
  /*
  ** If the validation succeeded, then Commit the data.
  **

  */
  IF Form_Success THEN
    Commit;
    IF :System.Form_Status <> 'QUERY' THEN
      Message('Error prevented Commit');
      RAISE Form_Trigger_Failure;
    END IF;
  END IF;
END;


FORMS_DDL built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Issues dynamic SQL statements at runtime, including server-side PL/SQL and DDL.

Note:  All DDL operations issue an implicit COMMIT and will end the current transaction without allowing Form Builder to process any pending changes.

Syntax

FUNCTION FORMS_DDL
  (statement  VARCHAR2);

Built-in Type   unrestricted function

Enter Query Mode  yes

Parameters

statement	Any string expression up to 32K:

•	a literal

•	an expression or a variable representing the text of a block of dynamically created PL/SQL code

•	a DML statement or

•	a DDL statement

Usage Notes

Commit (or roll back) all pending changes before you issue the FORMS_DDL command.  All DDL operations issue an implicit COMMIT and will end the current transaction without allowing Form Builder to process any pending changes, as well as losing any locks Form Builder may have acquired.

Some supplied stored procedures issue COMMIT or ROLLBACK commands as part of their logic.  Make sure all pending changes in the form are committed or rolled back before you call those built-ins.  Use the SYSTEM.FORM_STATUS variable to check whether there are pending changes in the current form before you issue the FORMS_DDL command.  (See Example 4.)

If you use FORMS_DDL to execute a valid PL/SQL block:

•	Use semicolons where appropriate.

•	Enclose the PL/SQL block in a valid BEGIN/END block structure.

•	Do not end the PL/SQL block with a slash.

•	Line breaks, while permitted, are not required.

If you use FORMS_DDL to execute a single DML or DDL statement:

•	Omit the trailing semicolon to avoid an invalid character error.

To check whether the statement issued using FORMS_DDL executed correctly, use the FORM_SUCCESS or FORM_FAILURE Boolean functions. If the statement did not execute correctly, check the error code and error text using DBMS_ERROR_CODE and  DBMS_ERROR_TEXT.  Note that the values of DBMS_ERROR_CODE and DBMS_ERROR_TEXT are not automatically reset following successful execution, so their values should only be examined after an error has been detected by a call to FORM_SUCCESS or FORM_FAILURE.


FORMS_DDL restrictions

The statement you pass to FORMS_DDL may not contain bind variable references in the string, but the values of bind variables can be concatenated into the string before passing the result to FORMS_DDL.  For example, this statement is not valid:

Forms_DDL ('Begin Update_Employee (:emp.empno); End;');

However, this statement is valid, and would have the desired effect:

Forms_DDL ('Begin Update_Employee ('||TO_CHAR(:emp.empno)
      ||');End;');

However, you could also call a stored procedure directly, using Oracle8's shared SQL area over multiple executions with different values for emp.empno:

Update_Employee (:emp.empno);

SQL statements and PL/SQL blocks executed using FORMS_DDL cannot return results to Form Builder directly.  (See Example 4.)

In addition, some DDL operations cannot be performed using FORMS_DDL, such as dropping a table or database link, if Form Builder is holding a cursor open against the object being operated upon.


FORMS_DDL examples

Example 1

/*

** Built-in:  FORMS_DDL
** Example:   The expression can be a string literal.
*/
BEGIN
  Forms_DDL('create table temp(n NUMBER)');
  IF NOT Form_Success THEN
    Message ('Table Creation Failed');
  ELSE
    Message ('Table Created');
  END IF;
END;

Example 2

/*

** Built-in:  FORMS_DDL
** Example:   The string can be an expression or variable.
**            Create a table with n Number columns.
**            TEMP(COL1, COL2, ..., COLn).
*/
PROCEDURE Create_N_Column_Number_Table (n NUMBER) IS
  my_stmt VARCHAR2(2000);
BEGIN
  my_stmt := 'create table tmp(COL1 NUMBER';
  FOR I in 2..N LOOP
    my_stmt := my_stmt||',COL'||TO_CHAR(i)||' NUMBER';
  END LOOP;
  my_stmt := my_stmt||')';
  /*
  ** Now, create the table...
  */
  Forms_DDL(my_stmt);
  IF NOT Form_Success THEN
    Message ('Table Creation Failed');
  ELSE
    Message ('Table Created');
  END IF;
END;

Example 3:

/*

** Built-in:  FORMS_DDL
** Example:   The statement parameter can be a block
**            of dynamically created PL/SQL code.
*/
DECLARE
  procname VARCHAR2(30);
BEGIN
  IF :global.flag = 'TRUE' THEN
    procname := 'Assign_New_Employer';
  ELSE
    procname := 'Update_New_Employer';
  END IF;
  Forms_DDL('Begin '|| procname ||'; End;');
  IF NOT Form_Success THEN
    Message ('Employee Maintenance Failed');
  ELSE
    Message ('Employee Maintenance Successful');
  END IF;
END;

Example 4:

/*

** Built-in:  FORMS_DDL
** Example:  Issue the SQL statement passed in as an argument,
**           and return a number representing the outcome of
**           executing the SQL statement.
**           A result of zero represents success.
*/
FUNCTION Do_Sql (stmt VARCHAR2, check_for_locks BOOLEAN := TRUE)
RETURN NUMBER
IS
  SQL_SUCCESS CONSTANT NUMBER := 0;
BEGIN
  IF stmt IS NULL THEN
    Message ('DO_SQL: Passed a null statement.');
    RETURN SQL_SUCCESS;
  END IF;
  IF Check_For_Locks AND :System.Form_Status = 'CHANGED' THEN
    Message ('DO_SQL: Form has outstanding locks pending.');
    RETURN SQL_SUCCESS;
  END IF;
    Forms_DDL(stmt);
  IF Form_Success THEN
    RETURN SQL_SUCCESS;
  ELSE
    RETURN Dbms_Error_Code;
  END IF;
END;


GENERATE_SEQUENCE_NUMBER built-in

 Examples	   Restrictions	 All Built-ins

Description

Initiates the default Form Builder processing for generating a unique sequence number when a record is created.  When a sequence object is defined in the database, you can reference it as a default value for an item by setting the Initial Value property to SEQUENCE.my_seq.NEXTVAL.  By default, Form Builder gets the next value from the sequence whenever a record is created.  When you are connecting to a non-ORACLE data source, you can include a call to this built-in in the On-Sequence-Number trigger

Syntax

PROCEDURE GENERATE_SEQUENCE_NUMBER;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


GENERATE_SEQUENCE_NUMBER restrictions

Valid only in an On-Sequence-Number trigger.


GENERATE_SEQUENCE_NUMBER examples

/*

** Built-in:  GENERATE_SEQUENCE_NUMBER
** Example:   Perform Form Builder standard sequence number
**            processing based on a global flag setup at
**            startup by the form, perhaps based on a
**            parameter.
** Trigger:   On-Sequence-Number
*/
BEGIN
  /*
  ** Check the global flag we setup at form startup
  */
  IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
    User_Exit('my_seqnum seq=EMPNO_SEQ');
  /*
  ** Otherwise, do the right thing.
  */
  ELSE
    Generate_Sequence_Number;
  END IF;
END;


GET_APPLICATION_PROPERTY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Returns information about the current Form Builder application.  You must call the built-in once for each value you want to retrieve.

Syntax

FUNCTION GET_APPLICATION_PROPERTY
  (property  NUMBER);

Built-in Type   unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

property	Specify one of the following constants to return information about your application:

APPLICATION_INSTANCE  Returns the pointer value  of an instance handle.  Only applies to the Microsoft Windows platform.  For all other platforms, Form Builder returns NULL.

BUILTIN_DATE_FORMAT   Returns the current value of the Builtin date format mask (which is held in the Builtin_Date_Format property).

CALLING_FORM  Returns the name of the calling form if the current form was invoked by the CALL_FORM built-in.  If the current form is not a called form, Form Builder returns NULL.

CONNECT_STRING  Returns the database connect string of the current operator.  If the current operator does not have a connect string,  Form Builder returns NULL.

CURRENT_FORM  Returns the .FMX file name of the form currently being executed.

CURRENT_FORM_NAME  Returns the name of the current form as indicated by the form module Name property.

CURSOR_STYLE  Returns the name of the current cursor style property.  Valid VARCHAR2 return values are BUSY, CROSSHAIR, DEFAULT,  HELP, and INSERTION.

DATASOURCE  Returns the name of the database that is currently in use.  Valid return values are NULL, ORACLE, DB2, NONSTOP, TERADATA, NCR/3600/NCR/3700, and SQLSERVER.  This call returns the database name only for connections established by Form Builder, not for connections established by On-Logon triggers.

DATE_FORMAT_COMPATIBILITY_MODE  Returns the compatibility setting contained in this property.

DISPLAY_HEIGHT  Returns the height of the display.  The size of each unit depends on how you defined the Coordinate System property for the form module.

DISPLAY_WIDTH  Returns the width of the display.  The size of each unit depends on how you defined the Coordinate System property for the form module.

ERROR_DATE/DATETIME_FORMAT Returns the current value of the error date or datetime format mask (which is established in the FORMSnn_Error_Date/Datetime_Format environment variable).

FLAG_USER_VALUE_TOO_LONG   Returns the current value of this property, either ‘TRUE’ or ‘FALSE’, which controls truncation of user-entered values that exceed an item’s Maximum Length property.

OPERATING_SYSTEM  Returns the name of the operating system that is currently in use.  Valid return values are MSWINDOWS, MSWINDOWS32, WIN32COMMON, UNIX, SunOS, MACINTOSH, VMS, and HP-UX.

OUTPUT_DATE/DATETIME_FORMAT Returns the current value of the output date or datetime format mask (which is established in the FORMSnn_Output_Date/Datetime_Format environment variable).

PASSWORD  Returns the password of the current operator.

PLSQL_DATE_FORMAT Returns the current value of the PLSQL date format mask (which is held in the PLSQL_Date_Format property).

RUNTIME_COMPATIBILITY_MODE  Returns the compatibility setting contained in this property.

SAVEPOINT_NAME  Returns the name of the last savepoint Form Builder has issued.  This call is valid only from an On-Savepoint or On-Rollback trigger.  It is included primarily for developers who are using transactional triggers to access a non-ORACLE data source.

TIMER_NAME  Returns the name of the most recently expired timer.  Form Builder returns NULL in response to this constant if there is no timer.

USER_DATE/DATETIME_FORMAT  Returns the current value of the user date or datetime format mask (which is established in the FORMSnn_User_Date/Datetime_Format environment variable).

USER_INTERFACE  Returns the name of the user interface that is currently in use.  Valid return values are MOTIF, MACINTOSH, MSWINDOWS, MSWINDOWS32, WIN32COMMON, WEB, PM, CHARMODE, BLOCKMODE, X, and UNKNOWN.

USER_NLS_CHARACTER_SET  Returns the current value of the character set portion only of the USER_NLS_LANG environment variable defined for the form operator. If USER_NLS_LANG is not explicitly set, it defaults to the setting of NLS_LANG.

USER_NLS_LANG  Returns the complete current value of the USER_NLS_LANG environment variable defined for the form operator, for national language support. If USER_NLS_LANG is not explicitly set, it defaults to the setting of NLS_LANG.  USER_NLS_LANG is the equivalent of concatenating USER_NLS_LANGUAGE, USER_NLS_TERRITORY, and USER_NLS_CHARACTER_SET.

USER_NLS_LANGUAGE  Returns the current value of the language portion only of the USER_NLS_LANG environment variable defined for the form operator.  If USER_NLS_LANG is not explicitly set, it defaults to the setting of NLS_LANG.

USER_NLS_TERRITORY  Returns the current value of the territory portion only of the USER_NLS_LANG environment variable defined for the form operator.  If USER_NLS_LANG is not explicitly set, it defaults to the setting of NLS_LANG

USERNAME  Returns the name of the current operator.  Note: If the user connects by using an OPS$ account, GET_APPLICATION_PROPERTY(USERNAME) will not return the actual username. In this case, you should use GET_APPLICATION_PROPERTY(CONNECT_STRING) to retrieve username information.

Usage Notes

To request a complete login, including an appended connect string, use the Username, Password, and Connect_String properties.  For instance, assume that the user has initiated an Microsoft Windows Runform session specifying the following connect string:

ifrun60 my_form scott/tiger@corpDB1

Form Builder returns the following string as the result of a call to GET_APPLICATION_PROPERTY(USERNAME):

scott

Form Builder returns the following string as the result of a call to GET_APPLICATION_PROPERTY(PASSWORD):

tiger

Form Builder returns the following string as the result of a call to GET_APPLICATION_PROPERTY(CONNECT_STRING):

corpDB1


GET_APPLICATION_PROPERTY restrictions

To retrieve the timer name of the most recently executed timer, you must initiate a call to GET_APPLICATION_PROPERTY from within a When-Timer-Expired trigger.  Otherwise, the results of the built-in are undefined.


GET_APPLICATION_PROPERTY examples

Example 1

/*

** Built-in:  GET_APPLICATION_PROPERTY
** Example:   Determine the name of the timer that just
**            expired, and based on the username perform a
**            task.
** Trigger:   When-Timer-Expired
*/
DECLARE
  tm_name  VARCHAR2(40);
BEGIN
  tm_name  := Get_Application_Property(TIMER_NAME);

  IF tm_name = 'MY_ONCE_EVERY_FIVE_MINUTES_TIMER' THEN

  :control.onscreen_clock := SYSDATE;

  ELSIF tm_name = 'MY_ONCE_PER_HOUR_TIMER' THEN

    Go_Block('connected_users');
    Execute_Query;

  END IF;
END;

Example 2

/*

** Built-in:  GET_APPLICATION_PROPERTY
** Example:   Capture the username and password of the
**            currently logged-on user, for use in calling
**            another Tool.
*/
PROCEDURE Get_Connect_Info( the_username IN OUT VARCHAR2,
              the_password IN OUT VARCHAR2,
              the_connect  IN OUT VARCHAR2) IS
BEGIN
  the_username := Get_Application_Property(USERNAME);
  the_password := Get_Application_Property(PASSWORD);
  the_connect  := Get_Application_Property(CONNECT_STRING);
END;


GET_BLOCK_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns information about a specified block. You must issue a call to the built-in once for each property value you want to retrieve.

Syntax

FUNCTION GET_BLOCK_PROPERTY
  (block_id  Block,
   property  NUMBER);

FUNCTION GET_BLOCK_PROPERTY
  (block_name  VARCHAR2,
   property    NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

block_id	The unique ID Form Builder assigned to the block when you created it.  Datatype is BLOCK.

block_name	The name you gave the block when you created it.  Datatype is VARCHAR2.

property	Specify one of the following constants to return information about the given block:

ALL_RECORDS Specifies whether all the records matching the query criteria should be fetched into the data block when a query is executed.

BLOCKSCROLLBAR_X_POS  Returns the x position of the block's scroll bar as a number specified in the form coordinate units indicated by the Coordinate System form property.

BLOCKSCROLLBAR_Y_POS   Returns the y position of the block's scroll bar as a number specified in the form coordinate units indicated by the Coordinate System form property.

COLUMN_SECURITY  Returns the VARCHAR2 value of TRUE if column security is set to Yes, and the VARCHAR2 string FALSE if it is set to No.

COORDINATION_STATUS  For a block that is a detail block in a master-detail block relation, this property specifies the coordination status of the block with respect to its master block(s).  Returns the VARCHAR2 value COORDINATED if the block is coordinated with all of its master blocks.  If it is not coordinated with all of its master blocks, the built-in returns the VARCHAR2 value NON_COORDINATED. Immediately after records are fetched to the detail block, the status of the detail block is COORDINATED.  When a different record becomes the current record in the master block, the status of the detail block again becomes NON_COORDINATED.

CURRENT_RECORD  Returns the number of the current record.

CURRENT_RECORD_ATTRIBUTE  Returns the VARCHAR2 name of the named visual attribute of the given block.

CURRENT_ROW_BACKGROUND_COLOR  The color of the object's background region.

CURRENT_ROW_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

CURRENT_ROW_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

CURRENT_ROW_FONT_SIZE  The size of the font, specified in points.

CURRENT_ROW_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

CURRENT_ROW_FONT_STYLE  The style of the font.

CURRENT_ROW_FONT_WEIGHT The weight of the font.

CURRENT_ROW_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

CURRENT_ROW_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

DEFAULT_WHERE Returns the default WHERE clause in effect for the block, as indicated by the current setting of the WHERE block property.

DELETE_ALLOWED  Returns the VARCHAR2 value TRUE if the Delete Allowed block property is Yes, FALSE if it is No.  This property determines whether the operator or the application is allowed to delete records in the block.

DML_DATA_TARGET_NAME  Returns the VARCHAR2 name of the block's DML data source.

DML_DATA_TARGET_TYPE  Returns the VARCHAR2 value that indicates the current setting of the DML Data Target Type property.  Return values for this property are NONE, TABLE, STORED PROCEDURE, or TRANSACTIONAL TRIGGER.

ENFORCE_PRIMARY_KEY  Returns the VARCHAR2 value TRUE if the Enforce Primary Key property is set to Yes for the block.  Otherwise, if the Enforce Primary Key property is set to No, this parameter returns the VARCHAR2 value FALSE.

ENTERABLE   Returns the VARCHAR2 value TRUE if the block is enterable, that is, if any item in the block has its Enabled and Keyboard Navigable properties set to Yes.  Returns the VARCHAR2 string FALSE if the block is not enterable.

FIRST_DETAIL_RELATION  Returns the VARCHAR2 name of the first relation in which the given block is a detail.  Returns NULL if one does not exist.

FIRST_ITEM  Returns the VARCHAR2 name of the first item in the given block.

FIRST_MASTER_RELATION  Returns the VARCHAR2 name of the first relation in which the given block is a master.  Returns NULL if one does not exist.

INSERT_ALLOWED  Returns the VARCHAR2 value TRUE if the Insert Allowed block property is Yes, FALSE if it is No.  This property determines whether the operator or the application is allowed to insert records in the block.

KEY_MODE  Returns the VARCHAR2 value that indicates the current setting of the Key Mode block property.  Return values for this property are UNIQUE_KEY, UPDATEABLE_PRIMARY_KEY, or NON_UPDATEABLE_PRIMARY_KEY.

LAST_ITEM  Returns the name of the last item in the given block.

LAST_QUERY  Returns the SQL statement of the last query in the specified block.

LOCKING_MODE  Returns the VARCHAR2 value IMMEDIATE if rows are to be locked immediately on a change to a base table item; otherwise, it returns the VARCHAR2 value DELAYED if row locks are to be attempted just prior to a commit.

MAX_QUERY_TIME Returns the VARCHAR2 value that indicates the current setting of the Maximum Query Time property.  This property determines whether the operator can abort a query when the elapsed time of the query exceeds the value of this property.

MAX_RECORDS_FETCHED  Returns a number representing the maximum number of records that can be fetched.  This property is only useful when the Query All Records property is set to Yes.

NAVIGATION_STYLE  Returns the VARCHAR2 value that indicates the current setting of the block's NAVIGATION_STYLE property, either SAME_RECORD, CHANGE_RECORD, or CHANGE_BLOCK.

NEXTBLOCK  Returns the name of the next block.  Returns NULL if the indicated block is the last block in the form.  Note that the setting of the block's NEXT_NAVIGATION_BLOCK property has no effect on the value of NEXTBLOCK.

NEXT_NAVIGATION_BLOCK  Returns the VARCHAR2 name of the block's next navigation block.  By default, the next navigation block is the next block as defined by the order of blocks in the Object Navigator; however, the NEXT_NAVIGATION_BLOCK block property can be set to override the default block navigation sequence.

OPTIMIZER_HINT  Returns a hint in the form of a VARCHAR2 string that Form Builder passes on to the RDBMS optimizer when constructing queries.

ORDER_BY  Returns the default ORDER BY clause in effect for the block, as indicated by the current setting of the ORDER BY block property.

PRECOMPUTE_SUMMARIES[Under Construction]

PREVIOUSBLOCK  Returns the name of the block that has the next lower sequence in the form, as defined by the order of blocks in the Object Navigator.  Returns NULL if the indicated block is the first block in the form.  Note that the setting of the block's PREVIOUS_NAVIGATION_BLOCK property has no effect on the value of PREVIOUSBLOCK.

PREVIOUS_NAVIGATION_BLOCK  Returns the VARCHAR2 name of the block's previous navigation block.  By default, the previous navigation block is the block with the next lower sequence, as defined by the order of blocks in the Object Navigator; however, the NEXT_NAVIGATION_BLOCK block property can be set to override the default block navigation sequence.

QUERY_ALLOWED  Returns the VARCHAR2 value TRUE if the Query Allowed block property is Yes, FALSE if it is No.  This property determines whether the operator or the application is allowed to query records in the block.

QUERY_DATA_SOURCE_NAME  Returns the VARCHAR2 name of the block's query data source.

QUERY_DATA_SOURCE_TYPE  Returns the VARCHAR2 value that indicates the current setting of the Query Data Source Type property.  Return values for this property are NONE, TABLE, STORED PROCEDURE, TRANSACTIONAL TRIGGER, or SUB-QUERY.

QUERY_HITS  Returns the VARCHAR2 value that indicates the number of records identified by the COUNT_QUERY operation.  If this value is examined while records are being retrieved from a query, QUERY_HITS specifies the number of records that have been retrieved.

QUERY_OPTIONS  Returns the VARCHAR2 values VIEW, FOR_UPDATE, COUNT_QUERY, or a null value if there are no options.  You can call GET_BLOCK_PROPERTY with this parameter from within a transactional trigger when your user exit needs to know what type of query operation Form Builder would be doing by default if you had not circumvented default processing.

RECORDS_DISPLAYED  Returns the number of records that the given block can display.  Corresponds to the Number of Records Displayed block property.

RECORDS_TO_FETCH  Returns the number of records Form Builder expects an On-Fetch trigger to fetch and create as queried records.

STATUS  Returns the VARCHAR2 value NEW if the block contains only new records, CHANGED if the block contains at least one changed record, and QUERY if the block contains only valid records that have been retrieved from the database.

TOP_RECORD  Returns the record number of the topmost visible record in the given block.

UPDATE_ALLOWED  Returns the VARCHAR2 value TRUE if the Update Allowed block property is Yes, FALSE if it is No.  This property determines whether the operator or the application is allowed to update records in the block.

UPDATE_CHANGED_COLUMNS  Specifies that only those columns updated by an operator will be sent to the database.  When Update Changed Columns Only is set to No, all columns are sent, regardless of whether they have been updated.  This can result in considerable network traffic, particularly if the block contains a LONG data type.


GET_BLOCK_PROPERTY examples

/*

** Built-in:  GET_BLOCK_PROPERTY
** Example:   Return the screen line of the current record in
**            a multi-record block. Could be used to
**            dynamically position LOV to a place on the
**            screen above or below the current line so as to
**            not obscure the current record in question.
*/
FUNCTION Current_Screen_Line
RETURN NUMBER IS
  cur_blk VARCHAR2(40) := :System.Cursor_Block;
  cur_rec NUMBER;
  top_rec NUMBER;
  itm_lin NUMBER;
  cur_lin NUMBER;
  bk_id   Block;
BEGIN
  /*
  ** Get the block id since we'll be doing multiple
  ** Get_Block_Property operations for the same block
  */
  bk_id := Find_Block( cur_blk );
  /*
  ** Determine the (1) Current Record the cursor is in,
  **               (2) Current Record which is visible at the
  **                   first (top) line of the multirecord
  **                   block.
  */
  cur_rec := Get_Block_Property( bk_id, CURRENT_RECORD);
  top_rec := Get_Block_Property( bk_id, TOP_RECORD);
  /*
  ** Determine the position on the screen the first field in
  ** the multirecord block
  */
  itm_lin := Get_Item_Property( Get_Block_Property
                     (bk_id,FIRST_ITEM),Y_POS);
  /*
  ** Add the difference between the current record and the
  ** top record visible in the block to the screen position
  ** of the first item in the block to get the screen
  ** position of the current record:
  */
  cur_lin := itm_lin + (cur_rec - top_rec);
  RETURN cur_lin;
END;


GET_CANVAS_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the given canvas property for the given canvas. .

Syntax

FUNCTION GET_CANVAS_PROPERTY
  (canvas_id  Canvas,
   property   NUMBER);

FUNCTION GET_CANVAS_PROPERTY
  (canvas_name  VARCHAR2,
   property     NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

canvas_id	The unique ID that Form Builder assigns the canvas object when it creates it.  Use the FIND_CANVAS built-in to return the ID to a variable with datatype of CANVAS.

canvas_name	The name you gave the canvas object when you defined it.

property	The property for which you want to get a value for the given canvas.  You can enter the following constants for return values:

BACKGROUND_COLOR  The color of the object's background region.

FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE  The size of the font, specified in points.

FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE  The style of the font.

FONT_WEIGHT  The weight of the font.

FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

HEIGHT  Returns the height of the canvas, specified in the form coordinate units indicated by the Coordinate System form property.

TAB_PAGE_X_OFFSET  Returns the distance between the left edge of the tab canvas and the left edge of the tab page.  The value returned depends on the form coordinate system—pixel, centimeter, inch, or point.

TAB_PAGE_Y_OFFSET  Returns the distance between the top edge of the tab canvas and the top edge of the tab page.  The value returned depends on the form coordinate system—pixel, centimeter, inch, or point.

TOPMOST_TAB_PAGE  Returns the name of the tab page currently top-most on the named tab canvas.

WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

WIDTH  Returns the width of the canvas, specified in the form coordinate units indicated by the Coordinate System form property.

VISUAL_ATTRIBUTE   Returns the name of the visual attribute currently in force.  If no named visual attribute is assigned to the canvas, returns CUSTOM for a custom visual attribute or DEFAULT for a default visual attribute.


GET_CANVAS_PROPERTY examples

/*

** Built-in:  GET_CANVAS_PROPERTY
** Example:   Can get the width/height of the canvas.
*/
DECLARE
  the_width  NUMBER;
  the_height NUMBER;
  cn_id      CANVAS;
BEGIN
  cn_id      := FIND_CANVAS('my_canvas_1');
  the_width  := GET_CANVAS_PROPERTY(cn_id, WIDTH);
  the_height := GET_CANVAS_PROPERTY(cn_id,HEIGHT);
END;


GET_CUSTOM_PROPERTY built-in

  Related Topics

Description

Gets the value of a user-defined property in a Java pluggable component.

Syntax

The built-in returns a VARCHAR2 value containing the string, numeric, or boolean data.

GET_CUSTOM_PROPERTY
  (item,
   row-number,
   prop-name);

Built-in Type  unrestricted procedure

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

item	The name or ID of the item associated with the target Java pluggable component. The name can be in the form of either a varchar2 literal or a variable set to the value of the name.

row-number	The row number of the instance of the item that you want to get.  (Instance row numbers begin with 1.)

prop-name	The particular property of the Java component that you want to get.

Usage Notes

•	In the Java pluggable component, each custom property type must be represented by a single instance of the ID class, created by using ID.registerProperty.

•	For each Get_Custom_Property built-in executed in the form, the Java component’s getProperty method is called.

•	The name of the item can be gained through either Find_Item(‘Item_Name’), or simply via ‘Item_Name’.


GET_FILE_NAME built-in

 Examples	 All Built-ins

Description

Displays the standard open file dialog box where the user can select an existing file or specify a new file.

Syntax

FUNCTION GET_FILE_NAME
  (directory_name   VARCHAR2,
   file_name        VARCHAR2,
   file_filter      VARCHAR2,
   message          VARCHAR2,
   dialog_type      NUMBER,
   select_file      BOOLEAN;

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

directory_name	Specifies the name of the directory containing the file you want to open.  The default value is NULL.  If directory_name is NULL, subsequent invocations of the dialog may open the last directory visited.

file_name	Specifies the name of the file you want to open.  The default value is NULL.

file_filter	Specifies that only particular files be shown.  The default value is NULL.  File filters take on different forms, and currently are ignored on the motif and character mode platforms.  On Windows, they take the form of “Write Files (*.WRI)|*.WRI|” defaulting to “All Files (*.*)|*.*|” if NULL.  On the Macintosh the attribute currently accepts a string such as “Text.”

message	Specifies the type of file that is being selected.  The default value is NULL.

dialog_type	Specifies the intended dialog to OPEN_FILE or SAVE_FILE.  The default value is OPEN_FILE.

select_file	Specifies whether the user is selecting files or directories.  The default value is TRUE.  If dialog_type is set to SAVE_FILE, select_file is internally set to TRUE.


GET_FILE_NAME examples

/*

** Built-in:  GET_FILE_NAME
** Example:   Can get an image of type TIFF.
*/
DECLARE
  filename VARCHAR2(256)
BEGIN
  filename := GET_FILE_NAME(File_Filter=> 'TIFF Files (*.tif)|*.tif|');
  READ_IMAGE_FILE(filename, 'TIFF', 'block5.imagefld);
END;


GET_FORM_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns information about the given form.  If your application is a multi-form application, then you can call this built-in to return information about the calling form, as well as about the current, or called form.

Syntax

FUNCTION GET_FORM_PROPERTY
  (formmodule_id  FormModule,
   property       NUMBER);

FUNCTION GET_FORM_PROPERTY
  (formmodule_name  VARCHAR2,
   property         NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

formmodule_id	Specifies the unique ID Form Builder assigns when it creates the form module.  Use the FIND_FORM built-in to return the ID to an appropriately typed variable.  The data type of the ID is FormModule.

formmodule_name	Specifies the VARCHAR2 name that you gave to the form module when you defined it.

property	Returns information about specific elements of the form based on which of the following constants are supplied to the built-in:

CHARACTER_CELL_HEIGHT Returns the dimensions of the character cell in the form units specified by the Coordinate System property.  When Coordinate System is Character Cells, the value is returned in pixels.

CHARACTER_CELL_WIDTH Returns the dimensions of the character cell in the form units specified by the Coordinate System property. When Coordinate System is Character Cells, the value is returned in pixels.

COORDINATE_SYSTEM Returns a VARCHAR2 string indicating the coordinate system used in the form module.

•	CHARACTER_CELL if the current coordinate system for the form is character cell based.

•	POINTS if the current coordinate system for the form is points.

•	CENTIMETERS if the current coordinate system for the form is centimeters.

•	INCHES if the current coordinate system for the form is inches.

•	PIXELS if the current coordinate system for the form is pixels.

CURRENT_RECORD_ATTRIBUTE  Returns the VARCHAR2 name of the named visual attribute that should be used for the current row.

CURRENT_ROW_BACKGROUND_COLOR  The color of the object's background region.

CURRENT_ROW_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

CURRENT_ROW_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

CURRENT_ROW_FONT_SIZE  The size of the font, specified in points.

CURRENT_ROW_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

CURRENT_ROW_FONT_STYLE  The style of the font.

CURRENT_ROW_FONT_WEIGHT The weight of the font.

CURRENT_ROW_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

CURRENT_ROW_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

CURSOR_MODE  Returns the setting that indicates the intended effect of a commit action on existing cursors.

DEFER_REQUIRED_ENFORCEMENT  Returns the setting that indicates whether enforcement of required fields has been deferred from item validation to record validation.  Valid return values are TRUE, 4.5, and FALSE.

DIRECTION   Returns the layout direction for bidirectional objects.  Valid return values are RIGHT_TO_LEFT, LEFT_TO_RIGHT.

FILE_NAME  Returns the name of the file where the named form is stored.

FIRST_BLOCK  Returns the name of the block with the lowest sequence number in the indicated form.

FIRST_NAVIGATION_BLOCK  Returns the name of the block into which Form Builder attempts to navigate at form startup.  By default, the first navigation block is the first block defined in the Object Navigator; however, the FIRST_NAVIGATION_BLOCK block property can be set to specify a different block as the first block at form startup.

FORM_NAME Returns the name of the form.

INTERACTION_MODE Returns the interaction mode for the form. Valid return values are BLOCKING or NONBLOCKING.

ISOLATION_MODE Returns the form’s isolation mode setting, either READ_COMMITTED or SERIALIZABLE.

LAST_BLOCK  Returns the name of the block with the highest sequence number in the indicated form.

MAX_QUERY_TIME Returns the VARCHAR2 value that indicates the current setting of the Maximum Query Time property.  This property determines whether the operator can abort a query when the elapsed time of the query exceeds the value of this property.

MAX_RECORDS_FETCHED  Returns a number representing the maximum number of records that can be fetched.  This property is only useful when the Query All Records property is set to Yes.

MODULE_NLS_CHARACTER_SET  Returns the current value of the character set portion only of the DEVELOPER_NLS_LANG environment variable defined for the form.  If DEVELOPER_NLS_LANG is not explicitly set, it defaults to the setting of NLS_LANG.

MODULE_NLS_LANG  Returns the complete current value for national language support contained in the DEVELOPER_NLS_LANG environment variable defined for the form.  If DEVELOPER_NLS_LANG is not explicitly set, it defaults to the setting of NLS_LANG.   MODULE_NLS_LANG is the equivalent of concatenating MODULE_NLS_LANGUAGE, MODULE_NLS_TERRITORY, and MODULE_NLS_CHACTER_SET.

MODULE_NLS_LANGUAGE  Returns the current value of the language portion only of the DEVELOPER_NLS_LANG environment variable defined for the form. If DEVELOPER_NLS_LANG is not explicitly set, it defaults to the setting of NLS_LANG.

MODULE_NLS_TERRITORY  Returns the current value of the territory portion only of the DEVELOPER_NLS_LANG environment variable defined for the form. If DEVELOPER_NLS_LANG is not explicitly set, it defaults to the setting of NLS_LANG.

SAVEPOINT_MODE  Returns PROPERTY_ON or PROPERTY_OFF  to indicate whether savepoints are supported in the data source.

VALIDATION  Returns TRUE or FALSE to indicate whether default Form Builder validation is enabled.

VALIDATION_UNIT  Returns a VARCHAR2 string  indicating the current validation unit for the form:

•	FORM_SCOPE if the current validation unit is the form.

•	BLOCK_SCOPE if the current validation unit is the block.

•	RECORD_SCOPE if the current validation unit is the record.

•	ITEM_SCOPE if the current validation unit is the item or if the current validation unit is set to DEFAULT.


GET_FORM_PROPERTY examples

Example 1

/*

** Built-in:  GET_FORM_PROPERTY
** Example:   Determine the name of the first block in the form.
*/
DECLARE
  curform VARCHAR2(40);
  blkname VARCHAR2(40);
BEGIN
  curform := :System.Current_Form;
  blkname := Get_Form_Property(curform,FIRST_BLOCK);
END;

Example 2

/*

** Built-in:  GET_FORM_PROPERTY
** Example:   Evaluate the current setting of the
**            Validate property.
*/
BEGIN
  IF Get_Form_Property('curform', VALIDATION) = 'FALSE'
  THEN
    Message ('Form currently has Validation turned OFF');
  END IF;
END;


GET_GROUP_CHAR_CELL built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Returns the VARCHAR2 or LONG value for a record group cell identified by the given row and column.  A cell is an intersection of a row and column.

Syntax

FUNCTION GET_GROUP_CHAR_CELL
  (groupcolumn_id  GroupColumn,
   row_number      NUMBER);

FUNCTION GET_GROUP_CHAR_CELL
  (groupcolumn_name  VARCHAR2,
   row_number        NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

groupcolumn_id	Specifies the unique ID that Form Builder assigns when it creates the record group column.  Use the FIND_COLUMN built-in to return the ID to an appropriately typed variable.  The data type of the ID is GroupColumn.

groupcolumn_name	Specifies the fully qualified VARCHAR2 record group column name you gave the column when you defined it, preceded by the record group name and a dot, as in recordgroup_name.groupcolumn_name.  If the column was defined as a result of a query, its name is the same as its corresponding database column.

row_number	Specifies the row from which to retrieve the value of the cell.


GET_GROUP_CHAR_CELL restrictions

The row_number specified must be within the bounds implied by the number of rows in the record group.  A non-existent row_number results in an index out of bounds error.


GET_GROUP_CHAR_CELL examples

/*

** Built-in:  GET_GROUP_CHAR_CELL
** Example:   Search thru names in a static record group to
**            determine if the value passed into this subprogram
**            exists in the list. Returns the row number
**            where the record was first located, or zero (0)
**            if no match was found.
*/
FUNCTION Is_Value_In_List( the_value     VARCHAR2,
               the_rg_name   VARCHAR2,
               the_rg_column VARCHAR2)
RETURN NUMBER IS
  the_Rowcount   NUMBER;
  rg_id          RecordGroup;
  gc_id          GroupColumn;
  col_val        VARCHAR2(80);
  Exit_Function  Exception;
BEGIN
  /*
  ** Determine if record group exists, and if so get its ID.
  */
  rg_id := Find_Group( the_rg_name );

  IF Id_Null(rg_id) THEN
    Message('Record Group '||the_rg_name||' does not exist.');
    RAISE Exit_Function;
  END IF;

  /*
  ** Make sure the column name specified exists in the
  ** record Group.
  */
  gc_id := Find_Column( the_rg_name||'.'||the_rg_column );

  IF Id_Null(gc_id) THEN
    Message('Column '||the_rg_column||' does not exist.');
    RAISE Exit_Function;
  END IF;
  /*
  ** Get a count of the number of records in the record
  ** group
  */
  the_Rowcount := Get_Group_Row_Count( rg_id );

  /*
  ** Loop through the records, getting the specified column's
  ** value at each iteration and comparing it to 'the_value'
  ** passed in.  Compare the values in a case insensitive
  ** manner.
  */
  FOR j IN 1..the_Rowcount LOOP
    col_val := GET_GROUP_CHAR_CELL( gc_id, j );
    /*
    ** If we find a match, stop and return the
    ** current row number.
    */
    IF UPPER(col_val) = UPPER(the_value) THEN
      RETURN j;
    END IF;
  END LOOP;

  /*
  ** If we get here, we didn't find any matches.
  */
  RAISE Exit_Function;
EXCEPTION
  WHEN Exit_Function THEN
    RETURN 0;
END;


GET_GROUP_DATE_CELL built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Returns the DATE value for a record group cell identified by the given row and column.  A cell is an intersection of a row and column.

Syntax

FUNCTION GET_GROUP_DATE_CELL
  (groupcolumn_id  GroupColumn,
   row_number      NUMBER);

FUNCTION GET_GROUP_DATE_CELL
  (groupcolumn_name  VARCHAR2,
   row_number        NUMBER);

Built-in Type  unrestricted function

Returns  DATE

Enter Query Mode  yes

Parameters

groupcolumn_id	Specifies the unique ID that Form Builder assigns when it creates the record group column.  Use the FIND_COLUMN built-in to return the ID to an appropriately typed variable.  The data type of the ID is GroupColumn.

groupcolumn_name	Specifies the fully qualified VARCHAR2 record group column name you gave the column when you defined it, preceded by the record group name and a dot, as in recordgroup_name.groupcolumn_name.  If the column was defined as a result of a query, its name is the same as its corresponding database column.

row_number	Specifies the row from which to retrieve the value of the cell.


GET_GROUP_DATE_CELL restrictions

The row_number specified must be within the bounds implied by the number of rows in the record group.  A non-existent row_number results in an index out of bounds error.


GET_GROUP_DATE_CELL examples

/*

** Built-in:  GET_GROUP_DATE_CELL
** Example:   Lookup a row in a record group, and return the
**            minimum order date associated with that row in
**            the record group. Uses the 'is_value_in_list'
**            function from the GET_GROUP_CHAR_CELL example.
*/
FUNCTION Max_Order_Date_Of( part_no VARCHAR2 )
RETURN DATE IS
  fnd_row NUMBER;
BEGIN
  /*
  ** Try to lookup the part number among the temporary part
  ** list record group named 'TMPPART' in its 'PARTNO'
  ** column.
  */
  fnd_row := Is_Value_In_List( part_no, 'TMPPART', 'PARTNO');
  IF fnd_row = 0 THEN
    Message('Part Number '||part_no||' not found.');
    RETURN NULL;
  ELSE
    /*
    ** Get the corresponding Date cell value from the
    ** matching row.
    */
    RETURN Get_Group_Date_Cell( 'TMPPART.MAXORDDATE', fnd_row );
 END IF;
END;


GET_GROUP_NUMBER_CELL built-in

 Examples	   Restrictions	 All Built-ins

Description

Returns the NUMBER value for a record group cell identified by the given row and column.  A cell is an intersection of a row and column.

Syntax

FUNCTION GET_GROUP_NUMBER_CELL
  (groupcolumn_id  GroupColumn,
   row_number      NUMBER);

FUNCTION GET_GROUP_NUMBER_CELL
  (groupcolumn_name  VARCHAR2,
   row_number        NUMBER);

Built-in Type  unrestricted function

Returns  NUMBER

Enter Query Mode  yes

Parameters

groupcolumn_id	Specifies the unique ID that Form Builder assigns when it creates the record group column.  Use the FIND_COLUMN built-in to return the ID to an appropriately typed variable.  The data type of the ID is GroupColumn.

groupcolumn_name	Specifies the fully qualified VARCHAR2 record group column name you gave the column when you defined it, preceded by the record group name and a dot, as in recordgroup_name.groupcolumn_name.  If the column was defined as a result of a query, its name is the same as its corresponding database column.

row_number	Specifies the row from which to retrieve the value of the cell.


GET_GROUP_NUMBER_CELL restrictions

The row_number specified must be within the bounds implied by the number of rows in the record group.  A non-existent row_number results in an index out of bounds error.


GET_GROUP_NUMBER_CELL examples

/*

** Built-in:  GET_GROUP_NUMBER_CELL
** Example:   Lookup a row in a record group, and return the
**            minimum order quantity associated with that row
**            in the record group. Uses the
**            'is_value_in_list' function from the
**            GET_GROUP_CHAR_CELL example.
*/
FUNCTION Min_Order_Qty_Of( part_no VARCHAR2 )
RETURN NUMBER IS
  fnd_row NUMBER;
BEGIN
  /*
  ** Try to lookup the part number among the temporary part
  ** list record group named 'TMPPART' in its 'PARTNO'
  ** column.
  */
  fnd_row := Is_Value_In_List( part_no, 'TMPPART', 'PARTNO');

  IF fnd_row = 0 THEN
    Message('Part Number '||part_no||' not found.');
    RETURN NULL;
  ELSE
    /*
    ** Get the corresponding Number cell value from the
    ** matching row.
    */
    RETURN Get_Group_Number_Cell( 'TMPPART.MINQTY', fnd_row );
  END IF;
END;


GET_GROUP_RECORD_NUMBER built-in

 Examples	   Restrictions	 All Built-ins

Description

Returns the record number of the first record in the record group with a column value equal to the cell_value parameter.  If there is no match, 0 (zero) is returned.

Syntax

FUNCTION GET_GROUP_RECORD_NUMBER
  (groupcolumn_id  GroupColumn,
   cell_value      NUMBER);

FUNCTION GET_GROUP_RECORD_NUMBER
  (groupcolumn_name  VARCHAR2,
   cell_value      NUMBER);

Built-in Type  unrestricted function

Returns  NUMBER

Enter Query Mode  yes

Parameters

groupcolumn_id	Specifies the unique ID that Form Builder assigns to the record group column when it creates it.  Use the FIND_COLUMN built-in to return the ID to a variable.  The data type of the ID is GroupColumn.

groupcolumn_name	Specifies the name of the record group column that you gave to the group when creating it.  The data type of the name is VARCHAR2.

cell_value	Specifies the value to find in the specified record group column.  The data type of the name is VARCHAR2, NUMBER, or DATE.


GET_GROUP_RECORD_NUMBER restrictions

The dataype of the cell_value parameter must match the datatype of the record group column.  The comparison is case-sensitive for VARCHAR2 comparisons.


GET_GROUP_RECORD_NUMBER examples

/*

** Built-in: GET_GROUP_RECORD_NUMBER
** Example:  Find the first record in the record group with a
**     cell in a column that is identical to the value
**    specified in the cell_value parameter.
*/
DECLARE
  rg_id         RecordGroup;
  match         NUMBER := 2212;
  status        NUMBER;
  the_recordnum NUMBER;
BEGIN
  rg_id := Create_Group_From_Query('QGROUP',
          'SELECT ENAME,EMPNO,SAL FROM EMP ORDER BY SAL DESC');
  status := Populate_Group( rg_id );
  */  *** Zero status is success***  /
  IF status = 0 THEN
    the_recordnum :=Get_Group_Record_Number('QGROUP.ENAME',match);
    Message('The first match is record number                                   '||to_CHAR(the_recordnum));
  ELSE
    Message('Error creating query record group.');
    RAISE Form_Trigger_Failure;
  END IF;
END;


GET_GROUP_ROW_COUNT built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the number of rows in the record group.

Syntax

FUNCTION GET_GROUP_ROW_COUNT
  (recordgroup_id  RecordGroup);

FUNCTION GET_GROUP_ROW_COUNT
  (recordgroup_name  VARCHAR2);

Built-in Type  unrestricted function

Returns  NUMBER

Enter Query Mode  yes

Parameters

recordgroup_id	Specifies the unique ID that Form Builder assigns to the record group when it creates it.  Use the FIND_GROUP built-in to return the ID to a variable.  The data type of the ID is RecordGroup.

recordgroup_name	Specifies the name of the record group that you gave to the group when creating it.  The data type of the name is VARCHAR2.


GET_GROUP_ROW_COUNT examples

/*

** Built-in:  GET_GROUP_ROW_COUNT
** Example:   Determine how many rows were retrieved by a
**            Populate_Group for a query record group.
*/
DECLARE
  rg_id        RecordGroup;
  status       NUMBER;
  the_rowcount NUMBER;
BEGIN
  rg_id := Create_Group_From_Query('MY_QRY_GROUP',
          'SELECT ENAME,EMPNO,SAL FROM EMP ORDER BY SAL DESC');
  status := Populate_Group( rg_id );
  */  *** Zero status is success***  /
  IF status = 0 THEN
    the_rowcount := Get_Group_Row_Count( rg_id );
    Message('The query retrieved '||to_CHAR(the_rowcount)||
           ' record(s)');
  ELSE
    Message('Error creating query record group.');
    RAISE Form_Trigger_Failure;
  END IF;
END;


GET_GROUP_SELECTION built-in

 Examples	     Related Topics	 All Built-ins

Description

Retrieves the sequence number of the selected row for the given group.

Syntax

FUNCTION GET_GROUP_SELECTION
  (recordgroup_id    RecordGroup,
   selection_number  NUMBER);

FUNCTION GET_GROUP_SELECTION
  (recordgroup_name  VARCHAR2,
   selection_number  NUMBER);

Built-in Type  unrestricted function

Returns  NUMBER

Enter Query Mode  yes

Parameters

recordgroup_id	Specifies the unique ID that Form Builder assigns to the record group when it creates it.  Use the FIND_GROUP built-in to return the ID to a variable.  The data type of the ID is RecordGroup.

recordgroup_name	Specifies the name of the record group that you gave to the group when creating it.

selection_number	Identifies the selected rows in order of their selection.  For example, given that rows 3, 7, and 21 are selected, their respective selection values are 1, 2, and 3.  The selection_number argument takes a value of the NUMBER data type.


GET_GROUP_SELECTION examples

/*

** Built-in:  GET_GROUP_SELECTION
** Example:   Return a comma-separated list (string) of the
**            selected part numbers from the presumed
**            existent PARTNUMS record group.
*/
FUNCTION Comma_Separated_Partnumbers
RETURN VARCHAR2 IS
  tmp_str      VARCHAR2(2000);
  rg_id        RecordGroup;
  gc_id        GroupColumn;
  the_Rowcount NUMBER;
  sel_row      NUMBER;
  the_val      VARCHAR2(20);
BEGIN
  rg_id := Find_Group('PARTNUMS');
  gc_id := Find_Column('PARTNUMS.PARTNO');
  /*
  ** Get a count of how many rows in the record group have
  ** been marked as "selected"
  */
  the_Rowcount := Get_Group_Selection_Count( rg_id );
  FOR j IN 1..the_Rowcount LOOP
    /*
    ** Get the Row number of the J-th selected row.
    */
    sel_row := Get_Group_Selection( rg_id, j );
    /*
    ** Get the (VARCHAR2) value of the J-th row.
    */
    the_val := Get_Group_CHAR_Cell( gc_id, sel_row );
    IF j = 1 THEN
      tmp_str := the_val;
    ELSE
      tmp_str := tmp_str||','||the_val;
    END IF;
  END LOOP;
  RETURN tmp_str;
END;


GET_GROUP_SELECTION_COUNT built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the number of rows in the indicated record group that have been programmatically marked as selected by a call to SET_GROUP_SELECTION.

Syntax

FUNCTION GET_GROUP_SELECTION_COUNT
  (recordgroup_id  RecordGroup);

FUNCTION GET_GROUP_SELECTION_COUNT
  (recordgroup_name  VARCHAR2);

Built-in Type  unrestricted function

Returns  NUMBER

Enter Query Mode  yes

Parameters

recordgroup_id	Specifies the unique ID that Form Builder assigns to the record group when it creates it.  Use the FIND_GROUP built-in to return the ID to a variable.  The data type of the ID is RecordGroup.

recordgroup_name	Specifies the name of the record group that you gave to the group when creating it.


GET_GROUP_SELECTION_COUNT examples

/*

** Built-in:  GET_GROUP_SELECTION_COUNT
** Example:   See GET_GROUP_SELECTION
*/


GET_INTERFACE_POINTER

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

 Returns a handle to an OLE2 automation object.

Syntax

FUNCTION GET_INTERFACE_POINTER
  (item_id  Item);

FUNCTION GET_INTERFACE_POINTER
  (item_name  VARCHAR2);

Returns  PLS_INTEGER

Built-in Type  unrestricted function

Enter Query Mode  no

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is Item.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.


GET_INTERFACE_POINTER restrictions

Valid only on Microsoft Windows and Macintosh.


GET_INTERFACE_POINTER examples

/*

** Built-in: GET_INTERFACE_POINTER
** Example:  Finds a handle to an OLE object
*/
FUNCTION HandleMap(MapName VARCHAR2) RETURN OLE2.obj_type is
BEGIN
 RETURN(Get_interface_Pointer(MapName));
END;


GET_ITEM_INSTANCE_PROPERTY built-in

 All Built-ins

Description

Returns property values for the specified item instance. GET_ITEM_INSTANCE_PROPERTY returns the initial value or the value last specified by SET_ITEM_INSTANCE_PROPERTY for the specified item instance. It does not return the effective value of a property (i.e. the value derived from combining properties specified at the item instance, item, and block levels). See SET_ITEM_INSTANCE_PROPERTY for information about effective property values.

Syntax

FUNCTION GET_ITEM_INSTANCE_PROPERTY
  (item_id  ITEM,
   record_number  NUMBER,
   property  NUMBER);

FUNCTION GET_ITEM_INSTANCE_PROPERTY
  (item_name  VARCHAR2,
   record_number  NUMBER,
   property   NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

item_id	The unique ID that Form Builder assigns to the object when it creates it.  Use the FIND_ITEM built-in to return the ID to a variable of datatype ITEM.

item_name	The name you gave the object when you created it.

record_number	A record number or CURRENT_RECORD.

property	The property the value of which you want to get for the given item.  Valid properties are:

BORDER_BEVEL  Returns RAISED, LOWERED, or PLAIN if the BORDER_BEVEL property is set to RAISED, LOWERED, or PLAIN, respectively at the item instance level. If BORDER_BEVEL is not specfied at the item instance level, this property returns " ".

INSERT_ALLOWED  Returns the VARCHAR2 string TRUE if the item instance INSERT_ALLOWED property is set to true. Returns the string FALSE if the property is set to false.

NAVIGABLE  Returns the VARCHAR2 string TRUE if the item instance NAVIGABLE property is set to true. Returns the string FALSE if the property is set to false.

REQUIRED  Returns the VARCHAR2 string TRUE if the item instance REQUIRED property is set to true. Returns the string FALSE if the property is set to false.

SELECTED_RADIO_BUTTON  Returns the label of the selected radio button within the radio group in the specified record. Returns NULL if the radio group for the specified record does not have a selected radio button or if the specified record has been scrolled out of view.

UPDATE_ALLOWED  Returns the VARCHAR2 string TRUE if the item instance UPDATE_ALLOWED property is set to true. Returns the string FALSE if the property is set to false.

VISUAL_ATTRIBUTE  Returns the name of the visual attribute currently in force.  If no named visual attribute is assigned to the item instance, returns  DEFAULT for a default visual attribute. Returns '' if VISUAL_ATTRIBUTE is not specified at the item instance level.


GET_ITEM_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns property values for the specified item.  Note that in some cases you may be able to get—but not set—certain object properties.

Syntax

FUNCTION GET_ITEM_PROPERTY
  (item_id,  ITEM
   property  NUMBER);

FUNCTION GET_ITEM_PROPERTY
  (item_name  VARCHAR2,
   property   NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

item_id	The unique ID that Form Builder assigns to the object when it creates it.  Use the FIND_ITEM built-in to return the ID to a variable of datatype ITEM.

item_name	The name you gave the object when you created it.

property	The property the value of which you want to get for the given item.  Valid properties are:

AUTO_HINT  Returns the VARCHAR2 string TRUE if the Automatic Hint property is set to Yes, and the VARCHAR2 string FALSE if it is set to No.

AUTO_SKIP  Returns the VARCHAR2 string TRUE if Automatic Skip is set to Yes for the item, and the string FALSE if it is set to No for the item.

BACKGROUND_COLOR  The color of the object's background region.

BLOCK_NAME  Returns the VARCHAR2 block name for the item.

BORDER_BEVEL  Returns RAISED, LOWERED, or PLAIN if the BORDER_BEVEL property is set to RAISED, LOWERED, or PLAIN, respectively at the item level.

CASE_INSENSITIVE_QUERY  Returns the VARCHAR2 string TRUE if this property is set to Yes for the item, and the string FALSE if the property is set to No.

CASE_RESTRICTION  Returns UPPERCASE if text for the item is to display in upper case, LOWERCASE if the text is to display in lower case, or NONE if no case restriction is in force.

COLUMN_NAME  Returns the name of the column in the database to which the datablock item is associated.

COMPRESS Returns a value (either TRUE or FALSE) that indicates whether the sound object being read into a form from a file should be compressed when converting to the Oracle internal format.

CONCEAL_DATA  Returns the VARCHAR2 string TRUE if the text an operator types into the text item is to be hidden, and the VARCHAR2 string FALSE if the text an operator types into the text item is to be displayed.

CURRENT_RECORD_ATTRIBUTE  Returns the VARCHAR2 name of the named visual attribute of the given item.

CURRENT_ROW_BACKGROUND_COLOR  The color of the object's background region.

CURRENT_ROW_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

CURRENT_ROW_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

CURRENT_ROW_FONT_SIZE  The size of the font, specified in points.

CURRENT_ROW_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

CURRENT_ROW_FONT_STYLE  The style of the font.

CURRENT_ROW_FONT_WEIGHT The weight of the font.

CURRENT_ROW_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

CURRENT_ROW_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

DATABASE_VALUE  For a base table item, returns the value that was originally fetched from the database.

DATATYPE  Returns the data type of the item: ALPHA, CHAR, DATE, JDATE, EDATE,  DATETIME, INT, RINT, MONEY, RMONEY, NUMBER, RNUMBER, TIME, LONG, GRAPHICS, or IMAGE.  Note that some item types, such as buttons and charts, do not have data types.  To avoid an error message in these situations, screen for item type before getting data type.

DIRECTION   Returns the layout direction for bidirectional objects.  Valid return values are RIGHT_TO_LEFT, LEFT_TO_RIGHT.

DISPLAYED Returns the VARCHAR2 string TRUE or FALSE.

ECHO  Returns the VARCHAR2 string TRUE if the Conceal Data property is set to No for the item, and the VARCHAR2 string FALSE if the Conceal Data property is set to Yes for the item.

EDITOR_NAME  Returns the name of the editor attached to the text item.

EDITOR_X_POS  Returns the x coordinate of the editor attached to the text item.  (Corresponds to the Editor Position property.)

EDITOR_Y_POS  Returns the y coordinate of the editor attached to the edit item.  (Corresponds to the Editor Position property.)

ENFORCE_KEY  Returns the name of the item whose value is copied to this item as a foreign key when a new record is created as part of a master-detail relation.  (Corresponds to the Copy property.)

ENABLED  Returns TRUE if enabled property is set to Yes, FALSE if set to No.

FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FIXED_LENGTH  Returns the VARCHAR2 string TRUE if the property is set to Yes for the item, and the VARCHAR2 string FALSE if the property is set to No for the item.

FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE  The size of the font, specified in hundredths of a point (i.e., an item with a font size of 8 points will return 800).

FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE  The style of the font.

FONT_WEIGHT  The weight of the font.

FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

FORMAT_MASK  Returns the format mask used for the text item.

HEIGHT  Returns the height of the item.  The size of the units depends on the Coordinate System and default font scaling you specified for the form.

HINT_TEXT  Returns the item-specific help text displayed on the message line at runtime.

ICON_NAME  Returns the file name of the icon resource associated with a button item having the iconic property set to TRUE.

ICONIC_BUTTON  Returns the VARCHAR2 value TRUE if the button is defined as iconic, and the VARCHAR2 value FALSE if it is not an iconic button.

IMAGE_DEPTH  Returns the color depth of the specified image item.

IMAGE_FORMAT  Returns the format of the specified image item.

INSERT_ALLOWED  Returns the VARCHAR2 string TRUE if the INSERT_ALLOWED property is set to true at the item level. Returns the string FALSE if the property is set to false.

ITEM_CANVAS  Returns the name of the canvas to which the item is assigned.

ITEM_IS_VALID Returns the VARCHAR2 string TRUE if the current item is valid, and the VARCHAR2 string FALSE if the  current item is not valid.

ITEM_NAME  Returns the name of the item.

ITEM_TAB_PAGE  Returns the name of the tab page to which the item is assigned.  Note that the item must be assigned to a tab canvas in order for Form Builder to return the name of the item's tab page.

ITEM_TYPE  Returns the type of the item. Returns BUTTON if the item is a button, CHART ITEM if the item is a chart item, CHECKBOX if the item is a check box, DISPLAY ITEM if the item is a display item, IMAGE if the item is an image item, LIST if the item is a list item, OLE OBJECT if the item is an OCX control or an OLE container, RADIO GROUP if the item is a radio group, TEXT ITEM if the item is a text item, USER AREA if the item is a user area, and VBX CONTROL if the item is a custom item that is a VBX control.

JUSTIFICATION  Returns the text alignment for text items and display items only.  Valid return values are START, END, LEFT, CENTER, RIGHT.

KEEP_POSITION  Returns the VARCHAR2 string TRUE if the cursor is to re-enter at the identical location it was in when it left the item, and the VARCHAR2 string FALSE if the cursor is to re-enter the item at its default position.

LABEL  Returns the VARCHAR2 value defined for the item's Label property.  This property is valid only for items that have labels, such as buttons and check boxes.

LIST  Returns the VARCHAR2 string TRUE if the item is a text item to which a list of values (LOV) is attached; otherwise returns the VARCHAR2 string FALSE.

LOCK_RECORD_ON_CHANGE  Returns the VARCHAR2 string TRUE if Form Builder should attempt to lock a row based on a potential change to this item, and returns the VARCHAR2 string FALSE if no lock should be attempted.

LOV_NAME  Returns the VARCHAR2 name of the LOV associated with the given item.  If  the LOV name does not exist, you will get an error message.

LOV_X_POS Returns the x coordinate of the LOV associated with the text item.  (Corresponds to the List X Position property.)

LOV_Y_POS Returns the y coordinate of the LOV  associated with the text item.  (Corresponds to the List Y Position property.)

MAX_LENGTH  Returns the maximum length setting for the item.  The value is returned as a whole NUMBER.

MERGE_CURRENT_ROW_VA Merges the contents of the specified visual attribute with the current row’s visual attribute (rather than replacing it).

MERGE_TOOLTIP_ATTRIBUTE Merges the contents of the specified visual attribute with the tooltip’s current visual attribute (rather than replacing it).

MERGE_VISUAL_ATTRIBUTE  Merges the contents of the specified visual attribute with the object’s current visual attribute (rather than replacing it).

MOUSE_NAVIGATE  Returns the VARCHAR2 string TRUE if Mouse Navigate is set to Yes for the item, and the VARCHAR2 string FALSE if it is set to No for the item.

MULTI_LINE  Returns the VARCHAR2 value TRUE if the item is a multi-line text item, and the VARCHAR2 string FALSE if it is a single-line text item.

NAVIGABLE  Returns the VARCHAR2 string TRUE if the NAVIGABLE property is set to true at the item level. Returns the string FALSE if the property is set to false.

NEXTITEM  Returns the name of the next item in the default navigation sequence, as defined by the order of items in the Object Navigator.

NEXT_NAVIGATION_ITEM  Returns the name of the item that is defined as the "next navigation item" with respect to this current item.

POPUPMENU_CONTENT_ITEM  Returns the setting for any of the OLE popup menu item properties:

•	POPUPMENU_COPY_ITEM

•	POPUPMENU_CUT_ITEM

•	POPUPMENU_DELOBJ_ITEM

•	POPUPMENU_INSOBJ_ITEM

•	POPUPMENU_LINKS_ITEM

•	POPUPMENU_OBJECT_ITEM

•	POPUPMENU_PASTE_ITEM

•	POPUPEMNU_PASTESPEC_ITEM

Returns the VARCHAR2 string HIDDEN if the OLE popup menu item is not displayed.  Returns the VARCHAR2 string ENABLED if the OLE popup menu item is displayed and enabled.  Returns the VARCHAR2 string DISABLED if the OLE popup menu item is displayed and not enabled.  Returns the VARCHAR2 string UNSUPPORTED if the platform is not Microsoft Windows.

PREVIOUSITEM  Returns the name of the previous item.

PREVIOUS_NAVIGATION_ITEM  Returns the name of the item that is defined as the "previous navigation item" with respect to this current item.

PRIMARY_KEY  Returns the VARCHAR2 value TRUE if the item is a primary key, and the VARCHAR2 string FALSE if it is not.

PROMPT_ALIGNMENT_OFFSET  Returns the distance between the item and its prompt as a VARCHAR2 value.

PROMPT_BACKGROUND_COLOR  The color of the object's background region.

PROMPT_DISPLAY_STYLE  Returns the prompt’s display style, either FIRST_RECORD, HIDDEN, or ALL_RECORDS.

PROMPT_EDGE  Returns a value that indicates which edge the item’s prompt is attached to, either START, END, TOP, or BOTTOM.

PROMPT_EDGE_ALIGNMENT  Returns a value that indicates which edge the item’s prompt is aligned to, either START, END, or CENTER.

PROMPT_EDGE_OFFSET  Returns the distance between the item and its prompt as a VARCHAR2 value.

PROMPT_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

PROMPT_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

PROMPT_FONT_SIZE  The size of the font, specified in points.

PROMPT_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

PROMPT_FONT_STYLE  The style of the font.

PROMPT_FONT_WEIGHT  The weight of the font.

PROMPT_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

PROMPT_TEXT  Returns the text label that displays for an item.

PROMPT_TEXT_ALIGNMENT  Returns a value that indicates how the prompt is justified, either START, LEFT, RIGHT, CENTER, or END.

PROMPT_VISUAL_ATTRIBUTE Returns a value that indicates the prompt’s named visual attribute .

PROMPT_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

QUERYABLE  Returns the VARCHAR2 string TRUE if the item can be included in a query, and the VARCHAR2 string FALSE if it cannot.

QUERY_LENGTH  Returns the number of characters an operator is allowed to enter in the text item when the form is in Enter Query mode.

QUERY_ONLY  Returns the VARCHAR2 string TRUE if property is set to Yes for the item, and the VARCHAR2 string FALSE if the property is set to No for the item.

RANGE_HIGH  Returns the high value of the range limit.   (Corresponds to the Range property.)

RANGE_LOW  Returns the low value of the range limit.   (Corresponds to the Range property.)

REQUIRED  For multi-line text items, returns the VARCHAR2 string TRUE if the REQUIRED property is set to true at the item level. Returns the string FALSE if the property is set to false.

SCROLLBAR  Returns the VARCHAR2 string TRUE if the Show Scroll Bar property is Yes, and the VARCHAR2 string FALSE if the Show Scroll Bar property is No.

SHOW_FAST_FORWARD_BUTTON  Returns the VARCHAR2 value TRUE if [image] is displayed on the specified sound item, FALSE if not.

SHOW_PALETTE  Returns the VARCHAR2 value TRUE if the image-manipulation palette is displayed adjacent to the specified image item, FALSE if not.

SHOW_PLAY_BUTTON  Returns the VARCHAR2 value TRUE if [image] is displayed on the specified sound item, FALSE if not.

SHOW_RECORD_BUTTON  Returns the VARCHAR2 value TRUE if [image] is displayed on the specified sound item, FALSE if not.

SHOW_REWIND_BUTTON  Returns the VARCHAR2 value TRUE if [image] is displayed on the specified sound item, FALSE if not.

SHOW_SLIDER  Returns the VARCHAR2 value TRUE if the Slider position control is displayed on the specified sound item, FALSE if not.

SHOW_TIME_INDICATOR  Returns the VARCHAR2 value TRUE if [image] is displayed on the specified sound item, FALSE if not.

SHOW_VOLUME_CONTROL  Returns the VARCHAR2 value TRUE if [image] is displayed on the specified sound item, FALSE if not.

TOOLTIP_BACKGROUND_COLOR  The color of the object's background region.

TOOLTIP_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

TOOLTIP_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

TOOLTIP_FONT_SIZE  The size of the font, specified in points.

TOOLTIP_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

TOOLTIP_FONT_STYLE  The style of the font.

TOOLTIP_FONT_WEIGHT  The weight of the font.

TOOLTIP_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

TOOLTIP_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

TOOLTIP_TEXT Returns the item’s tooltip text.

UPDATE_ALLOWED Returns the VARCHAR2 string TRUE if the UPDATE_ALLOWED property is set to true at the item level. Returns the string FALSE if the property is set to false.

UPDATE_COLUMN  Returns the VARCHAR2 string TRUE if Form Builder should treat the item as updated, and FALSE if it should not.

UPDATE_NULL  Returns the VARCHAR2 string TRUE if the item should be updated only if it is NULL, and the VARCHAR2 string FALSE if it can always be updated.  (Corresponds to the Update if NULL property.)

UPDATE_PERMISSION  Returns the VARCHAR2 string TRUE if the UPDATE_PERMISSION property is set to ON, turning on the item's UPDATEABLE and UPDATE_NULL properties.  The VARCHAR2 string FALSE indicates that UPDATEABLE and UPDATE_NULL are turned off.

VALIDATE_FROM_LIST  Returns the VARCHAR2 string TRUE if Form Builder should validate the value of the text item against the values in the attached LOV; otherwise returns the VARCHAR2 string FALSE.

VISIBLE  Returns the VARCHAR2 string TRUE if the property is set to Yes for the item, and the VARCHAR2 string FALSE if the property is set to No for the item.

VISUAL_ATTRIBUTE  Returns the name of the visual attribute currently in force.  If no named visual attribute is assigned to the item, returns  DEFAULT for a default visual attribute.

WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

WIDTH  Returns the width of the item.

WINDOW_HANDLE  Returns the a unique internal VARCHAR2 constant that is used to refer to objects.  Returns the VARCHAR2 value ‘0’ if the platform is not Microsoft Windows.

WRAP_STYLE  Returns VARCHAR2 if the item has wrap style set to VARCHAR2, WORD if word wrap is set, NONE if no wrap style is specified for the item.

X_POS  Returns the x coordinate that reflects the current placement of the item's upper left corner relative to the upper left corner of the canvas.

Y_POS  Returns the y coordinate that reflects the current placement of the item's upper left corner relative to the upper left corner of the canvas.

Usage Notes

If you attempt to use GET_ITEM_PROPERTY to get a property for an item that is not valid for that item, an error will occur.  For example, an error will occur when you attempt to get LIST from a radio group because LIST is valid only for text items.


GET_ITEM_PROPERTY examples

/*

**  Built-in:  GET_ITEM_PROPERTY
**  Example:   Navigate to the next required item in the
**             current block.      */
PROCEDURE Go_Next_Required_Item IS
  cur_blk        VARCHAR2(40);
  cur_itm        VARCHAR2(80);
  orig_itm       VARCHAR2(80);
  first_itm      VARCHAR2(80);
  wrapped        BOOLEAN := FALSE;
  found          BOOLEAN := FALSE;
  Exit_Procedure EXCEPTION;
  /*
  ** Local function returning the name of the item after the
  ** one passed in. Using NVL we make the item after the
  ** last one in the block equal the first item again.
  */
  FUNCTION The_Item_After(itm VARCHAR2)
  RETURN VARCHAR2 IS
 BEGIN
    RETURN cur_blk||'.'||
      NVL(Get_Item_Property(itm,NEXTITEM),
      first_itm);
 END;
BEGIN
  cur_blk   := :System.Cursor_Block;
  first_itm := Get_Block_Property( cur_blk, FIRST_ITEM );
  orig_itm  := :System.Cursor_Item;
  cur_itm   := The_Item_After(orig_itm);
  /*
  ** Loop until we come back to the item name where we started
  */
  WHILE (orig_itm <> cur_itm) LOOP

    /*
    ** If required item, set the found flag and exit procedure
    */
    IF Get_Item_Property(cur_itm,REQUIRED) = 'TRUE' THEN
      found := TRUE;
      RAISE Exit_Procedure;
    END IF;
    /*
    ** Setup for next iteration
    */
    cur_itm := The_Item_After(cur_itm);
  END LOOP;
  /*
  ** If we get here we wrapped all the way around the
  ** block's item names
  */
  wrapped := TRUE;
  RAISE Exit_Procedure;
EXCEPTION
  WHEN Exit_Procedure THEN
    /*
    ** If we found a required item and we didn't come back
    ** to the item we started in, then navigate there
    */
    IF found AND NOT wrapped THEN
      Go_Item(cur_itm);
    END IF;
END;


GET_LIST_ELEMENT_COUNT built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the total number of list item elements in a list, including elements with NULL values.

Syntax

FUNCTION GET_LIST_ELEMENT_COUNT
  (list_id  Item);

FUNCTION GET_LIST_ELEMENT_COUNT
  (list_name  VARCHAR2);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

list_id	Specifies the unique ID that Form Builder assigns when it creates the list item.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

list_name	The name you gave to the list item when you created it.  The data type of the name is VARCHAR2.


GET_LIST_ELEMENT_COUNT examples

/*

**  Built-in:  GET_LIST_ELEMENT_COUNT
**  Example:   Add an element to the list item.  Before adding
**             the element, verify that the element is not in
**             the current list.
*/
DECLARE
   total_list_count    NUMBER(2);
   loop_index_var      NUMBER(2) := 1;
   list_element        VARCHAR2(50);
   list_element_value  VARCHAR2(50);
   list_element_to_add   VARCHAR2(50);
   list_value_to_add   VARCHAR2(50);
   element_match       VARCHAR2(5) := 'TRUE';
   value_match         VARCHAR2(5) := 'TRUE';
BEGIN
/*
** Determine the total number of list elements.
*/
   total_list_count := Get_List_Element_Count(list_id);
/*
** Compare the current list item elements with the element that
** will be added.
*/
   LOOP
     list_element := Get_List_Element_Value(list_id,
     loop_index_var);
     loop_index_var := loop_index_var + 1;
     IF list_element_to_add = list_element THEN
       element_match := 'FALSE';
     END IF;
     EXIT WHEN list_element = list_element_to_add OR
     loop_index_var = total_list_count;
   END LOOP;
/*
** Compare the current list item values with the value that
** will be added.
*/
   loop_index_var := 1;
   LOOP
     list_element_value:= Get_List_Element_Value(list_id,
        loop_index_var);
     loop_index_var := loop_index_var + 1;
     IF list_value_to_add = list_element_value THEN
       value_match := 'FALSE';
     END IF;
     EXIT WHEN list_element_value = list_value_to_add OR
     loop_index_var = total_list_count;
   END LOOP;
/*
**  Add the element and value if it is not in the current list
*/
   IF element_match AND value_match = 'TRUE' THEN
     Add_List_Element(list_id, list_name, list_element_to_add,
     list_value_to_add);
   END IF
END;


GET_LIST_ELEMENT_LABEL built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns information about the requested list element label.

Syntax

FUNCTION GET_LIST_ELEMENT_LABEL
  (list_id     ITEM,
   list_name   VARCHAR2,
   list_index  NUMBER);

FUNCTION GET_LIST_ELEMENT_LABEL
  (list_name   VARCHAR2,
   list_index  NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

list_id	Specifies the unique ID that Form Builder assigns when it creates the list item.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

list_name	The name you gave to the list item when you created it.  The data type of the name is VARCHAR2.

list_index	Specifies the list index value.  The list index is 1 based.   If the index is greater than the count of elements in the list, GET_LIST_ELEMENT_LABEL will fail.

Usage Notes

The value associated with a list item element is not necessarily the list item's current value.  That is, the value of :block.list_item.


GET_LIST_ELEMENT_LABEL examples

/*

**  Built-in:  GET_LIST_ELEMENT_LABEL
**  Example:   See GET_LIST_ELEMENT_COUNT
*/


GET_LIST_ELEMENT_VALUE built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the value associated with the specified list item element.

Syntax

FUNCTION GET_LIST_ELEMENT_VALUE
  (list_id     ITEM,
   list_index  NUMBER);

FUNCTION GET_LIST_ELEMENT_VALUE
  (list_name   VARCHAR2,
   list_index  NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

list_id	Specifies the unique ID that Form Builder assigns when it creates the list item.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

list_name	The name you gave to the list item when you created it.  The data type of the name is VARCHAR2.

list_index	Specifies the list index value.  The list index is 1 based.   It will return a string containing the value of the requested element.  If the index is greater than the count of elements in the list, GET_LIST_ELEMENT_VALUE will fail.


GET_LIST_ELEMENT_VALUE examples

/*

**  Built-in:  GET_LIST_ELEMENT_VALUE
**  Example:   See GET_LIST_ELEMENT_COUNT
*/


GET_LOV_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns information about a specified list of values (LOV).

You must issue a call to the built-in once for each property value you want to retrieve.

Syntax

FUNCTION GET_LOV_PROPERTY
  (lov_id, property  LOV);

FUNCTION GET_LOV_PROPERTY
  (lov_name  VARCHAR2,
   property  NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

lov_id	Specifies the unique ID that Form Builder assigns the object at the time it creates it.  Use the FIND_LOV built-in to return the ID to an appropriately typed variable.  The data type of the ID is LOV.

lov_name	Specifies the name that you gave the object when creating it.

property	Specifies the property you want to set for the given LOV.  The possible properties are as follows:

AUTO_REFRESH  Returns the VARCHAR2 string TRUE if the property is set to Yes;  that is, if Form Builder re-executes the query each time the LOV is invoked.  Returns the VARCHAR2 string FALSE if the property is set to No.

GROUP_NAME  Returns the name of the record group currently associated with this LOV.  The data type of the name is VARCHAR2.

HEIGHT   Returns the height of the LOV.  The size of the units depends on the Coordinate System and default font scaling you specified for the form.

WIDTH  Returns the width of the LOV. The size of the units depends on the Coordinate System and default font scaling you specified for the form.

X_POS  Returns the x coordinate that reflects the current placement of the LOV's upper left corner relative to the upper left corner of the screen.

Y_POS  Returns the y coordinate that reflects the current placement of the LOV's upper left corner relative to the upper left corner of the screen.


GET_LOV_PROPERTY examples

/*

** Built-in:  GET_LOV_PROPERTY
** Example:  Can get the width/height of the LOV.
*/
DECLARE
  the_width  NUMBER;
  the_height NUMBER;
  lov_id      LOV;
BEGIN
  lov_id     := Find_LOV('My_LOV_1');
  the_width := Get_LOV_Property(lov_id, WIDTH);
  the_height := Get_LOV_Property(lov_id,HEIGHT);
END;


GET_MENU_ITEM_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the state of the menu item given the specific property.  You can use this built-in function to get the state and then you can change the state of the property with the SET_MENU_ITEM_PROPERTY built-in.

Syntax

FUNCTION GET_MENU_ITEM_PROPERTY
  (menuitem_id  MenuItem,
   property     NUMBER);

FUNCTION GET_MENU_ITEM_PROPERTY
  (menu_name.menuitem_name  VARCHAR2,
   property                 NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

menuitem_id	The unique ID Form Builder assigns to the menu item when you create it.  Use the FIND_MENU_ITEM built-in to return the ID to an appropriately typed variable.  Datatype is MenuItem.

menu_name. menuitem_name	The name you gave the menu item when you created it.  If you specify the menu item by name, include the qualifying menu name, for example, menu_name.menuitem_name.  Datatype is VARCHAR2.

property	Specify one of the following constants to retrieve information about the menu item:

CHECKED  Returns the VARCHAR2 string TRUE if a check box menu item is checked, FALSE if it is unchecked. Returns the VARCHAR2 string TRUE if a radio menu item is the selected item in the radio group, FALSE if some other radio item in the group is selected.  Returns TRUE for other menu item types.

ENABLED  Returns the VARCHAR2 string TRUE if a menu item is enabled, FALSE if it is disabled (thus grayed out and unavailable).

ICON_NAME  Returns the file name of the icon resource associated with a menu item having the Icon in Menu property set to TRUE.

LABEL  Returns the VARCHAR2 string for the menu item label.

VISIBLE  Returns the VARCHAR2 string TRUE if a menu item is visible, FALSE if it is hidden from view.


GET_MENU_ITEM_PROPERTY examples

/*

** Built-in:  GET_MENU_ITEM_PROPERTY
** Example:  Toggle the enabled/disable status of the menu
**           item whose name is passed in.  Pass in a string
**           of the form 'MENUNAME.MENUITEM'.
*/
PROCEDURE Toggle_Enabled( menuitem_name VARCHAR2) IS
  mi_id MenuItem;
BEGIN
  mi_id := Find_Menu_Item( menuitem_name );
  IF Get_Menu_Item_Property(mi_id,ENABLED) = 'TRUE' THEN
    Set_Menu_Item_Property(mi_id,ENABLED,PROPERTY_FALSE);
  ELSE
    Set_Menu_Item_Property(mi_id,ENABLED,PROPERTY_TRUE);
  END IF;
END;


GET_MESSAGE built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Returns the current message, regardless of type.

Syntax

FUNCTION GET_MESSAGE;

Built-in Type   unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

none


GET_MESSAGE restrictions

GET_MESSAGE is only instantiated when a message is directed to the display device, either by Form Builder or by a call to the MESSAGE built-in.  If you redirect messages using the On-Message trigger, a call to GET_MESSAGE does not return a value.  Refer to the On-Message trigger for more information.


GET_MESSAGE examples

/*

** Built-in:  GET_MESSAGE
** Example:   Capture the contents of the Message Line in a
**            local variable
*/
DECLARE
  string_var VARCHAR2(200);
BEGIN
  string_var := Get_Message;
END;


GET_OLE_proptype
GET_OLE_<proptype>

 All Built-ins

Description

Obtains an OLE property.

There are four versions of the function (denoted by the value in proptype), one for each of the argument types CHAR, NUM, OBJ, and VAR.

Syntax

FUNCTION GET_OLE_CHAR
  (obj OLEOBJ, memberid PLS_INTEGER)
RETURN oleprop VARCHAR2;

...or...

FUNCTION GET_OLE_NUM
  (obj OLEOBJ, memberid PLS_INTEGER)
RETURN oleprop NUMBER;

...or...

FUNCTION GET_OLE_OBJ
  (obj OLEOBJ, memberid PLS_INTEGER)
RETURN oleprop OLEOBJ;

...or...

FUNCTION GET_OLE_VAR
  (obj OLEOBJ, memberid PLS_INTEGER,
   persistence BOOLEAN)
RETURN oleprop OLEVAR;

Built-in Type  unrestricted function

Returns  the OLE property.  Note that the type varies according to the form of the function chosen.

Parameters

obj	A pointer to the OLE object.
memberid	The member ID of the OLE property.
persistence	Controls the persistence of the OLEVAR argument after its retrieval.  This is an optional parameter; if not specified, the default value is FALSE (that is, non-persistent).
Usage Notes

•	If INIT_OLEARGS and ADD_OLEARG calls precede this GET_OLE_type call, and there have been no intervening GET_OLE, SET_OLE, or CALL_OLE calls, then this call will retrieve the property by using the arguments specified in those INIT_OLEARGS and ADD_OLEARG calls.

•	In contrast to a returned OLEVAR argument, whose persistence can be user-controlled, a returned OLEOBJ argument is always set to be non-persistent.


GET_OLEARG_type
GET_OLEARG_<type>

 All Built-ins

Description

Obtains the nth argument from the OLE argument stack.

There are four versions of the function (denoted by the value in type), one for each of the argument types CHAR, NUM, OBJ, and VAR.

Syntax

FUNCTION GET_OLEARG_CHAR
  (which NUMBER)
RETURN olearg VARCHAR2;

...or...

FUNCTION GET_OLEARG_NUM
  (which NUMBER)
RETURN olearg NUMBER;

...or...

FUNCTION GET_OLEARG_OBJ
  (which NUMBER)
RETURN olearg OLEOBJ;

...or...

FUNCTION GET_OLEARG_VAR
  (which NUMBER, persistence BOOLEAN)
RETURN olearg OLEVAR;

Built-in Type  unrestricted function

Returns  the indicated argument.  Note that the type varies according to the form of the function used.

Parameters

which	A relative number indicating which argument in the OLE argument stack should be retrieved.
persistence	Controls the persistence of the OLEVAR argument after its retrieval.  This is an optional parameter; if not specified, the default value is FALSE (that is, non-persistent).
Usage Notes

•	Use this function to retrieve arguments whose value might change as a result of the method call.

•	In contrast to a returned OLEVAR argument, whose persistence can be user-controlled, a returned OLEOBJ argument is always set to be non-persistent.


GET-OLE-MEMBERID
GET_OLE_MEMBERID

 All Built-ins

Description

Obtains the member ID of a named method or property of an OLE object.

Syntax

FUNCTION GET_OLE_MEMBERID
  (obj OLEOBJ, name VARCHAR2)
RETURN memberid PLS_INTEGER;

Built-in Type  unrestricted function

Returns  member ID of the method or property

Parameters

obj	Pointer to the OLE object.
name	Name of the object's method or property.
Usage Notes

The member ID is a hard-coded value.  The result returned may vary depending on the language used to run the OLE server.


GET_PARAMETER_ATTR built-in

  Related Topics	 All Built-ins

Description

Returns the current value and type of an indicated parameter in an indicated parameter list.

Syntax

FUNCTION GET_PARAMETER_ATTR
  (list       VARCHAR2,
   key        VARCHAR2,
   paramtype  NUMBER,
   value      VARCHAR2);

FUNCTION GET_PARAMETER_ATTR
  (name       VARCHAR2,
   key        VARCHAR2,
   paramtype  NUMBER,
   value      VARCHAR2);

Built-in Type  unrestricted procedure that returns two OUT parameters

Enter Query Mode  yes

Parameters

list or name	Specifies the parameter list to which the parameter is assigned.  The actual parameter can be either a parameter list ID of type PARAMLIST, or the VARCHAR2 name of the parameter list.

key	The VARCHAR2 name of the parameter.

paramtype	An OUT parameter of type NUMBER.  The actual parameter you supply must be a variable of type NUMBER, and cannot be an expression.  Executing the parameter sets the value of the variable to one of the following numeric constants:

DATA_PARAMETER  Indicates that the parameter's value is the name of a record group.

TEXT_PARAMETER  Indicates that the parameter's value is an actual data value.

value	An OUT parameter of type VARCHAR2.  If the parameter is a data type parameter, the value is the name of a record group.  If the parameter is a text parameter, the value is an actual text parameter.

For an overview of using OUT parameters with PL/SQL procedures, refer to the PL/SQL 2.0 User's Guide and Reference.


GET_PARAMETER_LIST built-in

 Examples	     Related Topics	 All Built-ins

Description

Searches the list of parameter lists and returns a parameter list ID when it finds a valid parameter list with the given name.  You must define an variable of type PARAMLIST to accept the return value.  This function is similar to the FIND_ functions available for other objects.

Syntax

FUNCTION GET_PARAMETER_LIST
  (name  VARCHAR2);

Built-in Type   unrestricted function

Returns  ParamList

Enter Query Mode  yes

Parameters

name	Specifies a valid VARCHAR2 parameter list name.


GET_PARAMETER_LIST examples

See CREATE_PARAMETER_LIST


GET_RADIO_BUTTON_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns information about a specified radio button.

Syntax

FUNCTION GET_RADIO_BUTTON_PROPERTY
  (item_id      ITEM,
   button_name  VARCHAR2,
   property     NUMBER);

FUNCTION GET_RADIO_BUTTON_PROPERTY(
  item_name    VARCHAR2,
  button_name  VARCHAR2,
  property     NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

item_id	Specifies the radio group item ID.  Form Builder assigns the unique ID at the time it creates the object.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

item_name	Specifies the name of the radio group.  The radio group is the owner or parent of its subordinate radio buttons.  The data type of the name is VARCHAR2.

button_name	Specifies the name of the radio button whose property you want.  The data type of the name is VARCHAR2.

property	Specifies the property for which you want the current state.  The possible property constants you can indicate are as follows:

BACKGROUND_COLOR  The color of the object's background region.

ENABLED  Returns the VARCHAR2 string TRUE if property is set to Yes, and the VARCHAR2 string FALSE if property is set to No.

FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE  The size of the font, specified in points.

FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE  The style of the font.

FONT_WEIGHT  The weight of the font.

FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

HEIGHT  Returns the height of the radio button.  The value is returned as a VARCHAR2 and is expressed in the units as set for the form by the form module Coordinate System property.

LABEL  Returns the actual string label for that radio button.

PROMPT_BACKGROUND_COLOR  The color of the object's background region.

PROMPT_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

PROMPT_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

PROMPT_FONT_SIZE  The size of the font, specified in points.

PROMPT_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

PROMPT_FONT_STYLE  The style of the font.

PROMPT_FONT_WEIGHT  The weight of the font.

PROMPT_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

PROMPT_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

VISIBLE  Returns the VARCHAR2 string TRUE if property is set to Yes, returns and the VARCHAR2 string FALSE if property is set to No.

VISUAL_ATTRIBUTE  Returns the name of the visual attribute currently in force.  If no named visual attribute is assigned to the radio button, returns CUSTOM for a custom visual attribute or DEFAULT for a default visual attribute.

WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

WIDTH  Returns the width of the radio button, including the label part.  The value is returned as a VARCHAR2 and is expressed in the units as set for the form by the form module Coordinate System property.

WINDOW_HANDLE  Returns the a unique internal VARCHAR2 constant that is used to refer to objects.  Returns the number 0 if the platform is not Microsoft Windows.

X_POS  Returns the x coordinate that reflects the current placement of the button's upper left corner relative to the upper left corner of the canvas.  The value is returned as a VARCHAR2 and is expressed in the units defined by the form module Coordinate System property.

Y_POS  Returns the y coordinate that reflects the current placement of the button's upper left corner relative to the upper left corner of the canvas.  The value is returned as a VARCHAR2 and is expressed in the units defined by the form module Coordinate System property.


GET_RADIO_BUTTON_PROPERTY examples

/*

** Built-in:  GET_RADIO_BUTTON_PROPERTY
** Example:   Determine whether a given radio button is
**            displayed and has a particular visual
**            attribute.
*/
DECLARE
  it_id   Item;
  disp    VARCHAR2(5);
  va_name VARCHAR2(40);
BEGIN
  it_id := Find_Item('My_Favorite_Radio_Grp');
  disp    := Get_Radio_Button_Property( it_id, 'REJECTED',                   VISIBLE);
  va_name := Get_Radio_Button_Property( it_id, 'REJECTED',
          VISUAL_ATTRIBUTE);

  IF disp = 'TRUE' AND va_name = 'BLACK_ON_PEACH' THEN
    Message('You win a prize!');
  ELSE
    Message('Sorry, no luck today.');
  END IF;
END;


GET_RECORD_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the value for the given property for the given record number in the given block.  The three parameters are required.  If you do not pass the proper constants, Form Builder issues an error.  For example, you must pass a valid record number as the argument to the record_number parameter.

Syntax

FUNCTION GET_RECORD_PROPERTY
  (record_number  NUMBER,
   block_name     VARCHAR2,
   property       NUMBER);

Built-in Type   unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

record_number	Specifies the record in a block for which you want property information.  The number must correspond to a record number.

block_name	Specifies the block containing the target record.

property	Specifies the property for which you want the current state. One property constant is supported: Status.

STATUS returns NEW if the record is marked as new and there is no changed record in the block.  Returns CHANGED if the record is marked as changed.  Returns QUERY if the record is marked as query.  Returns INSERT if the record is marked as insert.

Usage Notes

The following table illustrates the situations which return a NEW status.

	Record Status	Block      Status	Form        Status
Created record with no modified fields	NEW	<N|Q|C>	<N|Q|C>
...and all records in current block are NEW	NEW	NEW	<N|Q|C>
...and all blocks in current form are NEW	NEW	NEW	NEW

The following table illustrates the effect on record, block, and form status of changes to base table items and control item in base table and control blocks.

Type of Block/Type of Item Changed	Record Status  Before Change	Record Status   After Change	Block  Status	Form   Status
In a Base Table Block: Change a Base Table Item	NEW	INSERT	CHANGED	CHANGED
In a Base Table Block:Change a Base Table Item	QUERY	CHANGED	CHANGED	CHANGED
In a Base Table Block:Change a Control  Item	QUERY	QUERY	<Q|C>	<Q|C>
...and no record in current block is changed		QUERY	QUERY	<Q|C>
...and no block in current form is changed		QUERY	QUERY	QUERY
In a Base Table Block: Change a Control  Item	NEW	INSERT	<Q|C>	<Q|C>
In a Control Block:  Change a Control  Item	NEW	INSERT	<Q>	<Q|C>
...and no record in current block is changed		INSERT	QUERY	<Q|C>
...and no block in current form is changed		INSERT	QUERY	QUERY
Note:

In general, any assignment to a database item will change a record's status from QUERY to CHANGED (or  from NEW to INSERT), even if the value being assigned is the same as the previous value.  Passing an item to a procedure as OUT or IN OUT parameter counts as an assignment to it.

Both GET_RECORD_PROPERTY and the system variable SYSTEM.RECORD_STATUS return the status of a record in a given block, and in most cases, they return the same status.  However, there are specific cases in which the results may differ.

GET_RECORD_PROPERTY always has a value of NEW, CHANGED, QUERY, or INSERT, because GET_RECORD_PROPERTY returns the status of a specific record without regard to the processing sequence or whether the record is the current record.

SYSTEM.RECORD_STATUS, on the other hand, can in certain cases return a value of NULL, because SYSTEM.RECORD_STATUS is undefined when there is no current record in the system.  For example, in a When-Clear-Block trigger, Form Builder is at the block level in its processing sequence, so there is no current record to report on, and the value of SYSTEM.RECORD_STATUS is NULL.


GET_RECORD_PROPERTY examples

/*

** built-in:  GET_RECORD_PROPERTY
** Example:   Obtain the status of a record in given block
*/
BEGIN
  IF Get_Record_Property(1,'orders',STATUS) = 'NEW' AND
     Get_Record_Property(1,'customers',STATUS) = 'NEW' THEN
    Message('You must enter a customer and order first!');
    RAISE Form_Trigger_Failure;
  END IF;
END;


GET_RELATION_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the state of the given relation property.

Syntax

FUNCTION GET_RELATION_PROPERTY
  (relation_id  Relation,
   property     NUMBER);

FUNCTION GET_RELATION_PROPERTY
  (relation_name  VARCHAR2,
   property       NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

relation_id	Specifies the unique ID Form Builder assigns when it creates the relation.  Use the FIND_RELATION built-in to return the ID to an appropriately typed variable.  The data type of the ID is Relation.

relation_name	Specifies the VARCHAR2 name you gave to the relation when you defined it, or the name that Form Builder assigned to the relation when created.

property	Specifies the property for which you want the current state.  The property constants you can use are as follows:

AUTOQUERY  Returns the VARCHAR2 value TRUE if the Automatic Query relation property is Yes, FALSE if it is No.  When the Deferred relation property is set to Yes, this property determines whether Form Builder automatically populates the detail block when a different record becomes the current record in the master block.

DEFERRED_COORDINATION  Returns the VARCHAR2 value TRUE if the Deferred relation property is Yes, FALSE if it is No.  This property determines whether the detail block is to be immediately coordinated with the current master record, or left clear until the operator navigates to the detail block.

DETAIL_NAME  Returns the VARCHAR2 name of the detail block in the given master-detail relationship.

MASTER_DELETES  Returns one of the following VARCHAR2 values to indicate the current setting of the block's Delete Record Behavior property: NON_ISOLATED, ISOLATED, or CASCADING.

MASTER_NAME  Returns the VARCHAR2 name of the master block in the given master-detail relationship.

NEXT_DETAIL_RELATION  Returns the VARCHAR2 name of the next detail relation, if one exists.  To get the name of the first detail for a given block, issue a call to GET_BLOCK_PROPERTY.  Returns NULL if none exists.

NEXT_MASTER_RELATION  Returns the VARCHAR2 name of the next relation, if one exists.  To get the name of the first relation for a given block, issue a call to GET_BLOCK_PROPERTY.  Returns NULL if one does not exist.

PREVENT_MASTERLESS_OPERATION  Returns the VARCHAR2 value TRUE if this relation property is Yes, FALSE if it is No.  When set to Yes, Form Builder does not allow records to be inserted in the detail block when there is no master record in the master block, and does not allow querying in the detail block when there is no master record from the database.


GET_RELATION_PROPERTY examples

/*

** Built-in:  GET_RELATION_PROPERTY
** Example:   If the relation is not deferred, then go
**            coordinate the detail block. Otherwise, mark
**            the detail block as being in need of
**            coordination for an eventual deferred query.
*/
PROCEDURE Query_The_Details(rel_id Relation,
    detail VARCHAR2) IS
BEGIN
  IF Get_Relation_Property(rel_id, DEFERRED_COORDINATION)
   = 'FALSE' THEN
    Go_Block(detail);
    IF NOT Form_Success THEN
      RAISE Form_Trigger_Failure;
    END IF;
    Execute_Query;
  ELSE
    Set_Block_Property(detail, coordination_status,
             NON_COORDINATED);
  END IF;
End;


GET_REPORT_OBJECT_PROPERTY built-in

 Examples	 All Built-ins

Description

Programmatically obtain a property of a report object.

Syntax

FUNCTION GET_REPORT_OBJECT_PROPERTY
  (report_id REPORT_OBJECT,
   property NUMBER
);

FUNCTION GET_REPORT_OBJECT_PROPERTY
  (report_name VARCHAR2,
   property NUMBER
);

Built-in Type  unrestricted procedure

Enter Query Mode yes

Parameters

report_id	Specifies the unique ID of the report. You can get the report ID for a particular report using FIND_REPORT_OBJECT .

report_name	Specifies the unique name of the report.

property	One of the following constants:

REPORT_EXECUTION_MODE: Returns a string value of the report execution mode, either BATCH or RUNTIME

REPORT_COMM_MODE: Returns a string value of the report communication mode, either SYNCHRONOUS or ASYNCHRONOUS

REPORT_DESTYPE: Returns a string value of the report destination type, either PREVIEW, FILE, PRINTER, MAIL, CACHE or SCREEN

REPORT_FILENAME: Returns a string value of the report filename

REPORT_SOURCE_BLOCK: Returns a string value of the report source block name

REPORT_QUERY_NAME: Returns a string value of the report query name

REPORT_DESNAME: Returns a string value of the report destination name

REPORT_DESFORMAT: Returns a string value of the report destination format

REPORT_SERVER: Returns a string value of the report server name

REPORT_OTHER: Returns a string value of the other user-specified report properties

Usage Notes

•	GET_REPORT_OBJECT_PROPERTY returns a string value for all properties. In contrast, SET_REPORT_OBJECT_PROPERTY sets properties using constant or string values. The value type depends on the particular property being set.


GET_REPORT_OBJECT_PROPERTY examples

DECLARE

repid REPORT_OBJECT;

report_prop VARCHAR2(20);

BEGIN

repid := find_report_object('report4');

report_prop := get_report_object_property(repid,
          REPORT_EXECUTION_MODE);

message('REPORT EXECUTION MODE PROPERTY IS ' || report_prop);

report_prop  := get_report_object_property(repid, REPORT_COMM_MODE);

message('REPORT COMM_MODE PROPERTY IS ' || report_prop);

report_prop  := get_report_object_property(repid, REPORT_DESTYPE);

message('REPORT DESTYPE PROPERTY IS ' || report_prop);

report_prop := get_report_object_property(repid, REPORT_FILENAME);

message('REPORT_FILENAME PROPERTY IS ' || report_prop);

END;


GET_TAB_PAGE_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns property values for a specified tab page.

Syntax

FUNCTION GET_TAB_PAGE_PROPERTY
  (tab_page_id  TAB_PAGE,
   property     NUMBER);

FUNCTION GET_TAB_PAGE_PROPERTY
  (tab_page_name  VARCHAR2,
   property       NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

tab_page_id	The unique ID Form Builder assigned to the tab page object when you created it.  Use the FIND_TAB_PAGE built-in to return the ID to a variable of datatype TAB_PAGE.

tab page_name	The name you gave the tab page object when you created it.  Note:  if two tab pages in the same form module share the same name, you must provide the canvas and tab page (e.g., CVS_1.TAB_PG_1).

property	The property the value of which you want to get for the given tab page.  The possible properties are as follows:

BACKGROUND_COLOR  The color of the object's background region.

CANVAS_NAME  Returns the VARCHAR2 name of the canvas to which the tab page belongs.

ENABLED  Returns the VARCHAR2 string TRUE if a tab page is enabled, FALSE if it is disabled (i.e., greyed out and unavailable).

FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE  The size of the font, specified in points.

FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE  The style of the font.

FONT_WEIGHT  The weight of the font.

FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

LABEL   Returns the VARCHAR2 string for the tab page label.

VISIBLE  Returns the VARCHAR2 value TRUE if the tab page is visible, FALSE if it is not.  A tab page is reported visible if it is currently mapped to the screen, even if it is entirely hidden behind another tab page.

VISUAL_ATTRIBUTE  Returns the name of the visual attribute currently in force.  If no named visual attribute is assigned to the tab page, returns CUSTOM for a custom visual attribute or DEFAULT for a default visual attribute.

WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.


GET_TAB_PAGE_PROPERTY examples

/* Use FIND_TAB_PAGE and GET_TAB_PAGE_PROPERTY to check

** if a tab page is enabled:
*/
DECLARE
  tp_id  TAB_PAGE;
  live   VARCHAR2(32);

BEGIN
  tp_id := FIND_TAB_PAGE('tab_page_1');
  live  := GET_TAB_PAGE_PROPERTY(tp_id, enabled);
END;


GET_TREE_NODE_PARENT built-in

 Examples 	 All Built-ins

Description

Returns the parent of the specified node.

Syntax

FUNCTION GET_TREE_NODE_PARENT

  (item_name VARCHAR2

   node NODE);

FUNCTION GET_TREE_NODE_PARENT

  (item_id ITEM

   node NODE);

Returns  NODE

Built-in Type   unrestricted function

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
node	Specifies a valid node.


GET_TREE_NODE_PARENT examples

/*

** Built-in:  GET_TREE_NODE_PARENT
*/

-- This code could be used in a WHEN-TREE-NODE-SELECTED

-- trigger to locate the parent of the node that was

-- clicked on.

DECLARE

   htree         ITEM;

   parent_node   FTREE.NODE;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Get the parent of the node clicked on.

   parent_node := Ftree.Get_Tree_Node_Parent(htree, :SYSTEM.TRIGGER_NODE);

   ...

END;


GET_TREE_NODE_PROPERTY built-in

 Examples 	 All Built-ins

Description

Returns the value of the specified property of the hierarchical tree node.

Syntax

FUNCTION GET_TREE_NODE_PROPERTY

  (item_name VARCHAR2,

   node NODE,

   property NUMBER);

FUNCTION GET_TREE_NODE_PROPERTY

  (item_id ITEM,

   node NODE,

   property NUMBER);

Returns  VARCHAR2

Built-in Type   unrestricted function

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
node	Specifies a valid node.
property	Specify one of the following properties: NODE_STATE   Returns the state of the hierarchical tree node. This is either EXPANDED_NODE, COLLAPSED_NODE, or LEAF_NODE. NODE_DEPTH   Returns the nesting level of the hierarchical tree node. NODE_LABEL   Returns the label NODE_ICON   Returns the icon name NODE_VALUE   Returns the value of the hierarchical tree node.


GET_TREE_NODE_PROPERTY examples

/*

** Built-in:  GET_TREE_NODE_PROPERTY
*/

-- This code could be used in a WHEN-TREE-NODE-SELECTED

-- trigger to return the value of the node that was

-- clicked on.

DECLARE

   htree         ITEM;

   node_value    VARCHAR2(100);

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Find the value of the node clicked on.

   node_value := Ftree.Get_Tree_Node_Property(htree, :SYSTEM.TRIGGER_NODE, Ftree.NODE_VALUE);

   ...

END;


GET_TREE_PROPERTY built-in

 Examples 	 All Built-ins

Description

Returns property values of the specified hierarchical tree.

Syntax

FUNCTION GET_TREE_PROPERTY

  (item_name VARCHAR2,

   property NUMBER);

FUNCTION GET_TREE_PROPERTY

  (item_id ITEM,

   property NUMBER);

Returns  VARCHAR2

Built-in Type   unrestricted function

Enter Query Mode  no

Parameters

item_name	Specifies the name you gave the object when you created it.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
property	Specify one of the following properties: DATASOURCE   Returns the source used to initially populate the hierarchical tree, either in Form Builder or by using the SET_TREE_PROPERTY built-in. Returns EXTERNAL if neither property was set in Form Builder. RECORD_GROUP   Returns the RecordGroup used to initially populate the hierarchical tree, either in Form Builder or by using the SET_TREE_PROPERTY built-in. This may be a null string. QUERY_TEXT   Returns the text of the query used to initially populate the hierarchical tree, either in Form Builder or by using the SET_TREE_PROPERTY built-in.. This may be a null string. NODE_COUNT   Returns the number of rows in the hierarchical tree data set. SELECTION_COUNT   Returns the number of selected rows in the hierarchical tree. ALLOW_EMPTY_BRANCHES   Returns the character string TRUE or FALSE. ALLOW_MULTI-SELECT   Returns the character string TRUE or FALSE.
Usage Notes

The values returned by datasource RECORD_GROUP and QUERY_TEXT do not necessarily reflect the current data or state of the tree. The values returned are those that were set in Form Builder and not those set using the SET_TREE_PROPERTY built-in.


GET_TREE_PROPERTY examples

/*

** Built-in:  GET_TREE_PROPERTY
*/

-- This code could be used to find out how many nodes are

-- in a given tree.

DECLARE

   htree         ITEM;

   node_count    NUMBER;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Get the node count of the tree.

   node_count := Ftree.Get_Tree_Property(htree, Ftree.NODE_COUNT);

   ...

END;


GET_TREE_SELECTION built-in

 Examples 	 All Built-ins

Description

Returns the data node indicated by selection. Selection is an index into the list of selected nodes.

Syntax

FUNCTION GET_TREE_SELECTION

  (item_name VARCHAR2,

   selection NUMBER);

FUNCTION GET_TREE_SELECTION

  (item_id ITEM,

   selection NUMBER);

Returns  FTREE.NODE

Built-in Type   unrestricted function

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
selection	Specifies the selection of a single node.


GET_TREE_SELECTION examples

/*

** Built-in:  GET_TREE_SELECTION
*/

-- This code will process all tree nodes marked as selected.  See the

-- Ftree.Set_Tree_Selection built-in for a definition of "selected".

DECLARE

   htree         ITEM;

   num_selected  NUMBER;

   current_node  FTREE.NODE;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Find the number of nodes marked as selected.

   num_selected := Ftree.Get_Tree_Property(htree, Ftree.SELECTION_COUNT);

   -- Loop through selected nodes and process them. If you are deleting

   -- nodes, be sure to loop in reverse!

   FOR j IN 1..num_selected LOOP

      current_node := Ftree.Get_Tree_Selection(htree, j);

      ...

   END LOOP;

END;


GET_VA_PROPERTY built-in

 All Built-ins

Description

Returns visual attribute property values for the specified property.

Syntax

FUNCTION GET_VA_PROPERTY

  (va_id VISUALATTRIBUTE

   property NUMBER);

FUNCTION GET_VA_PROPERTY

  (va_name VARCHAR2

   property NUMBER);

Built-in Type   unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

va_id	The unique ID Form Builder assinged to the visual attribute when you created it. The data type is VISUALATTRIBUTE.
va_name	The name you gave the visual attribute when you created it. The data type is VARCHAR2.
property	Specify one of the following properties: BACKGROUND_COLOR The color of the object's background region.  FILL_PATTERN The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.  FONT_NAME The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.  FONT_SIZE The size of the font, specified in hundreds of points. For example, 8pt. would be 800. FONT_SPACING The width of the font, that is, the amount of space between characters (kerning).  FONT_STYLE The style of the font.  FONT_WEIGHT The weight of the font.  FOREGROUND_COLOR The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.  WHITE_ON_BLACK Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.


GET_VAR_BOUNDS

 All Built-ins

Description

Obtains the bounds of an OLE variant's array.

Syntax

PROCEDURE GET_VAR_BOUNDS
  (var OLEVAR, bounds OLE_SAFEARRAYBOUNDS);

Built-in Type  unrestricted procedure

Parameters

var	The variant.
bounds	The PL/SQL table that is populated with the bounds of the array. For more information about the contents and layout of this parameter, see Array Types for OLE Support


GET_VAR_DIMS

 All Built-ins

Description

Determines if an OLE variant is an array, and if so, obtains the number of dimensions in that array.

Syntax

FUNCTION GET_VAR_DIMS
  (var OLEVAR)
RETURN vardims PLS_INTEGER;

Built-in Type  unrestricted function

Returns  A value of zero (0) if the variant is not an array.  Otherwise, the return value is the number of dimensions in the array.

Parameters

var	The variant.


GET_VAR_TYPE

 All Built-ins

Description

Obtains the type of an OLE variant.

Syntax

FUNCTION GET_VAR_TYPE
  (var OLEVAR)
RETURN vartype VT_TYPE;

Built-in Type  unrestricted function

Returns  type of the variable

Parameters

var	The variant.
vartype	Type of the variant.
Usage Notes

A list of the supported VT_TYPEs can be found in OLE Variant Types .


GET_VERB_COUNT

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Returns the number of verbs that an OLE server recognizes. An OLE verb specifies the action that you can perform on an OLE object, and the number of verbs available depends on the OLE server.  The number of verbs is returned as a VARCHAR2 string and must be converted to NUMBER for use in determining the verb index and verb name for each verb.  You must define an appropriately typed variable to accept the return value.

Syntax

FUNCTION GET_VERB_COUNT
  (item_id  Item);

FUNCTION GET_VERB_COUNT
  (item_name VARCHAR2);

Returns  VARCHAR2

Built-in Type  unrestricted function

Enter Query Mode  no

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is Item.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.


GET_VERB_COUNT restrictions

Valid only on Microsoft Windows and Macintosh.


GET_VERB_COUNT examples

/*

** Built-in: GET_VERB_COUNT
** Example:  Obtains the number of verbs that the OLE server
** issues and recognizes when executed from the OLE container.
** Trigger:  When-Button-Pressed
*/
DECLARE
 item_id  ITEM;
 item_name VARCHAR(25) := 'OLEITM';
 verb_cnt_str VARCHAR(20);
 verb_cnt NUMBER;
 verb_name VARCHAR(20);
 loop_cntr NUMBER;
BEGIN
 item_id := Find_Item(item_name);
 IF Id_Null(item_id) THEN
  message('No such item: '||item_name);
 ELSE
  verb_cnt_str := Get_Verb_Count(item_id);
  verb_cnt := TO_NUMBER(verb_cnt_str);
  FOR loop_cntr in 1..verb_cnt LOOP
    verb_name := Get_Verb_Name(item_id,loop_cntr);
    IF verb_name = 'Edit' THEN
   Exec_Verb(item_id,verb_name);
    END IF;
  END LOOP;
 END IF;
END;


GET_VERB_NAME

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Returns the name of the verb that is associated with the given verb index. An OLE verb specifies the action that you can perform on an OLE object, and each OLE verb has a corresponding OLE verb index.  You must define an appropriately typed variable to accept the return value.

Syntax

FUNCTION GET_VERB_NAME
  (item_id     Item,
   verb_index  VARCHAR2);

FUNCTION GET_VERB_NAME
  (item_name   VARCHAR2,
   verb_index  VARCHAR2);

Returns  VARCHAR 2

Built-in Type  unrestricted function

Enter Query Mode  no

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is Item.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2.

verb_index	Specifies the numeric index of a verb. Use the FIND_OLE_VERB built-in to obtain this value.  The data type of index is VARCHAR2.


GET_VERB_NAME restrictions

Valid only on Microsoft Windows and Macintosh.


GET_VERB_NAME examples

/*

** Built-in: GET_VERB_COUNT
** Example:  See EXEC_VERB and GET_VERB_COUNT
*/


GET_VIEW_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the indicated property setting for the indicated canvas.

Syntax

FUNCTION GET_VIEW_PROPERTY
  (view_id   ViewPort,
   property  NUMBER);

FUNCTION GET_VIEW_PROPERTY
  (view_name  VARCHAR2,
   property   NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

view_id	Specifies the unique ID that Form Builder assigns the canvas when it creates the object.  Use the FIND_VIEW built-in to return the ID to an appropriately typed variable.  The data type of the ID is ViewPort.

view_name	Specifies the name that you gave the object when defining it.

property	Specifies the property whose state you want to get  for the given canvas. You must make a separate call to GET_VIEW_PROPERTY for each property you need, as shown in the example.  You can enter one of the following constants to obtain return values:

DIRECTION   Returns the layout direction for bidirectional objects.  Valid return values are RIGHT_TO_LEFT, LEFT_TO_RIGHT.

HEIGHT  Returns the height of the view.  For a content view, the height of the view is actually the height of the window in which the view is currently displayed.  The size of each unit depends on how you defined the Coordinate System property for the form module.

VIEWPORT_X_POS  For a stacked canvas, returns the x coordinate that reflects the current placement of the view's upper left corner relative to the upper left corner of the window's current content canvas.  For a content view, returns 0.  The value is returned as a VARCHAR2 and is expressed in the units defined by the form module Coordinate System property.

VIEWPORT_Y_POS  For a stacked canvas, returns the y coordinate that reflects the current placement of the view's upper left corner relative to the upper left corner of the window's current content canvas.  For a content view, returns 0.  The value is returned as a VARCHAR2 and is expressed in the units defined by the form module Coordinate System property.

VIEWPORT_X_POS_ON_CANVAS  Returns the x coordinate that reflects the current placement of the view's upper left corner relative to the upper left corner of its canvas.  The value is returned as a VARCHAR2 and is expressed in the units defined by the form module Coordinate System property.

VIEWPORT_Y_POS_ON_CANVAS  Returns the y coordinate that reflects the current placement of the view's upper left corner relative to the upper left corner of its canvas.  The value is returned as a VARCHAR2 and is expressed in the units defined by the form module Coordinate System property.

VISIBLE  Returns the VARCHAR2 value TRUE if the view is visible, FALSE if it is not.  A view is reported visible when it is a) in front of all other views in the window or b) only partially obscured by another view.  A view is reported not visible when it is a) a stacked view that is behind the content view or b) completely obscured by a single stacked view.  Note that this property is independent of the current window display state.  Thus a view can be reported visible even when its window is currently hidden or iconified.

WIDTH  Returns the width of the view.  For a content view, the width of the view is actually the width of the window in which the view is currently displayed.  The size of each unit depends on how you defined the Coordinate System property for the form module.

WINDOW_NAME  Returns the name of the window where this canvas is displayed.


GET_VIEW_PROPERTY examples

/*

** Built-in:  GET_VIEW_PROPERTY
** Example:   Use the Width, and display position of one
**            stacked view (View1) to determine where to
**            position another one (View2) immediately to its
**            right.
*/
PROCEDURE Anchor_To_Right( View2 VARCHAR2, View1 VARCHAR2) IS
  vw_id1 ViewPort;
  vw_id2 ViewPort;
  x      NUMBER;
  y      NUMBER;
  w      NUMBER;
BEGIN
  /*
  ** Find View1 and get its (x,y) position, width
  */
  vw_id1 := Find_View(View1);
  x      := Get_View_Property(vw_id1,VIEWPORT_X_POS);
  y      := Get_View_Property(vw_id1,VIEWPORT_Y_POS);
  w      := Get_View_Property(vw_id1,WIDTH);
  /*
  ** Anchor View2 at (x+w,y+h)
  */
  vw_id2 := Find_View(View2);
  Set_View_Property(vw_id2,VIEWPORT_X_POS, x+w );
  Set_View_Property(vw_id2,VIEWPORT_Y_POS, y );
END;


GET_WINDOW_PROPERTY built-in

  Related Topics	 All Built-ins

Description

Returns the current setting for the indicated window property for the given window.

Syntax

FUNCTION GET_WINDOW_PROPERTY
  (window_id  Window,
   property   NUMBER);

FUNCTION GET_WINDOW_PROPERTY
  (window_name  VARCHAR2,
   property     NUMBER);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Usage Notes

On Microsoft Windows, you can reference the MDI application window with the constant FORMS_MDI_WINDOW.

Parameters

window_id	Specifies the unique ID that Form Builder assigns the window at the time it creates it.  Use the FIND_WINDOW built-in to return the ID to an appropriately typed variable.  The data type of the ID is Window.

window_name	Specifies the name that you gave the window  when creating it.

property	You must make a separate call to GET_WINDOW_PROPERTY for each property you need, as shown in the FIND_WINDOW example. Specify one of the following constants to get the current value or state of the property:

BACKGROUND_COLOR  The color of the object's background region.

DIRECTION   Returns the layout direction for bidirectional objects.  Valid return values are RIGHT_TO_LEFT, LEFT_TO_RIGHT.

FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE  The size of the font, specified in points.

FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE  The style of the font.

FONT_WEIGHT  The weight of the font.

FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

HEIGHT  Returns the height of the window.

HIDE_ON_EXIT  Returns the VARCHAR2 value TRUE if the window has the Remove On Exit property set to Yes, otherwise, it is FALSE.

ICON_NAME  Returns the file name of the icon resource associated with a window item when it is minimized.

TITLE  Returns the title of the window.

VISIBLE  Returns the VARCHAR2 value TRUE if the window is visible, FALSE if it is not.  A window is reported visible if it is currently mapped to the screen, even if it is entirely hidden behind another window or iconified (minimized).

WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

WIDTH  Returns the width of the window.

WINDOW_HANDLE  Returns the a unique internal VARCHAR2 constant that is used to refer to objects.  Returns the number 0 if the platform is not Microsoft Windows.

WIDOW_SIZE  Returns the width and height of the window as a string, separated by commas.

WINDOW_STATE  Returns the current display state of the window.  The display state of a window is the VARCHAR2 string NORMAL, MAXIMIZE, or MINIMIZE.

X_POS  Returns the x coordinate that reflects the window's current display position on the screen.

Y_POS  Returns the y coordinate that reflects the window's current display position on the screen.


GO_BLOCK built-in

 Examples	     Related Topics	 All Built-ins

Description

GO_BLOCK navigates to an indicated block.  If the target block is non-enterable, an error occurs.

Syntax

PROCEDURE GO_BLOCK
  (block_name  VARCHAR2);

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

block_name	Specifies the name you gave the block when defining it.  The data type of the name is VARCHAR2.


GO_BLOCK examples

/*

** Built-in:  GO_BLOCK
** Example:   Navigate to a block by name. Make sure to check
**            that the Go_Block succeeds by checking FORM_SUCCESS.
*/
BEGIN
  IF :Global.Flag_Indicator = 'NIGHT' THEN
    Go_Block('Night_Schedule');
    /*
    ** One method of checking for block navigation success.
    */
    IF NOT FORM_SUCCESS THEN
      RAISE Form_Trigger_Failure;
    END IF;
  ELSIF :Global.Flag_Indicator = 'DAY' THEN
    Go_Block('Day_Schedule');
    /*
    ** Another way of checking that block navigation
    ** succeeds. If the block the cursor is in hasn't
    ** changed after a block navigation, something went
    ** wrong. This method is more reliable than simply
    ** checking FORM_SUCCESS.
    */
    IF :System.Trigger_Block = :System.Cursor_Block THEN
      RAISE Form_Trigger_Failure;
    END IF;
  END IF;
  Execute_Query;
  Go_Block('Main');
END;


GO_FORM built-in

 Restrictions	    Related Topics	 All Built-ins

Description

In a multiple-form application, navigates from the current form to the indicated target form. When navigating with GO_FORM, no validation occurs and no triggers fire except WHEN-WINDOW-DEACTIVATED, which fires for the form that initiates navigation, and WHEN-WINDOW-ACTIVATED, which fires for the target window in the target form.

Attempting to navigate to a form that has not yet been opened raises an error.

Syntax

PROCEDURE GO_FORM
  (form_id  FORMMODULE);

PROCEDURE GO_FORM
  (form_name  VARCHAR2);

Built-in Type  restricted procedure

Enter Query Mode  no

Parameters

form_id	The unique ID that is assigned to the form dynamically when it is instantiated at runtime. Use the FIND_FORM built-in to return the ID to an appropriately typed variable. The data type of the ID is FORMMODULE.

form_name	The name of the target form.  The data type of name is VARCHAR2. The GO_FORM built-in attempts to search for the form module name, not the name of the .fmx file.


GO_FORM restrictions

The target form cannot be a form that is currently disabled as a result of having invoked another form with CALL_FORM.


GO_ITEM built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

GO_ITEM navigates to an indicated item.  GO_ITEM succeeds even if the target item has the Keyboard Navigable property set to No.

Syntax

PROCEDURE GO_ITEM
  (item_id  Item);

PROCEDURE GO_ITEM
  (item_name  VARCHAR2);

Built-in Type  restricted procedure

Enter Query Mode  yes

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. The data type of the ID  is Item.

item_name	Specifies the string you defined as the name of the item at design time.  The data type of the name is VARCHAR2.


GO_ITEM restrictions

GO_ITEM('emp.ename');

•	In Enter Query mode, GO_ITEM cannot be used to navigate to an item in a different block.

•	You cannot use GO_ITEM to navigate to a non-navigable item, such as a VARCHAR2 item or display item.


GO_ITEM examples

/*

** Built-in:  GO_ITEM
** Example:   Invoke a dialog window by navigating to
**            an item which is on the canvas which the window
**            displays.
*/
PROCEDURE Open_Preference_Dialog IS
BEGIN
 Go_Item('pref_dialog.printer_name');
END;


GO_RECORD built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Navigates to the record with the specified record number.

Syntax

PROCEDURE GO_RECORD
  (record_number  NUMBER);

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

record_number	Specifies any integer value that PL/SQL can evaluate to a number.  This includes values derived from calls to system variables, such as TO_NUMBER(:SYSTEM.TRIGGER_RECORD) + 8.

You can use the system variables SYSTEM.CURSOR_RECORD or SYSTEM.TRIGGER_RECORD to determine a record's sequence number.


GO_RECORD restrictions

•	If the query is open and the specified record number is greater than the number of records already fetched, Form Builder fetches additional records to satisfy the call to this built-in.


GO_RECORD examples

/*

** Built-in:  GO_RECORD
** Example:   Navigate to a record in the current block
**            by record number. Also see FIRST_RECORD and
**            LAST_RECORD built-ins.
*/
BEGIN
  Go_Record( :control.last_record_number );
END;


HELP built-in

 Examples	     Related Topics	 All Built-ins

Description

Displays the current item's hint message on the message line.  If the hint message is already displayed, HELP displays the detailed help screen for the item.

Syntax

PROCEDURE HELP;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none


HELP examples

/*

** Built-in:  HELP
** Example:   Gives item-level hint/help.
*/
BEGIN
  Help;
END;


HIDE_MENU built-in

 Examples	 All Built-ins

Description

On character mode platforms, makes the current menu disappear if it is currently displayed, uncovering any part of the form display that the menu had covered.  The menu will redisplay if the SHOW_MENU built-in is invoked or the operator presses [Menu].

Syntax

PROCEDURE HIDE_MENU;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


HIDE_MENU examples

/*

** Built-in:  HIDE_MENU
** Example:  Hides the menu from view on character-mode or
**           block-mode devices
*/
BEGIN
  Hide_Menu;
END;


HIDE_VIEW built-in

 Examples	     Related Topics	 All Built-ins

Description

Hides the indicated canvas.

Syntax

PROCEDURE HIDE_VIEW
  (view_id  ViewPort);

PROCEDURE HIDE_VIEW
  (view_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Description

Hides the indicated canvas.

Parameters

view_id	Specifies the unique ID that Form Builder assigns the view at the time it creates it.  Use the FIND_VIEW built-in to return the ID to an appropriately typed variable.  The data type of the ID is ViewPort.

view_name	Specifies the name that you gave the view when creating it.


HIDE_VIEW examples

/*

** Built-in:  HIDE_VIEW
** Example:   Programmatically dismiss a stacked view from the
**            operator's sight.
*/
PROCEDURE Hide_Button_Bar IS
BEGIN
  Hide_View('Button_Bar');
END;


HIDE_WINDOW built-in

 Examples	     Related Topics	 All Built-ins

Description

Hides the given window.  HIDE_WINDOW is equivalent to setting VISIBLE to No by calling SET_WINDOW_PROPERTY.

Syntax

PROCEDURE HIDE_WINDOW
  (window_id  Window);

PROCEDURE HIDE_WINDOW
  (window_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

window_id	Specifies the unique ID that Form Builder assigns the window at the time it creates it.  Use the FIND_WINDOW built-in to return the ID to an appropriately typed variable.  The data type of the ID is Window.

window_name	Specifies the name that you gave the window  when creating it.


HIDE_WINDOW examples

/*

** Built-in:  HIDE_WINDOW
** Example:   When a main window is closed, hide other
**            "subordinate" windows automatically. To
**            establish this window hierarchy we might define
**            a static record group in the form called
**            'WINDOW_HIERARCHY' with a structure of:
**
**               Parent_Window      Child_Window
**               -------------      -------------
**                 MAIN               DETAIL1
**                 MAIN               DETAIL2
**                 DETAIL1            DETAIL3
**                 DETAIL1            DETAIL4
**                 DETAIL2            DETAIL5
**                 DETAIL3            DETAIL6
**
**           We also have to make sure we navigate to some
**           item not on any of the canvases shown in the
**           windows we are closing, or else that window
**           will automatically be re-displayed by forms
**           since it has input focus.
*/
PROCEDURE Close_Window( wn_name VARCHAR2,
           dest_item VARCHAR2 ) IS
  rg_id        RecordGroup;
  gc_parent    GroupColumn;
  gc_child     GroupColumn;
  the_Rowcount NUMBER;
  /*
  ** Local function called recursively to close children at
  ** all levels of the hierarchy.
  */
  PROCEDURE Close_Win_With_Children( parent_win VARCHAR2 ) IS
    the_child  VARCHAR2(40);
    the_parent VARCHAR2(40);
  BEGIN
    FOR j IN 1..the_Rowcount LOOP
      the_parent := Get_Group_Char_Cell(gc_parent,j);
      /* If we find a matching parent in the table */
      IF UPPER(the_parent) = UPPER(parent_win) THEN
    the_child := Get_Group_Char_Cell(gc_child,j);
    /*
    ** Close this child and any of its children
    */
    Close_Win_With_Children( the_child );
      END IF;
    END LOOP;
    /*
    ** Close the Parent
    */
    Hide_Window( parent_win );
  END;
BEGIN
  /*
  ** Setup
  */
  rg_id        := Find_Group('WINDOW_HIERARCHY');
  gc_parent    := Find_Column('WINDOW_HIERARCHY.PARENT_WINDOW');
  gc_child     := Find_Column('WINDOW_HIERARCHY.CHILD_WINDOW');
  the_Rowcount := Get_Group_Row_Count(rg_id);
  /* Close all the child windows of 'wn_name' */
  Close_Win_With_Children( wn_name );
  /* Navigate to the Destination Item supplied by the caller */
  Go_Item( dest_item );
END;


HOST built-in

 Examples	 All Built-ins

Description

Executes an indicated operating system command.

Syntax

PROCEDURE HOST
  (system_command_string  VARCHAR2);

PROCEDURE HOST
  (system_command_string  VARCHAR2,
   screen_action          NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

system_command_ string	Specifies the system command you want to pass to your particular operating system.

screen_action	Specifies one of the following constants:

no parameter  Specifies that Form Builder will:

•	clear the screen

•	prompt the operator to return from the command

NO_PROMPT  Specifies that Form Builder will:

•	clear the screen (does not prompt the operator to return from the command)

NO_SCREEN  Specifies that Form Builder will:

•	not clear the screen

•	not prompt the operator to return from the system command

(The HOST command should not send output to the screen when using the NO_SCREEN parameter.)

Usage notes

•	Thescreen_action parameter is only relevant to applications running in character mode, where the output of the Host command is displayed in the same window as the form.  In GUI applications, the output of the Host command is displayed in a separate window.

•	Note that the command interpreter for Microsoft Windows NT is cmd, while on Windows 95 it is command.  Before using the HOST built-in to run an external command, be sure to check for the operating system and pass the appropriate command string.

•	On Microsoft Windows NT, when using HOST to execute a 16-bit application, the FORM_SUCCESS built-in will return TRUE whether the application succeeds or fails.  This is a Microsoft Win32 issue.  32-bit applications and OS commands will correctly return TRUE if executed sucessfully and FALSE if failed.  Invalid commands will return FALSE.

•	On Windows 95 platforms the FORM_SUCCESS built-in will always return TRUE for HOST commands which fail.  This includes calls to command.com or OS functions, any 16-bit DOS or GUI application, or an invalid command.  32-bit applications will correctly return TRUE if executed sucessfully and FALSE if failed.


HOST examples

/*

** built-in:  HOST
** Example:   Execute an operating system command in a
**            subprocess or subshell. Uses the
**            'Get_Connect_Info' procedure from the
**            GET_APPLICATION_PROPERTY example.
*/
PROCEDURE Mail_Warning( send_to VARCHAR2) IS
  the_username VARCHAR2(40);
  the_password VARCHAR2(40);
  the_connect  VARCHAR2(40);
  the_command  VARCHAR2(2000);
BEGIN
  /*
  ** Get Username, Password, Connect information
  */
  Get_Connect_Info(the_username,the_password,the_connect);
  /*
  ** Concatenate together the static text and values of
  ** local variables to prepare the operating system command
  ** string.
  */
  the_command := 'orasend '||
      ' to='||send_to||
      ' std_warn.txt '||
      ' subject="## LATE PAYMENT ##"'||
      ' user='||the_username||
      ' password='||the_password||
      ' connect='||the_connect;

  Message('Sending Message...', NO_ACKNOWLEDGE);
  Synchronize;
  /*
  ** Execute the command string as an O/S command The
  ** NO_SCREEN option tells forms not to clear the screen
  ** while we do our work at the O/S level "silently".
  */
  Host( the_command, NO_SCREEN );
  /*
  ** Check whether the command succeeded or not
  */
  IF NOT Form_Success THEN
    Message('Error -- Message not sent.');
  ELSE
    Message('Message Sent.');
  END IF;
END;


ID_NULL built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns a BOOLEAN value that indicates whether the object ID is available.

Syntax

FUNCTION ID_NULL
  (Alert  BOOLEAN);

FUNCTION ID_NULL
  (Block  BOOLEAN);
FUNCTION ID_NULL
  (Canvas  BOOLEAN);
FUNCTION ID_NULL
  (Editor  BOOLEAN);
FUNCTION ID_NULL
  (FormModule  BOOLEAN);
FUNCTION ID_NULL
  (GroupColumn  BOOLEAN);
FUNCTION ID_NULL
  (Item  BOOLEAN);
FUNCTION ID_NULL
  (LOV  BOOLEAN);
FUNCTION ID_NULL
  (MenuItem  BOOLEAN);
FUNCTION ID_NULL
  (ParamList  BOOLEAN);
FUNCTION ID_NULL
  (RecordGroup  BOOLEAN);
FUNCTION ID_NULL
  (Relation  BOOLEAN);
FUNCTION ID_NULL
  (Timer  BOOLEAN);
FUNCTION ID_NULL
  (Viewport  BOOLEAN);
FUNCTION ID_NULL
  (Window  BOOLEAN);

Built-in Type  unrestricted function

Returns  BOOLEAN

Enter Query Mode  yes

Parameters

object_id	You can call this function to test results of the following object ID types:

•	Alert

•	Block

•	Canvas

•	Editor

•	FormModule

•	GroupColumn

•	Item

•	LOV

•	MenuItem

•	ParamList

•	RecordGroup

•	Relation

•	Timer

•	Viewport

•	Window

Usage Notes

Use ID_NULL when you want to check for the existence of an object created dynamically at runtime.  For example, if a specific record group already exists, you will receive an error message if you try to create that record group.  To perform this check, follow this general process:

•	Use the appropriate FIND_ built-in to obtain the object ID.

•	Use ID_NULL to check whether an object with that ID already exists.

•	If the object does not exist, proceed to create it.

If you are going to test for an object’s existence at various times (that is, more than once during a run), then you need to reissue the appropriate FIND_ every time -- once preceding each use of ID_NULL.


ID_NULL examples

See CREATE_GROUP


IMAGE_SCROLL built-in

 Examples	 All Built-ins

Description

Scrolls the image item as close to the specified offset (the X,Y coordinates) as possible. This is useful if the image is bigger than the image item.

Syntax

PROCEDURE IMAGE_SCROLL
  (item_name VARCHAR2,
   X NUMBER,
   Y NUMBER
);

PROCEDURE IMAGE_SCROLL
  (item_id ITEM,
   X NUMBER,
   Y NUMBER
);

Built-in Type  unrestricted procedure

Enter Query Mode yes

Parameters

item_id	Specifies the unique ID Form Builder assigns when it creates the image item.

item_name	Specifies the name you gave the image when defining it.

X	The X coordinate of the offset.

Y	The Y coordinate of the offset.


IMAGE_SCROLL examples

For example, suppose the image is twice the size of the image item, that is, the image coordinates are 0, 200, and the item coordinates are 0, 100. To roughly center the image, you can set IMAGE_SCROLL X, Y coordinates to 50, 50. This sets the top left corner of the item at 50 50 instead of 0, 0, which offsets the image so that it is displayed from its coordinates of 50 to 150.


IMAGE_ZOOM built-in

 Examples	     Related Topics	 All Built-ins

Description

Zooms the image in or out using the effect specified in zoom_type and the amount specified in zoom_factor.

Syntax

PROCEDURE IMAGE_ZOOM
  (image_id   ITEM,
   zoom_type  NUMBER);

PROCEDURE IMAGE_ZOOM
  (image_name  VARCHAR2,
   zoom_type   NUMBER);
PROCEDURE IMAGE_ZOOM
  (image_id     ITEM,
   zoom_type    NUMBER,
   zoom_factor  NUMBER);
PROCEDURE IMAGE_ZOOM
  (image_name   VARCHAR2,
   zoom_type    NUMBER,
   zoom_factor  NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

image_id	Specifies the unique ID Form Builder assigns when it creates the image item.  The data type of the ID is ITEM.

image_name	Specifies the name you gave the image when defining it.

zoom_type	Specify one of the following constants to describe the effect you want to have on the image displayed:

ADJUST_TO_FIT  Scales the image to fit within the display rectangle:  the entire image is visible and the image fills as much of the image item as possible without distorting the image.

SELECTION_RECTANGLE  Scales the image so the selected region fully fills the image item.

ZOOM_IN_FACTOR  Enlarges the image by the zoom_factor.

ZOOM_OUT_FACTOR  Reduces the image by the zoom_factor.

ZOOM_PERCENT  Scales the image to the percentage indicated in zoom_factor.

zoom_factor	Specifies either the factor or the percentage to which you want the image zoomed.  Supply a whole number for this argument.

Usage Notes

•	Check zoom_factor for reasonableness.  For example, specifying a ZOOM_IN_FACTOR of 100 would increase the size of your image 100 times, and could cause your application to run out of memory.

•	When specifying ZOOM_IN_FACTOR or ZOOM_OUT_FACTOR, you can use any positive integer value for zoom_factor, but performance is optimal if you use 2, 4, or 8.

•	When specifying ZOOM_PERCENT, you can use any positive integer value for zoom_factor.  To enlarge the image, specify a percentage greater than 100.

•	The operator must use the mouse to select a region before specifying SELECTION_RECTANGLE, or Form Builder will return an error message.

•	Your design should include scroll bars on images that use SELECTION_RECTANGLE.

•	Valid for both color and black-and-white images.


IMAGE_ZOOM examples

The following example shows a When-Button-Pressed trigger that doubles the size of the image every time the button is pressed.

Image_Zoom('my_image', zoom_in_factor, 2);


INIT-OLEARGS
INIT_OLEARGS

 All Built-ins

Description

Establishes how many arguments are going to be defined and passed to the OLE object's method,

Syntax

PROCEDURE INIT_OLEARGS (num_args NUMBER);

Built-in Type  unrestricted procedure

Parameters

num_args	Number of arguments that are to be passed to the method -- plus one.
Usage Notes

•	This built-in should be called before establishing the arguments' types and values with ADD_OLEARG.

•	This built-in and ADD_OLEARG would also be used to prepare for GET_OLE_* calls if the property is accessed (for example, with an index).

•	It is not necessary to use INIT_OLEARGS before a GET_OLE_* call if that call does not take OLE parameters.

•	Note that the number specified in num_args should be one more than the number of actual arguments.  (Thus, if four arguments are to be passed, set num_arg to be five ).  This increase is required only in preparation for GET_OLE_* calls, not for CALL_OLE, but does no harm in the latter case.


INITIALIZE_CONTAINER

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Inserts an OLE object from a server-compatible file into an OLE container.

Syntax

PROCEDURE INITIALIZE_CONTAINER
  (item_id    Item,
   file_name  VARCHAR2);

PROCEDURE INITIALIZE_CONTAINER
  (item_name  VARCHAR2,
   file_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  no

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is Item.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.

file_name	Specifies the name of the file containing the object for insertion into an OLE container.  Include the path of the file location.


INITIALIZE_CONTAINER restrictions

Valid only on Microsoft Windows and Macintosh.


INITIALIZE_CONTAINER examples

/*

** Built-in: INITIALIZE_CONTAINER
** Example:  Initializes an OLE container by inserting an object
**           from a specified file into an OLE container.
** Trigger:  When-Button-Pressed
*/
DECLARE
 item_id  ITEM;
 item_name VARCHAR(25) := 'OLEITM';
BEGIN
 item_id := Find_Item(item_name);
 IF Id_Null(item_id) THEN
  message('No such item: '||item_name);
 ELSE
  Initialize_Container(item_id,'c:\OLE\oleobj.xls');
 END IF;
END;


INSERT_RECORD built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

When called from an On-Insert trigger, inserts the current record into the database during Post and Commit Transactions processing.  This built-in is included primarily for applications that will run against a non-ORACLE datasource.

Syntax

PROCEDURE INSERT_RECORD;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


INSERT_RECORD restrictions

Valid only in an On-Insert trigger.


INSERT_RECORD examples

/*

** Built-in:  INSERT_RECORD
** Example :  Perform Form Builder standard insert processing
**            based on a global flag setup at startup by the
**            form, perhaps based on a parameter.
** Trigger:   On-Insert
*/
BEGIN
  /*
  ** Check the global flag we setup at form startup
  */
  IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
    User_Exit('my_insrec block=EMP');
  /*
  ** Otherwise, do the right thing.
  */
  ELSE
    Insert_Record;
  END IF;
END;


ISSUE_ROLLBACK built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

When called from an On-Rollback trigger, initiates the default Form Builder processing for rolling back to the indicated savepoint.

This built-in is included primarily for applications that will run against a non-ORACLE data source.

Syntax

PROCEDURE ISSUE_ROLLBACK
  (savepoint_name  VARCHAR2);

Built-in Type   unrestricted procedure

Enter Query Mode  no

Parameters

savepoint name	Name of the savepoint to which you want to rollback.  A null savepoint_name causes a full rollback.


ISSUE_ROLLBACK restrictions

Results are unpredictable when ISSUE_ROLLBACK is used outside an On-Rollback trigger or when used with a savepoint other than that provided by a call to GET_APPLICATION_PROPERTY(SAVEPOINT_NAME).


ISSUE_ROLLBACK examples

/*

** Built-in:  ISSUE_ROLLBACK
** Example:   Perform Form Builder standard Rollback processing.
**            Decide whether to use this built-in based on a
**            global flag setup at startup by the form.
**            perhaps based on a parameter.
** Trigger:   On-Rollback
*/
DECLARE
  sp_name VARCHAR2(80);
BEGIN
  /*
  ** Get the name of the savepoint to which Form Builder needs to
  ** rollback. (NULL = Full Rollback)
  */
  sp_name := Get_Application_Property(SAVEPOINT_NAME);
  /*
  ** Check the global flag we setup at form startup
  */
  IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
    User_Exit('my_rollbk name='||sp_name);
  ELSE
    Issue_Rollback(sp_name);
 END IF;
END;


ISSUE_SAVEPOINT built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

When called from an On-Savepoint trigger, ISSUE_SAVEPOINT initiates the default processing for issuing a savepoint.  You can use GET_APPLICATION_PROPERTY (SAVEPOINT_NAME) to determine the name of the savepoint that Form Builder would be issuing by default, if no On-Savepoint trigger were present.

This built-in is included primarily for applications that will run against a non-ORACLE datasource.

Syntax

PROCEDURE ISSUE_SAVEPOINT
  (savepoint_name  VARCHAR2);

Built-in Type   unrestricted procedure

Enter Query Mode  no

Parameters

savepoint _name	Name of the savepoint you want to be issued


ISSUE_SAVEPOINT restrictions

Never issue a savepoint with the name FM_<number>, unless the savepoint name was provided by a call to GET_APPLICATION_PROPERTY.  Doing so may cause a conflict with savepoints issued by Form Builder.


ISSUE_SAVEPOINT examples

/*

** Built-in:  ISSUE_SAVEPOINT
** Example:   Perform Form Builder standard savepoint processing.
**            Decide whether to use this built-in based on a
**            global flag setup at startup by the form,
**            perhaps based on a parameter.
** Trigger:   On-Savepoint
*/
DECLARE
 sp_name VARCHAR2(80);
BEGIN
  /*  Get the name of the savepoint Form Builder needs to issue
  */
  sp_name := Get_Application_Property(SAVEPOINT_NAME);
  /*  Check the global flag we setup at form startup
  */
  IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
    User_Exit('my_savept name='||sp_name);
  /*  Otherwise, do the right thing.
  */
  ELSE
    Issue_Savepoint(sp_name);
  END IF;
END;


ITEM_ENABLED built-in

  Related Topics	 All Built-ins

Description

Returns the Boolean value TRUE when the menu item is enabled.  Returns the Boolean value FALSE when the menu item is disabled.

Note: ITEM_ENABLED is equivalent to GET_MENU_ITEM_PROPERTY (MENU_ITEM, ENABLED).

Syntax

FUNCTION ITEM_ENABLED
  (mnunam  VARCHAR2,
   itmnam  VARCHAR2);

Built-in Type   unrestricted function

Returns  BOOLEAN

Enter Query Mode  yes

Parameters

mnunam	Specifies the VARCHAR2 name of the menu.

itmnam	Specifies the VARCHAR2 name of the menu item.


LAST_OLE_ERROR

 All Built-ins

Description

Returns the identifying number of the most recent OLE error condition

Syntax

FUNCTION LAST_OLE_ERROR RETURN number;

Built-in Type  unrestricted function

Returns  number

Parameters  None

Usage Notes

•	This function can be used for most error conditions.  However, if the error was a PL/SQL exception, use the LAST_OLE_EXCEPTION function instead.

•	For more information about error values and their meanings, refer to winerror.h.  Winerror.h is supplied by your C compiler vendor.


LAST_OLE_EXCEPTION

 All Built-ins

Description

Returns the identifying number of the most recent OLE exception that occurred in the called object.

Syntax

FUNCTION LAST_OLE_EXCEPTION
  (source OUT VARCHAR2, description OUT VARCHAR2,
   helpfile OUT VARCHAR2,
   helpcontextid OUT PLS_INTEGER)
RETURN errornumber PLS_INTEGER;

Built-in Type  unrestricted function

Returns  error number that the OLE server assigned to this exception condition

Parameters

source	Name of the OLE server that raised the exception condition.
description	Error message text.
helpfile	Name of the file in which the OLE server has additional error information.
helpcontextid	ID of a specific document in the above help file.
Usage Notes

This function can be used after a PL/SQL FORM_OLE_FAILURE exception has occurred as a result of calling an OLE object server.  For information about other types of errors (not PL/SQL exceptions), use the LAST_OLE_ERROR function.


LAST_RECORD built-in

 Examples	 All Built-ins

Description

Navigates to the last record in the block's list of records.  If a query is open in the block, Form Builder fetches the remaining selected records into the block's list of records, and closes the query.

Syntax

PROCEDURE LAST_RECORD;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


LAST_RECORD examples

See FIRST_RECORD


LIST_VALUES built-in

  Related Topics	 All Built-ins

Description

LIST_VALUES displays the list of values for the current item, as long as the input focus is in a text item that has an attached LOV.  The list of values remains displayed until the operator dismisses the LOV or selects a value.

By default, LIST_VALUES uses the NO_RESTRICT parameter.  This parameter causes Form Builder not to use the automatic search and complete feature.  If you use the RESTRICT parameter, Form Builder uses the automatic search and complete feature.

Automatic Search and Complete Feature  With the automatic search and complete feature, an LOV evaluates a text item's current value as a search value.  That is, if an operator presses [List] in a text item that has an LOV, Form Builder checks to see if the item contains a value.

If the text item contains a value, Form Builder automatically uses that value as if the operator had entered the value into the LOV's search field and pressed [List] to narrow the list.

If the item value would narrow the list to only one value, Form Builder does not display the LOV, but automatically reads the correct value into the field.

Syntax

PROCEDURE LIST_VALUES
  (kwd  NUMBER);

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

kwd	Specifies one of the following constants:

NO_RESTRICT  Specifies that Form Builder will not use the automatic search and complete feature.

RESTRICT Specifies that Form Builder will use the automatic search and complete feature.


LOCK_RECORD built-in

 Examples	     Related Topics	 All Built-ins

Description

Attempts to lock the row in the database that corresponds to the current record.  LOCK_RECORD locks the record immediately, regardless of whether the Locking Mode block property is set to Immediate (the default) or Delayed.

When executed from within an On-Lock trigger, LOCK_RECORD initiates default database locking.  The following example illustrates this technique.

Syntax

PROCEDURE LOCK_RECORD;

Built-in Type   unrestricted procedure

Enter Query Mode  no

Parameters

none


LOCK_RECORD examples

/*

** Built-in:  LOCK_RECORD
** Example:   Perform Form Builder standard record locking on the
**            queried record which has just been deleted or
**            updated. Decide whether to use default
**            processing or a user exit by consulting a
**            global flag setup at startup by the form,
**            perhaps based on a parameter.
** Trigger:   On-Lock
*/
BEGIN
  /*
  ** Check the global flag we set up at form startup
  */
  IF :Global.Non_Oracle_Datasource = 'TRUE' THEN
    User_Exit('my_lockrec block=EMP');
  /*
  ** Otherwise, do the right thing.
  */
  ELSE
    Lock_Record;
  END IF;
END;


LOGON built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Performs the default Form Builder logon processing with an indicated username and password.  Call this procedure from an On-Logon trigger when you want to augment default logon processing.

Syntax

PROCEDURE LOGON
  (username  VARCHAR2,
   password  VARCHAR2);

PROCEDURE LOGON
  (username               VARCHAR2,
   password               VARCHAR2,
   logon_screen_on_error  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

This built-in takes the following arguments:

username	Any valid username of up to 80 characters.

password	Any valid password of up to 80 characters, including a database connect string.

logon_screen_ on_error	An optional BOOLEAN parameter that, when set to TRUE (default), causes Form Builder to automatically display the logon screen if the logon specified fails (usually because of a incorrect username/password).  When logon_screen_on_error is set to FALSE and the logon fails, the logon screen will not display and FORM_FAILURE is set to TRUE so the designer can handle the condition in an appropriate manner.

Usage Notes:

When using LOGON to connect to an OPS$ database use a slash '/' for the user.name and the database name for the password..


LOGON restrictions

•	If you identify a remote database, a SQL*Net connection to that database must exist at runtime.

•	Form Builder can connect to only one database at a time.  However, database links may be used to access multiple databases with a single connection.


LOGON examples

/*

** Built-in:  LOGON
** Example:   Perform Form Builder standard logon to the ORACLE
**            database.  Decide whether to use Form Builder
**            built-in processing or a user exit by consulting a
**            global flag setup at startup by the form,
**            perhaps based on a parameter. This example
**            uses the 'Get_Connect_Info' procedure from the
**            GET_APPLICATION_PROPERTY example.
** Trigger:   On-Logon
*/
DECLARE
  un  VARCHAR2(80);
  pw  VARCHAR2(80);
  cn  VARCHAR2(80);
BEGIN
  /*
  ** Get the connection info
  */
  Get_Connect_Info(un,pw,cn);
  /*
  ** If at startup we set the flag to tell our form that we
  ** are not running against ORACLE, then call our
  ** appropriate MY_LOGON userexit to logon.
  */
  IF :Global.Non_Oracle_Datasource = 'TRUE' THEN
    User_Exit('my_logon username='||un||' password='||pw);
  /*
  ** Otherwise, call the LOGON built-in
  */
  ELSE

  /*

  ** Use the following to place a slash in the username field for OPS$ logon

  */

    IF un IS NULL THEN

      un:='/';

    END IF

    IF cn IS NOT NULL THEN
      LOGON(un,pw||'@'||cn);
    ELSE
      LOGON(un,pw);
    END IF;
  END IF;
END;


LOGON_SCREEN built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Displays the default Form Builder logon screen and requests a valid username and password.  Most commonly, you will include this built-in subprogram in an On-Logon trigger to connect to a non-ORACLE data source.

Syntax

PROCEDURE LOGON_SCREEN;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


LOGON_SCREEN restrictions

•	You must issue a call to the LOGON built-in to create the connection to your data source.


LOGON_SCREEN examples

/*

** Built-in:  LOGON_SCREEN
** Example:   Use the default Form Builder logon screen to prompt
**            for username and password before logging on to
**            the database. This uses the 'Get_Connect_Info'
**            procedure from the GET_APPLICATION_PROPERTY
**            example.
*/
DECLARE
  un  VARCHAR2(80);
  pw  VARCHAR2(80);
  cn  VARCHAR2(80);
BEGIN
  /*
  ** Bring up the logon screen
  */
  Logon_Screen;
  /*
  ** Get the username, password and
  ** connect string.
  */
  Get_Connect_Info( un, pw, cn );
  /*
  ** Log the user onto the database
  */
  IF cn IS NOT NULL THEN
    LOGON(un,pw||'@'||cn);
  ELSE
    LOGON(un,pw);
  END IF;
END;


LOGOUT built-in

 Examples	     Related Topics	 All Built-ins

Description

Disconnects the application from the ORACLE RDBMS.  All open cursors are automatically closed when you issue a call to the LOGOUT built-in. You can programmatically log back on with LOGON. If you LOGOUT of a multiple-form application with multiple connections, Form Builder tries to re-establish all of those connections when you subsequently execute LOGON.

Syntax

PROCEDURE LOGOUT;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


LOGOUT examples

/*

** Built-in:  LOGOUT
** Example:   Perform Form Builder standard logout. Decide
**            whether to use Form Builder built-in processing or a
**            user exit by consulting a global flag setup at
**            startup by the form, perhaps based on a
**            parameter.
** Trigger:   On-Logout
*/
BEGIN
  /*
  ** Check the flag we setup at form startup
  */
  IF :Global.Non_Oracle_Datasource = 'TRUE' THEN
    User_Exit('my_logout');
  /*
  ** Otherwise, do the right thing.
  */
  ELSE
    Logout;
  END IF;


MENU_CLEAR_FIELD built-in

 Restrictions	 All Built-ins

Description

MENU_CLEAR_FIELD clears the current field's value from the current cursor position to the end of the field.  If the current cursor position is to the right of the last nonblank character, MENU_CLEAR_FIELD clears the entire field, making its value NULL.

Syntax

PROCEDURE MENU_CLEAR_FIELD;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


MENU_CLEAR_FIELD restrictions

The Enter Parameter Values dialog must be displayed.


MENU_NEXT_FIELD built-in

 Restrictions	 All Built-ins

Description

MENU_NEXT_FIELD navigates to the next field in an Enter Parameter Values dialog.

Syntax

PROCEDURE MENU_NEXT_FIELD;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none


MENU_NEXT_FIELD restrictions

You must be in an Enter Parameter Values dialog.


MENU_PARAMETER built-in

 Restrictions	 	 All Built-ins

Description

MENU_PARAMETER displays all the parameters associated with the current menu, and their current values, in the Enter Parameter Values dialog box.

Syntax

PROCEDURE MENU_PARAMETER;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


MENU_PARAMETER restrictions

Valid only for menus running in full-screen display style.


MENU_PREVIOUS_FIELD built-in

 Restrictions	 All Built-ins

Description

MENU_PREVIOUS_FIELD returns to the previous field in an Enter Parameter Values dialog.

Syntax

PROCEDURE MENU_PREVIOUS_FIELD;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


MENU_PREVIOUS_FIELD restrictions

You must be in an Enter Parameter Values dialog box.


MENU_REDISPLAY built-in

 Restrictions	 All Built-ins

Description

This procedure redraws the screen in a menu.

Syntax

PROCEDURE MENU_REDISPLAY;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


MENU_REDISPLAY restrictions

You must be on a character mode or block mode platform.


MENU_SHOW_KEYS built-in

 Restrictions	 All Built-ins

Description

MENU_SHOW_KEYS displays the Keys screen for the menu module at runtime.

Syntax

PROCEDURE MENU_SHOW_KEYS;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


MENU_SHOW_KEYS restrictions

MENU_SHOW_KEYS is available in any context.


MESSAGE built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Displays specified text on the message line.

Syntax

PROCEDURE MESSAGE
  (message_string  VARCHAR2,
   user_response   NUMBER);

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

message_string	Specify a character string enclosed in single quotes or a variable of VARCHAR2 data type.

user_response	Specifies one of the following constants:

ACKNOWLEDGE  Specifies that Form Builder is to display a modal alert that the operator must dismiss explicitly, whenever two consecutive messages are issued. ACKNOWLEDGE forces the first message to be acknowledged before the second message can be displayed.  This is the default.

NO_ACKNOWLEDGE  Specifies that, when two consecutive messages are issued,  the operator is not expected to respond to the first message displayed before Form Builder displays a second message.  Using NO_ACKNOWLEDGE creates a risk that the operator may not see the first message, because the second message immediately overwrites it without prompting the operator for acknowledgement.


MESSAGE restrictions

The message_string can be up to 200 characters long.  Note, however, that several factors affect the maximum number of characters that can be displayed, including the current font and the limitations of the runtime window manager.


MESSAGE examples

/*

** Built-in:  MESSAGE
** Example:   Display several messages to the command line
**            throughout the progress of a particular
**            subprogram. By using the NO_ACKNOWLEDGE parameter,
**            we can avoid the operator's having to
**            acknowledge each message explicitly.
*/
PROCEDURE Do_Large_Series_Of_Updates IS
BEGIN
  Message('Working... (0%)', NO_ACKNOWLEDGE);
  /*
  ** Long-running update statement goes here
  */

  SYNCHRONIZE;
  Message('Working... (30%)', NO_ACKNOWLEDGE);
  /*
  ** Another long-running update statement goes here
  */
  Message('Working... (80%)', NO_ACKNOWLEDGE);
  /*
  ** Last long-running statement here
  */
  Message('Done...', NO_ACKNOWLEDGE);
END;


MESSAGE_CODE built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns a message number for the message that Form Builder most recently generated during the current Runform session.  MESSAGE_CODE returns zero at the beginning of a session, before Form Builder generates any messages.

Use MESSAGE_CODE to test the outcome of a user action (e.g., pressing a key) to determine processing within an On-Message trigger.

Refer to the Messages appendix for a list of messages and message numbers.

Syntax

FUNCTION MESSAGE_CODE;

Built-in Type   unrestricted function

Returns  NUMBER

Enter Query Mode  yes

Parameters

none


MESSAGE_CODE examples

/*

** Built-in:  MESSAGE_CODE,MESSAGE_TEXT,MESSAGE_TYPE
** Example:   Reword certain FRM message messages by checking
**            the Message_Code in an ON-MESSAGE trigger
** Trigger:   On-Message
*/
DECLARE
  msgnum NUMBER       := MESSAGE_CODE;
  msgtxt VARCHAR2(80) := MESSAGE_TEXT;
  msgtyp VARCHAR2(3)  := MESSAGE_TYPE;
BEGIN
  IF msgnum = 40400 THEN
    Message('Your changes have been made permanent.');
  ELSIF msgnum = 40401 THEN
    Message('You have no unsaved changes outstanding.');
  ELSE
    /*
    ** Print the Normal Message that would have appeared
    **
    **  FRM-12345: Message Text Goes Here
    */
    Message(msgtyp||'-'||TO_CHAR(msgnum)||': '||msgtxt);
  END IF;
END;


MESSAGE_TEXT built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns message text for the message that Form Builder most recently generated during the current Runform session.  MESSAGE_TEXT returns NULL at the beginning of a session, before Form Builder generates any messages.

Use MESSAGE_TEXT to test the outcome of a user action (e.g., pressing a key) to determine processing within an On-Message trigger.

Note: If your applications must be supported in more than one language, use the MESSAGE_CODE built-in instead of the MESSAGE_TEXT built-in. Referencing message codes rather than message text is particularly useful in applications that provide national language support.

Syntax

FUNCTION MESSAGE_TEXT;

Built-in Type   unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

none


MESSAGE_TEXT examples

/*

** Built-in:  MESSAGE_CODE,MESSAGE_TEXT,MESSAGE_TYPE
** Example:   Reword certain FRM message messages by checking
**            the Message_Code in an ON-MESSAGE trigger
** Trigger:   On-Message
*/
DECLARE
  msgnum NUMBER       := MESSAGE_CODE;
  msgtxt VARCHAR2(80) := MESSAGE_TEXT;
  msgtyp VARCHAR2(3)  := MESSAGE_TYPE;
BEGIN
  IF msgnum = 40400 THEN
    Message('Your changes have been made permanent.');
  ELSIF msgnum = 40401 THEN
    Message('You have no unsaved changes outstanding.');
  ELSE
    /*
    ** Print the Normal Message that would have appeared
    **
    **  FRM-12345: Message Text Goes Here
    */
    Message(msgtyp||'-'||TO_CHAR(msgnum)||': '||msgtxt);
  END IF;
END;


MESSAGE_TYPE built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns a message type for the message that Form Builder most recently generated during the current Runform session.

Use MESSAGE_TYPE to test the outcome of a user action (e.g., pressing a key) to determine processing within an On-Message trigger.

Syntax

FUNCTION MESSAGE_TYPE;

Built-in Type   unrestricted function

Returns  VARCHAR2

MESSAGE_TYPE returns one of three values for the message type:

FRM	Indicates that an Form Builder message was generated.

ORA	Indicates that an ORACLE message was generated.

NULL	Indicates that Form Builder has not yet issued any messages during the session.

Enter Query Mode  yes

Parameters

none


MESSAGE_TYPE examples

/*

** Built-in:  MESSAGE_CODE,MESSAGE_TEXT,MESSAGE_TYPE
** Example:   Reword certain FRM message messages by checking
**            the Message_Code in an ON-MESSAGE trigger
** Trigger:   On-Message
*/
DECLARE
  msgnum NUMBER       := MESSAGE_CODE;
  msgtxt VARCHAR2(80) := MESSAGE_TEXT;
  msgtyp VARCHAR2(3)  := MESSAGE_TYPE;
BEGIN
  IF msgnum = 40400 THEN
    Message('Your changes have been made permanent.');
  ELSIF msgnum = 40401 THEN
    Message('You have no unsaved changes outstanding.');
  ELSE
    /*
    ** Print the Normal Message that would have appeared
    **
    **  FRM-12345: Message Text Goes Here
    */
    Message(msgtyp||'-'||TO_CHAR(msgnum)||': '||msgtxt);
  END IF;
END;


MOVE_WINDOW built-in

 Examples	     Related Topics	 All Built-ins

Description

Moves the given window to the location specified by the given coordinates.

If you have specified the form property Coordinate System as Character, then your x, y  coordinates are specified in characters.  If the Coordinate System is specified as Real, then your x, y  coordinates are specified in the real units you have selected--pixels, inches, centimeters, or points.

Syntax

FUNCTION MOVE_WINDOW
  (window_id  Window,
   x          NUMBER,
   y          NUMBER);

FUNCTION MOVE_WINDOW
  (window_name  VARCHAR2,
   x            NUMBER,
   y            NUMBER);

Built-in Type  unrestricted function

Enter Query Mode  yes

Parameters

window_id	Specifies the unique ID that Form Builder assigns the window when created.  Use the FIND_WINDOW built-in to return the ID to an appropriately typed variable.  The data type of the ID is Window.

window_name	Specifies the name that you gave the window  when creating it.

x	Specifies the x coordinate on the screen where you want to place the upper left corner of a window.

y	Specifies the y coordinate on the screen where you want to place the upper left corner of a window.


MOVE_WINDOW examples

/*

** Built-in:  MOVE_WINDOW
** Example:   Move window2 to be anchored at the bottom right
**            corner of window1.
*/
PROCEDURE Anchor_Bottom_Right2( Window2 VARCHAR2, Window1 VARCHAR2) IS
  wn_id1 Window;
  wn_id2 Window;
  x      NUMBER;
  y      NUMBER;
  w      NUMBER;
  h      NUMBER;
BEGIN
  /*
  ** Find Window1 and get its (x,y) position, width, and
  ** height.
  */
  wn_id1 := Find_Window(Window1);
  x      := Get_Window_Property(wn_id1,X_POS);
  y      := Get_Window_Property(wn_id1,Y_POS);
  w      := Get_Window_Property(wn_id1,WIDTH);
  h      := Get_Window_Property(wn_id1,HEIGHT);
  /*
  ** Anchor Window2 at (x+w,y+h)
  */
  wn_id2 := Find_Window(Window2);
  Move_Window( wn_id2, x+w, y+h );
END;


NAME_IN built-in

 Examples	     Related Topics	 All Built-ins

Description

Returns the value of the indicated variable.

The returned value is in the form of a character string.  However, you can use NAME_IN to return numbers and dates as character strings and then convert those strings to the appropriate data types.  You can use the returned value as you would use any value within an executable statement.

If you nest the NAME_IN function, Form Builder evaluates the individual NAME_IN functions from the innermost one to the outermost one.

Syntax

FUNCTION NAME_IN
  (variable_name  VARCHAR2);

Built-in Type   unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

variable_name	Specifies a valid variable or text item.  The data type of the name is VARCHAR2.

Usage Notes

If the returned value is a date string, NAME_IN will use the format mask specified in the BUILTIN_DATE_FORMAT property.  If the DATE_FORMAT_COMPATIBILITY_MODE property is set to 4.5 the default American format is used to format the returned string.


NAME_IN examples

/*

** Built-in:  NAME_IN
** Example:  Simple implementation of a Last-In-First-Out
**           stack mechanism using Global variables.
**           For each named stack, a global variable
**           GLOBAL.<stackname>_PTR points to the largest
**           element on the stack. PUSH increments this
**           value as new elements are added.  Values
**           PUSH'ed on or POP'ed off the named stack are
**           actually stored in GLOBAL variables of a
**           conveniently formed name: GLOBAL.<stackname>nnn
**           where 'nnn' is the number of the element on the
**           stack.
**
**           Usage:
**           Push('MYSTACKNAME', '1');
**           Push('MYSTACKNAME', '2');
**
**           str_var := Pop('MYSTACKNAME');  -- Gets '2'
**           str_var := Pop('MYSTACKNAME');  -- Gets '1'
**           str_var := Pop('MYSTACKNAME');  -- Gets 'EOS'
**
*/
PROCEDURE Push ( the_stackname VARCHAR2,
         the_value     VARCHAR2 ) IS

  ptr_name VARCHAR2(40); -- This stack's pointer name
  prefix   VARCHAR2(40); -- Common prefix for storage vars
  elt_name VARCHAR2(40); -- Name of storage element
  new_idx  VARCHAR2(4) ; -- New stack pointer value
BEGIN
  /*
  ** For any named stack that we reference, the global
  ** variables used for storing the stack's values and the
  ** stack's pointer all begin with a common prefix:
  ** GLOBAL.<stackname>
  */
  prefix := 'GLOBAL.' || the_stackname;
  /*
  ** This named stack's pointer resides in
  ** GLOBAL.<stackname>_PTR Remember that this is the *name*
  ** of the pointer.
  */
  ptr_name := prefix || '_PTR';
  /*
  ** Initialize the stack pointer with a default value of
  ** zero if the stack pointer did not exist previously, ie
  ** the GLOBAL.<stackname>_PTR had yet to be created.
  */
  Default_Value( '0', ptr_name );
  /*
  ** Since we're PUSH'ing a new element on the stack,
  ** increment the stack pointer to reflect this new
  ** element's position.  Remember that GLOBAL variables are
  ** always of type VARCHAR2, so we must convert them TO_NUMBER
  ** before any calculations.
  */
  new_idx  := TO_CHAR( TO_NUMBER( Name_In( ptr_name ) ) + 1 ) ;
  Copy( new_idx   , ptr_name );
  /*
  ** Determine the name of the global variable which will
  ** store the value passed in, GLOBAL.<stackname><new_idx>.
  ** This is simply the prefix concatenated to the new index
  ** number we just calculated above.
  */
  elt_name := prefix||new_idx;
  Copy( the_value , elt_name );
END;

FUNCTION Pop ( the_stackname VARCHAR2)
RETURN VARCHAR2 IS
  ptr_name VARCHAR2(40); -- This stack's pointer name
  prefix   VARCHAR2(40); -- Common prefix for storage vars
  elt_name VARCHAR2(40); -- Name of storage element
  new_idx  VARCHAR2(4) ; -- New stack pointer value
  cur_idx  VARCHAR2(4) ; -- Current stack pointer value
  the_val  VARCHAR2(255);

  EMPTY_STACK   CONSTANT VARCHAR2(3) := 'EOS';
  NO_SUCH_STACK CONSTANT VARCHAR2(3) := 'NSS';
BEGIN
  /*
  ** For any named stack that we reference, the global
  ** variables used for storing the stack's values and the
  ** stack's pointer all begin with a common prefix:
  ** GLOBAL.<stackname>
  */
  prefix   := 'GLOBAL.' || the_stackname;
  /*
  ** This named stack's pointer resides in
  ** GLOBAL.<stackname>_PTR Remember that this is the *name*
  ** of the pointer.
  */
  ptr_name := prefix || '_PTR';
  /*
  ** Force a default value of NULL so we can test if the
  ** pointer exists (as a global variable). If it does not
  ** exist, we can test in a moment for the NULL, and avoid
  ** the typical error due to referencing non-existent
  ** global variables.
  */
  Default_Value( NULL, ptr_name );
  /*
  ** If the *value* contained in the pointer is NULL, then
  ** the pointer must not have existed prior to the
  ** Default_Value statement above. Return the constant
  ** NO_SUCH_STACK in this case and erase the global
  ** variable that the Default_Value implicitly created.
  */
 IF Name_In( ptr_name ) IS NULL THEN
   the_val := NO_SUCH_STACK;
  Erase( ptr_name );
 /*
 ** Otherwise, the named stack already exists. Get the
 ** index of the largest stack element from this stack's
 ** pointer.
 */
 ELSE
   cur_idx := Name_In( ptr_name ) ;
   /*
   ** If the index is zero, then the named stack is already
   ** empty, so return the constant EMPTY_STACK, and leave
   ** the stack's pointer around for later use, ie don't
   ** ERASE it.
   **
   ** Note that a stack can only be empty if some values
   ** have been PUSH'ed and then all values subsequently
   ** POP'ed.  If no values were ever PUSH'ed on this named
   ** stack, then no associated stack pointer would have
   ** been created, and we would flag that error with the
   ** NO_SUCH_STACK case above.
   */
   IF cur_idx = '0' THEN
     the_val := EMPTY_STACK;
    /*
    ** If the index is non-zero, then:
    ** (1) Determine the name of the global variable in
    **     which the value to be POP'ed is stored,
    **     GLOBAL.<stackname><cur_idx>
    ** (2) Get the value of the (cur_idx)-th element to
    **     return
    ** (3) Decrement the stack pointer
    ** (4) Erase the global variable which was used for
    **     value storage
    */
    ELSE
      elt_name:= prefix || cur_idx;
      the_val := Name_In( elt_name );
      new_idx := TO_CHAR( TO_NUMBER( Name_In(ptr_name) ) - 1 ) ;
      Copy( new_idx , ptr_name );
      Erase( elt_name );
    END IF;
  END IF;
  RETURN the_val;
END;


NEW_FORM built-in

 Examples	     Related Topics	 All Built-ins

Description

Exits the current form and enters the indicated form.  The calling form is terminated as the parent form.  If the calling form had been called by a higher form, Form Builder keeps the higher call active and treats it as a call to the new form.  Form Builder releases memory (such as database cursors) that the terminated form was using.

Form Builder runs the new form with the same Runform options as the parent form.  If the parent form was a called form, Form Builder runs the new form with the same options as the parent form.

Syntax

PROCEDURE NEW_FORM
  (formmodule_name  VARCHAR2);

PROCEDURE NEW_FORM
  (formmodule_name  VARCHAR2,
   rollback_mode    NUMBER);
PROCEDURE NEW_FORM
  (formmodule_name  VARCHAR2,
   rollback_mode    NUMBER,
   query_mode       NUMBER);
PROCEDURE NEW_FORM
  (formmodule_name  VARCHAR2,
   rollback_mode    NUMBER,
   query_mode       NUMBER,
   data_mode        NUMBER);
PROCEDURE NEW_FORM
  (formmodule_name  VARCHAR2,
   rollback_mode    NUMBER,
   query_mode       NUMBER,
   paramlist_id     PARAMLIST);
PROCEDURE NEW_FORM
  (formmodule_name  VARCHAR2,
   rollback_mode    NUMBER,
   query_mode       NUMBER,
   paramlist_name   VARCHAR2);
PROCEDURE NEW_FORM
  (formmodule_name  VARCHAR2,
   rollback_mode    NUMBER,
   query_mode       NUMBER,
   data_mode        NUMBER,
   paramlist_id     PARAMLIST);
PROCEDURE NEW_FORM
  (formmodule_name  VARCHAR2,
   rollback_mode    NUMBER,
   query_mode       NUMBER,
   data_mode        NUMBER,
   paramlist_name   VARCHAR2);

Built-in Type  restricted procedure

Enter Query Mode  no

Parameters

formmodule_name	Then name of the called form (must be enclosed in single quotes).  Datatype is VARCHAR2.

rollback_mode	TO_SAVEPOINT  (The default.)  Form Builder will roll back all uncommitted changes (including posted changes) to the current form's savepoint.

NO_ROLLBACK  Form Builder will exit the current form without rolling back to a savepoint.  You can leave the top level form without performing a rollback, which means that you retain any locks across a NEW_FORM operation.  These locks can also occur when invoking Form Builder from an external 3GL program.  The locks are still in effect when you regain control from Form Builder.

FULL_ROLLBACK  Form Builder rolls back all uncommitted changes (including posted changes) that were made during the current Runform session.  You cannot specify a FULL_ROLLBACK from a form that is running in post-only mode.  (Post-only mode can occur when your form issues a call to another form while unposted records exist in the calling form.  To avoid losing the locks issued by the calling form, Form Builder prevents any commit processing in the called form.)

query_mode	NO_QUERY_ONLY  (The default.)  Runs the indicated form normally, allowing the end user to perform inserts, updates, and deletes in the form.

QUERY_ONLY  Runs the indicated form in query-only mode;  end users can query records, but cannot perform inserts, updates or deletes.

data_mode	NO_SHARE_LIBRARY_DATA  (The default.)  At runtime, Form Builder will not share data between forms that have identical libraries attached (at design time).

SHARE_LIBRARY_DATA  At runtime, Form Builder will share data between forms that have identical libraries attached (at design time).

paramlist_id	The unique ID Form Builder assigns when it creates the parameter list.  Specify a parameter list when you want to pass parameters from the calling form to the new form.  Datatype is PARAMLIST.  A parameter list passed to a form via NEW_FORM cannot contain parameters of type DATA_PARAMETER (a pointer to record group).

paramlist_name	The name you gave the parameter list object when you defined it.  Datatype is VARCHAR2.  A parameter list passed to a form via NEW_FORM cannot contain parameters of type DATA_PARAMETER (a pointer to record group).


NEW_FORM examples

/* Create a generic procedure that will invoke the

** formname passed-in using the method indicated by
** the 'newform' and 'queryonly' parameters.
*/
PROCEDURE GENERIC_CALL(formname   VARCHAR2,
                       newform    VARCHAR2,
                       queryonly  VARCHAR2) IS

  msglvl          VARCHAR2(2);
  error_occurred  EXCEPTION;
BEGIN
  /*
  ** Remember the current message level and temporarily
  ** set it to 10 to suppress errors if an incorrect
  ** formname is called
  */
  msglvl := :SYSTEM.MESSAGE_LEVEL;
  :SYSTEM.MESSAGE_LEVEL := '10';

  IF newform = 'Y' THEN
     IF queryonly = 'Y' THEN
        NEW_FORM(formname, to_savepoint, query_only);
     ELSIF queryonly = 'N' THEN
        NEW_FORM(formname);
     END IF;
  ELSIF newform = 'N' THEN
     IF queryonly = 'Y' THEN
        CALL_FORM(formname, hide, no_replace, query_only);
     ELSIF queryonly = 'N' THEN
        CALL_FORM(formname);
     END IF;
  END IF;
  IF NOT form_success THEN
     MESSAGE('Cannot call form '||UPPER(formname)||
             '. Please contact your SysAdmin for help.');
     RAISE error_occurred;
  END IF;
  :SYSTEM.MESSAGE_LEVEL := msglvl;
EXCEPTION
  WHEN error_occurred THEN
     :SYSTEM.MESSAGE_LEVEL := msglvl;
    RAISE form_trigger_failure;
END;


NEXT_BLOCK built-in

 Examples	     Related Topics	 All Built-ins

Description

Navigates to the first navigable item in the next enterable block in the navigation sequence.  By default, the next block in the navigation sequence is the block with the next higher sequence number, as defined by the order of blocks in the Object Navigator.  However, the Next Navigation Block block property can be set to specify a different block as the next block for navigation purposes.

If there is no enterable block with a higher sequence, NEXT_BLOCK navigates to the enterable block with the lowest sequence number.

Syntax

PROCEDURE NEXT_BLOCK;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


NEXT_BLOCK examples

/*

** Built-in:  NEXT_BLOCK
** Example:   If the current item is the last item in the
**            block, then skip to the next block instead of
**            the default of going back to the first item in
**            the same block
** Trigger:   Key-Next-Item
*/
DECLARE
  cur_itm VARCHAR2(80) := :System.Cursor_Item;
  cur_blk VARCHAR2(80) := :System.Cursor_Block;
  lst_itm VARCHAR2(80);
BEGIN
  lst_itm := cur_blk||'.'||Get_Block_Property(cur_blk,LAST_ITEM);
  IF cur_itm = lst_itm THEN
    Next_Block;
  ELSE
    Next_Item;
  END IF;
END;


NEXT_FORM built-in

 Restrictions	    Related Topics	 All Built-ins

Description

In a multiple-form application, navigates to the independent form with the next highest sequence number. (Forms are sequenced in the order they were invoked at runtime.) If there is no form with a higher sequence number, NEXT_FORM navigates to the form with the lowest sequence number.  If there is no such form, the current form remains current.

When navigating with NEXT_FORM, no validation occurs and no triggers fire except WHEN-WINDOW-DEACTIVATED, which fires for the form that initiates navigation, and WHEN-WINDOW-ACTIVATED, which fires for the target form.

Syntax

PROCEDURE NEXT_FORM;

Built-in Type   restricted procedure

Enter Query Mode  no


NEXT_FORM restrictions

The target form cannot be a form that is currently disabled as a result of having invoked another form with CALL_FORM.


NEXT_ITEM built-in

 Examples	     Related Topics	 All Built-ins

Description

Navigates to the navigable item with the next higher sequence number than the current item.  If there is no such item, NEXT_ITEM navigates to the item with the lowest sequence number.  If there is no such item, NEXT_ITEM navigates to the current item.

If the validation unit is the item, NEXT_ITEM validates any fields with sequence numbers greater than the current item or less than the target item.

The function of NEXT_ITEM from the last navigable item in the block depends on the setting of the Navigation Style block property.  The valid settings for Navigation Style include:

Same Record (Default): A Next Item operation from a block's last item moves the input focus to the first navigable item in the block, in that same record.

Change Record:  A Next Item operation from a block's last item moves the input focus to the first navigable item in the block, in the next record. If the current record is the last record in the block and there is no open query, Form Builder creates a new record.  If there is an open query in the block (the block contains queried records), Oracle forms retrieves additional records as needed.

Change Block: A Next Item operation from a block's last item moves the input focus to the first navigable item in the first record of the next block.

Syntax

PROCEDURE NEXT_ITEM;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none


NEXT_ITEM examples

/*

** Built-in:  NEXT_ITEM
** Example:   See NEXT_BLOCK
*/


NEXT_KEY built-in

 Examples	     Related Topics	 All Built-ins

Description

Navigates to the enabled and navigable primary key item with the next higher sequence number than the current item.  If there is no such item, NEXT_KEY navigates to the enabled and navigable primary key item with the lowest sequence number.  If there is no primary key item in the current block, an error occurs.

If the validation unit is the item, NEXT_KEY validates any fields with sequence numbers greater than the current item or less than the target item.

Syntax

PROCEDURE NEXT_KEY;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none


NEXT_KEY examples

/*

** Built-in:  NEXT_KEY
** Example:   Jump the cursor to the next primary key item in
**            in the current block.
*/
BEGIN
  Next_Key;
END;


NEXT_MENU_ITEM built-in

 Restrictions	 	 All Built-ins

Description

Navigates to the next menu item in the current menu.

Syntax

PROCEDURE NEXT_MENU_ITEM;

Built-in Type   restricted procedure

Parameters

none


NEXT_MENU_ITEM restrictions

NEXT_MENU_ITEM is available only in a custom menu running in the full-screen menu display style.


NEXT_RECORD built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Navigates to the first enabled and navigable item in the record with the next higher sequence number than the current record.  If there is no such record, Form Builder will fetch or create a record.  If the current record is a new record, NEXT_RECORD fails.

Syntax

PROCEDURE NEXT_RECORD;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


NEXT_RECORD restrictions

Not allowed in Enter Query mode.


NEXT_RECORD examples

/*

** Built-in: NEXT_RECORD
** Example:  If the current item is the last item in the
**           block, then skip to the next record instead of
**           the default of going back to the first item in
**           the same block
** Trigger:   Key-Next-Item
*/
DECLARE
  cur_itm VARCHAR2(80) := :System.Cursor_Item;
  cur_blk VARCHAR2(80) := :System.Cursor_Block;
  lst_itm VARCHAR2(80);
BEGIN
  lst_itm := cur_blk||'.'||Get_Block_Property(cur_blk,LAST_ITEM);
  IF cur_itm = lst_itm THEN
    Next_Record;
  ELSE
    Next_Item;
  END IF;
END;


NEXT_SET built-in

 Examples	     Related Topics	 All Built-ins

Description

Fetches another set of records from the database and navigates to the first record that the fetch retrieves.  NEXT_SET succeeds only if a query is open in the current block.

Syntax

PROCEDURE NEXT_SET;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


NEXT_SET examples

/*

** Built-in:  NEXT_SET
** Example:   Fetch the next set of records from the database
**            when a button is pressed.
** Trigger:   When-Button-Pressed
*/
BEGIN
  Next_Set;
END;


OLEVAR_EMPTY

 All Built-ins

Description

An OLE variant of type VT_EMPTY.

Syntax

OLEVAR_EMPTY OLEVAR;

Usage Notes

This is a non-settable variable.  It is useful for supplying empty or non-existant arguments to an OLE call.


OPEN_FORM built-in

 Restrictions	    Related Topics	 All Built-ins

Description

Opens the indicated form.  Use OPEN_FORM to create multiple-form applications, that is, applications that open more than one form at the same time.

Syntax

PROCEDURE OPEN_FORM
  (form_name  VARCHAR2);

PROCEDURE OPEN_FORM
  (form_name      VARCHAR2,
   activate_mode  NUMBER);
PROCEDURE OPEN_FORM
  (form_name      VARCHAR2,
   activate_mode  NUMBER,
   session_mode   NUMBER);
PROCEDURE OPEN_FORM
  (form_name      VARCHAR2,
   activate_mode  NUMBER,
   session_mode   NUMBER,
   data_mode      NUMBER);
PROCEDURE OPEN_FORM
  (form_name       VARCHAR2,
   activate_mode   NUMBER,
   session_mode    NUMBER,
   paramlist_name  VARCHAR2);
PROCEDURE OPEN_FORM
  (form_name      VARCHAR2,
   activate_mode  NUMBER,
   session_mode   NUMBER,
   paramlist_id   PARAMLIST);
PROCEDURE OPEN_FORM
  (form_name       VARCHAR2,
   activate_mode   NUMBER,
   session_mode    NUMBER,
   data_mode       NUMBER,
   paramlist_name  VARCHAR2);
PROCEDURE OPEN_FORM
  (form_name      VARCHAR2,
   activate_mode  NUMBER,
   session_mode   NUMBER,
   data_mode      NUMBER,
   paramlist_id   PARAMLIST);

Built-in Type  restricted procedure

Enter Query Mode  no

Parameters:

form_name	The name of the form to open.  Datatype is VARCHAR2.  Required

activate_mode	ACTIVATE  (The default.)  Sets focus to the form to make it the active form in the application.

NO_ACTIVATE  Opens the form but does not set focus to the form. The current form remains current.

session_mode	NO_SESSION  (The default.)  Specifies that the opened form should  share the same database session as the current form.  POST and COMMIT operations in any form will cause posting, validation, and commit processing to occur for all forms running in the same session.

SESSION  Specifies that a new, separate database session should be created for the opened form.

data_mode	NO_SHARE_LIBRARY_DATA  (The default.)  At runtime, Form Builder will not share data between forms that have identical libraries attached (at design time).

SHARE_LIBRARY_DATA  At runtime, Form Builder will share data between forms that have identical libraries attached (at design time).

paramlist_name	The name of a parameter list to be passed to the opened form.  Datatype is VARCHAR2.

paramlist_id	The unique ID that Form Builder assigns to the parameter list at the time it is created.  Use the GET_PARAMETER_LIST function to return the ID to a variable of type PARAMLIST.

Usage Notes

•	Whether you open a form with ACTIVATE or NO_ACTIVATE specified, any startup triggers that would normally fire will execute in the opened form.  (However, see the usage note regarding SESSION-specified below.)

•	When you open a form with ACTIVATE specified (the default), the opened form receives focus immediately; trigger statements that follow the call to OPEN_FORM never execute.

•	When you open a form with NO_ACTIVATE specified, trigger statements that follow the call to OPEN_FORM will execute after the opened form has been loaded into memory and its initial start-up triggers have fired.

•	When you open a form with SESSION specified, the PRE-LOGON, ON-LOGON, and POST-LOGON triggers will not fire.

•	If the form that issues the OPEN_FORM built-in is running in QUERY_ONLY mode, then the opened form will also run in QUERY_ONLY mode.

•	On Microsoft Windows, if any window in the form that opens the independent form is maximized, the first window displayed by the opened form will also be maximized, regardless of its original design-time setting. (The GUI display state of a window is controlled by the Window_State property.)

•	For most applications, you should avoid using OPEN_FORM with forms that contain root windows. Because there can be only one root window displayed at a time, canvases that are assigned to the root window in the current form and in the opened form will be displayed in the same window. This causes the opened form to "take over" the root window from the original form, thus hiding the canvases in the original form partially or completely.


OPEN_FORM restrictions

•	You can set session On for all Runform invocations by setting the FORMSnn_SESSION environment variable to TRUE.  When you set the FORMSnn_SESSION variable, all Runform invocations inherit its setting, unless you override the environment variable by setting the Session option from the Runform command line.

•	If you set session_mode to SESSION when you use OPEN_FORM to create a multiple-form application, you cannot set data_mode to SHARE_LIBRARY_DATA (Form Builder will display a runtime error message).


PASTE_REGION built-in

  Related Topics	 All Built-ins

Description

Pastes the contents of the clipboard (i.e., the selected region that was cut or copied most recently), positioning the upper left corner of the pasted area at the cursor position.

Syntax

PROCEDURE PASTE_REGION;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none

Usage Notes

Use PASTE_REGION, as well as the other editing functions, on text and image items only.  The cut and copy functions transfer the selected region into the system clipboard until you indicate the paste target.  At that time, the cut or copied content is pasted onto the target location.


PAUSE built-in

 All Built-ins

Description

Suspends processing until the end user presses a function key.  PAUSE might display an alert.

Syntax

PROCEDURE PAUSE;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Description

Suspends processing until the end user presses a function key.  PAUSE might display an alert.

Parameters

none


PLAY_SOUND built-in

 Examples	    Related Topics	 All Built-ins

Description

Plays the sound object in the specified sound item.

Syntax

PLAY_SOUND(item_id ITEM);

PLAY_SOUND(item_name VARCHAR2);

Built-in Type  restricted

Enter Query Mode  No

Parameters:

item_id	The unique ID Form Builder gave the sound item when you created it.

item_name	The name you gave the sound item when you created it.


PLAY_SOUND examples

/* Example 1: This procedure call (attached to a menu item)

** plays a sound object from the specified sound item:
*/
GO_ITEM('about.abc_inc');
PLAY_SOUND('about.abc_inc');

/* Example 2: These procedure calls (attached to a
** When-Button-Pressed trigger) read a sound object from the
** file system and play it. Note: since an item must have focus
** in order to play a sound, the trigger code includes a call
** to the built-in procedure GO_ITEM:
*/
BEGIN
  IF :clerks.last_name EQ 'BARNES' THEN
    GO_ITEM('orders.filled_by');
    READ_SOUND_FILE('t:\orders\clerk\barnes.wav',
                    'wave',
                    'orders.filled_by');
    PLAY_SOUND('orders.filled_by');
  END IF;
END;


POPULATE_GROUP built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Executes the query associated with the given record group and returns a number indicating success or failure of the query.  Upon a successful query, POPULATE_GROUP returns a 0 (zero).  An unsuccessful query generates an ORACLE error number that corresponds to the particular SELECT statement failure.  The rows that are retrieved as a result of a successful query replace any rows that exist in the group.

Note: Be aware that the POPULATE_GROUP array fetches 100 records at a time.  To improve network performance, you may want to restrict queries, thus limiting network traffic.

Syntax

FUNCTION POPULATE_GROUP
  (recordgroup_id  RecordGroup);

FUNCTION POPULATE_GROUP
  (recordgroup_name  VARCHAR2);

Built-in Type  unrestricted function

Returns  NUMBER

Enter Query Mode  yes

Parameters

recordgroup_id	The unique ID that Form Builder assigns when it creates the group.  The data type of the ID is RecordGroup.

recordgroup_name	The name you gave to the record group when creating it.  The data type of the name is VARCHAR2.


POPULATE_GROUP restrictions

Valid only for record groups

•	that were created at design time with a query

•	that were created by a call to the CREATE_GROUP_FROM_QUERY built-in

•	that have been previously populated with the POPULATE_GROUP_WITH_QUERY built-in (which associates a query with the record group)


POPULATE_GROUP examples

/*

** Built-in:  POPULATE_GROUP
** Example:   See GET_GROUP_ROW_COUNT and CREATE_GROUP_FROM_QUERY
*/


POPULATE_GROUP_FROM_TREE built-in

 Examples	 All Built-ins

Description

Populates a record group with the data from the hierarchical tree.

Syntax

PROCEDURE POPULATE_GROUP_FROM_TREE

  (group_name VARCHAR2,

   item_name VARCHAR2,

   node NODE);

PROCEDURE POPULATE_GROUP_FROM_TREE

  (group_name VARCHAR2,

   item_id ITEM,

   node NODE);

PROCEDURE POPULATE_GROUP_FROM_TREE

  (group_id RECORDGROUP,

   item_name VARCHAR2,

   node NODE);

PROCEDURE POPULATE_GROUP_FROM_TREE

  (group_id RECORDGROUP,

   item_id ITEM,

   node NODE);

Built-in Type   unrestricted procedure

Enter Query Mode  no

Parameters

group_name	Specifies the name of the group.
group_id	Specifies the ID assigned to the group.
item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
node	Specifies a valid node. If specified, indicates a sub-tree used to populate the RecordGroup, including the specified node.
Usage Notes

The record group is cleared prior to inserting the hierarchical tree’s data set.


POPULATE_GROUP_FROM_TREE examples

/*

** Built-in:  POPULATE_GROUP_FROM_TREE
*/

-- This code will transfer all the data from a hierarchical tree

-- that is parented by the node with a label of "Zetie" to a

-- pre-created record group.  Please see the documentation

-- for the structure of the required record group.

DECLARE

   htree         ITEM;

   find_node     NODE;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Find the node with a label "Zetie".

   find_node := Ftree.Find_Tree_Node(htree, 'Zetie', Ftree.FIND_NEXT,

                Ftree.NODE_LABEL, Ftree.ROOT_NODE, Ftree.ROOT_NODE);

   -- Populate the record group with the tree data.

   -- The record group must already exist.

   Ftree.Populate_Group_From_Tree('tree_data_rg', htree, find_node);

END;


POPULATE_GROUP_WITH_QUERY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Populates a record group with the given query.  The record group is cleared and rows that are fetched replace any existing rows in the record group.

If the SELECT statement fails, Form Builder returns an ORACLE error number.  If the query is successful, this built-in returns 0 (zero).

You can use this built-in to populate record groups that were created by a call to either:

•	the CREATE_GROUP built-in or

•	the CREATE_GROUP_FROM_QUERY built-in

When you use this built-in, the indicated query becomes the default query for the group, and will be executed whenever the POPULATE_GROUP built-in is subsequently called.

Note: Be aware that the POPULATE_GROUP_WITH_QUERY  array fetches 20 records at a time.  To improve network performance, you may want to restrict queries, thus  limiting network traffic.

Syntax

FUNCTION POPULATE_GROUP_WITH_QUERY
  (recordgroup_id  RecordGroup,
   query           VARCHAR2);

FUNCTION POPULATE_GROUP_WITH_QUERY
  (recordgroup_name  VARCHAR2,
   query             VARCHAR2);

Built-in Type  unrestricted function

Returns  NUMBER

Enter Query Mode  yes

Parameters

recordgroup_id	The unique ID that Form Builder assigns when it creates the group.  The data type of the ID is RecordGroup.

recordgroup_name	The name you gave to the record group when creating it.  The data type of the name is VARCHAR2.

query	A valid SELECT statement, enclosed in single quotes.  Any columns retrieved as a result of the query take the data types of the columns in the table.  If you restrict the query to a subset of the columns in the table, then Form Builder creates only those columns in the record group.  The data type of the query is VARCHAR2.


POPULATE_GROUP_WITH_QUERY restrictions

•	The columns specified in the SELECT statement must match the record group columns in number and type.


POPULATE_GROUP_WITH_QUERY examples

/*

** Built-in:  POPULATE_GROUP_WITH_QUERY
** Example:   See CREATE_GROUP
*/


POPULATE_LIST built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Removes the contents of the current list and populates the list with the values from a record group.  The record group must be created at runtime and it must have the following two column (VARCHAR2) structure:

Column 1:	Column 2:

the list label	the list value

Syntax

PROCEDURE POPULATE_LIST
  (list_id    ITEM,
   recgrp_id  RecordGroup);

PROCEDURE POPULATE_LIST
  (list_id      ITEM,
   recgrp_name  VARCHAR2);
PROCEDURE POPULATE_LIST
  (list_name  VARCHAR2,
   recgrp_id  RecordGroup);
PROCEDURE POPULATE_LIST
  (list_name    VARCHAR2,
   recgrp_name  VARCHAR2);

Built-in Type

unrestricted procedure

Enter Query Mode  yes

Parameters

list_id	Specifies the unique ID that Form Builder assigns when it creates the list item.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

list_name	The name you gave to the list item when you created it.  The data type of the name is VARCHAR2.

recgrp_id	Specifies the unique ID that Form Builder assigns when it creates the record group.  The data type of the ID is RecordGroup.

recgrp_name	The VARCHAR2 name you gave to the record group when you created it.

Usage Notes

•	Do not use the POPULATE_LIST built-in if the Mapping of Other Values property is defined and there are queried records in the block.  Doing so may cause Form Builder to be unable to display records that have already been fetched.

For example, assume that a list item contains the values A, B, and C and the Mapping of Other Values property is defined.  Assume also that these values have been fetched from the database (a query is open).  At this point, if you populate the list using POPULATE_LIST, an error will occur because Form Builder will attempt to display the previously fetched values (A, B, and C), but will be unable to because these values were removed  from the list and replaced with new values.

•	Before populating a list, close any open queries.  Use the ABORT_QUERY built-in to close an open query.


POPULATE_LIST restrictions

POPULATE_LIST returns error FRM-41337: Cannot populate the list from the record group if:

•	the record group does not contain either the default value element or the other values element and the list does not meet the criteria specified for deleting these elements with DELETE_LIST_ELEMENT.  Refer to the restrictions on DELETE_LIST_ELEMENT for more information.

•	the record group contains an other value element but the list does not meet the criteria specified for adding an other value element with ADD_LIST_ELEMENT. Refer to the restrictions on ADD_LIST_ELEMENT for more information.


POPULATE_LIST examples

/*

**  Built-in:  POPULATE_LIST
**  Example:   Retrieves the values from the current list item
**             into record group one, clears the list, and
**             populates the list with values from record group
**             two when a button is pressed.
**  Trigger:   When-Button-Pressed
*/
BEGIN
   Retrieve_List(list_id, 'RECGRP_ONE');
   Clear_List(list_id);
   Populate_List(list_id, 'RECGRP_TWO');
END;


POPULATE_TREE built-in

 Examples	 All Built-ins

Description

Clears out any data already in the hierarchical tree, and obtains the data set specified by the RecordGroup or QueryText properties.

Syntax

PROCEDURE POPULATE_TREE

  (item_name VARCHAR2);

PROCEDURE POPULATE_TREE

  (item_id ITEM);

Built-in Type   unrestricted procedure

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.


POPULATE_TREE examples

/*

** Built-in:  POPULATE_TREE
*/

-- This code will cause a tree to be re-populated using

-- either the record group or query already specified

-- for the hierarchical tree.

DECLARE

   htree         ITEM;

   top_node      FTREE.NODE;

   find_node     FTREE.NODE;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Populate the tree with data.

   Ftree.Populate_Tree(htree);

END;


POST built-in

 Examples	  Related Topics	 All Built-ins

Description

Writes data in the form to the database, but does not perform a database commit.  Form Builder first validates the form.  If there are changes to post to the database, for each block in the form Form Builder writes deletes, inserts, and updates to the database.

Any data that you post to the database is committed to the database by the next COMMIT_FORM that executes during the current Runform session.  Alternatively, this data can be rolled back by the next CLEAR_FORM.

Syntax

PROCEDURE POST;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none

Usage Notes

If this form was called via OPEN_FORM with the NO_SESSION parameter specified, then the POST will validate and write the data both in this form and in the calling form.


POST examples

/*

** Built-in:  POST and EXIT_FORM
** Example:   Leave the called form, without rolling back the
**            posted changes so they may be posted and
**            committed by the calling form as part of the
**            same transaction.
*/
BEGIN
  Post;

  /*
  ** Form_Status should be 'QUERY' if all records were
  ** successfully posted.
  */
  IF :System.Form_Status <> 'QUERY' THEN
    Message('An error prevented the system from posting changes');
    RAISE Form_Trigger_Failure;
  END IF;
  /*
  ** By default, Exit_Form asks to commit and performs a
  ** rollback to savepoint. We've already posted, so we do
  ** not need to commit, and we don't want the posted changes
  ** to be rolled back.
  */
  Exit_Form(NO_COMMIT, NO_ROLLBACK);
END;


PREVIOUS_BLOCK built-in

 Examples	     Related Topics	 All Built-ins

Description

Navigates to the first navigable item in the previous enterable block in the navigation sequence.  By default, the previous block in the navigation sequence is the block with the next lower sequence number, as defined by the block order in the Object Navigator.  However, the Previous Navigation Block block property can be set to specify a different block as the previous block for navigation purposes.

If there is no enterable block with a lower sequence, PREVIOUS_BLOCK navigates to the enterable block with the highest sequence number.

Syntax

PROCEDURE PREVIOUS_BLOCK;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


PREVIOUS_BLOCK examples

/*

** Built-in:  PREVIOUS_BLOCK
** Example:   If the current item is the first item in the
**            block, then skip back the previous block
**            instead of the default of going to the last
**            item in the same block
** Trigger:   Key-Previous-Item
*/
DECLARE
  cur_itm VARCHAR2(80) := :System.Cursor_Item;
  cur_blk VARCHAR2(80) := :System.Cursor_Block;
  frs_itm VARCHAR2(80);
BEGIN
  frs_itm := cur_blk||'.'||Get_Block_Property(cur_blk,FIRST_ITEM);
  IF cur_itm = frs_itm THEN
    Previous_Block;
  ELSE
    Previous_Item;
  END IF;
END;


PREVIOUS_FORM built-in

 Restrictions	    Related Topics	 All Built-ins

Description

In a multiple-form application, navigates to the form with the next lowest sequence number. (Forms are sequenced in the order they were invoked at runtime.) If there is no form with a lower sequence number, PREVIOUS_FORM navigates to the form with the highest sequence number. If there is no such form, the current form remains current.

When navigating with PREVIOUS_FORM, no validation occurs and no triggers fire except WHEN-WINDOW-DEACTIVATED, which fires for the form that initiates navigation, and WHEN-WINDOW-ACTIVATED, which fires for the target form.

Syntax

PROCEDURE PREVIOUS_FORM;

Built-in Type   restricted procedure

Enter Query Mode  no


PREVIOUS_FORM restrictions

The target form cannot be a form that is currently disabled as a result of having invoked another form with CALL_FORM.


PREVIOUS_ITEM built-in

 Examples	     Related Topics	 All Built-ins

Description

Navigates to the navigable item with the next lower sequence number than the current item.  If there is no such item, PREVIOUS_ITEM navigates to the navigable item with the highest sequence number.  If there is no such item, PREVIOUS_ITEM navigates to the current item.

The function of PREVIOUS_ITEM from the first navigable item in the block depends on the setting of the Navigation Style block property.  The valid settings for Navigation Style include:

Same Record (Default):  A Previous Item operation from a block's first item moves the input focus to the last navigable item in the block, in that same record.

Change Record:  A Previous Item operation from a block's first item moves the input focus to the last navigable item in the block, in the previous record.

Change Block:  A Previous Item operation from a block's first item moves the input focus to the last navigable item in the current record of the previous block.

Syntax

PROCEDURE PREVIOUS_ITEM;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none


PREVIOUS_ITEM examples

/*

** Built-in:  PREVIOUS_ITEM
** Example:   See PREVIOUS_BLOCK
*/


PREVIOUS_MENU built-in

 Restrictions	 All Built-ins

Description

PREVIOUS_MENU navigates to the previously active item in the previous menu.

Syntax

PROCEDURE PREVIOUS_MENU;

Built-in Type   restricted procedure

Parameters

none


PREVIOUS_MENU restrictions

PREVIOUS_MENU applies only in full-screen and bar menus.


PREVIOUS_MENU_ITEM built-in

 Restrictions	 All Built-ins

Description

PREVIOUS_MENU_ITEM navigates to the previous menu item in the current menu.

Syntax

PROCEDURE PREVIOUS_MENU_ITEM;

Built-in Type   restricted procedure

Parameters

none


PREVIOUS_MENU_ITEM restrictions

PREVIOUS_MENU_ITEM applies only in full-screen menus.


PREVIOUS_RECORD built-in

 Examples	     Related Topics	 All Built-ins

Description

Navigates to the first enabled and navigable item in the record with the next lower sequence number than the current record.

Syntax

PROCEDURE PREVIOUS_RECORD;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


PREVIOUS_RECORD examples

/*

** Built-in:  PREVIOUS_RECORD
** Example:   If the current item is the first item in the
**            block, then skip back to the previous record
**            instead of the default of going to the last
**            item in the same block
** Trigger:   Key-Previous-Item
*/
DECLARE
  cur_itm VARCHAR2(80) := :System.Cursor_Item;
  cur_blk VARCHAR2(80) := :System.Cursor_Block;
  frs_itm VARCHAR2(80);
BEGIN
  frs_itm := cur_blk||'.'||Get_Block_Property(cur_blk,FIRST_ITEM);
  IF cur_itm = frs_itm THEN
    Previous_Record;
  ELSE
    Previous_Item;
  END IF;
END;


PRINT built-in

 Examples	 All Built-ins

Description

Prints the current window to a file or to the printer.

Syntax

PROCEDURE PRINT;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


PRINT examples

/*

** Built-in:  PRINT
** Example:   Print the current window.
*/
BEGIN
  Print;
END;


PTR_TO_VAR

 All Built-ins

Description

First, creates an OLE variant of type VT_PTR that contains the supplied address.  Then, passes that variant and type through the function VARPTR_TO_VAR.

Syntax

FUNCTION PTR_TO_VAR
  (address PLS_INTEGER, vtype VT_TYPE)
RETURN newvar OLEVAR;

Built-in Type  unrestricted function

Returns  the created and transformed OLE variant.

Parameters

address	A variable whose value is an address.
vtype	The type to be given to the final version of the OLE variant (after its processing by VARPTR_TO_VAR).
Usage Notes

In most applications, there is no need to use this function.  If the function is used, care must be taken to ensure that the correct address value is placed in the new variant.


QUERY_PARAMETER built-in

 Examples	 All Built-ins

Description

Displays the Query Parameter dialog showing the current values of the specified substitution parameters.  End users can set the value of any parameter you include in the list.

The Query Parameter dialog is modal, and control does not return to the calling trigger or procedure until the end user either accepts or cancels the dialog. This means that any PL/SQL statements that follow the call to QUERY_PARAMETER are not executed until the Query Parameter dialog is dismissed.

Syntax

PROCEDURE QUERY_PARAMETER
  (parameter_string  VARCHAR2);

Built-in Type   unrestricted procedure

Parameters

parameter_string	Specifies a string of substitution parameters for a menu item.  The syntax for specifying the parameter_string parameter requires the ampersand &parm_name.  Substitution parameters are referenced in PL/SQL code with the colon syntax ":param_name" used for all bind variables).


QUERY_PARAMETER examples

/*

** Built-in:  QUERY_PARAMETER
** Example:   Prompt for several menu parameters
**            programmatically, validating their contents.
*/
PROCEDURE Update_Warehouse IS
  validation_Err BOOLEAN;
BEGIN
  WHILE TRUE LOOP
    Query_Parameter('&p1 &q2 &z6');
    /*
    ** If the user did not Cancel the box the Menu_Success
    ** function will return boolean TRUE.
    */
    IF Menu_Success THEN
      IF TO_NUMBER( :q2 ) NOT BETWEEN 100 AND 5000 THEN
      Message('Qty must be in the range 100..5000');
      Bell;
      Validation_Err := TRUE;
        END IF;
    /*
    ** Start a sub-block so we can catch a Value_Error
    ** exception in a local handler
    */
      BEGIN
    IF TO_DATE( :z6 ) < SYSDATE THEN
      Message('Target Date must name a day in the future.');
      Bell;
      Validation_Err := TRUE;
    END IF;
      EXCEPTION
    WHEN VALUE_ERROR THEN
      Message('Target Date must be of the form DD-MON-YY');
      Bell;
      Validation_Err := TRUE;
      END;
      /*
      ** If we get here, all parameters were valid so do the
      ** Update Statement.
      */
      IF NOT Validation_Err THEN
    UPDATE WAREHOUSE
      SET QTY_TO_ORDER = QTY_TO_ORDER*0.18
    WHERE TARGET_DATE = TO_DATE(:z6)
      AND QTY_ON_HAND > TO_NUMBER(:q2)
      AND COST_CODE LIKE :p1||'%';
      END IF;
    ELSE
      /*
      ** If Menu_Success is boolean false, then return back
      ** from the procedure since user cancelled the dialog
      */
      RETURN;
    END IF;
  END LOOP;
END;


READ_IMAGE_FILE built-in

 Examples	     Related Topics	 All Built-ins

Description

Reads an image of the given type from the given file and displays it in the Form Builder image item.

Syntax

PROCEDURE READ_IMAGE_FILE
  (file_name  VARCHAR2,
   file_type  VARCHAR2,
   item_id    ITEM);

PROCEDURE READ_IMAGE_FILE
  (file_name  VARCHAR2,
   file_type  VARCHAR2,
   item_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

file_name	Valid file name.  The file name designation can include a full path statement appropriate to your operating system.

file_type	The valid image file type:  BMP, CALS, GIF, JFIF, JPG, PICT, RAS, TIFF, or TPIC.  (Note:  File type is optional, as Form Builder will attempt to deduce it from the source image file.  To optimize performance, however, you should specify the file type.)

item_id	The unique ID Form Builder assigns to the image item when it creates it.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  Datatype is ITEM.

item_name	The name you gave the image item when you created it.  Datatype is VARCHAR2.

Usage Notes

Form Builder searches for the image file along the same default path as it searches for an .FMX file.  For more information on the specific search path for your platform, refer to the Form Builder documentation for your operating system.


READ_IMAGE_FILE examples

/* Read an image from the filesystem into an image item on the

** form. In this example, the scanned picture identification
** for each employee is NOT saved to the database, but is
** stored on the filesystem.  An employee's  photo is a TIFF
** image stored in a file named <Userid>.TIF Each employee's
** Userid is unique.
** Trigger: Post-Query
*/
DECLARE
  tiff_image_dir VARCHAR2(80) := '/usr/staff/photos/';
  photo_filename VARCHAR2(80);
BEGIN
  /*
  ** Set the message level high so we can gracefully handle
  ** an error reading the file if it occurs
  */
  :System.Message_Level := '25';
  /*
  ** After fetching an employee record, take the employee's
  ** Userid and concatenate the '.TIF' extension to derive
  ** the filename from which to load the TIFF image. The EMP
  ** record has a non-database image item named 'EMP_PHOTO'
  ** into which we read the image.
  */
  photo_filename := tiff_image_dir||LOWER(:emp.userid)||'.tif';

  /*
  ** For example 'photo_filename' might look like:
  **
  **     /usr/staff/photos/jgetty.tif
  **                       ------
  **
  ** Now, read in the appropriate image.
  */

  READ_IMAGE_FILE(photo_filename, 'TIFF', 'emp.emp_photo');
  IF NOT FORM_SUCCESS THEN
    MESSAGE('This employee does not have a photo on file.');
  END IF;
  :SYSTEM.MESSAGE_LEVEL := '0';
END;


READ_SOUND_FILE built-in

 Examples	    Related Topics	 All Built-ins

Description

Reads sound object from the specified file into the specified sound item.

Syntax

READ_SOUND_FILE(file_name VARCHAR2,
                file_type VARCHAR2,
                item_id ITEM);

READ_SOUND_FILE(file_name VARCHAR2,
                file_type VARCHAR2,
                item_name VARCHAR2);

Built-in Type

unrestricted

Enter Query Mode  Yes

Parameters:

file_name	The fully-qualified file name of the file that contains the sound object to be read.

file_type	The file type for the sound data file.  Valid values are:  AU, AIFF, AIFF-C, and WAVE.  (Note:  file type is optional, but should be specified if known for increased performance.)

item_id	The unique ID Form Builder gave the sound item when you created it.

item_name	The name you gave the sound item when you created it.

Usage Notes

•	Specifying a file type for the sound file is optional.  If you know the file type, however, specifying it can increase performance.


READ_SOUND_FILE restrictions


READ_SOUND_FILE examples

/* These procedure calls (attached to a When-Button-Pressed

** trigger) reads a sound object from the file system and plays
** it. Note: since a sound item must have focus in order to play
** a sound object, the trigger code includes a call to the
** built-in procedure GO_ITEM:
*/
BEGIN
  IF :clerks.last_name EQ 'BARNES' THEN
    GO_ITEM('orders.filled_by');
    READ_SOUND_FILE('t:\orders\clerk\barnes.wav',
                    'wave',
                    'orders.filled_by');
    PLAY_SOUND('orders.filled_by');
  END IF;
END;


RECALCULATE built-in

 Restrictions	    Related Topics	 All Built-ins

Description

Marks the value of the specified formula calculated item (in each record of the block) for recalculation.  Typically you would invoke this when the formula (or function or procedure that it invokes) refers to a system variable or built-in function which now would return a different value.

Note that actual recalculation doesn't happen immediately;  it occurs sometime after the item is marked but before the new value of the calculated item is referenced or displayed to the end user.  Your application's logic should not depend on recalculation of a calculated item occurring at a specific time.

Syntax

PROCEDURE RECALCULATE
  (item_name  VARCHAR2);

PROCEDURE RECALCULATE
  (item_id  Item);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

item_name	The name you gave the item when you defined it.  Datatype is VARCHAR2.

item_id	The unique ID Form Builder assigned to the item when it created the item.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  Datatype is Item.


RECALCULATE restrictions

You can use the RECALCULATE built-in to recalculate formula calculated items only;  if you specify a summary item (or a non-calculated item) as the argument to RECALCULATE, Form Builder will return an error message:

   FRM-41379: Cannot recalculate non-formula item   <block_name.item_name>.


REDISPLAY built-in

 All Built-ins

Description

Redraws the screen.  This clears any existing system messages displayed on the screen.

Syntax

PROCEDURE REDISPLAY;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


RELEASE_OBJ

 All Built-ins

Description

Shuts down the connection to the OLE object.

Syntax

PROCEDURE RELEASE_OBJ
  (obj OLEOBJ, kill_persistence_boolean := NULL);

Built-in Type  unrestricted procedure

Parameters

obj	Pointer to the OLE object to be released.
Kill_persistence_boolean	A boolean value of NULL releases the object, ending its persistence. A boolean value of TRUE releases only a persistent object.  If you don't have a pointer to a persistent object, your code will misbehave.   A boolean value of FALSE releases only a non-persistent object.  If you don't have a pointer to a non-persistent object, you will get error FRM-40935. This is an optional parameter.  If not supplied, the default value is NULL (release object unconditionally).
Usage Notes

In general, you should not access an object after you release it.

The conditional form of this procedure (boolean TRUE or FALSE) should be used only in those rare cases when two instances of an object have been created, each carrying different persistence values, and the pointer is ambiguous.  The procedure will release one of the two objects, leaving the other as the sole instance.


REPLACE_CONTENT_VIEW built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Replaces the content canvas currently displayed in the indicated window with a different content canvas.

Syntax

PROCEDURE REPLACE_CONTENT_VIEW
  (window_id  Window,
   view_id    ViewPort);

PROCEDURE REPLACE_CONTENT_VIEW
  (window_name  VARCHAR2,
   view_id      ViewPort);
PROCEDURE REPLACE_CONTENT_VIEW
  (window_id  Window,
   view_name  VARCHAR2);
PROCEDURE REPLACE_CONTENT_VIEW
  (window_name  VARCHAR2,
   view_name    VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

window_id	Specifies the unique ID that Form Builder assigns the window when created.  Use the FIND_WINDOW built-in to return the ID to an appropriately typed variable.  The data type of the ID is Window.

window_name	Specifies the name that you gave the window  when creating it.  The data type of the name is VARCHAR2.

view_id	Specifies the unique ID that Form Builder assigns the view when it creates the object.  Use the FIND_VIEW built-in to return the ID to an appropriately typed variable.  The data type of the ID is ViewPort.

view_name	Specifies the name that you gave the object when defining it.  The data type of the name is VARCHAR2.


REPLACE_CONTENT_VIEW restrictions

•	The canvas that replaces the window's current content canvas must have been assigned to that window at design time.  That is, you cannot replace a window's content view with a content view from a different window.

•	If you replace a content canvas that contains the item that currently has focus, Form Builder will immediately undo the replacement to keep the focus item visible to the end user.


REPLACE_CONTENT_VIEW examples

/*

** Built-in:  REPLACE_CONTENT_VIEW
** Example:   Replace the 'salary' view with the 'history'
**            view in the 'employee_status' window.
*/
BEGIN
  Replace_Content_View('employee_status','history');
END;


REPLACE_MENU built-in

 Examples	     Related Topics	 All Built-ins

Description

Replaces the current menu with the specified menu, but does not make the new menu active.  REPLACE_MENU also allows you to change the way the menu displays and the role.

Because REPLACE_MENU does not make the new menu active, Form Builder does not allow the menu to obscure any part of the active canvas.  Therefore, all or part of the menu does not appear on the screen if the active canvas would cover it.

Syntax

REPLACE_MENU;

PROCEDURE REPLACE_MENU
  (menu_module_name  VARCHAR2);
PROCEDURE REPLACE_MENU
  (menu_module_name VARCHAR2,
   menu_type        NUMBER);
PROCEDURE REPLACE_MENU
  (menu_module_name    VARCHAR2,
   menu_type           NUMBER,
   starting_menu_name  VARCHAR2);
PROCEDURE REPLACE_MENU
  (menu_module_name  VARCHAR2,
   menu_type         NUMBER,
   starting_menu     VARCHAR2,
   group_name        VARCHAR2);
PROCEDURE REPLACE_MENU
  (menu_module_name  VARCHAR2,
   menu_type         NUMBER,
   starting_menu     VARCHAR2,
   group_name        VARCHAR2,
   use_file          BOOLEAN);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Usage Notes

REPLACE_MENU replaces the menu for all windows in the application.  If you are using CALL_FORM, REPLACE_MENU will replace the menu for both the calling form and the called form with the specified menu.

Parameters

menu_module _name	Name of the menu module that should replace the current menu module.  Datatype is VARCHAR2.  This parameter is optional; if it is omitted, Form Builder runs the form without a menu.

menu_type	The display style of the menu.  The following constants can be passed as arguments for this parameter:

PULL_DOWN  Specifies that you want Form Builder to display the menus in a pull-down style that is characteristic of most GUI platforms and some character mode platforms.

BAR  Specifies that you want Form Builder to display the menu in a bar style horizontally across the top of the root window.

FULL_SCREEN  Specifies that you want Form Builder to display the menu in a full-screen style.

starting_menu	Specifies the menu within the menu module that Form Builder should use as the starting menu.  The data type of the name is VARCHAR2.

group_name	Specifies the security role that Form Builder is to use.  If you do not specify a role name, Form Builder uses the current username to determine the role.

use_file	Indicates how Form Builder should locate the menu .MMX file to be run.  Corresponds to the Menu Source form module property.  The data type of use_file is BOOLEAN.

NULL  Specifies that Form Builder should read the current form's Menu Source property and execute REPLACE_MENU accordingly.  For example, if the form module Menu Source property is set to Yes for the current form, Form Builder executes REPLACE_MENU as if the use_file actual parameter was TRUE.

FALSE  Specifies that Form Builder should treat the menu_module value as a reference to a .MMB (binary) menu module in the database, and should query this module to get the actual name of the .MMX (executable).

TRUE  Specifies that Form Builder should treat the menu_module value as a direct reference to a .MMX menu runfile in the file system.


REPLACE_MENU examples

/*

** Built-in:    REPLACE_MENU
** Example:     Use a standard procedure to change which root
**              menu in the current menu application appears in
**              the menu bar. A single menu application may
**              have multiple "root-menus" which an application
**              can dynamically set at runtime.
*/
PROCEDURE Change_Root_To(root_menu_name VARCHAR2) IS
BEGIN
  Replace_Menu('MYAPPLSTD', PULL_DOWN, root_menu_name);
END;


REPORT_OBJECT_STATUS built-in

 Examples	 All Built-ins

Description

Provides status of a report object run  within a form by the RUN_REPORT_OBJECT built-in.

Syntax

FUNCTION REPORT_OBJECT_STATUS
  (report_id VARCHAR2(20)
);

Built-in Type  unrestricted function

Enter Query Mode yes

Parameters

report_id	The VARCHAR2 value returned by the RUN_REPORT_OBJECT built-in. This value uniquely identifies the report that is currently running either locally or on a remote report server.

Usage Notes

There are eight possible return values for this built-in: finished, running, canceled, opening_report, enqueued, invalid_job, terminated_with_error, and crashed.


REPORT_OBJECT_STATUS examples

DECLARE

repid REPORT_OBJECT;

v_rep  VARCHAR2(100);

rep_status varchar2(20);

BEGIN

repid := find_report_object('report4');

v_rep := RUN_REPORT_OBJECT(repid);

rep_status := REPORT_OBJECT_STATUS(v_rep);

if rep_status = 'FINISHED' then

message('Report Completed');

copy_report_object_output(v_rep,'d:\temp\local.pdf');

host('netscape d:\temp\local.pdf');

else

message('Error when running report.');

end if;

END;


RESET_GROUP_SELECTION built-in

 Examples	     Related Topics	 All Built-ins

Description

Deselects any selected rows in the given group. Use this built-in to deselect all record group rows that have been programmatically marked as selected by executing SET_GROUP_SELECTION on individual rows.

Syntax

PROCEDURE RESET_GROUP_SELECTION
  (recordgroup_id  RecordGroup);

PROCEDURE RESET_GROUP_SELECTION
  (recordgroup_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

recordgroup_id	The unique ID that Form Builder assigns when it creates the group.  The data type of the ID is RecordGroup.

recordgroup_name	The name you gave to the record group when creating it.  The data type of the name is VARCHAR2.


RESET_GROUP_SELECTION examples

/*

** Built-in:  RESET_GROUP_SELECTION
** Example:   If the user presses the (Cancel) button, forget
**            all of the records in the 'USERSEL' record
**            group that we may have previously marked as
**            selected records.
** Trigger:   When-Button-Pressed
*/
BEGIN
  Reset_Group_Selection( 'usersel' );
END;


RESIZE_WINDOW built-in

 Examples	     Related Topics	 All Built-ins

Description

Changes the size of the given window to the given width and height.  A call to RESIZE_WINDOW sets the width and height of the window, even if the window is not currently displayed.  RESIZE_WINDOW does not change the position of the window, as specified by the x and y coordinates of the window's upper left corner on the screen.

On Microsoft Windows, you can resize the MDI application window by specifying the constant FORMS_MDI_WINDOW as the window name.

You can also resize a window with SET_WINDOW_PROPERTY.

Syntax

PROCEDURE RESIZE_WINDOW
  (window_id  Window,
   width      NUMBER,
   height     NUMBER);

PROCEDURE RESIZE_WINDOW
  (window_name  VARCHAR2,
   width        NUMBER,
   height       NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

window_id	Specifies the unique ID that Form Builder assigns the window when created.  Use the FIND_WINDOW built-in to return the ID to an appropriately typed variable.  The data type of the ID is Window.

window_name	Specifies the name that you gave the window  when creating it.  The data type of the name is VARCHAR2.

width	Specifies the new width of the window, in form coordinate units.

height	Specifies the new height of the window, in form coordinate units.


RESIZE_WINDOW examples

/*

** Built-in:  RESIZE_WINDOW
** Example:   Set Window2 to be the same size as Window1
*/
PROCEDURE Make_Same_Size_Win( Window1 VARCHAR2, Window2 VARCHAR2) IS
  wn_id1 Window;
  w      NUMBER;
  h      NUMBER;
BEGIN
  /*
  ** Find Window1 and get it's width and height.
  */
  wn_id1 := Find_Window(Window1);
  w      := Get_Window_Property(wn_id1,WIDTH);
  h      := Get_Window_Property(wn_id1,HEIGHT);
  /*
  ** Resize Window2 to the same size
  */
  Resize_Window( Window2, w, h );
END;


RETRIEVE_LIST built-in

 Examples	     Related Topics	 All Built-ins

Description

Retrieves and stores the contents of the current list into the specified record group.  The target record group must have the following two-column (VARCHAR2) structure:

Column 1:	Column 2:

the list label	the list value

Storing the contents of a list item allows you to restore the list with its former contents.

Syntax

PROCEDURE RETRIEVE_LIST
  (list_id      ITEM,
   recgrp_name  VARCHAR2);

PROCEDURE RETRIEVE_LIST
  (list_id    ITEM,
   recgrp_id  RecordGroup);
PROCEDURE RETRIEVE_LIST
  (list_name  VARCHAR2,
   recgrp_id  RecordGroup);
PROCEDURE RETRIEVE_LIST
  (list_name    VARCHAR2,
   recgrp_name  VARCHAR2);

Built-in Type  unrestricted procedure

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

list_id	Specifies the unique ID that Form Builder assigns when it creates the list item.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

list_name	The name you gave to the list item when you created it.  The data type of the name is VARCHAR2.

recgrp_id	Specifies the unique ID that Form Builder assigns when it creates the record group.  The data type of the ID is RecordGroup.

recgrp_name	The VARCHAR2 name you gave to the record group when you created it.


RETRIEVE_LIST examples

/*

**  Built-in:  RETRIEVE_LIST
**  Example:   See POPULATE_LIST
*/


RUN_PRODUCT built-in

 Examples	     Related Topics	 All Built-ins

Description

Invokes one of the supported Oracle tools products and specifies the name of the module or module to be run.  If the called product is unavailable at the time of the call, Form Builder returns a message to the end user.

If you create a parameter list and then reference it in the call to RUN_PRODUCT, the form can pass text and data parameters to the called product that represent values for command line parameters, bind or lexical references, and named queries. Parameters of type DATA_PARAMETER are pointers to record groups in Form Builder. You can pass DATA_PARAMETERs to Report Builder and Graphics Builder, but not to Form Builder.

To run a report from within a form, you can alternatively use the dedicated report integration built-in RUN_REPORT_OBJECT .

Syntax

PROCEDURE RUN_PRODUCT
  (product   NUMBER,
   module  VARCHAR2,
   commmode  NUMBER,
   execmode  NUMBER,
   location  NUMBER,
   paramlist_id      VARCHAR2,
   display   VARCHAR2);

PROCEDURE RUN_PRODUCT
  (product   NUMBER,
   module  VARCHAR2,
   commmode  NUMBER,
   execmode  NUMBER,
   location  NUMBER,
   paramlist_name      VARCHAR2,
   display   VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

product	Specifies a numeric constant for the Oracle product you want to invoke: FORMS specifies a Runform session. GRAPHICS specifies Graphics Builder.  REPORTS specifies Report Builder. BOOK specifies Oracle Book.

module	Specifies the VARCHAR2 name of the module or module to be executed by the called product.  Valid values are the name of a form module, report, Graphics Builder display, or Oracle Book module.  The application looks for the module or module in the default paths defined for the called product.

commmode	Specifies the communication mode to be used when running the called product.  Valid numeric constants for this parameter are SYNCHRONOUS and ASYNCHRONOUS.

SYNCHRONOUS specifies that control returns to Form Builder only after the called product has been exited.  The end user cannot work in the form while the called product is running.

ASYNCHRONOUS specifies that control returns to the calling application immediately, even if the called application has not completed its display.

execmode	Specifies the execution mode to be used when running the called product.  Valid numeric constants for this parameter are BATCH and RUNTIME.  When you run Report Builder and Graphics Builder, execmode can be either BATCH or RUNTIME.  When you run Form Builder, always set execmode to RUNTIME.

location	Specifies the location of the module or module you want the called product to execute, either the file system or the database.  Valid constants for this property are FILESYSTEM and DB.

Paramlist_name or paramlist_ID	Specifies the parameter list to be passed to the called product.  Valid values for this parameter are the VARCHAR2 name of the parameter list, the ID of the parameter list, or a null string ('').  To specify a parameter list ID, use a variable of type PARAMLIST.

You can pass text parameters to called products in both SYNCHRONOUS and ASYNCHRONOUS mode. However, parameter lists that contain parameters of type DATA_PARAMETER (pointers to record groups) can only be passed to Report Builder and Graphics Builder in SYNCHRONOUS mode.  (SYNCHRONOUS mode is required when invoking Graphics Builder to return an Graphics Builder display that will be displayed in a form chart item.)

Note: You can prevent Graphics Builder from logging on by passing a parameter list that includes a parameter with key set to LOGON and value set to NO.

Note:  You cannot pass a DATA_PARAMETER to a child query in Report Builder. Data passing is supported only for master queries.

display	Specifies the VARCHAR2 name of the Form Builder chart item that will contain the display (such as a pie chart, bar chart, or graph) generated by Graphics Builder.  The name of the chart item must be specified in the format block_name.item_name. (This parameter is only required when you are using an Graphics Builder chart item in a form.)


RUN_PRODUCT examples

/*

** Built-in:  RUN_PRODUCT
** Example:   Call a Report Builder report, passing the
**            data in record group 'EMP_RECS' to substitute
**            for the report's query named 'EMP_QUERY'.
**            Presumes the Emp_Recs record group already
**            exists and has the same column/data type
**            structure as the report's Emp_Query query.
*/
PROCEDURE Run_Emp_Report IS
  pl_id ParamList;
BEGIN
  /*
  ** Check to see if the 'tmpdata' parameter list exists.
  */
  pl_id := Get_Parameter_List('tmpdata');
  /*
  ** If it does, then delete it before we create it again in
  ** case it contains parameters that are not useful for our
  ** purposes here.
  */
  IF NOT Id_Null(pl_id) THEN
    Destroy_Parameter_List( pl_id );
  END IF;
  /*
  ** Create the 'tmpdata' parameter list afresh.
  */
  pl_id := Create_Parameter_List('tmpdata');
  /*
  ** Add a data parameter to this parameter list that will
  ** establish the relationship between the named query
  ** 'EMP_QUERY' in the report, and the record group named
  ** 'EMP_RECS' in the form.
  */
  Add_Parameter(pl_id,'EMP_QUERY',DATA_PARAMETER,'EMP_RECS');
  /*
  **Pass a Parameter into PARAMFORM so that a parameter dialog will not appear
  **for the parameters being passing in.
  */

  Add_Parameter(pl_id, 'PARAMFORM', TEXT_PARAMETER, 'NO');

  /*
  ** Run the report synchronously, passing the parameter list
  */
  Run_Product(REPORTS, 'empreport', SYNCHRONOUS, RUNTIME,
           FILESYSTEM, pl_id, NULL);
END;


RUN_REPORT_OBJECT built-in

 Examples	 All Built-ins

Description

Use this built-in to run a report from within a form. You can run the report against either a local or remote database server. Executing this built-in is similar using the RUN_PRODUCT built-in on a report.

Syntax

FUNCTION RUN_REPORT_OBJECT
  (report_id REPORT_OBJECT
);

Built-in Type  unrestricted procedure

Returns   VARCHAR2

Enter Query Mode yes

Parameters

report_id	Specifies the unique ID of the report to be run. You can get the report ID for a particular report using the built-in FIND_REPORT_OBJECT.

Usage Notes

•	Returns a VARCHAR2 value that uniquely identifies the report that is running either locally or on a remote report server. You can use this report ID string as a parameter to REPORT_OBJECT_STATUS , COPY_REPORT_OBJECT , and CANCEL_REPORT_OBJECT.

If you invoke Run_Report_Object with a blank Report Server property, the return value will be NULL.  In that case, you cannot then use the built-ins Report_Object_Status and Copy_Report_Object_Output, because they require an actual ID value.


RUN_REPORT_OBJECT examples

DECLARE

repid REPORT_OBJECT;

v_rep  VARCHAR2(100);

rep_status varchar2(20);

BEGIN

repid := find_report_object('report4');

v_rep := RUN_REPORT_OBJECT(repid);

......

END;


SCROLL_DOWN built-in

 Examples	     Related Topics	 All Built-ins

Description

Scrolls the current block's list of records so that previously hidden records with higher sequence numbers are displayed.  If there are available records and a query is open in the block, Form Builder fetches records during SCROLL_DOWN processing. In a single-line block, SCROLL_DOWN displays the next record in the block's list of records.  SCROLL_DOWN puts the input focus in the instance of the current item in the displayed record with the lowest sequence number.

Syntax

PROCEDURE SCROLL_DOWN;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


SCROLL_DOWN examples

/*

** Built-in:  SCROLL_DOWN
** Example:   Scroll records down some.
*/
BEGIN
Scroll_Down;
END;


SCROLL_UP built-in

 Examples	     Related Topics	 All Built-ins

Description

Scrolls the current block's list of records so that previously hidden records with lower sequence numbers are displayed.  This action displays records that were "above" the block's display.

SCROLL_UP puts the input focus in the instance of the current item in the displayed record that has the highest sequence number.

Syntax

PROCEDURE SCROLL_UP;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


SCROLL_UP examples

/*

** Built-in:  SCROLL_UP
** Example:   Scroll records up some.
*/
BEGIN
  Scroll_Up;
END;


SCROLL_VIEW built-in

 Examples	     Related Topics	 All Built-ins

Description

Moves the view to a different position on its canvas by changing the Viewport X Position on Canvas and Viewport Y Position on Canvas properties. Moving the view makes a different area of the canvas visible to the operator, but does not change the position of the view within the window.

Note: For a content or toolbar canvas, the window in which the canvas is displayed represents the view for that canvas. For a stacked canvas, the view size is controlled by setting the Viewport Width and Viewport Height properties.

Syntax

PROCEDURE SCROLL_VIEW
  (view_id  ViewPort,
   x        NUMBER,
   y        NUMBER);

PROCEDURE SCROLL_VIEW
  (view_name  VARCHAR2,
   x          NUMBER,
   y          NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

view_id	Specifies the unique ID that Form Builder assigns the view when it creates the object.  Use the FIND_VIEW built-in to return the ID to an appropriately typed variable.  The data type of the ID is ViewPort.

view_name	Specifies the name that you gave the object when defining it.  The data type of the name is VARCHAR2.

x	Specifies the x coordinate of the view's upper left corner relative to the upper left corner of the canvas.

y	Specifies the y coordinate of the view's upper left corner relative to the upper left corner of the canvas.


SCROLL_VIEW examples

/*

** Built-in:  SCROLL_VIEW
** Example:   Scroll the view whose name is passed in 10% to
**            the right or left depending on the 'direction'
**            parameter.
*/
PROCEDURE Scroll_Ten_Percent( viewname VARCHAR2,
                 direction VARCHAR2 ) IS
  vw_id        ViewPort;
  vw_wid       NUMBER;
  vw_x         NUMBER;
  cn_id        Canvas;
  cn_wid       NUMBER;
  ten_percent  NUMBER;
  new_x        NUMBER;
  old_y        NUMBER;
BEGIN
  /*
  ** Get the id's for the View and its corresponding canvas
  */
  vw_id := Find_View( viewname );
  cn_id := Find_Canvas( viewname );

  /*
  ** Determine the view width and corresponding canvas
  ** width.
  */
  vw_wid := Get_View_Property(vw_id,WIDTH);
  cn_wid := Get_Canvas_Property(cn_id,WIDTH);
  /*
  ** Calculate how many units of canvas width are outside of
  ** view, and determine 10% of that.
  */
  ten_percent := 0.10 * (cn_wid - vw_wid);
  /*
  ** Determine at what horizontal position the view
  ** currently is on the corresponding canvas
  */
  vw_x:= Get_View_Property(vw_id,VIEWPORT_X_POS_ON_CANVAS);
  /*
  ** Calculate the new x position of the view on its canvas
  ** to effect the 10% scroll in the proper direction.
  ** Closer than ten percent of the distance to the edge
  ** towards which we are moving, then position the view
  ** against that edge.
  */
  IF direction='LEFT' THEN
    IF vw_x > ten_percent THEN
      new_x := vw_x - ten_percent;
    ELSE
      new_x := 0;
    END IF;
  ELSIF direction='RIGHT' THEN
    IF vw_x < cn_wid - vw_wid - ten_percent THEN
      new_x := vw_x + ten_percent;
    ELSE
      new_x := cn_wid - vw_wid;
    END IF;
  END IF;
  /*
  ** Scroll the view that much horizontally
  */
  old_y := Get_View_Property(vw_id,VIEWPORT_Y_POS_ON_CANVAS);
  Scroll_View( vw_id, new_x , old_y );
END;


SELECT_ALL built-in

  Related Topics	 All Built-ins

Description

Selects the text in the current item.   Call this procedure prior to issuing a call to CUT_REGION or COPY_REGION, when you want to cut or copy the entire contents of a text item.

Syntax

PROCEDURE SELECT_ALL;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none


SELECT_RECORDS built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

When called from an On-Select trigger, initiates default Form Builder SELECT processing.  This built-in is included primarily for applications that run against a non-ORACLE data source, and use transactional triggers to replace default Form Builder transaction processing.

Syntax

PROCEDURE SELECT_RECORDS;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


SELECT_RECORDS restrictions

Valid only within an On-Select trigger.


SELECT_RECORDS examples

/*

** Built-in:  SELECT_RECORDS
** Example:   Perform Form Builder standard SELECT processing
**            based on a global flag setup at startup by the
**            form, perhaps based on a parameter.
** Trigger:  On-Select
*/
BEGIN
  /*
  ** Check the flag variable we setup at form startup
  */
  IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
    User_Exit('my_select block=EMP');
  /*
  ** Otherwise, do the right thing.
  */
  ELSE
    Select_Records;
  END IF;
END;


FORMS_OLE.SERVER_ACTIVE
SERVER_ACTIVE

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Indicates whether or not the server associated with a given container is running:

•	Returns TRUE if the OLE server is running.

•	Returns FALSE if the OLE server is not running.

You must define an appropriately typed variable to accept the return value.

Syntax

FUNCTION SERVER_ACTIVE
  (item_id  Item);

FUNCTION SERVER_ACTIVE
  (item_name  VARCHAR2);

Returns  BOOLEAN

Built-in Type  unrestricted function

Enter Query Mode  no

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is Item.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.


FORMS_OLE.SERVER_ACTIVE restrictions
SERVER_ACTIVE restrictions

Valid only on Microsoft Windows and Macintosh.


FORMS_OLE.SERVER_ACTIVE examples
SERVER_ACTIVE examples

/*

** Built-in: SERVER_ACTIVE
** Example:  Checks to see if the OLE server is active.
** Trigger:  When-Button-Pressed
*/
DECLARE
 item_id  ITEM;
 item_name VARCHAR(25) := 'OLEITM';
 active_serv BOOLEAN;
BEGIN
 item_id := Find_Item(item_name);
 IF Id_Null(item_id) THEN
  message('No such item: '||item_name);
 ELSE
  active_serv := Forms_OLE.Server_Active(item_id);
  IF active_serv = FALSE THEN
   Forms_OLE.Activate_Server(item_id);
  END IF;
 END IF;
END;


SET_ALERT_BUTTON_PROPERTY built-in

 All Built-ins

Description

Changes the label on one of the buttons in an alert.

Syntax

PROCEDURE SET_ALERT_BUTTON_PROPERTY
  (alert_id  ALERT,
   button    NUMBER,
   property  VARCHAR2,
   value     VARCHAR2);

PROCEDURE SET_ALERT_BUTTON_PROPERTY
  (alert_name  VARCHAR2,
   button      NUMBER,
   property    VARCHAR2,
   value       VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

alert_id	Specifies the unique ID (data type ALERT) that Form Builder assigns to the alert when it is created.  Use FIND_ALERT to return the ID to an appropriately typed variable.

alert_name	Specifies the VARCHAR2 name of the alert.

buttoA	constant that specifies the alert button you want to change, either ALERT_BUTTON1, ALERT_BUTTON2, or ALERT_BUTTON3.

property	LABEL  Specifies the label text for the alert button.

value	Specifies the VARCHAR2 value to be applied to the  property you specified.

Usage Notes

If the label specified is NULL, the button's label reverts to the label specified at design time.


SET_ALERT_PROPERTY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Changes the message text for an existing alert.

Syntax

SET_ALERT_PROPERTY
  (alert_id  ALERT,
   property  NUMBER,
   message   VARCHAR2);

SET_ALERT_PROPERTY
  (alert_name  VARCHAR2,
   property    NUMBER,
   message     VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

alert_id	Specifies the unique ID (data type ALERT) that Form Builder assigns to the alert when it is created.  Return the ID to an appropriately typed variable.

alert_name	Specifies the VARCHAR2 name of the alert.

property	Specifies the specific alert property you are setting:

ALERT_MESSAGE_TEXT  Specifies that you are setting the text of the alert message.

TITLE  Specifies the title of the alert. Overrides the value specified in Form Builder unless the property value is NULL.

message	Specifies the message that is to replace the current alert message.  Pass the message as a string enclosed in single quotes, as a variable, or in a string/variable construction.


SET_ALERT_PROPERTY restrictions

If the message text exceeds 200 characters, it will be truncated.


SET_ALERT_PROPERTY examples

/*

** Built-in:  SET_ALERT_PROPERTY
** Example:   Places the error message into a user-defined alert **            named 'My_Error_Alert' and displays the alert.
** Trigger:   On-Error
*/
DECLARE
  err_txt   VARCHAR2(80) := Error_Text;
  al_id     Alert;
  al_button Number;
BEGIN
  al_id := Find_Alert('My_Error_Alert');
  Set_Alert_Property(al_id, alert_message_text, err_txt );
  al_button := Show_Alert( al_id );
END;


SET_APPLICATION_PROPERTY built-in

  Related Topics	 All Built-ins

Description

Sets (or resets) the application property for the current application.

Syntax

SET_APPLICATION_PROPERTY
  (property  NUMBER,
   value     VARCHAR2)

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

property	Specifies the property you want to set for the given application.  The possible properties are as follows:

BUILTIN_DATE_FORMAT  Specifies the Builtin date format mask.

CURSOR_STYLE  Specifies the cursor style for the given application.

DATE_FORMAT_COMPATIBILITY_MODE  Specifies how certain date format conversion operations will be performed.

FLAG_USER_VALUE_TOO_LONG   Specifies how Form Builder should handle user-entered values that exceed an item’s Maximum Length property.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

PLSQL_DATE_FORMAT  Specifies the PLSQL date format mask.

value	The new value to be set for this property.


SET_BLOCK_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Sets the given block characteristic of the given block.

Syntax

SET_BLOCK_PROPERTY
  (block_id	Block,
   property	VARCHAR,
   value	VARCHAR);

SET_BLOCK_PROPERTY
  (block_id	Block,
   property	VARCHAR,
   x	NUMBER);

SET_BLOCK_PROPERTY
  (block_id  Block,
   property VARCHAR,

   x	NUMBER
   y	NUMBER);

SET_BLOCK_PROPERTY
  (block_name	VARCHAR2,
   property	VARCHAR,
   value	VARCHAR);

SET_BLOCK_PROPERTY
  (block_name	VARCHAR2,
   property	VARCHAR,
   x	NUMBER);

SET_BLOCK_PROPERTY
  (block_name	VARCHAR2,
   property	VARCHAR,
   x	NUMBER,
   y	NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

block_id	The unique ID Form Builder assigned to the block when you created it.  Datatype is BLOCK.

block_name	The name you gave the block when you created it.  Datatype is VARCHAR2.

property	Specify one of the following constants:

ALL_RECORDS Specifies whether all the records matching the query criteria should be fetched into the data block when a query is executed.

BLOCKSCROLLBAR_POSITION   Specifies both the x and y positions of the block's scroll bar in the form coordinate units indicated by the Coordinate System form property.

BLOCKSCROLLBAR_X_POS   Specifies the x position of the block's scroll bar in the form coordinate units indicated by the Coordinate System form property.

BLOCKSCROLLBAR_Y_POS   Specifies the y position of the block scroll bar in the form coordinate units indicated by the Coordinate System form property.

COORDINATION_STATUS Specifies a status that indicates whether a block that is a detail block in a master-detail relation is currently coordinated with all of its master blocks; that is, whether the detail records in the block correspond correctly to the current master record in the master block.  Valid values are COORDINATED and NON_COORDINATED

CURRENT_RECORD_ATTRIBUTE  Specify the VARCHAR2 name of a named visual attribute to be associated with the given block.  If the named visual attribute does not exist, you will get an error message.

CURRENT_ROW_BACKGROUND_COLOR  The color of the object's background region.

CURRENT_ROW_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

CURRENT_ROW_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

CURRENT_ROW_FONT_SIZE  The size of the font, specified in points.

CURRENT_ROW_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

CURRENT_ROW_FONT_STYLE  The style of the font.

CURRENT_ROW_FONT_WEIGHT The weight of the font.

CURRENT_ROW_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

CURRENT_ROW_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

DEFAULT_WHERE  Specifies a default WHERE clause for the block, overriding previous WHERE clauses.  (Note:  this will not override a value established at design time via the Property Palette for the data block’s WHERE clause property.)

Enclose in single quotes. The WHERE reserved word is optional.   The default WHERE clause can include references to global variables, form parameters, and item values, specified with standard bind variable syntax.

DELETE_ALLOWED  Specifies whether the operator or the application is allowed to delete records in the given block.  Valid values are PROPERTY_TRUE or PROPERTY_FALSE.

DML_DATA_TARGET_NAME  Specifies the name of the block's DML data source.

ENFORCE_PRIMARY_KEY  Specifies that any record inserted or updated in the block must have a unique characteristic in order to be committed to the database. Valid values are PROPERTY_TRUE or PROPERTY_FALSE.

INSERT_ALLOWED  Specifies whether the operator or the application is allowed to insert records in the given block.  Valid values are PROPERTY_TRUE or PROPERTY_FALSE.

KEY_MODE  Specifies the key mode for the block.  This is particularly useful when running Form Builder against non-ORACLE data sources.  Valid values are UPDATEABLE_PRIMARY_KEY and NONUPDATEABLE_PRIMARY_KEY.

LOCKING_MODE   Specifies the block's LOCKING_MODE property.  Valid values are DELAYED or IMMEDIATE.

MAX_QUERY_TIME Specifies the maximum query time.  The operator can abort a query when the elapsed time of the query exceeds the value of this property.

MAX_RECORDS_FETCHED  Specifies the maximum number of records that can be fetched.  This property is only useful when the Query All Records property is set to Yes.

NAVIGATION_STYLE  Specifies the block's NAVIGATION_STYLE property.  Valid values are SAME_RECORD, CHANGE_RECORD, or CHANGE_BLOCK.

NEXT_NAVIGATION_BLOCK  Specifies the name of the block's next navigation block.  By default, the next navigation block is the block with the next higher sequence number; however, the NEXT_NAVIGATION_BLOCK block property can be set to override the default block navigation sequence.

OPTIMIZER_HINT  Specifies a hint that Form Builder passes on to the RDBMS optimizer when constructing queries.  This allows the form designer to achieve the highest possible performance when querying blocks.

ORDER_BY  Specifies a default ORDER BY clause for the block, overriding any prior ORDER BY clause. Enclose in single quotes but do not include the actual words 'ORDER BY'.  Form Builder automatically prefixes the statement you supply with "ORDER BY."

PRECOMPUTE_SUMMARIES[Under Construction]

PREVIOUS_NAVIGATION_BLOCK  Specifies the name of the block's previous navigation block.  By default, the previous navigation block is the block with the next lower sequence number; however, the NEXT_NAVIGATION_BLOCK block property can be set to override the default block navigation sequence.

QUERY_ALLOWED  Specifies whether a query can be issued from the block, either by an operator or programmatically.  Valid values are PROPERTY_TRUE or PROPERTY_FALSE.

QUERY_DATA_SOURCE_NAME   Specifies the name of the block's query data source.  Note: You cannot set a blocks’ QUERY_DATA_SOURCE_NAME when the block’s datasource is a procedure.

QUERY_HITS  Specifies the NUMBER value that indicates the number of records identified by the COUNT_QUERY operation.

UPDATE_ALLOWED  Specifies whether the operator or the application is allowed to update records in the given block. Valid values are PROPERTY_TRUE or PROPERTY_FALSE.

UPDATE_CHANGED_COLUMNS  Specifies that only those columns updated by an operator will be sent to the database.  When Update Changed Columns Only is set to No, all columns are sent, regardless of whether they have been updated.  This can result in considerable network traffic, particularly if the block contains a LONG data type.

value	The following constants can be passed as arguments to the property values described earlier:

COORDINATED  Specifies that the COORDINATION_STATUS property should be set to COORDINATED for a block that is a detail block in a master-detail relation.

DELAYED  Specifies that you want Form Builder to lock detail records only at the execution of a commit action.

IMMEDIATE  Specifies that you want Form Builder to lock detail records immediately whenever a database record has been modified.

NON_COORDINATED  Specifies that the COORDINATION_STATUS property should be set to NON_COORDINATED for a block that is a detail block in a master-detail relation.

NON_UPDATEABLE_PRIMARY_KEY  Specifies that you want Form Builder to process records in the block on the basis that the underlying data source does not allow primary keys to be updated.

PROPERTY_TRUE   Specifies that the property is to be set to the TRUE state.  Specifically, supply as the value for DELETE_ALLOWED, INSERT_ALLOWED, QUERY_HITS, and UPDATE_ALLOWED.

PROPERTY_FALSE   Specifies that the property is to be set to the FALSE state.

UNIQUE_KEY  Specifies that you want Form Builder to process records in the block on the basis that the underlying data source uses some form of unique key, or ROWID.

UPDATEABLE_PRIMARY_KEY  Specifies that you want Form Builder to process records in the block on the basis that the underlying data source allows for primary keys to be updated.

x	The NUMBER value of the axis coordinate specified in form coordinate system units.  If setting both x and y positions this value refers to the x coordinate.  When setting the y position only, this value refers to the y coordinate.

y	The NUMBER value of the y axis coordinate specified in form coordinate system units.  This value applies when setting both x and y positions, and  can be ignored for all other properties.


SET_BLOCK_PROPERTY examples

/*

** Built-in:  SET_BLOCK_PROPERTY
** Example:   Prevent future inserts, updates, and deletes to
**            queried records in the block whose name is
**            passed as an argument to this procedure.
*/
PROCEDURE Make_Block_Query_Only( blk_name IN VARCHAR2 )
IS
  blk_id Block;
BEGIN
  /* Lookup the block's internal ID */
  blk_id := Find_Block(blk_name);
  /*
  ** If the block exists (ie the ID is Not NULL) then set
  ** the three properties for this block. Otherwise signal
  ** an error.
  */
  IF NOT Id_Null(blk_id) THEN
    Set_Block_Property(blk_id,INSERT_ALLOWED,PROPERTY_FALSE);
    Set_Block_Property(blk_id,UPDATE_ALLOWED,PROPERTY_FALSE);
    Set_Block_Property(blk_id,DELETE_ALLOWED,PROPERTY_FALSE);
  ELSE
    Message('Block '||blk_name||' does not exist.');
    RAISE Form_Trigger_Failure;
  END IF;
END;

Using BLOCKSCROLLBAR_POSITION:

/*

** Built-in:  SET_BLOCK_PROPERTY
** Example:   Set the x and y position of the block's scrollbar
** 	to the passed x and y coordinates

*/
PROCEDURE Set_Scrollbar_Pos( blk_name IN VARCHAR2, xpos IN

NUMBER, ypos IN NUMBER )
IS
BEGIN
   Set_Block_Property(blk_name, BLOCKSCROLLBAR_POSITION, xpos, ypos);

END;


SET_CANVAS_PROPERTY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Sets the given canvas property for the given canvas.

Syntax

SET_CANVAS_PROPERTY
  (canvas_id  CANVAS,
   property   NUMBER,
   value      VARCHAR2);

SET_CANVAS_PROPERTY
  (canvas_id  CANVAS,
   property   NUMBER,
   x          NUMBER);
SET_CANVAS_PROPERTY
  (canvas_id  CANVAS,
   property   NUMBER,
   x          NUMBER,
   y          NUMBER);
SET_CANVAS_PROPERTY
  (canvas_name  VARCHAR2,
   property     NUMBER,
   value        VARCHAR2);
SET_CANVAS_PROPERTY
  (canvas_name  VARCHAR2,
   property     NUMBER,
   x            NUMBER);
SET_CANVAS_PROPERTY
  (canvas_name  VARCHAR2,
   property     NUMBER,
   x            NUMBER,
   y            NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

canvas_id	The unique ID Form Builder assigned to the canvas object when you created it.  Use the FIND_CANVAS built-in to return the ID to a variable of datatype CANVAS.

canvas_name	The name you gave the canvas object when you defined it.  Datatype is VARCHAR2.

property	The property you want to set for the given canvas.  Possible properties are:

BACKGROUND_COLOR  The color of the object's background region.

CANVAS_SIZE  The dimensions of the canvas (width, height).

FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE  The size of the font, specified in points.

FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE  The style of the font.

FONT_WEIGHT  The weight of the font.

FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

HEIGHT  The height of the canvas in characters.

TOPMOST_TAB_PAGE  The name of the tab page that will appear to operators as the top-most (i.e., overlaying all other tab pages in the tab canvas).

VISUAL_ATTRIBUTE  Either a valid named visual attribute that exists in the current form, or the name of a logical attribute definition in a runtime resource file that you want Form Builder to apply to the canvas.

WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

WIDTH  The width of the canvas in characters.

value	The VARCHAR2 value to be applied to the  property you specified.

x	The NUMBER value of the x coordinate or the width, depending on the property you specified.  Specify the argument in form coordinate system units.

y	The NUMBER value of the y coordinate or the height, depending on the property you specified.  Specify the argument in form coordinate system units.


SET_CANVAS_PROPERTY restrictions

•	You cannot enter a non-existent named visual attribute.

•	If Form Builder cannot find a named visual attribute by the name you supply, it looks for the display attribute in your Oracle*Terminal resource file.


SET_CANVAS_PROPERTY examples

/* Change the "background color" by dynamically setting the

** canvas color at runtime to the name of a visual attribute
** you created:
*/
BEGIN
  SET_CANVAS_PROPERTY('my_cvs', visual_attribute, 'blue_txt');
END;


SET_CUSTOM_ITEM_PROPERTY built-in

Note:

This built-in has been replaced by the SET_CUSTOM_PROPERTY built-in  You should use that built-in in any new form.  The following information is provided only for maintenance purposes.

Description

Sets the value of a property of a JavaBean associated with a Bean Area item.

Syntax

The built-in is available for types VARCHAR2, NUMBER, or BOOLEAN.

SET_CUSTOM_ITEM_PROPERTY
  (item,
   prop-name,
   varchar2 value);

SET_CUSTOM_ITEM_PROPERTY
  (item,
   prop-name,
   number value);

SET_CUSTOM_ITEM_PROPERTY
  (item,
   prop-name,
   boolean value);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

item	The name of the Bean Area item associated with the target JavaBean.  The name can be in the form of either a varchar2 literal or a variable set to the value of the name.

prop-name	The particular property of the JavaBean container associated with this Bean Area.

value	The value for the specified property.  Value must be of type varchar2, integer, or boolean.

Usage Notes

•	In the JavaBean container, each property type must be represented by a single instance of the ID class,. created by using ID.registerProperty.

•	For each Set_Custom_Item_Property built-in executed in the form, the JavaBean container’s setProperty method is called.

•	The name of the Bean Area item can be gained through either Find_Item(‘Item_Name’), or simply via ‘Item_Name’.


SET_CUSTOM_PROPERTY built-in

  Related Topics   [image]  Examples

Description

Sets the value of a user-defined property in a Java pluggable component.

Syntax

The built-in is available for types VARCHAR2, NUMBER, or BOOLEAN.

SET_CUSTOM_PROPERTY
  (item,
   row-number,
   prop-name,
   value   VARCHAR2);

SET_CUSTOM_PROPERTY
  (item,
   row-number,
   prop-name,
   value   NUMBER);

SET_CUSTOM_PROPERTY
  (item,
   row-number,
   prop-name,
   value   BOOLEAN);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

item	The name or ID of the item associated with the target Java pluggable component. The name can be in the form of either a varchar2 literal or a variable set to the value of the name.

row-number	The row number of the instance of the item that you want to set.  (Instance row numbers begin with 1.)  If you want to set all the instances, specify the constant ALL_ROWS.

prop-name	The particular property of the Java component that you want to set.

value	The new value for the specified property.  Value must be of type varchar2, number, or boolean.

Usage Notes

•	In the Java pluggable component, each custom property must be represented by a single instance of the ID class, created by using ID.registerProperty.

•	For each Set_Custom_Property built-in executed in the form, the Java component’s setProperty method is called.

•	The name of the item can be gained through either Find_Item(‘Item_Name’), or simply via ‘Item_Name’.


SET_CUSTOM_PROPERTY built-in:  example

In this example, the Java pluggable component is a JavaBean.  (To see the full context for this partial code, look at the complete example.)

In the container (or wrapper) for the JavaBean:

     private static final ID SETRATE = ID.registerProperty(“SetAnimationRate”);

In the form, as part of the PL/SQL code activated by a When_Button_Pressed trigger on a “faster” button on the end-user’s screen:

   NewAnimationRate := gb.CurAnimationRate + 25

     . . .

   Set_Custom_Property(’Juggler_Bean’, ALL_ROWS, ’SetAnimationRate’, NewAnimationRate);

In this Set_Custom_Property built-in:

•	Juggler_Bean is the name of the Bean Area item in the form.  The item is associated with the container of the JavaBean.

•	SetAnimationRate is a property in the container for the JavaBean.

•	NewAnimationRate is a variable holding the new value for that property that is being passed to the JavaBean container.


SET_FORM_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Sets a property of the given form.

Syntax

SET_FORM_PROPERTY
  (formmodule_id  FormModule,
   property       NUMBER,
   value          NUMBER);

SET_FORM_PROPERTY
  (formmodule_name  VARCHAR2,
   property         NUMBER,
   value            NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

formmodule_id	Specifies the unique ID that Form Builder assigns to the form when created.  The data type of the ID is FormModule.

formmodule_name	Specifies the name of the form module that you gave the form when creating it.  The data type of the name is VARCHAR2.

property	Specifies the property you want to set for the form:

CURRENT_RECORD_ATTRIBUTE  Specify the VARCHAR2 name of a named visual attribute to be associated with the given form.  If the named visual attribute does not exist, you will get an error message.

CURRENT_ROW_BACKGROUND_COLOR  The color of the object's background region.

CURRENT_ROW_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

CURRENT_ROW_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

CURRENT_ROW_FONT_SIZE  The size of the font, specified in points.

CURRENT_ROW_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

CURRENT_ROW_FONT_STYLE  The style of the font.

CURRENT_ROW_FONT_WEIGHT The weight of the font.

CURRENT_ROW_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

CURRENT_ROW_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

CURSOR_MODE  Specifies the cursor state Form Builder should attempt to define.  Primarily used when connecting to non-ORACLE data sources.  Valid values are OPEN_AT_COMMIT and CLOSE_AT_COMMIT.

DEFER_REQUIRED_ENFORCEMENT  Specifies whether enforcement of required fields has been deferred from item validation to record validation.  Valid values are PROPERTY_TRUE, PROPERTY_4_5,  and PROPERTY_FALSE.

DIRECTION   Specifies the layout direction for bidirectional objects.  Valid values are DIRECTION_DEFAULT,  RIGHT_TO_LEFT, LEFT_TO_RIGHT.

FIRST_NAVIGATION_BLOCK  Returns the name of the block into which Form Builder attempts to navigate at form startup.  By default, the first navigation block is the first block defined in the Object Navigator; however, the FIRST_NAVIGATION_BLOCK block property can be set to specify a different block as the first block at form startup.

SAVEPOINT_MODE  Specifies whether Form Builder is to issue savepoints.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

VALIDATION  Specifies whether Form Builder is to perform default validation.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

VALIDATION_UNIT  Specifies the scope of validation for the form.  Valid values are DEFAULT_SCOPE, BLOCK_SCOPE, RECORD_SCOPE, and ITEM_SCOPE.

value	The following constants can be passed as arguments to the property values described earlier:

BLOCK_SCOPE  Specify when you want Form Builder to validate data only at the block level.  This means, for instance, that Form Builder validates all the records in a block when a navigation event forces validation by leaving the block.

CLOSE_AT_COMMIT  Specify when you do not want cursors to remain open across database commits; for example, when a form is running against a non-ORACLE database.

DEFAULT_SCOPE  Sets the Validation Unit form module property to the default setting.  On GUI window managers, the default validation unit is ITEM.

FORM_SCOPE  Specify when you want validation to occur at the form level only.

ITEM_SCOPE.  Specify when you want Form Builder to validate at the item level.  This means, for instance, that Form Builder validates each changed item upon navigating out of an item as a result of a navigation event.

OPEN_AT_COMMIT  Specify when you want cursors to remain open across database commits.  This is the normal setting when running against ORACLE.

PROPERTY_TRUE  Specifies that the property is to be set to the TRUE state.

PROPERTY_FALSE  Specifies that the property is to be set to the FALSE state.

RECORD_SCOPE  Specify when you want Form Builder to validate at the record level.  This means that Form Builder validates each changed record when, for instance, it leaves the record.


SET_FORM_PROPERTY examples

Example 1

/*

** Built-in:  SET_FORM_PROPERTY
** Example:   Set the Cursor Mode property in the current form
**            to CLOSE_AT_COMMIT and changes the form
**            Validation unit to the Block level.
*/
DECLARE
  fm_id FormModule;
BEGIN
    fm_id := Find_Form(:System.Current_Form);
    Set_Form_Property(fm_id,CURSOR_MODE,CLOSE_AT_COMMIT);
    Set_Form_Property(fm_id,VALIDATION_UNIT,BLOCK_SCOPE);
END;

Example 2

/*

** Built-in:  SET_FORM_PROPERTY
** Example:   Setup form and block properties required to run
**            against a particular non-Oracle datasource.
**            Procedure accepts the appropriate numerical
**            constants like DELAYED as arguments.
**
** Usage:     Setup_Non_Oracle(PROPERTY_FALSE,
**                             CLOSE_AT_COMMIT,
**                             UPDATEABLE_PRIMARY_KEY,
**                             DELAYED);
*/
PROCEDURE Setup_Non_Oracle( the_savepoint_mode NUMBER,
                    the_cursor_mode    NUMBER,
                    the_key_mode       NUMBER,
                    the_locking_mode   NUMBER ) IS
  fm_id   FormModule;
  bk_id   Block;
  bk_name VARCHAR2(40);
BEGIN
  /* ** Validate the settings of the parameters ** */
  IF the_savepoint_mode NOT IN (PROPERTY_TRUE,PROPERTY_FALSE) THEN
    Message('Invalid setting for Savepoint Mode.');
    RAISE Form_Trigger_Failure;
  END IF;
  IF the_cursor_mode NOT IN (CLOSE_AT_COMMIT,OPEN_AT_COMMIT) THEN
    Message('Invalid setting for Cursor Mode.');
    RAISE Form_Trigger_Failure;
  END IF;
  IF the_key_mode NOT IN (UNIQUE_KEY,UPDATEABLE_PRIMARY_KEY,
              NON_UPDATEABLE_PRIMARY_KEY) THEN
    Message('Invalid setting for Key Mode.');
    RAISE Form_Trigger_Failure;
  END IF;
  IF the_locking_mode NOT IN (IMMEDIATE,DELAYED) THEN
    Message('Invalid setting for Locking Mode.');
    RAISE Form_Trigger_Failure;
  END IF;
  /*
  ** Get the id of the current form
  */
  fm_id := Find_Form(:System.Current_Form);
  /*
  ** Set the two form-level properties
  */
  Set_Form_Property(fm_id, SAVEPOINT_MODE, the_savepoint_mode);
  Set_Form_Property(fm_id, CURSOR_MODE, the_cursor_mode);
  /*
  ** Set the block properties for each block in the form
  */
  bk_name := Get_Form_Property(fm_id,FIRST_BLOCK);
  WHILE bk_name IS NOT NULL LOOP
    bk_id := Find_Block(bk_name);

    Set_Block_Property(bk_id,LOCKING_MODE,the_locking_mode);

    Set_Block_Property(bk_id,KEY_MODE,the_key_mode);
    IF the_key_mode IN (UPDATEABLE_PRIMARY_KEY,
               NON_UPDATEABLE_PRIMARY_KEY) THEN
      Set_Block_Property(bk_id,PRIMARY_KEY,PROPERTY_TRUE);
    END IF;

    bk_name := Get_Block_Property(bk_id, NEXTBLOCK);
  END LOOP;
END;


SET_GROUP_CHAR_CELL built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Sets the value for the record group cell identified by the given row and column.

Syntax

SET_GROUP_CHAR_CELL
  (groupcolumn_id  GroupColumn,
   row_number      NUMBER,
   cell_value      VARCHAR2);

SET_GROUP_CHAR_CELL
  (groupcolumn_name  VARCHAR2,
   row_number        NUMBER,
   cell_value        VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

groupcolumn_id	The unique ID that Form Builder assigns when it creates the column for the record group.  Use the FIND_COLUMN built-in to return the ID to an appropriately typed variable.  The data type of the ID is GroupColumn.

groupcolumn_name	The name you gave to the column when you created it, preceded by the record group name and a dot, as in recordgroup_name.groupcolumn_name.  The data type of the name is VARCHAR2.

row_number	Specifies the row number that contains the cell  whose value you intend to set.  Specify as a whole NUMBER.

cell_value	For a VARCHAR2 column, specifies the VARCHAR2 value you intend to enter into a cell; for a LONG column, specifies the LONG value you intend to enter into a cell.


SET_GROUP_CHAR_CELL restrictions

•	You must create the specified row before setting the value of a cell in that row.  Form Builder does not automatically create a new row when you indicate one in this built-in.  Explicitly add the row with the ADD_GROUP_ROW built-in or populate the group with either POPULATE_GROUP or POPULATE_GROUP_WITH_QUERY.

•	Not valid for a static record group.  A static record group is a record group that was created at design time and that has the Record Group Type property set to Static.


SET_GROUP_CHAR_CELL examples

/*

** Built-in:  SET_GROUP_CHAR_CELL
** Example:   See ADD_GROUP_ROW
*/


SET_GROUP_DATE_CELL built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Sets the value for the record group cell identified by the given row and column.

Syntax

SET_GROUP_DATE_CELL
  (groupcolumn_id  GroupColumn,
   row_number      NUMBER,
   cell_value      DATE);

SET_GROUP_DATE_CELL
  (groupcolumn_name  VARCHAR2,
   row_number        NUMBER,
   cell_value        DATE);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

groupcolumn_id	The unique ID that Form Builder assigns when it creates the column for the record group.  Use the FIND_COLUMN built-in to return the ID to an appropriately typed variable.  The data type of the ID is GroupColumn.

groupcolumn_name	The name you gave to the column when you created it, preceded by the record group name and a dot, as in recordgroup_name.groupcolumn_name.  The data type of the name is VARCHAR2.

row_number	Specifies the row number that contains the cell  whose value you intend to set.  Specify as a whole NUMBER.

cell_value	Specifies the DATE value you intend to enter into a cell.


SET_GROUP_DATE_CELL restrictions

•	You must create the specified row before setting the value of a cell in that row.  Form Builder does not automatically create a new row when you indicate one in this built-in.  Explicitly add the row with the ADD_GROUP_ROW built-in or populate the group with either POPULATE_GROUP or POPULATE_GROUP_WITH_QUERY.

•	Not valid for a static record group.  A static record group is a record group that was created at design time and that has the Record Group Type property set to Static.


SET_GROUP_DATE_CELL examples

/*

** Built-in:  SET_GROUP_DATE_CELL
** Example:   Lookup a row in a record group, and set the
**            minimum order date associated with that row in
**            the record group. Uses the 'is_value_in_list'
**            function from the GET_GROUP_CHAR_CELL example.
*/
PROCEDURE Set_Max_Order_Date_Of( part_no  VARCHAR2,
                     new_date DATE ) IS
  fnd_row NUMBER;
BEGIN
  /*
  ** Try to lookup the part number among the temporary part list
  ** record group named 'TMPPART' in its 'PARTNO' column.
  */
  fnd_row := Is_Value_In_List( part_no, 'TMPPART', 'PARTNO');

  IF fnd_row = 0 THEN
    Message('Part Number '||part_no||' not found.');
    RETURN;
  ELSE
    /*
    ** Set the corresponding Date cell value from the
    ** matching row.
    */
    Set_Group_Date_Cell('TMPPART.MAXORDDATE',fnd_row,new_date );
  END IF;
END;


SET_GROUP_NUMBER_CELL built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Sets the value for the record group cell identified by the given row and column.

Syntax

SET_GROUP_NUMBER_CELL
  (groupcolumn_id  GroupColumn,
   row_number      NUMBER,
   cell_value      NUMBER);

SET_GROUP_NUMBER_CELL
  (groupcolumn_name  VARCHAR2,
   row_number        NUMBER,
   cell_value        NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

groupcolumn_id	The unique ID that Form Builder assigns when it creates the column for the record group.  Use the FIND_COLUMN built-in to return the ID to an appropriately typed variable.  The data type of the ID is GroupColumn.

groupcolumn_name	The name you gave to the column when you created it, preceded by the record group name and a dot, as in recordgroup_name.groupcolumn_name.  The data type of the name is VARCHAR2.

row_number	Specifies the row number that contains the cell  whose value you intend to set.  Specify as a whole NUMBER.

cell_value	Specifies the NUMBER value you intend to enter into a cell.


SET_GROUP_NUMBER_CELL restrictions

•	You must create the specified row before setting the value of a cell in that row.  Explicitly add a row with the ADD_GROUP_ROW built-in or populate the group with either POPULATE_GROUP or POPULATE_GROUP_WITH_QUERY.

•	Not valid for a static record group.  A static record group is a record group that was created at design time and that has the Record Group Type property set to Static.


SET_GROUP_NUMBER_CELL examples

/*

** Built-in:  SET_GROUP_NUMBER_CELL
** Example:   See ADD_GROUP_ROW
*/


SET_GROUP_SELECTION built-in

 Examples	     Related Topics	 All Built-ins

Description

Marks the specified row in the given record group for subsequent programmatic row operations.  Rows are numbered sequentially starting at 1.  If you select rows 3, 8, and 12, for example, those rows are considered by Form Builder to be selections 1, 2, and 3.  You can undo any row selections for the entire group by calling the RESET_GROUP_SELECTION built-in.

Syntax

SET_GROUP_SELECTION
  (recordgroup_id  RecordGroup,
   row_number      NUMBER);

SET_GROUP_SELECTION
  (recordgroup_name  VARCHAR2,
   row_number        NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

recordgroup_id	Specifies the unique ID that Form Builder assigns to the record group when created.  Use the FIND_GROUP built-in to return the ID to a variable.  The data type of the ID is RecordGroup.

recordgroup_name	Specifies the name of the record group that you gave to the group when creating it.  The data type of the name is VARCHAR2.

row_number	Specifies the number of the record group row that you want to select.  The value you specify is a NUMBER.


SET_GROUP_SELECTION examples

/*

** Built-in:  SET_GROUP_SELECTION
** Example:   Set all of the even rows as selected in the
**            record group whose id is passed-in as a
**            parameter.
*/
PROCEDURE Select_Even_Rows ( rg_id RecordGroup ) IS
BEGIN
  FOR j IN 1..Get_Group_Row_Count(rg_id) LOOP
    IF MOD(j,2)=0 THEN
      Set_Group_Selection( rg_id, j );
    END IF;
  END LOOP;
END;


SET_INPUT_FOCUS built-in

 Examples	   Restrictions	 All Built-ins

Description

Sets the input focus on the menu of the current form.  Once trigger processing is completed, Form Builder activates the menu.

Syntax

SET_INPUT_FOCUS
  (MENU  );

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

MENU


SET_INPUT_FOCUS restrictions

Only for use in character mode and block mode environments.


SET_INPUT_FOCUS examples

/*

** Built-in:  SET_INPUT_FOCUS
** Example:   Directs the users input focus to the Menu when
**            used with the only support parameter, MENU.
**            Only has an effect on character-mode or
**            block-mode devices.
*/
BEGIN
  Set_Input_Focus(MENU);
END;


SET_ITEM_INSTANCE_PROPERTY built-in

 Examples	 All Built-ins

Description

Modifies the current item instance in a block by changing the specified item property. SET_ITEM_INSTANCE_PROPERTY does not change the appearance of items that mirror the current instance.

You can reference any item in the current form.  Note that SET_ITEM_INSTANCE_PROPERTY only affects the display of the current instance of the item; other instances of the specified item are not affected.  This means that if you specify a display change for an item that exists in a multi-record block, SET_ITEM_INSTANCE_PROPERTY only changes the instance of that item that belongs to the block's current record.  If you want to change all instances of an item in a multi-record block, use SET_ITEM_PROPERTY .

Any change made by a SET_ITEM_INSTANCE_PROPERTY remains in effect until:

•	the same item instance is referenced by another SET_ITEM_INSTANCE_PROPERTY, or

•	the same item instance is referenced by the DISPLAY_ITEM built-in, or

•	the instance of the item is removed (e.g., through a CLEAR_RECORD or a query), or

•	the current form is exited

Syntax

SET_ITEM_INSTANCE_PROPERTY
  (item_id   ITEM,
   record_number  NUMBER,
   property  NUMBER,
   value     VARCHAR2);

SET_ITEM_INSTANCE_PROPERTY
  (item_name  VARCHAR2,
   record_number  NUMBER,
   property   NUMBER,
   value      VARCHAR2);

SET_ITEM_INSTANCE_PROPERTY
  (item_name  VARCHAR2,
   record_number  NUMBER,
   property   NUMBER,
   value      NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

item_id	The unique ID that Form Builder assigned to the object when it created it.  Use the FIND_ITEM built-in to return the ID to a variable with datatype of ITEM.

record_number	The record number that you want to set. The record number is the record's position in the block.  Specify as a whole number. You can specify CURRENT_RECORD if you want to set the block's current record.

item_name	The name you gave the item when you created it.  Datatype is VARCHAR2.

property	The property you want to set for the given item.  Possible properties are:

BORDER_BEVEL  Specifies the item border bevel for the specified item instance.  Valid values are RAISED, LOWERED, PLAIN (unbeveled), or " ".  A value of " " causes the border bevel to be determined by the value specified at the item level at design-time or by SET_ITEM_PROPERTY at runtime.

Note:  You cannot set BORDER_BEVEL if the item's Bevel property is set to None in Form Builder.

INSERT_ALLOWED  Applies only to records not retrieved from the database.  When set to PROPERTY_TRUE at the item instance, item, and block levels, allows the end user to modify the item instance.  Setting this property to PROPERTY_FALSE at the item instance, item, or block levels, prohibits the end user from modifying the item instance.

NAVIGABLE  When set to PROPERTY_TRUE at the item instance and item levels, allows the end user to be able to navigate to the item instance using default keyboard navigation. Setting this property to PROPERTY_FALSE at the item instance or item levels, disables default keyboard navigation to the item instance.

REQUIRED  Specify the constant PROPERTY_TRUE if you want to force the end user to enter a non-null value for the item instance. Setting this property to PROPERTY_FALSE at the item instance and item levels, indicates that the item instance is not required.

UPDATE_ALLOWED  Applies only to records retrieved from the database.  When set to PROPERTY_TRUE at the item instance, item, and block levels, allows the end user to modify the item instance.  When set to PROPERTY_FALSE at the instance, item, or block levels, prohibits the end user from modifying the item instance.

VISUAL_ATTRIBUTE  Specify a valid named visual attribute that exists in the current form or ''. Specifying '' leaves visual attribute unspecified at the item instance level.

Usage Notes

When working with properties specified at multiple levels (item instance, item, and block), consider the following guidelines:

•	Required properties specified at multiple levels are ORed together

•	Other boolean properties specified at multiple levels are ANDed together

The value derived from combining properties specified at the item instance, item, and block levels is called the effective value. Some of the effects of these two rules are as follows:

•	setting INSERT_ALLOWED to true has no effect at the item instance level unless it is set consistently at the block and item levels.  For example, your user cannot type data into an item instance if INSERT_ALLOWED is true at the instance level, but not at the item or block levels.

•	setting NAVIGABLE to true has no effect at the item instance level unless it is set consistently at the item and item instance levels

•	Setting NAVIGABLE to true may affect whether the block is considered enterable.  A block’s read-only Enterable property will be true if and only if its current record contains an item instance whose effective value for the NAVIGABLE property is true.

•	setting REQUIRED to false has no effect at the item instance level unless it is set consistently at the item and item instance levels.

•	setting UPDATE_ALLOWED to true has no effect at the item instance level unless it is set consistently at the block, item, and item instance levels.

•	setting BORDER_BEVEL at the item instance level will override the item level BORDER_BEVEL setting, except when the item instance BORDER_BEVEL property is unspecified (that is, set to " ").

•	setting VISUAL_ATTRIBUTE at the item instance level will override the properties at the item and block levels unless you specify a partial visual attribute, in which case a merge will occur between the partial visual attribute and the item's current visual attribute. If VISUAL_ATTRIBUTE is set to " " at the item instance level, the item-level settings of this property are used.

•	When a new record is created, its item instance properties are set to values that do not override the values specified at higher levels. For example, the BORDER_BEVEL and VISUAL_ATTRIBUTE properties get set to " ", REQUIRED is set to false, and other boolean properties are set to true.

•	Setting an item instance property does not affect the item instance properties of any items that mirror the specified item.

•	An instance of a poplist will, when selected, display an extra null value if its current value is NULL or if its Required property is set to false.  When selecting the current value of an instance of a text list (t-list), it will be unselected (leaving the t-list with no selected value) if its Required property is set to false.  If its Required property is set to true, selecting a t-list instance's current value will have no effect, that is, the value will remain selected.


SET_ITEM_INSTANCE_PROPERTY examples

/*

** Built-in:  SET_ITEM_INSTANCE_PROPERTY
** Example: Change the visual attribute of each item instance in the
**            current record

*/
DECLARE
  cur_itm   VARCHAR2(80);
  cur_block VARCHAR2(80) := :System.Cursor_Block;
BEGIN
  cur_itm   := Get_Block_Property( cur_block, FIRST_ITEM );
  WHILE ( cur_itm IS NOT NULL ) LOOP
    cur_itm := cur_block||'.'||cur_itm;
    Set_Item_Instance_Property( cur_itm, CURRENT_RECORD,
        VISUAL_ATTRIBUTE,'My_Favorite_Named_Attribute');
    cur_itm := Get_Item_Property( cur_itm, NEXTITEM );
  END LOOP;
END;


SET_ITEM_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Modifies all instances of an item in a block by changing a specified item property.  Note that in some cases you can get but not set certain object properties.

Syntax

SET_ITEM_PROPERTY
  (item_id   ITEM,
   property  NUMBER,
   value     VARCHAR2);

SET_ITEM_PROPERTY
  (item_name  VARCHAR2,
   property   NUMBER,
   value      VARCHAR2);

SET_ITEM_PROPERTY
  (item_id   ITEM,
   property  NUMBER,
   x         NUMBER);

SET_ITEM_PROPERTY
  (item_name  VARCHAR2,
   property   NUMBER,
   x          NUMBER);

SET_ITEM_PROPERTY
  (item_id   ITEM,
   property  NUMBER,
   x         NUMBER,
   y         NUMBER);

SET_ITEM_PROPERTY
  (item_name  VARCHAR2,
   property   NUMBER,
   x          NUMBER,
   y          NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

item_id	The unique ID that Form Builder assigned to the object when it created it.  Use the FIND_ITEM built-in to return the ID to a variable with datatype of ITEM.

item_name	The name you gave the item when you created it.  Datatype is VARCHAR2.

property	The property you want to set for the given item.  Possible properties are:

ALIGNMENT  The text alignment (text and display items only).  Valid values are ALIGNMENT_START, ALIGNMENT_END, ALIGNMENT_LEFT, ALIGNMENT_ CENTER, ALIGNMENT_RIGHT.

AUTO_HINT  Determines if Form Builder will display help hints on the status line automatically when input focus is in the specified item.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

AUTO_SKIP  Specifies whether the cursor should skip to the next item automatically when the end user enters the last character in a text item.  Valid only for a text item.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

BACKGROUND_COLOR  The color of the object's background region.

BORDER_BEVEL  Specifies the item border bevel for the specified item instance.  Valid values are RAISED, LOWERED, or PLAIN (unbeveled).

Note:  You cannot set BORDER_BEVEL if the item's Bevel property is set to None in Form Builder.

CASE_INSENSITIVE_QUERY  Specifies whether query conditions entered in the item should be case-sensitive.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

CASE_RESTRICTION  Specifies the case restriction applied to any text entered in the indicated text item.  Valid values are UPPERCASE, LOWERCASE, or NONE.

COMPRESSSpecifies whether the sound data from a sound object should be compressed before Form Builder writes the data to the file.  Valid values are COMPRESSION_ON, COMPRESSION_OFF, and ORIGINAL_SETTING (retain the default compression setting of the data).

CONCEAL_DATA  Specify the constant PROPERTY_TRUE if you want the item to remain blank or otherwise obscured when the end user enters a value.  Specify the constant PROPERTY_FALSE if you want any value that is typed into the text item to be visible.

CURRENT_RECORD_ATTRIBUTE  Specifies the VARCHAR2 name of a named visual attribute to be associated with the given item.  If the named visual attribute does not exist, you will get an error message.

CURRENT_ROW_BACKGROUND_COLOR  The color of the object's background region.

CURRENT_ROW_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

CURRENT_ROW_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

CURRENT_ROW_FONT_SIZE  The size of the font, specified in points.

CURRENT_ROW_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

CURRENT_ROW_FONT_STYLE  The style of the font.

CURRENT_ROW_FONT_WEIGHT The weight of the font.

CURRENT_ROW_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

CURRENT_ROW_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

DIRECTION   Specifies the layout direction for bidirectional objects.  Valid values are DIRECTION_DEFAULT, RIGHT_TO_LEFT, LEFT_TO_RIGHT.

DISPLAYED Specifies whether the item will be displayed/enabled or hidden/disabled.

ECHO  Specifies whether characters an end user types into a text item should be visible.  When Echo is false, the characters typed are hidden.  Used for password protection.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

ENABLED  Specifies whether end users should be able to manipulate an item.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

Note:  Setting Enabled to false will cause other item property settings to change.  Consult the  "Propagation of Property Changes" section for details.

FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FIXED_LENGTH  Specifies whether the item's value should be validated against the setting of the item's Max Length property.  When FIXED_LENGTH is true, the item is valid only if the number of characters in its value equals the Max Length setting.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE  The size of the font, specified in hundredths of a point (i.e., for a font size of 8 points, the value should be set to 800).

FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE  The style of the font.

FONT_WEIGHT  The weight of the font.

FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

FORMAT_MASK  Specifies the display format and input accepted for data in text items.

HEIGHT  Specifies the height of the item.

HINT_TEXT Specifies the item-specific help text displayed on the message line at runtime. If the text specified is NULL, the original hint text, specified in Form Builder, will be restored.

ICON_NAME  Specifies the file name of the icon resource associated with a button item having the Iconic property set to YES.

IMAGE_DEPTH  Specifies the depth of color to be applied to an image item.

INSERT_ALLOWED  In a new record, allows end user to insert items normally when set to PROPERTY_TRUE.  Specify PROPERTY_FALSE to specify that the item does not accept modification, but is displayed normally (not grayed out).  (Insert_Allowed does not propagate changes to the Enabled property.)

ITEM_IS_VALID  Specifies whether the current item should be considered valid. Set to PROPERTY_TRUE or PROPERTY_FALSE.

ITEM_SIZE  Specifies a width and height for the item as two numbers separated by a comma.  Use the syntax that includes x, y.

KEEP_POSITION Specifies whether the Keep Cursor Position property should be true or false.  When Keep Cursor Position is true, the cursor returns to the same position it was in when it left the text item.  When Keep Cursor Position is false, the cursor returns to the default position in the text item.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

LABEL  Specifies the VARCHAR2 string that you want displayed as the label of the item.  This property is only valid for items that have labels, such as buttons.

LOCK_RECORD_ON_CHANGE  Specify the constant PROPERTY_TRUE if you want the record to be locked when this item is changed.  Specify the constant PROPERTY_FALSE if you do not want the record locked when this item is changed.  Use primarily when connecting to a non-ORACLE data source that does not have row-level locking.

LOV_NAME  Specify the VARCHAR2 name of an LOV to be associated with the given item.  If  the LOV name does not exist, you will get an error message.

MERGE_CURRENT_ROW_VA Merges the contents of the specified visual attribute with the current row’s visual attribute (rather than replacing it).

MERGE_TOOLTIP_ATTRIBUTE Merges the contents of the specified visual attribute with the tooltip’s current visual attribute (rather than replacing it).

MERGE_VISUAL_ATTRIBUTE  Merges the contents of the specified visual attribute with the object’s current visual attribute (rather than replacing it).

MOUSE_NAVIGATE  Specifies whether Form Builder should navigate and set focus to the item when the end user activates the item with the mouse. Specify the constant PROPERTY_TRUE if you want the end user to be able to navigate to the item using the mouse.  Specify the constant PROPERTY_FALSE if you want a mouse click to keep the input focus in the current item.

NAVIGABLE  Specify the constant PROPERTY_TRUE if you want the end user to be able to navigate to the item using default keyboard navigation.  Specify the constant PROPERTY_FALSE if you want to disable default keyboard navigation to the item.  (Keyboard Navigable does not propagate changes to the Enabled property.)

NEXT_NAVIGATION_ITEM  Specifies the name of the item that is defined as the "next navigation item" with respect to this current item.

POPUPMENU_CONTENT_ITEM  Specifies the setting for any of the OLE popup menu item properties:

•	POPUPMENU_COPY_ITEM

•	POPUPMENU_CUT_ITEM

•	POPUPMENU_DELOBJ_ITEM

•	POPUPMENU_INSOBJ_ITEM

•	POPUPMENU_LINKS_ITEM

•	POPUPMENU_OBJECT_ITEM

•	POPUPMENU_PASTE_ITEM

•	POPUPEMNU_PASTESPEC_ITEM

Specify the character string HIDDEN for the OLE popup menu item not to be displayed on the OLE popup menu.  Specify the character string ENABLED for the OLE popup menu item to be displayed and enabled.  Specify the character string DISABLED for the OLE popup menu item to be displayed and not enabled.

POSITION  Specify the x, y coordinates for the item as NUMBERs separated by a comma.  Use the syntax that includes x, y.

PREVIOUS_NAVIGATION_ITEM  Specifies the name of the item that is defined as the "previous navigation item" with respect to this current item.

PRIMARY_KEY  Specify the constant PROPERTY_TRUE to indicate that any record inserted or updated in the block must have a unique characteristic in order to be committed to the database.  Otherwise, specify the constant PROPERTY_FALSE.

PROMPT_ALIGNMENT_OFFSET  Determines the distance between the item and its prompt.

PROMPT_BACKGROUND_COLOR  The color of the object's background region.

PROMPT_DISPLAY_STYLE  Determines the prompt’s display style, either PROMPT_FIRST_RECORD, PROMPT_HIDDEN, or PROMPT_ALL_RECORDS.

PROMPT_EDGE  Determines which edge the item’s prompt is attached to, either START_EDGE, END_EDGE, TOP_EDGE, or BOTTOM_EDGE.

PROMPT_EDGE_ALIGNMENT  Determines which edge the item’s prompt is aligned to, either ALIGNMENT_START, ALIGNMENT_END, or ALIGNMENT_CENTER.

PROMPT_EDGE_OFFSET  Determines the distance between the item and its prompt as a VARCHAR2 value.

PROMPT_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

PROMPT_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

PROMPT_FONT_SIZE  The size of the font, specified in points.

PROMPT_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

PROMPT_FONT_STYLE  The style of the font.

PROMPT_FONT_WEIGHT  The weight of the font.

PROMPT_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

PROMPT_TEXT  Determines the text label that displays for an item.

PROMPT_TEXT_ALIGNMENT  Determines how the prompt is justified, either ALIGNMENT_START, ALIGNMENT_LEFT, ALIGNMENT_RIGHT, ALIGNMENT_CENTER, or ALIGNMENT_END.

PROMPT_VISUAL_ATTRIBUTE Specifies the named visual attribute that should be applied to the prompt at runtime.

PROMPT_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

QUERYABLE  Specify the constant PROPERTY_TRUE if you want the end user to be able to initiate a query against the item.  Specify the constant PROPERTY_FALSE if you want to disallow the use of the item in a query.

QUERY_ONLY   Specify an item to be queried, preventing that item from becoming part of insert or update statements.  QUERY_ONLY is applicable to text items, radio groups, and check boxes. Enclose the fully-qualified item name in single quotes.

REQUIRED  Specify the constant PROPERTY_TRUE if you want to force the end user to enter a value for the item.  Specify the constant PROPERTY_FALSE if the item is not to be required.

SHOW_FAST_FORWARD_BUTTON  Specify the constant PROPERTY_TRUE  to display [image] on a sound item, PROPERTY_FALSE to hide it.

SHOW_PLAY_BUTTON  Specify the constant PROPERTY_TRUE  to display [image] on a sound item, PROPERTY_FALSE to hide it.  Note that Form Builder will hide either [image] or [image], but not both.

SHOW_RECORD_BUTTON  Specify the constant PROPERTY_TRUE  to display [image] on a sound item, PROPERTY_FALSE to hide it.  Note that Form Builder will hide either [image] or [image], but not both.

SHOW_REWIND_BUTTON  Specify the constant PROPERTY_TRUE  to display [image] on a sound item, PROPERTY_FALSE to hide it.

SHOW_SLIDER  Specify the constant PROPERTY_TRUE  to display [image] on a sound item, PROPERTY_FALSE to hide it.

SHOW_TIME_INDICATOR  Specify the constant PROPERTY_TRUE  to display [image] button on a sound item, PROPERTY_FALSE to hide it.

SHOW_VOLUME_CONTROL  Specify the constant PROPERTY_TRUE  to display [image] on a sound item, PROPERTY_FALSE to hide it.

TOOLTIP_BACKGROUND_COLOR  The color of the object's background region.

TOOLTIP_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

TOOLTIP_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

TOOLTIP_FONT_SIZE  The size of the font, specified in points.

TOOLTIP_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

TOOLTIP_FONT_STYLE  The style of the font.

TOOLTIP_FONT_WEIGHT  The weight of the font.

TOOLTIP_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

TOOLTIP_TEXT Determines the item’s tooltip text.

TOOLTIP_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

UPDATE_ALLOWED  Specify the constant PROPERTY_TRUE if you want the end user to be able to update the item.  Specify the constant PROPERTY_FALSE if you want the item protected from update.

UPDATE_COLUMN  Specify the constant PROPERTY_TRUE if this column should be treated as updated, and included in the columns to be written to the database.  Specify the constant PROPERTY_FALSE if this column should be treated as not updated, and not be included in the columns to be written to the database.

UPDATE_NULL  Specify the constant PROPERTY_TRUE if you want the end user to be able to update the item only if its value is NULL.  Specify the constant PROPERTY_FALSE if you want the end user to be able to update the value of the item regardless of whether the value is NULL.

UPDATE_PERMISSION  Use UPDATE_ ALLOWED when you run against non-ORACLE data sources.  Specify the constant PROPERTY_TRUE to turn on the item's UPDATEABLE and UPDATE_NULL properties.  Specify the constant PROPERTY_FALSE to turn off the item's UPDATEABLE and UPDATE_NULL properties.

VALIDATE_FROM_LIST  Specifies that Form Builder should validate the value of the text item against the values in the attached LOV when set to PROPERTY_TRUE.  Specify PROPERTY_FALSE to specify that Form Builder should not use the LOV for validation.

VISIBLE  Specifies whether the indicated item should be visible or hidden.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

Note:  Setting Visible to false will cause other item property settings to change. Consult the "Propagation of Property Changes" section for details.

VISUAL_ATTRIBUTE  Specify a valid named visual attribute that exists in the current form.

Note:  You cannot set the visual attribute for an image item.

WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

WIDTH  Specify the width of the item as a NUMBER.  The size of the units depends on how you set the Coordinate System property and default font scaling for the form.

X_POS  Specify the x coordinate as a NUMBER.

Y_POS  Specify the y coordinate as a NUMBER.

value	Specify the value to be applied to the given property.  The data type of the property determines the data type of the value you enter.  For instance, if you want to set the VISIBLE property to true, you specify the constant PROPERTY_TRUE for the value.  If you want to change the LABEL for the item, you specify the value, in other words, the label, as a VARCHAR2 string.

PROPERTY_TRUE  Specifies that the property is to be set to the TRUE state.

PROPERTY_FALSE  Specifies that the property is to be set to the FALSE state.

If you want to reset the value of the property to be the value originally established for it at design time, enter two single quotes with no space between:  ‘’.  For example, SET_ITEM_PROPERTY(‘DEPTNO’, FORMAT_MASK, ‘’); would reset that format mask to its design-time value.

x	Specifies the NUMBER value of the x coordinate or the width, depending on the property you specified.  Specify the argument in form coordinate system units.

y	Specifies the NUMBER value of the y coordinate or the height, depending on the property you specified.  Specify the argument in form coordinate system units.

Usage Notes

The following issues can affect your decisions on how to apply certain property values to an item:

•	validation of property changes

•	propagation of property changes

Validation of Property Changes   When you specify a change through the SET_ITEM_PROPERTY built-in, Form Builder validates the change before it adjusts the property.  If the change is validated, Form Builder makes the change and leaves it in effect until another SET_ITEM_PROPERTY changes the same property or the current form is exited.

Illegal Settings  If the change is not validated, Form Builder issues an error message.  You cannot use SET_ITEM_PROPERTY to set the following item properties true or false, given the following target item conditions.

You cannot set this property parameter...	To this restricted setting	If this target item condition is true:
(All)	true/false	• NULL-canvas item (item's canvas property is null)
ENABLED	true/false true	• current item  • Visible item property is false
INSERT_ALLOWED	true true	• Enabled item property is false  • Visible item property is false
NAVIGABLE	true/false true	• current item • Visible item property is false
QUERYABLE (Query Allowed)	true	• Visible item property is false
UPDATE_ALLOWED	true true	• Enabled item property is false  • Conceal Data item property is true
UPDATE_NULL (Update if NULL)	true true	• Enabled item property is false • Conceal Data item property is true
VISIBLE	true/false	• current item
Form Builder does not consider the current contents of an item before allowing a property change.  If SET_ITEM_PROPERTY changes an item property that would affect how Form Builder validates the data in an item (for example, FIXED_LENGTH or REQUIRED), the validation consequences are not retroactive.  The new validation rules do not apply to the item until Form Builder next validates it under normal circumstances.

For example, suppose the application has a required text item, such as Employee ID.  In the application, the end user needs to be able to leave this item (behavior not allowed for a REQUIRED item), so you temporarily set the REQUIRED property to False.  At this point, Form Builder marks an existing NULL value as VALID.  Later in the application, when you set the REQUIRED property to true again, Form Builder does not automatically change the VALID/INVALID marking.  In order to have a NULL value marked as INVALID (expected for a REQUIRED item), you must make a change in the item that will cause Form Builder to validate it, such as:

IF :block.item IS NULL
THEN :block.item := NULL;

Propagation of Property Changes You can only specify a change to one item property at a time through the SET_ITEM_PROPERTY built-in.  However, one SET_ITEM_PROPERTY statement can cause changes to more than one item property if the additional changes are necessary to complete, or propagate, the intended change.  This is included primarily for compatibility with prior versions.

The following table shows the SET_ITEM_PROPERTY settings that cause Form Builder to propagate changes across item properties:

Setting this property parameter...	To this setting	Also causes these propagated changes:
ENABLED	False	• sets the Navigable item property to False • sets the Update_Null item property to False • sets the Updateable item property to False • sets the Required item property to False
DISPLAYED	False	• sets the Enabled and Navigable item properties to False • sets the Updateable item property to False • sets the Update_Null item property to False • sets the Required item property to False • sets the Queryable item property to False
UPDATEABLE	True	• sets the Update_Null item property to False
UPDATE_NULL	True	• sets the Updateable item property to False


SET_ITEM_PROPERTY examples

/*

** Built-in:  SET_ITEM_PROPERTY
** Example:   Change the icon of an iconic button dynamically
**            at runtime by changing its icon_name. The user
**            clicks on this button to go into enter query
**            mode, then clicks on it again (after the icon
**            changed) to execute the query. After the query
**            is executed the user sees the original icon
**            again.
** Trigger:   When-Button-Pressed
*/
DECLARE
  it_id Item;
BEGIN
  it_id := Find_Item('CONTROL.QUERY_BUTTON');
  IF :System.Mode = 'ENTER-QUERY' THEN
    /*
    ** Change the icon back to the enter query icon, and
    ** execute the query.
    */
    Set_Item_Property(it_id,ICON_NAME,'entquery');
    Execute_Query;
  ELSE
    /*
    ** Change the icon to the execute query icon and get
    ** into enter query mode.
    */
    Set_Item_Property(it_id,ICON_NAME,'exequery');
    Enter_Query;
  END IF;
END;


SET_LOV_COLUMN_PROPERTY built-in

 All Built-ins

Description

Sets the given LOV property for the given LOV.

Syntax

SET_LOV_COLUMN_PROPERTY
  (lov_id    LOV,
   colnum    NUMBER,
   property  NUMBER,
   value     VARCHAR2);

SET_LOV_COLUMN_PROPERTY
  (lov_name  VARCHAR2,
   colnum    NUMBER,
   property  NUMBER,
   value     VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

lov_id	Specifies the unique ID that Form Builder assigns the LOV when created.  Use the FIND_LOV built-in to return the ID to an appropriately typed variable.  The data type of the ID is LOV.

lov_name	Specifies the LOV name (as a VARCHAR2).

colnum	Specifies the column to be modified (as a NUMBER). The first column is column 1.

property	Specifies the property you want to set for the given LOV.  The possible properties are as follows:

TITLE  Sets the Column Title property that controls the title that displays above an LOV column.

Note:  Setting the column title to NULL resets the column title to the title specified at design time.

WIDTH  Specifies the width to be reserved in the LOV for displaying column values.

Note: Setting the column width to NULL results in a hidden, or non-displayed, column.

value	The VARCHAR2 or NUMBER value that represents the desired property setting.


SET_LOV_PROPERTY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Sets the given LOV property for the given LOV.

Syntax

SET_LOV_PROPERTY
  (lov_id    LOV,
   property  NUMBER,
   value     NUMBER);

SET_LOV_PROPERTY
  (lov_name  VARCHAR2,
   property  NUMBER,
   value     NUMBER);
SET_LOV_PROPERTY
  (lov_id    LOV,
   property  NUMBER,
   x         NUMBER,
   y         NUMBER);
SET_LOV_PROPERTY
  (lov_name  VARCHAR2,
   property  NUMBER,
   x         NUMBER,
   y         NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

lov_id	Specifies the unique ID that Form Builder assigns the LOV when created.  Use the FIND_LOV built-in to return the ID to an appropriately typed variable.  The data type of the ID is LOV.

lov_name	Specifies the LOV name (as a VARCHAR2).

property	Specifies the property you want to set for the given LOV.  The possible properties are as follows:

AUTO_REFRESH  Specifies whether Form Builder re-executes the query each time the LOV is invoked.

GROUP_NAME  Specifies the record group with which the LOV is associated.

LOV_SIZE  Specifies a width, height pair indicating the size of the LOV.

POSITION  Specifies an x, y pair indicating the position of the LOV.

TITLE  Specifies the title of the LOV. Overrides the value specified in the Form Builder unless the property value is NULL.

value	Specify one of the following constants:

PROPERTY_TRUE  Specifies that the property is to be set to the TRUE state.

PROPERTY_FALSE  Specifies that the property is to be set to the FALSE state.

Recordgroup Name  	Specify the VARCHAR2 name of the record group you are setting.  You can create this record group in Form Builder or programmatically, as long as the record group exists when the SET_LOV_PROPERTY is called.

x	Specify either the x coordinate or the width, depending on the property you specified.

y	Specify either the y coordinate or the height, depending on the property you specified.


SET_LOV_PROPERTY restrictions

•	You can set only one property per call to the built-in.


SET_LOV_PROPERTY examples

/*

** Built-in:  SET_LOV_PROPERTY
** Example:   if LOV is currently base on GROUP1,
**            make LOV use GROUP2
*/
DECLARE
  lov_id      LOV;
BEGIN
  lov_id     := Find_LOV('My_LOV_1');
  IF Get_LOV_Property(lov_id,GROUP_NAME) = 'GROUP1' THEN
    Set_LOV_Property(lov_id,GROUP_NAME,'GROUP2');
  ENDIF;
END;


SET_MENU_ITEM_PROPERTY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Modifies the given properties of a menu item.

Syntax

SET_MENU_ITEM_PROPERTY
  (menuitem_id  MenuItem,
   property     NUMBER,
   value        NUMBER);

SET_MENU_ITEM_PROPERTY
  (menu_name.menuitem_name  VARCHAR2,
   property                 NUMBER,
   value                    NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

menuitem_id	Specifies the unique ID Form Builder assigns when it creates the menu item.  Use the FIND_MENU_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is MenuItem.

menu_name.menuitem_name	Specifies the VARCHAR2 name you gave to the menu item when you defined it.  If you specify the menu item by name, include the qualifying menu name, as shown in the syntax.

property	Specify one of the following constants to set information about the menu item:

CHECKED  Specifies the Checked property, which indicates if a check box menu item or a radio menu item is in the checked state or unchecked state.

ENABLED  Specifies whether the menu item is enabled (thus active) or disabled (thus greyed out and unavailable to the operator).

ICON_NAME  Specifies the file name of the icon resource associated with a menu item having the Icon in Menu property set to TRUE.

LABEL  Specifies the character string for the menu item label.

VISIBLE  Specifies whether the menu item is visibly displayed.

value	Specify one of the following constants:

PROPERTY_TRUE  Specifies that the property is to be set to the TRUE state.

PROPERTY_FALSE  Specifies that the property is to be set to the FALSE state.

Label  	Specify the VARCHAR2 label name.


SET_MENU_ITEM_PROPERTY restrictions

These restrictions apply only if the menu module's Use Security property is set to Yes:

•	If the menu module Use Security property is Yes, whether you can set the property of a menu item using SET_MENU_ITEM_PROPERTY depends on whether the form operator has access privileges for that item.

•	If the menu item is hidden and the operator does not have security access to a menu item, Runform does not display that item.  You cannot set the property of a menu item using SET_MENU_ITEM_PROPERTY if the item is currently hidden.

•	If the menu item is displayed, but disabled and the Display w/o Priv property for this menu item was set in Form Builder, Runform displays the item in a disabled state.  In this case, you can set the menu item properties programmatically.


SET_MENU_ITEM_PROPERTY examples

/*

** Built-in:  SET_MENU_ITEM_PROPERTY
** Example:  See GET_MENU_ITEM_PROPERTY
*/


SET_OLE

 All Built-ins

Description

Changes the value of an OLE property.

There are three versions of the procedure, one for each of the new-value types:  NUMBER, VARCHAR, and OLEVAR.

Syntax

PROCEDURE SET_OLE
  (obj OLEOBJ, memberid PLS_INTEGER
   newval NUMBER, vtype VT_TYPE);

...or...

PROCEDURE SET_OLE
  (obj OLEOBJ, memberid PLS_INTEGER
   newval VARCHAR2, vtype VT_TYPE);

...or...

PROCEDURE SET_OLE
  (obj OLEOBJ, memberid PLS_INTEGER
   newval OLEVAR, vtype VT_TYPE);

Built-in Type  unrestricted procedure

Parameters

obj	A pointer to the OLE object.
memberid	The member ID of the OLE property.
newval	A new value of the specified type to replace the OLE property.
vtype	The VT_TYPE of the original variant.   This is an optional parameter. If not specified, the default value for the NUMBER version of the procedure is VT_R8.  For the VARCHAR2 version, the default is VT_BSTR.  For the OLEVAR version, the default is VT_VARIANT: that is, whatever type the variant itself actually specifies .
Usage Notes

If INIT_OLEARGS and ADD_OLEARG calls precede this SET_OLE call, and there have been no intervening GET_OLE, SET_OLE, or CALL_OLE calls, then this call will access the property by using the arguments specified in those INIT_OLEARGS and ADD_OLEARG calls.


SET_PARAMETER_ATTR built-in

  Related Topics	 All Built-ins

Description

Sets the type and value of an indicated parameter in an indicated parameter list.

Syntax

SET_PARAMETER_ATTR
  (list       PARAMLIST,
   key        VARCHAR2,
   paramtype  NUMBER,
   value      VARCHAR2);

SET_PARAMETER_ATTR
  (name       VARCHAR2,
   key        VARCHAR2,
   paramtype  NUMBER,
   value      VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

list or name	Specifies the parameter list.  The actual parameter can be either a parameter list ID of type PARAMLIST, or the VARCHAR2 name of the parameter list.

key	The VARCHAR2 name of the parameter.

paramtype	Specifies the type of parameter you intend to pass:

DATA_PARAMETER  Indicates that the parameter's value is the name of a record group.

TEXT_PARAMETER   Indicates that the parameter's value is an actual data value.

value	The value of the parameter specified as a VARCHAR2 string.


SET_RADIO_BUTTON_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Sets the given property for a radio button that is part of the given radio group specified by the item_name or item_id.

Syntax

SET_RADIO_BUTTON_PROPERTY
  (item_id      VARCHAR2,
   button_name  VARCHAR2,
   property     NUMBER,
   value        NUMBER);

SET_RADIO_BUTTON_PROPERTY
  (item_id      VARCHAR2,
   button_name  VARCHAR2,
   property     NUMBER,
   x            NUMBER,
   y            NUMBER);
SET_RADIO_BUTTON_PROPERTY
  (item_name    VARCHAR2,
   button_name  VARCHAR2,
   property     NUMBER,
   x            NUMBER,
   y            NUMBER);
SET_RADIO_BUTTON_PROPERTY
  (item_name    VARCHAR2,
   button_name  VARCHAR2,
   property     NUMBER,
   value        NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

item_id	Specifies the radio group item ID.  Form Builder assigns the unique ID at the time it creates the object.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.

item_name	Specifies the name of the radio group.  The radio group is the owner or parent of its subordinate radio buttons.  The data type of the name is VARCHAR2.

button_name	Specifies the name of the radio button whose property you want to set.  The data type of the name is VARCHAR2.

property	Specifies the property you want to set.  The possible property constants you can set are as follows:

BACKGROUND_COLOR  The color of the object's background region.

ENABLED  Specify PROPERTY_TRUE constant if you want to enable the radio button.  Specify PROPERTY_FALSE if you want to disable the radio button from operator control.

FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE  The size of the font, specified in points.

FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE  The style of the font.

FONT_WEIGHT  The weight of the font.

FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

HEIGHT  Specify the height of the given radio button.  Specify the value as a number.

ITEM_SIZE  Sets the width and height of the given radio button.  Use the syntax that shows an x,y coordinate pair and specify the values as numbers.

LABEL  Specify the actual string label for that radio button.

POSITION  Sets the position of the given radio button.  Use the syntax that shows an x,y coordinate pair and specify the values as numbers.

PROMPT  The text displayed in the object.

PROMPT_BACKGROUND_COLOR  The color of the object's background region.

PROMPT_FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

PROMPT_FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

PROMPT_FONT_SIZE  The size of the font, specified in points.

PROMPT_FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

PROMPT_FONT_STYLE  The style of the font.

PROMPT_FONT_WEIGHT  The weight of the font.

PROMPT_FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

PROMPT_WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

VISIBLE  Specify PROPERTY_TRUE constant if you want the radio button to be displayed.  Specify PROPERTY_FALSE constant if you want the radio button to be hidden.

VISUAL_ATTRIBUTE  Specifies either a valid named visual attribute that exists in the current form, or the name of a logical attribute definition in a runtime resource file that you want Form Builder to apply to the radio button.

WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

WIDTH  Specify the width of the given radio button.  Specify the value as a number.

X_POS  Specify the x-coordinate for the radio button.  Specify the value as a number.

Y_POS  Specify the y-coordinate for the radio button.  Specify the value as a number.

value	Specifies a NUMBER or a VARCHAR2 value.  The data type of the value you enter is determined by the data type of the property you specified.  If you enter a VARCHAR2 value, you must enclose it in quotes, unless you reference a text item or variable.

PROPERTY_TRUE  Specifies that the property is to be set to the TRUE state.

PROPERTY_FALSE  Specifies that the property is to be set to the FALSE state.

x	Specifies the first numeric value for the ITEM_SIZE and POSITION properties.

y	Specifies the second numeric value for the ITEM_SIZE and POSITION properties.


SET_RADIO_BUTTON_PROPERTY examples

/*

** Built-in:  SET_RADIO_BUTTON_PROPERTY
** Example:   Set a particular radio button to disabled.
*/
BEGIN
  Set_Radio_Button_Property('MYBLOCK.FLIGHT_STATUS',
                         'GROUNDED',ENABLED,PROPERTY_FALSE);
END;


SET_RECORD_PROPERTY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Sets the specified record property to the specified value.

Syntax

SET_RECORD_PROPERTY
  (record_number  NUMBER,
   block_name     VARCHAR2,
   property       NUMBER,
   value          NUMBER);

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

record_number	Specifies the number of the record whose status you want to set.  The record number is the record's position in the block.  Specify as a whole number.

block_name	Specifies the name of the block in which the target record exists.  The data type of the name is VARCHAR2.

property	Use the following property:

STATUS  Specifies that you intend to change the record status.  STATUS is a constant.

value	Use one of the following values:

CHANGED_STATUS  Specifies that the record should be marked for update and should be treated as an update when the next commit action occurs.

INSERT_STATUS  Specifies that the record is to be marked as an INSERT and should be inserted into the appropriate table when the next commit action occurs.

NEW_STATUS  Specifies that the record is to be treated as a NEW record, that is, a record that has not been marked for insert, update, or query.  Changed but uncleared or uncommitted records cannot be assigned a status of NEW.

QUERY_STATUS  Specifies that the record is to be treated as a QUERY record, whether it actually is.  See also the CREATE_QUERIED_RECORD built-in.


SET_RECORD_PROPERTY restrictions

The following table illustrates the valid transition states of a record.

Current  Status	Target   Status
	NEW	QUERY	INSERT	CHANGED
NEW	yes	yes1	yes2	no
QUERY	yes4	yes	no	yes
INSERT	yes4	yes3	yes	no
CHANGED	yes4	no	no	yes
1	Adheres to the rules described in footnotes 2 and 3.

2	This transition is not allowed in query mode, because QUERY and INSERT are not valid in query mode.

3	If this transition is performed while Runform is running in Unique Key mode and not all of the transactional triggers exist, then you must enter a valid value in the ROWID field.  Put another way, if you are connected to a non-ORACLE data source that does not support ROWID, but you are using a unique key, you must supply the key for a record that goes from Insert to Query, in one of the transactional triggers, either On-Lock, On-Update, or On-Delete.  Otherwise Form Builder returns an error.

4	Records that have been changed but not yet committed or cleared cannot be assigned a status of NEW.


SET_RECORD_PROPERTY examples

/*

** Built-in:  SET_RECORD_PROPERTY
** Example:   Mark the third record in the EMP block as if it
**            were a queried record.
*/
BEGIN
  Set_Record_Property( 3, 'EMP', STATUS, QUERY_STATUS);
END;


SET_RELATION_PROPERTY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Sets the given relation property in a master-detail relationship.

Syntax

SET_RELATION_PROPERTY
  (relation_id  Relation,
   property     NUMBER,
   value        NUMBER);

SET_RELATION_PROPERTY
  (relation_name  VARCHAR2,
   property       NUMBER,
   value          NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

relation_id	Specifies the unique ID that Form Builder assigns the relation when it creates the relation object.  This can occur automatically when you define a master-detail relationship in the Form Builder, or you can explicitly create the relation.  The data type of the ID is Relation.

relation_name	Specifies the name you or Form Builder gave the relation object when defining it.  The data type of the name is VARCHAR2.

property	Use one of the following relation properties, which can be passed to the built-in as a constant:

AUTOQUERY   Specifies that the detail block of this relation is to be automatically coordinated upon instantiation of the block.  This allows potentially expensive processing to be deferred until blocks that are involved in relations are actually visited.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

DEFERRED_COORDINATION  Specifies that a  block requiring coordination is to be marked but not coordinated until the detail blocks are instantiated.  Deferred coordination refers only to the population phase of coordination.  Even deferred detail blocks are cleared during the clear phase of coordination to present the form in a visually consistent state.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

MASTER_DELETES  Specifies the default relation behavior for deletion of a detail record in the detail block when there is a corresponding master record in the master block.  Valid values are NON-ISOLATED, ISOLATED, or CASCADING.  The ability to set this property programmatically is included only for designers who are coding their own master-detail coordination.  It does not alter a default relation that was created at design time.

PREVENT_MASTERLESS_OPERATION  Specifies that operations in a detail block are not allowed when no corresponding master record exists.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

value	The following constants can be supplied for the properties described earlier:

CASCADING  Specifies that the MASTER_DELETES property is to be set so that when an operator deletes a master record, its corresponding detail records are locked at the same time as the master records are locked.

ISOLATED  Specifies that the MASTER_DELETES property is to be set so that an operator can delete a master record for which detail records exist.  This does not cause subsequent locking and deletion of detail records, however, Form Builder still initiates detail block coordination in this case.

NON_ISOLATED  Specifies that the  MASTER_DELETES property is to be set so that if the operator attempts to delete a master record for which detail records exist, Form Builder issues an error message and disallows the deletion.

PROPERTY_TRUE  Specifies that the property is to be set to the TRUE state.

PROPERTY_FALSE  Specifies that the property is to be set to the FALSE state.


SET_RELATION_PROPERTY restrictions

You can only set one property per call to this built-in.


SET_RELATION_PROPERTY examples

/*

** Built-in:  SET_RELATION_PROPERTY
** Example:   Set the coordination behavior of a relation to
**            be deferred, and auto-query.
*/
PROCEDURE Make_Relation_Deferred( rl_name VARCHAR2 ) IS
  rl_id Relation;
BEGIN
  /*
  ** Look for the relation's ID
  */
  rl_id := Find_Relation( rl_name );
  /*
  ** Set the two required properties
  */
  Set_Relation_Property(rl_id,AUTOQUERY,PROPERTY_TRUE);
END;


SET_REPORT_OBJECT_PROPERTY built-in

 Examples	 All Built-ins

Description

Programmatically sets the value of a report property.

Syntax

PROCEDURE SET_REPORT_OBJECT_PROPERTY
(report_id REPORT_OBJECT,
   property NUMBER,
   value VARCHAR2
);

PROCEDURE SET_REPORT_OBJECT_PROPERTY
  (report_name VARCHAR2,
   property NUMBER,
   value VARCHAR2
);

PROCEDURE SET_REPORT_OBJECT_PROPERTY
(report_id REPORT_OBJECT,
   property NUMBER,
   value NUMBER
);

PROCEDURE SET_REPORT_OBJECT_PROPERTY
  (report_name VARCHAR2,
   property NUMBER,
   value NUMBER
);

Built-in Type  unrestricted procedure

Enter Query Mode yes

Parameters

report_id	Specifies the unique ID of the report. You can get the report ID for a particular report using FIND_REPORT_OBJECT .

report_name	Specifies the unique name of the report.

property	One of the following constants:

REPORT_EXECUTION_MODE: The report execution mode, either BATCH or RUNTIME

REPORT_COMM_MODE: The report communication mode, either SYNCHRONOUS or ASYNCHRONOUS

REPORT_DESTYPE: The report destination type, either PREVIEW, FILE, PRINTER, MAIL, CACHE or SCREEN

One of the following strings:

REPORT_FILENAME: The report filename

REPORT_SOURCE_BLOCK: The report source block name

REPORT_QUERY_NAME: The report query name

REPORT_DESNAME: The report destination name

REPORT_DESFORMAT: The report destination format

REPORT_SERVER: The report server name

REPORT_OTHER: The other user-specified report properties

value 	One of the following constants:

REPORT_EXECUTION_MODE: Value must be BATCH or RUNTIME

REPORT_COMM_MODE: Value must be SYNCHRONOUS or ASYNCHRONOUS

REPORT_DESTYPE: Value must be PREVIEW, FILE, PRINTER, MAIL, CACHE, or SCREEN

One of the following strings:

REPORT_FILENAME: Value must be of type VARCHAR2

REPORT_SOURCE_BLOCK: Value must be of type VARCHAR2

REPORT_QUERY_NAME: Value must be of type VARCHAR2

REPORT_DEST_NAME: Value must be of type VARCHAR2

REPORT_DEST_FORMAT: Value must be of type VARCHAR2

REPORT_SERVER: Value must be of type VARCHAR2

REPORT_OTHER: Value must be of type VARCHAR2

Usage Notes

•	SET_REPORT_OBJECT_PROPERTY sets properties using constant or string values. The value type depends on the particular property being set, as specified above. In contrast, GET_REPORT_OBJECT_PROPERTY returns a string value for all properties.


SET_REPORT_OBJECT_PROPERTY examples

DECLARE

repid REPORT_OBJECT;

report_prop VARCHAR2(20);

BEGIN

repid := find_report_object('report4');

SET_REPORT_OBJECT_PROPERTY(repid, REPORT_EXECUTION_MODE, BATCH);

SET_REPORT_OBJECT_PROPERTY(repid, REPORT_COMM_MODE, SYNCHRONOUS);

SET_REPORT_OBJECT_PROPERTY(repid, REPORT_DESTYPE, FILE);

END;


SET_TAB_PAGE_PROPERTY built-in

 Examples	     Related Topics	 All Built-ins

Description

Sets the tab page properties of the specified tab canvas page.

Syntax

SET_TAB_PAGE_PROPERTY
  (tab_page_id  TAB_PAGE,
   property     NUMBER,
   value        NUMBER);

SET_TAB_PAGE_PROPERTY
  (tab_page_name  VARCHAR2,
   property       NUMBER,
   value          NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

tab_page_id	The unique ID Form Builder assigns to the tab page when it creates it.  Datatype is TAB_PAGE.

tab_page_name	The name you gave the tab page when you defined it.  Datatype is VARCHAR2.

property	The property you want to set for the given tab page.  Possible values are:

BACKGROUND_COLOR  The color of the object's background region.

ENABLED  Specify TRUE to enable the tab page, FALSE to disable it (i.e., make it greyed out and unavailable).

FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE  The size of the font, specified in points.

FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE  The style of the font.

FONT_WEIGHT  The weight of the font.

FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

LABEL   The character string for the tab page label.

VISIBLE  Specify TRUE to make the tab page visible, FALSE to make it not visible.  A tab page is reported visible if it is currently mapped to the screen, even if it is entirely hidden behind another tab page.

VISUAL_ATTRIBUTE  Specifies the name of the visual attribute currently in force.

WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

value	You can pass the following constants as arguments to the property values described earlier:

PROPERTY_TRUE  (sets the property to the TRUE state)

PROPERTY_FALSE  (sets the property to the FALSE state)


SET_TAB_PAGE_PROPERTY examples

/* Example 1: Use SET_TAB_PAGE_PROPERTY to set the
** ENABLED property to TRUE for a tab page (if it currently
** is set to FALSE:
*/

DECLARE
  tb_pg_id  TAB_PAGE;

BEGIN
  tb_pg_id := FIND_TAB_PAGE('tab_page_1');
  IF GET_TAB_PAGE_PROPERTY(tb_pg_id, enabled) = 'FALSE' THEN
     SET_TAB_PAGE_PROPERTY(tb_pg_id, enabled, property_true);
  END IF;
END;


SET_TIMER built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Changes the settings for an existing timer.  You can modify the interval, the repeat parameter, or both.

Syntax

SET_TIMER
  (timer_id      Timer,
   milliseconds  NUMBER,
   iterate       NUMBER);

SET_TIMER
  (timer_name    VARCHAR2,
   milliseconds  NUMBER,
   iterate       NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

timer_id	Specifies the unique ID that Form Builder assigns when it creates the timer, specifically as a response to a successful call to the CREATE_TIMER built-in.  Use the FIND_TIMER built-in to return the ID to an appropriately typed variable.  The data type of the ID is Timer.

timer_name	Specifies the name you gave the timer when you defined it.  The data type of the name is VARCHAR2.

milliseconds	Specifies the duration of the timer in milliseconds.   The range of values allowed for this parameter is 1 to 2147483648 milliseconds. Values > 2147483648 will be rounded down to 2147483648.  Note that only positive numbers are allowed.  The data type of the parameter is NUMBER.  See Restrictions below for more information.

NO_CHANGE  Specifies that the milliseconds property is to remain at its current setting.

iterate	Specifies the iteration of the timer.

REPEAT  Indicates that the timer should repeat upon expiration.  Default.

NO_REPEAT  Indicates that the timer should not repeat upon expiration, but is to be used once only, until explicitly called again.

NO_CHANGE  Specifies that the iterate property is to remain at its current setting.


SET_TIMER restrictions

•	Values > 2147483648 will be rounded down to 2147483648.

•	A value less than 1 results in a runtime error.

•	A value greater than the stated upper bound results in an integer overflow.

•	Milliseconds cannot be expressed as a negative number.

•	No two timers can share the same name in the same form instance, regardless of case.

•	If there is no When-Timer-Expired trigger defined at the execution of a timer, Form Builder returns an error.

•	If there is no When-Timer-Expired trigger defined at the execution of a timer, and the timer is a repeating timer, subsequent repetitions are canceled, but the timer is retained.


SET_TIMER examples

/*

** Built-in:  SET_TIMER
** Example:   See FIND_TIMER
*/


SET_TREE_NODE_PROPERTY built-in

 Examples 	 All Built-ins

Description

Sets the state of a branch node.

Syntax

PROCEDURE SET_TREE_NODE_PROPERTY

  (item_name VARCHAR2,

   node FTREE.NODE,

   property NUMBER,

   value NUMBER);

PROCEDURE SET_TREE_NODE_PROPERTY

  (item_name VARCHAR2,

   node FTREE.NODE,

   property NUMBER,

   value VARCHAR2);

PROCEDURE SET_TREE_NODE_PROPERTY

  (item_id ITEM,

   node FTREE.NODE,

   property NUMBER,

   value NUMBER);

PROCEDURE SET_TREE_NODE_PROPERTY

  (item_id ITEM,

   node FTREE.NODE,

   property NUMBER,

   value VARCHAR2);

Built-in Type   unrestricted procedure

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
node	Specifies a valid node.
property	Specify one of the following properties: NODE_STATE   Possible values are EXPANDED_NODE, COLLAPSED_NODE, and LEAF_NODE. NODE_LABEL   Sets the label of the node. NODE_ICON   Sets the icon of the node. NODE_VALUE   Sets the value of the node.
value	The actual value you intend to pass.


SET_TREE_NODE_PROPERTY examples

/*

** Built-in:  SET_TREE_NODE_PROPERTY
*/

-- This code could be used in a WHEN-TREE-NODE-SELECTED

-- trigger to change the icon of the node clicked on.

DECLARE

   htree         ITEM;

   current_node  FTREE.NODE;

   find_node     FTREE.NODE;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Change it icon of the clicked node.

   -- The icon file will be located using the

   -- UI60_ICON environment variable in client/server

   -- or in the virtual directory for web deployment.

   Ftree.Set_Tree_Node_Property(htree, :SYSTEM.TRIGGER_NODE, Ftree.NODE_ICON, 'Open');

END;


SET_TREE_PROPERTY built-in

 Examples 	 All Built-ins

Description

Sets the value of the indicated hierarchical tree property.

Syntax

PROCEDURE SET_TREE_PROPERTY

  (item_name VARCHAR2,

   property NUMBER,

   value NUMBER);

PROCEDURE SET_TREE_PROPERTY

  (item_name VARCHAR2,

   property NUMBER,

   value VARCHAR2);

PROCEDURE SET_TREE_PROPERTY

  (item_name VARCHAR2,

   property NUMBER,

   value RECORDGROUP);

PROCEDURE SET_TREE_PROPERTY

  (item_id ITEM,

   property NUMBER,

   value NUMBER);

PROCEDURE SET_TREE_PROPERTY

  (item_id ITEM,

   property NUMBER,

   value VARCHAR2);

PROCEDURE SET_TREE_PROPERTY

  (item_id ITEM,

   property NUMBER,

   value RECORDGROUP);

Built-in Type   unrestricted procedure

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
property	Specify one of the following properties: RECORD_GROUP   Replaces the data set of the hierarchical tree with a record group and causes it to display. QUERY_TEXT   Replaces the data set of the hierarchical tree with an SQL query and causes it to display. ALLOW_EMPTY_BRANCHES   Possible values are PROPERTY_TRUE and PROPERTY_FALSE.
value	Specify the value appropriate to the property you are setting:  PROPERTY_TRUE  The property is to be set to the TRUE state. PROPERTY_FALSE  The property is to be set to the FALSE state.


SET_TREE_PROPERTY examples

/*

** Built-in:  SET_TREE_PROPERTY
*/

-- This code could be used in a WHEN-NEW-FORM-INSTANCE

-- trigger to initially populate the hierarchical tree

-- with data.

DECLARE

   htree         ITEM;

   v_ignore      NUMBER;

   rg_emps       RECORDGROUP;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Check for the existence of the record group.

   rg_emps := Find_Group('emps');

   IF NOT Id_Null(rg_emps) THEN

      DELETE_GROUP(rg_emps);

   END IF;

   -- Create the record group.

   rg_emps := Create_Group_From_Query('rg_emps',

             'select 1, level, ename, NULL, to_char(empno) ' ||

             'from emp '                                     ||

             'connect by prior empno = mgr '                 ||

             'start with job = ''PRESIDENT''');

   -- Populate the record group with data.

   v_ignore := Populate_Group(rg_emps);

   -- Transfer the data from the record group to the hierarchical

   -- tree and cause it to display.

   Ftree.Set_Tree_Property(htree, Ftree.RECORD_GROUP, rg_emps);

END;


SET_TREE_SELECTION built-in

 Examples 	 All Built-ins

Description

Specifies the selection of a single node.

Syntax

PROCEDURE SET_TREE_SELECTION

  (item_name VARCHAR2,

   node NODE,

   selection_type NUMBER);

PROCEDURE SET_TREE_SELECTION

  (item_id ITEM,

   node NODE,

   selection_type NUMBER);

Built-in Type   unrestricted procedure

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
node	Specifies a valid node.
selection_type	Specifies the type of selection. SELECT_ON   Selects the node. SELECT_OFF   Deselects the node. SELECT_TOGGLE   Toggles the selection state of the node.


SET_TREE_SELECTION examples

/*

** Built-in:  SET_TREE_SELECTION
*/

-- This code could be used in a WHEN-TREE-NODE-EXPANDED

-- trigger and will mark the clicked node as selected.

DECLARE

   htree         ITEM;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Mark the clicked node as selected.

   Ftree.Set_Tree_Selection(htree, :SYSTEM.TRIGGER_NODE, Ftree.SELECT_ON);

END;


SET_VA_PROPERTY built-in

 All Built-ins

Description

Modifies visual attribute property values for the specified property.

Syntax

SET_VA_PROPERTY

  (va_id VISUALATTRIBUTE

   property NUMBER

   value VARCHAR2);

SET_VA_PROPERTY

  (va_name VARCHAR2

   property NUMBER

   value VARCHAR2);

SET_VA_PROPERTY

  (va_id VISUALATTRIBUTE

   property NUMBER

   value NUMBER);

SET_VA_PROPERTY

  (va_name VARCHAR2

   property NUMBER

   value NUMBER);

Built-in Type   unrestricted function

Enter Query Mode  yes

Parameters

va_id	The unique ID Form Builder assinged to the visual attribute when you created it. The data type is VISUALATTRIBUTE.
va_name	The name you gave the visual attribute when you created it. The data type is VARCHAR2.
Property value	Specify one of the following properties: BACKGROUND_COLOR The color of the object's background region.  FILL_PATTERN The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.  FONT_NAME The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.  FONT_SIZE The size of the font, specified in hundreds of points. FONT_SPACING The width of the font, that is, the amount of space between characters (kerning).  FONT_STYLE The style of the font.  FONT_WEIGHT The weight of the font.  FOREGROUND_COLOR The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.  WHITE_ON_BLACK Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.  Specify the value to be applied to the given property. The data type of the property determines the data type of the value you enter.  For instance, if you want to set the WHITE_ON_BLACK property to true, specify the constant PROPERTY_TRUE for the value. If you want to change the FONT_NAME for the item, specify the value, in other words, the label, as a VARCHAR2 string.  PROPERTY_TRUE Specifies that the property is to be set to the TRUE state.  PROPERTY_FALSE Specifies that the property is to be set to the FALSE state.  If you want to reset the value of the property to be the value originally established for it at design time, enter two single quotes with no space between: ''. For example, SET_ITEM_PROPERTY('DEPTNO', FONT_SIZE, ''); would reset that format size to its design-time value.


SET_VAR

 All Built-ins

Description

Sets a newly-created OLE variant to its initial value.  Or, resets an existing OLE variant to a new value.

There are four versions of the procedure, one for each of the new value types CHAR, NUMBER, OLEVAR, and table.

Syntax

PROCEDURE SET_VAR
  (var OLEVAR, newval CHAR
   vtype VT_TYPE, arrspec VARCHAR2);

...or...

PROCEDURE SET_VAR
  (var OLEVAR, newval NUMBER
   vtype VT_TYPE, arrspec VARCHAR2);

...or...

PROCEDURE SET_VAR
  (var OLEVAR, newval OLEVAR
   vtype VT_TYPE, arrspec VARCHAR2);

...or...

PROCEDURE SET_VAR
  (var OLEVAR, source_table,
   vtype VT_TYPE, arrspec VARCHAR2);

Built-in Type  unrestricted procedure

Parameters

var	The variant to be set.
newval	The value to be given to the variant.
vtype	The OLE VT_TYPE to be given to the variant.  This is an optional parameter. If not specified, the default value for the NUMBER version of the procedure is VT_R8.  For the VARCHAR2 version, the default is VT_BSTR.  For the OLEVAR version, the default is VT_VARIANT: that is, whatever type the variant value actually specifies .
source_table	A PL/SQL table whose dimensions and element values are to be given to the variant.
arrspec	Indicates which selected element or elements of the source table are to be used in the creation of the new variant.  For more information, see Specifiers for OLE Arrays This is an optional parameter.  If not specified, the entire source table  is used..
Usage Notes

The target variant in this SET_VAR procedure must first be created with the CREATE_VAR function.


SET_VIEW_PROPERTY built-in

  Related Topics	 All Built-ins

Description

Sets a property for the indicated canvas. You can set only one property per call to the built-in. In other words, you cannot split the argument in such a way that the x coordinate applies to X_POS and the y coordinate applies to the HEIGHT.

Syntax

SET_VIEW_PROPERTY
  (view_id   ViewPort,
   property  NUMBER,
   value     NUMBER);

SET_VIEW_PROPERTY
  (view_id   ViewPort,
   property  NUMBER,
   x         NUMBER,
   y         NUMBER);
SET_VIEW_PROPERTY
  (view_name  VARCHAR2,
   property   NUMBER,
   value      NUMBER);
SET_VIEW_PROPERTY
  (view_name  ViewPort,
   property   NUMBER,
   x          NUMBER,
   y          NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

view_id	The unique ID Form Builder assigned the view when you created the canvas/view.  Use the FIND_VIEW built-in to return the ID to an appropriately typed variable.  Datatype is VIEWPORT.

view_name	The name you gave the canvas object when you defined it.  Datatype is VARCHAR2.

property	Specifies one of the following properties:

DIRECTION  The layout direction for bidirectional objects.  Valid values are DIRECTION_DEFAULT, RIGHT_TO_LEFT, LEFT_TO_RIGHT.

DISPLAY_POSITION  For a stacked view, the position of the view's upper-left corner relative to the window's content view, as an X, Y pair.  Determines where the view is displayed in the window.

HEIGHT  For a stacked canvas, the height of the view.  To change the size of the canvas itself, use SET_CANVAS_PROPERTY.

POSITION_ON_CANVAS  An X, Y pair indicating the location of the view's upper-left corner relative to its canvas.

VIEWPORT_X_POS  For a stacked view, the X coordinate for the view's upper-left corner relative to the window's content view.

VIEWPORT_Y_POS  For a stacked view, the Y coordinate for the view's upper-left corner relative to the window's content view.

VIEWPORT_X_POS_ON_CANVAS  The X coordinate for the view's upper-left corner relative to its canvas.

VIEWPORT_Y_POS_ON_CANVAS  The Y coordinate for the the view's upper-left corner relative to its canvas.

VIEW_SIZE  For a stacked canvas, the size of the view, as a width, height pair.  To change the size of the canvas itself, use SET_CANVAS_PROPERTY.

VISIBLE  Whether the view is to be displayed.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

WIDTH  For a stacked canvas, the width of the view.  To change the size of the canvas itself, use SET_CANVAS_PROPERTY.

value	Specify the value appropriate to the property you are setting:

PROPERTY_TRUE  The property is to be set to the TRUE state.

PROPERTY_FALSE  The property is to be set to the FALSE state.

x	The NUMBER value of the X coordinate or the width, depending on the property you specified.  Specify the argument in form coordinate system units.

y	The NUMBER value of the Y coordinate or the height, depending on the property you specified.  Specify the argument in form coordinate system units.


SET_WINDOW_PROPERTY built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Sets a property for the indicated window.

Syntax

SET_WINDOW_PROPERTY
  (window_id  Window,
   property   NUMBER,
   value      VARCHAR2);

SET_WINDOW_PROPERTY
  (window_id  Window,
   property   NUMBER,
   x          NUMBER);
SET_WINDOW_PROPERTY
  (window_id  Window,
   property   NUMBER,
   x          NUMBER,
   y          NUMBER);
SET_WINDOW_PROPERTY
  (window_name  VARCHAR2,
   property     NUMBER,
   value        VARCHAR2);
SET_WINDOW_PROPERTY
  (window_name  VARCHAR2,
   property     NUMBER,
   x            NUMBER);
SET_WINDOW_PROPERTY
  (window_name  VARCHAR2,
   property     NUMBER,
   x            NUMBER,
   y            NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

window_id	Specifies the unique ID that Form Builder assigns the window when created.  Use the FIND_WINDOW built-in to return the ID to an appropriately typed variable.  The data type of the ID is Window.

window_name	Specifies the name that you gave the window  when creating it.  The data type of the name is VARCHAR2.

property	Specify one of the following window properties:

BACKGROUND_COLOR  The color of the object's background region.

DIRECTION   Specifies the layout direction for bidirectional objects.  Valid values are DIRECTION_DEFAULT, RIGHT_TO_LEFT, LEFT_TO_RIGHT.

FILL_PATTERN  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FONT_NAME  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE  The size of the font, specified in points.

FONT_SPACING  The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE  The style of the font.

FONT_WEIGHT  The weight of the font.

FOREGROUND_COLOR  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

HEIGHT  Specifies the height of the window.

HIDE_ON_EXIT  Specifies whether Form Builder hides the current window automatically when the operator navigates to an item in another window.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

ICON_NAME  Specifies the file name of the icon resource associated with a window item when the window is minimized.

POSITION  Specifies an x, y pair indicating the location for the window on the screen.

TITLE  Sets the title of the window.

VISIBLE  Specifies whether the window is to be displayed.  Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

WHITE_ON_BLACK  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

WINDOW_SIZE  Specifies a width, height pair indicating the size of the window on the screen.

WINDOW_STATE  Specifies the current display state of the window.  Valid values are NORMAL, MAXIMIZE, or MINIMIZE.

WIDTH  Specifies the width of the window.

X_POS  Sets the x coordinate for the window's upper left corner on the screen.

Y_POS  Sets the y coordinate for the window's upper left corner on the screen.

value	The following constants can be passed as arguments to the property values described earlier:

PROPERTY_TRUE  Specifies that the property is to be set to the TRUE state.  This applies specifically to the VISIBLE property.

PROPERTY_FALSE  Specifies that the property is to be set to the FALSE state.   This applies specifically to the VISIBLE property.

The following constants can be passed as arguments for use with the WINDOW_STATE property:

NORMAL  Specifies that the window is displayed normally according to the current Width, Height, X Position, and Y Position property settings.

MAXIMIZE  Specifies that the window is enlarged to fill the screen according to the display style of the window manager.

MINIMIZE  Specifies that the window is minimized, or iconified.

x	Specifies the NUMBER value of the x coordinate or the width, depending on the property you specified.  Specify the argument in form coordinate system units.

y	Specifies the NUMBER value of the y coordinate or the height, depending on the property you specified.  Specify the argument in form coordinate system units.

Usage Notes

On Microsoft Windows, forms run inside the MDI application window.  You can use SET_WINDOW_PROPERTY to set the following properties of the MDI application window:

•	TITLE

•	POSITION

•	WIDTH, HEIGHT

•	WINDOW_SIZE

•	WINDOW_STATE

•	X_POS, Y_POS

To reference the MDI application window in a call to SET_WINDOW_PROPERTY, use the constant FORMS_MDI_WINDOW:

Set_Window_Property(FORMS_MDI_WINDOW, POSITION, 5,10)
Set_Window_Property(FORMS_MDI_WINDOW, WINDOW_STATE, MINIMIZE)


SET_WINDOW_PROPERTY restrictions

•	If you change the size or position of a window, the change remains in effect for as long as the form is running, or until you explicitly change the window's size or position again.  Closing the window and reopening it does not reset the window to its design-time defaults.  You must assign the design-time defaults to variables if you intend to set the window back to those defaults.


SET_WINDOW_PROPERTY examples

/*

** Built-in:  SET_WINDOW_PROPERTY
** Example:   See FIND_WINDOW
*/


SHOW_ALERT built-in

 Examples	     Related Topics	 All Built-ins

Description

Displays the given alert, and returns a numeric value when the operator selects one of three alert buttons.

Syntax

SHOW_ALERT
  (alert_id  Alert);

SHOW_ALERT
  (alert_name  VARCHAR2);

Built-in Type  unrestricted function

Returns  A numeric constant corresponding to the button the operator selected from the alert. Button mappings are specified in the alert design.

If the operator selects...	Form Builder returns
Button 1	ALERT_BUTTON1
Button 2	ALERT_BUTTON2
Button 3	ALERT_BUTTON3

Enter Query Mode  yes

Parameters

alert_id	The unique ID that Form Builder assigns the alert when the alert is created. Use the FIND_ALERT built-in to return the ID to an appropriately typed variable. The data type of the ID is Alert.

alert_name	The name you gave the alert when you defined it.  The data type of the name is VARCHAR2.


SHOW_ALERT examples

/*

** Built-in:  SHOW_ALERT
** Example:   See FIND_ALERT and SET_ALERT_PROPERTY
*/


SHOW_EDITOR built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Displays the given editor at the given coordinates and passes a string to the editor, or retrieves an existing string from the editor.  If no coordinates are supplied, the editor is displayed in the default position specified for the editor at design time.

Syntax

SHOW_EDITOR
  (editor_id    Editor,
   message_in   VARCHAR2,
   message_out  VARCHAR2,
   result       BOOLKAN);

SHOW_EDITOR
  (editor_id    Editor,
   message_in   VARCHAR2,
   x            NUMBER,
   y            NUMBER,
   message_out  VARCHAR2,
   result       BOOLEAN);
SHOW_EDITOR
  (editor_name  VARCHAR2,
   message_in   VARCHAR2,
   message_out  VARCHAR2,
   result       BOOLEAN);
SHOW_EDITOR
  (editor_name  VARCHAR2,
   message_in   VARCHAR2,
   x            NUMBER,
   y            NUMBER,
   message_out  VARCHAR2,
   result       BOOLEAN);

Built-in Type  unrestricted procedure that returns two OUT parameters (result and message_out)

Enter Query Mode  yes

Parameters

editor_id	Specifies the unique ID that Form Builder assigns when it creates the editor.  Use the FIND_EDITOR built-in to return the ID to a variable of the appropriate data type.  The data type of the ID is Editor.

editor_name	Specifies the name you gave to the editor when you defined it.  The data type of the name is VARCHAR2.

message_i 	Specifies a required IN parameter of VARCHAR2 data type.  The value passed to this parameter can be NULL.  You can also reference a text item or variable.

x	Specifies the x coordinate of the editor.  Supply a whole number for this argument.

y	Specifies the y coordinate of the editor.  Supply a whole number for this argument.

message_out	Specifies a required OUT parameter of VARCHAR2 data type.  You can also reference a text item or variable.  If the operator cancels the editor, result is FALSE and message_out is NULL.

result	Specifies a required OUT parameter of BOOLEAN data type.  If the operator accepts the editor, result is TRUE.  If the operator cancels the editor, result is FALSE and message_out is NULL.


SHOW_EDITOR restrictions

•	Message_out should be at least as long as message_in, because the length of the variable or text item specified for message_out determines the maximum number of characters the editor can accept.

•	The message_in parameter values are always converted to VARCHAR2 by Form Builder when passed to the editor.  However, if you are passing message_out to something other than a VARCHAR2 type object, you must first perform the conversion by passing the value to a variable and then perform type conversion on that variable with PL/SQL functions TO_DATE or TO_NUMBER.

•	The Width must be at least wide enough to display the buttons at the bottom of the editor window.


SHOW_EDITOR examples

/*

** Built-in:  SHOW_EDITOR
** Example:   Accept input from the operator in a user-defined
**            editor. Use the system editor if the user has
**            checked the "System_Editor" menu item under the
**            "Preferences" menu in our custom menu module.
*/
DECLARE
  ed_id   Editor;
  mi_id   MenuItem;
  ed_name VARCHAR2(40);
  val     VARCHAR2(32000);
  ed_ok   BOOLEAN;
BEGIN
  mi_id := Find_Menu_Item('PREFERENCES.SYSTEM_EDITOR');
  IF Get_Menu_Item_Property(mi_id,CHECKED) = 'TRUE' THEN
    ed_name := 'system_editor';
  ELSE
    ed_name := 'my_editor1';
  END IF;

  ed_id := Find_Editor( ed_name );
  /*
  ** Show the appropriate editor at position (10,14) on the
  ** screen.  Pass the contents of the :emp.comments item
  ** into the editor and reassign the edited contents if
  ** 'ed_ok' returns boolean TRUE.
  */
  val := :emp.comments;
  Show_Editor( ed_id, val, 10,14, val, ed_ok);
  IF ed_ok THEN
    :emp.comments := val;
  END IF;
END;


SHOW_KEYS built-in

 Examples	     Related Topics	 All Built-ins

Description

Displays the Keys screen.  When the operator presses a function key, Form Builder redisplays the form as it was before invoking the SHOW_KEYS built-in.

Syntax

SHOW_KEYS;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


SHOW_KEYS examples

/*

** Built-in:  SHOW_KEYS
** Example:   Display valid function key bindings
*/
BEGIN
  Show_Keys;
END;


SHOW_LOV built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Displays a list of values (LOV) window at the given coordinates, and returns TRUE if the operator selects a value from the list, and FALSE if the operator Cancels and dismisses the list.

Syntax

SHOW_LOV
  (lov_id  LOV);

SHOW_LOV
  (lov_id  LOV,
   x       NUMBER,
   y       NUMBER);
SHOW_LOV
  (lov_name  VARCHAR2);
SHOW_LOV
  (lov_name  VARCHAR2,
   x         NUMBER,
   y         NUMBER);

Built-in Type  unrestricted function

Returns  BOOLEAN

Enter Query Mode  yes

Parameters

lov_id	Specifies the unique ID that Form Builder assigns the LOV when created.  Use the FIND_LOV built-in to return the ID to an appropriately typed variable.  The data type of the ID is LOV.

lov_name	The name you gave to the LOV when you defined it.  The data type of the name is VARCHAR2.

x	Specifies the x coordinate of the LOV.

y	Specifies the y coordinate of the LOV.

Usage Notes

When SHOW_LOV is used to display an LOV, Form Builder ignores the LOV's Automatic Skip property.

If you want to move the cursor to the next navigable item, use the LIST_VALUES built-in.


SHOW_LOV restrictions

If the lov_name argument is not supplied and there is no LOV associated with the current item, Form Builder issues an error.

If the record group underlying the LOV contains 0 records, the BOOLEAN return value for SHOW_LOV will be FALSE.


SHOW_LOV examples

/*

** Built-in:   SHOW_LOV
** Example:    Display a named List of Values (LOV)
*/
DECLARE
  a_value_chosen BOOLEAN;
BEGIN
  a_value_chosen := Show_Lov('my_employee_status_lov');
  IF NOT a_value_chosen THEN
    Message('You have not selected a value.');
    Bell;
    RAISE Form_Trigger_Failure;
  END IF;
END;


SHOW_MENU built-in

 Examples	   Restrictions	 All Built-ins

Description

Displays the current menu if it is not currently displayed.  It does not make the menu active.

Because SHOW_MENU does not make the menu active, Form Builder does not allow the menu to obscure any part of the current canvas.  Therefore, all or part of the menu does not appear on the screen if the current canvas would cover it.

Syntax

SHOW_MENU;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


SHOW_MENU restrictions

Only for use in character mode environments.


SHOW_MENU examples

/*

** Built-in:  SHOW_MENU
** Example:   Display the menu if no canvas overlays it.
*/
BEGIN
  Show_Menu;
END;


SHOW_VIEW built-in

 Examples	     Related Topics	 All Built-ins

Description

Displays the indicated canvas at the coordinates specified by the canvas's X Position and Y Position property settings.  If the view is already displayed, SHOW_VIEW raises it in front of any other views in the same window.

Syntax

SHOW_VIEW
  (view_id  ViewPort);

SHOW_VIEW
  (view_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

view_id	Specifies the unique ID that Form Builder assigns the view when it creates the object.  Use the FIND_VIEW built-in to return the ID to an appropriately typed variable.  The data type of the ID is ViewPort.

view_name	Specifies the name that you gave the view when defining it.  The data type of the name is VARCHAR2.


SHOW_VIEW examples

/*

** Built-in:  SHOW_VIEW
** Example:   Programmatically display a view in the window to
**            which it was assigned at design time.
*/
BEGIN
  Show_View('My_Stacked_Overlay');
END;


SHOW_WINDOW built-in

 Examples	     Related Topics	 All Built-ins

Description

Displays the indicated window at either the optionally included X,Y coordinates, or at the window's current X,Y coordinates. If the indicated window is a modal window, SHOW_WINDOW is executed as a GO_ITEM call to the first navigable item in the modal window.

Syntax

SHOW_WINDOW
  (window_id  Window);

SHOW_WINDOW
  (window_id  Window,
   x          NUMBER,
   y          NUMBER);
SHOW_WINDOW
  (window_name  VARCHAR2);
SHOW_WINDOW
  (window_name  VARCHAR2,
   x            NUMBER,
   y            NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

window_id	Specifies the unique ID that Form Builder assigns the window when created.  Use the FIND_WINDOW built-in to return the ID to an appropriately typed variable.  The data type of the ID is Window.

window_name	Specifies the name that you gave the window  when defining it.  The data type of the name is VARCHAR2.

x	Specifies the x coordinate of the window.  Supply a whole number for this argument.

y	Specifies the y coordinate of the window.  Specify this value as a whole NUMBER.


SHOW_WINDOW examples

/*

** Built-in:  SHOW_WINDOW
** Example:   Override the default (x,y) coordinates for a
**            windows location while showing it.
*/
BEGIN
  Show_Window('online_help',20,5);
END;


SYNCHRONIZE built-in

 Examples	   Restrictions	 All Built-ins

Description

Synchronizes the terminal screen with the internal state of the form.  That is, SYNCHRONIZE updates the screen display to reflect the information that Form Builder has in its internal representation of the screen.

Syntax

SYNCHRONIZE;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


SYNCHRONIZE restrictions

SYNCHRONIZE only updates the screen display if both of the following conditions are true:

•	Form Builder is at the item level in the forms hierarchy (i.e., SYSTEM.CURRENT_ITEM is not NULL).


SYNCHRONIZE examples

/*

** Built-in:  SYNCHRONIZE
** Example:   Achieve an odometer effect by updating the
**            screen as an items value changes quickly.
**            Without synchronize, the screen is typically
**            only updated when Form Builder completes all trigger
**            execution and comes back for user input.
*/
BEGIN
  FOR j IN 1..1000 LOOP
    :control.units_processed := j;
    SYNCHRONIZE;
    Process_Element(j);
  END LOOP;
END;


TERMINATE built-in

 Restrictions	 All Built-ins

Description

TERMINATE terminates input in a form or dialog box.  This function is equivalent to the operator pressing [ACCEPT].

Syntax

TERMINATE;

Built-in Type   restricted function

Parameters

none


TERMINATE restrictions

Terminate applies only in the Enter Parameter Values dialog.


TO_VARIANT built-in

 All Built-ins

Description

Creates an OLE variant and assigns it a value.  There are four versions of the function.

Syntax

FUNCTION TO_VARIANT
  (newval NUMBER,
   vtype VT_TYPE
   persistence BOOLEAN)
RETURN newvar OLEVAR;

...or...

FUNCTION TO_VARIANT
  (newval VARCHAR2,
   vtype VT_TYPE
   persistence BOOLEAN)
RETURN newvar OLEVAR;

...or...

FUNCTION TO_VARIANT
  (source_table,
   vtype VT_TYPE
   arrspec VARCHAR2, persistence BOOLEAN)
RETURN newvar OLEVAR;

...or...

FUNCTION TO_VARIANT
  (var OLEVAR,
   vtype VT_TYPE
   arrspec VARCHAR2, persistence BOOLEAN)
RETURN newvar OLEVAR;

Built-in Type  unrestricted function

Returns  the newly-created OLE variant.

Parameters

newval	The value to be given to the newly-created OLE variant.
vtype	The OLE VT_TYPE to be given to the newly-created variant.   This is an optional parameter. If not specified, the default value for the NUMBER version of the function is VT_R8.  For the VARCHAR2 version, the default is VT_BSTR.  For the table version, the default is determined from the PL/SQL types of the table  For the OLEVAR version, the default is the type of the source variant.
persistence	Controls the persistence of the variant after its creation.  A boolean value of TRUE establishes the variant as persistent; a value of FALSE establishes the variant as non-persistent. This is an optional parameter.  If not specified, the default value is non-persistent.
source_table	An existing PL/SQL table that is used to establish the bounds and values of the newly-created variant table.  The source table can be of any type.
arrspec	Indicates which selected element or elements of a source table are to be used in the creation of the new variant.  The lower bound always starts at 1.  For more information, see Specifiers for OLE Arrays. This is an optional parameter.  If not specified, the entire source table or source variant is used.
var	An existing OLE variant whose value is to be given to the new variant.  (This source variant may be a table.)
Usage Notes

•	This function first creates an empty variant and then gives it a value.  It offers a combined version of the CREATE_VAR and SET_VAR operations.

•	This TO_VARIANT function can also be thought of as the inverse version of the VAR_TO_* function.

•	Note that the OLEVAR version of this function differs from the NUMBER, VARCHAR2, and table versions in that it uses an existing OLE variant as the source, rather than a PL/SQL equivalent value.


UNSET_GROUP_SELECTION built-in

 Examples	     Related Topics	 All Built-ins

Syntax

UNSET_GROUP_SELECTION
  (recordgroup_id  RecordGroup,
   row_number      NUMBER);

UNSET_GROUP_SELECTION
  (recordgroup_name  VARCHAR2,
   row_number        NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Description

Unmarks the specified row in the indicated record group. Use the procedure to unmark rows that have been programmatically selected by a previous call to SET_GROUP_SELECTION.

Rows are numbered sequentially starting at 1.  If you select rows 3, 8, and 12, for example, those rows are considered by Form Builder to be selections 1, 2, and 3.  You can undo any row selections for the entire group by calling the RESET_GROUP_SELECTION built-in.

Parameters

recordgroup_id	Specifies the unique ID that Form Builder assigns to the record group when created.  Use the FIND_GROUP built-in to return the ID to a variable.  The data type of the ID is RecordGroup.

recordgroup_name	Specifies the name of the record group that you gave to the group when creating it.  The data type of the name is VARCHAR2.

row_number	Specifies the number of the record group row that you want to select.  The value you specify is a NUMBER.


UNSET_GROUP_SELECTION examples

/*

** Built-in:  UNSET_GROUP_SELECTION
** Example:   Clear all of the even rows as selected in the
**            record group whose id is passed-in as a
**            parameter.
*/
PROCEDURE Clear_Even_Rows ( rg_id RecordGroup ) IS
BEGIN
  FOR j IN 1..Get_Group_Row_Count(rg_id) LOOP
    IF MOD(j,2)=0 THEN
      Unset_Group_Selection( rg_id, j );
    END IF;
  END LOOP;
END;


UP built-in

  Related Topics	 All Built-ins

Description

Navigates to the instance of the current item in the record with the next lowest sequence number.

Syntax

UP;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


UPDATE_CHART built-in

 All Built-ins

Description

A data block is updated whenever it is queried or when changes to it are committed. By default, when the block is updated, any charts based on the data block are automatically updated. You can use the UPDATE_CHART built-in to explicitly cause a chart item to be updated, even if the data block on which it is based has not been updated. For example, you may want update the chart to reflect uncommitted changes in the data block.

Syntax

PROCEDURE UPDATE_CHART
  (chart_name VARCHAR2,
   param_list_id TOOLS.PARAMLIST
);

PROCEDURE UPDATE_CHART
  (chart_name VARCHAR2,
   param_list_name VARCHAR2
);

PROCEDURE UPDATE_CHART
  (chart_id FORMS4C.ITEM,
   param_list_id TOOLS.PARAMLIST
);

PROCEDURE UPDATE_CHART
  (chart_id FORMS4C.ITEM,
   param_list_name VARCHAR2
);

PROCEDURE UPDATE_CHART
  (chart_id FORMS4C.ITEM
);

PROCEDURE UPDATE_CHART
  (chart_name VARCHAR2
);

Built-in Type  unrestricted procedure

Enter Query Mode yes

Parameters

chart_id	Specifies the unique ID of the chart.

chart_name	Specifies the unique name of the chart.

param_list_id	Specifies the unique ID of the chart parameter list.

param_list_name	Specifies the unique name of the chart parameter list.


UPDATE_RECORD built-in

 Restrictions	 All Built-ins

Description

When called from an On-Update trigger, initiates the default Form Builder processing for updating a record in the database during the Post and Commit Transaction process.

This built-in is included primarily for applications that run against a non-ORACLE data source.

Syntax

UPDATE RECORD;

Built-in Type    restricted procedure

Enter Query Mode  no

Parameters

none


UPDATE_RECORD restrictions

Valid only in an On-Update trigger.


USER_EXIT built-in

 Examples	     Related Topics	 All Built-ins

Description

Calls the user exit named in the user_exit_string.

Syntax

USER_EXIT
  (user_exit_string  VARCHAR2);

USER_EXIT
  (user_exit_string  VARCHAR2,
   error_string      VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

user_exit_string	Specifies the name of the user exit you want to call, including any parameters.

error_string	Specifies a user-defined error message that Form Builder should display if the user exit fails.


USER_EXIT examples

/*

** Built-in:  USER_EXIT
** Example:   Invoke a 3GL program by name which has been
**            properly linked into your current Form Builder
**            executable. The user exit subprogram must parse
**            the string argument it is passed to decide what
**            functionality to perform.
*/
PROCEDURE Command_Robotic_Arm( cmd_string VARCHAR2 ) IS
BEGIN
  /*
  ** Call a C function 'RobotLnk' to initialize the
  ** communication card before sending the robot a message.
  */
  User_Exit('RobotLnk INITIALIZE Unit=6,CmdToFollow=1');
  IF NOT Form_Success THEN
    Message('Failed to initialize Robot 6');
    RAISE Form_Trigger_Failure;
  END IF;
  /*
  ** Pass the string argument as a command to the robot
  */
  User_Exit('RobotLnk SEND Unit=6,Msg='||cmd_string );
  IF NOT Form_Success THEN
    Message('Command not understood by Robot 6');
    RAISE Form_Trigger_Failure;
  END IF;
  /*
  ** Close the robot's communication channel
  */
  User_Exit('RobotLnk DEACTIVATE Unit=6');
  IF NOT Form_Success THEN
    Message('Failed to Deactivate Robot');
    RAISE Form_Trigger_Failure;
  END IF;

  /*
  ** The user exit will deposit a timing code into the item
  ** called 'CONTROL.ROBOT_STATUS'.
  */
  Message('Command Successfully Completed by Robot 6'||
      ' in '||TO_CHAR(:control.robot_timing)||
      ' seconds.');
END;


VALIDATE built-in

 Examples	     Related Topics	 All Built-ins

Description

VALIDATE forces Form Builder to immediately execute validation processing for the indicated validation scope.

Syntax

VALIDATE
  (validation_scope  NUMBER);

Built-in Type:

unrestricted procedure

Enter Query Mode  yes

Parameters

validation scope	Specify one of the following scopes:

DEFAULT_SCOPE  Perform normal validation for the default scope, determined by the runtime platform.

Note:  If you change the scope via SET_FORM_PROPERTY(VALIDATION UNIT) and then call VALIDATE(DEFAULT_SCOPE), you will override the default scope as defined in the form module.  In this case, Form Builder will not validate at the default scope but at the scope defined by SET_FORM_PROPERTY.

FORM_SCOPE  Perform normal validation for the current form.

BLOCK_SCOPE  Perform normal validation for the current block.

RECORD_SCOPE Perform normal validation for the current record.

ITEM_SCOPE  Perform normal validation for the current item.

Note on runtime behavior

If an invalid field is detected when validation is performed, the cursor does not move to that field.  Instead, the cursor remains in its previous position.


VALIDATE examples

/*

** Built-in:  VALIDATE
** Example:  Deposits the primary key value, which the user
**           has typed, into a global variable, and then
**           validates the current block.
** Trigger:  When-New-Item-Instance
*/
BEGIN
  IF :Emp.Empno IS NOT NULL THEN
   :Global.Employee_Id := :Emp.Empno;
    Validate(block_scope);
      IF NOT Form_Success THEN
        RAISE Form_Trigger_Failure;
      END IF;
    Execute_Query;
  END IF;
END;


VARPTR_TO_VAR

 All Built-ins

Description

Changes a variant pointer into a simple variant.

Syntax

FUNCTION VARPTR_TO_VAR
  (variant OLEVAR, vtype VT_TYPE)
RETURN changed OLEVAR;

Built-in Type  unrestricted function

Returns  the transformed variant.

Parameters

variant	The OLE variant pointer to be changed into a variant.
vtype	The OLE VT_TYPE to be given to the transformed variant. This is an optional parameter.  If not specified, the default value is VT_VARIANT.
Usage Notes

•	This function removes VT_BYREF typing from the variant.

•	If the variant's type was not VT_BYREF, the variant is assumed to hold an address to the type specified in the vtype, and is de-referenced accordingly.

•	If the pointer was NULL or the variant was of type VT_NULL, then VT_EMPTY is returned.


VAR_TO_TABLE

 All Built-ins

Description

Reads an OLE array variant and populates a PL/SQL table from it.

Syntax

PROCEDURE VAR_TO_TABLE
  (var OLEVAR,
   target_table,
   arrspec VARCHAR2);

Built-in Type  unrestricted procedure

Parameters

var	The OLE variant that is the source array.
target_table	The PL/SQL table to be populated.
arrspec	Indicates which rows, columns, or elements of the source array are to be used.  See Specifiers for OLE Arrays for more information. This is an optional parameter.  If not specified, all elements in the source array are used.
Usage Notes

For similar operations on other data types, use the function VAR_TO_type .


VAR_TO_type
VAR_TO_<type>

 All Built-ins

Description

Reads an OLE variant and transforms its value into an equivalent PL/SQL type.

There are three versions of the function (denoted by the value in type), one for each for of the types CHAR, NUMBER, and OBJ.

Syntax

FUNCTION VAR_TO_CHAR
  (var OLEVAR, arrspec VARCHAR2)
RETURN retval VARCHAR2;

...or...

FUNCTION VAR_TO_NUMBER
  (var OLEVAR, arrspec VARCHAR2)
RETURN retval NUMBER;

...or...

FUNCTION VAR_TO_OBJ
  (var OLEVAR, arrspec VARCHAR2)
RETURN retval OLEOBJ;

Built-in Type  unrestricted function

Returns  The variant with its value changed into an equivalent PL/SQL-type.  Note that the type of the return depends on the version of the function chosen.

Parameters

var	The OLE variant to be read.
arrspec	This parameter is used only if the OLE variant is an array.  It indicates which element of the array is to be read and returned. See Specifiers for OLE Arrays for more information.
Usage Notes

•	To return a table, use the procedure VAR_TO_TABLE .

•	In the VAR_TO_OBJ version of this function, the returned object is local (non-persistent).


VAR_TO_VARPTR

 All Built-ins

Description

Creates an OLE variant that points to an existing variant.

Syntax

FUNCTION VAR_TO_VARPTR
  (variant OLEVAR, vtype VT_TYPE)
RETURN newpointer OLEVAR;

Built-in Type  unrestricted function

Returns  the created variant

Parameters

variant	The existing OLE variant to be pointed to.
vtype	The type to be assigned to the created OLE variant. Permissible types are VT_BYREF, VT_PTR, and VT_NULL. This is an optional parameter.  If not specified, the default value is VT_BYREF.
Usage Notes

•	If the variant to be pointed to is of type VT_EMPTY, then the created pointer will be of type VT_NULL, regardless of the vtype specification in the function.

•	If vtype is specified as VT_BYREF, or defaults to VT_BYREF, then the created pointer will be of type VT_BYREF plus the source variant's type.

•	If the vtype does not have a VT_BYREF in it, then the created pointer will be of type VT_PTR, and it will point to the content within the variant.


VBX.FIRE_EVENT

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Raises an event for the VBX control.

Syntax

VBX.FIRE_EVENT
  (item_id       ITEM,
   event_name    VARCHAR2,
   paramlist_id  PARAMLIST);

VBX.FIRE_EVENT
  (item_id         ITEM,
   event_name      VARCHAR2,
   paramlist_name  VARCHAR2);
VBX.FIRE_EVENT
  (item_name     VARCHAR2,
   event_name    VARCHAR2,
   paramlist_id  PARAMLIST);
VBX.FIRE_EVENT
  (item_name       VARCHAR2,
   event_name      VARCHAR2,
   paramlist_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.

event_name	Specifies the name of a VBX event sent to the VBX control.  The data type of the name is VARCHAR2 string.

paramlist_id	Specifies the unique ID Form Builder assigns when a parameter list is created.  The data type of the ID is PARAMLIST.

paramlist_name	The name you give the parameter list object when it is defined.  The data type of the name is VARCHAR2 string.


VBX.FIRE_EVENT restrictions

Valid only on Microsoft Windows.


VBX.FIRE_EVENT examples

/*

** Built-in:  VBX.FIRE_EVENT
** Example:   The VBX.FIRE_EVENT built-in triggers a SpinDown
**            event for the SpinButton VBX control.
** Trigger:   When-Button-Pressed
*/
DECLARE
 ItemName VARCHAR2(40) := 'SPINBUTTON';
 PL_ID  PARAMLIST;
 PL_NAME  VARCHAR2(20) := 'EName';
BEGIN
 PL_ID := Get_Parameter_List(PL_NAME);
 IF id_null(PL_ID) THEN
  PL_ID := Create_Parameter_List(PL_NAME);
 END IF;
 VBX.FIRE_EVENT(ItemName,'SpinDown',PL_ID);
END;


VBX.GET_PROPERTY

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Obtains the value of a property from a VBX control.

Syntax

VBX.GET_PROPERTY
  (item_id   ITEM,
   property  VARCHAR2);

VBX.GET_PROPERTY
  (item_name  VARCHAR2,
   property   VARCHAR2);

Built-in Type  unrestricted function

Returns  VARCHAR2

Enter Query Mode  yes

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.

property	Specifies a property or an element of a property array for a VBX control.  A set of VBX properties exists for any given VBX control.  Examples of VBX properties are Width, Height, and FontSize.  The data type of property is a VARCHAR2 string.


VBX.GET_PROPERTY restrictions

Valid only on Microsoft Windows.


VBX.GET_PROPERTY examples

/*

** Built-in:  VBX.GET_PROPERTY
** Example:   Uses the VBX.GET_PROPERTY built-in to obtain the
**            CURRTAB property of the VBX item named TABCONTROL.
**            The property value of CURRTAB is returned to the
**            TabNumber variable and is used as input in the
**            user-defined Goto_Tab_Page subprogram.
** Trigger:   When-Custom-Item-Event
*/
DECLARE
 TabEvent varchar2(80);
 TabNumber char;
BEGIN
 TabEvent := :system.custom_item_event;
 IF (UPPER(TabEvent) = 'CLICK') then
  TabNumber := VBX.Get_Property('TABCONTROL','CurrTab');
  Goto_Tab_Page(TO_NUMBER(TabNumber));
 END IF;
END;


VBX.GET_VALUE_PROPERTY

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Gets the VBX Control Value Property of a VBX control.

Syntax

VBX.GET_VALUE_PROPERTY
  (item_id  ITEM);

VBX.GET_VALUE_PROPERTY
  (item_name  VARCHAR2);

Built-in Type  unrestricted function

Returns  property

Enter Query Mode  yes

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.


VBX.GET_VALUE_PROPERTY restrictions

Valid only on Microsoft Windows.


VBX.GET_VALUE_PROPERTY examples

/*

** Built-in:  VBX.GET_VALUE_PROPERTY
** Example:   Passes the VBX Control Value to the user-defined
**            Verify_Item_Value subprogram. Verify_Item_Value
**            ensures the display value is the expected value.
*/
DECLARE
 ItemName VARCHAR2(40) := 'SPINBUTTON';
 VBX_VAL_PROP VARCHAR2(40);
BEGIN
 VBX_VAL_PROP := VBX.Get_Value_Property(ItemName);
 Verify_Item_Value(VBX_VAL_PROP);
END;


VBX.INVOKE_METHOD

 Examples	   Restrictions	    Related Topics	 All Built-ins

Syntax

VBX.INVOKE_METHOD(item_id, method_name, w, x, y, z);

VBX.INVOKE_METHOD(item_name, method_name, w, x, y, z);

Built-in Type:

unrestricted procedure

Enter Query Mode  yes

Description

Invokes the specified method on the item.  If the method takes arguments, they should be specified.  The arguments should be provided in the order that the VBX control expects them.  The methods that are valid for VBX controls and a listing of the arguments they expect can be found in the moduleation that accompanies the VBX control.

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.

method_name	Specifies the name of the method to invoke.  The data type of the name is VARCHAR2 string.

w, x, y, z	Specifies optional arguments that might be required for VBX controls.  The data type of the arguments is VARCHAR2 string.


VBX.INVOKE_METHOD restrictions

Valid only on Microsoft Windows.


VBX.INVOKE_METHOD examples

/*

** Built-in:  VBX.INVOKE_METHOD_PROPERTY
** Example:   Adds an entry to a combobox. The entry to
**            add to the combobox is the first optional argument.
**            The position where the entry appears is the second
**            optional argument.
*/
DECLARE
 ItemName VARCHAR2(40) := 'COMBOBOX';
BEGIN
 VBX.Invoke_Method(ItemName,'ADDITEM','blue','2');
END;


VBX.SET_PROPERTY

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Sets the specified property for a VBX control.

Syntax

VBX.SET_PROPERTY
  (item_id   ITEM,
   property  VARCHAR2,
   value     VARCHAR2);

VBX.SET_PROPERTY
  (item_name  VARCHAR2,
   property   VARCHAR2,
   value      VARCHAR2);

Built-in Type:

unrestricted procedure

Enter Query Mode  yes

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.

property	Specifies a property or an element of a property array for a VBX control.  A set of VBX properties exists for any given VBX control.  Examples of VBX properties are Width, Height, and FontSize.  The data type of property is a VARCHAR2 string.

value	Specifies the value to be applied to the VBX property.  The data type of value is a VARCHAR2 string.


VBX.SET_PROPERTY restrictions

Valid only on Microsoft Windows.


VBX.SET_PROPERTY examples

/*

** Built-in:  VBX.SET_PROPERTY
** Example:   Uses the VBX.SET_PROPERTY built-in to set the Index
**            property of the SpinButton VBX control.
** Trigger:   When-Button-Pressed
*/
DECLARE
 ItemName VARCHAR2(40) := 'SPINBUTTON';
 VBX_VAL_PROP VARCHAR2(40);
 VBX_VAL  VARCHAR2(40);
BEGIN
 IF :System.Custom_Item_Event = 'SpinDown' THEN
  VBX_VAL_PROP := 'Index';
  VBX_VAL := '5';
  VBX.Set_Property(ItemName,VBX_VAL_PROP,VBX_VAL);
 END IF;
END;


VBX.SET_VALUE_PROPERTY

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Sets the VBX Control Value Property of a VBX control.

Syntax

VBX.SET_VALUE_PROPERTY
  (item_id   ITEM,
   property  VARCHAR2);

VBX.SET_VALUE_PROPERTY
  (item_name  VARCHAR2,
   property   VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.

property	Specifies a property for the Form Builder VBX Control Value Property. A set of VBX properties exists for any given VBX control.  Examples of VBX properties are Width, Height, and FontSize.  The data type of property is a VARCHAR2 string.


VBX.SET_VALUE_PROPERTY restrictions

Valid only on Microsoft Windows.


VBX.SET_VALUE_PROPERTY examples

/*

** Built-in:  VBX.SET_VALUE_PROPERTY
** Example:   Uses the VBX.SET_VALUE_PROPERTY built-in to set the
**            VBX Control Value property.
*/
DECLARE
 ItemName VARCHAR2(40) := 'SPINBUTTON';
 VBX_VAL_PROP VARCHAR2(40);
BEGIN
 IF :System.Custom_Item_Event = 'SpinDown' THEN
  VBX_VAL_PROP := 'Index';
  VBX.Set_Value_Property(ItemName,VBX_VAL_PROP);
 END IF;
END;


WEB.SHOW_DOCUMENT
WEB.SHOW_DOCUMENT built-in

 All Built-ins

Syntax:

SHOW_DOCUMENT(url, target);

Built-in Type:   unrestricted procedure

Enter Query Mode:  yes

Description:

Specifies the URL and target window of a Web application.

Parameters:

url	Datatype is VARCHAR2.  Specifies the Uniform Resource Locator of the document to be loaded.

target	Datatype is VARCHAR2.  Specifies one of the following targets:

_SELF  Causes the document to load into the same frame or window as the source document.

_PARENT Causes the target document to load into the parent window or frameset containing the hypertext reference.  If the reference is in a window or top-level frame, it is equivalent to the target _self.

_TOP Causes the document to load into the window containing the hypertext link, replacing any frames currently displayed in the window.

_BLANK Causes the document to load into a new, unnamed top-level window.

Restrictions:

Can only be used from within a form run from the Web.

Example:

/*

** Built-in:  WEB.SHOW_DOCUMENT
** Example:   Display the specified URL in the target window.
*/
BEGIN
  Web.Show_Document(‘http://www.abc.com’, ‘_self’);
END;


WHERE_DISPLAY built-in

 Restrictions	 All Built-ins

Description

Toggles the Where menu navigation option on and off.  In a full-screen menu, the Where option displays information about the operator's current location in the menu hierarchy.

Syntax

WHERE_DISPLAY;

Built-in Type:

unrestricted procedure

Enter Query Mode  yes

Parameters

none


WHERE_DISPLAY restrictions

WHERE_DISPLAY is valid only in a full-screen menu.


WRITE_IMAGE_FILE built-in

 Examples	   Restrictions	    Related Topics	 All Built-ins

Description

Writes the image from a Form Builder image item into the specified file.

Syntax

WRITE_IMAGE_FILE
 (file_name            VARCHAR2,
  file_type            VARCHAR2,
  item_id              ITEM,
  compression_quality  NUMBER,
  image_depth          NUMBER);

WRITE_IMAGE_FILE
  (file_name            VARCHAR2,
   file_type            VARCHAR2,
   item_name            VARCHAR2,
   compression_quality  NUMBER,
   image_depth          NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

file_name	The name of the file where the image is stored.  The file name must adhere to your operating system requirements.

file_type	The file type of the image:  BMP, CALS, GIF, JFIF, JPEG, PICT, RAS, TIFF, or TPIC.  The parameter takes a VARCHAR2 argument.

item_id	The unique ID Form Builder assigned to the image item when you created it.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  Datatype is ITEM.

item_name	The name you gave the image item when you defined it.  Datatype is VARCHAR2.

compression_quality	The degree of compression Form Builder will apply to the image when it stores it to the file (optional).  Datatype is VARCHAR2.  Valid values are:NO_COMPRESSION, MINIMIZE_COMPRESSION, LOW_COMPRESSION, MEDIUM_COMPRESSION, HIGH_COMPRESSION, MAXIMIZE_COMPRESSION

image_depth	The degree of depth Form Builder will apply to the image when it stores it to the file (optional).  Datatype is VARCHAR2.  Valid values are:ORIGINAL_DEPTH, MONOCHROME, GRAYSCALE, LUT  (Lookup Table), RGB  (Red, Green, Blue)


WRITE_IMAGE_FILE restrictions

•	The indicated file type must be compatible with the actual file type of the image.

•	As with any file, if you write the image to an existing file, you overwrite the contents of that file with the contents of the image item.

•	Though you can read PCD and PCX files from the filesystem or the database, you cannot write image files to the filesystem in PCD or PCX format (using WRITE_IMAGE_FILE).  (If you use a restricted file type when writing images to the filesystem, Form Builder defaults the image file to TIFF format.)

•	Writing a JPEG file from a Form Builder image item will result in loss of resolution.


WRITE_IMAGE_FILE examples

/* Built-in: WRITE_IMAGE_FILE

**
** Save the contents of an image item out to a file
** on the filesystem in a supported image format.
*/
BEGIN
  WRITE_IMAGE_FILE('output.tif',
                   'TIFF',
                   'emp.photo_image_data',
                   maximize_compression,
                   original_depth);
END;


WRITE_SOUND_FILE built-in

 Restrictions	    Related Topics	 All Built-ins

Description

Writes sound data from the specified sound item to the specified file.

Syntax

WRITE_SOUND_FILE(file_name     VARCHAR2,
                  file_type     VARCHAR2,
                  item_id       ITEM,
                  compression   NUMBER,
                  sound_quality NUMBER,
                  channels      NUMBER);

WRITE_SOUND_FILE(file_name      VARCHAR2,
                 file_type      VARCHAR2,
                 item_name      VARCHAR2,
                 compression    NUMBER,
                 sound_quality  NUMBER,
                 channels       NUMBER);

Built-in Type  unrestricted

Enter Query Mode  Yes

Parameters:

file_name	The fully-qualified file name of the file to which you wish to write sound data.

file_type	The file type for the sound data file.  Valid values are:  AU, AIFF, AIFF-C, and WAVE.  Note:  File type is optional, but should be specified if known for increased performance.  If omitted, Form Builder applies a default file type:  WAVE (Microsoft Windows), AIFF-C  (Macintosh), or AU (all others).

item_id	The unique ID Form Builder gave the sound item when you created it.

item_name	The name you gave the sound item when you created it.

compression	Whether the sound data should be compressed before Form Builder writes the data to the file.  Possible values are COMPRESSION_ON, COMPRESSION_OFF, and ORIGINAL_SETTING (retain the default compression setting of the data).  Compression is optional:  the default value, if omitted, is ORIGINAL_SETTING.

sound_quality	The quality of data sampling rate and depth for the sound data.  Possible values are:  HIGHEST_SOUND_QUALITY, HIGH_SOUND_QUALITY, MEDIUM_SOUND_QUALITY, LOW_SOUND_QUALITY, LOWEST_SOUND_QUALITY, and ORIGINAL_QUALITY.  Sound quality is optional:  the default value, if omitted, is ORIGINAL_QUALITY.

channels	Whether Form Builder should write the sound data to the file as monophonic or stereophonic.  Valid values are MONOPHONIC, STEREOPHONIC, and ORIGINAL_SETTING (retain the default channel setting of the data).  Channels is optional:  the default value, if omitted, is ORIGINAL_SETTING.


WRITE_SOUND_FILE restrictions

•	To use the PLAY_SOUND, READ_SOUND_FILE and WRITE_SOUND_FILE built-ins to play and/or record sound data in a file, you must create a sound item and place focus in that item before the call to the built-ins are executed.  Although the sound item will be represented by the sound item control at design-time, the control will not function for end users at runtime.  Therefore, you must "hide" the sound item behind another object on the canvas so users will not see the control at runtime.  (To place focus in an item, it cannot be assigned to a null canvas or have its Displayed property set to No.)  For example, to call the READ_SOUND_FILE and PLAY_SOUND built-ins from a When-Button-Pressed trigger, place focus in the "hidden" sound item by including a call to the built-in procedure GO_ITEM in the trigger code prior to calling READ_SOUND_FILE and PLAY_SOUND.


What are calculated items?

  Related Topics

Calculated items are items to which you declaratively assign values based on calculations involving one or more variable values.  An example of a calculated item is a running total of employees' compensation, which changes any time a component value of the total (a single employee's salary, bonus, etc.) changes.

Valid Item Types  A calculated item must be capable of storing a value.  You can define any of the following item types as a calculated item:

•	check box

•	display item

•	list item

•	radio group

•	text item

•	VBX control


Guidelines for working with calculated items

  Related Topics

•	Calculated items are display-only control items.

•	Calculated items cannot be database items.

•	While you can set a calculated item's Enabled, Mouse Navigate, and Keyboard Navigable properties to Yes, you cannot set the Insert Allowed or Update Allowed properties to Yes.


About calculation modes

  Related Topics

The value of a calculated item is based on a calculation.  To define the calculation, you first must specify a calculation mode—Summary or Formula:

•	Summary—the calculated item's value is the summary of all values of a single item in a single block

•	Formula—the calculated item's value is the result of a formula that performs calculations involving one or more values


About summary calculation

  Related Topics

A summary calculation for a calculated item consists of a single computation performed on all records of a single item in a single data block.

When working with summary calculations, draw a distinction between two similar terms:

•	The summary item is the calculated item to which you will assign a value.  It must reside either in a control block with the Single Record property set to Yes, or in the same block as the summarized item.

•	The summarized item's values are summarized (i.e., averaged, summed up, etc.) and then assigned to the summary item.  The summarized item must reside in a data block with the Query All Records or Precompute Summaries property set to Yes, or in a control block.

Null Value  If the summarized item's block is empty—or if each instance of the item has a null value—then the item's value is null, unless its Summary Function property is set to Count, in which case the item's value is zero.  For purposes of computing summary items, a block is treated as empty while it is in Enter-Query mode, and while it is being selected into (up to but not including the firing of an ON_CLOSE trigger), unless the block's Precompute Summaries property is set to Yes.

Valid Datatypes  You must set the Data Type property of a summary item to Number, unless the item's Summary Type property is Max or Min, in which case the datatype must mirror that of its associated summarized item.  For example, a calculated item that displays the most recent (i.e., maximum) date in the HIRE_DATE column must have a datatype of Date.


About formula calculation

  Related Topics

A formula calculation assigns a value to a calculated item by performing calculations involving one or more bind variables or constants.  Bind variables include form items, parameters, global variables, and system variables.

Calculation Expression  To define the calculation that will assign values to a formula item, you must provide a single PL/SQL expression in the item's Formula property.  The expression you write can reference built-in or user-written subprograms.

You cannot enter an entire PL/SQL statement in the Formula property field.  Form Builder adds the actual assignment code to the formula internally, so do not add the code yourself or terminate your calculation expression with a semicolon.  For example, if you set the Formula property to the expression:

   :emp.sal + :emp.comm

Form Builder will internally convert this into a complete statement:

   :emp.gross_comp := (:emp.sal + :emp.comm);

Null Value  The value of a formula item is NULL if  (1) an end user has not navigated to the item's block, and no item in the formula item's block has been assigned a value by a PL/SQL statement, or  (2) the formula item's block is in Enter-Query mode.


About recalculation of calculated items

  Related Topics

Form Builder automatically marks a calculated item for recalculation whenever the value of a bind variable involved in the calculation is modified in any way.

Note that actual recalculation doesn't happen immediately. It occurs sometime after the item is marked but before the new value of the calculated item is referenced or displayed to the end user.  Your application's logic should not depend on recalculation of a calculated item occurring at a specific time.

Record Status  Recalculation does not change the status of a calculated item's record, even if the status is NEW.


About summary item recalculation

  Related Topics

Form builder marks a summary item for recalculation whenever a value of its summarized item is inserted, modified, or deleted in any row of its block.


About formula item recalculation

  Related Topics

A formula item is marked for recalculation whenever a change occurs to any non-system bind variable (i.e., global variable, parameter, or item) that appears in the formula or in any user-written subprogram referenced by the formula.  Note that Form Builder does not automatically mark an item for recalculation when the value returned by a built-in function or system variable (referenced by the formula) changes.

Indirect References  Using built-ins such as COPY, NAME_IN, DO_KEY, and EXECUTE_TRIGGER can result in an indirect reference to a bind variable.  If you use such built-ins in a formula, Form Builder will not recognize that a bind variable has been referenced (at compile time), and thus will not mark the associated calculated item for recalculation when the bind variable changes (at runtime).  To avoid this, code an explicit reference for each bind variable (in any program unit directly or indirectly called by the formula) that is indirectly referenced.  Use the DUMMY_REFERENCE built-in for this purpose:

   temp_sal := NAME_IN('emp.sal');
   DUMMY_REFERENCE(:emp.sal);

Note:  DUMMY_REFERENCE need not be executed for the referenced bind variable to be recognized by Form Builder (thereby causing the related calculated item to be marked for recalculation).

RECALCULATE Built-in  Use RECALCULATE to explicitly mark a formula item for recalculation.  Do this if a formula references a system variable or built-in function, and a change has occurred that would cause the system variable or built-in function to return a different value. Note that even when RECALCULATE is called on a formula item, recalculation does not happen immediately. The item will be recalculated sometime before the next reference to the item.

Warning:  Regarding formula items, avoid a scenario where the formula for calculated item A calls a subprogram that changes the value of a bind variable that affects the value of calculated item B.  In a case like this, it is difficult to ensure that the value of the bind variable will be accurate in relation to its effect on the value of items A or B (since Form Builder cannot guarantee precisely when A and B will be recalculated).


Creating a calculated item

  Next Step	   Examples	   Restrictions	    Related Topics

To create a calculated item:

1	In the Object Navigator, create a new interface item (make sure it is a control item).

Tip:  The item's datatype must be compatible with the calculation you wish to use to compute the item's value.  For example, if you wish to compute an item's value with the Sum function, create an interface item of datatype Number.

2	Double-click the item's object icon to display the Property Palette.

3	Under the Calculation node, set the item's Calculation Mode property to Formula or Summary.

4	If you set Calculation Mode to:

•	Formula, click on the Formula property, click the More button to display the Formula dialog, and type a PL/SQL expression to define the formula.  Click OK to compile the expression.

•	Summary, use the Summary Function poplist to select a summary type, then use the Summarized Block and Summarized Item poplists to select the block and item whose values will be summarized to compute a value for the calculated item.


Creating a calculated item restrictions

•	The following item properties are defaulted to No at compilation time:  Database Item, Insert Allowed, Primary Key, Query Allowed, Required, Update Allowed, and Update Only if NULL.

•	The following item properties are ignored at compilation time:  Copy Value from Item, Initial Value, Highest Allowed Value, and Lowest Allowed Value.

•	You cannot use PL/SQL to directly assign a value to a calculated item.

•	End users cannot insert or modify a calculated item.

•	A calculated item cannot be an LOV return item.

•	A calculated item cannot be a master or subordinate mirror item.

•	If the value of a formula item in a master block depends on values of detail block items—and more than one row of the master block is displayed—then values of the calculated item for non-current master-block rows are meaningless.

•	A formula (and all user-written subprograms called by the formula) cannot reference a restricted built-in subprogram.

•	A formula (and all user-written subprograms called by the formula) cannot execute DML statements.

•	You cannot create any circular dependencies among a form's calculated items.

•	You cannot use a When-Validate-Item trigger in conjunction with a calculated item.  Since a calculated item is by definition a valid item, this trigger event never will occur.


Creating a calculated item examples

Example

/* Example 1: Define a summary calculation to display the

** maximum salary of all employees. Create display item MAX_SAL
** in the EMP block, set its Calculation Mode property to
** Summary, set its Summary Function property to Max, set its
** Summarized Block property to EMP, and set its Summarized
** Item property to SAL.
**
** Example 2: Define a formula calculation to compute an
** employee's gross total compensation. Create display item
** TOTAL_COMP in the EMP block, set its Calculation Mode
** property to Formula, and set its Formula property to the
** following PL/SQL expression:
*/
   :emp.sal + :emp.comm

/* Example 3: Define a Formula item to compute a different
** value for total compensation depending on the block where
** the cursor currently is positioned. Form has 3 blocks:
** 2 data blocks (EMP1 and EMP2), and one control block
** (COMP). Create a display item TOTAL_COMP in the COMP block
** that displays total compensation. Set the Formula property
** for COMP.TOTAL_COMP to an expression (a function call):
*/
   total_comp_func

/* Function TOTAL_COMP_FUNC is defined as follows: */

   FUNCTION total_comp_func RETURN number IS
   BEGIN
     IF :system.cursor_block = 'emp1' THEN
        RETURN :emp1.sal + :emp1.comm;
     END IF;
     IF :system.cursor_block = 'emp2' THEN
        RETURN :emp2.sal + :emp2.comm;
     END IF;
     RETURN null;
   END;

/* Form Builder automatically recalculates COMP.TOTAL_COMP
** whenever a change occurs to the value of :EMP1.SAL,
** :EMP1.COMM, :EMP2.SAL, or :EMP2.COMM.  Form Builder
** will not, however, recalculate COMP.TOTAL_COMP when an
** end user navigates between blocks, since changes to
** system variables don't automatically cause recalculation.
** To ensure that the correct value always is displayed,
** define a PRE-BLOCK trigger at the form level, containing
** the statement:
*/
   RECALCULATE('comp.total_comp');


The Database Trigger editor interface

The Database Trigger editor consists of the following:

Table Owner	Displays the userid 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.
Table	Displays the name of the current database table.  Click the arrow to the right of this field to display a drop-down list of table names of the tables owned by the user shown in the Table Owner field.  Click a table in the list to select it.  The Table list displays only the names of the database tables you have access to.
Name	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 shown in the Table field.  The Name list displays only the names of the database triggers you have access to.
Triggering (BEFORE and AFTER)	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 options of the SQL command CREATE TRIGGER.
Statement	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.
Of Columns	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.
	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.
For Each Row	Specifies whether the trigger is a row trigger or a statement trigger.  For Each Row corresponds to the FOR EACH ROW option of the CREATE TRIGGER command.
Referencing 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	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.
Trigger Body	Is 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.
New	Creates a new, unnamed database 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 appear in a separate dialog.
Revert	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.
Drop	Drops the current database trigger from the database, with confirmation.
Close	Attempts to close the Database Trigger editor.  If any changes have been made but not applied, an alert appears, prompting you to compile or revert the changes or cancel the operation.  Once all changes have been compiled or reverted, the Database Trigger editor is closed.


Displays the userid 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.  Click the arrow to the right of this field to display a drop-down list of table names of the tables owned by the user shown in the Table Owner field.  Click a table in the list to select it.  The Table list displays only the names of the database tables you have access to.


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 shown in the Table field.  The Name list displays only the names of the database triggers you have access to.


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 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 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.


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.


Specifies whether the trigger is a row trigger or a statement trigger.  For Each Row corresponds to the FOR EACH ROW option of the CREATE TRIGGER command.


Specifies a correlation name to avoid a name conflict between the correlation name and a table that is named OLD.


Specifies a correlation name to avoid a name conflict between the correlation name and a table 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.


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 separate dialog.


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.


Attempts to close the Database Trigger editor.  If any changes have been made but not applied, an alert appears, prompting you to compile or revert the changes or cancel the operation.  Once all changes have been compiled or reverted, the Database Trigger editor is closed.


&


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 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
. . .


Server support

This release adds support for the Oracle8 Database Server.  At the same time, support for the Oracle7 Server is continued.

New applications

You can build new Forms Developer applications that will run against either an Oracle8 or an Oracle7 Server.  Naturally, applications that make use of Oracle8 features will need to run with that level of the server.

Existing applications

Existing Forms Developer applications that were designed to run using an Oracle7 Server will continue to run with that server.  In addition, if the application's target data is moved from an Oracle7 to an Oracle8 Server, an existing application can be run in that Oracle8 environment.


PL/SQL 8 support

This release of Form Builder 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 manual describes the new PL/SQL 8 features.

Compatibility with earlier versions of PL/SQL

If you have client-side program units written in PL/SQL V1 or V2, you must convert that code to the new level.  The PL/SQL V1 conversion utility is provided to help automate the upgrading process.

Stored program units written in PL/SQL V2 will run against the PL/SQL V8 engine on the database server, but may compile with errors.  These errors arise in some situations where there is syntax incompatibility between V2 and V8.  A V2 compatibility flag in V8 database enables you to choose a V2 compatibility mode, so that the V8 engine does not issue such errors when it compiles V2 code.  Chapter 6 in the Oracle8 Migration manual describes the situations that are covered by this compatibility flag.


New and extended properties

The following table lists the Form Builder properties that are new or extended in this release.

Property	Status and Use
Alias	New.  Creates an alias for an Oracle8 table name.
Column Name	Extended.  Now includes dot notation for items from column objects.
Detail Reference	New.  Identifies the REF item that forms a master-detail link.
DML Returning Value	New.  Controls Forms’ refreshing of screen with changed values after a database insert or update.
Implementation Class	New.  Identifies the class name of a user-supplied Java component or Bean.
Include REF Item	New.  Creates a hidden item called REF in the master block.
Relation Type	New.  Identifies the type of master-detail link (either relational join or object REF).


Form Builder 4.5 Runtime Behavior

Runtime behavior of forms created with Form Builder 5.0 through 6.0 differ from runtime behavior for Form Builder 4.5. During design time, you can select which runtime behavior will be used for a form by setting the form-level property, Runtime Compatibility Mode to either 4.5 (for Release 4.5) or 5.0 (for Release 5.0 through 6.0).

Overview

The following runtime behaviors are changed in Form Builder 5.0 through 6.0. The sections that follow describe the corresponding Form Builder 4.5 behavior:

•	When validation occurs (differences in navigation rules)

•	Standard validation checks (validation steps for various types of items)

•	Validation and the Defer Required Enforcement property

•	Initialization of mirror (synchronized) items

•	Validation of mirror items

•	Converting between date and string formats

•	Implicitly setting an item's Required property

•	Null values in poplists and T-lists

•	Null values and firing the POST-CHANGE trigger

When Validation Occurs

Form Builder 4.5 validation rules for navigation are as follows:

•	When you navigate from item A to item B in the same block, and item-level validation is in effect, the action taken depends on how the navigation was done:

•	If the navigation is the result of a GO_ITEM (mouse click), or the result of a PREVIOUS_ITEM (shift-tab key), then only item A is validated.  (This is the same as Form Builder 5.0.)

•	If the navigation is the result of a NEXT_ITEM (tab key), then item A and all items between A and B (in terms of their sequence number within the block, not in terms of their position in the block's navigation sequence) are validated. This may cause redundant validation.  For example, if you use the Next Navigable Item property to establish a navigation sequence that's the reverse of the items' sequence within the block  (as shown in the object navigator), then every time you hit tab, all items in the block (except the one you're tabbing to) will be validated. (In Form Builder 5.0, only item A is validated.)

•	For item-level validation, when Form Builder needs to position you at the first navigable item in a block, all earlier items in the block are validated.  This sometimes causes Form Builder to exit if one of those earlier items fails validation. (In Form Builder 5.0, the earlier items are not validated.)

•	For item-level validation, when you attempt to navigate out of a null-valued, Required item and the Defer Required Enforcement  is set to No, the action taken depends on how the navigation was done:

•	If the navigation is the result of a GO_ITEM (mouse click), or the result of a NEXT_ITEM (tab key), then you will get the error:  FRM-40202 Field must be entered. (This is the same as Form Builder 5.0.)

•	If the navigation is the result of a PREVIOUS_ITEM (shift-tab key), then no error will occur, and the navigation will succeed. (In Form Builder 5.0, error FRM-40202 is issued.)

Standard Validation Checks

There are certain steps that are performed whenever an item of a particular type is validated. The validation steps for Form Builder 4.5 text items are performed in the following order. If any step fails, the item is marked invalid, and the remaining steps are skipped:

1	Verify that a Required item is not null.

This step is performed only for:

•	combo boxes

•	poplist and T-list items that do not allow other values

•	navigable list items that mirror other items

•	navigable text items

A failure on combo boxes or poplist and T-list items that do not allow other values produces the message:
FRM-40212 Invalid value for field

Other failures produce the message : FRM-40202 Field must be entered

This validation is performed on item instances that are protected against update, even when the form's Validation Unit is ITEM.

2	Verify that a non-null value is the correct format for its data type.

This step is performed only for:

•	navigable combo boxes

•	text items

3	Verify that a Fixed Length item does not contain a non-null value of the wrong length.

This step is performed only for enabled text items.

4	Verify that the item's non-null value falls within the range specified for the item.

This step is performed only for enabled text items.

5	If the item’s Use LOV for Validation property is Yes, verify that the item's non-null value appears in the item's list of values (LOV).

6	If the item value is non-null, fire the POST-CHANGE trigger.

7	Fire the WHEN-VALIDATE-ITEM trigger.

Validation of non-text items omits steps 3 through 5. Step 2 only applies to text items and combo boxes, since they are the only items that allow the end user to type in values.

Validation and the Defer Required Enforcement Property

This property applies only when item-level validation is in effect.

This property has three settings:  Yes, 4.5, and No.  See the discussion of Defer Required Enforcement property for details.

 When set to Yes or 4.5, the item’s Required property is not enforced until record-level validation is performed.  A null value in the item is accepted.  The When-Validate-Item trigger does fire.

The following table shows how Form Runtime 4.5 and 5.0 behaviors differ for the various settings of Defer Required Enforcement for an item having the Required property but containing a null value:

	Defer-Req-Enf = Yes	Defer-Req-Enf = 4.5	Defer-Req-Enf = No
Runtime-Compat-Mode = 4.5	Behavior A	Behavior A	Behavior B
Runtime-Compat-Mode = 5.0	Behavior C	Behavior D	Behavior B
•	Behavior A:  The null value is accepted.  The When-Validate-Item trigger fires, and (assuming it is successful) the item instance is marked as valid; that is, its Item Is Valid property is set to Yes.  (Valid null-valued item instances will be re-validated during record-level validation.)

This behavior applies only to text items.  (The Defer Required Enforcement property is ignored for list items.)

•	Behavior B:  The null value is not accepted.  Navigation cannot leave the item instance until a valid, non-null value is entered.

•	Behavior C:  The null value is accepted.  The When-Validate-Item trigger does not fire.  Validation does not take place, and the item’s Item Is Valid property is unchanged.  (Thus, if the item is still null when record-level validation occurs, Forms Runtime will issue an error.)

•	Behavior D:  The null value is accepted. However, the item instance is not marked as valid. The When-Validate-Item trigger does fire.

This behavior applies to both text items and list items.

Initialization of Mirror (Synchronized) Items

Assume there are three items (A, B, and C) in the same data block. If you set the Synchronize With Item property of A and B to item C, items A and B are considered as subordinate mirror items. Item C is the master mirror item.

Form Builder 4.5 initialization rules for mirror items differ from 5.0 rules in the following respects:

•	Within a group of items that mirror each other (including the master mirror item), the initial value is taken from the last item within the group (in terms of sequence within the block) that specifies a displayable initial value.  That is, each initial value is applied in turn at runtime, and the last one that can be displayed by its item's widget overrides any earlier initial values. The ON-SEQUENCE-NUMBER trigger (if present) is fired when its item's initial value is being set (assuming it is a sequence number).

•	The initial value will be ignored at run time if the item is a poplist, T-list, radio group, or checkbox that does not allow other values and which has no element corresponding to the initial value. Mirroring items are not inspected.

Validation of Mirror Items

Form Builder 4.5 validation rules for mirror items differ from 5.0 rules in the following respects:

•	For a subordinate mirror item, the Required, RANGE_HIGH, and RANGE_LOW properties, and the POST-CHANGE and WHEN-VALIDATE-ITEM triggers, are taken from the subordinate mirror item.

•	During item-level validation, validation rules are always taken from the item currently being validated.  This means that the validation rules for an item set programmatically are determined by the item that is first visited by the end user. This may be an item that mirrors it or the item itself.

•	During record-level validation, within a group of mirror items, Form Builder validates the item that appears earliest in the block. This may cause a validation problem if invalid data is entered into a text item or combo box that is mirrored by another item that appears earlier in the block.

Converting Between Date and String Formats

To convert an item of data type DATE or DATETIME into an internal string (a string that is not user-visible) or vice versa, Form Builder chooses a date format mask to do the conversion.

In 5.0, Form Builder uses a built-in date format mask to do the conversion. This does not include conversions performed by PL/SQL.

In Form Builder 4.5 runtime compatibility mode, Form Builder uses the input , output, or built-in date format masks for the following cases  (see About format masks for dates for information about input, output, and built-in date format masks):

•	When executing GET_ITEM_PROPERTY on an item of data type DATE or DATETIME, for the properties RANGE_HIGH and RANGE_LOW.

•	When executing GET_ITEM_PROPERTY on an item of data type DATE or DATETIME, for the property DATABASE_VALUE. Form Builder 4.5 runtime compatibility mode gives you the behavior of Form Builder 4.5.7. (Earlier releases exhibit 5.0 behavior.)

•	When setting the value of an LOV column's return item, when the LOV column is of data type CHAR and the return item is of data type DATE or DATETIME, or vice versa. Form Builder 4.5 runtime compatibility mode gives you the behavior of Form Builder 4.5.7. (Earlier releases exhibit 5.0 behavior.)

•	When setting the initial value of an item of data type DATE or DATETIME, where the initial value is taken from a variable (using colon notation) of data type CHAR. Form Builder 4.5 runtime compatibility mode gives you the behavior of Form Builder 4.5.7. (Earlier releases exhibit 5.0 behavior.)

•	When setting the initial value of an item of data type CHAR, where the initial value is specified as $$DATE$$, $$DATETIME$$, $$DBDATE$$, or $$DBDATETIME$$.  Form Builder 4.5 runtime compatibility mode gives you the behavior of Form Builder 4.5.7. (Earlier releases exhibit 5.0 behavior.)

•	For all other cases, Form Builder uses the built-in date format mask.  For information about various date format masks, see Format Masks in the online help.

Implicitly Setting an Item’s Required Property

In Form Builder 4.5 runtime compatibility mode, an item's Required property is implicitly set to false if the item is disabled by setting its Enabled property to PROPERTY_FALSE using the SET_ITEM_PROPERTY built-in.

Null Values in Poplists and T-Lists

In Form Builder 4.5 runtime compatibility mode, programmatically assigning a null value to a poplist or T-list will fail if all of the following conditions are true:

•	Required property set to true

•	the item does not contain an explicitly-specified, null-valued element

•	the item does not allow other values

Under these conditions, Form Builder will issue the error: FRM-40212: Invalid value for field).

If a fetched row contains a null value in a column that is to be assigned to such a poplist or T-list, the fetched row will be rejected (it will not appear in the block).

In both Form Builder 4.5 and 5.0 runtime compatibility modes, a null value can always be displayed in any list item, even if the list item contains no explicitly-specified, null-valued element and does not allow other values.  In a T-list, the null value is displayed by selecting none of the elements. In a poplist, an implicit null value is temporarily added to the poplist.

Null Values and Firing the POST-CHANGE Trigger

In Form Builder 4.5 runtime compatibility mode, the POST-CHANGE trigger is never fired for a null value that was fetched into an item by a query. But for a null value assigned programmatically to an item, or entered into an item by the end user, the POST-CHANGE trigger is fired. The only exception is when the item is a text item. We do not recommend using the POST-CHANGE trigger for new applications.


Object constraints

  Related Topics

The following table presents constraints that Form Builder has for objects you create and for any other elements that are related to these objects.

Note:

Even though Form Builder itself imposes no limits on the number of objects you can create in a form, the amount of memory available can be a limiting factor.

Element	Constraint/Note
blocks per form	no practical limit
canvases/windows	no practical limit
canvas width	no practical limit
column name length	30 characters
boilerplate text	no practical limit
database field     references	no practical limit
detail blocks per master	no practical limit
global variable length	255 characters
identifiers (block names, field names, parameter list names, etc.)	30 characters
item max length	2000 characters, for CHAR values
items per block	no practical limit
join condition	255 characters
levels of menu nesting	8 - 10, depending on your operating system (When using pulldown menus, it is a good practice to limit menu nesting to four levels.)
list of values	no practical limit
menu items	no practical limit
menus	no practical limit
named visual attributes	255 named visual attributes
PL/SQL strings	no practical limit
WHERE Clause and ORDER BY Clause	total of 32,000 characters
record group character    columns	255 characters
record groups	255 columns
substitution parameters	no practical limit
text item range    checks per block	no practical limit
triggers	no practical limit
user-defined local variable name length	30 characters


Cursor constraints

  Related Topics

A database cursor is the memory that the ORACLE RDBMS assigns to a SQL command.  This applies to the SQL commands that are implicit to posting and querying data and the SQL commands that are explicit in triggers.  Form Builder controls cursor assignment for all implicit SQL commands and the explicit SQL commands in V2 triggers.

The following table presents constraints that apply to database cursors.

Element	Constraint/Note
open cursors     (maximum)	value of the OPEN_CURSORS parameter found in the INIT.ORA file
open cursors     (minimum)	• 5 per ORACLE connection.
	• 4 per runtime session when running against ORACLE or SQL*Connect.
	• 5 per block (1 for SELECT, 1 for UPDATE, 1 for INSERT, 1 for DELETE, and 1 for QUERY ).The first 4 listed are opened as needed, but can be suppressed by running in OPTIMIZETP=YES mode.  This restriction applies under normal circumstances, but it is possible to change the number of cursors by altering settings on the Set Options form or by using command line switches.One cursor for query is always opened for each block as needed and is never shared even when running in OPTIMIZETP=NO mode.
open cursors    (minimum)	• 1 per record group created with query.
	• 1 cursor is used if database date or time default values ($$DBDATE$$) are referenced for any item.
	• 1 for any SQL statement.These can be in triggers, procedures, or functions.  This restriction applies under normal circumstances, but it is possible to change the number of cursors by altering settings on the Set Options form or by using command line switches.  V2 style trigger cursor consumption can be tailored using the OPTIMIZESQL command line parameter.


Database Libraries dialog

The Database Libraries dialog 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.
OK	Performs the specified command (e.g. Open, Save) on the selected library.
Cancel	Cancels the current operation and closes the dialog.


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.


Performs the specified command on the selected library.


Cancels the current operation and closes the dialog.


New Program Unit dialog

The New Program Unit dialog allows you to specify a name and type of program unit to create.

Name	A text box where you type the name of the program unit.
Type	Specifies the type of program unit you will create.
OK	Accepts the settings you have specified and displays the PL/SQL editor with an initial specification for your program unit.
Cancel	Cancels the current operation and closes the dialog.


A text box where you type the name of the program unit.


Specifies the type of program unit you will create.


Accepts the settings you have specified and displays the PL/SQL editor with an initial specification for your program unit.


Cancels the current operation and closes the dialog.


Open Library dialog

The Open Library dialog 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	A text box where you type the name (and location) of the library you wish to open.
Find	If File System or Either is selected in the From field, displays your operating system file dialog.  If Database is selected in the From field, displays the Database Libraries dialog.
From	Indicates whether the library is stored on the file system or in the database.
OK	Confirms your selections, opens the library, and closes the dialog.
Cancel	Cancels the current operation and closes the dialog.


A text box where you 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.  If Database is selected in the From field, displays the Database Libraries dialog.


Indicates whether the library is stored on the file system or in the database.


Confirms your selections, opens the library, and closes the dialog.


Cancels the current operation and closes the dialog.


Attach Library dialog

The Attach Library dialog allows you to attach libraries to your current session, and provides a graphical user interface for the Interpreter's ATTACH command.

Library	A text box where you type the name (and location) of the library to attach.
Find	If File System or Either is selected in the From field, displays your operating system file dialog.  If Database is selected in the From field, displays the Database Libraries dialog.
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.
Cancel	Cancels the current operation and closes the dialog.


A text box where you 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.  If Database is selected in the From field, displays the Database Libraries dialog.


Indicates whether the library is stored on the file system or in the database.


Confirms your selections, attaches the library, and closes the dialog.


Cancels the current operation and closes the dialog.


Log Interpreter dialog

The Log Interpreter dialog allows you to manage logging activities and provides a graphical user interface for the Interpreter's LOG command.

File	A text box where you type the name of the file you want the logging session recorded in.
Find	Displays your operating system File dialog 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 is accepted.  You can also display the Interpreter Log browser by choosing View->Interpreter Log in the Interpreter.
OK	Confirms your selections and closes the dialog.
Cancel	Cancels the current operation and closes the dialog.


A text box where you type the name of the file you want the logging session recorded in.


Displays your operating system File dialog 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 is accepted.  You can also display the Interpreter Log browser by choosing View->Interpreter Log in the Interpreter.


Confirms your selections and closes the dialog.


Cancels the current operation and closes the dialog.


Interpreter Log browser

The 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.
Close	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.


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

The Connect dialog allows you to establish a connection to a database instance and provides a graphical user interface for the Interpreter's CONNECT command.

Username	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
	Note that each field is separated by a colon (:).  See your database administrator for the correct connect string for your database.
Connect	Confirms the information you have supplied and attempts a connection.  If the database connection is successful, the dialog closes.  If the database connection is not successful, an error is issued.
Cancel	Cancels the current operation and closes the dialog.


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 you wish to connect to.  This is generally in the form:


Confirms the information you have supplied and attempts a connection.  If the database connection is successful, the dialog closes.  If the database connection is not successful, an error is issued.


Cancels the current operation and closes the dialog.


Grant Access List dialog

The Grant Access List dialog allows you to view and modify access to the currently selected library, 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.  Click a username to place it in the User text box.
User	Type in the username that you wish to grant or revoke access to for the selected library.  This username must be valid username for the current database.  If the user already appears in the User list box, simply click the name.
Add	Adds the username to the list of those with GRANT access to the library.
Remove	Removes the username from the list of those with GRANT access to the library.
OK	Saves the actions performed on the current library, and closes the dialog.
Cancel	Cancels the current operation and closes the dialog.


Lists the users who currently have access to the selected library.  Click a username to place it in the User text box.


Type in the username that you wish to grant or revoke access to for the selected library.  This username must be valid username for the current database.  If the user already appears in the User list box, simply click the name.


Adds the username to the list of those with GRANT access to the library.


Removes the username from the list of those with GRANT access to the library.


Saves the actions performed on the current library, and closes the dialog.


Cancels the current operation and closes the dialog.


Save Library dialog

The Save Library dialog 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.
Find	If File System is selected in the To field, displays your operating system file dialog.  If Database is selected in the To field, displays the Database Libraries dialog.
To	Indicates whether the library will be saved on the file system or in the database.
OK	Confirms your selections, saves the library, and closes the dialog.
Cancel	Cancels the current operation and closes the dialog.


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.  If Database is selected in the To field, displays the Database Libraries dialog.


Indicates whether the library will be saved on the file system or in the database.


Confirms your selections, saves the library, and closes the dialog.


Cancels the current operation and closes the dialog.


Find & Replace dialog

The Find & Replace dialog allows you to search for and replace character strings or regular expressions in your program unit source.

Find	Type the string you want to find.  If you want this string to be treated as a regular expression, activate the Regular Expressions check box by clicking it.
Replace With	Type the string to replace any matches found.
Regular Expression	Specifies whether the search string should be treated as a regular expression or a string.  If this check box is not checked, the content of the Search text box is treated as 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	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).
Cancel	Cancels the current operation and closes the dialog.


Type the string you want to find.  If you want this string to be treated as a regular expression, activate the Regular Expressions check box by clicking it.


Type the string to replace any matches found.


Specifies whether the search string should be treated as a regular expression or a string.  If this check box is not checked, the content of the Search text box is treated as a string.


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.


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).


Cancels the current operation and closes the dialog.


Breakpoint dialog

The Breakpoint dialog allows you to create a breakpoint and provides a graphical user interface for the Interpreter's BREAK command.

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 where the breakpoint will be created.
Line	Identifies the source location of the breakpoint in the program unit.
Trigger	Type a breakpoint trigger that will fire when the breakpoint is hit.
OK	Confirms your selections, creates or modifies the breakpoint, and closes the dialog.
Cancel	Cancels the current operation and closes the dialog.


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 breakpoint will be created.


Identifies the source location of the breakpoint in the program unit.


Type a breakpoint trigger that will fire when the breakpoint is hit.


Confirms your selections, creates or modifies the breakpoint, and closes the dialog.


Cancels the current operation and closes the dialog.


Trigger dialog

The Trigger dialog allows you to create a debug trigger, and provides a graphical user interface for the Interpreter's 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 a 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 code to be used as the body of the debug trigger.
OK	Confirms your selections, creates or modifies the debug trigger and closes the dialog.
Cancel	Cancels the current operation and closes the dialog.


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 code to be used as the body of the debug trigger.


Confirms your selections, creates or modifies the debug trigger and closes the dialog.


Cancels the current operation and closes the dialog.


Step dialog

The Step dialog 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.

Step Mode	Specifies which Step option to use.
	INTO resumes execution until the next executable statemtent.
	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 remains displayed until you explicitly close it, or as long as there is an active debug level.
OK	Confirms your selections, resumes program unit execution accordingly,  and closes the dialog.
Cancel	Cancels the current operation and closes the dialog.


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 remains displayed until you explicitly close it, or as long as there is an active debug level.


Confirms your selections, resumes program unit execution accordingly,  and closes the dialog.


Cancels the current operation and closes the dialog.


Load Program Unit dialog

The Load Program Unit dialog 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.
Find	Displays your operating system file dialog.
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.
Cancel	Cancels the current operation and closes the dialog.


Type the name (and location) of the file containing the program unit source text.


Displays your operating system file dialog.


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.


Cancels the current operation and closes the dialog.


Interpret Debug Script dialog

The Interpret Debug Script dialog 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.
Find	Displays your operating system file dialog.
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.
Cancel	Cancels the current operation and closes the dialog.


Type the name (and location) of the file containing the debug script to be interpreted.


Displays your operating system file dialog.


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.


Cancels the current operation and closes the dialog.


Compile dialog

The Compile dialog displays compilation error messages during batch compilation and allows you to halt and resume compilation as well as navigate to 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.
Interrupt	Temporarily stops compilation—for example, when too many errors are being generated.
Resume	Resumes compilation after an interrupt.
OK	Closes the dialog after compilation has completed.
Cancel	Cancels the current operation and closes the dialog.
Goto Error	Presents the PL/SQL 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) an alert appears warning you that going to the source of an error will abandon the batch compilation.

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.

You can click on an error in the Compilation Errors pane to display the PL/SQL editor and the program unit where the error is located.

If you click an error in the Compilation Errors  pane while in an interrupted state of compilation (as a result of clicking Interrupt) an alert appears warning you that going to the source of an error will abandon the batch compilation.

You can click Goto Error to present the PL/SQL editor and the program unit that contains the first error in the Compilation Errors list box.


Specifies the following information while program units are being 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.


Closes the dialog after compilation has completed.


Cancels the current operation and closes the dialog.


Presents the Compilation Messages browser and displays the PL/SQL editor containing the program unit source at the location of the first error.


Closes the browser.


 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.

Two 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 use the escape character between brackets.  For example, if you enter [\*\+], * or + would match.
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 Row Selection Box

The PL/SQL Table Row Selection 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 listbox	A scrollable, mouse-sensitive area that contains a list of indexes to all rows in the currently-selected table.
OK	Confirms your selections, expands the selections in the Object Navigator, and closes the dialog.
Cancel	Cancels the current operation and closes the dialog.
Select All	Selects all elements in the currently-selected table.
Deselect All	Deselects all elements in the currently-selected table.
By default, all indexes are selected.  Clear individual selections by clicking on them in the list, or deselect all selections by clicking outside the list.  Then use your platform’s convention for sequential or non-sequential selections, as necessary, to choose the rows you want to examine.

The dialog remembers selections.  If you select certain rows to examine in one table and close the dialog or examine a second table, then return to the first table, your selections remain.


&


The PL/SQL Editor interface

Compile	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.
Apply	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.
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, where you can specify the type and name of the program unit you wish to create.
Delete	Deletes the displayed program unit, with confirmation.
Close	Attempts to close the editor.  If any changes have been made but not applied, an alert appears, prompting you to apply or revert the changes or cancel the operation.  Once all changes have been applied or reverted, the PL/SQL editor is closed.
Name	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.

In addition, the following elements make up the editor window:

Source pane	Used to enter and edit PL/SQL program unit source text.
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 offending source statement, and positions the text cursor at the location of the error. By default, the Compilation messages pane appears only when there are compilation error messages generated.  However, you can display the Compilation messages pane at any time by moving the split bar at the bottom right corner of the editor.
Split bar	Enables you to change the relative amount of space occupied by the two panes (source and compilation messages) in the PL/SQL editor.  Note that by default, the Messages compilation pane is displayed only when error messages are generated during compilation.
Status line	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, 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, an alert appears, prompting you to apply or revert the changes or cancel the operation.  Once all changes have been applied or reverted, the PL/SQL editor is closed.


Specifies the type of program unit (trigger, procedure, etc.) currently displayed in the editor.


Specifies what object the program is associated with.


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 PL/SQL Editor.  Note that by default, the Messages compilation pane is displayed only when error messages are generated during compilation.


The left side of the status line 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 line 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 print the current program unit, and you can use TAB/Shift-TAB to indent/outdent selected lines.


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.
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)


About form design goals

Before you design your application, consider these aspects of usability:

Productivity  The application must make the end-user more productive than the prior system they were using.  It should employ simple, easy-to-understand presentation of information.

Ease of Learning  The application must be easy to learn and intuitive to use.  The products must be consistent, familiar, and predictable.  There should be clear and obvious methods for novice users combined with quick and powerful methods for experts.

The User Experience  The application should be inviting to use.  It should reward a user by providing them with information and tools necessary to complete tasks rapidly, and it should guide them where appropriate with timely and meaningful feedback.  The application should allow exploration, without the fear of irreversible consequences.

At the same time, a balance must be struck between achieving the "ultimate UI", the time and resources required to build and maintain it, as well as the allocation of resources required to build basic product functionality.  A product with the best UI fails to meet any requirements if it is available too late, or does not satisfy business requirements.


Performing a requirements analysis

It is important to design a product user interface based on feedback from qualified users.  For example, design a journal entry screen based on comments from the general ledger clerks who will be using it regularly.  This seemingly simple concept is often overlooked, and UI designs instead are based on 'tests' done on the developer sitting in the next office.  Only the actual user of the product is qualified to comment if the UI is appropriate.

Be sure to sample a wide variety of users; feedback from users at a single customer site will be biased toward their specific implementation of the task.  Whenever possible get feedback based on actual 'hands-on' testing, rather than just paper prototypes.


Analyzing task flow

For every task that a product is designed to support, a flowchart should be built of the steps necessary to perform that task.  Only by identifying all the aspects of a particular task will opportunities for optimization be revealed.  Once the desired flow of a task is documented, analyze the following issues to lead to the proper UI for the screen(s) designed to support that task:

•	What related information is needed to complete the task?  What amount of information does the user need to ignore?

•	What is the frequency of use and volume of data for the screen?

•	What widgets are most appropriate?  Will the screen be used by high-speed data entry clerks?

•	What level of training do you anticipate the user having on this particular task and screen?

•	What if a user makes a mistake at a particular step, or attempts to bypass a step?  Must the task steps be done sequentially, or can they be done in parallel?

•	What decisions is the user required to make along the way?  What if those decisions are only in exceptional cases?

•	What other tools might the user be familiar with?  What are their expectations of your product based on these other tools?


About portability

 Examples	     Related Topics

Portability is the quest for uniformity in a diverse environment.  Ideally, portability means an application developed on one platform such as UNIX may be run on other platforms such as Microsoft Windows without changes.

In reality, the different ways that various platforms and windowing systems implement the basics that provide their distinctive "look and feel" mean that the distinguishing characteristics of one user interface  may appear differently on another user interface.  For example, the placement and presentation of the Help menu is different on Microsoft Windows, Macintosh, and Motif.


Designing for portability

  Related Topics

Restrictions imposed by supporting all platforms and translation requirements must be evaluated early in the design phase.

If an application is going to be deployed in multiple environments, it should conform to all of the constraints for all of those environments. If it is going to be deployed only in a single environment, the application only needs to conform to the constraints for that environment.  Additionally, even a product that is designed to run on all platforms may have additional logic that only gets invoked on specific platforms.  It is up to you as the designer to ensure that your application performs as expected on all platforms on which it is intended to be run.


About portability examples

•	Platform portability: the ability to deploy the same application across platforms.

Example Develop on UNIX, deploy on Microsoft Windows and Macintosh.

•	Device portability (including variations in screen size and resolution, as well as monochrome/color differences):  the ability to develop and deploy on the same platform, but different devices.

Example Develop on Microsoft Windows, deploy on both Microsoft Windows large screen, high resolution and Microsoft Windows small screen, low resolution.

•	UI portability:  the ability to deploy the same application on GUI and character-mode devices.

Example  Develop on Microsoft Windows, deploy on Microsoft Windows and a VT220.


About the porting process

  Related Topics

The general process for creating portable applications includes these stages:

1	Create standards for the application to ensure a similar "look and feel" both within the application and across platforms.

2	Create the application on the base platform.

3	Copy, re-compile, and run on the target platform, testing for any areas where adjustment is needed for optimum appearance.

When an application is ported, it will be able to run directly on the target platform.  The Toolkit level on which Form Builder is built will render all widgets with the native look-and-feel of the target platform.

However, because of platform-to-platform differences, some minor changes may have to be made to the original source code so that it meets the requirements on both the original and the target platform.

4	In Form Builder, fine-tune the base-platform application.


Platform-Specific Functionality

Platform-specific functionality may be coded on forms that run on multiple platforms, provided that the basic business requirements of the product are met on all platforms.  For example, an HR product may build a textual editor to maintain management hierarchies, which executes on all platforms, and augment this with a graphical one on a specific platform.

However, despite the availability of some capability on a particular platform, using it might be inappropriate in some contexts.  For example, in a screen designed for heads-down data entry, it would be incorrect to use any widget which cannot be operated without looking at the screen.


Platform-Specific Characteristics

There are basic incompatibilities among all the supported UIs, such as widget placement and size.  Where such inconsistencies exist, and are not easily resolved, these standards follow the model recommended on Microsoft Windows.

Many display characteristics of widgets can be accounted for with a scheme of referenced property classes that insure the proper look on all platforms.  However, it is the responsibility of the developer to write standard code to account for some behavioral characteristics.  For example, on the Macintosh a user cannot navigate to any widget other than a text item.


Screen Characteristics

In general, the maximum recommended window size is 7.8" (width) x 5.0" (height).  This maximum size comes from the requirement to support character mode.  If the product or form being built does not need to run in character mode, then it may be able to assume a larger screen size and thus a larger window size.

To support various screen resolutions on bitmap monitors, forms should be built with coordinate systems based on logical, not physical, measures.  For that reason, lay out all screens in inches.

Finally, in order to support monochrome screens and users who are color blind, any use of color coding must only be used to augment.  For example, a financials total may be rendered in red if negative, but should also be drawn such that it is readable without the aid of color (such as with a negative sign preceding the value).


Character-Mode Issues

Character mode restricts the UI in several ways:

•	Fonts are monospaced and thus consume much more space, on average, than proportional fonts.  Screens must be designed so that boilerplate and textual widgets can be rendered with one character per cell.

•	Most objects must be laid out snapped to the character cell grid, including boilerplate (prompts and lines) and widgets (text items, check boxes, etc.)

•	Each widget must be operable from the keyboard, including when it does not have the focus.

•	All screens must fit in a character cell grid of 80 x 24 characters.

•	Anything that requires scrolling is very hard to use.

•	Iconic buttons should be hidden, thus any functionality they provide must either not be needed in character mode, or must have an alternative invocation method (such as the Special menu).

•	Encoding of data with font or color variations can only be used as a secondary method to present such information.

Products or screens that do not need to run in character mode are not bound by these limitations, although often a GUI form is easier to develop, and more usable, if many of them are followed.  For example, design a screen so that it is fully operable from the keyboard, whether it is to be run in character mode or not.


Resource Issues for Microsoft Windows

In order to manage system resource usage when running on Microsoft Windows, it may be necessary to deviate from the standards slightly in order to reduce the number of widgets created.

For very large forms that may cause severe resource problems, the following guidelines and suggestions can also be used to lower resource usage:

•	Have certain commands available as entries on the Special menu rather than as buttons on the form.

•	Change horizontal scrolling areas into alternative regions showing only a subset of the columns at a time.

•	Reduce the number of windows by using multiple alternative regions in one window or by improving the window flow.

•	Display multiple rows of certain information (primary key and descriptor fields) and one row of less important information by using overflow regions or combination blocks.


Translation

In order for a product to run in the proper language in all countries, all prompts, titles, messages, and information presented to the user, other than data they enter while using the product, must be translatable.  The Oracle Translation Manager handles most aspects of this, except for messages, which are handled by the Message Dictionary.  All text must be presented to a user in their native language, except critical errors which a developer needs to debug the application (and should never be seen by a user).

Anything that is translated must have sufficient space available to expand 30% when translated from English to other languages.  Depending on the widget and its placement, this space must be available either to the left, right, or both sides.  Note that this 30% expansion rule applies to the number of character cells, not inches, unless the form does not need to run in character mode.  In addition, unless the translated lengths are known ahead of time, all prompts should have a minimum of one inch total space available in which to expand when translated.

Numeric data and dates must also be presented to the user in their proper format for the current language.


Understanding the user's perception of information

Window layouts should be based on the logical relation of data, not the physical database tables.  For example, in the Sales and Marketing product, a user perceives an 'Account' as the specific data of the Account, as well as the 'Contacts' and 'Executives' of that account.  These three entities are stored in separate physical tables, but by placing them all in a single set of windows, the user continues to perceive them as one logical object.

Note:  Form Builder will ask the user to save changes when a new master record is selected and changes are pending in the detail block.  This breaks the unity of both a logical object and a transaction by exposing the block- and record-level properties of each, but was judged to be infeasible to circumvent.


Choosing summary versus detail

Placing information in a window always involves a compromise between the desire to see many records of an entity simultaneously, and to see all of the detail about each record at once.  A summary view has the advantage of showing more records of an entity, but at the loss of detailed information about each record.  A careful analysis must be done to determine the best compromise of rows and detail for each function.  Often a hybrid of the two views is the best answer.


Avoiding information clutter

There is no such thing as information overload - a user can never see too much information.  However, if information is not well organized, then it simply becomes clutter.  Presenting an entity with a large number of attributes merely as a 'sea' of fields would force the user to scan an entire screen to locate the piece of information they are interested in.  Instead, carefully organize and group the data to allow a user to navigate the information more easily and naturally.


Understanding information visibility

An analysis of the task flows should reveal what information a user must have access to at each point in time.  For example, if a user must see Set of Books information in order to enter a Journal, a decision must be made as to whether the Set of Books information must be visible at all times, or the user merely needs the ability to see it upon request.  This in turn impacts how much of each entity should be displayed at once, and how many windows are necessary.


General layout rules

  Related Topics

The following rules apply to all screens.  Specific exceptions are noted throughout this document.

•	Orient screen layouts based on a top-to-bottom task sequence.  Blocks, regions, and items are arranged by order of precedence, from left-to-right, then top-to-bottom.

•	Don't waste screen space.  Make windows only as large as is necessary.  Use blank space as a way to group information.

•	Most widgets are 0.25 inches high, and multiples of 0.1 inches wide.  Two-dimensional widgets (multiline text items, TLists) are multiples of 0.25 inches high.  Textual button heights differ depending on the platform.

•	In single-record blocks, items should be left aligned where possible.  In multi-record blocks items should be stacked horizontally and aligned along their top.

•	Place titles and prompts toward the top or left of the element they are describing.  Prompts in single-record blocks are always to the left of the field; prompts in multi-record blocks are above the field, and aligned similarly to the data within the field they describe.  Exceptional cases exist for matrix-style layouts, fields that do not require prompts, connecting prompts, and multiline prompts.

•	At least a one-character wide space should be left between the items on a canvas and the window frame.  It is also preferable to leave one row at the top and bottom empty too, but this is not required.  Exceptional cases exist for lines and rectangles used to denote blocks and regions.

•	Indicate things that are similar, and things that are different, when it is meaningful for the user.  That is, do not create regions or use boilerplate lines to group items unless it improves the usability of the screen.

•	Make data stand out, and controls to access that data intuitive but non-obtrusive.

•	Use the same widget for the same attribute in all windows.


About building forms

  Related Topics

So, how do you get from beginning a form to a finished application, ready for operators to run?  Here's the basic process:

1	Create modules.

2	Create blocks and items.

3	Apply user interface standards to your objects.

4	Fine-tune the layout.

5	Set properties.

6	Add code.

7	Test your application.

To do this:	Use this Form Builder tool:
Create modules.	Object Navigator
Create blocks and items.	Data Block Wizard
Apply standards.	Object Library
Fine-tune the layout.	Layout Wizard or Layout Editor
Set properties.	Property Palette
Add code.	PL/SQL Editor
Test the form.	Forms Runtime Debugger


About blocks on forms

  Related Topics

A block is a container that holds a related group of objects, such as text items, lists, and buttons.

Blocks do not have a physical representation—only the items contained in a block are visible in the application interface. However, like other objects, blocks have properties, and can be created, copied, and modified.

Blocks provide a mechanism for grouping related items into a functional unit for storing, displaying, and manipulating records.  Just as tables in the database consist of related columns and rows, blocks contain related items that display data.

There is no practical limit to the number of blocks that can be defined in a form. A block is a logical grouping only;  the items in a block can be placed on different canvases and can be displayed in different windows.


About block types

  Related Topics

There are two types of blocks, data and control.

Data Block	Data blocks are associated with data (table columns) within a database.

By default, the association between a data block and the database allows operators to automatically query, update, insert, and delete rows within a database.

Data blocks can be based on database tables, views, procedures, or transactional triggers.

Control Block	In contrast, a control block is not associated with the database, and the items in a control block do not relate to table columns within a database.

All blocks are either single-record or multi-record blocks:

•	A single-record block displays one record at a time.

•	A multi-record block displays more than one record at a time.

In addition, a data block can also be a master or detail block:

•	A master block displays a master record associated with detail records displayed in a detail block.

•	A detail block displays detail records associated with a master record displayed in master block.


Block datasources

  Related Topics

A data block can be based on any of the following datasources:

•	table

•	view

•	FROM clause (query datasource only)

•	procedure

•	transactional trigger


Guidelines for choosing block datasources

  Related Topics

When deciding on a block datasource, consider the requirements:

•	Will the block be used only to query records?

•	Will the block be used to perform INSERTS, UPDATES, and DELETES (DML)?

•	Will the block be used to perform both query and DML?

A table is the most commonly used block datasource.  Unless you have special needs, a table is the best choice for a block datasource.

Consider also the functional restrictions for each datasource type.

Datasource	Allows Query	Allows DML (INSERTS, UPDATES, and DELETES	Allows Array Processing	Allows Query by  Example
Table	yes	yes	yes	yes
View	yes	yes (certain Join views may not allow DML)	yes	yes
FROM clause	yes	no	yes (only for queried records)	no
Procedure	yes	no (if your procedure uses a ref cursor variable)	no (if your procedure uses a table of records)	no
Transactional trigger	yes	yes	no (if your trigger uses a table of records)	no

Note: You can specify separate query and DML datasources for a data block.


Using tables as block datasources

  Related Topics

A table is the most commonly used block datasource.  Unless you have special needs, a table is the best choice for a block datasource.

A data block that is based on a table allows the end-user to:

•	query records

•	INSERT, UPDATE, and DELETE records

•	query by example

A data block based on a table, also reduces network traffic through array processing.

The Query Array Size property enables array processing for records queried, and the DML Array Size property enables array processing for records used in DML operations.


Using transactional triggers as block datasources

  Related Topics

Transactional triggers may be used to provide data for data blocks.  Transactional triggers are typically used when Form Builder is running against a non-ORACLE datasource.  When transactional triggers are used, Form Builder default functionality is replaced.

A transactional trigger block datasource can be used for both query and DML.  Array processing is not supported when the block datasource is based on a transactional trigger.


Using stored procedures as block datasources

  Related Topics

Using a stored procedure as a block datasource is a more advanced option.  Base a data block on a stored procedure when you want to:

•	increase control and security

•	query and update multiple tables

•	perform complex computations

•	perform validation and DML on the server-side

•	encapsulate logic within a subprogram

•	reduce network traffic through array processing

A stored procedure returns data to a data block by using either a ref cursor or a table of records.


About ref cursors

  Related Topics

A ref cursor is a pointer to a server-side cursor variable.  It is analogous to a pointer in "C" in that it is an address to a location in memory.  The stored procedure returns a reference to a cursor that is open and populated by a SELECT statement to be used as a block datasource.

A stored procedure that uses a reference cursor can only be used as a query block datasource; it cannot be used for DML block datasource.  Using a ref cursor is ideal for queries that are dependent only on variations in SQL statements and not PL/SQL.

When deciding whether to use a ref cursor or a table of records, consider that:

•	a stored procedure that uses a ref cursor can only be used as a query block datasource

•	a stored procedure that uses a table of records can be used as both a query and DML block datasource


About table of records

  Related Topics

A table of records is a PL/SQL structure that resembles an array of records.  The stored procedure constructs the array and passes back the resulting set of records to be used as a block datasource.

Using a table of records is ideal for queries that are dependent on PL/SQL and SQL.

Using a table of records is extremely efficient in terms of the savings on network traffic, because it takes a single round trip (from client to server) to execute the stored procedure, and a single round trip for all the records returned.

Array processing is not an option when a data block is based on a stored procedure returning a table of records.  Instead, a single array is used in query and DML operations.  The size of the array is the number of records that are processed for the entire operation.  For instance, a query of 300 records will return a single array that is 300 records in size.

Because array processing cannot be used, additional records may be returned that are unnecessary.  A lot of memory may be required, because all records are in memory at the same time.  When using a table of records, anticipate the memory requirements when designing your application.  You can limit memory usage, by controlling the size of the array in your stored procedure.

When deciding whether to use a ref cursor or a table of records, consider that:

•	a stored procedure that uses a ref cursor can only be used as a query block datasource

•	a stored procedure that uses a table of records can be used as both a query and DML block datasource


Using the FROM clause as a block datasource

  Related Topics

A FROM clause may be used as the datasource for a data block.  A FROM clause is a feature of the Oracle8 Server that allows you to nest a SELECT statement in the FROM clause of a SELECT statement.  A FROM clause is a valid query block datasource, but it is not a valid DML block datasource.  The value returned from a FROM clause is a subset of records from the original query.

FROM clauses are used to perform joins, lookups, and calculations without having to create a view on the server.  FROM clauses can also be used to prototype views and to increase performance.

Using a FROM clause as a block datasource is similar to using an updateable join-view as a block datasource.  However, a FROM clause provides more control, because the presence of a DBA is not required to define the view.  You should note that the FROM clause produces results that are identical to an updateable join-view from the client side, but that there is no defined view on the server.

Array processing is supported to increase performance by reducing network traffic.  Set the Query Array Size property to enable array processing.


Creating a data block from a table

  Next Step	    Related Topics

To create a data block from a table:

Choose Tools [image] Data Block Wizard to invoke a wizard that guides you through the process of building a data block.

Or,

1	In the Object Navigator, click the Data Blocks node.

2	Click the Create button [image] in the toolbar.

3	In the New Data Block dialog box, choose Build a New Data Block Manually and click OK.

4	Double-click the Block object icon [image] to display the Property Palette.

5	Under the Database node:

•	Set the Query Data Source Type property to Table.

•	Type the name of a database table in the Query Data Source Name text box.

6	Under the Advanced Database node:

•	Set the DML Data Target Type property to Table.

•	Type the name of your datasource in the DML Data Target Name text box.

7	Under the General node, click the Name property, then type a name or accept the default name.

You can use any name that follows ORACLE naming conventions and is unique among blocks in the form. The block name is an internal descriptor that is not displayed at runtime.


Creating a data block from a transactional trigger

  Related Topics

To create a data block from a transactional trigger:

Choose Tools [image] Data Block Wizard to invoke a wizard that guides you through the process of building a data block.

Or,

1	In the Object Navigator, click the Data Blocks node.

2	Click the Create button [image] in the toolbar.

3	In the New Data Block dialog, choose Build a New Data Block Manually and click OK.

4	Double-click the Block object icon [image] to display the Property Palette.

5	Under the Database node, set the Query Data Source Type property to Transactional Triggers.

6	Define the appropriate transactional triggers.

7	Under the Advanced Database node, set the DML Data Target Type property to Transactional Triggers.

8	Define the appropriate transactional triggers.

9	Under the General node, click the Name property, then type a name or accept the default name.

You can use any name that follows ORACLE naming conventions and is unique among blocks in the form. The block name is an internal descriptor that is not displayed at runtime.


Creating a data block from a procedure that uses a ref cursor

 Examples	   Restrictions	    Related Topics

To create a data block from a procedure that uses a ref cursor:

Choose Tools [image] Data Block Wizard to invoke a wizard that guides you through the process of building a data block.

Or,

1	In the Object Navigator, click the Data Blocks node.

2	Click the Create button [image] in the toolbar.

3	In the New Data Block dialog box, choose Build a New Data Block Manually and click OK.

4	Double-click the Block object icon [image] to display the Property Palette.

5	Under the Database node:

•	Set the Query Data Source Type property to Procedure.

•	Type the name of a procedure in the Query Data Source Name text box.

•	Type the name of a procedure in the Query Data Source Name text box.

•	Double-click the Query Data Source Columns property and in the Query Data Source Columns dialog box, type in the column names, type, length, precision, and scale for the result set returned from the ref cursor.

•	Double-click the Query Data Source Arguments property and in the Query Data Source Arguments dialog box, type in the names, data types, mode, and value for the arguments passed to and from the procedure.

6	Under the General node, click the Name property, then type a name or accept the default name.

You can use any name that follows ORACLE naming conventions and is unique among blocks in the form. The block name is an internal descriptor that is not displayed at runtime.


Creating a data block from a procedure that uses a ref cursor restrictions

•	If the query datasource of a block is a stored procedure returning a cursor variable, and the block is a detail block in a relation, only the isolated deletes option is supported.  Non-isolated deletes and cascading deletes cannot be supported, because the appropriate SQL statements cannot be constructed (cursors are a single active set of records resulting from a single select statement that is issued).  To enforce non-isolated deletes and cascading deletes, provide checks in the ON-DELETE  or PRE-DELETE triggers.

•	Count Query Hits is disabled when using stored procedures as a datasource.  An error message occurs if you attempt to count query hits at runtime.  Instead, you can use the ON-COUNT trigger to count the query hits.

•	You cannot pass a WHERE or ORDER BY clause to a stored procedure.


Creating a data block from a procedure that uses a ref cursor examples

/*

This is an example of a stored procedure that returns a ref cursor as a block datasource.  A package is used to logically group the related data types and procedures.
*/
PACKAGE cv_datasource IS
TYPE emprec is RECORD (empno  emp.empno%TYPE,
         ename  emp.ename%TYPE,
         job    emp.job%TYPE,
         mgr    emp.mgr%TYPE,
         sal    emp.sal%TYPE,
         comm   emp.comm%TYPE,
         deptno emp.deptno%TYPE);
TYPE empcur is REF CURSOR RETURN emprec;
PROCEDURE empquery(resultset  IN OUT empcur,
         p_deptno  IN NUMBER);
END;

PACKAGE BODY cv_datasource IS
    PROCEDURE empquery(resultset IN OUT empcur,
            p_deptno  IN NUMBER) IS;
    BEGIN
      OPEN resultset FOR
      SELECT empno, ename, job, mgr, sal, comm, deptno
      FROM emp
      WHERE deptno = p_deptno
      ORDER BY empno;
    END;
END;


Creating a data block from a procedure that uses a table of records

 Restrictions	    Related Topics

To create a data block from a procedure that uses a table of records:

Choose Tools [image] Data Block Wizard to invoke a wizard that guides you through the process of building a data block.

Or,

1	In the Object Navigator, click the Data Blocks node.

2	Click the Create button [image] in the toolbar.

3	In the New Data Block dialog box, choose Build a New Data Block Manually and click OK.

4	Double-click the Block object icon [image] to display the Property Palette.

5	Under the Database node:

•	Set the Query Data Source Type property to Procedure.

•	Type the name of a database procedure in the Query Procedure Name text box.

•	Double-click the Query Data Source Columns property.  Then in the Query Data Source Columns dialog box, type in the column names, type, length, precision, and scale for the result set returned from the table of records.

•	Double-click the Query Data Source Arguments property.  Then in the Query Data Source Arguments dialog box, type in the name, data types, mode, and value for the arguments passed to and from the procedure.

6	Under the Advanced Database node:

•	Set the DML Data Target Type property to Procedure.

•	If you are performing an INSERT from your procedure, type the name of the procedure in the Insert Procedure Name text box, double-click the Insert Procedure Result Set Columns property to provide the result set information (name, type, length, precision, and scale), and double-click the Insert Procedure Arguments property to provide the argument information (name, data type, mode, value).

•	If you are performing an UPDATE from your procedure, type the name of the procedure in the Update Procedure Name text box, double-click the Update Procedure Result Set Columns property to provide the result set information (name, type, length, precision, and scale), and double-click the Update Procedure Arguments property to provide the argument information (name, data type, mode, value).

•	If you are performing a DELETE from your procedure, type the name of the procedure in the Delete Procedure Name text box, double-click the Delete Procedure Result Set Columns property to provide the result set information (name, type, length, precision, and scale), and double-click the Delete Procedure Arguments property to provide the argument information (name, data type, mode, value).

•	If you are performing a LOCK from your procedure, type the name of the procedure in the Lock Procedure Name text box, double-click on the Lock Procedure Result Set Columns property to provide the result set information (name, type, length, precision, and scale), and double-click the Lock Procedure Arguments property to provide the argument information (name, data type, mode, value).

7	Under the General node, click the Name property, then type a name or accept the default name.

You can use any name that follows ORACLE naming conventions and is unique among blocks in the form. The block name is an internal descriptor that is not displayed at runtime.


Creating a data block from a procedure that uses a table of records restrictions

•	In a block based on a stored procedure performing an UPDATE, always reference the same columns in both the procedure and the block.  Do not pass back values from the procedure or function that you do not use as database items in your form.  If the procedure or function returns more columns than those used in the block, the procedure or function returns null values for the columns that are not used.

•	Because Update Changed Columns is not supported with procedures or functions as block datasources, the procedure or function should always pass back all the column values (Updated Changed Columns specifies that only columns whose values have changed are included in the UPDATE statement).  It is impossible to determine whether a null value passed to procedure or function is an unused column in the block or an intentional null value for a column that is used.  If you do not have a procedure or function that requires you to pass back all the column values, you will not be able to set a column to a null value in an UPDATE statement.

•	Count Query Hits is disabled when using stored procedures as a datasource.  An error message occurs if you attempt to count query hits at runtime.  Instead, you can use the ON-COUNT trigger to count the query hits.

•	You cannot pass a WHERE or ORDER BY clause to a stored procedure.


Creating a data block from a FROM clause

  Related Topics

To create a data block from a procedure returning a table of records:

Choose Tools [image] Data Block Wizard to invoke a wizard that guides you through the process of building a data block.

Or,

1	In the Object Navigator, click the Data Blocks node.

2	Click the Create button [image] in the toolbar.

3	In the New Data Block dialog, choose Build a New Data Block Manually and click OK.

4	Double-click the Block object icon [image] to display the Property Palette.

5	Under the Database node:

•	Set the Query Data Source Type property to FROM clause.

•	Type the a SELECT statement (sub-query) in the Query Data Source Name text box.

6	Under the General node, click the Name property, then type a name or accept the default name.

You can use any name that follows ORACLE naming conventions and is unique among blocks in the form. The block name is an internal descriptor that is not displayed at runtime.


Creating a control block

  Next Step	    Related Topics

To create a control block:

1	In the Object Navigator, click the Data Blocks node.

2	Click the Create button [image] in the toolbar.

3	In the New Data Block dialog box, choose Build a New Data Block Manually and click OK.

4	Double-click the Block object icon [image] to display the Property Palette.

5	Under the General node, click the Name property, then type a name or accept the default name.

You can use any name that follows ORACLE naming conventions and is unique among blocks in the form.  The block name is an internal descriptor that is not displayed at runtime.


About multi-record blocks

  Related Topics

A multi-record block displays multiple instances of each block item.

For example, when the Number of Records Displayed property is set to 3, Form Builder displays three instances of each item in the block—one instance for each record the block can potentially display. You can specify that an item in the block display fewer records by setting the Number of Items Displayed item property.


Creating a multi-record block

  Related Topics

To create a multi-record block:

1	In the Object Navigator, click the Data Blocks node.

2	Double-click the desired block object icon [image] to display the Property Palette.

3	Under the Records node, set the Number of Records Displayed property to the desired number of records.

Note: The default is 1.  Setting Records Displayed greater than 1 makes the block a multi-record block.


Deleting a block

To delete a block:

1	In the Object Navigator, click the desired block object icon.

2	Choose Navigator [image] Delete.

Deleting a block also deletes the items the block contains, and any triggers that were attached to the block or to its items.  If the block was a master or detail block in a relation, the relation is also deleted.


About scroll bars

  Related Topics

The scroll bar is separate from the items in the block, and can be placed anywhere on any canvas in the form.

In the Layout Editor, you can move and resize the scroll bar and set its color and pattern attributes.  You cannot, however, Cut, Copy, Delete, or Duplicate a scroll bar in the Layout Editor.


Deleting a block scroll bar

To delete a scroll bar:

1	In the Layout Editor, double-click the scroll bar to display the Property Palette.

2	Set the Show Scroll Bar block property to No.


Scroll Bar interaction at runtime

The position of the scroll bar thumb in the scroll bar alley gives visual feedback to the operator about the relative position of the current record within the block's current record set.

Note, however, that in the case of a query, the scroll bar thumb indicates the position of the current record within the set of records that have been fetched so far.  This may or may not include all records that match the query criteria.

For example, if 100 records match the query criteria but only 10 records are being fetched at a time, moving the scroll bar thumb to the bottom of the scroll bar alley would display the 10th record, not the 100th.  Moving the scroll bar down again causes Form Builder to fetch the next set of 10 records.

Note:  You can override the default array fetch mechanism for a block by calling the EXECUTE_QUERY built-in with the ALL_RECORDS parameter.  Doing so, however, is not recommended when the set of records is likely to be large.


Creating a block scroll bar

  Related Topics

To create a block scroll bar:

1	In the Object Navigator, double-click the Block object icon [image] for the desired block to display the Property Palette.

2	Under the Scroll bar node:

•	Set the Show Scroll Bar block property to Yes.

•	Set the Scroll Bar Canvas property to specify on which canvas the scroll bar should be displayed.


Connecting to a database

To connect to an Oracle database:

1	Choose File [image] Connect.

2	In the Connect dialog box:

•	Type your user name, password, and database name.

•	Click Connect.

When a connection to the database is made successfully, the status bar displays the Connect lamp: <Con>.


About Items

  Related Topics

Items are the interface objects that display information to operators and allow them to interact with your application.

Each item in a form (text item, image item, radio group, and so on), belongs to a block.

Form Builder supports several types of interface items that can be used to build an application's interface.

ActiveX control	A custom control that simplifies the building and enhancing of user interfaces.

Bean area	An identification of a JavaBean that supplies a control for this item.

chart item	A bordered rectangle of any size that can display a chart or other display generated by Graphics Builder.  Operators cannot navigate to or manipulate chart items.

check box	A text label with a graphic state indicator that displays the current value as either checked or unchecked.  Clicking on a check box toggles it to the opposite state.

display item	A read-only text box whose value must be fetched or assigned programmatically.  Operators cannot navigate to a display item or edit the text it contains.

heirarchical tree item	An area which displays grouped data in the form of a standard navigator with expandable nodes.

image item	A bordered rectangle of any size that can display images fetched from the database or read in from the file system.

list item	A list of choices displayed as either a drop-down list, a list box, or a combo box.

OLE container	An area that stores and displays an OLE object that is created from an OLE server application.

push button	A rectangle with a text label or an icon graphic inside.

radio group	A group of radio buttons, one of which is always selected.

sound item	Sound items allow the user to load, record, edit, play, and save sounds.

text item	A single- or multi-line text box that supports a variety of data types, format masks, and editing capabilities.

User area	An area that stores and displays a user-defined item.

VBX control 	For use only in Microsoft Windows 3.1.


About data and control items

  Related Topics

Data items correspond to table columns within the database.  By manipulating a data item (a text item, for example), the operator can automatically affect data that is in the database.

Control items do not have any association with the database.  When the operator manipulates a control item, data within the database is not affected unless the appropriate SQL statements are provided.  In general, control items allow the operator to perform common application functions, such as navigating from one screen to another, and do not allow operators to modify database data.

Control items can also be used to do the following:

•	Display totals, averages, rankings, and other summary information calculated from values in data items and database tables.

•	Accept input from operators that is required by the application, but that is not stored in the database.

•	Display  "look-up values," that is, database values derived from a  different table.

When building a block, consider this:

•	data blocks can contain both data items and control items

For example, a data block might contain four data items that display queried database values and a fifth item that displays calculated values but does not correspond to any column in the database.  The fifth item would be a control item populated by an assignment statement in the trigger that does the calculation.

•	control blocks cannot contain data items

Because control blocks are not associated with the database, none of the items they contain can be data items.  (Control items may be populated with database values by writing SQL statements in trigger code.)

•	buttons and chart items are always control items

Because buttons and chart items do not store values, they cannot relate to columns in the database, and are always control items.

•	the values of control items may be referenced in code, in the same fashion as local and global variables.


About creating items

  Related Topics

Once you create a data or control block, you can create items in that block at any time.  Create items via the Object Navigator by inserting them under the desired block, or via the Layout Editor by drawing them on the desired canvas.

Keep in mind that a block is a logical, not a physical, container for items.  The items in a block can be arranged in any layout and can be displayed on any canvas.

Before creating an item, decide in which block the item should be, and whether the item will be a data or a control item.

Creating Items in Data Blocks

When an item is created in a data block, Form Builder assumes the item is a data item, and sets its Database Item property to Yes.  Data items are automatically included in any SELECT, UPDATE, and INSERT statements issued to the database.

If the new item created is a control item in a data block, its Database Item property must be explicitly set to No.

Creating Items in Control Blocks

When an item is created in a control block, that item is always a control item, regardless of how the item's Database Item property is set.  (Because a control block is not associated with a database table, none of the items in a control block can be data items.)


Creating a data item

  Next Step	    Related Topics

To create a data item:

Choose Tools [image] Data Block Wizard to invoke a wizard that guides you through the process of creating a data item.

Or,

1	In the Object Navigator, click the plus icon [image] beside the desired Data Blocks node.

Form Builder expands the Data Blocks node and displays its subnodes.

2	Click the plus icon [image] beside the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon beside the newly created item to display the Property Palette.

5	Under the General node:

•	Set the Name property to the name of the desired database column.

•	Set the new item's Type property to specify the type of item you want.

The default item type is text item.  You can change the default by setting the Type property to the item type desired (check box, radio group, list item, and so on).

6	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign each interface item in a form to a canvas.


Creating a control item

  Next Step	    Related Topics

To create a control item:

1	In the Object Navigator, click the plus icon [image] beside the desired Data Blocks node.

Form Builder expands the Data Blocks node and displays its subnodes.

2	Click the plus icon [image] beside the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon beside the newly created item to display the Property Palette.

5	Under the Database node:

•	Set the Database Item property to No.

Note: When you create an item in a data block, Form Builder assumes the item is a data item, and sets the Database Item property to Yes.  Data items are automatically included in any SELECT, UPDATE, and INSERT statements issued to the database.  If the item being created is a control item in a data block, you must explicitly set its Database Item property to No.

•	Set the Type property to specify the type of item you want.

The default item type is text item.  You can change the default by setting the Type property to the item type desired (check box, radio group, list item, and so on).

6	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign each interface item in a form to a canvas.


About Layout Editor Block Context

  Related Topics

Each Layout Editor window maintains block context that identifies the current block for item operations. The name of the current block is displayed in parentheses on the title bar of the Layout Editor window.

Block context affects item operations as follows:

•	Items that you create in the Layout Editor are automatically assigned to the current block.

•	Items that are selected when you issue the Set Block command are re-assigned to the new block.


Setting Layout Editor block context

  Related Topics

To change block context within the Layout Editor:

1	In the Layout Editor, choose a block from the Block drop-down located in the upper region of the Layout Editor.

2	Click the drop-down list box to display a list of all blocks.


About assigning items to canvases

  Related Topics

Canvases are displayed in windows at runtime; the canvas to which an item is assigned determines the window in which the item will be displayed.  When an item is created by drawing it in the Layout Editor, that item is automatically assigned to the Layout Editor's current canvas.  To display an item at runtime, assign each interface item in a form to a canvas by setting the item's Canvas property.

When the Canvas property for an item is left unspecified, that item is said to be a NULL-canvas item.  NULL-canvas items are not displayed at runtime or in the Layout Editor at design time.  You can use NULL-canvas items programmatically as variables, by assigning and referencing their values in PL/SQL code using :block_name.item_name syntax.

To make an item a NULL-canvas item, simply leave its Canvas property blank.


Changing the canvas assignment of an item

To change the canvas assignment of an item:

•	In the Property Palette, set the item's Canvas property to the name of the desired canvas.  The canvas specified must already be defined in the current form.

- Or -

•	In a Layout Editor, Cut the desired item, then Paste it to a different canvas in another Layout Editor window.

- Or -

•	In the Object Navigator, choose Navigator [image] Visual View to display the form hierarchy in the Visual View.  In Visual View, items appear under the canvas to which they are assigned, and no blocks are displayed.  Click the item which will be changed, and use the mouse to drag an item to a different canvas.


Converting an item to a different type

  Next Step	    Related Topics

To convert an item to a different item type:

1	In the Object Navigator or the Layout Editor, double-click the item you want to convert to display the Property Palette.

2	Under the General node, set the Type property to the desired item type.

When an item is converted to a different item type, the properties of the new item are set as follows:

•	Properties that apply only to the new item type are set to the default settings for that item type.

•	Properties that are common to both the original item type and the new item type retain their current settings.

For example, when you convert a text item to a check box, the Label property (which applies only to check box items) is set to the default setting, but the Data Type property (which applies to both text items and check boxes) retains its current setting.


About number of items displayed within a block

  Related Topics

You can set the Number of Items Displayed item property to specify the number of records an item in a multi-record block should display.  For example, a multi-record block with its Number of Records Displayed property set to 3 might include four multi-record text items and one single-record image item. Or, you might create a single button in a multi-record data block.


Specifying the number of items displayed within a block

  Related Topics

To specify the number of records an item should display:

1	Double-click the desired item in the Object Navigator or in the Layout Editor to display the Property Palette.

2	Under the Records node, set the Number of Items Displayed property to specify the number of records the item should display.

•	To display the number of records indicated by the block's Number of Records Displayed property setting, set Number of Items Displayed to 0 (the default).

•	To display fewer records, set Number of Items Displayed to a number less than the block's Number of Records Displayed property setting, but greater than 0.

Number of Items Displayed cannot be set greater than the block's Number of Records Displayed property setting.


Changing the space between items in a multi-record block

  Related Topics

To change the space between items:

1	In the Layout Editor, select the desired item.

Special spacing handles are displayed in the middle of the top and bottom of the item's bounding box.

2	Click and drag one of the spacing handles up or down.

When the Grid Snap option on the View menu is enabled, the amount of space between each item instance must be at least as large as the distance between snap points defined for the current grid.

If you are working in character cell ruler units, the amount of space between item instances must be at least as large as the height of a single cell.  Thus, to increase the space between records in a 5 record item, you must drag the appropriate spacing handle up or down at least four character cells--one cell for each space between item instances.


Deleting an item

To delete an item:

1	In the Object Navigator, click the desired item.

2	Choose Navigator [image] Delete.

Deleting an item also deletes any triggers that are attached to that item.


About the default navigation sequence

  Related Topics

You can control the navigation path through an application by controlling the order in which the operator moves to items.  Operators navigate by pressing navigational keys and by using the mouse.  As the application designer, you can also initiate navigation programmatically by calling built in procedures such as GO_ITEM and GO_BLOCK from triggers and built-in subprograms.

When Form Builder navigates to an item and waits for input, that item is said to have the “input focus”. That is, the item is ready to accept keyboard input from the operator.  Only one item in an application has the input focus at any time.

The sequence of blocks in a form and items in a block defines the default navigation order (sometimes called the TAB sequence or Tab Order.)

Blocks and items are sequenced within a form according to the order in which they appear in the Object Navigator.  Each block and item has an implicit sequence number (1, 2, 3, etc.).

At form startup, Form Builder sets the input focus to the first item in the first block, as indicated by sequence.  If the operator presses [Next Item] (the TAB key on most systems), the input focus moves to the next item in that same block.  Pressing [Next Item] from the last item in the block sets focus back to the first item.  Conversely, pressing [Previous Item] in the first navigable item moves the input focus to the last navigable item.  Pressing [Next Block] moves the input focus to the first item in Block 2.


Specifying the default navigation sequence

  Related Topics

To define the default navigation sequence:

1	In the Object Navigator, arrange all of the blocks in the form according to the desired navigation sequence.

To move a block, click and drag it to the desired location under the Data Blocks node.

2	Arrange all of the items in each block according to the desired navigation sequence.

To move an item, click and drag it to the desired location under the Items node.

Note:  The sequence of blocks within a form also defines the default commit sequence, that is, the order in which Form Builder validates each block during a save/commit operation.


 The Stored PL/SQL Editor interface

New	Displays the New Program Unit dialog, where you can specify the type and name of the program unit you wish to create.
Save	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.
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, with confirmation.
Close	Attempts to close the Stored PL/SQL editor.  If any changes have been made but not saved, an alert appears, prompting you to save or revert the changes or cancel the operation.  Once all changes have been saved or reverted, the Stored PL/SQL editor is closed.
Owner	Displays the database userid of the owner of the current program unit.  Click the arrow to the right of this field to display a drop-down list of usernames 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 field to display a drop-down list of stored program units owned by the userid 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 window:

Source pane	Used to enter and edit PL/SQL stored program unit source text.
Compilation Messages pane	Displays error messages generated as a result of compilation.  Clicking an error message highlights it, scrolls the Source pane to the offending source statement, and positions the text cursor at the location of the error. By default, the Compilation messages pane appears only when there are compilation error messages generated for the stored program unit.  However, you can display the Compilation messages pane at any time by moving the split bar.
Split bar	Enables you to change the relative amount of space occupied by the two panes in the Stored PL/SQL editor.  Note that by default, the Compilation messages pane is displayed only when error messages are generated during compilation.
Status line	Displays information about the current state of the stored program unit at the bottom of the editor.


Displays the New Program Unit dialog, 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.


Attempts to close the Stored PL/SQL editor.  If any changes have been made but not saved, an alert appears, prompting you to save or revert the changes or cancel the operation.  Once all changes have been saved or reverted, the Stored PL/SQL editor is closed.


Displays the database userid of the owner of the current program unit.  Click the arrow to the right of this field to display a drop-down list of usernames whose stored program units you have access to.


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 userid 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 PL/SQL 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 designing forms for querying

  Related Topics

Data blocks that correspond to a specific database table automatically support querying, updating, inserting, and deleting records, with no additional coding required.  By setting the properties of the block and its items, you can control, modify, and even prevent queries as desired.

A form can be placed in Enter Query mode by an operator pressing [Enter Query], or by executing the ENTER_QUERY built-in procedure.  Form Builder remains in Enter Query mode until the query is executed by the EXECUTE_QUERY operation, or until the operator presses [Cancel].

While the form is in Enter Query mode, operators set the values of items in the current block to specify criteria for the query.  Operators can use pattern matching, relational operators, and the QUERY WHERE dialog box to define the example record.

The ENTER_QUERY and EXECUTE_QUERY operations, whether initiated by the operator or programmatically, always occur at the block level.  Once a form is in Enter Query mode, Form Builder does not allow the operator or the application to navigate to a different block until the query is executed or the operator cancels Enter Query mode.

Set the Query Allowed block property to specify whether a block is queryable.  To make a "query-only" block, set Query Allowed to Yes and Delete Allowed, Insert Allowed, and Update Allowed to No.

There is a default SELECT statement associated with each data block.  At runtime, Form Builder executes this SELECT statement when a query is made against the block, either programmatically or by the operator.

The syntax for a block's default SELECT statement is derived from the names of the data items in the block. A data item is an item in a data block that has its Database Block property set to Yes. The name of a data item must match the name of a column in the block's base table.  For example, in the Sample form, when operators execute a query in the ORD_BLK block, Form Builder uses the following default query:

SELECT id, customer_id, date_ordered, payment_type, order_filled,	   sales_rep_id 	FROM   S_ORD

The Customer_Name and Sales_Rep_Name items are also in the ORD_BLK block, but they are control items whose values are derived from columns in different tables.  Because these items have the Database Block property set to No, Form Builder does not include them in the default SELECT statement.

The default query returns a value from each database column for which there is a corresponding item in the block.  The query is unrestricted by default, and retrieves all rows from the base table in no particular order.

Operators can restrict the rows retrieved by a query by entering values in data items.  Form Builder then uses these values to construct the WHERE clause for the default SELECT statement.

For example, if the operator navigates to the ORD_BLK block, presses [Enter Query], types 55 in the ID text item, and then executes the query, Form Builder issues the following SELECT statement:

SELECT id, customer_id, date_ordered, payment_type, order_filled,	   sales_rep_id 	FROM   S_ORD	WHERE  id = '55'

You can also specify the WHERE and ORDER BY clauses by setting the WHERE and ORDER BY block properties, either at design time or at runtime.  For example, if you had set the ORDER BY Clause property for the ORD_BLK block to "id DESC, " the SELECT statement from the previous example would have been issued as follows:

SELECT  id, customer_id, date_ordered, payment_type, order_filled,	    sales_rep_id 	FROM  S_ORD	WHERE id = '55'	ORDER BY id DESC

When Form Builder executes a query, it identifies the rows in the database that match the query criteria, and then fetches the number of rows required by the block. You can control the number of records that Form Builder fetches at one time by setting the Maximum Records Fetched block property.


About defining a block's WHERE and ORDER BY clauses

  Related Topics

The WHERE and ORDER BY block properties allow you to restrict and order the records returned to a data block by the default SELECT statement associated with that block.

You can modify the WHERE and ORDER BY clauses programmatically at runtime by executing the SET_BLOCK_PROPERTY built-in procedure.

Remember also that operators can place the form in Enter Query mode and then further restrict the default WHERE Clause by specifying additional query conditions in data items.

You can set the default WHERE and ORDER BY clauses for a block in the Property Palette.  To invoke a text editor in the Property Palette, double-click the desired property.

Tip:  Select Tools [image] Tables/Columns to invoke the Tables/Columns browser to look up table and column names in the database.

Any valid SQL WHERE and ORDER BY clauses can be entered in the default WHERE clause and default ORDER BY clause properties.  Some additional considerations are specific to Form Builder:

•	It is not necessary to include the reserved words WHERE and ORDER BY; Form Builder implicitly adds them to any text you enter.  Thus, the clause

ORDER BY last_name

can be entered as

last_name

And the following is a valid WHERE clause entry:

account_balance > 5000

•	You cannot reference LONG database columns in the default WHERE/ORDER BY clauses.


About defining items for Enter Query mode

  Related Topics

The following types of items are queryable in Enter Query mode:

•	check boxes

•	list items

•	radio groups

•	text items

•	OLE container custom items

All other types of items are non-navigable when a form is in Enter Query mode, and their values cannot be included in the example record.

When the operator or the application executes a query, the SELECT statement that Form Builder sends to the database includes the WHERE clause defined by the block's WHERE and ORDER BY properties, plus any additional query criteria specified by the operator.  When a form is in Enter Query mode, operators can enter example values in items to further restrict the query, as follows:

Text Items	To include a text item value in a query, enter a value in the item.  To exclude the item from the query, leave the item blank.
Check Boxes	To include or exclude the current check box value from a query, shift-click the item with the mouse to toggle it between the Query Enabled and Query Disabled states.  When the check box is query-enabled, its value is included in the query.
Radio Groups	To include a radio group value in a query, click any button in the radio group.  To exclude the radio group from the query, click the currently selected radio button so that no radio buttons in the group are selected.
List Items	To include a list item value in a query, select any list item value.  To exclude the list item from the query, select the blank (empty) element in the list.
Query Allowed Property   Set the Query Allowed property of a check box, list item, radio group, or text item to specify whether operators are able to navigate to the item in Enter Query mode.

When a form is in Enter Query mode, Form Builder skips over items that have the Query Allowed property set to No, even if those items are navigable in normal mode.

Query Length Property  Query Length specifies the number of characters an operator is allowed to enter in a text item when the form is in Enter Query mode.  The Query Length must be at least as many characters as the text item's Maximum Length property.

The Query Length property applies only to text items.

Setting the Query Length property greater than Maximum Length allows operators to enter relational operators in the text item when using query-by-example.  For example, in a SALARY text item with a Maximum Length of 6, operators might want to enter query values such as

<=52200

or

#BETWEEN 30000 and 40000

Setting the SALARY item's Query Length property to 26 allows operators to enter these queries directly in the text item, without having to invoke the Query WHERE dialog box.

Case Restriction Property  The Case Restriction property applies only to text items.  It determines whether Form Builder should treat upper and lower case values the same way when processing a query.


About defining check boxes, radio groups, and list items for querying

  Related Topics

Check boxes, radio groups, and list items have predefined values that are associated with specific selection states or list elements.  For example, when a check box labeled Security Clearance is checked, its actual stored value might be the string "TOP_SECRET."

When you define a check box, radio group, or list item, you specify whether it accepts fetched or assigned “other values.”  An “other value” is a value that does not match any of the values associated with a specific selection state (checked or unchecked), radio button in a group, or list element in a list.

To specify how Form Builder handles other values, set the appropriate item property:  For a check box, set the Checkbox Mapping of Other Values property; for radio groups and list items, set the Mapping of Other Values property.  For example, for a check box, you might set the  Checkbox Mapping of Other Values property to Checked to specify that any other value that is fetched into the check box should be interpreted as the Checked value.

If you set the Mapping of Other Values property of a check box, radio group, or list item to specify that the item should not accept other values, operators will not be able to retrieve records that contain other values in the corresponding database column.

For example, when a block contains a check box that does not accept other values, operators can retrieve only records with column values that exactly match either the Value When Checked or the Value When Unchecked values.  Any row containing an other value in that column would not match the block's query criteria, and so would not be displayed in the block.

When creating a data item check box, radio group, or list item, consider how that item's value is interpreted in the example record when the operator uses query-by-example in Enter Query mode.  Consider a check box called Security Clearance that corresponds to a database column called CLEARANCE, and that is defined as follows:

Property	Setting
Checked Value	TOP_SECRET
Unchecked Value	NONE
Check Box Mapping of Other Values	Not Allowed

 If a form operator includes this check box in a query, the WHERE clause predicate for the block's default SELECT statement will be constructed as follows:

Check Box State	Resulting WHERE Clause
Checked	(CLEARANCE = TOP_SECRET)
Unchecked	(CLEARANCE = NONE)

Form Builder could alternatively set the Check Box Mapping of Other Values property to Checked, so that the item accepts other values (displaying them as checked) as shown here:

Property	Setting
Checked Value	TOP_SECRET
Unchecked Value	NONE
Check Box Other Values	Checked (Other Values OK)

Then, if the form operator elects to include this check box in a query, the WHERE clause predicate for the block's default SELECT statement will be constructed as follows:

Check Box State	Resulting WHERE Clause
Checked	(CLEARANCE <> NONE)
Unchecked	(CLEARANCE = NONE)


About executing a query programmatically

  Related Topics

Queries are often initiated programmatically.  For example, to create a menu item or button that operators can press to execute a query, write the appropriate menu item command or When-Button-Pressed trigger.

To place a form in Enter Query mode programmatically, call the ENTER_QUERY built-in procedure.  Operators can then specify query conditions before executing the query with a menu or button command.  To execute a query immediately, call the built-in procedure EXECUTE_QUERY.

In some situations, it may be best to write a trigger that executes either the ENTER_QUERY or EXECUTE_QUERY procedure, depending on whether or not the form is already in Enter Query mode.  To make this work, read the value of the SYSTEM.MODE system variable to determine if the form is in Normal mode or Enter Query mode:

IF System.Mode = 'NORMAL' THEN	Enter_Query;ELSE	Execute_Query;

To execute a query programmatically, the block to be queried must be the current block.  When necessary, navigate to the desired block before executing the query:

IF System.Cursor_Block != 'ORD_BLK' THEN	Go_Block('ord_blk');	Execute_Query;END IF;


About controlling queries with Pre-Query and Post-Query triggers

  Related Topics

The Pre-Query and Post-Query triggers allow control over query processing.  They can be defined at the form or block level.  Most often, attach them to specific blocks to control the query functionality of those blocks.

The Pre-Query trigger fires just before Form Builder issues the SELECT statement to the database, after the operator has defined the example record by entering query criteria in Enter Query mode.

Inside a Pre-Query trigger, the example record defined by the query criteria is the current record.  This means that trigger code can read and set the values of items in the example record using standard :block_name.item_name syntax.

A Pre-Query trigger can be used to disallow query conditions that might be invalid.  When a form is in Enter Query mode, normal validation is suspended and no validation triggers fire as they do in Normal mode.  The Pre-Query trigger thus allows you to verify that any values entered by the operator are valid query conditions.

When invalid query conditions have been entered, you can abort the query by raising the FORM_TRIGGER_FAILURE built-in exception in the Pre-Query trigger.

You can also call SET_BLOCK_PROPERTY to modify the block's WHERE and ORDER BY clauses from within the Pre-Query trigger, to further restrict or order the records the query will retrieve.

The Post-Query trigger fires after the query has executed, when Form Builder is fetching records into the form.  Post-Query fires once for each record retrieved into the form, which allows you to read and set the values of items in a fetched record before the operator sees them displayed in the block.

A Post-Query trigger is also useful for populating control items whose values are derived from a table other than the block's base table.


About defining triggers to fire in Enter Query mode

  Related Topics

Certain triggers can be specified whether they should fire when the form is in Enter Query mode by setting the Fire in Enter Query Mode trigger property.

Consider a button that operators can select to display a list of values (LOV).  The text of the When-Button-Pressed trigger attached to the button might look like this:

/*  When-Button-Pressed Trigger: */ DECLARE 	dummy_var BOOLEAN; BEGIN 	dummy_var := Show_LOV('Customers',10,20); END;

If the Fire in Enter Query Mode property is set to Yes for this trigger, operators will be able to invoke the list of values in Enter Query mode as well as Normal mode.

The following triggers are valid in Enter Query mode:

•	key - *

•	On-Error

•	On-Message

•	When- triggers, except:

•	When-Database-Record

•	When-Image-Activated

•	When-New-Block-Instance

•	When-New-Form-Instance

•	When-Create-Record

•	When-Remove-Record

•	When-Validate-Record

•	When-Validate-Item


Creating a trigger that fires in Enter Query mode

  Related Topics

To create a trigger that fires in Enter Query mode:

1	In the Object Navigator, select the desired trigger.

2	In the Property Palette, set the Fire in Enter Query Mode property to Yes.

By default, the Fire in Enter Query Mode property is set to Yes for any trigger that is valid in Enter Query mode.


About using SYSTEM.MODE to determine the current mode

  Related Topics

Setting the Fire in Enter Query Mode property to Yes causes a trigger to fire in both Enter Query mode and in Normal mode.  For a trigger to perform different functions depending on whether the form is in Normal mode or Enter Query mode use the SYSTEM.MODE system variable to determine the current mode.

For example, you might want a trigger to take one set of actions if the form is in Enter Query mode, and a different set of actions if it is Normal mode:

/*  Trigger with Fire in Enter Query Mode property to Yes: */

IF :System.Mode = 'ENTER-QUERY' THEN 	-- execute these statements ELSE

-- execute these other statements

Similarly, you can write a trigger that fires only if Form Builder is in Enter Query mode:

/*  Trigger with Fire in Query Mode property to Yes:  */

IF :System.Mode = 'ENTER-QUERY' THEN 	-- execute these statements

END IF;

Note:  The SYSTEM.MODE system variable reports on the mode of the current block.  This means, for example, that you cannot expect SYSTEM.MODE to be accurate when you read its status in a trigger attached to a control block, such as a When-Button-Pressed trigger.  Because a control block is not based on a database table, it can never be placed in Enter Query mode.


About Built-ins that are not allowed in Enter Query mode

  Related Topics

The following built-in subprograms cannot be called from a trigger while Form Builder is in Enter Query mode:

ABORT_QUERY	LAST_RECORD
BLOCK_MENU	LOCK_RECORD
CALL_INPUT	LOGON/LOGON_SCREEN/LOGOUT
CLEAR_BLOCK	NEW_FORM
CLEAR_FORM	NEXT_BLOCK
COMMIT_FORM	NEXT_RECORD
CREATE_QUERIED_RECORD	NEXT_SET
CREATE_RECORD	POST
DELETE_RECORD	PREVIOUS_BLOCK
DOWN	PREVIOUS_RECORD
DUPLICATE_RECORD	SCROLL_DOWN
FETCH_RECORDS	SCROLL_UP
FIRST_RECORD	SELECT_RECORDS
GO_BLOCK	UP
GO_RECORD	UPDATE_RECORD
INSERT_RECORD

 Note:  Because Form Builder prevents navigation out of the current block while in Enter Query mode, GO_ITEM is allowed only if the target item is in the current block.


About controlling inserts, updates, and deletes

  Related Topics

Form Builder provides a set of properties and triggers that you can use to allow, prevent, or modify inserts, updates, and deletes in a form.

Set the following properties to control whether a block supports inserts, updates, and deletes:

•	Insert Allowed

•	Update Allowed

•	Delete Allowed

At the item level, set the following properties to control inserts and updates:

•	Insert Allowed

•	Update Allowed

•	Update Only if NULL


About controlling inserts

  Related Topics

Set the Insert Allowed block property to specify whether a block should support inserting new records in its base table.  When Insert Allowed is set to Yes (the default), the Insert Allowed item property determines whether each individual item in the block supports inserting new records.

Specifically, the Insert Allowed item property determines whether operators can modify the value of an item in a new record (i.e., when the status of the record is NEW or INSERT).

When the Insert Allowed item property is set to No, and the item has the Keyboard Navigable and/or Enabled properties set to Yes, operators can navigate to the item, but cannot modify its value when it is in a new record.

When a block supports inserting new records, Form Builder creates a new record in the block when any of the following events occur:

•	The operator selects Record [image] Insert from the default form menu.

•	The application executes the CREATE_RECORD built-in procedure.

•	The operator or the application navigates to the next record when the focus is in the last record in the block.

For example, if the focus is in the last record in a block and the operator presses [Next Record], Form Builder creates a new record in the block.

Form Builder also creates a new record in a block the first time the block is visited during a session.  For example, at form startup, when Form Builder navigates to the first navigable item in the first block in the form, a new record is created in that block.  The status of a record changes from NEW to INSERT as soon as the operator enters data that would need to be committed to the database by the next Save/Commit operation.


About default values for items in new records

The default value of an item is determined by the value of the Initial Value item property.  The value you specify must be compatible with the item's data type.  For example, the default value for a text item having a data type of DATE must be a value that can be displayed in a valid date format.

Form Builder assigns a default value to an item when a new record is created.  Specifically, Form Builder assigns the default value whenever the item is part of a record whose status is marked NEW.

The default value can be any of the following:

•	raw value (216, 'TOKYO')

•	$$DATE$$, $$DBDATE$$, $$DATETIME$$, $$DBDATETIME$$

•	form item value (:block_name.item_name)

•	global variable (:GLOBAL.my_global)

•	form parameter (:PARAMETER.my_param)

•	a sequence (:SEQUENCE.my_seq.NEXTVAL)

It is common to specify default values for check boxes, radio groups, and list items, so that the items appear with the desired selection state (checked or unchecked, etc.). When you set default values for these items, remember that the default value does not get assigned until Form Builder creates a new record in the item's block.  You can force Form Builder to create a new record in a block by navigating to the block programmatically, for example, in a When-New-Form-Instance trigger.

Note:  Simply copying a value to a field does not require navigation to the block, so it does not create a new record in the block, and does not display default values.


About item hint text

  Related Topics

Form Builder can display item-specific help text on the console's message line at runtime.  The help text for an item, or hint, can only be displayed when the input focus is in that item.  To display the hint text defined for the current item, execute the HELP built-in procedure.

Hint text is usually advice to the operator on how to enter valid data in the item.  For example, the hint text for an item that contains part numbers might be "Enter a 6-digit part number."  You control the display of hint text by setting an item's Hint and Display Hint Automatically properties.

Suppressing Hint Text  If you do not want Form Builder to display hint text for an item, leave the Hint property blank.  When the Hint property is blank, the Display Hint Automatically property has no effect, and can be either Yes or No.

Note:  The Hint and Display Hint Automatically properties apply only to items that are assigned to a canvas.  (Hint text does not apply to NULL-canvas items.)

Default Hints for Data Items  When you create a data block with the Data Block wizard, Form Builder sets the Hint and Display Hint Automatically properties for each item in the block as follows:

Hint	The default hint is Enter a Value for: <item_name> where item_name is the name of the data item created through the Data Block wizard.

Display Hint Automatically	Set to No (Form Builder displays the hint only if an operator presses [Help] in that item).


Creating hint text for an item

  Related Topics

To Specify the hint text for an item:

1	In the Object Navigator double-click the item for which you want to add hint text to display the Property Palette.

2	Under the Help node type the desired hint text in the Hint text box.  Do not enclose the text in quotes.

3	Set the Display Hint Automatically property to Yes or No to specify when Form Builder should display the hint text:

•	Set Display Hint Automatically to Yes to have Form Builder display the hint text when the input focus enters the item.

•	Set Display Hint Automatically to No to have Form Builder display the hint text when the operator presses [Help] or selects the Help item from the default menu while the input focus is on the item.


About controlling updates

  Related Topics

To specify whether or not operators should be able to update records that were queried from the database  set the Update Allowed and Enforce Column Security block properties.

When Update Allowed is set to Yes at the block level, you can set Update Allowed and Update Only if Null at the item level to specify whether operators should be able to update specific items in a queried record.

These mutually exclusive properties specify update conditions for an item that is part of a record whose status is QUERY.  Form Builder marks a record's status as QUERY if the record has been fetched or committed; that is, when the record reflects a row in the database.

Set the Enforce Column Security property to Yes to have Form Builder automatically set Update Allowed at runtime, depending on whether the current operator has update privileges for the item's corresponding column in the database.

When Enforce Column Security is set to Yes, the current operator must have column-level update privileges on the columns to which the block's items correspond.  Form Builder enforces column security by dynamically setting the Update Allowed property to No at form startup for items that correspond to columns on which the operator does not have update privileges.

When you set Enforce Column Security to Yes, Form Builder reads the privileges defined in the data dictionary at form startup.


About validating item values during data entry

  Related Topics

Form Builder has a data validation model that makes it easy to validate data in records that have been entered or updated by the operator.  Many of the most common validation requirements can be handled by setting the following item-level properties:

•	Data Type

•	Maximum Length

•	Fixed Length

•	Required

•	Highest Allowed Value/Lowest Allowed Value

To add application-specific validation, write a When-Validate-Item or When-Validate-Record trigger for the item or block.  When-Validate-Item fires when Form Builder during the Leave the Item event, just after Form Builder performs its own validation checks.  When-Validate-Record fires during the Leave the Record event, when Form Builder checks to ensure that all of the items in the current record are marked valid before navigating to the target record.

A common validation requirement is to ensure that items which correspond to primary key columns in the database have unique values. The Oracle8 Server enforces NOT NULL and UNIQUE constraints that can accomplish this for you at the kernel level.  However, it is usually desirable to give operators immediate feedback on such errors during data entry, rather than waiting for an ORACLE error to be displayed at commit time.

To check that a primary key value is unique immediately after it is entered by the operator, create a When-Validate-Item trigger that issues a SELECT statement to check if the value already exists in the block's datasource.

Note: You can also enforce unique primary keys by setting the Enforce Primary Key block and Primary Key item properties.  However, these properties are set, Form Builder does not check for duplicate values until commit time, when it processes each UPDATE or INSERT for the block.  Setting these properties provides no advantage over using comparable database constraints, because in both cases, duplicate primary key values are not flagged until commit time.


About populating items with values from other tables

 Examples	     Related Topics

It is often necessary to create an item in a data block whose value is derived from a table other than the block's datasource.  Such items are sometimes known as look-up fields, because the application needs to query, or "look up," a value for the item whenever a query is executed in the block, or whenever the current record changes.

For example, in the sample tables, the S_ORD (Orders) table includes a CUSTOMER_ID column, but does not include the customer name.  In the relational schema, Name is an attribute of a customer, not of an order, and the rules of normalization dictate that it should appear in the S_CUSTOMER table, rather than in the S_ORD table.  The CUSTOMER_ID column is the join field for S_ORD and S_CUSTOMER.

When you create a data block based on the S_ORD table, however, you will probably want to display the name of the customer along with each order, rather than just the ID for that customer.  To do so, create a control item in the Orders block, and populate it programmatically whenever the customer ID changes.


Populating an item with values from another table

  Related Topics

To populate an item with values from another table:

1	Create an item of the desired type in the appropriate data block.

2	Double click the item to display the Property Palette.

3	Under the Database node, set the Database Item property to No to make the item a control item.

4	Under the Data node, set the Data Type, Maximum Length, and any other properties needed to be compatible with the type of fetched values the item will display.

5	Create triggers to populate the control item at runtime.


About populating items with values from other tables examples

A Post-Query trigger fires when the operator or the application executes a query.  It fires once for each record fetched, which means that your code inside the trigger can read and set the values of values in each record.

To populate a control item named CUSTOMER_NAME in a data block named ORD_BLK, you could create the following Post-Query trigger attached to the ORD_BLK block.

Post-Query Trigger for ORD_BLK block: 	SELECT name	INTO :ord_block.customer_name	FROM s_customer	WHERE s_customer.id = :ord_blk.customer_id;

The Post-Query trigger takes care of retrieving the customer name when the operator queries orders in the block, but you also need to display the customer name when the operator is entering or updating the customer ID item during data entry.  To handle this task, create a When-Validate-Item trigger attached to the customer ID item.

A When-Validate-Item trigger fires when the operator or the application navigates out of the item, and gives you the opportunity to issue a SELECT statement that populates the Customer_Name item.

When-Validate-Item Trigger for Customer ID item: BEGIN	SELECT name	INTO :ord_block.customer_name	FROM s_customer	WHERE 	s_customer.id = :ord_blk.customer_id;EXCEPTION	WHEN	NO_DATA_FOUND THEN	Message('Invalid Customer ID. Please enter again.');	RAISE Form_Trigger_Failure;END;


About controlling navigation

  Related Topics

The default navigation sequence for items in a block and blocks in a form is determined by the arrangement of items and blocks in the Object Navigator.  Form Builder also gives you complete control over navigation by allowing you to set properties at the form, block, and item level.  By setting these properties at design-time or runtime, you can control whether operators can navigate to items, and in what order.

The following properties can be set to control navigation:

Object	Properties that Affect Navigation
Form	First Navigation Block
Block	Navigation Style Next Navigation Block Previous Navigation Block
Item	Enabled Mouse Navigate Keyboard Navigable Next Navigation Item Previous Navigation Item


About modifying the default navigation sequence

  Related Topics

You can override the default navigation sequence at the block or item level by setting the Next Navigation Block, Previous Navigation Block, First Navigation Block, Next Navigation Item, and Previous Navigation Item properties.

Next/Previous Navigation Data Block Property  The Next Navigation Block and Previous Navigation Block properties override the default navigation sequence defined by the order of blocks listed in the Object Navigator.  Specifically, the Next Navigation Block property allows you to name a different block as the next block in the sequence.

For example, given a form with three blocks, you could set Block 1's Next Navigation Block property to change its default next block from Block 2 to Block 3.  Doing so would yield a block navigation sequence of Block 1...Block 3...Block 1.  Note that in this example, the next block for Block 3 remains Block 1, and thus Block 2 is never visited during default keyboard navigation.

You can also use the Next Navigation Data Block and Previous Navigation Data Block properties to disable the Next Block and Previous Block operations.  For example, to disallow the [Next Block] key in Block 2, set Block 2's Next Navigation Block property to itself (Block 2).

Next/Previous Navigation Item Property  The Next Navigation Item and Previous Navigation Item properties are comparable to the Next and Previous Navigation Block properties, except that they control navigation at the item level, rather than the block level.

First Navigation Data Block Property  Set the First Navigation Block form module property to specify a block as the target block other than the first block in the navigation sequence when entering the form at form startup.  This property can be set in the Property Palette or programmatically with the built-in procedure SET_FORM_PROPERTY.


About specifying the navigation style for a block

  Related Topics

You can alter the default navigation sequence by setting the Navigation Style block property.  Navigation Style specifies how a Next Item or Previous Item operation is processed from the last navigable item and the first navigable item in the block, respectively.

The following settings are valid for Navigation Style:

Same Record	The default navigation style.  A Next Item operation from a block's last item moves the input focus to the first navigable item in the block, in the same record.
Change Record	A Next Item operation from a block's last item moves the input focus to the first navigable item in the block, in the next record. If the current record is the last record in the block and there is no open query, Form Builder creates a new record.  If there is an open query in the block (the block contains queried records), Form Builder retrieves additional records as needed.
Change Block	A Next Item operation from a block's last item moves the input focus to the first navigable item in the first record of the next block.  Similarly, a Previous Item operation from the first item in a block moves the input focus to the last item in the current record of the previous block.  Note that the Next Navigation Block and Previous Navigation Block properties can be set to redefine a block's next or previous block.
The Navigation Style block property can be set at design time in the Property Palette, and at runtime using the SET_BLOCK_PROPERTY built-in procedure.

The default navigation style is Same Record.  In general, applications that use this style must make it clear to form operators which items belong to which blocks.  If operators have to press [Next Block] to navigate to an item in a different block, it must be apparent to the operator which items are in which blocks.

It may not always be desirable to externalize the block navigation paradigm to users.  In such cases, you can use either the Change Record or Change Block navigation styles to achieve the desired navigation sequence.  The Change Block setting is often useful when you want operators to be able to press TAB to visit all of the items in a window, even if those items belong to more than one block.

For example, when you create a window with a row of buttons at the bottom, the button items are often in a different block than other items in the same window.  Using the Change Block navigation style for each block effectively eliminates the Next Block navigation restriction.

The Change Record navigation style is useful for database blocks that may store several records at a time.  This setting allows operators to quickly traverse multiple records, without having to use a different key or the mouse to explicitly navigate to the next or previous record.  During data entry, the Change Record property allows operators to quickly insert a new record at the end of the block's list of records.


About making items navigable and enabled

  Related Topics

A navigable item is one that operators can navigate to with the TAB key during default navigation, or that Form Builder can navigate to by executing a navigational built-in procedure.

For example, when an operator presses [Next Item], or the application executes the built-in procedure NEXT_ITEM, Form Builder moves the input focus to the next navigable item, skipping over any non-navigable items in the sequence.

You can set the Keyboard Navigable and ENABLED properties of items to specify whether operators are allowed to navigate to and interact with them.  The Keyboard Navigable property determines whether Form Builder can place the input focus in an item during default navigation.  It applies to all items except chart items and display items.  The ENABLED property determines whether operators can use the mouse to manipulate an item that has the Keyboard Navigable property set to No.

On most window managers, disabled items are displayed with reduced contrast to indicate that they are unavailable for input or selection.

When ENABLED is set to Yes, Keyboard Navigable can be either Yes or No.  When Enabled is No, an item is always non-navigable.

The following table shows the valid settings for these properties, and describes the resulting navigational behavior.

Keyboard Navigable	Enabled	Resulting Navigation Behavior
Yes	Yes	Item is navigable, and Form Builder can move the input focus to the item during default navigation.  Item is displayed normally.
No	Yes	Item is non-navigable.  During default navigation, Form Builder skips over the item to the next navigable item in the sequence.  Item is displayed normally, and operators can navigate to and manipulate the item with the mouse.
No	No	Item is non-navigable, and is displayed with reduced contrast to indicate that it is unavailable for input or mouse manipulation.

 Note:  Setting ENABLED to No prevents operators from updating the item's value but also disables and grays out the item.  To display the item normally but still prevent operators from modifying its value, set the Insert Allowed and/or Update Allowed item properties to No, to prevent operators from modifying a record whose status is either NEW/INSERT or QUERY/CHANGED.


About setting the mouse navigate property for GUI items

 Examples	     Related Topics

Operators can click with the mouse to activate a button, toggle a check box, select an element in a list item, or select a radio button.  For each of these items, you can set the Mouse Navigate property to specify whether a mouse click in the item should cause Form Builder to set the input focus on the item. The Mouse Navigate% property applies only to GUI applications, and is valid only for the following items:

•	button

•	check box

•	list item

•	radio group

When Mouse Navigate% is Yes (the default), Form Builder performs standard navigation to move the focus to the item when the operator activates the item with the mouse.

When Mouse Navigate% is set to No, Form Builder does not perform navigation (and the resulting validation) to move to the item when an operator activates the item with the mouse.


About setting the mouse navigate property for GUI items examples

Consider two blocks, A and B, each displayed in the same window.  Block A contains text items and Block B contains buttons.  When the input focus is in a text item in Block A, the operator can activate a button in block B by clicking it with the mouse.  When the operator clicks on the button, the When Button Pressed event occurs, and Form Builder executes the code in the When-Button-Pressed trigger attached to that button.

The setting of the button's Mouse Navigate property determines how Form Builder processes the mouse-click in the button:

If Mouse Navigate is set to Yes...  Form Builder navigates to the button, performing standard validation checks on the way.  Thus, the following internal navigation and validation events can potentially occur:

•	Leave the Item (the source text item)

•	Validate the Item

•	Leave the Record

•	Validate the Record

•	Leave the Block (Block A)

•	Enter the Block (Block B)

•	Enter the Record (the "record" the button is in)

•	Enter the Item (the target button)

If Mouse Navigate is set to No...  Form Builder simply fires the button's When-Button-Pressed% trigger, without performing internal navigation to the button.  Because no navigation occurs, the input focus remains in the source text item after the trigger executes.  (Unless, of course, the trigger code navigates to another item.)

If there are triggers defined for any of these standard navigation or validation events, they fire at the appropriate point during internal navigation to the button.

For example, if there is a When-Validate-Item trigger attached to the source item, it fires when the operator presses the button.  (If the button's Mouse Navigate property was set to No, no navigation would occur, and the validation trigger would not fire.)

Notes on Mouse Navigate property:

•	When Mouse Navigate% is Yes, the When-Button-Pressed% trigger on the button fires only if navigation to the button succeeds.  If any validation checks fail, navigation fails, and the When-Button-Pressed% trigger does not fire.  This means that operators cannot activate the button if any required fields contain invalid values.

•	Some window managers do not display any visual indication that the input focus is in an item such as a button or check box.  If you leave Mouse Navigate% as Yes on these platforms, be aware that operators will have no visual feedback regarding the location of the input focus.


About navigating using code

The navigation keys that operators can use to navigate in a form have corresponding built-in procedures that you can call to initiate navigation programmatically.  The following table shows some of the most common navigation keys and their corresponding built-ins:

Runform Function Key	Corresponding Built-in Subprogram
[Next Item] (TAB)	NEXT_ITEM
[Previous Item]	PREVIOUS_ITEM
[Next Block]	NEXT_BLOCK
[Previous Block]	PREVIOUS_BLOCK
[Next Record]	NEXT_RECORD
[Previous Record]	PREVIOUS_RECORD
[Next Key]	NEXT_KEY

Other built-in procedures navigate directly to an indicated target:

•	GO_ITEM navigates to an indicated item.

•	GO_BLOCK navigates to the first navigable item in the indicated block.

•	GO_FORM navigates to the current item in another open form.


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


Data Block Wizard: Welcome page
About the Data Block Wizard

  Next Step	  Related Topics

About the Data Block Wizard

The Data Block Wizard enables you to quickly and easily create or modify data blocks for use in your application.  When you use the wizard to create or modify a data block, the wizard can automatically generate code to enforce integrity constraints in the database, and modify various properties and settings for you, giving you more time to concentrate on other aspects of developing your application.

Use the Data Block Wizard to complete the following tasks:

•	create or modify a data block based either on a database table or view, or on a set of stored procedures (an advanced option)

•	map columns from the table, view, or stored procedure result set to items in the data block

•	specify arguments to procedures that query, insert, update, delete, and lock data for the data block (required only if you base the data block on stored procedures)

•	establish master-detail relations between the data blocks of a form module

The Data Block Wizard is re-entrant

A powerful quality of the Data Block Wizard is its ability to operate in re-entrant mode.  This means you can use the Data Block Wizard to modify an existing data block—even if the block was not originally created with the wizard.

To invoke the Data Block Wizard in re-entrant mode, select the existing data block in the Object Navigator (or select any item in the block in the Object Navigator or Layout Editor), then choose Tools [image] Data Block Wizard from the menu.

Navigating in the Data Block Wizard

The Data Block Wizard provides six buttons to help you navigate your way through its pages:

•	Cancel—cancel all changes you have made (if any), and exit the wizard

•	Help—display online help text for the current page of the wizard

•	Back—navigate to the previous page in the wizard

•	Next—navigate to the next page in the wizard

•	Apply—apply changes you have made without exiting the wizard (re-entrant wizard only)

•	Finish—save changes you have made with the wizard (if any), and exit the wizard

Note:  If you click Next or Back before you have entered all necessary information for a particular wizard page, the wizard prevents you from navigating to the next (or previous) page.  Similarly, if you have not entered all necessary information into the wizard when you click Apply or Finish, the wizard automatically places you onto the page where you can finish entering the required data.


Data Block Wizard: Type page

  Next Step 	  About the Wizard

To select a data source type:

1	On the Type page, click a radio button to specify a type:  either Table or View, or Stored Procedure.

If you select:

•	Table or View, next you select the table or view from the database, then map columns from the table or view to items in the data block.

•	Stored Procedure, next you select stored procedures to query, insert, update, delete, and lock data for the data block.

2	To select a data source, click Next to display the next page of the wizard (either Table or Query, depending on the data source type you selected).


Data Block Wizard: Table page

  Next Step 	  About the Wizard

First:  select a table or view as data source:

1	On the Table page, in the Table or View field, enter the name of the table or view, and click Refresh.

If you wish to select a table or view from a list of available tables and views in your database schema (or all available schemas), click Browse.

If you are not connected to a database, the wizard displays the Connect dialog.

2	If you want the wizard to automatically enforce integrity constraints defined in the database, set the Enforce Data Integrity checkbox to checked.

Next:  select columns

To map a column or columns from the table or view to a database item in the data block, select the column(s) and:

•	click  [image]  to move the selected column(s) from the Available Columns list to the Database Items list (to move all available columns, click  [image] ).

or

•	drag-and-drop the column(s) from the Available Columns list to the Database Items list.

When you move a column from the Available Columns list to the Database Items list, if the item:

•	does not already exist in the data block, then the wizard will create a new item and set its Database Item property to Yes.

•	already exists in the data block, then the wizard automatically will set the item's Database Item property to Yes.

Hint:  Be sure to map all primary-key and other mandatory column(s) from the table or view to item(s) in the data block.

To de-select a column

To move a column or columns out of the data block, select the column(s) and:

•	click  [image]  or  [image] .

or

•	drag-and-drop the column(s) to the Database Items list.

When you move a column from the Database Items list to the Available Columns list, if the item:

•	does not already exist in the data block, then no item based on the column will appear in the data block.

•	already exists in the data block, then the item will remain in the data block, but the wizard automatically will set the item's Database Item property to No.

About selecting object tables and column objects

If the table you select is a user-defined object table, or a relational table containing a column object, it will appear in the Available Columns window with the object expanded.  An outline format with indenting (similar to that used by the Object Navigator) is used to show the composite parts of these objects.

Forms Developer treats each component in an object table as a separate column, and allows you to select these columns individually.  The table need not be treated as a single, homogeneous object.  Similarly, a column object in a relational table is expanded into its composite parts -- each one of which is treated as a separate column and is individually selectable.

Examples of object tables

Suppose we had defined the following object type, and a table based upon it:

    CREATE TYPE addr_type AS OBJECT

                (street VARCHAR2(90),

                 city VARCHAR2(30),

                 area VARCHAR2(2));

    CREATE TABLE address OF addr_type;

Then the Data Block Wizard would show all columns (street, city, and area) of this object table (address) in the Available Columns area and allow you to select any or all as data block items.

As a second example, consider a table based on an object definition, which itself referred to another object definition:

     CREATE TYPE addr_type AS OBJECT
                 (street VARCHAR2(90),

                  city VARCHAR2(30),

                  area VARCHAR2(2));

     CREATE TYPE emp_type AS OBJECT

                 (empno NUMBER,

                  ename VARCHAR(80),

                  address addr_type,

                  salary NUMBER);

     CREATE TABLE emp_table of emp_type;

The emp_type object type is composed of four attributes, one of which (address) is based on another definition -- the addr_type object type definition.  Addr_type itself defines three attributes.  Thus, when we create a table based on the emp_type type, the result is a table with six columns (empno, ename, street, city, area, and salary).  Again, the Data Block Wizard would show all six columns, and any/all are selectable.

Example of column object

Consider a relational table that contains a column object based on the above object type of addr_type:

      CREATE TABLE customer (custname CHAR(20), custaddr addr_type);

Then, in its Available Columns area, the Data Block Wizard would show the following for the customer table:

      custname

      custaddr

         - street

         - city

         - area

Again, any or all of the columns custname, street, city, and area are selectable.  Note that custaddr also appears as the name of the column object that contains street, city, and area.  Selecting custaddr has the effect of selecting all of its parts -- but not custaddr itself.  A column object name is only a label, and cannot be moved into the Database Items area (into the data block).

Item names for the selected objects

After you select part of an available column object to become a data item in the block, the item's default name takes the form ColumnObjectName_AttributeName.  For instance, in the customer table example above, if you select city, it will appear in the Database Items area as custaddr_city  You would use this compound name for the item in any coding in your application.  (The name of the item's column name property is a slightly different format; it uses a dot or period as a connector, rather than an underscore.)

About selecting REF columns

Normally, column objects contain data.  REF columns, however, are a special type of object column; instead of containing data, they contain pointers to data that resides in other object tables.

How REFs appear in the Available Columns area

REFs are shown expanded, listing the object attributes they point to.  For example, if we defined dept_type as being an object type having three attributes -- deptnum, deptname, and deptloc, and we then defined a table having a REF column named deptref with type ref(dept_type), then the values in column deptref point to rows in a table having attributes of deptnum, deptname, and deptloc.  In the Available Columns area, we would see:

      R deptref

      + deptref

            - deptnum

            - deptname

            - deptloc

Note that the REF column (deptref, in this case) appears twice.  The first is the REF as a pointer.  The second is a label for the composite parts (attribute columns) of the object being pointed to.  This double listing allows you to make different types of choices, as explained below.  Basically, your choice establishes where the data will be displayed at runtime -- in the pointing block or in the pointed-to block.

How to make your REF selection

As with a regular column object, you can select any or all of a REF 's attribute columns.  Selecting the second instance of the REF name selects all its parts.

When you select one or more of the REF's attribute columns, they will appear as normal data items in the data block at runtime.  Forms Developer and Oracle8 will obtain the data values from the referenced table and show those values in this block.  (This is sometimes called a look-up technique.)  To the user, the REF data items appear no different than regular data items.

You can also select the REF itself (the first entry in the Available Columns area) to become a programmable item in your application.  (This is in contrast to regular column objects, where the name is just a label.)  Selecting the REF itself allows the data block to become a detail block in a REF-based master-detail relationship.

When you select the REF itself as an item, it is placed (by default) on the Null Canvas.  Although the REF item will  not appear on the canvas to the runtime user, it is available in the application for coding purposes.


Data Block Wizard:  Creating LOVs for REFs

  Next Step 	  About the Wizard

If the data block’s end users are going to change values in a REF lookup field, they need to have a LOV (list of values) available from which they can choose the appropriate new value.

The Data Block Wizard presents you with this window, which gives you an easy way to create the LOV.

Steps to create the LOV

First, select the REF desired.  (If only one REF exists in this block, only one will be listed in this window.)

For the REF you selected, the Wizard will list all the associated tables in the database.  (Remember that REFs are defined on object types, not on specific tables, and therefore a REF can potentially point to multiple tables.)

From this list of tables, select the particular table you want.  The Wizard will build the LOV from the values in this table.

The same LOV gets attached to all the lookup items associated with a particular REF.

Changing the LOV

The Data Block Wizard only creates an initial LOV for you.  It does not maintain it.

If you later make changes to the REF or other data structures that affect the LOV, you should use the LOV Wizard to make any associated changes required in the LOV .

You can also use the LOV Wizard if you want to adjust the format of this initial LOV.

Wizard Re-entry

If you later re-enter the Data Block Wizard for this block, and you check the ‘create LOV’ box, a new LOV will be created.  (The old LOV will not be deleted, but the lookup items will be attached to the new LOV.)


Data Block Wizard: Selecting a stored procedure

  Next Step 	  About the Wizard

To select a stored procedure as the data source for your data block, you must specify an individual procedure for querying records for the data block.  You also can specify procedures for inserting, updating, deleting, and locking records.  The Data Block Wizard provides a page for each of the above functions.

Notes:

Selecting a stored procedure as the data source for your data block is an advanced technique.  You should be familiar with Oracle PL/SQL programming before you choose this option.

In Release 6.0, Forms supports only stored procedures that use and return relational, scalar values.  It does not yet support stored procedures that use/return object values.


Data Block Wizard: Query page

  Next Step 	  About the Wizard

To select a QUERY procedure:

1	On the Query page, in the Procedure field, enter the name of the procedure that will retrieve information for the data block.

2	Click Refresh.

If you are not connected to a database, the wizard displays the Connect dialog.

To map a column from the stored procedure to a database item in the data block:

1	Select the column.

2	Drag-and-drop the column or click  [image]  to move the selected column(s) from the Available Columns list to the Database Items list.

3	When you move a column from the Available Columns list to the Database Items list, if the item:

•	does not already exist in the data block, the wizard will create a new item and set its Database Item property to Yes.

•	already exists in the data block, the wizard automatically will set the item's Database Item property to Yes.

4	To move all available columns, click  [image] .

Hint:  Be sure to map all primary-key and other mandatory columns from the stored procedure to items in the data block.

To move a column out of the data block:

1	Select the column.

2	Drag-and-drop the column to the Database Items list or click  [image]  or  [image] .

3	When you move a column from the Database Items list to the Available Columns list, if the item:

•	does not already exist in the data block, no item based on the column will appear in the data block.

•	already exists in the data block, the item will remain in the data block, but the wizard automatically will set the item's Database Item property to No.

To specify a value for an argument:

•	 Enter it in the Value field.


Data Block Wizard: Insert page

  Next Step 	  About the Wizard

To select an INSERT procedure:

1	On the Insert page, in the Procedure field, enter the name of the procedure that will insert information for the data block, and click Refresh.

2	To specify a value for an argument, enter it in the Value field.


Data Block Wizard: Update page

  Next Step 	  About the Wizard

To select an UPDATE procedure:

1	On the Update page, in the Procedure field, enter the name of the procedure that will update information for the data block, and click Refresh.

2	To specify a value for an argument, enter it in the Value field.


Data Block Wizard: Delete page

  Next Step 	  About the Wizard

To select a DELETE procedure:

1	On the Delete page, in the Procedure field, enter the name of the procedure that will delete information for the data block, and click Refresh.

2	To specify a value for an argument, enter it in the Value field.


Data Block Wizard: Lock page

  Next Step 	  About the Wizard

To select a LOCK procedure:

1	On the Lock page, in the Procedure field, enter the name of the procedure that will lock data for the data block, and click Refresh.

2	To specify a value for an argument, enter it in the Value field.


Data Block Wizard: Master-Detail page

  Next Step 	  About the Wizard

This page appears when your form already contains one or more completed data blocks.  The wizard gives you the opportunity to establish a master-detail relationship between the block you are currently working on and one of those other blocks.  (The wizard assumes the block you are currently working on is the detail block; and the already-created blocks are potential master blocks.)

The logical link between the data blocks can be a join condition (primary-key foreign-key relationship) or a REF pointer link.

If there is only one candidate for the master block and only one possible logical link, your master-detail creation is straightforward.  If there are several candidate blocks, and/or multiple logical links, the wizard lists them, and you then choose the master block and the specific link that you want.

The wizard also gives you the choice of building the linking condition yourself or having the wizard create it for you.

To create a master-detail relation:

First, choose a setting for the Auto-Join Data Blocks checkbox.  Checking the box means the wizard will build the linking condition for you.  In most situations, this is the simplest and easiest approach.

With Auto-Join selected:

1	On the Master-Detail page, click Create Relationship.

(If you are not connected to a database, the wizard displays the Connect dialog.  Sign on to the desired database.)

When you click Create Relationship, the wizard queries the database and displays (in its Data Blocks dialog window) all the data blocks in your form that are potential master blocks.  For each of these potential master blocks, the wizard also displays the block's associated foreign-key constraint name and/or the REFs pointing to it.

If no potential master blocks exist, the wizard displays an error message:
      FRM-10757: No master data blocks are available.

2	In the Data Blocks dialog window, select a master data block and the desired link, and click OK.

3	The wizard automatically interprets the foreign-key relationship or REF link between the data blocks' tables, displays it in the Join Condition field, and displays the name of the master block in the Master Data Blocks field.  (You can use the Detail Item and Master Item poplists to modify the auto-created join condition, although normally that is not necessary).

Without Auto-Join:

1	On the Master-Detail page, click Create Relationship.

(If you are not connected to a database, the wizard displays the Connect dialog.  Sign on to the desired database.)

When you click Create Relationship, the wizard queries the database and displays (in its Data Blocks dialog window) all the data blocks in your form that are potential master blocks.  The wizard does not display any foreign key or REF pointer information.

2	In the Data Blocks dialog window, select a master data block, and click OK.  The wizard displays the name of the master block in the Master Data Blocks field

3	Use the Detail Item and Master Item poplists to build a join condition manually.

Results

Once you specify the master data block and the join condition or REF, the wizard does the following:

•	displays the new relation object under the master data block's node in the Object Navigator

•	sets the properties of the new relation object to default values

•	if the relation is based on a REF pointer,  sets the Include REF Item property in the master block to Yes, and sets the Copy_Value_From_Item property in the detail block to access this REF item.

•	gives the relation a default name in the form:

      MasterDataBlock_DetailDataBlock

To delete a master-detail relation:

On the Master-Detail page, select the master block from the list, and then click Delete Relationship.  The wizard deletes the relation, and any triggers associated with the relation.


Data Block Wizard: Finish page

  About the Wizard 	  Related Topics

What's next?

Having finished creating the data block, you now have two choices:

•	exit the Data Block Wizard and immediately invoke the Layout Wizard (where you can layout the items of the data block in a frame on a canvas)

•	just exit the Data Block Wizard

If you choose to invoke the Layout Wizard, the wizard will walk you through the steps of selecting a canvas on which to display your data block items, specifying which items to display in the layout, selecting prompts and height/width for the items, creating a frame (including style and title) in which to display the items, and choosing the number of records to display in the frame and the distance between those records.  Using the Layout Wizard to layout the items of your data block is highly recommended, as the wizard automates all tasks required to create the basic layout.

If you choose to simply exit the Data Block Wizard without invoking the Layout Wizard, you have two choices:

•	manually layout the data block items

•	invoke the Layout Wizard at a later time

To manually layout the items of your data block, you must create a canvas, create frames on that canvas (optional), place items inside the frames or just on the canvas, and arrange all the items on the frame or canvas.

To invoke the Layout Wizard at a later, simply select the data block's frame in the Object Navigator (under the Canvases node) or Layout Editor, and choose Tools [image] Layout Wizard from the menu.


Dynamic Data Exchange

This chapter provides information on Dynamic Data Exchange (DDE) in Form Builder.  The topics covered include:

•	About DDE  14 - 584

•	Limitations  14 - 584

•	Function Overview   14 - 585

•	Function Descriptions   14 - 586

•	Microsoft Windows Predefined Data Formats  14 - 597

•	Exceptions   14 - 598


About DDE

Form Builder for Microsoft Windows supports Dynamic Data Exchange(DDE), a mechanism by which applications can communicate and exchange data.  DDE client support is a procedural extension to Form Builder for Microsoft Windows.  A PL/SQL package for DDE support provides application developers with an Application Programming Interface(API) for accessing DDE functionality from within PL/SQL procedures and triggers.

The DDE functions enable Form Builder, a DDE client application, to communicate with DDE server applications in the following ways:

•	by importing data

•	by exporting data

•	by executing commands against the DDE server


Form Builder DDE Limitations

Form Builder does not include the following:

•	Data linking (advise transaction)

Form Builder cannot automatically receive an update notice when a data item has changed.

•	Server support

Form Builder cannot respond to commands or requests for data from a DDE client; Form Builder must initiate the DDE conversation using DDE.APP_BEGIN (although data may still be transferred in either direction).


DDE Functions Overview

As part of the DDE package, the DDE functions available from within PL/SQL procedures and triggers can be grouped into the following categories:

•	Support functions

•	Connect/Disconnect functions

•	Transaction functions

•	Data type Translation functions

Support Functions

These functions are used to start and stop other DDE Server applications.

DDE.APP_BEGIN	Begins a DDE server application.
DDE.APP_END	Ends a DDE server application.
DDE.APP_FOCUS	Focuses a DDE server application.
Connect/Disconnect Functions

These functions are used to connect to and disconnect from DDE server applications.

DDE.INITIATE	Starts a DDE conversation with a DDE server application.
DDE.TERMINATE	Ends a DDE conversation with a DDE server application.
Transaction Functions

These functions are used to exchange data with DDE server applications.

DDE.EXECUTE	Executes a command recognized by a DDE server application.
DDE.POKE	Supplies information to a DDE server application.
DDE.REQUEST	Requests information from a DDE server application.
Data Type Translation Functions

These functions are used to translate DDE data type constants to strings and back; in addition, DDE.GETFORMATNUM allows users to register a new data format that is not predefined by Microsoft Windows.  Note that these functions do not translate the data itself (all DDE data is represented with the CHAR data type in PL/SQL), just data type constants.

DDE.GETFORMATNUM	Convert/register a data format string to a number.
DDE.GETFORMATSTR	Convert a data format number to a string.


DDE.APP_BEGIN

 Examples

Description

Begins a conversation with a DDE server application program.

Syntax

DDE.APP_BEGIN (Command, Mode)

Parameters

Parameter	Type	Description
Command	VARCHAR2	command line for executing a program
Mode	PLS_INTEGER	application window starting mode
Returns  PLS_INTEGER

Notes

In the Command string, the DDE server application program name can include a path.  If the DDE server application name does not include a path, then the following directories are searched:

•	the current directory

•	the Windows directory

•	the Windows system directory

•	the directory containing the executable file for the current task

•	the directories listed in the PATH environment variable

•	the directories mapped in a network

The DDE server application program name may be followed by arguments, which should be separated from the application program name with a space.

Start the DDE server application in either normal, minimized, or maximized size with the mode parameter.  The application mode constants for DDE.APP_BEGIN are the following:

Mode	Description
DDE.APP_MODE_NORMAL	Start application window in normal size.
DDE.APP_MODE_MINIMIZED	Start application window in minimized size.
DDE.APP_MODE_MAXIMIZED	Start application window in maximized size.
This function returns an application identifier that is a PLS_INTEGER. The application identifier is used in all subsequent calls to DDE.APP_END and DDE.APP_FOCUS for that application window.


DDE.APP_BEGIN examples

DECLARE
AppID   PLS_INTEGER;
BEGIN
/* Start Microsoft Excel with spreadsheet emp.xls loaded. */
AppID := DDE.App_Begin('C:\excel\excel.exe C:\emp.xls',
 DDE.APP_MODE_MINIMIZED);
END;


DDE.APP_END

 Examples	   Restrictions

Description

Ends a DDE server application program that DDE_APP_BEGIN starts.

Syntax

DDE.APP_END (AppID)

Parameters

Parameter	Type	Description
AppID	PLS_INTEGER	Application identifier that is returned from DDE.APP_BEGIN
Notes

The DDE server application can also be terminated in standard Microsoft Windows fashion, such as by double-clicking the Control menu.


DDE.APP_END restrictions

To terminate a DDE server application, the DDE server application must have been previously started by calling DDE.APP_BEGIN.


DDE.APP_END examples

DECLARE
AppID  PLS_INTEGER:
BEGIN
/* Start Microsoft Excel with spreadsheet emp.xls loaded. */
AppID := DDE.App_Begin('C:\excel\excel.exe C:\emp.xls'
DDE.APP_MODE_NORMAL);
...
/* End Microsoft Excel program. */
DDE.App_End(AppID);
END;


DDE.APP_FOCUS

 Examples	   Restrictions

Description

Activates a DDE server application program started by DDE.APP_BEGIN.

Syntax

DDE.APP_FOCUS (AppID)

Parameters

Parameter	Type	Description
AppID	PLS_INTEGER	application identifier returned by DDE.APP_BEGIN
Notes

The application can also be activated in standard Microsoft Windows fashion, such as by clicking within the application window.


DDE.APP_FOCUS restrictions

To activate a DDE server application, the DDE server application must have been previously started by calling DDE.APP_BEGIN.


DDE.APP_FOCUS examples

DECLARE
AppID   PLS_INTEGER;
BEGIN
/* Start Microsoft Excel application in fullscreen mode. */
AppID := DDE.App_Begin('C:\excel\excel.exe,
DDE.APP_MODE_MAXIMIZED);
/* Activate the application window. */
DDE.App_Focus(AppID);
END;


DDE.EXECUTE

 Examples

Description

Executes a command string that is acceptable in the receiving DDE server application.

Syntax

DDE.EXECUTE (ConvID, Command, Timeout)

Parameters

Parameter	Type	Description
ConvID	PLS_INTEGER	DDE conversation id
Command	VARCHAR2	Command string for the server to execute
Timeout	PLS_INTEGER	Timeout duration in milliseconds
Notes

The value of Command depends on what values are supported by the server application.

Timeout specifies the maximum length of time, in milliseconds, that this routine waits for a response from the DDE server application.  If the user specifies an invalid number, such as negative number, then the default value of 1000 ms is used.  The duration of the timeout depends on machine configuration and the DDE server application.


DDE.EXECUTE examples

DECLARE
ConvID   PLS_INTEGER;
BEGIN
/* Open a DDE conversation with Microsoft Excel for Windows */
ConvID := DDE.Initiate('EXCEL', 'C:\abc.xls');
/* Recalculate the Excel spreadsheet.*/
DDE.Execute(ConvID, '[calculate.now()]', 1000);
END;


DDE.GETFORMATNUM

 Examples

Description

Translates or registers a specified data format name and returns a format number.

Syntax

DDE.GETFORMATNUM (FormatStr)

Parameters

Parameter	Type	Description
FormatStr	VARCHAR2	Data format name string
Returns  PLS_INTEGER

Notes

This function converts a data format from a string to a number.  This number can be used in Poke and Request transactions to represent the  DataFormat parameter.

If the specified name is not registered, this function registers it and returns a unique format number.  This is the only way to use a format in a Poke or Request transaction that is not one of the predefined formats.

This function returns the numeric representation of the data format string that is a PLS_INTEGER.

See Microsoft Windows Predefined Data Formats for the predefined data format constants.


DDE.GETFORMATNUM examples

DECLARE
FormatNum   PLS_INTEGER;
MyFormatNum PLS_INTEGER;
BEGIN
/* Get predefined format number for "CF_TEXT"
(should return CF_TEXT=1). */
FormatNum := DDE.GetFormatNum('CF_TEXT');
/* Register a user-defined data format called "MY_FORMAT". */
MyFormatNum := DDE.GetFormatNum('MY_FORMAT');
END;


DDE.GETFORMATSTR

 Examples

Description

Translates a data format number into a format name string.

Syntax

DDE.GETFORMATSTR (FormatNum)

Parameters

Parameter	Type	Description
FormatNum	PLS_INTEGER	Data format number

Returns  CHAR

Notes

This function returns the string representation of the data format number that is a CHAR.

This function returns a data format name if the data format number is valid.  Valid format numbers include Microsoft Windows Predefined Data Formatsand any user-defined formats that were registered with DDE.GETFORMATNUM.


DDE.GETFORMATSTR examples

DECLARE
FormatStr   CHAR(20);
BEGIN
/* Get a data format name
(should return the string 'CF_TEXT') */
FormatStr := DDE.GetFormatStr(CF_TEXT);
END;


DDE.INITIATE

 Examples

Description

Opens a DDE conversation with a DDE server application.

Syntax

DDE.INITIATE (Service, Topic)

Parameters

Parameter	Type	Description
Service	VARCHAR2	DDE Server application's DDE service code
Topic	VARCHAR2	Topic name for the conversation
The values of Service and Topic depend on the values supported by a particular DDE server application.  Service is usually the name of the DDE server application program.  For applications that operate on file-based documents, Topic is usually the document filename; in addition, the System topic is usually supported by each service.

Returns  PLS_INTEGER

Notes

An application can start more than one conversation at a time with multiple services and topics, provided the conversation identifiers are not interchanged.

This function returns the DDE conversation identifier that is a PLS_INTEGER.  The conversation identifier that is returned must be used in all subsequent Execute, Poke, Request, and Terminate calls for that conversation.

To terminate the conversation, you should call DDE.TERMINATE.


DDE.INITIATE examples

DECLARE
ConvID   PLS_INTEGER;
BEGIN
/* Open a DDE conversation with Microsoft Excel for Windows
 on topic abc.xls. */
ConvID := DDE.Initiate('EXCEL', 'c:\abc.xls');
END;


DDE.POKE

 Examples

Description

Sends data to a DDE server application.

Syntax

DDE.POKE (ConvID, Item, Data, DataFormat, Timeout)

Parameters

Parameter	Type	Description
ConvID	PLS_INTEGER	DDE conversion identifier that is returned by DDE.INITIATE
Item	VARCHAR2	Data item name to which the data is to be sent
Data	VARCHAR2	Data buffer to send
DataFormat	PLS_INTEGER	Format of outgoing data
Timeout	PLS_INTEGER	Timeout duration in milliseconds
The value of Item depends on what values are supported by the DDE server application on the current conversation topic.

The Microsoft Windows Predefined Data Formats can be used for DataFormat.  A user-defined format that is registered with DDE.GETFORMATNUM can also be used, provided the DDE server application recognizes the format.  It is your responsibility to ensure that the DDE server application processes the specified data format.

Timeout specifies the maximum length of time, in milliseconds, that this routine waits for a response from the DDE server application.  If you specify an invalid number, such as negative number, then the default value of 1000 ms is used.  The duration of the timeout depends on machine configuration and the DDE server application.


DDE.POKE examples

DECLARE
ConvID   PLS_INTEGER;
BEGIN
/* Open a DDE conversation with Microsoft Excel for Windows on
topic abc.xls. */
ConvID = DDE.Initiate('EXCEL', 'C:\abc.xls');
/* Send data "foo" to cell at row 2, column 2. */
DDE.Poke(ConvID, 'R2C2', 'foo', DDE.CF_TEXT, 1000);
END;


DDE.REQUEST

 Examples

Description

Requests data from a DDE server application.

Syntax

DDE.REQUEST (ConvID, Item, Buffer, DataFormat, Timeout)

Parameters

Parameter	Type	Description
ConvID	PLS_INTEGER	DDE conversion identifier returned by DDE.INITIATE
Item	VARCHAR2	Requested data item name
Buffer	VARCHAR2	Return data buffer
DataFormat	PLS_INTEGER	Format of requested data
Timeout	PLS_INTEGER	Timeout duration in milliseconds
The value of Item depends on what values are supported by the DDE server application on the current conversation topic.

Be aware that the Buffer parameter determines the length of the return string.  It is your responsibility to ensure that the return data buffer is large enough for the requested data.  If the buffer size is smaller than the requested data, the data is truncated and an error may occur.

Microsoft Windows Predefined Data Formats can be used for DataFormat.  A user-defined format that is registered with DDE.GETFORMATNUM can also be used, provided  the DDE server application recognizes this format.  It is your responsibility to ensure that the DDE server application will process the specified data format.

Timeout specifies the maximum length of time, in milliseconds, that this routine waits for a response from the DDE server application.  If you specify an invalid number, such as negative number, then the default value of 1000 ms is used.  The duration of the timeout depends on machine configuration and the DDE server application.


DDE.REQUEST examples

DECLARE
ConvID   PLS_INTEGER;
Buffer   CHAR(100);
BEGIN
/* Open a DDE conversation with Microsoft Excel for Windows on
topic abc.xls. */
ConvID := DDE.Initiate('EXCEL', 'C:\abc.xls');
/* Request data from 6 cells between row 2, column 2
and row 3, column 4. */
DDE.Request(ConvID, 'R2C2:R3C4', Buffer, DDE.CF_TEXT,1000);
END;


DDE.TERMINATE

 Examples	   Restrictions

Description

Terminates the specified conversation with a DDE server application.

Syntax

DDE.TERMINATE (ConvID)

Parameters

Parameter	Type	Description
ConvID	PLS_INTEGER	DDE conversion identifier returned by DDE.INITIATE
Notes

After the DDE.TERMINATE call, all subsequent Execute, Poke, Request, and Terminate requests using the terminated conversation identifier will result in an error.


DDE.TERMINATE restrictions

Use DDE.INITIATE to start a DDE conversation with a server application before attempting to use DDE.TERMINATE.


DDE.TERMINATE examples

DECLARE
ConvID   PLS_INTEGER;
BEGIN
/* Open a DDE conversation with Microsoft Excel for Windows
on topic abc.xls. */
ConvID := DDE.Initiate('EXCEL', 'C:\abc.xls');
...
/* Terminate the Microsoft Excel for Windows conversation */
DDE.Terminate(ConvID);
END;


Microsoft Windows Predefined Data Formats

Format	Description
DDE.CF_BITMAP	The data is a bitmap.
DDE.CF_DIB	The data is a memory object containing a BITMAPINFO structure followed by the bitmap data.
DDE.CF_DIF	The data is in Data Interchange Format (DIF).
DDE.CF_DSPBITMAP	The data is a bitmap representation of a private format.  This data is displayed in bitmap format instead of the privately formatted data.
DDE.CF_DSPMETAFILEPICT	The data is a metafile representation of a private data format.  This data is displayed in metafile-picture format instead of the privately formatted data.
DDE.CF_DSPTEXT	The data is a textual representation of a private data format.  This data is displayed in text format instead of the privately formatted data.
DDE.CF_METAFILEPICT	The data is a metafile.
DDE.CF_OEMTEXT	The data is an array of text characters in the OEM character set.  Each line ends with a carriage return-linefeed (CR-LF) combination.  A null character signals the end of the data.
DDE.CF_OWNERDISPLAY	The data is in a private format that the clipboard owner must display.
DDE.CF_PALETTE	The data is a color palette.
DDE.CF_PENDATA	The data is for the pen extensions to the Microsoft Windows operating system.
DDE.CF RIFF	The data is in Resource Interchange File Format (RIFF).
DDE.CF_SYLK	The data is in Microsoft Symbolic Link (SYLK) format.
DDE.CF_TEXT	The data is an array of text characters.  Each line ends with a carriage return-linefeed (CR-LF) combination.  A null character signals the end of the data.
DDE.CF_TIFF	The data is in Tag Image File Format (TIFF).
DDE.CF_WAVE	The data describes a sound wave.  This is a subset of the CF_RIFF data format; it can be used only for RIFF WAVE files.


Exceptions

Exception	Description
DDE.DDE_APP_FAILURE	An application program specified in a DDE.APP_BEGIN call could not be started.
DDE.DDE_APP_NOT_FOUND	An application ID specified in a DDE.APP_END or DDE.APP_FOCUS call does not correspond to an application that is currently running.
DDE.DDE_FMT_NOT_FOUND	A format number specified in a DDE.GETFORMATSTR call is not known.
DDE.DDE_FMT_NOT_REG	A format string specified in a DDE.GETFORMATNUM call does not correspond to a predefined format and could not be registered as a user-defined format.
DDE.DDE_INIT_FAILED	The application was unable to initialize DDE communications, which caused a call to the DDE layer to fail.
DDE.DDE_PARAM_ERR	An invalid parameter, such as a NULL value, is passed to a DDE package routine.
DDE.DMLERR_BUSY	A transaction failed because the server application is busy.
DDE.DMLERR_DATAACKTIMEOUT	A request for a synchronous data transaction has timed out.
DDE.DMLERR_EXECACKTIMEOUT	A request for a synchronous execute transaction has timed out.
DDE.DMLERR_INVALIDPARAMETER	A parameter failed to be validated.  Some of the possible causes are as follows: The application used a data handle initialized with a different item-name handle or clipboard data format than that required by the transaction. The application used an invalid conversation identifier.More than one instance of theapplication used the same object.
DDE.DMLERR_MEMORY_ERROR	A memory allocation failed.
DDE.DMLERR_NO_CONV_ESTABLISHED	A client's attempt to establish a conversation has failed.  The service or topic name in a DDE.INITIATE call may be in error.
DDE.DMLERR_NOTPROCESSED	A transaction failed.  The item name in a Poke or Request transaction may be in error.
DDE.DMLERR_POKEACKTIMEOUT	A request for a synchronous poke transaction has timed out.
DDE.DMLERR_POSTMSG_FAILED	An internal call to the PostMessage function has failed.
DDE.DMLERR_SERVER_DIED	The server terminated before completing a transaction.
DDE.DMLERR_SYS_ERROR	An internal error has occurred in the DDE layer.


About the debugging process

  Related Topics

Debugging an application is an iterative process in which application errors are identified and corrected.  In general, quickly identifying and locating failing code is essential to successfully debugging your application.

If erroneous code cannot be located, run the application with debug messages.  When you run with debug messages, an alert appears whenever an event occurs that will cause a trigger to execute.

After identifying the location, use the Debugger to create debug actions (breakpoints and debug triggers) to isolate the failing code to a specific region or number of statements.

After narrowing the failing code to a specific region, use the Debugger to correct and test possible code fixes.


Debugging a form

To debug a form, perform the following steps:

1	Run the form in Debug mode.  Form Builder displays the Debugger.

Note:  Initially, you should close the Debugger to observe your application's behavior.  After identifying a problem area, invoke the Debugger.

2	In the Debugger, create the desired debug actions.

3	Close the Debugger.  Form Builder runs your form.

4	Browse your debug actions and evaluate application information.

5	Modify and test runtime code fixes within the Debugger.

6	Implement your code fixes using Form Builder.


About running a form in debug mode

  Related Topics

When you run your form in debug mode, the Debugger appears initially, allowing you to create debug actions, such as breakpoints and debug triggers.

After creating debug actions, choose Close from the toolbar to dismiss the Debugger and run your form.  The Close command is required only initially at debug startup.

After you close the Debugger, it appears whenever program execution is interrupted (upon reaching a breakpoint) or whenever you choose Help [image] Debug from the menu.

To run an application in debug mode, you must first enable the Debug Mode option and then run your form.

Note:  By default, when you run your form by choosing Program [image] Run Form [image] Debug (or press Shift+Control+R), Form Builder first compiles your form and then runs it.  When Form Builder compiles a form with the Debug Mode option enabled, it creates an .FMX or an .MMX that contains source code symbols that you can view and edit at runtime.  Access to your source code is essential to debugging your form.

If you do not compile with the Debug Mode option enabled, you will not be able to view or edit your source code at runtime.  Remember that the Debug Mode option is both a design-time and a compile option.


About debug messages

  Related Topics

When an application runs in debug mode with debug messages enabled, Form Builder displays a message box whenever an event occurs that will cause a trigger to execute.

Debug messages are displayed on the message line.  Each message specifies the name of the trigger that is being executed and the name of the object (form, block, or item) to which it is attached.


Displaying debug messages

To display debug messages at runtime:

Set the Debug Message preference On by including the Debug keyword (DEBUG_MESSAGES=YES) in the commands to run your application.  For example, on MS Windows:

IFRUN60 formname username/password debug_messages=YES


About the debugger

  Related Topics

When you run your form in debug mode, the Debugger appears, allowing you to create debug actions, such as breakpoints and debug triggers.  After you close the Debugger, it becomes active whenever program execution is interrupted (upon reaching a breakpoint) or whenever you choose Help [image] Debug from the menu.

A typical debug session centers around the Object Navigator.  Using the Object Navigator, you can inspect and modify program units, global variables, form item values, and so on.


About debugger features

  Related Topics

Debugging features include the following:

•	Direct manipulation debugging--insert debug actions and inspect program data by directly manipulating displayed source text.

•	Dynamic execution feedback--Form Builder automatically displays and tracks the current PL/SQL source location as program execution is interrupted by debug actions or incrementally advanced during program stepping.

•	Browsing of interrupted program state--once execution has been interrupted, it is possible to  browse the current stack, browse and modify variable state, and execute arbitrary PL/SQL statements.  All information is accessed symbolically (i.e., by name as opposed to by address or number).


About the Debugger window

  Related Topics

The Debugger has five main elements: the Debugger menu, Toolbar, the Source pane, the Object Navigator pane, and the Interpreter pane.


About the Debugger menu

  Related Topics

The Debugger menu includes three menus: View, Debug, and Navigator.

View Menu  The View menu contains the following menu items:

Source Pane	Shows the Source pane.
Object Navigator Pane	Shows the Object Navigator pane.
Interpreter Pane	Shows the Interpreter pane.
Interpreter Log	The LOG command saves a transcript of Debugger input and output to the specified log file.
Debug Menu  The Debug menu contains the following menu items:

Break...	Displays the Breakpoint dialog box, which allows you to create a breakpoint in a program unit.
Trigger...	Displays the Trigger dialog box, which allows you to create a debug trigger in a program unit.
Edit	Invokes the Program Unit Editor and displays the source of the program unit selected in the Object Navigator.
Step	Executes the STEP command in the Interpreter pane.  The STEP command advances execution of an interrupted program unit and returns control to the current debug level after the specified set of statements have been executed.
Go	Executes the GO command in the Interpreter pane.  The GO command resumes program execution until the currently executing thread of execution either terminates or is interrupted by a debug action.
Reset	The Reset command returns control to an outer debug level without continuing execution in the current debug level.

Navigator Menu  In addition to the standard design-time Navigator menu items (Create, Delete, Compile, etc.), the Debug mode Navigator menu includes two debug menu options:

Disable	Disables the debug action selected in the Object Navigator pane.
Enable	Enables the debug action selected in the Object Navigator.


About the debugger toolbar

  Related Topics

The Debugger toolbar includes these icons:

Step Into	Executes the STEP INTO command enables stepping into subprogram calls.
Step Over	The STEP OVER command executes called subprograms without stepping into a called subprogram body.
Step Out	The STEP OUT resumes execution until the current subprogram has returned.
Go	Executes the GO command in the Interpreter pane.  The GO command resumes program execution until the currently executing thread of execution either terminates or is interrupted by a debug action.
Reset	The Reset command returns control to an outer debug level without continuing execution in the current debug level.
Close	When you run in Debug mode, the Debugger appears initially, allowing you to create debug actions prior to form startup.  After creating your debug actions, choosing Close runs your form.
Create	Allows you to create a new program unit.
Delete	Deletes the program unit selected in the Navigator Pane.
Expand	Expands a currently selected node in the Navigator Pane.
Collapse	Collapses a currently selected node in the Navigator Pane.
Expand All	Expands all nodes under the currently selected node.
Collapse All	Collapses all nodes under the currently selected node.
Find	Allows you to navigate to a named program unit in the Navigation Pane by typing the name of the object into this text box.


About the source pane

  Related Topics

The Source pane displays a read-only copy of the program unit currently selected in the Object Navigator pane.

The numbers along the left hand margin correspond to the line numbers of the displayed program unit.

In addition, the symbols described below may appear in the margin.

|	Specifies the current source location.
=>	Specifies the current scope location.
-	Specifies the current execution location (if different from the current scope location).
B(n)	Specifies the location of a breakpoint, where n is the corresponding debug action ID.  It appears in the line number column.
T(n)	Specifies the location of a trigger, where n is the corresponding debug action ID.  It appears in the line number column.


About the object navigator pane

  Related Topics

The Object Navigator displays information about the current state of an Form Builder application.   Use this information to analyze the internal processing that takes place as your application runs.   You can also modify system variables, global variables, and item values.

The hierarchical display includes the following nodes:

Modules	Lists all the modules included in the form.  Under this node for each module are listed all the program units, attached libraries, triggers, blocks, items, parameter lists, subprograms,  references, and value for each object.
Global Variables	Lists all the global variables and values.
System Variables	Lists the current system variables.
Command Line Parameters	Lists the command line parameters and values for the current instance of Forms Runtime.
Built-In Packages	Lists the available Built-in packages, including the DEBUG package.
Debug Actions	Lists any breakpoint or triggers you have created in the debugger.
Stack	Lists all the local variables in the form.
Database Objects	Lists the objects in the currently attached databases.
Click the plus signs [image] to display more nodes.


About the interpreter pane

  Related Topics

The Interpreter pane provides a command line interface, allowing you to enter PL/SQL constructs and debugger commands.


About debug actions

  Related Topics

The debugger can be invoked from form code (triggers, user-named program units, libraries, etc.) by creating debug actions in the code.   These are instructions which interrupt the execution of PL/SQL program units so they can be monitored.  There are two types of debug actions: breakpoints and debug triggers.

Each debug action you create is automatically assigned a unique numeric ID.  While debugging, you can refer to this ID to browse, display, or modify a specific debug action via Form Builder debug commands.

You can display detailed information about one or more debug actions, including its ID, source location, and whether or not it is enabled.   You can temporarily disable specific debug actions and then re-enable them later if necessary.

Breakpoints suspend execution at a specific source line of a program unit, passing control to the Debugger.

Create breakpoints to identify specific debugging regions.  For example, create a breakpoint at lines 10 and 20 to debug the code within this region.

With breakpoints, suspension occurs just before reaching the line on which the breakpoint is specified.  At this point, use the Debugger's features to inspect and/or modify program state.  Once satisfied, resume execution with the GO or STEP commands, or abort execution using the RESET command.

Debug Triggers are a general form of debug action which associate a block of PL/SQL code with a specific source line within a program unit.  When a debug trigger is encountered, Form Builder executes the debug trigger code.

Create a debug trigger to execute a block of PL/SQL code provided at debug time:

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

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

•	at every PL/SQL source line being run

Debug triggers are especially useful as conditional breakpoints.  You can raise the exception DEBUG.BREAK from within a trigger.  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>line 10 is
+> IF Debug.Getn('my_sal') > 5000 THEN
+>   Raise Debug.Suspend;
+> END IF;


About creating a debug action

  Related Topics

Form Builder allows you to create debug actions (breakpoints and debug triggers) in three ways:

•	using the Break and Trigger menu commands

•	inserting debug actions in the Object Navigator pane

•	entering commands in the Interpreter pane

When you create a debug action, attach the breakpoint or debug trigger to a program unit source line that is "executable."  A source line is considered executable if it contains one or more statements for which the PL/SQL compiler generates code.  For example, source lines containing assignment statements and procedure calls are executable, while source lines containing comments, blank lines, declarations, or the NULL statement are not executable.


About the current execution location

  Related Topics

The current execution location specifies the next PL/SQL source line to be executed.  It corresponds to what is commonly referred to as the program counter, or PC.

When control passes to the Debugger while running a program (e.g., when a breakpoint is encountered or following a step operation), the Source pane in the Debugger automatically displays the source line associated with the current execution location.

Use the LIST command in the Interpreter pane to manually display the current execution location.

For example, entering:

.LIST PC

will list the current execution location in the Source pane.


About Debug levels

  Related Topics

When a debug action interrupts program execution, the Debugger 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.  Top level has no associated program state since it is the outermost level at which program units are originally invoked.  When code invoked from 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 Debugger command prompt reflects the current debug level.  When the Debugger enters levels below top level, the prompt includes a prefix containing the current debug level number.  For example, the Debugger command prompt at debug level 1 appears as shown below:

(debug 1)PL/SQL>


About the current scope location

  Related Topics

The current scope location dictates where the Debugger looks for local variables and parameters.  It corresponds to the current execution location of one of the PL/SQL subprograms on the stack.

Each time a program unit's execution is interrupted (e.g., by a debug action), the scope location is initialized to the execution location of the subprogram at the bottom of the stack.

Once execution has been interrupted, you can change the current scope location to another frame on the stack.  This enables you to view local variables in another subprogram in the call chain.


About modifying code at runtime

  Related Topics

At runtime, you can modify and compile any program unit, menu item command, or trigger that is not on the current stack.

Note: To modify an item on the current stack, first clear the stack by issuing the RESET command.

Although runtime code modification is not communicated back to the Designer, you can interactively test possible fixes, before returning to implement the eventual fix in the Designer.


About debug commands

  Related Topics

The following commands are available when using the Debugger.

CREATE  The CREATE command creates a new library that can be stored in either the file system or the current database.

DELETE  You can use the DELETE command to delete:

•	libraries that reside in the current database

•	library program units

•	program units

DESCRIBE  Use the DESCRIBE command to inspect a variable or parameter that is local to the current scope location.  The description includes the name, type, and value of the specified local.

EXPORT  Use the EXPORT command to write the source of one or more program units to a text file.

LIST  Use the LIST command to display the source text for program units, triggers, and debug actions.

LOG  The LOG command saves a transcript of Debugger input and output to the specified log file.

RESET  The RESET command returns control to an outer debug level without continuing execution in the current debug level.

SET  The SET command enables you to change the current scope location to a specified frame of the stack.  You can specify relative motion from the current stack frame to any other frame, or move to a particular subprogram on the stack.  There are several ways to invoke SET:

•	select a frame entry in the Object Navigator

•	enter the SET command in the Interpreter

SHOW  Use the SHOW command to list the name, type, and value of all variables and parameters at the current scope location.


About the DEBUG package

  Related Topics

When debugging your applications, use the DEBUG Package.

Note:  the DEBUG package is only available at runtime.  At runtime, the DEBUG package is displayed within the Built-in Packages node.

The DEBUG package contains procedures, functions, and exceptions that you can use when debugging your applications.

DEBUG.GETx Functions  The GETx functions in the DEBUG package enable you to retrieve the value of a variable or parameter that is local to the subprogram at the current scope location.  These functions are intended for use primarily within debug triggers.

DEBUG.SETx Functions  The SETx procedures in the DEBUG package enable you to set the value of a variable or parameter that is local to the subprogram at the current scope location.  These procedures are intended for use primarily within debug triggers.

DEBUG.SUSPEND Functions  The DEBUG.SUSPEND procedure suspends execution of the current program unit or trigger and transfers control to the Interpreter.

DEBUG.BREAK Functions  Use DEBUG.BREAK to enter a breakpoint from within the debugger.


About Debugger startup restrictions

When running a form in Debug mode, the Debugger is invoked prior to form-startup.  Although you can create debug actions at this point, many of the Form Builder built-in subprograms cannot be executed prior to form-startup.

Note:  Error-handling in Debug mode differs from default error-handling at runtime.  While in Debug mode, no ON-ERROR or ON-MESSAGE triggers fire. If the code you are executing generates any errors or messages, these will be shown in an alert.

The following list of built-in subprograms cannot be called prior to form-startup:

Abort_Query

Anchor_View

Bell

Block_Menu

Break

Call_Form

Call_Input

Call_Query

Clear_Block

Clear_Eol

Clear_Field

Clear_Form

Clear_Record

Close_Form

Commit_Form

Commit

Copy

Copy_Region

Count_Query

Create_Queried_Record

Create_Record

Cut_Region,

Default_Value

Delete_Record

Display_Error

Display_Page

Do_Key

Down

Duplicate_Record

Edit_Field

Enforce_Column_Security

Enter

Enter_Query

Execute_Query

Execute_Trigger

Exit_Form

Generate_Sequence_Number

Go_Form

Go_Record

Hide_Menu

Erase

Fetch_Records

Fire_Event

First_Record

Go_Block

Go_Field

Help

Hide_Page

Insert_Record

Last_Record

List_Values

Lock_Record

Logon

Logon_Screen

Logout

Macro

Message

Next_Field

Next_Form

Move_View

New_Form

Next_Block

Next_Key

Next_Record

Next_Set

Ohost

Open_Form

Paste_Region

Pause

Post

Print

Previous_Block

Previous_Form

Previous_Field

Previous_Record

Rollback_Form

Redisplay

Replace_Menu

Resize_View

Select_Records

Scroll_Down

Scroll_Up

Set_Input_Focus

Show_Keys

Show_Menu

Show_Page

Synchronize

Up

Update_Record

Validate


Running a form in debug mode

  Related Topics

To compile and run in debug mode from the Layout Editor:

1	Choose Tools [image] Preferences… to invoke the Preferences dialog.

2	On the Runtime Options tab, check the Debug Mode check box.

3	Click OK to accept the options.

4	Choose Program [image] Run Form to run the form.

To compile and run in debug mode from the command line:

Set the Debug Mode preference On by including the Debug keyword (DEBUG=YES) in the command to compile and run your application.  For example, on MS Windows:

IFCMP60 formname username/password debug=YES
IFRUN60 formname username/password debug=YES

Note:  When you compile your form with Debug Mode on, debug information (p-code) is incorporated into the .FMX runfile.  This information enables you to make runtime subprogram modifications.


Creating a breakpoint

  Related Topics

To create a breakpoint:

1	In the Object Navigator, select the desired program unit, trigger, or menu item command.  The Debugger displays your selection in the Source pane.

2	In the Source pane, select the line where the breakpoint will be attached.

3	Choose Debug [image] Break to invoke the Breakpoint dialog box .

4	Select the desired line and then click OK to create a breakpoint for the selected line.

Tip:  You can also create a breakpoint by double-clicking on the desired source line in the Source pane or by entering commands in the Interpreter pane.


About the Breakpoint Dialog box

The Breakpoint dialog box includes the following:

Breakpoint	Identifies the breakpoint as either a new breakpoint or as an existing breakpoint.  Existing breakpoints are numbered.
Cancel	Closes the dialog and cancels the operation.
Enabled	Indicates whether the breakpoint is enabled or disabled.  When you create a breakpoint, it is enabled by default.
Line	Specifies the line in a program unit at which to establish the breakpoint.
OK	Creates the breakpoint and closes the dialog.
Program Unit	Identifies the target program unit body.
Trigger	Defines a PL/SQL trigger for the breakpoint.  The trigger fires each time the breakpoint is reached.


Creating a debug trigger

  Related Topics

To create a debug trigger:

1	In the Object Navigator, click the desired program unit, trigger, or menu item command.  The Debugger displays your selection in the Source pane.

2	In the Source pane, click the line where the debug trigger will be attached.

3	Choose Debug [image] Trigger to invoke the Trigger dialog box .

4	Specify the trigger body.

For example, to create a debug trigger that interrupts program execution if the local NUMBER variable my_sal exceeds 5000, enter the following as the trigger body:

IF Debug.Getn('my_sal') > 5000 THEN
   raise Debug.Suspend;
END IF;

Note:  To create a debug trigger that contains multiple lines of text, include a BEGIN and an END statement around the code.

You must raise the DEBUG.SUSPEND exception from the DEBUG package if you want the Debugger to appear when this line is executed.  Otherwise, Form Builder executes the code silently and the Debugger does not appear.

5	Click OK to create a debug trigger for the selected line.

Tip:  You can also create a debug trigger by entering commands in the Interpreter pane.


About the Trigger dialog box

The Trigger dialog box includes the following:

Cancel	Closes the dialog and cancels the operation.
Enabled	Indicates whether the debug trigger is enabled or disabled.  When you create a debug trigger, it is enabled by default.
Line	Specifies the line in a program unit at which to establish the debug trigger.
Location	Specifies the source location of the debug trigger.  The Program Unit item indicates that the debug trigger location is entered in the Program Unit field and the Line field.  The Program Unit field and Line field are enabled only when the Program Unit item is the current chosen item in the Location drop-down list.  Placing a trigger on Debug Entry invokes the Debugger when program execution is suspended due to a breakpoint, program stepping, etc. Placing a trigger on Every Statement causes the specified block to be evaluated prior to executing every PL/SQL source line.
OK	Creates the debug trigger and closes the dialog box.
Program Unit	Identifies the target program unit body.
Trigger	Identifies the debug trigger as either a new debug trigger or as an existing debug trigger. Existing debug triggers are numbered.
Trigger Body	Specifies the PL/SQL code to be used as the body of the debug trigger.


Browsing debug actions

  Related Topics

To browse debug actions:

In the Object Navigator, expand the Debug Actions node.  The Object Navigator displays a list of the debug actions associated with the current form.

Or

In the Interpreter, use the DESCRIBE command to display information about a specific debug action.

For example, entering .DESCRIBE BREAK 1 in the Interpreter pane reveals the following about Breakpoint 1:

Breakpoint: 1
   Program Unit: Procedure Body <programunit_name>
Line: 3
Enabled: YES


Viewing debug action source

  Related Topics

To view debug action source:

1	In the Object Navigator, expand the Debug Actions node.

2	Click the desired debug action.  The source is then displayed in the Source pane.

Or

In the Interpreter, use the .LIST command.

For example, entering .LIST BREAKPOINT 1 in the Interpreter displays information about Breakpoint 1.


Disabling and enabling debug actions

  Related Topics

To disable/enable a debug action:

1	In the Object Navigator, double-click on the desired debug action.  The Breakpoint/Trigger dialog appears.

2	Check the Enabled check box to enable the debug action or uncheck the Enabled check box to disable the debug action.

Or

In the Interpreter, use the DISABLE command.

For example, entering .DISABLE BREAKPOINT 1 in the Interpreter pane disables breakpoint 1.


Removing debug actions

  Related Topics

To delete a debug action:

1	In the Object Navigator,  click the desired debug action.

2	Choose Navigator [image] Delete.

Or

In the Interpreter, use the DELETE command.

For example, entering .DELETE BREAK 1 in the Interpreter deletes breakpoint 1.


Saving debug actions

  Related Topics

The debug actions created within the Debugger are not saved and exist only in the current debug session.  Each time you start a debug session, you will have to create the desired debug actions for that session.

To reuse breakpoints from session to session, create your breakpoints at design-time by calling the BREAK built-in subprogram within the desired code.  The BREAK built-in subprogram provides the same functionality as a breakpoint created within the Debugger.

You can also create conditional breakpoints by adding conditional logic when using the BREAK built-in.

For example:

IF :emp.sal > 5000 THEN
   Break;
END IF;


Viewing subprogram references

To view subprogram references:

1	In the Object Navigator, select and expand the desired subprogram.

2	Select and expand either the References or Referenced By node.

The Object Navigator displays any subprogram references.

Note:  Referenced By shows the program units that call the current program unit.  References shows the program units that are called by the current program unit.


Examining the stack

The stack represents the chain of subprogram calls starting from the initial entry point down to the currently executing subprogram.

For example, if Procedure A calls Procedure B calls Procedure C and a statement in Procedure C is currently executing, the current call chain would appear as shown below:

Stack:

(0) A (Procedure Body) Line 3

(1) B (Procedure Body) Line 22

(2) C (Procedure Body) Line 5

Each subprogram call is represented by a frame on the stack.  A frame contains information about the corresponding subprogram call--its name, actual parameter values, local variable values, and the next statement to be executed.

Form Builder uses the standard debugging model of a downward growing stack, in which newly entered subprograms are added to the bottom of the stack.  Thus, 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.

Stack frames are numbered from 0 to N, where the 0th frame is at the top of the stack and the Nth frame is at the bottom.  Thus, the 0th frame corresponds to the original entry point, and the Nth frame corresponds to the currently executing subprogram.


Controlling program unit execution

  Related Topics

Once you have inspected and modified the program state, you can resume or terminate execution using the following features:

STEP	You can use the STEP command to temporarily resume execution of an interrupted program.  Control returns to the Debugger after the specified set of statements have been executed.  STEP Into or Over allows you to:  • execute the next statement (optionally descending into subprogram calls)  • resume execution until the current subprogram has returned  • continue execution until the specified source location is reached
GO	Use the GO command to resume program execution indefinitely--that is, until either the currently executing thread of execution terminates or it is interrupted again due to a debug action.
RESET	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 explicitly reset execution to any previous debug level, or you can simply reset to top level, which is the default.
 Execute these commands from either the debugger toolbar or by entering the command into the Interpreter pane.


Displaying the current scope location

To display the current scope location:

1	In the Object Navigator, expand the Stack node.

2	Expand the desired frame in the stack to reveal information about local variables and parameters.

Or

In the Interpreter, use the .LIST SCOPE command.


Modifying application variables

To modify a variable:

1	In the Object Navigator, expand the Global Variables node or the Stack node for local variables.

2	Select and expand the desired entry.  The Object Navigator displays any variables associated with the entry.

3	Click the existing value after the "=" then edit the value by entering the desired value.

Or

In the Interpreter, use the Debug.Getx and Debug.Setx packages to modify the desired variable.


Modifying item values

To modify a form item value:

1	In the Object Navigator, select and expand the desired Module, Block, and Item nodes, then select the desired item.

The Object Navigator displays any form item values associated with the current stack.

2	Click the existing value after the "=" then edit the value by entering the desired value.


Modifying code at runtime

To modify your code at runtime:

1	In the Object Navigator, double-click the desired program unit, menu item command, or trigger to invoke the Program Unit Editor.

2	In the PL/SQL Editor, make the desired modifications.

3	Choose Compile and then choose Close to dismiss the PL/SQL Editor.

4	In the Debugger toolbar, choose Go or Step Into, Over, or Out to resume program execution.


Creating program units at runtime

To create program units at runtime:

In the Object Navigator, select the desired node and then choose Navigator [image] Create.

To attach a library at runtime:

1	In the Object Navigator, select the Attached Libraries node and then choose Navigator [image] Create.

The Attach Library dialog appears.

Note:  At runtime, you can attach either a .PLL or a .PLX library file.  Form Builder first looks for a .PLX file. If no .PLX file is present, Form Builder then looks for the .PLL file with the specified name.

2	Specify which library to attach, then choose OK.

Or

In the Interpreter pane, use the ATTACH command.


Module Access

Description:

Module Access dialog box enables you to grant or revoke access (read/write/execute privileges) to an indicated module, if the module is stored in the database.

This dialog box contains:

Module	Type the name of a module in this text box.
Operation	Specifies Grant or Revoke.
Retrieve List button	Retrieves a list of modules stored in the database from which to choose.
Show	Filters the list of modules returned by Retrieve List into one or all of the module types: Forms, Menus, PL/SQL Libraries, Object Libraries.
User	Specifies the user name for which you want to grant or revoke access.
Usage Notes:

For modules stored in files, use the access control method provided by your operating system.


Database Roles

Description:

Database Roles displays a dialog containing two commands:

Role	Lets you define and modify security roles affecting menu access.

Role Access 	Lets you control which users have role administration privilege.

Role    Role lets you define or modify security roles that affect menu security.

New	Lets you define a security role by displaying the Role List dialog.

Edit	Lets you edit a security role by displaying the Role dialog for a previously defined role.  You can modify any of the fields previously listed for the New option, including adding or deleting users from the role.

Remove 	Lets you remove a role from the Role List.

Save 	Lets you save the modified Role List.

Exit	Lets you exit without accepting any changes.

Role Dialog     Oracle Forms displays the Role List dialog, including the following options:

Role Name	Specifies the name of the security role.

User Name	Specifies the name of the users you want to add to this role.  (User names are not required; you can create a role now and assign users to it later.)

Debug Mode	Specifies that operators who are members of this role can run a menu in debug mode.

OS Command	Specifies that operators who are members of this role can exit from a form to the operating system, where they can enter operating system commands.

Background Menu	Specifies that operators who are members of this role can display the background menu as a show-keys window.

Role Access     Role Access lets you grant or revoke role administration privileges to individuals.  Oracle Forms displays the Grant Role dialog,  including the following options:

Operation	Specifies Grant or Revoke.

User	Specifies the user name for which you want to grant or revoke role administration privilege.


Delete

Description:

The Delete dialog box enables you to remove a module from the database.

This dialog box contains:

Delete	Type the name of a module to be removed in this text box.
Retrieve List	Retrieves a list of modules stored in the database from which to choose.
Show	Filters the list of modules returned by Retrieve List into one or all of the module types: Forms, Menus, PL/SQL Libraries, Object Libraries.
Usage Notes:

To delete modules stored in files, use the access control method provided by your operating system.


Rename

Description:

The Rename dialog box enables you to change the name of a module in the database.

This dialog box contains:

New	Type the new name of the module in this text box.
Old	Type the name of an existing module to be renamed in this text box.
Retrieve List	Retrieves a list of modules stored in the database from which to choose.
Show	Filters the list of modules returned by Retrieve List into one or all of the module types: Forms, Menus, PL/SQL Libraries, Object Libraries.
Usage Notes:

To rename modules stored in files, use the access control method provided by your operating system.


Generate

Generate creates a runfile with the extension appropriate to the module type (.FMX or .MMX), overwriting the previously generated version.


Convert

Description:

The Convert dialog box allows you to convert a binary file, such as an .FMB form, to a text file, such as a .FMT, or convert from .FMT to .FMB.

This dialog box contains:

Browse	Click this button to search through the file system for a module.
Direction	Select Text-to-Binary or Binary-to-Text.
File	Type the name of an existing module to be converted in this text box.
Type	Select the type of object to be converted: Form, Menu, PL/SQL Libraries, Object Libraries.


Color Mode

Determines how a Form Builder color palette will be loaded on your system.  Each time you load, open, or create a form, Oracle Forms loads the Oracle Forms color palette into your current system color table. Because this system color table can handle only a limited number of colors at once, Oracle Forms may not be able to accurately modify multiple forms simultaneously if they use different color palettes.  For this reason, use the Read Only - Shared option except when you are actively modifying the Oracle Forms color palette.


Color Palette

Description:

This is the palette of colors that may be used in the Layout Editor.

This dialog box contains:

Current Color	This text box contains the name of the currently selected color.
Edit	Click Edit to change the currently selected color to a different color.
Palette Name	The name of the palette imported into the current session.  Blank if none was imported.
Rename	Click to change the name of a color after typing the new name into the Current Color text box.
Select Color to Edit	Displays all the colors currently available in the Layout Editor.  Select a color by clicking on its square.


Generate Before Run

Determines whether Oracle Forms automatically generates the active module when you run a form from the Designer.  When Generate Before Run is On, Oracle Forms does the following when you issue the File, Run command and then run a specified form:

•	generates the active form, menu, or library module to create an executable runfile having the same name as the module

•	runs the .FMX file (form runfile) you specify in the Run dialog

This preference lets you avoid issuing separate Generate and Run commands each time you modify and then run a form. However, this preference does not save the module.  You must issue the File, Save command to save the module.


Access

Specifies from where you can open or save modules:

File	Modules are loaded from and saved to the file system.
Database	Modules can be loaded from and saved to the database.
To stop Form Builder from displaying this dialog box and to specify a default location type set the Access Preference. You can find this preference on the Access tab of the Preferences dialog box displayed when you choose Tools [image] Preferences.


Open from/Save in Database

Lists available modules stored in the database.

Show	Filters the list of modules returned by the Retrieve List button into one or all of the module types: Forms, Menus, PL/SQL Libraries, Object Libraries.
Retrieve List button	Retrieves a list of modules stored in the database.  You can select one from the list below this button and the name will appear in the Open/Save As text box below the list.  If you change the Show filter you must press this button to refresh the list display.
Open/Save As	Type the name of a module to be opened or saved in this text box.


Printer

The name of the default printer. This name is operating-system dependent.


New Relation

  Related Topics

Creates a new relation based on the displayed Master Block.

Detail Block	Enter the name of a block to be related to the master block, or click Select for a list of available blocks from which to choose.  The Detail block must already exist before you can create a new relation to it.
Master Deletes	Determines what occurs when a record in the master block is deleted.  Set one of the following: Cascading: Allows master record to be deleted and automatically deletes associated detail records upon commit.  Only records in the immediate detail block are deleted. Isolated: Allows master record to be deleted, but does not effect the associated detail records. Non-isolated: Prevents the master record from being deleted if there are associated detail records.
Coordination	Deferred: Detail records are not automatically fetched.  The user must navigate to the detail block and explicitly execute a query. Auto-Query: Detail records are fetched when the user navigates to the associated detail block.  Part of the Deferred setting. Prevent Masterless Operation:  Prevents inserting or querying records in the detail block when there is no associated master record.
Join Condition	Enter a valid join condition in the multi-line field.  The join condition defines the relationship between the master block specified in the Master text box and the detail block specified in the Detail text box.  See Specifying the join condition for a master-detail relation. Example:  warehouse.region_id = region.id
Object REF	Specifies a join condition based on an object which exists on both the master block and the detail block.  Select an object from the drop-down box.


Run Modules Asynchronously

Determines whether forms that you run from the Designer are executed synchronously or asynchronously with respect to the Designer itself:

•	When Run Modules Asynchronously is disabled, forms you run from the Designer are synchronous.  That is, you cannot work in the Designer until you exit the form.

•	When Run Modules Asynchronously is enabled, forms you run from the Designer are asynchronous, so you can move back and forth between the Designer and the form.

When you run a form synchronously, Oracle Forms notifies you of any Runform startup errors that occur by displaying an alert in the Designer.  When you run a form asynchronously, no such communication between Runform and the Designer occurs, and Runform startup errors are not reported in the Designer.


Save

Determines whether Oracle Forms saves the current settings when you accept the Options dialog.  When Save is enabled, Oracle Forms writes the current options to the default options file (PREFS.ORA on most platforms).  Oracle Forms reads the settings in the options file each time you start up the Designer.


Save Before Generate

Determines whether Oracle Forms saves the current module automatically when you choose File, Generate.


Suppress Hints

Determines whether hints are suppressed from the message as you work the design facilities in the Designer.


Use System Editor

Determines which editor Oracle Forms uses when you invoke an editor from a multi-line field in a property sheet or design facility.  When System Editor is disabled, Oracle Forms displays the default Oracle Forms editor.  When System Editor is enabled, Oracle Forms displays the default system editor defined on your system.

Note:  If System Editor is enabled and you are using an editor with a native document format, you must save the document as ASCII text (with line breaks), instead of saving the document in that editor's format.


Array Processing

When you suppress array processing, Oracle Forms requests that the database only return a single row of query results at a time from server to client.

Suppressing array processing usually results in the first retrieved record displaying faster than it would if you fetched a number of records with array processing.  However, the total time required to fetch and display a number of records is shorter with array processing because network overhead can be reduced.


Buffer Records in File

Sets the number of records buffered in memory to the minimum allowable number of rows displayed plus some constant (for each block).  If a block retrieves any records by a query beyond this limit, Oracle Forms buffers these additional records to a temporary file on disk.

Setting this preference saves Runform memory, but may slow down processing because of disk I/O.


Debug Mode

Invokes the debug mode for the Runform session.  When you run a form in debug mode, the debugger appears initially allowing you to create debug actions.


Display Block Menu

Automatically displays the block menu as the first screen (after the login screen, if it displays) instead of the form.


Optimize SQL Processing

Specifies that Oracle Forms is to optimize SQL statement processing in V2-style triggers by sharing database cursors.

By default, Oracle Forms assigns a separate database cursor for each SQL statement that a form executes explicitly in a V2 trigger.  This behavior enhances processing because the statements in each cursor need to be parsed only the first time they are executed in a Runform session, not every time.

When you disable Optimize SQL Processing, Oracle Forms assigns a single cursor for all SQL statements in V2 triggers.  These statements share, or reuse, that cursor.  This behavior saves memory, but slows processing because the SQL statements must be parsed every time they are executed.

You can fine-tune this behavior through the New Cursor Area trigger step characteristic.  If a trigger step that contains a SQL statement has this characteristic turned on, Oracle Forms assigns a separate cursor to the statement, in effect overriding the Optimize SQL parameter for that statement.


Optimize Transaction Mode Processing

Optimizes transaction mode processing.

By default, Oracle Forms assigns a separate database cursor for each SQL statement that a form executes implicitly as part of posting or querying data.  This behavior enhances processing because the statements in each cursor are parsed only the first time they are executed in a Runform session, not every time.

Note that the cursors that are assigned to query SELECT statements must be parsed every time they are executed.  This exception exists because queries can vary from execution to execution.

When you disable Optimize Transaction Mode Processing, Oracle Forms assigns a separate cursor  only for each query SELECT statement.  All other implicit SQL statements share, or reuse, cursors.  This behavior saves memory but slows processing because all INSERT, UPDATE, DELETE, and SELECT FOR UPDATE statements must be parsed every time they are executed.


Query Only Mode

Invokes the form in query-only mode.  Setting this preference to On is equivalent to using the CALL_FORM(query_only) built-in subprogram.


Quiet Mode

Invokes the quiet mode for the Runform session.  In quiet mode, messages do not produce an audible beep.  You can explicitly ring the bell from a trigger by way of a call to the BELL built-in subprogram.  The default of quiet=NO means that the bell rings.  To turn off the bell, enable Quit Mode.


Statistics

Displays a message at the end of the session that states the maximum number of simultaneous cursors that were used during the session.  This message appears on the terminal screen, not on the message line.

This preference also issues the following command to the database:

ALTER SESSION SET SQL_TRACE TRUE

This command enables the SQL trace facility for the current session, displaying the trace file directory on the server.

If you are running a form within the Designer and you want to use this feature, activate the Statistics Runform preference.


Ruler Settings

Description:

The Ruler Settings dialog allows you to specify options for ruler units, grid definition, and snap points.

This dialog box contains:

Character Cell Size  (points)	Defines the height and width of a character cell when the Units option is set to Character Cell.  The width and height are expressed in points.  When the form module Form Coordinate property is set to Character Cell, the Layout Editor character cell's width and height default to the form character cell width and height.  Otherwise, the default is the width and height of the default font.
Grid Spacing	Grid Spacing specifies the distance (measured in ruler units as specified in the Unit field) between grid lines drawn in the Layout Editor.  For example, if ruler Unit is set to inches and grid spacing is set to 5, there will be one grid line every 5 inches.  A grid spacing of .25 results in four grid lines per ruler unit (e.g., one grid line each quarter-inch, with the conditions above).
Number of Snap Points	The Number of Snap Points Per Grid Spacing specifies how many snap points there are for each grid line.  Snap points are used in click-and-drag layout when Snap to Grid (under the View menu) is set.  For example, if Unit is set to inches, Grid Spacing is set to 1, and Number of Snap Points Per Grid Spacing is set to 8, there will be a snap point at every one-eighth inch.  If Number of Snap Points Per Grid Spacing is set to 2, there will be snap points at each half inch.  Choose 1 if you want the snap points to coincide with the grid lines.  This feature allows you to create a snap grid that is more granular than the grid lines defined by the Grid Spacing option. Enable the Other option and enter a value in the Other text box to specify a custom number.
Unit	Unit specifies the unit of measure that is used for the rulers displayed in the Layout Editor.  The default unit is the unit defined for the active form, as indicated by the form's Coordinate System property.


Layout Settings

Description:

The Layout Settings dialog allows you to specify the size and page direction of the Layout Editor workspace.

The workspace is the area of the Layout Editor window where you create and manipulate items and graphic text and images.  The size of the workspace is independent of the current size of the Layout Editor window.  That is, the workspace can be larger or smaller than the content area of the window.  When the workspace is larger than the Layout Editor window, scroll the window to display other parts of the workspace.

This dialog box contains:

Layout Size	Defines the height and width of the workspace in either inches or centimeters.  The workspace is the area within the Layout Editor window on which you can create items and boilerplate objects.  When grid lines are displayed, the lines of the grid are displayed within the workspace boundaries.  Objects that you create outside the workspace may not be displayed correctly.
Page Direction	Specifies the order in which pages are printed when you execute the Print Window command.  Page direction can be left-to-right or top-to-bottom.
Units	Defines the units of measure to be used for the Layout Size.


General Drawing Options Dialog

Description:

The General Drawing Options dialog allows you to set general drawing options.

This dialog box contains:

Cap Style	Specifies how the end points of lines should be rendered (Butt, Round, or Projecting).
Join Style	Determines how the corners of rectangles should be rendered (Round, Bevel, or Miter).
Object Creation	Determines how new objects are drawn when you click and drag with a graphic or item tool.  Choose Draw from Corner if you want the initial mouse click to mark the corner of a new object's bounding box.  Choose Draw from Center if you want the initial mouse click to mark the center of a new object's bounding box.
Usage Notes

The general drawing options you choose are applied to the currently selected objects and become the defaults for objects that you subsequently create.


Arc Drawing Options Dialog

Description:

The Arc Drawing Options dialog allows you to set the default appearance of arc objects:

This dialog box contains:

Arc Fill	Determines how the arc's fill region is drawn.  Choose Pie if the fill is to be rendered from the center-point of the circle described by the arc.  Choose Chord if the fill is to be rendered within a line segment between the arc's two end points. T
Arc Closure	Determines whether arcs are drawn closed or open.  Choose Closed if  the border of the arc is to be rendered on the entire perimeter of the arc object's fill region.  Choose Open if the border of the arc is to circumscribe only the arc itself.
The arc drawing options are applied to the currently selected arc objects and become the default for arcs subsequently created.

Usage Notes

You can hide the fill region of an arc by applying the transparent pattern to the fill region.


Text Drawing Options Dialog

Description:

The Text Drawing Options dialog allows you to set the options which affect  the display of text objects.

This dialog box contains:

Fixed Bounding Box	When checked, the bounding box of a text object can be sized independently of the text it contains if the Scalable Bounding Box check box is checked.  When unchecked, the bounding box of a text object changes size only to fit the text.
Horizontal Origin	Specifies how text objects are aligned horizontally (At Left, At Center, or At Right).
Invisible Text	Determines whether the text in a text object is visible or hidden.
Scalable Bounding  Box	Determines whether the bounding box of text objects can be resized.  This option is disabled when the Fixed Bounding Box check box is unchecked.  When the Scalable Bounding Box option is checked, you can create text objects with the text tool by clicking and dragging until the bounding box is the desired size.  Text entered in text mode wraps as required to keep the text within the bounding box.
Scalable Fonts	Determines whether the text in a text object is scaled proportionately when the object itself is resized.
Vertical Origin	Specifies how text objects are aligned vertically (At Top, At Center, or At Bottom).
Wraparound	When the Fixed Bounding Box check box is checked, the Wraparound option determines whether text in a text object wraps to the next line to fit within the bounding box.
 Usage Notes

The text drawing options are applied to the currently selected text objects and become the defaults for  text objects that are subsequently created.


Rounded Rectangle Drawing Options Dialog

Description:

The Rounded Rectangle Drawing Options dialog allows you to set the appearance of rectangles.

This dialog box contains:

Corner Radius	Specifies the amount of rounding that Oracle Forms applies when drawing the corners of a boilerplate rounded rectangle object.  You can specify both the horizontal and vertical radius in inches, centimeters, or points.  Larger values increase the amount of rounding at each corner.
Units	Specifies the unit of measurement (Inches, Centimeters, or Points).
Usage Notes

The rounded rectangle drawing options are applied to the currently selected rectangle objects and become the default for rectangle objects subsequently created.


Image Drawing Options Dialog Box

Description:

The Rounded Rectangle Drawing Options dialog allows you to set the appearance of rectangles.

This dialog box contains:

Image Quality	Specifies the quality with which Oracle Forms displays the image.  A higher image quality looks better, but results in slower screen redraw.
Image Dither	Specifies whether Form Builder dithers the image.  Dithering is a process  by which Form Builder simulates colors that appear in the image but are not available in the current color palette.  If the image is not dithered, Form Builder substitutes available colors that most closely match those in the image.  A dithered image looks better, but results in slower screen redraw.


Preferences

General Tab

Save Before Building

Build Before Running

Suppress Hints

Use System Editor

Color Palette

Color Mode

Printer

Access Tab

Access

Subclassing Path

Wizards Tab

Welcome Dialog

Wizard Welcome Pages

Runtime Tab

Buffer_Records in File

Debug Messages

Array Processing

Optimize SQL Processing

Optimize Transaction Mode Processing

Statistics

Display Block Menu

Query Only Mode

Quiet Mode

HTML File Name


Preferences - Access Tab

Access

Subclassing Path


Preferences - Wizards Tab

Welcome Dialog

Wizard Welcome Pages


Preferences - Runtime Tab

Buffer_Records in File

Debug Messages

Array Processing

Optimize SQL Processing

Optimize Transaction Mode Processing

Statistics

Display Block Menu

Query Only Mode

Quiet Mode

HTML File Name


About modules

  Related Topics

Form Builder applications consist of individual application components called modules.  There are four types of modules in Form Builder:

Form module	A collection of objects and code routines.  Objects that may be defined in a form module include windows, text items (fields), check boxes, buttons, message boxes, lists of values, and blocks of PL/SQL code called triggers.

Menu module 	A collection of menus (a main menu object and any number of submenu objects) and menu item commands that together make up an application menu.

PL/SQL Library module	A collection of user-named procedures, functions, and packages that can be called from other modules in the application.

Object Library module	A collection of objects that can be used to develop applications.

You can build a single application from multiple form, menu, and library modules as needed.  Modules can be saved to the file system or the database, and can be converted between binary, text, and compiled executable formats.


About module file formats

  Related Topics

Form, menu, and library modules created in Form Builder are stored in binary format, can be saved to files or to the database, and are portable across platforms.

When you compile a binary module, Form Builder creates a platform-specific runfile.  You can also use the Forms Compiler to create a human-readable text file that is portable across platforms.

The following table shows the file extensions for each type of module and storage format.

Module	Binary (Design)	Text	Executable Runfile
Form	.FMB	.FMT	.FMX
Menu	.MMB	.MMT	.MMX
PL/SQL  Library	.PLL	.PLD	.PLX, .PLL
Object Library	.OLB	.OLT	NA

The default file extensions indicate the module type and storage format:

.FMB	Form Module Binary
.FMT	Form Module Text
.FMX	Form Module Executable
.MMB	Menu Module Binary
.MMT	Menu Module Text
.MMX	Menu Module Executable
.PLL	PL/SQL Library Module Binary
.PLD	PL/SQL Library Module Text
.PLX	PL/SQL Library Module Executable  (contains no source)
.OLB	Object Library Module Binary
.OLT	Object Library Module Text


About compiling modules

  Related Topics

Before an application can be run, you must compile an executable .FMX file from an .FMB design file created in Form Builder.  When you Generate a form or menu module any uncompiled program units are compiled and an executable runfile is created.

When the Build Before Running preference is set to Yes (the default setting), Form Builder implicitly compiles a form when the Program [image] Run Form command is issued.  Forms may also be explicitly compiled from Form Builder or from the command line interface.

When you compile a form, Form Builder compiles any uncompiled PL/SQL code it contains.  Any compilation errors cause generation to fail.  When this happens, the Generation Errors dialog box is displayed showing appropriate error messages.  By default, each time the compile command is issued Form Builder compiles only those program units that are currently marked as uncompiled.

For an application with multiple modules to be successfully deployed at runtime, all of the .FMX, .MMX., and .PLX files used by the form must be delivered.


About compiling Libraries

  Related Topics

Unlike form and menu modules, library modules do not have to be compiled explicitly to create a separate runfile.  The .PLL library file that you work with in Form Builder includes both the source code required at design-time and the compiled executable code required at runtime.  Using the .PLL version of the library is required when you want to use the Debugger to view the source code within compiled program units.

When a library is attached to a form, menu, or to another library in Form Builder, the .PLL version of the library is also attached.  To run the application from Form Builder, you need only make sure that the subprograms and packages in the library have been compiled.  (See Compiling all units in a module.)

When you are ready to deploy your application, you can compile a .PLX library file from the .PLL library file. The .PLX file does not include the source code component that is part of the .PLL file.  You can compile a .PLX file from Form Builder or from the command line.

When you attach a library to a module in Form Builder, you attach the .PLL version of the library.  At runtime, Form Builder looks for a .PLX file by that name in the default search paths.  If no .PLX file is present, Form Builder looks for the .PLL file by that name.


About the coordinate system

  Related Topics

The coordinate system selected for a form module defines the units of measure that are used when specifying size and position coordinates for objects in the form.  A form's coordinate units can be set to either character cells or real units (centimeters, inches, pixels, or points).  The default units are points.

Size and position coordinates for objects are specified in Form Builder and programmatically at runtime.  When the size and position of objects are modified programmatically, Form Builder interprets values in the current form coordinate units.  For example, if a window has coordinate units set for points, you can resize it by calling the built-in procedure RESIZE_WINDOW, as shown here:

Resize_Window('my_window',20,25);

At runtime, the Width and Height values (20 and 25, respectively) are interpreted as points, the form's current form coordinate units.


Guidelines for choosing coordinate units

  Related Topics

It is good practice to set the coordinate units before designing the application interface and placing objects onto canvases.  When choosing coordinate units, consider the runtime platforms on which the application will be deployed.  As a general rule, if the application will run on both GUI and character-mode systems, character cell units should be used.

If you deploy your application only on GUI platforms, such as Microsoft Windows, the choice of coordinate system is a matter of personal preference.  If you deploy your application across multiple GUI platforms, or on the same platform but with different screen sizes or resolutions, pixels should not be used as the coordinate unit.


About using the character cell coordinate system

  Related Topics

When designing a form in character cell units, all object dimensions and position coordinates are expressed in character cells represented as whole numbers.  Form Builder will only accept whole numbers for size and position properties and will round up to the next integer.  For example, if the width property value of a text item is set to 12.5 character cells, Form Builder will round up the Width property value to 13 character cells automatically.

When Coordinate System is set to Character Cell, the Character Cell Width/Height properties show the actual size of a character cell in the current real units.  This character cell size is based on the size of the default font on the design time device, and the Character Cell Width/Height property values cannot be edited.

Working in the Layout Editor with character cell units can produce unexpected results, particularly when using the mouse to draw and position items, graphic text, and images.  Using character cells effectively produces a "snap-to-grid" effect, with the grid increments being the size of a character cell.


About using the real units coordinate system

  Related Topics

The Character Cell Width and Height properties show the dimensions of the default font in real units.  If you are designing in real units and plan to use the default font in your form, you will want to keep these dimensions in mind as you create items and boilerplate graphics that display text.

When you work in real units, it is up to you to ensure that the width and height of the text item's bounding box are compatible with the size of the font applied to the text item.  Note also that on some platforms, the presence of an object border can reduce the amount of space available for displaying text.  For example, setting the Bevel property of a text item can reduce the number of characters the item can display.


About converting coordinate system units

  Related Topics

When you change the coordinate system for an existing form, Form Builder converts all object size and position values to the new units of measurement.

Some loss of precision can occur when converting to different units.  When converting from one real unit to another, any loss of precision is usually insignificant.  However, converting from real units to character cells may affect the layout of the form.  Form Builder rounds all values to the nearest character cell value, and may noticeably alter the size and position of objects in your interface.

Note: Form Builder does not automatically convert size or position values specified in PL/SQL code (triggers, subprograms, and so on).  Form Builder interprets these values in the coordinate units in effect at runtime.

For example, for a form designed with the coordinate system units specified as pixels, containing PL/SQL code which explicitly changes the width of a text box on the form by 3 units, if the real unit coordinate system of the form is subsequently changed from pixels to inches, the code when executed will change the width of the text box by 3 inches.


About default font scaling

  Related Topics

The Default Font Scaling property applies only when using the character cell coordinate system.  This property is set to Yes by default, which causes Form Builder to scale all size and position dimensions relative to the size of the default font on the current device.

When you use the same device at runtime as at design time, setting Default Font Scaling to Yes or No has no effect.  However, when a form is deployed on a different runtime device, the Default Font Scaling property determines whether size and position dimensions are scaled relative to the default font of the runtime device, or to the size specified by the Character Cell Width/Height values specified in the Coordinate Info message box:

•	When Default Font Scaling is set to Yes, Form Builder scales objects according to the size of the default runtime font.  With this setting, text items and other objects "grow" and "shrink" to accommodate the size of the default runtime font.

•	When Default Font Scaling is set to No, Form Builder ignores the runtime font, and scales objects according to the size of the default design time font.  This can result in items and boilerplate graphics to seem scaled independently of the default runtime font.  For example, a text item can appear significantly larger or smaller than the characters it displays.


Specifying the coordinate system

  Related Topics

To specify the coordinate system for a form:

1	In the Object Navigator, double-click the form module object icon to display the Property Palette.

2	In the Property Palette, double-click the Coordinate System property to display the Coordinate System dialog box.

3	If you want to use character cell units, set the Coordinate System property to Character.  If you want to use real units, set Coordinate System to Real, then select the desired units from the Real Unit drop-down list.


Compiling a module to create an executable runfile

  Next Step	    Related Topics

To compile a module from Form Builder:

1	The module you want to compile must be open in Form Builder. If more than one module is open, make the desired module the current module by selecting any object it contains.

2	Select File [image] Administration [image] Compile File.

The message "Module Compiled Successfully" is displayed on the status bar if generation succeeds.


Compiling a module automatically

  Related Topics

To compile a form automatically when you run from Form Builder:

1	Choose Tools [image] Preferences.

2	Check the Build Before Running preference check box (the default setting).

3	Make the form you want to run the active module.

4	Choose Program [image] Run Form [image] Client/Server (or Web).

Form Builder implicitly compiles and then runs the indicated form.

Note:  Running a form when the Build Before Running preference is set to Yes does not compile any menu or library attached to that form; you must explicitly compile menus and libraries with the File [image] Administration [image] Compile File command.


Compiling all units in a module

  Related Topics

To compile all program units in a module explicitly:

1	Click a module, form, menu, or PL/SQL library in the Object Navigator.

2	Choose Program [image] Compile [image] All.


Compiling a .PLL library

To compile a .PLL library:

In Form Builder:

1	Select the library in the Object Navigator.

2	Choose Program [image] Compile [image] All.

- Or -

Using the Forms Compiler, use the module_type and compile_all options, as shown here:

ifcmp60 mylib.PLL [user ID/password] module_type=library compile_all=yes


Creating a module

  Next Step	    Related Topics

To create a module:

1	In the Object Navigator, click the desired node, either Forms, Menus, Libraries, or Object Libraries.

2	Click the Create button [image] in the toolbar.


Opening a Module

  Related Topics

To open a module:

1	Choose File [image] Open to display the file or database dialog box.

2	Choose the module you want to open and click OK.

A module that has been opened in Form Builder appears under the appropriate node (Form, Menu, Library, or Object Library) in the Object Navigator.


Saving a module

  Related Topics

To save a module:

 Choose File [image] Save.

If you are saving the module for the first time, the File or Database dialog box appears to allow you to specify a name for the module.  If you are saving an existing module, Form Builder overwrites the previously saved version with the current version.

Note: When you work with more than one module at a time, Form Builder keeps track of the changes that you make to each module separately.  When you issue a Save command, only the current module is saved.


Closing a module

To close a module:

1	Select any object in the module that you want to close.

2	Choose File [image] Close.


Deleting a module

To delete a module stored in the database:

1	Choose File [image] Administration [image] Delete.

2	(Optional) Choose Retrieve List to display all of the modules to which you have access.

3	Type the name of the module you want to delete in the Delete text box, or choose a module from the list.

4	Click OK to delete the module.

Note: To delete a module in the file system, use the appropriate file system commands for your platform.


Renaming a module

To rename a module stored in the database:

1	Choose File [image] Administration [image] Rename.

2	(Optional) Choose Retrieve List to display all of the modules to which you have access.

3	Type the name of the module you want to rename in the Old text box.

4	Type a new name for the module in the New text box.  Do not include extensions when you enter the name.

5	Click OK to rename the module.

Note: To rename a module in the file system, use the appropriate file system commands for your platform.


Reverting to the last saved version of a module

To revert to the last saved version of a module:

 Choose File [image] Revert.


Running a form in Client/Server mode

  Next Step	    Related Topics

To run a form in Client/Server mode:

1	Make the form module you want to run the current module by selecting any object in the form module.

2	Choose Program [image] Run Form [image] Client/Server.

If the Build Before Running preference is checked, Form Builder first compiles the form to create an .FMX file, then runs the form using Forms Runtime.  If Build Before Running is not checked, Form Builder looks for an .FMX file with the same name as the current form in the current directory before running the form with Forms Runtime.


About previewing web-based forms

  Related Topics

When you use the Web Previewer to run your forms, they will look and behave as though being deployed from a web server.  Use the Web Previewer as a tool to test your web forms without having to actually deploy the forms on a server.  All web functionality is enabled and you can create a base HTML file to run the form with custom applet client parameters.  By using your own base HTML file, you can specify custom Web Previewer options which remain constant throughout development.

For more information about deploying applications on the Web, including creating a base HTML file, see Guidelines for Building Applications.

The Web Previewer is currently available on Microsoft Windows platforms only.


Previewing a web-based form

  Related Topics

To run a form in the Web Previewer:

1	Make the form module you want to run the current module by selecting any object in the form module.

2	Choose Program [image] Run Form [image] Web,

OR

click on the Run Form Web button [image] in the Object Navigator or Layout Editor.

If the Build Before Running preference is checked, Form Builder first compiles the form to create an .FMX file, then runs the form using the Web Previewer.  If Build Before Running is not checked, Form Builder looks for an .FMX file with the same name as the current form in the current directory before running the form with the Web Previewer.

If you have specified an HTML filename preference, that file will be used to run the form in the Web Previewer.

Note:  The Web Previewer is currently available only on Microsoft Windows platforms.


Running a form from the command line

  Related Topics

To run a form from the command line:

Type the name of the Forms Runtime executable (IFRUN60 on Microsoft Windows) followed by the appropriate parameters:

ifrun60 [module_name] [user ID/password] [parameters]

For example,

ifrun60 custform.fmx scott/tiger statistics=yes

To run a form from the program icon:

1	On Microsoft Windows, double-click the Forms Runtime icon.

2	At the dialog box, enter the name of the form to run, and the database connection information

3	Click OK.

Note: Menu and library runfiles cannot be run independently of forms.  Rather, these are associated with a form at design-time by setting the appropriate properties.  When the form is run, Form Builder loads the associated menu and library files (.MMX and .PLL files) as needed.


About Converting Modules from Binary to Text Format

  Related Topics

Modules may be converted between binary and text formats in Form Builder.  For example, form, menu, and library modules can be converted from binary format (.FMB, .MMB, .PLL) to text format (.FMT, .MMT, .PLD).  The text version of a module is a human-readable file that describes its objects and code.

Converting a module creates a new version of the module,  leaving the current version intact.  For example, when a binary form file (.FMB) is converted to a text file (.FMT), both the .FMT file and the original .FMB file are available.

The convert command invokes the Forms Compiler component of Forms Developer.

Note: Editing of .FMT, .MMT, and .PLD files is not supported by Oracle.


Converting a Module From Binary to Text Format

  Related Topics

To convert a module:

1	Choose File [image] Administration [image] Convert.

2	Specify the type and name of the module to convert, and specify the conversion, from Binary-to-Text (e.g., .FMB [image].FMT), or Text-to-Binary (e.g., .FMT [image].FMB).

3	Click Convert.


About the Access Preference

  Related Topics

Modules may be saved to and loaded from the file system or the database by setting the Access  preference.

By default, the Access preference is set to File, and Form Builder assumes modules will be opened from the file system, rather than the database.  To access modules stored in the database, the Access design preference must be set to Database or to Ask.

Once a module has been saved, either to the file system or to the database, changing the Access preference has no effect on subsequent save operations for that module.  A module is always saved to the source from which it was opened or to which it was last Saved As.

Filter Dialog box  When the Access preference is set to Ask, Form Builder prompts you to specify the location (file system or database) and module type each time you open or save a module.  The Filter dialog box includes the following options:

Object Access:	Determines whether Form Builder displays the File dialog box or Database dialog box when you save or open a module.  Set to either Database or File System.
Display:	Determine which files/modules are displayed in the File dialog box or Database dialog box that displays when you save, open, rename, or delete a module.  Set to either All Files, Forms, or Menus.


Setting the Access Preference

To set the Access preference:

1	Choose Tools [image] Preferences.

2	Click the Access tab.

3	Set Access to File, Database, or Ask.

•	Choose File if you want all modules to be saved to and loaded from the file system.

•	Choose Database if you want all modules to be saved to and loaded from the database.

•	Choose Ask if you want Form Builder to display the Filter dialog box that prompts you to specify File or Database each time you save or open an existing module.

4	Click OK.


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.


About the Object Navigator

The Object Navigator provides a hierarchical display of the objects in all open modules. Objects are grouped under the appropriate node. For example, all of the windows defined in a form module appear under the Windows node. The Windows node, in turn, appears under the appropriate form module object.

The top-level nodes in the Object Navigator include Forms, Menus, Libraries, Object Libraries, Built-in Packages, and Database Objects.  All other nodes, and the objects they contain, are indented to indicate that they belong to these higher-level nodes.

Objects and nodes in the Object Navigator are displayed with a + or - symbol to indicate whether they are currently expanded or collapsed. A gray + is displayed for a node that does not yet contain lower-level objects. A round bullet is displayed in front of an atomic object that cannot contain any lower-level objects.

Each object in the Object Navigator is displayed with an icon that indicates its type. For some objects, double-clicking the icon invokes an editor appropriate to that type of object. For example, double-clicking the object icon for a canvas invokes the Layout Editor.

You can perform the following operations in the Object Navigator:

•	expand and collapse entries to locate objects quickly

•	select objects

•	create and delete objects

•	copy and move objects within and between modules

•	switch between views to display the objects you want to work with

•	locate objects quickly by searching with Fast Search

•	quickly display the code associated with objects such as triggers and program units

You can select commands in the Object Navigator from the menu and from the toolbar. The toolbar provides quick access to commands. Click once on the icon for the command you want to execute. To see a pop-up description of a toolbar command, move the cursor over the icon without clicking the mouse.

Status information

The Object Navigator also provides you with status information about program units by using these flags:

*   an asterisk following the name of a program unit indicates that the program unit has been modified since the library was opened and it needs to be recompiled.

@   this at symbol following the name of a program unit indicates that the program unit has not been changed since the library was opened.


About Object Navigator synchronization

You can set Object Navigator synchronization On or Off.

When Synchronization is On, the Object Navigator and any open Layout Editors and Menu Editors maintain the same current selection. For example, selecting a button in the Layout Editor automatically makes that button the current selection in the Object Navigator as well. Similarly, selecting a menu item in the Object Navigator makes that item the current selection in the Menu Editor.

When Synchronization is Off, selecting an object in the Object Navigator or an editor does not update the current selection in other windows.

To turn Synchronization On or Off, set the Synchronize option on the Navigator menu.

Note:  By default, the Property Palette is always synchronized with the current selection. You can toggle synchronization On and Off by clicking the Freeze/Unfreeze button on the Property Palette toolbar. Freezing the Property Palette is useful when you want to have two Property Palettes open at the same time, so you can compare the properties of two different objects side-by-side.


About Object Navigator views

The Object Navigator can display modules in one of two views: Ownership (the default), and Visual. The view determines which objects you see in the Object Navigator and how those objects are arranged.

Ownership View  In the ownership view, all form objects are visible, and the display hierarchy corresponds to the Form Builder object ownership hierarchy: form—block—item. Items and relations are owned by blocks; blocks are owned by forms; triggers can be owned by forms, blocks, or items; all other form objects (windows, editors, record groups, etc.) are owned by forms.

Visual View  In the Visual view, only windows, canvases, and items are displayed. The Visual view hierarchy corresponds to the hierarchy of objects in a form window: window—canvas—item. Items are assigned to canvases; canvases are assigned to windows. Each window can have multiple canvases, and there can be multiple items on a single canvas.

When the Object Navigator is in Ownership view, form items are listed under the blocks to which they are assigned. When the Object Navigator is in Visual View, form items are listed under the canvases on which they are displayed.

When a form contains items that are not assigned to any canvas (because their item Canvas property is set to <Null>), those items are displayed under the Null Canvas node. When there are canvases that are not yet assigned to a window, they are displayed under the Null Window node.

Only Objects with PL/SQL Option   You can set the Navigator [image] Only Objects with PL/SQL menu option On or Off. By default, this option is Off, and all objects are visible. Setting Only Objects with PL/SQL On hides all objects except code objects (triggers, program units, etc.) and objects to which triggers can be attached (forms, block, items).


Displaying the Object Navigator

To display the Object Navigator:

•	Choose Tools [image] Object Navigator.


changing, Object Navigator views
Changing Object Navigator views

To change the Object Navigator view:

•	In the Object Navigator, choose View [image] Ownership View or Visual View.


Navigating and selecting objects in the Object Navigator

You select Object Navigator entries as you move the cursor up and down in the Object Navigator. The current entry can be either a node or an actual object. When you select an object, the Property Palette is updated to display that object's properties.

You can use the following keys to navigate and select objects in the Object Navigator:

Up	Selects the previous node or object displayed above the current entry.

Down	Selects the next node or object displayed below the current entry.

Left	Selects and collapses the node or object at the level above the current entry.

Right	Selects the node or object at the level below the current selection, expanding collapsed entries as necessary. If there is no such object, selects the entry immediately below the cursor.

Selecting Objects with the Mouse  You can use the following techniques to select nodes and objects:

Single Selection	Select a single Object Navigator entry by clicking with the mouse or by moving the cursor with the arrow keys. When no other entries are selected, the cursor position represents the current single selection.

Range Selection	Shift-click to select a range of Object Navigator entries. Shift-click selects all entries between the cursor position and the selection point. Objects in a range selection must be of the same type.

Multi-Selection	Control-click to select multiple Object Navigator entries. You can select as many objects as you want this way, adding them one at a time. Deselect objects by Control-clicking again.

When a single object is selected, its properties are displayed in the Property Palette. When more than one object is selected in the Object Navigator, the Property Palette displays either the union or intersection of the selected objects' properties.

Navigating with the Context List  As you move up and down in the Object Navigator, the Context list at the top of the Object Navigator window displays the name of the currently selected object, its ancestors in the object hierarchy, and the names of all open modules. Selecting an object in the list moves you to that object in the Object Navigator.


Expanding and collapsing objects in the Object Navigator

You can quickly locate objects you want to work with by using navigation keys together with commands for collapsing and expanding the Object Navigator. Expanding an entry in the Object Navigator makes objects visible that were previously hidden because they were in a collapsed state. Collapsing an entry hides objects that were visible in the expanded state.

Object Navigator entries are prefixed with a plus, minus, or bullet symbol that indicates whether the entry is expanded or collapsed, as follows:

+ (plus)	The entry contains lower-level objects that are hidden because the entry is collapsed.

+ (grayed out)	The entry does not yet contain any lower-level objects.

- (minus)	The entry contains lower-level objects that are visible because the entry is expanded.

o (bullet)	The entry is an atomic object that cannot contain lower-level objects.

Use the following menu commands to expand and collapse selected Object Navigator entries. These commands are valid only when the current selection has a + or - in front of it.

Navigator [image] Expand	Expands objects at the level immediately below the level of the currently selected object or objects.  Equivalent to clicking the + in front of a node.
Navigator [image] Collapse	Collapses objects at the level immediately below the level of the currently selected object or objects.  Equivalent to clicking the - in front of a node.
Navigator [image] Expand All	Recursively expands every entry below the current entry.  Equivalent to Shift-clicking the + in front of a node.
Navigator [image] Collapse All	Recursively collapses every entry below the current entry.  Equivalent to Shift-clicking the - in front of a node.
You can expand or collapse an Object Navigator entry by clicking the + (plus) or - (minus) symbol in front of it:

•	Click the + in front of a collapsed entry to expand objects at the le	vel immediately below the level of the current object. This is equivalent to the Expand command. Shift+click to Expand All.

•	Click the - in front of an expanded entry to collapse objects at the level immediately below the level of the current object. This is equivalent to the Collapse command. Shift+click to Collapse All.

Expand/Collapse vs. Expand All/Collapse All  The Expand and Collapse commands affect only entries at the level immediately below the current entry. In contrast, the Expand All and Collapse All commands are recursive, meaning that they expand or collapse entries at every level that is below the current entry.

After expanding a collapsed entry, some lower-level objects might still be hidden. For example, when you Expand a form object, all of the blocks in that form will be visible; however, the items in each block (which are at the next level down in the object hierarchy) remain hidden if they were previously collapsed.  In contrast, when you Expand All, every object and node at every level under the current entry becomes visible.


Creating objects in the Object Navigator

To create an object in the Object Navigator:

1	Select either a node or an object of the type you want to create.

2	 Choose Navigator [image] Create, or click on the Create button.

Form Builder inserts the new object immediately after the current selection.

For example, to create a window, move the cursor to the Windows node and choose Navigator [image] Create. The Create command is not available when multiple objects are selected.

When a node does not yet contain any objects and so is displayed with a grayed +, you can create an object of that type by double-clicking the +.


Deleting objects in the Object Navigator

To delete an object in the Object Navigator

1	Select the node or object you want to delete.

2	Choose Edit [image] Cut.

Cut places the object on the clipboard, allowing you to subsequently paste it into another module.

Note:  When the current selection is a node, rather than an object, Cut remove all objects under that node.  When the current selection is a module, Cut closes the module.


Changing the names of objects in the Object Navigator

To change the name of an object in the Object Navigator:

1	Select the object by clicking or navigating with the arrow keys.

2	Click the name. The cursor changes to an I-beam.

3	Edit the name as desired, then press Return.

You can also change an object name by selecting the object and then setting its Name property in the Property Palette.

Note:  You cannot change the name of PL/SQL Library modules in the Object Navigator. Instead, specify the desired name when you save the library module with the Save As menu command.


Moving and copying objects in the Object Navigator

You can use the following commands to move and copy objects within modules in the Object Navigator:

•	To move the current selection, drag it to the desired destination. Or, choose Edit [image] Cut, move the cursor to the desired destination, then choose Edit [image] Paste.

•	To copy the current selection, Control-drag the selection to the desired location. Or, choose Edit [image] Copy, move the cursor to the desired destination, then choose Edit [image] Paste.

•	To cut or copy all objects within a node, position the cursor on the node, then choose Edit [image] Cut or Edit [image] Copy.

Restrictions on Copy/Move Destinations  The following restrictions apply when moving and copying objects in the Object Navigator:

•	Objects can be copied from one module to another, but cannot be moved from one module to another.

•	Objects must be dragged or pasted to the appropriate location in the module hierarchy. For example, in Ownership view, items which are owned by blocks can be copied only under other blocks. Similarly, you cannot drag a window object under the Parameters node because such an operation would be illogical.

If you drag an object under an invalid node in the Object Navigator, Form Builder beeps and disallows the move.

•	Only objects of the same type can be moved as part of a multiple selection.

How Object Ownership Affects Copy/Move Operations   When you move or copy an object, you also move or copy any objects owned by that object. For example, copying a block also copies the triggers attached to that block, the items owned by that block, and the triggers attached to those items.

It is important to distinguish between object ownership and the simple associations that can exist between objects.  For example, canvases are displayed in windows, and each canvas is assigned to a specific window at design time. However, the window does not own the canvas. Both objects are owned by the form. The relationship between the window and the canvas is simply an association that you define by setting the canvas's Window property.

When you move or copy an object, only objects owned by that object are moved or copied. The ownership rules for objects in form modules can be stated simply as follows: Items and relations belong to blocks. Triggers can belong to items, blocks, or forms. All other objects belong to forms.

The ownership rules for menu modules are even simpler: Menu items belong to menus. Menus belong to menu modules. All other objects belong to menu modules.

PL/SQL library modules contain only subprograms and packages, all of which belong to the library module.


Finding Object Navigator entries with Fast Search

You can use the Object Navigator's Fast Search feature to quickly locate objects and nodes in the Object Navigator. To begin a search, enter the string you want to search for in the Find field at the top of the Object Navigator window. As you enter each character, Form Builder moves the cursor to the next Object Navigator entry that matches the regular expression <search string> * , where * is a wildcard representing any number of characters.

For example, when the cursor is on the Forms node, typing the letter A in the Find field moves it to the first entry beginning with A, which might be the Alerts node. If the next character you typed was C, the cursor would move to the first entry that started with AC, which might be an item named ACCOUNT_REP.

When necessary, Form Builder expands collapsed entries to show an object that matches the search string.

The following search commands are available in the Object Navigator.

type any character	Starts or continues a search and moves the cursor to the next entry beginning with characters that match the criteria string displayed in the Find field.

Search Forward	When a search string has been entered, searches from the current entry to the end of the outline for the next entry that matches the search string.

Search Backward	When a search is in progress, searches from the current entry to the beginning of the outline for the next entry that matches the search string.

Searching is circular; if no entries are found, Form Builder wraps to the beginning or end of the hierarchy to continue searching for objects that match the search criteria.


Setting a mark in the Object Navigator

You can use the Add Bookmark and Go to Bookmark commands to mark an entry in the Object Navigator and then return to that entry later on. You can set a bookmark on a node (Blocks, Triggers, etc.), or on an object (CUST, ORD, etc.).

To insert a bookmark, position the cursor on the desired entry and choose Navigator [image] Add Bookmark.

Once a bookmark has been set, you can work in the Object Navigator and in other windows as desired. When you want to return to the marked entry, choose Navigator [image] Go to Bookmark. When necessary, Form Builder expands entries to show the marked entry.

A mark remains set until:

•	you set a new bookmark with Navigator [image] Add Bookmark

•	you delete the bookmarked object

•	you close the module that contained the bookmark

•	you quit the Form Builder

When you are using the split pane feature, you can set a bookmark in each pane. You can set only one bookmark per pane.


Working with multiple panes in the Object Navigator

To split the Object Navigator pane:

1	Click the black line above the vertical scroll bar or the black line to the left of the horizontal scroll bar. The mouse cursor changes shape when you are over the split bar.

2	Drag the split bar to the desired position in the Object Navigator pane.

By adding additional split bars you can create up to eight separate panes. Each pane has its own scroll bars. Once you split the Object Navigator pane, you cannot split the resulting panes in the opposite direction.

To remove a split bar, drag it out of the Object Navigator pane.


Closing the Object Navigator

To close the Object Navigator:

•	Choose File [image] Close.


Property Palette topics

About the Property Palette

Displaying the Property Palette

Toolbar commands in the Property Palette


About the Property Palette

The Property Palette is where you set the properties of objects you create in form and menu modules.

When you select an object in an editor or in the Object Navigator, the Property Palette is updated to show the properties of that object. By default, the list of properties in the palette is synchronized whenever you select a different object. You can turn synchronization On or Off for a specific palette by clicking the Freeze/Unfreeze button on the Property Palette toolbar.

When you need to compare the properties of two objects, you can invoke additional Property Palettes as needed.

The Property Palette has the following features:

Property List

The property list is a 2-column list of property names and property values. When no objects are selected, no properties are displayed in the list. You can select properties in the list by clicking and by navigating with the Up/Down arrow keys. You can set properties in the property list pane by selecting the property and then typing or double-clicking as required.

Name

The name field displays the name of the object currently selected in the Object Navigator or an editor. The Name field is not displayed when no objects are selected or when multiple objects are selected at the same time.

Set Property Controls

When a property is selected in the properties list, a text field, pop-list, or More button is displayed beside the property, as follows:

A text field is displayed when the current property can be set by entering a text value. For properties that require longer text values, there is an iconic button next to the text field that invokes a modal editor.

A poplist is displayed for properties that are either Yes/No, or that have a fixed set of valid values. You can cycle through the values by double-clicking repeatedly.

A More... button is displayed when the current property requires more complex values. Selecting the button invokes a dialog where you enter the required information.


Displaying the Property Palette

To display the Property Palette:

•	Choose Tools [image] Property Palette.

Or,

•	in the Object Navigator, double-click the object icon for any object except code objects and canvases. If the Property Palette is already displayed, double-clicking raises it in front of other windows.

To invoke a second Property Palette, Shift+double-click the object icon.

Or,

•	in the Layout Editor, double-click an item.

Or,

•	Click the desired object, then choose Properties from the right mouse button popup menu.


Toolbar commands in the Property Palette

  Related Topics

The toolbar provides quick access to commands. Click once on the icon for the command you want to execute.

Copy Properties	Copies the property settings currently selected in the Property Palette to the clipboard.

Paste Properties	Pastes the clipboard property settings to the list of properties in the Property Palette. Properties that are on the clipboard but not in the property list are ignored.

Add Property	Displays a list of values (LOV) from which you can choose a property to be added to a property class. This command is available only when the current single selection is a property class object.

Delete Property	Removes the property currently selected in the properties list. This command is available only when the current single selection is a property class object.

Property  Class	Creates a property class from the list of properties currently displayed in the palette. The new property class object is inserted under the Property Classes node in the Object Navigator and assigned a default name.

Inherit	Sets the current property to its default setting. If the property is based on a property class, the default setting is the setting defined in the class. If the current property list is not based on a property class, or is based on a class that does not include the current property, Inherit sets the property to the default value.  (Inherit re-sets the property to the Form Builder default for string values only, not for complex values such as those set in dialogs.)

Intersection/ Union	Toggles the Property Palette between union and intersection display modes. This option determines which properties appear when more than one object is selected at a time (a multiple selection).  In intersection mode (the default), only properties that the selected objects have in common are displayed. In union mode, the properties of all objects in the current selection are displayed.

Freeze/Unfreeze	Toggles Property Palette synchronization On and Off. When Freeze is Off (the default), the property list is updated to display the properties of objects you select in the Object Navigator and other windows. When Freeze is On, the property list is pinned and does not get updated, allowing you to compare it to other property lists.


Closing the Property Palette

To close the Property Palette:

•	Choose File [image] Close.


About the Layout Editor

The Layout Editor is a graphical design facility for creating and arranging interface items and graphic objects in a form.  In the Layout Editor, you work on a single canvas.  Canvases are displayed in windows at runtime. You specify the window a canvas will be displayed in by setting the canvas's Window property.

Layout Editor Context  The title bar of the Layout Editor window displays context information, including the name of the current form, the name of the canvas being edited, and the name of the current block. When you create an item by drawing it on a canvas in the Layout Editor, Form Builder assigns the item to the current block, as indicated by Layout Editor block context. You can change Layout Editor block context using the Block poplist on the toolbar.

Rulers  The horizontal and vertical rulers at the top and left side of the workspace provide a reference for sizing and arranging objects in the  Layout Editor.  To hide rulers, deselect the Rulers option on the View menu.

Layout Editor ruler units can be set to character cells, inches, centimeters, or points. To display the Ruler Settings dialog, choose View [image] Settings [image] Ruler Settings.

Grid  There is a grid defined within the workspace that helps you position objects.  The grid is rendered in the current ruler units.  To hide the grid lines, deselect the Grid option in the View menu.

Ruler Guides  Ruler guides are horizontal and vertical dotted lines that can be used as references when aligning objects on a canvas.  To create a ruler guide, position the pointer on either ruler, then click and drag into the workspace.  Ruler guides are not displayed at runtime.

To move a ruler guide, drag it to a different location.  To delete a ruler guide, drag it out of the workspace.  To temporarily hide ruler guides without deleting them, deselect the Ruler Guides option in the Arrange menu.

Status Line  The status line at the bottom of the Layout Editor window displays the following information:

•	absolute mouse position

•	mouse drag distance (when creating/moving objects)

•	rotation angle (when rotating the current selection)

•	magnification level

Note: You cannot clear, cut, copy, duplicate, or export the following objects in the Layout Editor:

•	the canvas object (when the View [image] Show Canvas option is On)

•	the view rectangle (when the View [image] Show View option is On)

•	a block scroll bar


Displaying the Layout Editor

To display the Layout Editor:

•	Choose Tools [image] Layout Editor, then select the canvas you want to work on:

•	If there is more than one canvas defined in the form, Form Builder displays a list of values (LOV) from which you can select the canvas you want to edit.

•	If there is only one canvas in the form, Form Builder displays it in the Layout Editor automatically.

•	If there are no canvases in the form, Form Builder creates a default canvas.

Or

•	In the Object Navigator, double-click the object icon for the canvas you want to edit.

Or

•	In the Object Navigator, choose Layout Editor from the popup menu. (On Microsoft Windows, press the right mouse button to display the popup menu.)

You can open more than one Layout Editor at the same time, and you can copy and paste objects between them as needed.


The Layout Editor tool palette

The tool palette contains the following types of tools:

•	Layout Tools

•	Graphic Drawing Tools

•	Item Drawing Tools

•	Fill/Line Color Palettes

Use Layout Editor tools to create and manipulate items and graphic objects.  The Select tool is the default tool.  It allows you to select and manipulate objects and groups.  To activate a different tool, click on its icon in the tool palette.

Clicking on a tool makes it the active tool for a single operation, and highlights the border around its icon.  Double-clicking a tool icon pins  that tool to make it the default tool, and its icon changes to show its pinned status.

To display a popup description of a tool, move the cursor over its icon without clicking the mouse.


Switching to a different canvas-view in the Layout Editor
Switching to a different canvas in the Layout Editor

To display a different canvas in a Layout Editor:

•	Select a specific canvas from the Canvas poplist.

The Canvas poplist displays all the canvases defined in the current form.


Closing the Layout Editor

To close the Layout Editor:

•	Choose File [image] Close.


About the PL/SQL Editor

The PL/SQL Editor is where you enter and compile code objects. Code objects in Form Builder include event triggers, subprograms (functions and procedures), menu item commands, menu startup code, and packages.


Displaying the PL/SQL Editor

To display the PL/SQL Editor:

Choose Program [image] PL/SQL Editor.

Or

•	In the Object Navigator, double-click the object icon for any code object.

Double-clicking the icon for a trigger or program unit when a PL/SQL Editor is already displayed synchronizes the editor to that object. To invoke a separate PL/SQL Editor for the object, Shift+Double-click instead.


PL/SQL Editor context

The Type and Object options at the top of the PL/SQL Editor define the current object context. The Name option lists all of the code objects defined in that context.

When you invoke the PL/SQL Editor, if the currently selected object is a code object or an object with which code objects are associated, the PL/SQL Editor is synchronized to that object's context. If there is a code object defined in the current context, it is displayed in the PL/SQL Editor. If no code objects are defined, the Name field is blank, and you can choose New to create a new code object.

You can change the Type, Object, and Name options when you want to view code objects defined in a different context, or when you want to create a new code object in a different context.

Type  Sets editor context to a specific type of code object. When the current module is a form, Type can be set to Trigger or Program Unit. When the current module is a menu, Type can be set to Menu Startup Code, Menu Item Code, or Program Unit. When the current module is a library, Type is always Program Unit.

Object  Sets editor context to a specific object scope. When Type is set to Trigger, object scope can be set to form by selecting Form Level in the first poplist. To set editor context to a particular block, select the  name of the block in the first Object poplist. To set editor context to an item, select the block that contains the item in the first Object poplist, then select the item itself in the second poplist.

When the current module is a menu, you can edit menu item PL/SQL commands by setting Type to Menu Item Code, then selecting the menu on which the item appears in the first object Object poplist, and the menu item itself in the second poplist.

Name The Name option lists all of the code objects defined in the current context. Selecting a code object from the Name poplist makes that object the current object in the editor. For example, when context is set to item-level trigger, the Name poplist shows all of the triggers attached to that item. To display a particular trigger, select it from the Name poplist.

When editor context is set to Program Unit, the Name poplist shows all subprograms and packages defined in the current module.


PL/SQL Editor commands

Compile	Compiles the code in the Source Code field. The compiler detects syntax errors, semantic errors, and references to non-existent objects, procedures, and functions.  When you compile successfully, the status line displays the message <Successfully Compiled>.

Revert	Undoes any changes that were made to the source text since the editor was invoked or since the last Revert operation.  Revert button is disabled when no changes have been made to source text.

New	Creates a new code object of the same type and scope as the current code object. For example, when the current object is a trigger attached to an item, choosing New displays the Triggers LOV to allow you to create a new trigger attached to that same item. When the current object is a program unit, choosing New invokes the New Program Unit dialog box.

Delete	Deletes the current code object and synchronizes the PL/SQL Editor to the next object of that type at the same scope.

Close	Closes the PL/SQL Editor.

Help	Displays a Help topic.

Clicking a   message	Moves the insertion point to the line at which an error was detected in the source code pane.

Message Pane  Displays compilation messages if an error occurs when you compile the current program unit.

Status Bar  Displays status information about the current code object.  The <Not Modified|Modified> lamp indicates whether unsaved changes are pending.  The <Not Compiled|Successfully Compiled|Compiled with Errors> lamp indicates the current compilation status.


Closing the PL/SQL Editor

To close the PL/SQL Editor:

•	Click the Close button in the PL/SQL Editor.


About the Object Library

  Related Topics

In any development environment, you will always have standards to which you want your developers to adhere as well as common objects which can be reused throughout the development effort.

The Object Library provides an easy method of reusing objects and enforcing standards across the entire development organization.

You can use the Object Library to:

•	create, store, maintain, and distribute standard and reusable objects.

•	rapidly create applications by dragging and dropping predefined objects to your form.

There are several advantages to using object libraries to develop applications:

•	Object libraries are automatically re-opened when you startup Form Builder, making your reusable objects immediately accessible.

•	You can associate multiple object libraries with an application.  For example, you can create an object library specfically for corporate standards, and you can create an object library to satisfy project-specific requirements.

•	Object libraries feature SmartClasses-- objects that you define as being the standard.  You use SmartClasses to convert objects to standard objects.


Displaying the Object Library

  Related Topics

To display the Object Library:

•	Choose Tools [image] Object Library.


Opening an Object Library module

  Related Topics

To open an Object Library module:

1	In the Object Library, click the Open button.

2	In the dialog, type the name of the desired file.


Creating a tab in the Object Library

To create a tab:

1	In the Object Navigator, click the Library Tabs node for the desired object library.

2	Click the Create button [image] in the toolbar.

3	Specify a name for the new tab.


Commenting objects in the Object Library

To add a comment:

1	In the Object Library, click the desired object.

2	Click the Edit Comment icon in the toolbar.

3	Type the desired text in the Comment dialog.


Removing an object from the Object Library

  Related Topics

To remove an object from the Object Library:

1	In the Object Library, click the desired object.

2	Click the Delete Object button in the toolbar.


Deleting a tab in the Object Library

To delete a tab from the Object Library:

1	In the Object Library, click the desired tab.

2	Click the Delete Tab button in the toolbar.

Note: When you delete a tab, you delete all of the objects on the tab.


Saving an object in the Object Library

To save objects in the Object Library:

1	In the Object Library, click the Save button.

2	In the dialog, type a name.

3	Click Save.


Closing the Object Library

To close the Object Library:

•	Choose File [image] Close.


About the Menu Editor

  Related Topics

The Menu Editor is a Form Builder design tool you use (along with the Object Navigator and Property Palette) to create and arrange custom form menu modules and popup menus.

Before you can use the Menu Editor to work with menu objects, you must create a new menu module (or open an existing one) in the Object Navigator.

Synchronization  Whether you work in the Menu Editor, the Object Navigator, or the Property Palette, Form Builder automatically synchronizes its design tools to simultaneously display the currently-selected object, even if Form Builder must expand nodes and menus to display the object.  So as you work with menus, the same menu object always is selected in the Menu Editor, the Object Navigator, and the Property Palette.


Displaying the Menu Editor

To display a menu module in the Menu Editor:

1	In the Object Navigator, create a new menu module, or select an existing menu module.

2	Choose Tools [image] Menu Editor, or double-click the menu module's object icon in the Object Navigator.

Form Builder displays the menu module in the Menu Editor.

You can display multiple menu modules at the same time in separate Menu Editor windows.  With one Menu Editor window open, select another menu module in the Object Navigator, then display a second Menu Editor window.


Creating objects in the Menu Editor

  Related Topics

To create new menu objects below an existing menu object:

1	Select an existing main menu item, or lower-level menu item in the Menu Editor.

2	Do one of the following:

•	Click the Create Down button in the Menu Editor toolbar

•	Choose Menu [image] Create Down

•	Press the key sequence Ctrl-Down arrow

A new menu object appears below the existing menu object.

To create a menu item to the right of an existing menu object:

1	Select an existing menu, submenu, or menu item in the Menu Editor.

2	Do one of the following:

•	Click the Create Right button in the Menu Editor toolbar

•	Choose Menu [image] Create Right

•	Press the key sequence Ctrl-Right arrow

A new menu object appears to the right of the existing menu object.

Menu Item Handles  Note that each time you add the first item to a lower-level menu or submenu, Form Builder places a shaded rectangle, or handle, to the left of the object.  Use the handle to perform operations on all menu items as a unit, or to display the Menu-level properties in the Property Palette.


About displaying objects in the Menu Editor

  Related Topics

If you want to know what menu a particular item belongs to, double-click on the menu handle, and check the Name property in the Property Palette.  The menu handle in the Menu Editor corresponds to the menu name in the Object Navigator.

Note:  The upper-most menu item on a menu is not the first item on the menu; it belongs instead to its parent menu.


Expanding and collapsing menu objects in the Menu Editor
About expanding and collapsing menu objects

  Related Topics

Expanding and collapsing objects (lower-level menus and submenus) in the Menu Editor is similar to collapsing and expanding Form Builder objects in the Object Navigator.  The triangular Expand/Collapse indicators in the Menu Editor are equivalent to the Object Navigator's + and - indicators.  An outlined triangle indicates that a menu is expanded;  a solid triangle indicates that a menu is collapsed.

You can either expand or collapse a menu object one level (using Expand or Collapse), or you can expand or collapse all related levels of a menu object (using Expand All and Collapse All).  Related menu object levels refers to the current menu object, and all objects below or to the right of the object.

The object you select in the Menu Editor (before you expand or collapse) defines the extent of the operation.  If you select:

•	a shaded menu handle, Expand, Expand All, Collapse, or Collapse All apply to all menus and submenus connected to that menu structure.

•	a menu item, Expand, Expand All, Collapse, or Collapse All apply only to lower-level menus and submenus connected to that menu item.


Expanding and collapsing individual objects in the Menu Editor

  Related Topics

To expand and collapse individual menu objects:

1	Select an object that displays an Expand/Collapse triangle indicator.

2	Do one of the following to toggle between expanded and collapsed states:

•	double-click the triangle indicator

•	press Return

•	choose Menu [image] Expand or Menu [image] Collapse


Expanding and collapsing related objects in the Menu Editor

  Related Topics

To expand and collapse related menu objects:

1	Select an object that displays an Expand/Collapse triangle indicator.

2	Do one of the following to toggle between fully-collapsed and fully-expanded states:

•	Shift double-click the triangle indicator

•	press Shift-Return

•	choose Menu [image] Expand All or Menu [image] Collapse All


Displaying a menu at the top level of the Menu Editor

  Related Topics

To display a menu at the top level of the Menu Editor:

1	In the Menu Editor toolbar, click the Display Menu poplist.

2	Select the menu you want to display as the top-level menu.

Form Builder temporarily displays the lower-level menu as the top-level menu in the Menu Editor.  To return to the original display, select the main menu from the Display Menu poplist.

Note:  Displaying a lower-level menu as the top-level menu in the Menu Editor is for temporary design purposes only, and stays in effect during the current design session only.  At runtime, the main menu always is the top-level menu.


Working with Menu Editor orientation

  Related Topics

To change the Menu Editor orientation:

1	In the Object Navigator, select the menu.

2	Choose Tools [image] Menu Editor to open the Menu Editor.

3	Choose Menu [image] Switch Orientation.


Changing object names and labels in the Menu Editor

  Related Topics

To change the name of a menu object:

1	Select the menu object in the Menu Editor.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the General node, change the object's Name property.

Note:  You will not see the effect of this change in the Menu Editor (unless the object is a menu, in which case you can view the new name in the Display Menu poplist).

To change the label of a menu object:

1	In the Menu Editor, select the menu object.

The label displays in reverse.

2	Click again to enter edit mode.

The cursor changes to an I-beam, the reverse display returns to normal, and the I-beam cursor is set wherever you clicked.

3	Replace the old label with a new label.

To end edit mode, press Return.  To verify the label change, check the object's Label property in the Property Palette.

Note:  The first time you edit a menu object's label in the Menu Editor or Property Palette, the Object Navigator and the Property Palette automatically reflect this change (as closely as possible) in the object's name, making it easy for you to find the item you just created.  For example, if you change the label for object ITEM2 from <New Item> to Show Keys, Form Builder automatically changes the object's name from ITEM2 to SHOW_KEYS.  Additional changes to the object's label, however, will not be automatically reflected in the object's name.


Moving objects in the Menu Editor

To move a menu:

1	Click and drag the shaded menu handle.

When you click on a handle, it displays as a solid rectangle, the cursor changes to a plus sign (+), and as you move the cursor to a specific location, Form Builder highlights the places where you can drop the menu.

2	Drop the menu in the desired location.

Note:  Moving a menu also moves its associated submenus.

To move a menu item:

1	Click and drag the menu item.

When you drag an item, Form Builder displays a heavy line to indicate where you can appropriately drop the item.

2	Drop the menu item in the desired location.

Note:  A menu item that displays a submenu must have its Command Type property set to Menu.  Accordingly, if you move a submenu to a parent item with Command Type set to PL/SQL or Null, Form Builder displays an alert:

RM-15207: Parent item requires type change before submenu is attached. (Code may be lost.)

3	Do one of the following:

•	Choose Change type to accept the type change, unless you have PL/SQL code attached to that menu item that you want to save.

•	If you have PL/SQL code attached to that menu item, choose Cancel and copy the PL/SQL code before you move the item.


Copying objects in the Menu Editor

To copy a menu:

1	Control-drag the shaded menu handle to the target item.

When you click on a handle, it displays as a solid rectangle, the cursor changes to a plus sign (+), and as you move the cursor to a specific location, Form Builder highlights the places where you can drop the menu.

Form Builder then displays the alert:

   Duplicate menu or reuse original?

2	Do one of the following:

•	Choose Duplicate to make a separate copy of the menu.

If there are any submenus, Form Builder then displays the message:

   Copy submenus?

Select Yes to copy all levels of submenus, No to copy just the first level.

•	Choose Reuse original to keep just one copy of the menu, but refer to it from two places.

Reuse original does not create a new instance of the original, but merely defines a pointer to the original.  This allows you to invoke the same menu from more than one menu item.  Both menus are identical and share the same name, thus they both display the Shared indicator.  Any subsequent changes to either instance of the menu also will appear on the other menu.

Hint:  If you have one instance of a shared menu selected and want to know where the other instances are, choose Menu [image] Next Instance.

To copy a menu item:

•	Select the menu item, then control-drag the menu item to the target item.


Deleting objects in the Menu Editor

To delete a menu or submenu:

1	Click on the menu or submenu handle.

2	Do one of the following:

•	click the Delete icon in the Menu Editor toolbar

•	select Menu [image] Delete

•	press Delete

Form Builder displays an alert:

   Do you want to detach the menu from its   parent or delete it?

3	Choose Delete, unless you plan to reuse the resulting menu fragment.

If the menu to be deleted has submenus under it, Form Builder displays a message asking if you want to delete submenus.

•	Choose Yes to delete the entire structure, including submenus.

•	Choose No if you want to save the submenu structure for later use.  (To use the orphaned submenu, go to the Object Navigator and move it to a new location.)

Choose Detach if you want to keep the menu fragment for later reuse.  (To re-attach the fragment, go to the Object Navigator and attach the menu fragment to a new parent.)

To delete items from a menu or submenu:

1	Select the item.

2	Choose Menu [image] Delete (or click on the Delete icon).

Form Builder displays an alert asking if you are sure you want to delete.

3	Click Yes.


Creating a main menu

  Related Topics

To create a main menu:

1	Display the menu module in the Menu Editor.

The Menu Editor appears, displaying a menu called MAIN_MENU.  A single item, labeled <New Item>, is highlighted.

2	Enter a more descriptive label (e.g., Action).

3	Add new main menu items by creating new menu objects to the right of the existing main menu item.

The Menu Editor creates items, labelled <New Item>.

4	Replace the default labels.

5	Repeat steps 3 and 4 to create additional main menu items.

Once you create the main menu, create individual menus by adding items below each main menu item.  For each "parent" item on the main menu (such as Action, Edit, Block, etc.), you can create a list of related "child" menu items.


Creating lower-level menus

  Related Topics

To create a lower-level menu:

1	In the main menu, select a parent item.

2	Create a new menu object below the existing main menu item.

The Menu Editor creates a menu item, labelled <New Item>.

3	Replace the default label.

4	To create additional items, repeat steps 2 and 3.

Note:  By adding menu items below the main menu parent item, you have converted the parent item into a menu heading.  Form Builder automatically switches the parent item's Command Type property to reflect this.  Examine the parent item's properties in the Property Palette;  the Command Type property has changed from PL/SQL to Menu.

Once you create a menu off of the main menu, you can create submenus, which are displayed to the right of menu items.


Creating submenus

  Related Topics

To create a submenu:

1	Select an individual menu item.

2	Create a new menu object to the right of the existing menu item.

The Menu Editor creates a menu item, labelled <New Item>.

3	Replace the default label.

4	Create a new menu object below the submenu item you just created.

5	Replace the default label.

6	Repeat steps 4 and 5 to create additional submenu items.


About the wizards

Form Builder includes several wizards to automate frequently performed tasks for both beginning and advanced users.

Using a wizard, you can do the following:

•	create or modify a form

•	create or modify a data block

•	create and arrange items within a frame

•	create or modify an LOV

•	create or modify chart item

To invoke a wizard:

•	Choose the desired wizard option from the Tools menu.


Editing text in Form Builder

This section describes the commands you can use to edit and select text in Form Builder. You can enter text in Insert mode or Replace mode. The current editing mode is displayed on the status line in the form builder. To switch modes, press [Insert/Replace].

You can use the following commands to edit text.

If you want to...	Do this...
Move one character to the left or right.	Press [Left] or [Right].
Move to the next line or previous line in an editor.	Press [Up] or [Down].
Move to the end of the line.	Press [End of Line].
Move to the beginning of a line.	Press [Beginning of Line].
Select text with the mouse.	Click and drag the desired text.
Delete selected text.	Select Edit [image] Clear.
Delete selected text and copy it to the clipboard.	Select Edit [image] Cut. Or press [Cut].
Copy selected text to the clipboard.	Select Edit [image] Copy. Or press [Copy].
Insert clipboard text at the insertion point.	Select Edit [image] Paste. Or press [Paste].
Delete the character to the left of the insertion point	Press [Delete Backwards].


Creating Editors


About editors

  Related Topics

There are three editors that can be used at runtime: the default editor, a system editor, or a user-named editor.

Default Editor	The default editor provides standard editing features, including search/replace and cut, copy, and paste.  The default editor is built into every form and is automatically available from every text item.

System Editor	If there is a system editor available, you can specify that Form Builder should use the current system editor, rather than the default editor.

User-Named Editor	A user-named editor has the same text editing functionality as the default editor, but, because it is a named object, you can specify editor attributes such as window display size, position, and title.  Also, a user-named editor can be displayed programmatically with the built-in procedure SHOW_EDITOR, independent of any particular text item.

By default, operators can invoke an editor by navigating to a text item and pressing [Edit] or by choosing Edit [image] Edit on the default menu.  An editor can also be displayed programmatically by executing the EDIT_TEXTITEM built-in procedure when the cursor is in a text item.


Using the default editor

  Related Topics

Unlike user-named editors, you do not have to create or attach the default editor; it is built into every form and can be invoked from any text item.

When the default editor is invoked at runtime, Form Builder determines its display size and position dynamically based on the size and position of the text item from which the editor was invoked.

To modify the default editor's display size and position:

1	In the Object Navigator, select the desired text item.

2	In the Property Palette, set the Editor property to <Null> by selecting <Null> from the Editor property poplist.

3	Specify the editor's display coordinates by setting the Editor X Position and Editor Y Position properties.


Using a user-named editor

  Related Topics

A user-named editor has the same text editing functionality as the default editor.  You create a user-named editor when you want to display the editor programmatically with SHOW_EDITOR, or when you want to specify custom editor attributes such as scroll bar and title.

Once you define a user-named editor, you can attach it to any text item in the form.  When the operator navigates to the text item and invokes an editor, the user-named editor replaces the default editor for that item.

To create a user-named editor:

1	In the Object Navigator, create an editor object.

To create an editor, select the Editors node in the Object Navigator and then choose Navigator [image] Create.

2	In the Property Palette, set the desired editor properties, including Height, Width, X Position, Y Position, Wrap Style, Horizontal Scroll Bar Canvas, Vertical Scroll Bar Canvas, and so on.

3	Attach the editor to one or more text items in your form or display the editor by calling the SHOW_EDITOR built-in procedure.

To attach a user-named editor to a text item:

1	In the Object Navigator, select the desired text item.

2	In the Property Palette, set the Editor property to the desired user-named editor by selecting it from the Editor property poplist.

3	Specify the editor's display coordinates by setting the X Position and Y Position properties.


Using a system editor

  Related Topics

You can specify that Form Builder should use a system editor, rather than the default editor.  Operators invoke the system editor in the same manner as the default editor.

The system editor to be used is defined by the FORMS60_EDITOR environment variable.  The editor specified must use the ASCII text format.  For information on environment variables and system editor availability, refer to the Form Builder documentation for your operating system.

To use a system editor:

1	In the Object Navigator, select the desired text item.

2	Double-click the icon beside the text item to display the Property Palette.

3	In the Property Palette, select SYSTEM_EDITOR from the Editor property poplist.

4	Specify the editor's display coordinates by setting the Editor X Position and Editor Y Position properties in the Property Palette.

5	Define the FORMS60_EDITOR environment variable.

For example, on Microsoft Windows, you can use the Notepad as a system editor by defining FORMS60_EDITOR as:

FORMS60_EDITOR = C:\WINDOWS\NOTEPAD.EXE


Using EDIT_TEXTITEM to display an editor

  Related Topics

The EDIT_TEXTITEM procedure invokes the editor associated with the current text item in the form (the default editor, a user-named editor, or the current system editor).  The following example navigates to a text item and then displays the editor associated with that item.

Go_Item('cust.comments');
Edit_TextItem;

The input focus must be in a text item for EDIT_TEXTITEM to execute successfully.  If the input focus is in any other type of item, Form Builder displays the message FRM-41026: Item does not understand operation.  EDIT_TEXTITEM has optional parameters that allow you to specify dynamic size and position coordinates:

Edit_Textitem(x, y, width, height);


Using SHOW_EDITOR to display an editor

  Related Topics

The SHOW_EDITOR procedure displays a user-named editor at the specified display coordinates.  SHOW_EDITOR takes message_in and message_out parameters that allow you to pass a text string in to the editor and to get the edited text string back when the operator accepts the editor.

SHOW_EDITOR(editor_name, message_in, x, y, message_out, result);

The result parameter is a BOOLEAN IN OUT parameter.  If the operator accepts the editor, SHOW_EDITOR sets result to TRUE, and sets message_out to the current text string.  If the operator cancels the editor, SHOW_EDITOR sets result to FALSE and sets message_out to NULL.


About handling runtime errors in triggers

  Related Topics

When you compile a trigger at design time or generate a form module, the compiler detects any errors that would prevent the trigger from executing successfully at runtime.  Other errors, however, manifest only at runtime, and are often impossible to avoid.

When a runtime error occurs, you need to detect and respond to the error in your trigger code so it does not interrupt the flow of the application.  Triggers should be written to handle runtime errors gracefully, rather than allowing them to disrupt the work of the form operator.

Form Builder default functionality helps you handle runtime errors by detecting errors as they occur, issuing error messages, setting the values of error variables, and, when appropriate, rolling back transactions that cannot be completed successfully.  You can supplement default error handling by writing triggers that respond to errors in an application-specific manner.

Note:  This section assumes you are familiar with PL/SQL error handling techniques.  Refer to the PL/SQL User's Guide and Reference for more information.


About using PL/SQL exception handling in triggers

  Related Topics

Errors in PL/SQL code are called exceptions. When an error occurs, an exception is raised. To handle raised exceptions, you can write exception handlers. In Form Builder, you can use exception handlers to handle runtime errors that occur in the following types of statements:

•	SQL statements

•	PL/SQL statements

•	calls to user-named subprograms

When one of these statements in a trigger or PL/SQL block raises an exception, normal processing stops and control transfers to the trigger's exception handling section.

How Exceptions Propagate in Triggers  PL/SQL blocks can be nested as in-line blocks in Form Builder triggers.  For example, a trigger might include a block that encloses another block.

When the inner block raises an exception for which there is no exception handler, that block terminates and the exception propagates, or "falls out," to the enclosing block.  If a handler is not found in the enclosing block, the exception propagates again, finally reaching the outermost block of the trigger.  If the outer block does not handle the exception, the trigger fails, and Form Builder returns a runtime error.

Exceptions Raised in User-Named Subprograms  For purposes of exception handling, calls to user-named subprograms are treated as in-line PL/SQL blocks within a trigger.  That is, an unhandled exception raised in a user-named subprogram propagates to the block in which the subprogram was called.


About trigger failure results

  Related Topics

Once a trigger fires, it can end with either success or failure.  A trigger fails when it raises an unhandled exception.  When this occurs, Form Builder aborts the trigger and performs the appropriate post-failure processing.  The specific processing that Form Builder performs depends on the type of trigger that failed.

The following table shows the post-failure processing for three types of triggers:

Trigger Type	Result of Trigger Failure
Key - * (any key trigger)	Trigger failure is ignored.
Pre-Item	Form Builder attempts to return input focus to the source item.
On-Insert	Form Builder rolls back all database changes posted by the current commit process and attempts to navigate to the first item in the current record of the block in error.
When-Validate-Item	Item validation fails. Form Builder sets the error location. When possible, input focus is returned to the source item.

When a trigger fails, Form Builder tries to undo any conditions that would cause a runtime error as a result of the trigger's failure.

For example, the Pre-Item trigger fires when Form Builder attempts to move the input focus from a source item to a target item.  When a Pre-Item trigger fails, navigation cannot be completed successfully, so Form Builder returns the input focus to the source item.

Similarly, when a commit processing trigger such as On-Insert fails, Form Builder performs the appropriate rollback to ensure data integrity.


About handling exceptions raised in triggers

  Related Topics

When you write triggers that include SQL statements, PL/SQL statements, or calls to user-named subprograms, you should consider how you will handle any exceptions that are raised.  Depending on the behavior desired, you can respond to exceptions in one of three ways:

•	Write exception handlers in the trigger to handle all raised exceptions.

•	Take advantage of Form Builder default post-failure trigger processing by deliberately omitting exception handlers; when an exception is raised, the trigger fails, and the appropriate post-failure processing occurs.

•	Write exception handlers for only the specific exceptions you want to handle in the trigger, and leave any other exceptions unhandled to deliberately cause the trigger to fail.


Responding to errors

  Related Topics

When an error occurs, you can use the following built-in subprograms to get information about the error, including the error number, type, and message:

•	ERROR_TYPE (returns CHAR)

•	ERROR_CODE (returns NUMBER)

•	ERROR_TEXT (returns CHAR)

•	DBMS_ERROR_CODE (returns NUMBER)

•	DBMS_ERROR_TEXT (returns CHAR)


About evaluating the success or failure of built-ins

  Related Topics

A built-in subprogram can have one of three outcomes: success, failure, or fatal error.  When a built-in subprogram fails, a runtime error occurs, and Form Builder responds by issuing the appropriate error message.  However, no exception is raised in the trigger.  For this reason, the trigger itself does not fail, and any subsequent statements in the trigger are executed.

When you call built-in subprograms in triggers, you will often want to trap the success or failure of the subprogram so that you can either correct any errors or cause the trigger to fail explicitly. This is particularly true when subsequent trigger statements depend on the successful outcome of a preceding built-in subprogram.

To trap the success or failure of a built-in subprogram, use the following Form Builder built-in functions:

•	FORM_SUCCESS (returns BOOLEAN)

•	FORM_FAILURE (returns BOOLEAN)

•	FORM_FATAL (returns BOOLEAN)

These functions report on the outcome of the most recently executed built-in subprogram.  In the following When-Button-Pressed trigger, the function FORM_SUCCESS is used to test the outcome of the GO_BLOCK built-in procedure:

Go_Block('xyz_block');

IF NOT Form_Success THEN

--handle the error

END IF;

This test detects both fatal and failure-type errors, and so is more encompassing than FORM_FAILURE or FORM_FATAL used alone.


Handling errors in built-in subprograms

  Related Topics

When a built-in subprogram fails or causes a fatal error, you might want to direct the trigger from which the subprogram was called to fail, rather than allowing Form Builder to continue processing subsequent trigger statements.

In a previous topic, you saw that a trigger fails when it raises an unhandled exception.  However, because errors in built-in subprograms do not raise exceptions, you must raise an exception explicitly in your code to cause a trigger to fail:

/*  When-Button-Pressed Trigger:  */

Go_Block('xyz_block');

IF NOT Form_Success THEN

RAISE Form_Trigger_Failure;

END IF; END IF;

Because this trigger does not have an exception handling section, raising an exception causes the trigger to fail, and Form Builder performs the post-failure processing appropriate for the trigger.  Although any valid exception can be raised to cause a trigger to fail, the example uses the built-in exception FORM_TRIGGER_FAILURE.


Raising the FORM_TRIGGER_FAILURE exception

  Related Topics

The FORM_TRIGGER_FAILURE exception is a predefined PL/SQL exception available only in Form Builder.  Because it is predefined, you can raise this exception without having to first define it in the declarative section of a trigger or user-named subprogram.

Indeed, this exception is used so often in Form Builder that it is common to write a user-named procedure that can be used to test the outcome of built-in procedures and functions:

/*  user-named subprogram:  */

PROCEDURE Check_Builtin ISBEGIN

IF NOT Form_Success THEN

RAISE Form_Trigger_Failure;

END IF; END;

You can define the procedure in a form or an attached library and then call it from any trigger in your form:

/*  When-Button-Pressed Trigger:  */

Go_Block('xyz_block');

Check_Builtin;

Note:  Do not use the internal error code associated with the FORM_TRIGGER_FAILURE exception, because the internal error code can change without notice.


Handling errors in user-named triggers

  Related Topics

User-named triggers are invoked by calling the EXECUTE_TRIGGER built-in subprogram:

/*  Built-in Trigger:  */

statement a;

Execute_Trigger('my_user_named_trigger');

statement b;

When an unhandled exception is raised in a user-named trigger, the user-named trigger fails, but the exception does not propagate to the calling trigger.  Rather, Form Builder treats the failure as an error in the built-in procedure EXECUTE_TRIGGER, and sets the return values of the built-in error functions accordingly. Thus, the outcome of a user-named trigger can be trapped in the same way as a call to any other built-in subprogram; that is, by evaluating the built-in error functions:

/*  Built-in Trigger:  */

statement a;

Execute_Trigger('my_usernamed_trigger');

IF NOT Form_Success THEN

RAISE Form_Trigger_Failure;

END IF;

statement b;


Error handling for stored procedures

  Related Topics

There are three primary methods for trapping ORACLE errors that are returned from the kernel during the processing of your PL/SQL code:

•	checking DBMS_ERROR_TEXT and DBMS_ERROR_CODE built-in subprograms within a form-level ON-ERROR trigger

•	creating appropriate user-defined exceptions

•	evaluating the SQLCODE and SQLERRM functions in a WHEN OTHERS exception handler


Checking DBMS_ERROR_TEXT and DBMS_ERROR_CODE

  Related Topics

From within an ON-ERROR trigger, you can check to see if the ERROR_CODE function reports any of the following database-related errors:

40501: ORACLE err - unable to reserve record for update or delete

40502: ORACLE err - unable to read list of values

40505: ORACLE err - unable to perform query

40506: ORACLE err - unable to check for record uniqueness

40507: ORACLE err - unable to fetch next query record

40508: ORACLE err - unable to INSERT record

40509: ORACLE err - unable to UPDATE record

40510: ORACLE err - unable to DELETE record

40512: ORACLE err - unable to issue SAVEPOINT command

40513: ORACLE err - unable to get date/time from database

40504: ORACLE err - unable to execute a gname trigger

40511: ORACLE err occurred while executing a gname trigger

Once you know that some database error has caused form processing to fail, you can interrogate the DBMS_ERROR_TEXT and DBMS_ERROR_CODE functions to determine exactly what server error has occurred. The full text of the error message is available in the return value for DBMS_ERROR_TEXT.


User-defined exceptions

 Examples	     Related Topics

Although PL/SQL includes many pre-defined exceptions—such as NO_DATA_FOUND, DUP_VAL_ON_INDEX, and VALUE_ERROR— they will never completely cover the range of ORACLE errors you may need to trap.  So PL/SQL provides the facility to define your own exceptions and associate them with the occurrence of a particular Oracle error of your choice. The following code illustrates how to use EXCEPTION_INIT to tell PL/SQL to report an error of your choice.  For more information refer to the PL/SQL User's Guide and Reference.


User-defined exceptions examples

Example

/*

**	Example of declaring your own error-driven exceptions

*/

DECLARE

    /*

    ** First declare the name of the exception

    */

    cannot_del_parent  EXCEPTION;

    /*

    ** Then associate it with the ORA-2292 error

    ** which is "violated integrity constraint XYZ -

    ** child record found". Note error number is negative.

    */

    PRAGMA Exception_Init (cannot_del_parent, -2292);

BEGIN

    DELETE FROM PARENT_TABLE

    WHERE PRIMARY_KEY_FIELD = :BLOCK.PK;

    /*

    ** If we get here, then things went ok.

    */

EXCEPTION

    /*

    ** If our error arises, then this exception

    ** will be raised. We can deal with it elegantly.

    */

    WHEN cannot_del_parent THEN

       Message('You cannot remove open '||

       'order number'||:block.pk);

       RAISE Form_Trigger_Failure;

END;

This method is best when the ORACLE error number itself is enough to allow your application to determine what happened. User-defined error messages can be returned from database triggers, procedures, or functions, as shown earlier with RAISE_APPLICATION_ERROR. Creating corresponding user-defined exceptions is a natural counterpart to trapping the errors you raise.

However, some errors returned by the kernel contain the name of the constraint (out of many possible ones) that has been violated, always returning a single ORACLE error number. An example of this would be:

ORA-02290: violated check constraint (SCOTT.C_CK)


Trapping SQLCODE and SQLERRM

 Examples	     Related Topics

In this case, we need access to the error message itself to gain knowledge about what went wrong. The WHEN OTHERS clause must be used so the SQLCODE and SQLERRM can be captured and evaluated. These two PL/SQL functions, which mimic their PRO*Language analogs, are only available within an exception handler, and are most useful in a WHEN OTHERS clause.  In addition, the function called strip_constraint_name will accept the text of an Oracle error and return in capital letters the name of the constraint that was violated. Consider two examples:


Trapping SQLCODE and SQLERRM examples

Example 1

/*

** Example of using SQLCODE/SQLERRM in WHEN OTHERS

*/

DECLARE

    lv_sqlcode NUMBER; /* Place to hold SQLCODE */

    lv_sqlerrm VARCHAR2(240); /* Place to hold SQLERRM */

    lv_constr  VARCHAR2(41); /* Place for Constraint Name */

BEGIN

    UPDATE PARENT_TABLE

       SET SOME_FIELD = 5

    WHERE PRIMARY_KEY_FIELD = :BLOCK.PK;

    /*

    ** If we get here, then things went ok.

    */

EXCEPTION

    /*

    ** If an error arises, the exception handler gets control

    */

    WHEN OTHERS THEN

       lv_sqlcode := SQLCODE;

       lv_sqlerrm := SQLERRM;

       IF (lv_sqlcode = -2290) THEN

          /*

          ** Strip out the name of the violated constraint

          */

          lv_constr := strip_constraint_name(lv_sqlerrm);

           IF (lv_constr = 'SCOTT.C_CK') THEN

                         Message('Code must be A,B, or C');

                         RAISE Form_Trigger_Failure;

          END IF;

       END IF;

END;

Example 2

/*  STRIP_CONSTRAINT_NAME:  Returns constraint name from error

**  Constraint name should appear enclosed by parentheses

**  in the Oracle errors 02290-02292 and 02296-02299.

**  Return the text between the parentheses when passed

**  the error message text.

*/

FUNCTION strip_constraint_name( errmsg VARCHAR2 )

RETURN VARCHAR2

IS

   lv_pos1 NUMBER;

   lv_pos2 NUMBER;

BEGIN

   lv_pos1 := INSTR(errmsg, '(');

   lv_pos2 := INSTR(errmsg, ')');

   IF (lv_pos1 = 0 OR lv_pos2 = 0 ) THEN

       RETURN(NULL);

     ELSE

        RETURN(UPPER(SUBSTR(errmsg, lv_pos1+1,

                               lv_pos2-lv_pos1-1)));

    END IF;

END;

To trap ORACLE errors that are a result of database block INSERT, UPDATE, and DELETE operations, you must code the respective ON-INSERT, ON-UPDATE, and/or ON-DELETE triggers to actually perform the DML operations so that you can trap the errors.

Errors related to the features discussed above that could be trapped by the first example are:

•	After a SET ROLE:

        ORA-01919: Role ROLENAME does not exist

        ORA-01979: Missing or invalid password

•	After relevant DML:

        ORA-00001: Duplicate key in index

        ORA-01400: Mandatory NOT NULL column missing

        ORA-01407: cannot update mandatory (NOT NULL)

                   column to NULL

        ORA-04088: error during execution of trigger

                  (OWNER.TRIGGERNAME)

        ORA-04092: trigger may not commit or rollback


About the Chart Wizard

  Next Step

About the Chart Wizard

The Chart Wizard leads you step-by-step through the process of creating a chart from within a form or a report.  It allows you to:

•	Specify a chart type and subtype.

•	Specify the data block that contains the data you want to assign to chart columns.

•	Specify the data that will appear on the Category (X) axis of the chart.

•	Specify the data that will appear on the Value (Y) axis of the chart.

Follow the prompts on each page of the wizard to specify the settings for the chart you want to create.

The Chart Wizard is Re-entrant

A powerful quality of the Chart Wizard is its ability to operate in re-entrant mode.  This means you can use the Chart Wizard to modify an existing chart created with the wizard.

To invoke the Chart Wizard in re-entrant mode, select the chart object in the Object Navigator, then choose Tools [image] Chart Wizard from the menu.

Navigating in the Chart Wizard

The Chart Wizard provides five buttons to help you navigate  through its pages:

•	Cancel-cancel all changes you have made (if any), and exit the wizard

•	Help-display online help text for the current page of the wizard

•	Back-navigate to the previous page in the wizard

•	Next-navigate to the next page in the wizard

•	Finish-save changes you have made with the wizard (if any), and exit the wizard

Note:  If you click Next or Back before you have entered all necessary information for a particular wizard page, the wizard prevents you from navigating to the next (or previous) page.  Similarly, if you have not entered all necessary information into the wizard when you click Finish, the wizard automatically displays the page on which you can enter the required data.


Chart Wizard:  Type page

  Next Step 	  About the Wizard

To use the Chart Wizard to specify a chart type:

1	(Optional) In the Title field, type the title that will appear above the chart.

2	In the Chart Type list, select the chart type. The chart type specifies the basic format of the display, such as a pie chart, or  bar chart. The display window displays an example of the chart type you select.

3	In the Chart Subtype list, select a chart subtype.  The chart subtype is a specific style or template for the display, such as Shadows.  The Chart Subtype list displays the possible subtypes for the chart type you selected.


Chart Wizard:  Block page

  Next Step 	  About the Wizard

To use the Chart Wizard to select a data block for your chart:

  In the Block Name list, click on the data block to use in your chart.  The data block you select determines the data that is available for assignment to the Category and Value axes of your chart.


Chart Wizard:  Category page

  Next Step 	  About the Wizard

To use the Chart Wizard to map data to your chart’s Category (X) axis:

1	In the Available Fields list, select the field that you want to map to the Category (X) axis of the chart.

Note:  You must select at least one field before navigating to the next page.

2	Click [image] to transfer the selected field from the Available Fields list to the Category Axis list.

Note:  You must transfer at least one field from the Available Fields list to the Category list before navigating to the next page.


Chart Wizard:  Value page

  Next Step 	  About the Wizard

To use the Chart Wizard to map data to your chart’s Value (Y) axis:

1	In the Available Fields list, select the field that you want to map to the Value (Y) axis of the chart.

2	Click [image] to transfer the selected field from the Available Fields list to the Value Axis list.  Tip

Note:  You must transfer at least one field from the Available Fields list to the Value list before navigating to the next page.


Chart Wizard:  File Name page

  About the Wizard

To save your chart to the default name:

  Click Finish.  The chart is saved to the automatically-generated default name that appears in the File name field  The completed chart appears on the layout.

To save your chart to a file name other than the default:

1	Click Save As.

2	In the Save As dialog box, navigate to the directory where you want to save the chart, and type the new file name.  Click Save.

3	Click Finish.  The chart appears on the layout.

What’s Next?

When you click Finish, Forms Builder displays your finished chart in the layout.  To reenter the wizard, you can select the completed chart object and choose Tools [image] Chart Wizard from the menu.


Tip
Click [image] to transfer a selected field from the Category Axis list back to the Available Fields list.


Tip
Click [image] to transfer a selected field from the Value Axis list back to the Available Fields list.


FRM-50001
FRM-50001:  Acceptable characters are a-z, A-Z, and space.

Cause:	You entered an unacceptable character into the item.

Action:	Enter a character from a-z, A-Z, or a space.

Level:	15

Type:	Error


FRM-50002
FRM-50002:  Month must be between 1 and 12.

Cause:	You entered an invalid month value in a date field.

Action:	Enter a month value from 1 (for January) to 12 (for December).

Level:	15

Type:	Error


FRM-50003
FRM-50003:  Year must be 00-99 or 1000-4712.

Cause:	You entered an invalid year.

Action:	Enter a valid year.  The year may be a number between 0 and 99 (representing the years 1900 to 1999) or between 1000 and 4712.

Level:	15

Type:	Error


FRM-50004
FRM-50004:  Day must be between 1 and last of month.

Cause:	You entered an invalid day.

Action:	Enter a valid day.  For April, for example, enter a number between 1 and 30.

Level:	15

Type:	Error


FRM-50006
FRM-50006:  Legal characters are 0-9 + and -.

Cause:	You entered an unacceptable character in a number item.

Action:	Enter a valid number.  A valid number has digits 0 through 9.  A number may be preceded by a plus (+) or minus (-) sign.   If the message allows it, a number may contain one  decimal point at any location, except before the sign.

Level:	15

Type:	Error


FRM-50007
FRM-50007:  Too many digits after decimal point.

Cause:	You entered a number with 3 or more decimal digits after the decimal point in an item with the MONEY or RMONEY data type.

Action:	Re-enter a valid number.

Level:	15

Type:	Error


FRM-50009
FRM-50009:  Too many decimal points.

Cause:	You entered a number that contains two or more decimal points, or you have entered a number that contains a decimal point in an item that requires a whole (non-decimal) number.

Action:	Enter a number with no more than one decimal point.  If you have used only one decimal, remove the decimal and the decimal part of the number.

Level:	15

Type:	Error


FRM-50010
FRM-50010:  Money format is [+-]9999999.99

Cause:	You entered an invalid value in a MONEY or RMONEY item.

Action:	Enter a valid value.  This value should have zero or dollar digits, followed by a decimal and two cents digits.  The entire number can be preceded by a plus (+) or a minus (-) sign.

Level:	15

Type:	Error


FRM-50011
FRM-50011:  Not a valid month name.

Cause:	You entered an invalid month name in a date field.

Action:	Enter a valid month name.  Form Builder recognizes the first three characters of a month name.  For example, JAN stands for January, JUN for June.

Level:	15

Type:	Error


FRM-50012
FRM-50012:  Date must be entered in a format like %s.

Cause:	You entered an invalid or incorrectly formatted date.

Action:	Re-enter the date in the requested format.

Level:	15

Type:	Error


FRM-50013
FRM-50013:  Plus or minus must be in first position.

Cause:	You entered the plus or minus sign in the wrong position.

Action:	Retype with the plus or minus sign in the first position.

Level:	15

Type:	Error


FRM-50014
FRM-50014:  Bad exponent.

Cause:	You entered an exponent in an item that does not accept exponents.

Action:	Enter a value without an exponent.

Level:	15

Type:	Error


FRM-50016
FRM-50016:  Legal characters are 0-9 - + E .

Cause:	You entered an unacceptable character in a number item.

Action:	Enter a valid number.  A valid number has digits 0 through 9.  A number may be preceded by a plus (+) or minus (-) sign.  If the message allows it, a number may contain one decimal point at any location, except before the sign.  You can use an E to specify scientific notation.

Level:	15

Type:	Error


FRM-50017
FRM-50017:  Hour must be between 0 and 23.

Cause:	You entered an invalid hour.

Action:	Enter a valid hour.  Form Builder records time on a 24-hour basis.

Level:	15

Type:	Error


FRM-50018
FRM-50018:  Minutes must be between 00 and 59.

Cause:	You entered an invalid minute value.

Action:	Enter a valid minute value.

Level:	15

Type:	Error


FRM-50019
FRM-50019:  Seconds must be between 00 and 59.

Cause:	You entered an invalid value.

Action:	Enter a value between 00 and 59.

Level:	15

Type:	Error


FRM-50020
FRM-50020:  Missing exponent.

Cause:	You failed to enter an exponent.

Action:	Enter an exponent.

Level:	15

Type:	Error


FRM-50021
FRM-50021:  Date must be entered in a format like %s.

Cause:	You entered an invalid or incorrectly formatted date.

Action:	Re-enter the date in the requested format.

Level:	15

Type:	Error


FRM-50022
FRM-50022:  Time must be entered in a format like %s.

Cause:	You entered an invalid or incorrectly formatted time.

Action:	Re-enter the time in the requested format.

Level:	15

Type:	Error


FRM-50023
FRM-50023:  Date must be entered in a format like %s.

Cause:	You entered an invalid or incorrectly formatted date.

Action:	Re-enter the date in the requested format.

Level:	15

Type:	Error


FRM-50024
FRM-50024:  Space are allowed in leading positions only.

Cause:	You entered spaces intermixed with data.

Action:	Re-enter data with no spaces intermixed.

Level:	15

Type:	Error


FRM-50025
FRM-50025:  Date/time must be entered in a format like %s.

Cause:	You entered an invalid or incorrectly formatted date and time.

Action:	Re-enter the date and time in the requested format.

Level:	15

Type:	Error


FRM-50026
FRM-50026:  Date must be entered in a format like %s.

Cause:	You entered an invalid or incorrectly formatted date.

Action:	Re-enter the date in the requested format.

Level:	15

Type:	Error


FRM-50027
FRM-50027:  Invalid format mask for given datatype.

Cause:	The format mask you assigned to a text item is incompatible with the data type of the text item.

Action:	Assign a new format mask to the text item. For more information, refer to help on  item format masks .

Level:	15

Type:	Error


FRM-50028
FRM-50028:  Format mask not allowed for this datatype.

Cause:	The data types LONG, IMAGE, and GRAPHICS do not support a format mask.

Action:	Do not try to create a format mask for data types LONG, IMAGE, or GRAPHICS.

Level:	15

Type:	Error


FRM-50029
FRM-50029:  Too many digits preceding decimal point for scientific notation.

Cause:	You specified a number using scientific notation, but used more than one digit preceding the decimal point.

Action:	Re-enter the number using scientific notation.

Level:	15

Type:	Error


FRM-50045
FRM-50045:  Seconds past midnight confilicts with hour.

Cause:	You entered a time where the seconds past midnight component does not agree with the hour component.

Action:	Make sure the hour and seconds past midnight agree, or use a format mask without seconds past midnight.

Level:	15

Type:	Error


FRM-90925
FRM-90925:  Too many arguments on command line.

Cause:	Too many arguments were specified on the command line.

Action:	Retype your commands and try again.


FRM-90926
FRM-90926:  Duplicate parameter on command line.

Cause:	Two identical parameters were typed on the command line.

Action:	Correct the command you typed and try again.


FRM-90927
FRM-90927:  Unknown parameter on command line.

Cause:	You specified an unknown parameter on the command line.

Action:	Check the command line and edit as necessary.


FRM-90928
FRM-90928:  Positional parameter after key on command line.

Cause:	The parameters are not in the proper order on the command line, there is a missing parameter, or a missing '=' sign .

Action:	Correct the command line as necessary and try again.


FRM-90929
FRM-90929:  Invalid value for parameter on command line.

Cause:	You specified an invalid parameter value on the command line.

Action:	Check the command line and edit as necessary.


FRM-90930
FRM-90930:  Invalid file parameter on command line.

Cause:	You specified an invalid file parameter on the command line.

Action:	Check the command line and edit as necessary.


FRM-90931
FRM-90931:  Error processing command line.

Cause:	Internal error.

Action:	Contact your Oracle support representative.


FRM-90932
FRM-90932:  Invalid list value on command line.

Cause:	List value specified is invalid.

Action:	Specify the correct value and try again.


FRM-90933
FRM-90933:  Illegal list value on command line.

Cause:	Illegal list value specified on the command line.

Action:	Check the command line and try again.


FRM-91010
FRM-91010:  Module_Access parameter must be FILE or DATABASE.

Cause:	The parameter specified for Module_Access was not FILE or DATABASE.

Action:	Specify FILE or DATABASE for the Module_Access parameter.


FRM-91017
FRM-91017:  Module_Type parameter must be FORM, MENU or LIBRARY.

Cause:	The parameter specified for Module_Type was not FORM, MENU or LIBRARY.

Action:	Specify FORM, MENU or LIBRARY for the Module_Type parameter.


FRM-91100
FRM-91100:  Internal Error: unable to create Common context.

Cause:	Internal error.

Action:	Contact your Oracle support representative.


FRM-91101
FRM-91101:  Internal Error: unable to create Foundation context.

Cause:	Internal error.

Action:	Contact your Oracle support representative.


FRM-91102
FRM-91102:  Internal Error: unable to tokenize command line.

Cause:	Internal error.

Action:	Contact your Oracle support representative.


FRM-91103
FRM-91103:  Internal Error: out of memory.

Cause:	Internal error.

Action:	Contact your DBA or an Oracle support representative.


FRM-91104
FRM-91104:  Internal Error: unknown error.

Cause:	Internal error.

Action:	Contact your Oracle support representative.


FRM-91108
FRM-91108:  Internal Error: unable to initialize PL/SQL.

Cause:	Internal error.

Action:	Contact your Oracle support representative.


FRM-91109
FRM-91109:  Internal Error: application startup failure.

Cause:	Unable to start window system.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91110
FRM-91110:  Internal Error: cannot find file name: %s.

Cause:	Unable to find resource files.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91111
FRM-91111:  Internal Error: window system startup failure.

Cause:	You are in character mode and trying to run Form Builder on a window system.

Action:	Run the correct executable.

Level:	15

Type:	Error


FRM-91112
FRM-91112:  Internal Error: resource manager startup failure.

Cause:	Unable to find resource files.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91113
FRM-91113:  Internal Error: cannot get default resource file name.

Cause:	Unable to find resource files.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91115
FRM-91115:  Internal Error: bind table failure.

Cause:	Unable to find key mappings.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91116
FRM-91116:  Internal Error: Oracle*Image startup failure.

Cause:	Unable to find resource files.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91117
FRM-91117:  Internal Error: font metric initialization failure.

Cause:	Unable to find resource files.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91118
FRM-91118:  Internal Error: root window initialization failure.

Cause:	Unable to find root window.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91119
FRM-91119:  Internal Error: Oracle*VGS startup failure.

Cause:	Unable to start VGS context.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91120
FRM-91120:  Internal Error: Unable to load NLS character set.

Cause:	Unable to load the specified NLS character set.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91121
FRM-91121:  Internal Error: Unable to start up cue card viewer.

Cause:	Unable to start the Cue Card Viewer.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91122
FRM-91122:  Internal Error: Unable to create string context.

Cause:	Unable to start the String Context.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91123
FRM-91123:  Internal Error: Unable to start up quark manager.

Cause:	Unable to start the Quark Manager.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91124
FRM-91124:  Warning: %s specified for ORAFORMS_DECIMAL_PREFIX. Should be 0 (zero) or ' ' (the empty string).

Cause:	An invalid value was specified for the environment variable ORAFORMS_DECIMAL_PREFIX.

Action:	Do one of the following:

1.  Specify ORAFORMS_DECIMAL_PREFIX as 0 to force a zero before a leading decimal point in any number displayed without a format mask in the application.

2.  Specify ORAFORMS_DECIMAL_PREFIX as ' ' (the empty string).

3.  Do not specify a variable value.


FRM-91125
FRM-91125:  Internal Error: Unable to start up browser layer.

Cause:	Unable to start the browser layer.

Action:	Contact an Oracle support representative.

Level:	15

Type:	Error


FRM-91500
FRM-91500:  Unable to start/complete the build.

Cause:	Unable to find resource files.

Action:	Contact your Oracle support representative.


FRM-10000
FRM-10000:  Validation error on item.

Cause:	You tried to apply an invalid item definition.

Action:	Change the item's property settings to make the item definition valid.


FRM-10001
FRM-10001:  Internal Error: TOS.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10002
FRM-10002:  Unable to save the current module.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10003
FRM-10003:  Unable to retrieve the module from the file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10004
FRM-10004:  Unique and valid value must be entered.

Cause:	You entered an invalid value.

Action:	Change the value to a valid value.


FRM-10005
FRM-10005:  Value is required.

Cause:	You attempted to exit the field without first entering a value.

Action:	Enter a value.


FRM-10006
FRM-10006:  Internal error.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10007
FRM-10007:  Unable to access the table.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10008
FRM-10008:  Unable to create the table.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10009
FRM-10009:  Unable to find the object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10010
FRM-10010:  Internal error: unable to insert an object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10011
FRM-10011:  Internal error: unable to delete an object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10012
FRM-10012:  Internal error: no memory.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10013
FRM-10013:  Duplicate object is found.

Cause:	Internal system error occurred when trying to save a module to the database.

Action:	Contact your DBA or an Oracle support representative.


FRM-10014
FRM-10014:  Module by this name already exists.

Cause:	Internal system error occurred when trying to save a module to the database.

Action:	Contact your DBA or an Oracle support representative.


FRM-10015
FRM-10015:  Duplicate reference information is found.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10016
FRM-10016:  Internal error: unable to close the object store.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10017
FRM-10017:  Internal error: unable to rollback.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10018
FRM-10018:  Internal error: unable to commit the changes.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10019
FRM-10019:  Internal error: unable to open the object store.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10020
FRM-10020:  Module exists.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10021
FRM-10021:  Unable to find the module.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10022
FRM-10022:  Internal error: unable to reference an object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10023
FRM-10023:  Internal error: unable to retrieve objects from the object store.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10024
FRM-10024:  Unable to save the column mapping object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10025
FRM-10025:  Unable to retrieve the column mapping object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10026
FRM-10026:  Unable to save the column specification object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10027
FRM-10027:  Unable to retrieve the column specification object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10028
FRM-10028:  Unable to save the named list object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10029
FRM-10029:  Unable to retrieve the named list object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10030
FRM-10030:  Unable to save the radio button object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10031
FRM-10031:  Unable to retrieve the radio button object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10032
FRM-10032:  Unable to save the VGS object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10033
FRM-10033:  Unable to retrieve the VGS object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10034
FRM-10034:  Valid module name must be entered.

Cause:	Internal system error occurred when trying to open a module from the database.

Action:	Contact your DBA or an Oracle support representative.


FRM-10035
FRM-10035:  Module does not exist.

Cause:	The module name you specified does not exist.

Action:	Check the module name or try another name.


FRM-10036
FRM-10036:  Unable to save the relations.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10037
FRM-10037:  Unable to retrieve the relations.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10038
FRM-10038:  Cannot delete. Object is locked.

Cause:	You tried to delete an object -- such as an item or a canvas -- that is locked by an active Layout Editor. An object is locked when it has been modified in the Layout Editor.

Action:	Release the lock on the object.


FRM-10039
FRM-10039:  Unable to start up the Form Builder.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10040
FRM-10040:  Cannot revert a new module.

Cause:	You chose File->Revert for a module that has not been saved. Since the module has not been saved, there is no version to revert to.

Action:	Close the module without saving, then open a new module.


FRM-10041
FRM-10041:  Operation not valid without database connection.

Cause:	You tried to perform a design operation that requires the Form Builder to be connected to the database.

Action:	Logon and connect to the database.


FRM-10042
FRM-10042:  Not a Form Builder file.

Cause:	You tried to open a file that is not a valid Form Builder design module.

Action:	Open a form (.FMB), menu (.MMB), or library (.PLL) module.


FRM-10043
FRM-10043:  Cannot open file.

Cause:	You tried to open a file that is not a valid Form Builder design module file.

Action:	Open a form (.FMB), menu (.MMB), or library (.PLL) module.


FRM-10044
FRM-10044:  Cannot create file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10045
FRM-10045:  Cannot connect to database.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10046
FRM-10046:  Unable to delete VGS object.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10047
FRM-10047:  Import only allowed to a multi-line text item.

Cause:	You tried to import text to a single line text field or another control type. (Text can be imported only to a multi-line text item.)

Action:	None.


FRM-10048
FRM-10048:  Export is only allowed from a multi-line text item.

Cause:	You tried to export text from a single-line text field or another control type. (Text can only be exported from a multi-line text field.)

Action:	None.


FRM-10049
FRM-10049:  Operation is only allowed from a multi-line text item.

Cause:	You tried to invoke the default operation that can only be invoked from a multi-line text field.

Action:	None.


FRM-10050
FRM-10050:  Valid value must be entered.

Cause:	You specified an invalid value or left a required field blank.

Action:	Specify a valid value.


FRM-10051
FRM-10051:  Error occurred while importing text.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10052
FRM-10052:  Error occurred while exporting text.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10053
FRM-10053:  No printer available.

Cause:	The printer you specified is busy or not connected.

Action:	Check the printer connections, or try again later.


FRM-10054
FRM-10054:  Cannot attach PL/SQL library %s.

Cause:	The library you specified is locked by other users, or the library name is invalid.

Action:	Check the library name and try again later.


FRM-10056
FRM-10056:  Incorrect module type stored in the file.

Cause:	The file is not the correct module type for the operation you are trying to perform.

Action:	None.


FRM-10057
FRM-10057:  Cannot perform this operation on a module you do not own.

Cause:	You tried to perform an operation -- such as revoking access privileges -- on a module in the database of which you are not the owner.

Action:	None.


FRM-10058
FRM-10058:  Object to be copied/referenced was not found.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10059
FRM-10059:  Changes were not saved to the PL/SQL library before building.

Cause:	You tried to compile the library before saving your changes.

Action:	Save your changes, then compile the library.


FRM-10060
FRM-10060:  Database connection required for retrieving referenced objects.

Cause:	You tried to reference an object when Form Builder was not connected to the database. Only objects in modules that are stored in the database can be referenced.

Action:	Logon and connect to the database.


FRM-10061
FRM-10061:  Cannot script/parse PL/SQL library file

Cause:	You attempted to parse or script a library file.

Action:	Do not attempt to parse or script a library file.


FRM-10062
FRM-10062:  Modal window must be dismissed before exiting.

Cause:	The system did not get your response to a modal window.

Action:	Reply to the modal window before you quit.


FRM-10063
FRM-10063:  Cannot find help file, or help file is damaged.

Cause:	Form Builder cannot locate or load the help file.

Action:	Check your environment and check the path to the help file. If necessary, contact your DBA.


FRM-10064
FRM-10064:  Unable to load the object from the resource file.

Cause:	There is a bad resource file, a memory problem, or some other resource problem.

Action:	Check your development environment.


FRM-10065
FRM-10065:  Failed to initialize development environment (DE).

Cause:	The development environment did not initialize, possibly because the system could not find resources.

Action:	Check your development environment.


FRM-10066
FRM-10066:  Failed to create a module.

Cause:	The system could not find the necessary resources.

Action:	Check your development environment.


FRM-10067
FRM-10067:  Unable to lock module.

Cause:	The module currently is opened by other users.

Action:	Wait until the module is free, or have the user of the module quit.


FRM-10068
FRM-10068:  Unable to unlock the module.

Cause:	The module is locked by another user

Action:	The other user must unlock the module.


FRM-10069
FRM-10069:  Cannot detach the current working PL/SQL library module.

Cause:	You tried to detach a working library.

Action:	Do not detach a working library.


FRM-10070
FRM-10070:  Unable to load the attached library information of the current PL/SQL library.

Cause:	You tried to load a Forms 4.0 library module, but Forms was unable to load the module.

Action:	Make sure the library can be loaded using Forms 4.0. If so, contact your DBA or an Oracle support representative.


FRM-10071
FRM-10071:  Internal error: cannot open resource file %s.

Cause:	Resource file cannot be found.

Action:	Reinstall Form Builder or call an Oracle support representative.


FRM-10072
FRM-10072:  Internal error: cannot open menu definition %s

Cause:	Resource definitions for menu cannot be found.

Action:	Reinstall Form Builder or call an Oracle support representative.


FRM-10074
FRM-10074:  Unable to build a PL/SQL library script file.

Cause:	Error in reading a library file.

Action:	Fix the errors detected during the scripting process.


FRM-10075
FRM-10075:  Unable to build a PL/SQL library from a script file.

Cause:	Unable to convert an ASCII library file to library format.

Action:	Fix the errors detected during the conversion process.


FRM-10076
FRM-10076:  Value as entered will be truncated to fit in space allocated.

Cause:	You entered a string that is too long to fit into the field.

Action:	Reduce the length of the string.


FRM-10077
FRM-10077:  Unable to extract translatable strings into NX file.

Cause:	An internal error occurred while translating strings from NX file.

Action:	Contact an Oracle support representative.


FRM-10078
FRM-10078:  Unable to merge translated strings from NX file.

Cause:	An internal error occurred while translating strings from NX file.

Action:	Contact an Oracle support representative.


FRM-10080
FRM-10080:  Source control services are not installed on this machine.

Cause:	The source control component of Form Builder is not installed on your machine

Action:	Contact your DBA or an Oracle support representative.


FRM-10081
FRM-10081:  Cannot retrieve %s in '%s' module.

Cause:	Internal error that appears during the loading process.

Action:	Contact an Oracle support representative.


FRM-10082
FRM-10082:  Cannot save %s.

Cause:	Internal error that appears during the loading process.

Action:	Contact an Oracle support representative.


FRM-10083
FRM-10083:  Cannot find/open '%s' module for referenced objects.

Cause:	The file containing the form module cannot be found, or the user ID for logging on to the database is incorrect.

Action:	Make sure the file containing the form module is in your local directory, or under the search path FORMS50_PATH.  Also, make sure you are logging on to the database with the correct user ID.


FRM-10084
FRM-10084:  Module appears to be an older version of Form Builder file.

Cause:	The module you are referencing is not in the latest Form Builder format.

Action:	Load the reference file and save it in the latest Form Builder format.


FRM-10085
FRM-10085:  Cannot read in module information.

Cause:	The file you tried to open is not an Form Builder file, or the file is corrupted.

Action:	Contact an Oracle support representative.


FRM-10086
FRM-10086:  The file is already open.

Cause:	You are trying to open a file that is already open.

Action:	None.


FRM-10087
FRM-10087:  Libraries cannot be compiled.

Cause:	You cannot compile libraries.

Action:	None.


FRM-10088
FRM-10088:  Libraries cannot be run.

Cause:	You cannot run libraries.

Action:	None.


FRM-10089
FRM-10089:  Menus cannot be run from the Form Builder.

Cause:	You clicked the Run button with a menu module selected.

Action:	Select a form module before clicking the Run button.


FRM-10090
FRM-10090:  Cannot save module to database.

Cause:	Internal error.

Action:	Contact an Oracle support representative.


FRM-10091
FRM-10091:  Unable to create a script/parse file.

Cause:	Internal error. Errors occurred during the conversion process.

Action:	Contact an Oracle support representative.


FRM-10092
FRM-10092:  Unable to convert an old module to current format:

Cause:	Internal error occurs when converting Oracle Forms 4.0 structures to Forms 4.5 structures.

Action:	Contact an Oracle support representative.


FRM-10093
FRM-10093:  No PL/SQL source code.

Cause:	You created a trigger that does not contain PL/SQL source code.

Action:	Add PL/SQL source code to your trigger, or delete the trigger.


FRM-10094
FRM-10094:  Could not compile the Formula.

Cause:	Forms was unable to compile the PL/SQL expression specified in the Formula property.

Action:	Check the PL/SQL expression for syntax errors and recompile.


FRM-10095
FRM-10095:  Assertion failed in %s, at %s:%d.

Cause:	An internal inconsistency was detected.

Action:	Contact an Oracle support representative, and proceed with caution.


FRM-10096
FRM-10096:  Cannot load Cue Card file.

Cause:	Form Builder could not load the Cue Card file. It is missing or corrupt.

Action:	Reinstall Form Builder or contact an Oracle support representative.


FRM-10097
FRM-10097:  Cannot load Quick Tour file.

Cause:	Forms could not load the Quick Tour file. It is missing or corrupt.

Action:	Reinstall Form Builder or contact an Oracle support representative.


FRM-10098
FRM-10098:  Cannot place entire module in Object Library.

Cause:	You tried to place an entire Form Builder module into an Object Library.

Action:	You can place only individual objects into an Object Library.


FRM-10099
FRM-10099:  Cannot SmartClass object. An object with this name exists already.

Cause:	You tried to SmartClass an object which would have conflicted with another object of the same name.

Action:	Rename the existing object.


FRM-10100
FRM-10100:  File name must be entered.

Cause:	You tried to perform an operation that requires a valid file name to be specified.

Action:	Specify a valid file name.


FRM-10101
FRM-10101:  Cannot build module.

Cause:	The module was not created due to generated errors.

Action:	Contact your DBA or an Oracle support representative.


FRM-10102
FRM-10102:  Cannot attach PL/SQL library %s. This library attachment will be lost if the module is saved.

Cause:	The library you specified is locked by other users, or the library name is invalid.

Action:	Check the library name and try again later.


FRM-10150
FRM-10150:  Error occurred while trying to save the preferences.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10250
FRM-10250:  Module type must be specified for a delete operation.

Cause:	You did not name the module properly.

Action:	Check the module name and enter it correctly.


FRM-10275
FRM-10275:  Destination module already exists.

Cause:	You tried to rename a module in the database to a name that duplicates an existing module.

Action:	Specify a unique name for the module.


FRM-10325
FRM-10325:  Invalid module type.

Cause:	Incorrect file extension specified.

Action:	Use the correct extension (.FMX, .MMX or .LIB).


FRM-10326
FRM-10326:  Cannot revoke access privileges of module owner.

Cause:	You tried to revoke the design privileges of the owner of the module. The user identified as the owner of a module always has access to the module.

Action:	None.


FRM-10327
FRM-10327:  Only module owner can modify module access.

Cause:	You attempted to grant or revoke access to a module of which you are not the owner.

Action:	No action required. To modify access to the module, contact your DBA or the owner of the module.


FRM-10328
FRM-10328:  Unable to modify access to this module.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10329
FRM-10329:  User name must be entered.

Cause:	Form Builder expects the name of a valid user.

Action:	Enter the name of a valid user.


FRM-10350
FRM-10350:  User does not have privileges to perform this operation.

Cause:	You tried to perform an operation for which you do not have access privileges.

Action:	If you wish to execute the operation, contact your DBA for access privileges.


FRM-10400
FRM-10400:  Unable to open Report Builder.

Cause:	Form Builder was unable to launch Report Builder.

Action:	Start Report Builder as a separate process.


FRM-10401
FRM-10401:  Valid data block name required.

Cause:	You did not enter a data block name in the dialog.

Action:	Enter a data block name before accepting or canceling the dialog.


FRM-10600
FRM-10600:  Mismatch between source module/object type and target module type.

Cause:	The object you tried to copy or reference is not valid for the active module. For example, you cannot copy a block to a menu module.

Action:	Make sure the object you tried to copy or reference is valid for the active target module.


FRM-10601
FRM-10601:  Invalid parent for the target object.

Cause:	Parent object name does not exist.

Action:	Check the parent object name and try again.


FRM-10602
FRM-10602:  Target by that name already exists.

Cause:	The name you specified for the target object duplicates the name of another object of that same class.

Action:	Change the target name to a name that is unique within the scope of that object.


FRM-10603
FRM-10603:  Copy/reference to and from a PL/SQL library is not supported.

Cause:	You tried to copy or reference a PL/SQL program unit -- such as a user-named procedure or function -- from a library module.

Action:	None.


FRM-10604
FRM-10604:  Cannot copy/reference the ROOT_WINDOW.

Cause:	You attempted an editing operation upon a root window.

Action:	None.


FRM-10605
FRM-10605:  Valid module name required.

Cause:	You did not enter a module name in the dialog.

Action:	Enter a module name before accepting or canceling the dialog.


FRM-10606
FRM-10606:  Valid data block name required.

Cause:	You did not enter a data block name in the dialog.

Action:	Enter a data block name before accepting or canceling the dialog.


FRM-10607
FRM-10607:  Valid item name required.

Cause:	You did not enter a valid item name in the dialog.

Action:	Enter an item name before accepting or canceling the dialog.


FRM-10608
FRM-10608:  Object type is invalid (internal error).

Cause:	An internal Oracle error occurred.

Action:	Contact your DBA.


FRM-10609
FRM-10609:  Valid menu name required.

Cause:	You did not enter a valid menu name in the dialog.

Action:	Enter a menu name before accepting or canceling the dialog.


FRM-10625
FRM-10625:  Input focus must be in text item.

Cause:	You attempted an operation without the required input focus.

Action:	Use keyboard of mouse navigation to place input focus in the the text item.


FRM-10650
FRM-10650:  Input focus must be in text item.

Cause:	You attempted an operation without the required input focus.

Action:	Use keyboard of mouse navigation to place input focus in the the text item.


FRM-10700
FRM-10700:  Replacement object does not exist in destination module.

Cause:	The name you specified in the Copy Object Options dialog cannot be found in the destination module for the appropriate object type.

Action:	Click a Select button in the dialog to view a list of appropriate object types in the destination module.


FRM-10725
FRM-10725:  Failed to load the wizard from the resource file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10750
FRM-10750:  Table name required.

Cause:	You must enter a table name before leaving this page of the wizard.

Action:	Enter a table name, or click Browse to find a table in the database.


FRM-10751
FRM-10751:  At least one database column must be selected.

Cause:	At least one column must appear in the Database Items list of the field picker in order to leave this page of the wizard.

Action:	Move one or more columns from the Available Columns list to the Database Items list of the field picker.


FRM-10752
FRM-10752:  Wizard can modify only one data block at a time.

Cause:	You have invoked the Data Block Wizard when two or more data blocks are selected in the Object Navigator.  The wizard may only modify one data block at a time.

Action:	Ensure that only one data block is selected in the Object Navigator before invoking the Data Block Wizard.


FRM-10753
FRM-10753:  Invalid join condition to master data block %s.

Cause:	While loading a data block in order to modify it, the Data Block Wizard has found an invalid join condition to the given master data block.

Action:	Locate the relevant relation object of the given master data block and correct the join condition before invoking the Data Block Wizard again.


FRM-10754
FRM-10754:  More than one join to master data block %s.

Cause:	While loading a data block in order to modify it, the Data Block Wizard has found that the data block is joined more than once to the given master data block. This is an internal error that should not normally be encountered.

Action:	Do one of the following:

1. Make sure that only one relation object links the master data block to the detail data block.

2. Contact your DBA or an Oracle support representative.


FRM-10755
FRM-10755:  No join condition to master data block %s.

Cause:	A join condition to the given master data block must exist before you can leave this page of the wizard.

Action:	Use the Detail Item and Master Item poplists to setup a join condition to the given master data block.


FRM-10756
FRM-10756:  Error retrieving constraints for table %s.

Cause:	An internal error occured as the Data Block Wizard attempted to retreive constraints for the given table.

Action:	Contact your DBA or an Oracle support representative.


FRM-10757
FRM-10757:  No master data blocks are available.

Cause:	No data blocks are available with which to define a master-detail relationship.

Action:	If the Auto-join data blocks checkbox is:

1. Checked, then the only potential master data blocks are those that are based on tables referenced by a foreign key on the current block's base table.

2. Unchecked, then all data blocks in the form are potential master data blocks, but you must enter the join condition manually.


FRM-10758
FRM-10758:  No item based on join column %s in this detail data block.

Cause:	The Data Block Wizard is attempting to use foreign key constraint information to automatically setup the join condition between the current data block and the selected master data block. However, one of the columns included in the foreign key constraint does not appear as an item in the current data block.

Action:	Return to the Table page of the wizard and ensure that all the columns needed to link the current data block to the required master data block appear in the Database Items list of the field picker.


FRM-10759
FRM-10759:  No item based on join column %s in master data block %s.

Cause:	The Data Block Wizard is attempting to use foreign key constraint information to automatically setup the join condition between the current data block and the selected master data block. However, one of the columns included in the foreign key constraint does not appear as an item in the selected master data block.

Action:	Leave the wizard and ensure that the items needed to link the current data block to the required master block appear as items of the required master data block.


FRM-10760
FRM-10760:  Error encountered while describing stored procedure.

Cause:	Internal Oracle error.

Action:	Contact your DBA or an Oracle support representative.


FRM-10761
FRM-10761:  Wizard can only modify data blocks based on a single table or a set of procedures.

Cause:	While loading a data block in order to modify it, the Data Block Wizard found a combination of data block properties not supported by the wizard.

Action:	Ensure that the data block is either based on one of the following:

1. A single table (with Query Data Source Type and DML Data Target Type properties both set to Table, and identical Query Data Source Name and DML Target Name properties).

2. A set of stored procedures (with Query Data Source Type and DML Data Target Type properties both set to Procedure).


FRM-10762
FRM-10762:  Procedure name required.

Cause:	You must enter a procedure name to leave this page of the wizard.

Action:	Enter a procedure name.


FRM-10763
FRM-10763:  Argument of type TABLE or REFCURSOR must be IN OUT.

Cause:	An argument of type TABLE or REFCURSOR (for a procedure used to query data for the data block) must have a mode of IN OUT.

Action:	Do one of the following:

1. Select an alternative procedure to query data for your data block.

2. Exit the Data Block Wizard, change the argument mode to IN OUT, then re-invoke the wizard.


FRM-10764
FRM-10764:  No argument of type TABLE or REFCURSOR.

Cause:	A procedure used to query data for a data block must have one argument of type TABLE or REFCURSOR.

Action:	Do one of the following:

1. Select an alternative procedure to query data for your data block.

2. Exit the Data Block Wizard, add an argument of type TABLE or REFCURSOR to the procedure, then re-invoke the wizard.


FRM-10765
FRM-10765:  Only one argument of type TABLE or REFCURSOR permitted.

Cause:	A procedure used to query data for a data block can have only one argument of type TABLE or REFCURSOR.

Action:	Do one of the following:

1. Select an alternative procedure to query data for your data block.

2. Exit the Data Block Wizard, ensure that the procedure has only one argument of type TABLE or REFCURSOR, then re-invoke the wizard.


FRM-10766
FRM-10766:  Arguments of type RECORD not permitted.

Cause:	Arguments of type RECORD are not permitted in procedures that query, insert, update, delete or lock data for your data block.

Action:	Do one of the following:

1. Select an alternative procedure to query, insert, update, delete or lock data for your data block.

2. Exit the Data Block Wizard, ensure that the procedure has no arguments of type RECORD, then re-invoke the wizard.


FRM-10767
FRM-10767:  Please select at least one result set column.

Cause:	At least one result set column must appear in the Database Items list of the field picker before you can leave this page of the wizard.

Action:	Move one or more result set columns from the Available Columns list to the Database Items list of the field picker.


FRM-10768
FRM-10768:  Argument of type TABLE must be IN or IN OUT.

Cause:	A TABLE argument of a procedure used to insert, update, delete or lock data for the data block must have a mode of IN or IN OUT.

Action:	Do one of the following:

1. Select an alternative procedure to insert, update, delete or lock data for your data block.

2. Exit the Data Block Wizard, correct the argument mode to IN or IN OUT, then re-invoke the wizard.


FRM-10769
FRM-10769:  No argument of type TABLE.

Cause:	A procedure used to insert, update, delete or lock data for a data block must have one argument of type TABLE.

Action:	Do one of the following:

1. Select an alternative procedure to insert, update, delete or lock data for your data block.

2. Exit the Data Block Wizard, add an argument of type TABLE to the procedure, then re-invoke the wizard.


FRM-10770
FRM-10770:  Only one argument of type TABLE permitted.

Cause:	A procedure used to insert, update, delete or lock data for a data block must only have one argument of type TABLE.

Action:	Do one of the following:

1. Select an alternative procedure to insert, update, delete or lock data for your data block.

2. Exit the Data Block Wizard, ensure that the procedure has only one argument of type TABLE, then re-invoke the wizard.


FRM-10771
FRM-10771:  Arguments of type REFCURSOR not permitted.

Cause:	A procedure used to insert, update, delete or lock data for a data block must not have arguments of type REFCURSOR.

Action:	Do one of the following:

1. Select an alternative procedure to insert, update, delete or lock data for your data block.

2. Exit the Data Block Wizard, ensure that the procedure has no arguments of type REFCURSOR, then re-invoke the wizard.


FRM-10772
FRM-10772:  Use of a function is not permitted.

Cause:	A function has been specified to query, insert, update, delete or lock data for your data block. Only procedures may be used for this purpose.

Action:	Do one of the following:

1. Select a procedure to query, insert, update, delete or lock data for your data block.

2. Exit the Data Block Wizard, convert the function to a procedure, then re-invoke the wizard.


FRM-10773
FRM-10773:  No item based on REF item %s in this detail data block.

Cause:	The Data Block Wizard is attempting to use a REF to automatically set up the relation between the current data block and the selected master data block. However, the selected REF does not appear as an item in the current data block.

Action:	Return to the Table page of the wizard and ensure that the REF column needed to link the current data block to the required master data block appears in the Database Items list of the field picker.


FRM-10800
FRM-10800:  Please select at least one displayed item.

Cause:	At least one item must appear in the Displayed Items list of the field picker before you can leave this page of the wizard.

Action:	Move one or more items from the Available Items list to the Displayed Items list of the field picker.


FRM-10801
FRM-10801:  No data blocks in the current form to lay out.

Cause:	You cannot invoke the Layout Wizard because there are no data blocks to lay out.

Action:	Ensure that at least one data block exists in the form before invoking the Layout Wizard.


FRM-10803
FRM-10803:  One or more items have a negative width or height.

Cause:	One or more of the items in the table has a negative width or height.

Action:	Ensure that no items in the table have a negative width or height.


FRM-10804
FRM-10804:  Distance Between Records must be 0 or higher.

Cause:	You entered a negative value for Distance Between Records.

Action:	Set the Distance Between Records to 0 or a positive value.


FRM-10805
FRM-10805:  Records Displayed must be greater than 0.

Cause:	You entered a value less than 1 for Records Displayed.

Action:	Set the Records Displayed to a value greater than 0.


FRM-10850
FRM-10850:  Frame %s can only display %d records.

Cause:	The given frame cannot display the requested number of records.

Action:	No action is necessary. The frame will display the given maximum number of records. If you wish to display more records in the frame, use the Property Palette to set the Allow Expansion property of the frame to Yes.


FRM-10851
FRM-10851:  Not enough horizontal space in frame %s to start layout.

Cause:	The given frame does not have enough horizontal space to start the layout of its associated data block.

Action:	Increase the width of the frame so that more horizontal space is available.


FRM-10852
FRM-10852:  Not enough vertical space in frame %s to start layout.

Cause:	The given frame does not have enough vertical space to start the layout of its associated data block.

Action:	Do one of the following:

1. Increase the height of the frame so that more vertical space is available.

2. Set the frame's Allow Expansion property to Yes.


FRM-10853
FRM-10853:  Horizontal overflow in frame %s.

Cause:	The layout has horizontally overflowed the boundaries of the frame and the frame is not permitted to expand.

Action:	Increase the width of the frame so that more horizontal space is available, or use the Property Palette to set the Allow Expansion property of the frame to Yes.


FRM-10854
FRM-10854:  Vertical overflow in frame %s.

Cause:	The layout has vertically overflowed the boundaries of the frame and the frame is not permitted to expand.

Action:	Increase the height of the frame so that more vertical space is available, or use the Property Palette to set the Allow Expansion property of the frame to Yes.


FRM-10855
FRM-10855:  Not enough horizontal space in frame %s for object %s.

Cause:	The given object is too wide to fit within the width of the frame.

Action:	Decrease the width of the object, or increase the width of the frame.


FRM-10802
FRM-10802:  Wizard can modify only one LOV at a time.

Cause:	You have invoked the LOV Wizard while multiple LOVs are selected in the Object Navigator. The wizard can modify only one LOV at a time.

Action:	Ensure that only one LOV is selected in the Object Navigator before invoking the LOV Wizard.


FRM-11001
FRM-11001:  Invalid character cell width.

Cause:	The Character Cell Width is set to 0 or a negative number.

Action:	Set the Character Cell Width to a whole number greater than 0.


FRM-11002
FRM-11002:  Invalid character cell height.

Cause:	The Character Cell Height field is set to 0 or a negative number.

Action:	Set the Character Cell Height field to a whole number greater than 0.


FRM-11004
FRM-11004:  Form module with this name already exists.

Cause:	You attempted to rename a module using a name already in use.

Action:	Choose another name with which to rename the module.


FRM-11005
FRM-11005:  Unable to store the current form module.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11006
FRM-11006:  Unable to retrieve the current form.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11007
FRM-11007:  Invalid form name.

Cause:	You have entered an invalid name for the form module.

Action:	Enter a form module name composed only of valid characters: letters, numbers, underscores, and the # symbol (no dashes, periods, or @).


FRM-11008
FRM-11008:  Data block does not exist.

Cause:	Referenced block does not exist.

Action:	Check the block name and try again.


FRM-11009
FRM-11009:  Failed to load in the color palette %s.

Cause:	You probably were working with an editable color palette and starting a new form or opening a form.

Action:	Change to a sharable color mode; restart Form Builder.


FRM-11010
FRM-11010:  Failed to save the color palette %s.

Cause:	You probably were working with an editable color palette and starting a new form or opening a form.

Action:	Change to a sharable color mode; restart Form Builder.


FRM-11100
FRM-11100:  Master data block does not exist.

Cause:	The block you specified in the Master Block field is not defined in the active form module.

Action:	Enter the name of a valid master block. Use the LOV to display a list of all potential master blocks.


FRM-11101
FRM-11101:  Error while parsing join condition.

Cause:	Invalid value in the Join Condition property.

Action:	Enter a valid join condition to define the relationship between the master block specified in the Master Block property and the detail block you are defining.


FRM-11102
FRM-11102:  Error while generating the constraints.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11103
FRM-11103:  Error while creating the default data block.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11104
FRM-11104:  Valid data block and table names must be entered.

Cause:	You entered an invalid block name or table name.

Action:	Enter a a valid block name and a valid table name.


FRM-11105
FRM-11105:  Error occurred while generating a list of master data blocks.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11106
FRM-11106:  No master data blocks available.

Cause:	You tried to invoke a list of potential master blocks for the current detail block you are defining, but no such block exists in the active form. A potential master block is a block whose base table has a foreign key relationship to the base table of the current block.

Action:	None.


FRM-11107
FRM-11107:  Number of records displayed must be between 1 and 100.

Cause:	The number of records to be displayed is between 1 and 100.

Action:	Enter a value between 1 and 100 for the block's Displayed property.


FRM-11108
FRM-11108:  Data block name cannot be SYSTEM, GLOBAL or PARAMETER.

Cause:	The block name specified is a PL/SQL reserved word.

Action:	Specify another name.


FRM-11109
FRM-11109:  Cannot fit the data block on the specified canvas.

Cause:	The canvas you specified in the Canvas property is not large enough to display all of the text items you are trying to create (using the default layout).

Action:	Increase the dimensions of the canvas. (If the specified canvas does not exist, you must first create it.) To change dimensions, either set the Width and Height properties in the Properties window, or re-size the canvas in the Layout Editor.


FRM-11110
FRM-11110:  Retrieved columns do not match specified table.

Cause:	You may have changed table names after a retrieve of columns.

Action:	Retrieve the columns again.


FRM-11111
FRM-11111:  Master data block name must be entered.

Cause:	You may have specified a join condition without a master block.

Action:	Specify a master block.


FRM-11112
FRM-11112:  Enter a base table name before choosing columns.

Cause:	You are trying to select columns before specifying a base table.

Action:	Specify a base table name before choosing columns.


FRM-11200
FRM-11200:  Valid data block name must be entered and be unique within the form.

Cause:	The Block Name property is blank or specifies the name of another block.

Action:	Enter a name for the block that is unique among all blocks in the active form.


FRM-11201
FRM-11201:  Number of Records Displayed is invalid.

Cause:	You entered an invalid value for the Records Displayed property, or you entered a blank.

Action:	Enter a valid value. Records Displayed must be one of the following:

1. A whole number.

2. Greater than 0.

3. Less than or equal to the number of buffered records.


FRM-11203
FRM-11203:  Data block with Records Buffered, Primary Key or Column Security must have a base table.

Cause:	You may not have identified a base table.

Action:	Identify a base table.


FRM-11204
FRM-11204:  Data block with this name already exists.

Cause:	There is already a block in the active form with the name specified by the Block Name property.

Action:	Enter a name for the block that is unique among all blocks in the active form.


FRM-11205
FRM-11205:  Unable to store the current data block.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11206
FRM-11206:  Unable to retrieve the data blocks.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11207
FRM-11207:  Data block does not exist.

Cause:	You may have supplied the wrong name.

Action:	Supply the correct name of a valid block.


FRM-11208
FRM-11208:  Unable to get the copied/referenced data block %s.

Cause:	The specified block does not exist in the database.

Action:	Check the block name and try again.


FRM-11209
FRM-11209:  Sequence number must be > 0 and < 65536.

Cause:	You may have attempted to use a number that is out of range.

Action:	Enter a valid sequence number.


FRM-11210
FRM-11210:  Records fetched must be a whole number > 0 and < 65536, or null.

Cause:	You may have tried to fetch a number of records that are out of range.

Action:	Try to fetch using a valid number.


FRM-11211
FRM-11211:  Number of rows buffered must be a whole number > 0 and < 65536.

Cause:	You entered an invalid value.

Action:	Enter a positive integer.


FRM-11300
FRM-11300:  Valid item name must be entered and be unique within the data block.

Cause:	The Name property is blank or specifies the name of another item.

Action:	Enter a name for the item that is unique among all items in the same block.


FRM-11301
FRM-11301:  Sequence number must be > 0 and < 65536.

Cause:	The Sequence ID field is blank or specifies a number greater than zero and less than 65536.

Action:	In the Sequence ID field, enter a valid number.


FRM-11302
FRM-11302:  Data block name must be entered and exist in the form.

Cause:	The Block Name field is blank or specifies the name of another block.

Action:	Enter a name for the block that is unique among all blocks in the active form.


FRM-11303
FRM-11303:  Canvas name can be null, otherwise it must exist in the form.

Cause:	The Canvas property specifies a non-existent canvas.

Action:	Leave the Canvas property blank (to make the current item a NULL-canvas item) or enter the name of an existing canvas.


FRM-11304
FRM-11304:  Valid X coordinate is required.

Cause:	The X Position property is blank or specifies a negative number.

Action:	Enter a non-negative number in the X Position property to specify the position of the item's upper left corner on the canvas.


FRM-11305
FRM-11305:  Valid Y coordinate is required.

Cause:	The Y Position property is blank or specifies a negative number.

Action:	Enter a non-negative number in the Y Position property to specify the position of the item's upper left corner on the canvas.


FRM-11306
FRM-11306:  Valid width coordinate is required.

Cause:	The View Width property is blank or specifies a negative number.

Action:	Enter a non-negative number in the Width field to specify the width of the item in the current form coordinate units.


FRM-11307
FRM-11307:  Valid height coordinate is required.

Cause:	The View Height property field is blank or specifies a negative number.

Action:	Enter a non-negative number in the Height field to specify the height of item in the current form coordinate units.


FRM-11310
FRM-11310:  Invalid maximum length for the current item/data type.

Cause:	You entered an invalid maximum length for an item.

Action:	If the current item type is:

1. An image item, set the Maximum Length property to 1024 or greater.

2. Not an image item, set the Maximum Length property to 1 or greater.

3. The Maximum Length property for Char items must be less than 32767 (32K).


FRM-11311
FRM-11311:  Item's data block must be based on a database table.

Cause:	You tried to invoke an LOV on the Name property for a control block item.

Action:	No action required.


FRM-11312
FRM-11312:  Item name already exists in the current data block.

Cause:	The name you have specified is already in use.

Action:	Enter a unique item name.


FRM-11313
FRM-11313:  Unable to store the current items.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11314
FRM-11314:  Unable to retrieve the items from the file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11316
FRM-11316:  Editor name can be null, else it must exist in the form.

Cause:	The editor specified in the Editor property is not defined in the active form.

Action:	Do one of the following:

1. If you do not want to assign a custom editor to the item, leave the Editor Name property blank.

2. Enter the name of an existing editor.


FRM-11317
FRM-11317:  LOV name can be null, else it must exist in the form.

Cause:	The List of Values specified in the LOV property is not defined in the active form.

Action:	Do one of the following:

1. If you do not want to attach an LOV to the text item, leave the LOV property blank.

2. Enter the name of an existing LOV.


FRM-11318
FRM-11318:  Multi-line attribute cannot be set for this data type.

Cause:	You tried to set the Multi-line property to True when the Data Type property is set to CHAR, ALPHA, or LONG.  This is not allowed.

Action:	Set the Multi-line property to False or change the Data Type property to CHAR, ALPHA, or LONG.


FRM-11319
FRM-11319:  Query length must be 0 or >= the maximum length and < 65536 (depending upon the data type).

Cause:	The Query Length property setting is invalid.

Action:	Enter a valid length in the Query Length property. If not 0, it must be equal to or greater than the Maximum Length property value.


FRM-11320
FRM-11320:  Valid initial value must be entered.

Cause:	You attempted to enter an invalid global or parameter.

Action:	Enter a valid value.


FRM-11321
FRM-11321:  Valid range value must be entered.

Cause:	The values in the Range Low Value and Range High Value properties are incompatible with the data type of the text item.

Action:	Change the low and high range values to be compatible with the data type or change the Data Type property to be compatible with the range values.


FRM-11322
FRM-11322:  Other value is invalid.

Cause:	The other value specified for a radio group or list item is invalid.

Action:	Other value must be one of the following:

1. Item, parameter, sequence, or global reference.

2. Equal to the value of one of the buttons or lists.

3. Equal to the name of one of the buttons or lists.

4. NULL.


FRM-11323
FRM-11323:  Initial value is invalid.

Cause:	The initial value specified for a radio group, list item, or check box is invalid.

Action:	Initial value must be one of the following:

1. Item, parameter, sequence, or global reference.

2. Equal to the "checked" value (check box only).

3. Equal to the "unchecked" value (check box only).

4. Equal to the "checked" or "unchecked" value - case insensitive (check box only).

5. NULL.


FRM-11324
FRM-11324:  Value is invalid.

Cause:	The value you entered is out of the legal range.

Action:	Enter a legal value.


FRM-11325
FRM-11325:  Invalid horizontal spacing between columns.

Cause:	You entered an invalid value.

Action:	Enter a positive number.


FRM-11326
FRM-11326:  Invalid column display width.

Cause:	You entered an invalid value.

Action:	Enter a positive number.


FRM-11327
FRM-11327:  Unable to get the copied/referenced item %s in data block %s.

Cause:	You specified an item that does not exist in the specified block.

Action:	Check the block and item names, and try again.


FRM-11328
FRM-11328:  Initial Value is invalid; correct format is %s.

Cause:	Value is not compatible with data type.

Action:	Make the value compatible with the data type.


FRM-11329
FRM-11329:  Other Value is invalid; correct format is %s.

Cause:	Value is not compatible with data type.

Action:	Make the value compatible with the data type.


FRM-11330
FRM-11330:  Value is invalid; correct format is %s.

Cause:	Value is not compatible with data type.

Action:	Make the value compatible with the data type.


FRM-11331
FRM-11331:  High range value must be greater than low range value.

Cause:	Low range value is greater than high range value.

Action:	Make sure high range value is greater than low range value.


FRM-11332
FRM-11332:  Value is inconsistent with data type.

Cause:	Value is not compatible with data type.

Action:	Make the value compatible with the data type.


FRM-11400
FRM-11400:  PL/SQL with this name already exists.

Cause:	You may have created two code segments with the same name.

Action:	Rename a code segment.


FRM-11401
FRM-11401:  Unable to store the current PL/SQL.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11402
FRM-11402:  Unable to retrieve the PL/SQL.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11403
FRM-11403:  Unable to initialize the PL/SQL context.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11404
FRM-11404:  Unable to load the procedures.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11405
FRM-11405:  Unable to load the program unit browser from the resource file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11406
FRM-11406:  Unable to show the program unit browser.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11407
FRM-11407:  Unable to load the PL/SQL editor.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11408
FRM-11408:  Unable to get the copied/referenced PL/SQL %s.

Cause:	The specified PL/SQL does not exist in the database.

Action:	Check the PL/SQL name, and try again.


FRM-11409
FRM-11409:  Program unit %s is already shown in another window.

Cause:	You can only view a program unit from one PL/SQL editor window.

Action:	View the program unit from another window.


FRM-11410
FRM-11410:  Menu item %s is already shown in another window.

Cause:	You can only view a menu item from one PL/SQL editor window.

Action:	View the menu item from another window.


FRM-11411
FRM-11411:  Menu %s is already shown in another window.

Cause:	You can only view menu startup code from one PL/SQL Editor window.

Action:	View the menu startup code from another window.


FRM-11412
FRM-11412:  PL/SQL code for %s is too large to be stored.

Cause:	The program unit is too large to store in a single memory allocation.

Action:	Reduce the size of the PL/SQL code by encapsulating the code and making several program units.


FRM-11413
FRM-11413:  PL/SQL code for %s is too large to be decoded.  %s needs to be broken up into smaller program units.

Cause:	The program unit is too large to decode in a single memory allocation.  You may loose the incremental compilation feature.

Action:	Divide the program unit into several smaller program units so that you can decode each program unit in a single memory allocation.


FRM-11500
FRM-11500:  Data block with this name does not exist in the form.

Cause:	You tried to attach a trigger to a block that is not defined in the active form module.

Action:	Enter a valid block name in the Object field.


FRM-11501
FRM-11501:  Item with this name does not exist in the data block.

Cause:	You tried to attach a trigger to an item that is not defined in the block.

Action:	Enter a valid item name in the Object field.


FRM-11502
FRM-11502:  Built-in trigger with this name does not exist.

Cause:	The trigger name specified in the Name field is not a valid built-in trigger.

Action:	Check the syntax of the trigger name and make sure it corresponds to one of the predefined trigger names.  Use the List of Values for this field to display a list of Form Builder triggers.


FRM-11503
FRM-11503:  Trigger that is not a key-trigger cannot be shown with Show-Keys.

Cause:	You set the Show Keys option to True on the Properties window.

Action:	Change the trigger name or delete the descriptor.


FRM-11504
FRM-11504:  Trigger with this name already exists.

Cause:	You tried to define a trigger at the same definition level as an existing trigger of the same type.

Action:	None.


FRM-11505
FRM-11505:  User-named trigger conflicts with built-in name.

Cause:	You tried to create a user-named trigger with the same name as a built-in Form Builder trigger.

Action:	Choose a unique name for the user-named trigger.


FRM-11506
FRM-11506:  Unable to store the current triggers.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11507
FRM-11507:  Unable to retrieve the triggers from the file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11508
FRM-11508:  Built-in trigger invalid at this definition level.

Cause:	You tried to define a trigger at an invalid definition level (form-, block-, or item-). Certain triggers are valid only at specific definition levels.

Action:	Change the Object field to specify a valid definition level. For more information, refer to help on  trigger definition level .


FRM-11509
FRM-11509:  Valid trigger name must be entered.

Cause:	The Trigger Type property is set to User-Named but the Type field is either blank or contains an invalid trigger name.

Action:	In the Type field, enter a valid user-named trigger name.  The name must adhere to Oracle naming conventions and must be unique among triggers in the form, including built-in triggers.


FRM-11510
FRM-11510:  Unable to get the copied/referenced trigger %s in form %s.

Cause:	The specified trigger does not exist in the specified form.

Action:	Check the trigger and form names, and try again.


FRM-11511
FRM-11511:  Unable to get the copied/referenced trigger %s in data block %s.

Cause:	The specified trigger does not exist in the specified block.

Action:	Check the trigger and block names, and try again.


FRM-11512
FRM-11512:  Unable to get the copied/referenced trigger %s in item %s of data block %s.

Cause:	The specified trigger does not exist in the item on the specified block.

Action:	Check the trigger, item, and block names, and try again.


FRM-11513
FRM-11513:  Trigger %s is already shown in another window.

Cause:	You can only view a trigger from one PL/SQL editor window.

Action:	View the trigger from another window.


FRM-11600
FRM-11600:  Unable to store the current V2 triggers.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11601
FRM-11601:  Unable to retrieve the V2 triggers from the file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11602
FRM-11602:  Text for step must be entered.

Cause:	You tried to create a V2-style trigger but left the Trigger Step Text field blank.

Action:	Enter the desired trigger text in the Trigger Step Text field.


FRM-11603
FRM-11603:  Sequence number must be at least 1 and less than 65536.

Cause:	You attempted to enter a negative or non-integer number.

Action:	Enter a non-negative, non-zero, whole number sequence.


FRM-11700
FRM-11700:  Valid alert name must be entered and be unique within the form.

Cause:	The Name field is blank.

Action:	Enter a unique name for the alert.


FRM-11701
FRM-11701:  Alert with this name already exists.

Cause:	There is already an alert with the same name defined in the active form.

Action:	Enter a unique name for the alert.


FRM-11702
FRM-11702:  Unable to store the current alert objects.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11703
FRM-11703:  Unable to retrieve the alert objects from the file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11704
FRM-11704:  At least one button label must be supplied.

Cause:	All of the Button properties (Button 1, Button 2, Button 3) are blank.

Action:	Enter a label for at least one of the buttons.


FRM-11705
FRM-11705:  Default button must have a label.

Cause:	The Label property is blank for the button that is the Default button.

Action:	Enter a label for the default button (Button 1, Button 2, or Button 3).


FRM-11706
FRM-11706:  Unable to get the copied/referenced alert %s.

Cause:	The specified alert does not exist in the database.

Action:	Check the alert name, and try again.


FRM-11800
FRM-11800:  Valid editor name must be entered and be unique within the form.

Cause:	The editor Name property is blank.

Action:	Enter a unique name for the editor.


FRM-11801
FRM-11801:  Editor with this name already exists.

Cause:	There is already an editor with the same name defined in the active form.

Action:	Enter a unique name for the editor.


FRM-11802
FRM-11802:  Unable to store the current editor objects.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11803
FRM-11803:  Unable to retrieve the editor objects from the file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11804
FRM-11804:  Unable to get the copied/referenced editor %s.

Cause:	The specified editor does not exist in the database.

Action:	Check the editor name, and try again.


FRM-11900
FRM-11900:  List Of Values with this name already exists.

Cause:	The name specified for the LOV duplicates the name of an existing LOV defined in the same form.

Action:	Enter a valid name that is unique among LOVs in the active form.


FRM-11901
FRM-11901:  Error occurred while trying to create the LOV.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11902
FRM-11902:  Unable to store the current LOV objects.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11903
FRM-11903:  Unable to retrieve the LOV objects from the file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-11905
FRM-11905:  Item referenced in select statement does not exist.

Cause:	You are trying to select an item that does not exist.

Action:	Check the table and fix the select statement.


FRM-11906
FRM-11906:  Valid LOV name must be entered and be unique within the form.

Cause:	The Name field is blank.

Action:	Enter a valid name that is unique among LOVs in the active form.


FRM-11907
FRM-11907:  Record group must exist within the form.

Cause:	The record group specified in the Record Group Type property does not exist in the active form.

Action:	Enter the name of an existing record group, or create a new record group.


FRM-11908
FRM-11908:  Item name must be valid and exist in the form.

Cause:	The Return Item property contains an invalid value.

Action:	Enter a valid value in the Return Item property.  Valid values include the name of an item in the active form, the name of a global variable, or the name of a form parameter.  Do not preface the object name with a colon or enclose it in quotes.


FRM-11909
FRM-11909:  Valid column display width required.

Cause:	The Display Width property of one or more columns in the LOV is blank or contains an invalid number.

Action:	Change the Display Width value for each LOV column to be either 0 (for a hidden column) or a non-negative number.


FRM-11910
FRM-11910:  Unable to get the copied/referenced LOV %s.

Cause:	The specified LOV does not exist in the database.

Action:	Check the LOV name, and try again.


FRM-12000
FRM-12000:  Record group with this name already exists.

Cause:	The name specified for the record group duplicates the name of an existing record group defined in the same form.

Action:	Enter a valid name that is unique among record groups in the active form.


FRM-12001
FRM-12001:  Cannot create the record group (check your query).

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12002
FRM-12002:  Unable to store the current record group objects.

Cause:	Form Builder cannot understand the Y coordinate you want for your window.

Action:	Supply a positive number.


FRM-12003
FRM-12003:  Unable to retrieve the record group objects.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12005
FRM-12005:  Unable to get the copied/referenced record group %s.

Cause:	The specified record group does not exist in the database.

Action:	Check the record group name, and try again.


FRM-12006
FRM-12006:  Valid record group name must be entered and be unique within the form.

Cause:	Form Builder could not understand your record group name.

Action:	Enter a unique name.


FRM-12100
FRM-12100:  Valid canvas name must be entered and be unique within the form.

Cause:	The Name field is blank.

Action:	Enter a valid name that is unique among canvas objects in the active form.


FRM-12101
FRM-12101:  Window name must be entered and window must exist in the form.

Cause:	The Window property is either left blank or specifies a window that is not defined in the active form.

Action:	Every canvas-view must be assigned to a window.  Enter the name of an existing window in the Window property.


FRM-12102
FRM-12102:  Value entered is not a valid coordinate.

Cause:	You did not enter a valid value for width and height.

Action:	Enter a valid X coordinate for canvas-view width, and a Y coordinate for canvas-view height.


FRM-12103
FRM-12103:  Canvas with this name already exists.

Cause:	The name specified for the canvas duplicates the name of an existing canvas defined in the same form.

Action:	Enter a valid name that is unique among canvas objects in the active form.


FRM-12104
FRM-12104:  Unable to store the current canvas objects.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12105
FRM-12105:  Unable to retrieve the canvas objects from the file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12106
FRM-12106:  Sequence number must be at least 1 and less than 65536.

Cause:	The canvas-view Sequence (Seq) field is invalid.

Action:	Enter a valid sequence number.  Note that although the Sequence property is required for all canvas objects, it takes effect only when you assign more than one canvas to the same window.


FRM-12107
FRM-12107:  Unable to get the copied/referenced canvas %s.

Cause:	The specified canvas-view does not exist in the database.

Action:	Check the canvas-view name, and try again.


FRM-12200
FRM-12200:  Valid window name must be entered, unique within the form, and not ROOT_WINDOW.

Cause:	The Name field is blank.

Action:	Enter a valid window name that is unique among windows defined in the active form.  The name ROOT_WINDOW is not a valid window name.


FRM-12201
FRM-12201:  Valid X coordinate required.

Cause:	Form Builder cannot understand the X coordinate you want for your window.

Action:	Supply a positive number.


FRM-12202
FRM-12202:  Valid Y coordinate is required.

Cause:	Form Builder cannot understand the Y coordinate you want for your window.

Action:	Supply a positive number.


FRM-12203
FRM-12203:  Valid width coordinate is required.

Cause:	Invalid width coordinate entered.

Action:	Enter a positive width coordinate.


FRM-12204
FRM-12204:  Valid height coordinate is required.

Cause:	Invalid height coordinate entered.

Action:	Enter a positive height coordinate.


FRM-12205
FRM-12205:  Content view name can be null, otherwise it must exist in the form.

Cause:	The View property is not defined in the active form.

Action:	Leave the View property blank or enter the name of an existing view.


FRM-12211
FRM-12211:  Window with this name already exists.

Cause:	The name specified for the window duplicates the name of an existing window defined in the same form.

Action:	Enter a valid name that is unique among windows in the active form.


FRM-12212
FRM-12212:  Unable to store the current window objects.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12213
FRM-12213:  Unable to retrieve the window objects.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12214
FRM-12214:  Unable to get the copied/referenced window %s.

Cause:	The specified window does not exist in the database.

Action:	Check the window name, and try again.


FRM-12300
FRM-12300:  Unable to store the current visual attribute objects.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12301
FRM-12301:  Unable to retrieve the visual attributes.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12302
FRM-12302:  Valid visual attribute name must be entered and unique within the module.

Cause:	The Name property is blank.

Action:	Enter a valid visual attribute name that is unique among visual attributes defined in the active module.


FRM-12303
FRM-12303:  Visual attribute by this name does not exist.

Cause:	You tried to assign an undefined visual attribute to an object.

Action:	Enter the name of a visual attribute that is defined in the active module.


FRM-12304
FRM-12304:  Visual attribute by this name already exists.

Cause:	The name specified for the visual attribute duplicates the name of an existing visual attribute defined in the same form.

Action:	Enter a valid name that is unique among visual attributes in the active form.


FRM-12305
FRM-12305:  Color by this name does not exist.

Cause:	The Foreground Color or Background Color property is invalid.

Action:	Enter a valid color name in the Foreground Color or Background Color property, or leave the properties blank.


FRM-12306
FRM-12306:  Pattern by this name does not exist.

Cause:	The Fill Pattern property is invalid.

Action:	Enter a valid pattern name in the Fill Pattern property, or leave the property blank.


FRM-12307
FRM-12307:  Valid font size must be entered (1-100).

Cause:	The Font Size field is invalid.

Action:	Enter a valid font size or leave the field blank.


FRM-12308
FRM-12308:  Unable to get the copied/referenced visual attribute %s.

Cause:	The specified visual attribute does not exist in the database.

Action:	Check the visual attribute name, and try again.


FRM-12400
FRM-12400:  Menu module by this name already exists.

Cause:	You entered a menu module name that already exists.

Action:	Enter a valid name that is unique among menu modules.


FRM-12401
FRM-12401:  Unable to store the menu module.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12402
FRM-12402:  Unable to retrieve the menu module from the file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12403
FRM-12403:  Invalid module name.

Cause:	The name specified for the menu module is invalid.

Action:	Enter a name for the module that follows standard Oracle naming conventions.


FRM-12500
FRM-12500:  Valid menu name must be entered and be unique within the menu.

Cause:	You attempted to exit the menu Name field without entering a name.

Action:	Enter a menu name.


FRM-12501
FRM-12501:  Unable to store the current menus.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12502
FRM-12502:  Unable to retrieve the menus.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12503
FRM-12503:  Invalid menu name.

Cause:	The name specified for the menu is invalid.

Action:	Enter a valid menu name in the Name field.  Menu names are internal handles that are not displayed at runtime.


FRM-12504
FRM-12504:  Unable to get the copied/referenced menu %s.

Cause:	The specified menu does not exist in the database.

Action:	Check the menu name, and try again.


FRM-12600
FRM-12600:  Menu Item with this name already exists.

Cause:	You tried to enter a menu item name that already exists.

Action:	Enter a unique and valid name for the menu item.


FRM-12601
FRM-12601:  Unable to store the current menu items.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12602
FRM-12602:  Unable to retrieve the menu items from the file.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12603
FRM-12603:  Valid radio group name must be entered.

Cause:	One or more menu item in the menu module has the Type property set to Radio but its radio group property is invalid.

Action:	Each radio menu item must be assigned to a radio group.  To assign a radio item to a group, select the item in the appropriate menu column, set the Type selector to Type, then enter the name of the desired radio group property.  The radio group name must adhere to Oracle naming conventions and must be unique.  Radio group names are internal handles that are not displayed at runtime.


FRM-12604
FRM-12604:  Valid accelerator key must be entered.

Cause:	You entered an invalid accelerator key name in the Accelerator property.

Action:	Enter a valid accelerator key name.  Valid accelerator keys are ACCELERATOR-1 through ACCELERATOR-10.


FRM-12605
FRM-12605:  Valid menu name must be entered.

Cause:	You did not give a valid name for your menu.

Action:	Supply a valid name.


FRM-12606
FRM-12606:  Unable to get the copied/referenced menu item %s in menu %s.

Cause:	The specified menu item does not exist in the specified menu.

Action:	Check the menu and menu item names, and try again.


FRM-12607
FRM-12607:  Invalid command type for this magic menu item.

Cause:	The current combination of command type and magic item type is incompatible.

Action:	Select a command type that is compatible with the current magic menu item type.


FRM-12700
FRM-12700:  Parameter with this name already exists.

Cause:	The name specified for the parameter duplicates the name of an existing parameter defined in the same module.

Action:	Enter a valid name that is unique among parameters in the active module.


FRM-12701
FRM-12701:  Unable to store the current menu parameters.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12702
FRM-12702:  Unable to retrieve the menu parameters.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12703
FRM-12703:  A 2 character name must be entered and be unique within the menu.

Cause:	The menu parameter name is invalid.

Action:	Enter a 2-character alphanumeric name for the parameter in the Name field.


FRM-12704
FRM-12704:  Value must be at least 1 and less than 65536.

Cause:	The parameter Length is invalid.

Action:	Enter a valid value in the Length field.


FRM-12705
FRM-12705:  Unable to get the copied/referenced menu parameter %s.

Cause:	The specified menu parameter does not exist in the database.

Action:	Check the menu parameter name, and try again.


FRM-12800
FRM-12800:  Role with this name already exists.

Cause:	The name specified for the role duplicates an existing role in the database.

Action:	Enter a unique role name.


FRM-12801
FRM-12801:  Unable to store the current menu role objects.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12802
FRM-12802:  Unable to retrieve the menu role objects.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12803
FRM-12803:  Valid role name must be entered and be unique within the list.

Cause:	The role Name field is blank.

Action:	Enter a valid role name in the Name field.


FRM-12900
FRM-12900:  Parameter with this name already exists.

Cause:	The name specified for the parameter duplicates that of an existing parameter within the current module.

Action:	Enter a unique and valid name for the parameter.


FRM-12901
FRM-12901:  Unable to store the current form parameters.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12902
FRM-12902:  Unable to retrieve the form parameters.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-12903
FRM-12903:  Valid parameter name is required and be unique within the form.

Cause:	The Name field is blank.

Action:	Enter a valid name for the parameter in the Name field.  Form parameter names must follow Oracle naming conventions.


FRM-12904
FRM-12904:  Numeric value between 1 and 2000 must be entered.

Cause:	The parameter length is invalid.

Action:	Enter a valid length in the Length field.


FRM-12905
FRM-12905:  Initial value must match data type and be of the proper length.

Cause:	The initial value is incompatible with the data type or length of the parameter.

Action:	Change the Initial Value, Data Type, or Maximum Length settings.


FRM-12906
FRM-12906:  Unable to get the copied/referenced form parameter %s.

Cause:	The specified form parameter does not exist in the database.

Action:	Check the form parameter name, and try again.


FRM-13000
FRM-13000:  A fatal error has occurred.

Cause:	An internal error has occurred in the Layout Editor.

Action:	Contact your DBA or an Oracle support representative.


FRM-13001
FRM-13001:  Unable to accept this canvas.

Cause:	An internal error has occurred in the Layout Editor.

Action:	Contact your DBA or an Oracle support representative.


FRM-13002
FRM-13002:  Stacked and Tab canvases must be created within content canvases.

Cause:	An internal error has occurred in the Layout Editor.

Action:	Contact your DBA or an Oracle support representative.


FRM-13003
FRM-13003:  Unimplemented observer event; close and reopen layout editor.

Cause:	An internal error has occurred in the Layout Editor.

Action:	Contact your DBA or an Oracle support representative.


FRM-13504
FRM-13504:  There are no stacked canvases for this canvas.

Cause:	You selected a view of a stacked view when no stacked views were created.

Action:	Define a stacked view before selecting this option.


FRM-13005
FRM-13005:  Dropping objects of this type in the layout editor is not supported.

Cause:	An internal error has occurred in the Layout Editor.

Action:	Contact your DBA or an Oracle support representative.


FRM-13006
FRM-13006:  A non-fatal error has occurred.

Cause:	This is the default message when a more specific message has not been defined.

Action:	Contact an Oracle support representative.


FRM-13007
FRM-13007:  Unable to create an object's view in the layout editor.

Cause:	Forms could not display an object in layout editor.

Action:	You may be low on resources; try closing other windows or restarting Forms.


FRM-15000
FRM-15000:  Duplicate relation name.

Cause:	There already exists a relation with the same name.

Action:	Change the name of the relation.


FRM-15001
FRM-15001:  Relation name must be entered and must be unique within the data block.

Cause:	There already exists a relation with the same name in the selected block.

Action:	Use a unique name for the relation.


FRM-15002
FRM-15002:  Master data block is required and must exist in the form.

Cause:	You tried to enter a master or detail block name that is invalid.

Action:	Type in a valid block name or select a valid block name from the list.


FRM-15003
FRM-15003:  Detail data block is required and must exist in the form.

Cause:	You tried to enter a master or detail block name that is invalid.

Action:	Type in a valid block name or select a valid block name from the list.


FRM-15004
FRM-15004:  Error while parsing join condition.

Cause:	The join condition is incorrect.

Action:	Enter a valid join condition in the multi-line field provided.  The join condition defines the relationship between the master block specified in the Master field and the detail block specified in the Detail field.


FRM-15005
FRM-15005:  Join condition cannot be null.

Cause:	The join condition is undefined.

Action:	Enter a valid join condition in the multi-line field provided.  The join condition defines the relationship between the master block specified in the Master field and the detail block specified in the Detail field.


FRM-15006
FRM-15006:  Master and detail data blocks cannot be the same.

Cause:	The master block and detail block are the same.

Action:	Specify a different master or detail block.


FRM-15007
FRM-15007:  Master-Detail relationship already exists for given data blocks.

Cause:	You attempted to create a relation between two blocks that already have a master-detail relationship.

Action:	Verify the name of the detail block and retry.


FRM-15008
FRM-15008:  Triggers describing master-detail relationships have been modified.

Cause:	The triggers describing master-detail relationships between the two data blocks have been manually modified in a way that prevents the code being automatically updated.

Action:	Delete and recreate the relation object.


FRM-15009
FRM-15009:  Master data block must not be referenced.

Cause:	You cannot add new relations to a reference block.

Action:	Do not attempt to add a new relation to a reference block.


FRM-15100
FRM-15100:  All objects selected must be of the same type.

Cause:	You attempted to perform an operation requiring that all objects selected in the Object Navigator be of the same type.

Action:	Perform the operation separately for each group of objects that are the the same type.


FRM-15101
FRM-15101:  Cannot copy %s because its parent is subclassed.

Cause:	You attempted to perform an operation on an object that is owned by a referenced object.

Action:	You can only perform the operation on the object's parent or on the object that is the source of the reference.  You can find the module that the source object is in by viewing the reference information in the Properties window.


FRM-15102
FRM-15102:  Property class inherits from itself.

Cause:	You tried to assign a property class to itself.  In other words, you are trying to make the parent property class the same as the property class you are editing.

Action:	Assign another property class to the object.


FRM-15103
FRM-15103:  Can't delete %s because its parent is subclassed.

Cause:	You tried to delete an object which is owned by a subclassed object.

Action:	You cannot delete the object; instead, consider disabling the object by modifying the appropriate property in the Property Palette.


FRM-15104
FRM-15104:  Can't move %s because its parent is subclassed.

Cause:	You tried to move (reorder) an object which is owned by a subclassed object.

Action:	Consider reordering in the source of the owning object.  You can find the module that the source object is in by viewing the subclass information in the Properties window.


FRM-15107
FRM-15107:  Cannot create a reference.

Cause:	You tried to create a referenced object and the system does not have sufficient information to create the reference.

Action:	Make sure that the source of the referencing has been saved to either the file system or the database.  A new form that has not be saved cannot be the source of a reference.


FRM-15108
FRM-15108:  Cannot create an object before an inherited object.

Cause:	You tried to add or delete subobjects from a referenced object.

Action:	If you need to change a referenced object's structure, you must perform the operation at the source of the reference.  You can find the source of the reference by viewing the reference information in the Properties window for that object.


FRM-15109
FRM-15109:  Source module must be saved before subclassing.

Cause:	You tried to reference a source module that has not been saved.

Action:	Save the source module and reestablish the reference.


FRM-15110
FRM-15110:  Can't delete %s because it belongs to a subclassed object group.

Cause:	You tried to delete an object which belongs to a subclassed object group.

Action:	If you don't want all the objects in the subclassed object group, then you might consider either subclassing the desired objects individually, or creating an object group which contains only the desired objects.


FRM-15111
FRM-15111:  Can't create an item because the  module has no blocks.

Cause:	You tried to create an item in a form which contains no blocks.

Action:	Switch back to Ownership View and create a new block.


FRM-15200
FRM-15200:  There are cycles in this module.

Cause:	There is a cycle of submenu references in the module.

Action:	Find and fix the cycles before generating.  Use Expand All to help find cycles.


FRM-15201
FRM-15201:  Cannot expand because a cycle would be created.

Cause:	The selected item refers to a menu that is also an ancestor of that item.

Action:	Fix the cycle before expanding.


FRM-15202
FRM-15202:  There are references to non-existent submenus in this module.

Cause:	The module contains items that refer to submenus that do not exist.

Action:	Fix the non-existent references before generating.


FRM-15203
FRM-15203:  Cannot expand because submenu does not exist.

Cause:	There is a cycle of submenu references in the module.

Action:	Find and fix the cycles before generating.  Use Expand All to help find cycles.


FRM-15204
FRM-15204:  Cannot drag menus and menu items at the same time.

Cause:	You tried to drag a multiple selection that contains menus and menu items.

Action:	Drag menus one at a time.


FRM-15205
FRM-15205:  Cannot drag more than one menu at once.

Cause:	You tried to drag a multiple selection of menus.

Action:	Drag menus one at a time.


FRM-15206
FRM-15206:  Cannot modify referenced menu or menu item.

Cause:	Referenced objects cannot be modified.

Action:	If you need to change a referenced object's structure, you must perform the operation at the source of the reference.  You can find the source of the reference by viewing the reference information in the Properties window for that object.


FRM-15207
FRM-15207:  Parent item requires type change before submenu is attached.(Code may be lost.)

Cause:	The parent item is a type that cannot have a submenu.

Action:	Change the parent type before attaching the submenu.


FRM-15208
FRM-15208:  Unable to start the Menu Editor.

Cause:	Forms was unable to start up the Menu Editor due to an internal error.

Action:	Contact your DBA or an Oracle support representative.


FRM-15300
FRM-15300:  Column value is longer than specified length.

Cause:	A column value is longer than the length specified in the field.

Action:	Change the length value or column values.


FRM-15400
FRM-15400:  Unable to load the Chart Wizard.

Cause:	Either an internal error occurred, or Oracle Graphics was not properly installed.

Action:	Make sure Oracle Graphics is properly installed.


FRM-15401
FRM-15401:  Unable to load the specified Graphics Designer (OGD) file.

Cause:	The OGD filen specified in the Filename property of the chart item could not be found.

Action:	Make sure the specified OGD file exists in the specified location.


FRM-15402
FRM-15402:  Unable to run the Chart Wizard.

Cause:	Either an internal error occurred, or Oracle Graphics was not properly installed.

Action:	Contact your DBA or an Oracle support representative.


FRM-15403
FRM-15403:  Unable to display the Chart Item.

Cause:	Forms could not obtain a VGS display list from the Graphics Designer (OGD) file.

Action:	Make sure the specified file is a valid OGD file, or try recreating the OGD file.


FRM-15404
FRM-15404:  Unable to set attributes in the Graphics Designer (OGD) file.

Cause:	Forms could not apply the attributes from the Chart Wizard to the OGD file.

Action:	Make sure the specified file is a valid OGD file, or try recreating the OGD file.


FRM-15405
FRM-15405:  Unable to create a new Graphics Designer (OGD) file.

Cause:	Either an internal error occurred, or you do not have permission to create a file in the specified location.

Action:	Make sure you are allowed to create files in the specified location, and that Oracle Graphics is properly installed.


FRM-15500
FRM-15500:  Valid and unique object name must be entered.

Cause:	Object name must be a valid Oracle identifier and unique within its scope.

Action:	Enter a valid and unique name.


FRM-15501
FRM-15501:  This is not a referenced object.

Cause:	You tried to edit the reference information for a non-referenced object.

Action:	There is no reference information for this object.  Do not try to edit the reference information.


FRM-15502
FRM-15502:  This built-in trigger name is not valid at this level.

Cause:	You tried to create an invalid trigger for an object type.

Action:	Make sure you define the trigger for the appropriate level.


FRM-15503
FRM-15503:  This is a referenced subobject.

Cause:	You tried to edit the reference information for a subobject of a referenced object.

Action:	If you need to change a referenced object's structure, you must perform the operation at the source of the reference.  You can find the source of the reference by viewing the reference information in the Properties window for that object.


FRM-15504
FRM-15504:  Cannot retrieve list of VBX control names.

Cause:	Unable to locate list of VBX control names.

Action:	Reinstall VBX control files.


FRM-15505
FRM-15505:  Cannot retrieve list of VBX control properties.

Cause:	Unable to locate list of VBX control properties.

Action:	Reinstall VBX control files.


FRM-15506
FRM-15506:  Cannot retrieve list of OLE classes.

Cause:	Cannot communicate with the registration database.

Action:	Reinstall OLE servers.


FRM-15507
FRM-15507:  This selection would create a circular reference.choose another object.

Cause:	You are trying to assign a property class A to property class B, but property class A is defined as inheriting from property class B.

Action:	Do not attempt to make a circular reference.


FRM-17000
FRM-17000:  Data type is not valid for this object type.

Cause:	You selected a data type that is not valid for the type of object.

Action:	Select another data type.


FRM-17001
FRM-17001:  Items displayed must not be greater than records displayed in data block.

Cause:	You tried to set the Items Displayed property of an item to a number larger than the Records displayed property in the block.

Action:	Make sure the Records displayed property is greater than or equal to the Items displayed property.


FRM-17002
FRM-17002:  There is no tenant for this control.

Cause:	You tried to edit a property which requires the control to be populated with a tenant.

Action:	From the layout editor, insert a tenant into the control using the Insert Object command.


FRM-17003
FRM-17003:  The control must be visible in the layout editor to view this property.

Cause:	You tried to edit a property which requires the control to be visible in the layout edtior.

Action:	Open the layout editor for the canvas to which this control is assigned.


FRM-17004
FRM-17004:  There is no help available for this control.

Cause:	Forms could not locate a help file for this control.

Action:	Make sure the control is properly installed, or reinstall the control.


FRM-17005
FRM-17005:  Cannot determine the name of the control's class.

Cause:	Forms could not open the help file because the control's class name is not available.

Action:	Make sure the control is properly installed, or reinstall the control.


FRM-18100
FRM-18100:  Failed to compile the library.

Cause:	Generation of the library was unsuccessfull

Action:	Verify that all of the program units have been compiled successfully.


FRM-18101
FRM-18101:  Failed to start up the Information Navigator.

Cause:	The Information Navigator failed to start up.

Action:	Verify that the Information Navigator has been installed correctly.


FRM-18102
FRM-18102:  Failed to initialize the error dialog.

Cause:	Forms could not create the default error dialog.

Action:	Check your development environment.


FRM-18103
FRM-18103:  Failed to initialize the Development Environment.

Cause:	Forms could not start the Development Environment.

Action:	Check your development environment.


FRM-18104
FRM-18104:  Failed to start the Object Navigator.

Cause:	Forms could not start the Object Navigator.

Action:	Check your development environment.


FRM-18105
FRM-18105:  Failed to start the Help System.

Cause:	Forms could not start the Help System.

Action:	Check your development environment.


FRM-18106
FRM-18106:  Failed to create the Layout Editor context.

Cause:	Forms could not create the layout editor context.

Action:	Check your development environment.


FRM-18107
FRM-18107:  Failed to create a DE context for the module.

Cause:	Forms could not create the DE context for the module.

Action:	Check your development environment.


FRM-18108
FRM-18108:  Failed to load the following objects.

Cause:	Forms could not load the foreign references specified.

Action:	Verify that all the referenced forms and object libraries are present.


FRM-18109
FRM-18109:  An object named %s already exists inside object group %s.

Cause:	You attempted to add a Program Unit to the object library, but a Program Unit with the same name already exists inside an object group in the object library.

Action:	Remove the Program Unit from the object group and try again.


FRM-40007
FRM-40007:  Invalid user identifier or password. Re-enter.

Cause:	You entered an incorrect ORACLE username or password.

Action:	Retype your username and password properly.

Level:	>25

Type:	Error


FRM-40010
FRM-40010:  Cannot read form %s.

Cause:	One of the following:

1. You entered a nonexistent form name.

2. You typed an incomplete path.

3. You do not have the proper privileges to run the form.

4. You do not have a compiled copy of the form.

Action:	Retype the form name correctly, provide the proper path name, compile the form, or contact the DBA.

Level:	5

Type:	Error


FRM-40011
FRM-40011:  Form was created by an old version of Form Builder.

Cause:	The .FMB file was created with an old and incompatible version of Forms Compiler.

Action:	Recompile the form or relink Generate.

Level:	>25

Type:	Error


FRM-40012
FRM-40012:  Form was created by a new version of Form Builder.

Cause:	The .FMB file was created by a new and incompatible version of Forms Compiler.

Action:	Recompile the form.

Level:	>25

Type:	Error


FRM-40013
FRM-40013:  Program Error: error occurred while reading form.

Cause:	An internal error occurred while Form Builder was trying to read the .FMB file.

Action:	Recompile the form.

Level:	>25

Type:	Error


FRM-40014
FRM-40014:  Not enough memory to load the form.

Cause:	Internal error. Your computer does not have enough memory to run the form.

Action:	The designer might be able to modify the form so that it will run.  If that is not feasible, your installation must make more memory available, either by modifying the operating system parameters or by adding more memory to the computer.

Level:	>25

Type:	Error


FRM-40015
FRM-40015:  Unexpected end of file reading form.

Cause:	The form was fragmented or incomplete.

Action:	Recompile the form.

Level:	>25

Type:	Error


FRM-40019
FRM-40019:  Unknown screen number to display.

Cause:	An internal error occurred.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40020
FRM-40020:  Page %d too small for this form.

Cause:	Application design error.  An item is positioned off the page.

Action:	Ensure that all items that are associated with the given page fit completely on that page.  You can reposition the items or resize the page.

Level:	>25

Type:	Error


FRM-40021
FRM-40021:  Item in form file is too large.

Cause:	An internal error occurred while Form Builder was reading the form.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40023
FRM-40023:  Error creating record manager context.

Cause:	Form Builder could not initialize its internal record manager.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40024
FRM-40024:  Out of memory.

Cause:	Internal error.  Your computer does not have enough memory to run the form.

Action:	The designer might be able to modify the form so that it will run.  If that is not feasible, your installation must make more memory available, either by modifying the operating system parameters or by adding more memory to the computer.

Level:	>25

Type:	Error


FRM-40025
FRM-40025:  Cannot suppress screen output without file input.

Cause:	You tried to run a form on the command line using incompatible preferences.  The output_file preference works only in conjunction with the keyin preference.

Action:	Retype the command to include both the output_file and keyin preferences.

Level:	>25

Type:	Error


FRM-40026
FRM-40026:  Error opening key script file.

Cause:	Form Builder cannot open the file you specified with the keyin preference.

Action:	Make sure the file exists and the file protections are set properly.  Or create a file with the keyin preference.

Level:	>25

Type:	Error


FRM-40027
FRM-40027:  Error opening display spool file.

Cause:	Operating system error.  Form Builder cannot open a file specified with the output_file preference because there is insufficient disk space or because you have specified an incorrect filename.

Action:	Contact your DBA or system administrator.

Level:	>25

Type:	Error


FRM-40028
FRM-40028:  Error opening message file %s%s%s.MSB.

Cause:	Form Builder cannot find the message file.

Action:	Make sure the message file exists and the appropriate path is set.

Level:	>25

Type:	Error


FRM-40029
FRM-40029:  Already logged on.  Must logout before changing connections.

Cause:	The Login() built-in was issued while already logged on.

Action:	Use the Logout() built-in first.

Level:	>25

Type:	Error


FRM-40030
FRM-40030:  File %s is not a Forms 4.0 file.

Cause:	The file specified on the command line was not a valid Form Builder file.

Action:	Re-enter Forms Runtime startup command with the name of a valid file.

Level:	No level

Type:	Startup message


FRM-40031
FRM-40031:  File %s is not a Forms Runtime file.

Cause:	The file specified on the command line is not a Forms Runtime (.FMX) file.

Action:	Re-enter a valid Forms Runtime (.FMX) file.

Level:	No level

Type:	Startup message


FRM-40032
FRM-40032:  Internal Error: file %s contains an improper chunk size.

Cause:	Internal error.  File was compiled incorrectly or is corrupted.

Action:	Recompile your file.

Level:	No level

Type:	Startup message


FRM-40033
FRM-40033:  Internal Error: file %s contains a bad chunk table.

Cause:	Internal error.  File was compiled incorrectly or is corrupted.

Action:	Recompile your file.

Level:	No level

Type:	Startup message


FRM-40034
FRM-40034:  Cannot attach the library file.

Cause:	Form Builder was unable to find the specified library file.

Action:	Exit Forms Runtime and try again.

Level:	>25 (this message cannot be suppressed)

Type:	Error


FRM-40035
FRM-40035:  Error creating per-block record manager context.

Cause:	Form Builder could not initialize its internal record manager.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40036
FRM-40036:  Library was created by a new version of Form Builder.

Cause:	Form Builder unable to use library.

Action:	Recompile the library with current version of Form Builder.

Level:	>25

Type:	Error


FRM-40037
FRM-40037:  Library was created by an old version of Form Builder.

Cause:	Form Builder unable to use library.

Action:	Recompile the library with current version of Form Builder.

Level:	>25

Type:	Error


FRM-40038
FRM-40038:  Could not find %s VBX control for item %s in block %s.

Cause:	Application design error. A VBX control specified in the .FMB file cannot be found at runtime.

Action:	Make sure the VBX control file can be found in the location as specified in the Form Builder.

Level:	>25

Type:	Error


FRM-40039
FRM-40039:  Cannot attach library %s while opening form %s.

Cause:	The given library is attached to the form but cannot be located in the search path for PL/SQL libraries.

Action:	Make sure that the given library can be found and that it has read permissions set.

Level:	99

Type:	Error


FRM-40100
FRM-40100:  At first record.

Cause:	You pressed [Previous Record] when the cursor was at the first record.

Action:	No action is necessary.

Level:	5

Type:	Error


FRM-40101
FRM-40101:  Cannot position to a key item. None are navigable.

Cause:	You pressed [Next Primary Key Item], but there are no enterable primary key items in this block.

Action:	Use [Next Item] for navigation rather than [Next Primary Key Item].

Level:	10

Type:	Error


FRM-40102
FRM-40102:  Record must be entered or deleted first.

Cause:	You pressed [Next Record] or [Down] in a context where it is meaningless. Either:

1.  The last record in a block is the current record.

2.  The block is empty.

3.  You are in a new record in the middle of the block created by pressing [Insert Record].

Action:	No action is necessary.

Level:	5

Type:	Error


FRM-40103
FRM-40103:  Cannot position to a key item. None are queryable.

Cause:	You tried to use [Next Primary Key Item], but none of the primary key items in the block allow you to enter query criteria.

Action:	No action is necessary.

Level:	10

Type:	Error


FRM-40104
FRM-40104:  No such block: %s.

Cause:	Runtime error.  A GO_BLOCK statement references a nonexistent block.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40105
FRM-40105:  Unable to resolve reference to item %s.

Cause:	Runtime error.  A GO_ITEM statement references a nonexistent item.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40106
FRM-40106:  No navigable items in destination block.

Cause:	Runtime error.  A GO_BLOCK statement references a block with no enterable items.

Action:	Remove the statement or make at least one item in the block enterable.

Level:	>25

Type:	Error


FRM-40107
FRM-40107:  Cannot navigate to non-displayed item %s.

Cause:	Runtime error.  A GO_ITEM statement references a non-displayed item.

Action:	Remove the statement or turn on the Displayed property for the indicated item.

Level:	>25

Type:	Error


FRM-40108
FRM-40108:  No such form: %s.

Cause:	You attempted to get/set properties of a nonexistent or unloaded form.

Action:	Use a valid form name.

Level:	>25

Type:	Error


FRM-40109
FRM-40109:  Cannot navigate out of current block in enter-query mode.

Cause:	You attempted to navigate out of the current block during enter-query mode.

Action:	No action is necessary.  You cannot navigate out of the current block or record during enter-query mode.

Level:	99

Type:	Error


FRM-40110
FRM-40110:  At first block.

Cause:	You attempted [Previous Block] when at the first block.

Action:	None.  Consider an alternative method of navigation.

Level:	5

Type:	Error


FRM-40111
FRM-40111:  At last block.

Cause:	You attempted [Next Block] when at the last block.

Action:	None.  Consider an alternative method of navigation.

Level:	5

Type:	Error


FRM-40200
FRM-40200:  Field is protected against update.

Cause:	You tried to update a field that does not allow updates.

Action:	No action is necessary. You cannot update this field in this form.

Level:	15

Type:	Error


FRM-40201
FRM-40201:  Field is full. Can't insert character.

Cause:	Form Builder is in insert mode, and the current field is full.

Action:	Delete a character to make room for the new character or press [Insert/Replace] to activate replace mode.

Level:	10

Type:	Error


FRM-40202
FRM-40202:  Field must be entered.

Cause:	You have not entered a value (or you have deleted a value) in a field that requires data input.

Action:	You must enter a value in this field.

Level:	15

Type:	Error


FRM-40203
FRM-40203:  Field must be entered completely.

Cause:	You have not entered a complete value (or you have deleted part of a value) in a field that has a fixed length requirement.

Action:	Enter a complete value (one that extends to the end of the field).

Level:	15

Type:	Error


FRM-40204
FRM-40204:  Cursor is at beginning of field value.

Cause:	You tried to delete a character before the first character position of the field.

Action:	Use [Delete Character] to delete the character that the cursor is on.

Level:	10

Type:	Error


FRM-40205
FRM-40205:  Cursor is beyond the current field value.

Cause:	On a block mode terminal, you positioned the cursor out of a field.

Action:	Move the cursor into the field and try the entry again.

Level:	15

Type:	Error


FRM-40206
FRM-40206:  Previous character is currently hidden.

Cause:	You tried to delete a character that is off the screen.

Action:	Scroll the character you want to delete into view using the arrow keys or [Scroll Left] and [Scroll Right].

Level:	10

Type:	Error


FRM-40207
FRM-40207:  Must be in range %.30s to %.30s.

Cause:	You entered a value not in the valid item range.

Action:	Enter a value in the range shown.

Level:	15

Type:	Error


FRM-40208
FRM-40208:  Form running in query-only mode. Cannot change database fields.

Cause:	You entered a value on a query-only form.

Action:	Do not enter values on this form.  You can execute queries and view data, but you cannot alter existing data or enter new data.

Level:	15

Type:	Error


FRM-40209
FRM-40209:  Field must be of form %s.

Cause:	The value that you entered did not match the format mask on the field.

Action:	Retry with a field value that matches the format mask.

Level:	>25

Type:	Error


FRM-40210
FRM-40210:  Search string not found.

Cause:	Search string does not exist in the module.

Action:	Check your search string to make sure it is accurate or try another search string.

Level:	99

Type:	Informative


FRM-40211
FRM-40211:  Warning!  Newlines may be stripped from this field.

Cause:	You attempted to assign data with newlines to a single-line text field.

Action:	Assign to a multi-line text field if you need the newlines.

Level:	5

Type:	Informative


FRM-40212
FRM-40212:  Invalid value for field %s.

Cause:	Caused by one of the following:

1.  The value is not of the proper data type.

2.  The value does not match any of the list of acceptable values.

3.  For a text field, the value does not match the specified range.

Action:	Retry with another value.

Level:	>20

Type:	Message


FRM-40213
FRM-40213:  Cannot Copy_Region/Cut_Region; region not selected.

Cause:	Region not selected.

Action:	Select a region and try again.

Level:	5

Type:	Error


FRM-40214
FRM-40214:  Cannot open the clipboard for the copy/cut.

Cause:	Clipboard unavailable.

Action:	Platform specific.

Level:	99

Type:	Error


FRM-40215
FRM-40215:  Cannot write to the clipboard.

Cause:	Clipboard unavailable.

Action:	Platform specific.

Level:	99

Type:	Error


FRM-40216
FRM-40216:  Cannot open the clipboard for the paste.

Cause:	Clipboard unavailable.

Action:	Platform specific.

Level:	99

Type:	Error


FRM-40217
FRM-40217:  Cannot get the data size from the clipboard.

Cause:	Invalid data.

Action:	Platform specific.

Level:	99

Type:	Error


FRM-40218
FRM-40218:  Cannot read from the clipboard.

Cause:	Invalid data.

Action:	Platform specific.

Level:	99

Type:	Error


FRM-40219
FRM-40219:  Cannot format the data read from the clipboard.

Cause:	Invalid data.

Action:	Platform specific.

Level:	99

Type:	Error


FRM-40220
FRM-40220:  Cannot paste from the clipboard; value too long.

Cause:	Invalid data.

Action:	Platform specific.

Level:	99

Type:	Error


FRM-40221
FRM-40221:  Cannot Paste_Region; region not selected.

Cause:	Paste_Region was invoked while no portion of the image item was selected.

Action:	Select a region of the image item prior to calling Paste_Region.


FRM-40222
FRM-40222:  Disabled item '%s.%s' failed validation.

Cause:	Probable application design error.  Forms determined that the item contains an invalid value, but it cannot give focus to the item because it is disabled.  This could happen because either:

The application programmatically assigned an invalid valid to the item.

The application programmatically disabled the item after the end user entered an invalid valid in the item (and before the item was validated).

Action:	Correct the application logic.

Level:	25

Type:	Error


FRM-40301
FRM-40301:  Query caused no records to be retrieved. Re-enter.

Cause:	No records matched the query criteria. Still in Enter Query mode.

Action:	Either adjust the query criteria or press [Exit/Cancel] to leave Enter Query mode.

Level:	>25

Type:	Informative


FRM-40302
FRM-40302:  Cannot enter a query. No fields are queryable.

Cause:	You pressed [Enter Query] while the cursor was in a block with no queryable fields.

Action:	No action is necessary.

Level:	15

Type:	Error


FRM-40303
FRM-40303:  No base table fields in the block.

Cause:	One of the blocks in the current module has no base table fields.

Action:	No action is necessary.

Level:	5

Type:	Informative


FRM-40350
FRM-40350:  Query caused no records to be retrieved.

Cause:	The current query fetched no records from the table. The table is empty, or it contains no records that meet the query's search criteria.

Action:	No action is necessary.

Level:	5

Type:	Informative


FRM-40352
FRM-40352:  Last record of query retrieved.

Cause:	You pressed [Down], [Next Record], [Next Set of Records], or [Scroll Down] after all records had been retrieved.

Action:	No action is necessary.

Level:	5

Type:	Informative


FRM-40353
FRM-40353:  Query cancelled.

Cause:	You pressed [Exit/Cancel] in Enter Query mode, or you pressed CTRL-C (or its equivalent) while Form Builder was fetching rows from the database.

Action:	No action is necessary.

Level:	The message level is 5 when the message is invoked by CTRL-C.

Type:	Informative


FRM-40355
FRM-40355:  Query will retrieve %ld records.

Cause:	You pressed [Count Query Hits].  If you now press [Execute Query], the number of records will be retrieved.

Action:	No action is necessary.

Level:	25

Type:	Informative


FRM-40356
FRM-40356:  Invalid number in example record.  Query not issued.

Cause:	In Enter Query mode, you entered an invalid number in the example record.

Action:	Correct the entry and retry the query.

Level:	>25

Type:	Error


FRM-40357
FRM-40357:  Invalid string in example record.  Query not issued.

Cause:	In query mode, you entered an invalid ALPHA or CHAR value in the example record.

Action:	Correct the entry and retry the query.

Level:	>25

Type:	Error


FRM-40358
FRM-40358:  Invalid date in example record.  Query not issued.

Cause:	In Enter Query mode, you entered an invalid DATE in the example record.

Action:	Correct the entry and retry the query.

Level:	>25

Type:	Error


FRM-40359
FRM-40359:  Invalid date or time in example record.  Query not issued.

Cause:	In Enter Query mode, you entered an invalid JDATE, EDATE, or TIME value in the example record.

Action:	Correct the entry and retry the query.

Level:	>25

Type:	Error


FRM-40360
FRM-40360:  Cannot query records here.

Cause:	You attempted to query a block that does not allow queries.

Action:	Do not attempt to query this block.

Level:	>25

Type:	Error


FRM-40361
FRM-40361:  Query operation not support for TIME data type.

Cause:	You made a query with a % "like" operator in a time field, which is not supported.

Action:	Try to restate your query without a time data type.

Level:	>25

Type:	Error


FRM-40364
FRM-40364:  The data type of item '%s' does not match the corresponding column in the stored procedure.

Cause:	The data type of the item is different from the data type of the corresponding column in the stored procedure.

Action:	Make the data type of the item in the block and the column in the stored procedure the same.

Level:	20

Type:	Error

Cause:	A long running query is currently executing, press the cancel button to stop it.

Action:	No action is necessary.

Level:	5

Type:	Informative

Cause:	A long running query is currently executing.  Press this button to stop it.

Action:	No action is necessary.

Level:	5

Type:	Informative


FRM-40400
FRM-40400:  Transaction complete: %d records applied and saved.

Cause:	Save complete.

Action:	No action is necessary.

Level:	5

Type:	Informative


FRM-40401
FRM-40401:  No changes to save.

Cause:	No records were added or modified since the last apply or save.

Action:	No action is necessary.

Level:	5

Type:	Error


FRM-40402
FRM-40402:  Save cancelled.

Cause:	You pressed CTRL-C (or the equivalent) while waiting for a lock.

Action:	No action is necessary.

Level:	10

Type:	Informative


FRM-40403
FRM-40403:  A calling form has unapplied changes.  Save not allowed.

Cause:	A calling form has unapplied changes.

Action:	Apply the changes or return to the calling form and retry the save.

Level:	15

Type:	Error


FRM-40404
FRM-40404:  Database apply complete: %d records applied.

Cause:	Apply complete.

Action:	No action is necessary.

Level:	5

Type:	Informative


FRM-40405
FRM-40405:  No changes to apply.

Cause:	No records were added or modified since the last apply or save.

Action:	No action is necessary.

Level:	5

Type:	Error


FRM-40406
FRM-40406:  Transaction complete: %d records applied; all records saved.

Cause:	You finished an apply that recorded your changes and saved previously applied changes.

Action:	No action is necessary.

Level:	5

Type:	Informative


FRM-40407
FRM-40407:  Transaction complete: applied records saved.

Cause:	You finished a save that saved previously applied changes.

Action:	No action is necessary.

Level:	5

Type:	Informative


FRM-40501
FRM-40501:  ORACLE error: unable to reserve record for update or delete.

Cause:	A fatal error occurred while trying to select the record for update.

Action:	Pressing [Display Error] provides more information, if it is available.  You can also try to update or delete this record later.  If necessary, contact your DBA.

Level:	>25

Type:	Error


FRM-40502
FRM-40502:  ORACLE error: unable to read list of values.

Cause:	A fatal error occurred while trying to read a list of values.

Action:	Contact your DBA or an Oracle support representative.

Level:	>25

Type:	Error


FRM-40504
FRM-40504:  ORACLE error: unable to execute a %s trigger.

Cause:	A fatal error occurred while trying to execute a trigger.

Action:	Contact your DBA or an Oracle support representative.

Level:	>25

Type:	Error


FRM-40505
FRM-40505:  ORACLE error: unable to perform query.

Cause:	Processing error encountered.  The table associated with the current block of the form might not exist, or your username might not have authority to perform the specified action on the table.

Action:	Pressing [Display Error] provides more information, if it is available.  You can also try to update or delete this record later.  If necessary, contact your DBA.

Level:	>25

Type:	Error


FRM-40506
FRM-40506:  ORACLE error: unable to check for record uniqueness.

Cause:	Processing error encountered while checking a record's primary key items for uniqueness.  The table associated with the current block of the form does not exist, or you do not have authority to access the table.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40507
FRM-40507:  ORACLE error: unable to fetch next query record.

Cause:	One of the following:

1. A fatal error occurred while trying to fetch the next query record.

2. If you are connected to an non-Oracle datasource through ODBC, the cursor loses its position in the result set after a commit.

Action:	Requery if you are connected with a non-Oracle datasource. If not, contact your DBA.

Level:	>25

Type:	Error


FRM-40508
FRM-40508:  ORACLE error: unable to INSERT record.

Cause:	A fatal error occurred while trying to insert a record.  The table associated with the current block of the form might not exist, your username might not have authority to perform the specified action on the table, or some other reason might have caused the fatal error.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40509
FRM-40509:  ORACLE error: unable to UPDATE record.

Cause:	A fatal error occurred while trying to update a record.  The table associated with the current block of the form might not exist, your username might not have authority to perform the specified action on the table, or some other reason might have caused the fatal error.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40510
FRM-40510:  ORACLE error: unable to DELETE record.

Cause:	A fatal error occurred while trying to delete a record.  The table associated with the current block of the form might not exist, your username might not have authority to perform the specified action on the table, or some other reason might have caused the fatal error.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40511
FRM-40511:  ORACLE error occurred while executing a %s trigger.

Cause:	A fatal error occurred while trying to execute a trigger.  The table associated with the current block of the form might not exist, your username might not have authority to perform the specified action on the table, or some other reason might have caused the fatal error.

Action:	Contact your DBA

Level:	>25

Type:	Error


FRM-40512
FRM-40512:  ORACLE error: unable to issue SAVEPOINT command.

Cause:	While attempting to call a new form or to commit, the issued SAVEPOINT command failed.  This generally means that the module has run out of savepoints.

Action:	Press [Display Error] to display the specific ORACLE error.  You might be able to increase the maximum number of savepoints in the INIT.ORA file.

Level:	>25

Type:	Error


FRM-40513
FRM-40513:  ORACLE error: unable to get date/time from database.

Cause:	An error occurred while trying to resolve a database date/time initial value.

Action:	Connect if you have not already done so.  Verify database status.

Level:	10

Type:	Error


FRM-40514
FRM-40514:  Operation requires a database connection.

Cause:	You tried to perform an database operation without connecting to the database.

Action:	Connect to the database and retry.

Level:	20

Type:	Error


FRM-40515
FRM-40515:  ORACLE error: unable to open cursor.

Cause:	You reached the limit in the number of cursors you can open.

Action:	Check the number of cursors you have open.

Level:	99

Type:	Error


FRM-40600
FRM-40600:  Record has already been inserted.

Cause:	You attempted to insert or update a record, but uniqueness is enforced on the block's primary key items.  The record, as inserted or updated, is not unique.

Action:	Change the values in one or more primary key fields of the current record, making them unique.  If the requirement of unique primary key fields creates difficulties, consider eliminating the constraint.

Level:	>25

Type:	Error


FRM-40602
FRM-40602:  Cannot insert into or update data in a view.

Cause:	You tried to modify the contents of a view in a manner that is not permitted.

Action:	No action is necessary; you cannot perform the operation you have attempted.

Level:	20

Type:	Error


FRM-40603
FRM-40603:  Records no longer reserved for update.  Re-query to make changes.

Cause:	You committed your modifications in a block where you had previously entered an ENTER_QUERY or EXECUTE_QUERY packaged procedure with the FOR_UPDATE parameter.  This action released all locks on the records in this block.

Action:	If you want to modify the block, you will need to re-query.

Level:	>25

Type:	Error


FRM-40652
FRM-40652:  Cannot lock table in shared update mode.

Cause:	Caused by one of the following:

1. You do not have access to this table.

2. Form Builder cannot lock the table in shared update mode.

Action:	Contact your DBA.

Level:	15

Type:	Error


FRM-40653
FRM-40653:  Record not reserved for update or delete.  Try again later.

Cause:	You pressed CTRL-C (or the equivalent) to cancel.  The operation that was attempting to update or delete the record was terminated.

Action:	No action is necessary.

Level:	20

Type:	Informative


FRM-40654
FRM-40654:  Record has been updated by another user. Re-query to see change.

Cause:	Another user has updated this record since you performed a query and has changed at least one field in the record.  Your actions have not changed the record in memory.

Action:	You can update or delete this record now only if another user has restored the field values back to the way they were when you performed the query.  Otherwise, you must re-query to fetch and display the new record into the form before you can update or delete it.

Level:	20

Type:	Error


FRM-40655
FRM-40655:  SQL error forced rollback: clear form and re-enter transaction.

Cause:	A deadlock or some other error has caused the current transaction to fail.  Your changes were rolled back.

Action:	Clear the form (or exit and re-enter the form) and re-enter the transaction. You might have to modify the form's design to prevent the error from recurring.

Level:	>25

Type:	Error


FRM-40656
FRM-40656:  Update cannot be made due to prior rollback.  Clear the record.

Cause:	This record was already updated, but when you attempted to commit your changes, a serious error prevented this update or any further update or delete from being performed.  The error might have occurred due to one of the following reasons:

1.  A deadlock forced the loss of row locks.

2.  The record had a database cluster key, and the previous attempt to update the record in the database was rolled back due to an error somewhere else in the form.

Action:	You must clear this record before you can commit any other transactions in the form.

Level:	25

Type:	Error


FRM-40657
FRM-40657:  Record changed or deleted by another user.

Cause:	Another user has deleted the record since the query was executed.

Action:	You can clear this record from your screen, but you cannot update or delete it since it no longer exists in the database.

Level:	20

Type:	Informative


FRM-40659
FRM-40659:  Last row of query retrieved.  Re-query to see remaining records.

Cause:	A FOR_UPDATE query has been closed by executing a commit.  Because the query was open prior to the commit, there may be more records to retrieve.

Action:	Re-query to see remaining records.

Level:	5

Type:	Message


FRM-40700
FRM-40700:  No such trigger:  %s.

Cause:	Application design error.  The form attempted to execute a trigger that doesn't exist, causing a fatal error.

Action:	Correct the reference to the trigger.

Level:	20

Type:	Error


FRM-40702
FRM-40702:  Cannot call form with changes to save

Cause:	You attempted to call another form with unsaved changes in the current form and savepoint mode off.

Action:	Commit/post changes and then retry.

Level:	15

Type:	Error


FRM-40703
FRM-40703:  Fetched field cannot be changed in query mode.

Cause:	You attempted to modify a fetched item in query mode.

Action:	None required.

Level:	20

Type:	Error


FRM-40704
FRM-40704:  Illegal SQL statement in query-only mode

Cause:	Application design error.  The form tried to execute a function that is illegal in a query-only form.

Action:	You might need to redesign the form.

Level:	20

Type:	Error


FRM-40705
FRM-40705:  Illegal SQL statement in non-commit-time trigger.

Cause:	Application design error.  The current trigger contains a SQL statement that is illegal for the trigger type.

Action:	Rewrite the trigger text or use a different type of trigger.

Level:	20

Type:	Error


FRM-40714
FRM-40714:  Function illegal in this context.

Cause:	Application design error.  The current trigger contains an illegal function code.

Action:	Rewrite the trigger text or use a different type of trigger.

Level:	20

Type:	Error


FRM-40720
FRM-40720:  No statements found in list of statements.

Cause:	Application design error.  A step in a V2 trigger uses incorrect syntax.

Action:	Correct the trigger step text.

Level:	>25

Type:	Error


FRM-40721
FRM-40721:  Missing function code in trigger.

Cause:	Application design error.  A step in a V2 trigger uses incorrect syntax.

Action:	Correct the trigger step text.

Level:	>25

Type:	Error


FRM-40722
FRM-40722:  Unrecognized function name.

Cause:	Application design error.  A trigger references a nonexistent function code.

Action:	Correct the reference.

Level:	>25

Type:	Error


FRM-40723
FRM-40723:  Missing argument for function code.

Cause:	Application design error.  An argument is missing in an ERASE, EXECUTE_TRIGGER, GO_BLOCK, GO_ITEM, GO_RECORD, or NEW_FORM statement.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40724
FRM-40724:  Missing selector in CASE statement.

Cause:	Application design error.  The selector portion is missing in a CASE statement.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40725
FRM-40725:  Missing keyword in CASE statement.

Cause:	Application design error.  A keyword is missing in a CASE statement.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40726
FRM-40726:  Missing choice in CASE statement.

Cause:	Application design error.  A choice is not specified in a CASE statement.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40727
FRM-40727:  Illegal keyword in CASE statement.

Cause:	Application design error.  A CASE statement contains a mistyped keyword.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40728
FRM-40728:  Unrecognized or extra arguments to function.

Cause:	Application design error.  A function specifies extra arguments.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40729
FRM-40729:  Missing semicolon at end of statement.

Cause:	Application design error.  A semicolon is missing at the end of a function code.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40730
FRM-40730:  Invalid message suppress level--unchanged from %d.

Cause:	Application design error.  A trigger attempted to set the system message level to an invalid number.

Action:	Reset the SYSTEM.MESSAGE_LEVEL system variable to a valid number.

Level:	>25

Type:	Error


FRM-40731
FRM-40731:  INTO keyword missing.

Cause:	Application design error.  A COPY statement is missing the INTO clause.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40732
FRM-40732:  Target of GOTO does not exist in this macro.

Cause:	Application design error.  The label referenced in PL/SQL does not exist.

Action:	Correct the statement.


FRM-40733
FRM-40733:  PL/SQL built-in %s failed.

Cause:	A fatal error occurred in Form Builder or in PL/SQL during trigger execution.

Action:	Notify the DBA.

Level:	>25

Type:	Error


FRM-40734
FRM-40734:  Internal Error: PL/SQL error occurred.

Cause:	A fatal error occurred in PL/SQL during trigger execution.

Action:	Notify the DBA.

Level:	>25

Type:	Error


FRM-40735
FRM-40735:  %s trigger raised unhandled exception %s.

Cause:	Application design error.  The current trigger raised an exception (other than FORM_TRIGGER_FAILURE), but it did not handle the exception.

Action:	Rewrite the trigger text to handle the exception.

Level:	>25

Type:	Error


FRM-40736
FRM-40736:  Cannot initialize PL/SQL.

Cause:	An internal error occurred while initializing PL/SQL.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40737
FRM-40737:  Illegal restricted procedure %s in %s trigger.

Cause:	Application design error.  A trigger tried to execute a restricted packaged procedure.

Action:	Remove the packaged procedure from the trigger text.

Level:	>25

Type:	Error


FRM-40738
FRM-40738:  Argument %d to builtin %s cannot be null.

Cause:	Application design error.  No arguments were provided to the built-in.

Action:	Refer to the online Help for the correct usage of this built-in.

Level:	99

Type:	Error


FRM-40739
FRM-40739:  Full rollback not allowed in post-only form.

Cause:	Application design error.  A trigger tried to issue a CLEAR_FORM packaged procedure with the FULL_ROLLBACK parameter in a post-only, called form.

Action:	Remove the FULL_ROLLBACK parameter or ensure that the calling form does not have unposted changes when the call occurs.

Level:	>25

Type:	Error


FRM-40740
FRM-40740:  Procedure %s only allowed in an on-%s trigger.

Cause:	Application design error.  A non-transactional trigger attempted to invoke a built-in procedure that is restricted to a given trigger.

Action:	Refer to the online Help for the correct usage of this procedure.

Level:	>25

Type:	Error


FRM-40741
FRM-40741:  Unable to locate record %d on block %s.

Cause:	You attempted to get or set record properties for an invalid record number for the given block.

Action:	Verify your Get/Set record property parameters.

Level:	20

Type:	Error


FRM-40742
FRM-40742:  Illegal status conversion on record %d: %s to %s.

Cause:	Application design error.  A call to SET_RECORD_PROPERTY attempted an illegal conversion between record statuses.

Action:	Refer to SET_RECORD_PROPERTY in online Help for correct transitions.

Level:	>25

Type:	Error


FRM-40743
FRM-40743:  This operation with no base table requires the %s trigger.

Cause:	Application design error.  Attempted a database operation (query, insert, update, etc.) on a non-base table block without the appropriate transactional trigger.

Action:	Refer to online Help for the appropriate transactional trigger and then create the correct trigger.

Level:	20

Type:	Error


FRM-40744
FRM-40744:  Truncation of input value will occur if editor accepted.

Cause:	The editor's buffer is too small to accept the input.

Action:	Change editors or enlarge the buffer.

Level:	15

Type:	Error


FRM-40745
FRM-40745:  Output value of built-in %s was truncated.

Cause:	Output variable is too small.

Action:	Increase the size of the PL/SQL output variable.

Level:	15

Type:	Error


FRM-40746
FRM-40746:  Cannot call built-in %s from startup debugger window.

Cause:	Built-in is not accessible from the startup debugger window.

Action:	Refer to the Form Builder Developer's Guide for a list of built-ins that are not accessible from the startup debugger window.

Level:	99

Type:	Informative


FRM-40747
FRM-40747:  Cannot call built-in %s from a debug trigger.

Cause:	Built-in is not accessible from the debug trigger.

Action:	Refer to the Form Builder Developer's Guide for a list of built-ins that are accessible from a debug trigger .

Level:	99

Type:	Informative


FRM-40748
FRM-40748:  Trigger %s terminated by reset command.

Cause:	You issued the reset command or you pressed the reset button in the debugger.

Action:	If you want to navigate downward, go to the call stack.

Level:	99

Type:	Informative


FRM-40749
FRM-40749:  Invalid record status specified for record %d.

Cause:	Application design error.  An attempt was made to set the STATUS property of a record to an invalid value.

Action:	The record's STATUS property should be set to NEW_STATUS, QUERY_STATUS, INSERT_STATUS, or CHANGED_STATUS.

Level:	99

Type:	Error


FRM-40750
FRM-40750:  Record %d: Can't set status to QUERY or CHANGED in a control block.

Cause:	Application design error.  An attempt was made to set the STATUS property of a record in a control block to QUERY_STATUS or CHANGED_STATUS.

Action:	The record's STATUS property should be set to NEW_STATUS or INSERT_STATUS.

Level:	99

Type:	Error


FRM-40800
FRM-40800:  User exit %s does not exist.

Cause:	The form tried to invoke a user exit that does not exist. This could be caused by one of the following:

1. You are using the wrong version of Forms Runtime.

2. There could be an error in the form.

Action:	If you are using the wrong version of Forms Runtime, determine which version contains the user exit, and use that version to run the form.  If there is an error in the form, the designer should correct the call to the user exit.

Level:	20

Type:	Error


FRM-40801
FRM-40801:  Out of memory processing user exit.

Cause:	A fatal error occurred.

Action:	Contact your DBA.

Level:	25

Type:	Error


FRM-40804
FRM-40804:  Not enough arguments to COPY command.

Cause:	Application design error.  A COPY statement does not specify a source or destination.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40805
FRM-40805:  Not enough arguments to ERASE command.

Cause:	Application design error.  An ERASE statement does not specify a variable.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40807
FRM-40807:  No command string specified for HOST command.

Cause:	Application design error.  A HOST statement does not specify a command string.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40808
FRM-40808:  Cannot execute HOST command.  Error code = %s.

Cause:	Cannot execute a HOST statement because of an operating system error.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40809
FRM-40809:  HOST command had error code = %s.

Cause:	The operating system command resulted in the above error code.

Action:	Verify that you entered the command properly.

Level:	>25

Type:	Error


FRM-40811
FRM-40811:  Shell command had error.

Cause:	The operating system command resulted in the above error code.

Action:	Verify that you entered the command properly.

Level:	>25

Type:	Error


FRM-40814
FRM-40814:  Illegal function code in this context.

Cause:	Application design error.  The NOFAIL keyword is specified for a function code that does not accept that keyword.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40815
FRM-40815:  Variable GLOBAL.%s does not exist.

Cause:	Application design error.  A trigger references a global variable that does not exist.

Action:	Create the global variable or remove the reference.

Level:	>25

Type:	Error


FRM-40816
FRM-40816:  Could not allocate memory for new symbol.

Cause:	Internal error. Out of memory while accessing a new global variable.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40817
FRM-40817:  Could not allocate memory for new value.

Cause:	Internal error. Out of memory while accessing a new global variable.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40818
FRM-40818:  System variable name not defined.

Cause:	You have tried to access a system variable that does not exist.

Action:	Check the system variable name.

Level:	99

Type:	Error


FRM-40819
FRM-40819:  System variable is not modifiable.

Cause:	You have tried to modify a system variable.

Action:	You cannot modify system variables.

Level:	99

Type:	Error


FRM-40820
FRM-40820:  Not enough memory to evaluate system variable.

Cause:	Internal error.  Out of memory while accessing a system variable.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40822
FRM-40822:  Not enough arguments to SET function.

Cause:	Application design error.  A SET function code does not specify enough arguments.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40823
FRM-40823:  Extra argument to SET function.

Cause:	Application design error.  A SET function code specifies too many arguments.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40824
FRM-40824:  Not enough arguments to PAGE function.

Cause:	Application design error.  A HIDEPAGE or a SHOWPAGE function code does not specify enough arguments.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40825
FRM-40825:  Not enough arguments to VIEW function.

Cause:	Application design error.  A MOVEVIEW, ANCHORVIEW, or RESIZEVIEW function code does not specify enough arguments.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40826
FRM-40826:  Invalid number of arguments to CALL function.

Cause:	Application design error.  A CALL or CALLQRY function code does not specify enough arguments.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40827
FRM-40827:  Not enough arguments to GOREC function.

Cause:	Application design error.  A GOREC function code does not specify enough arguments.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40828
FRM-40828:  CALL or CALLQRY with invalid variable reference.

Cause:	Application design error.  A CALL or CALLQRY function code contains an invalid variable reference.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-40829
FRM-40829:  Not enough arguments to EDITFIELD function.

Cause:	Application design error.  An EDITFIELD function code does not specify enough arguments.

Action:	Correct the statement.

Level:	No message suppression level.

Type:	Error


FRM-40830
FRM-40830:  Not enough arguments to DISPLAYPAGE function.

Cause:	Application design error.  A DISPLAYPAGE function code does not specify enough arguments.

Action:	Correct the statement.

Level:	No message suppression level.

Type:	Error


FRM-40831
FRM-40831:  Truncation occurred: value too long for field %s.

Cause:	Application design error.  A trigger, query, or user exit read a value into an item that is not long enough to hold the entire value.  The item truncated the value.

Action:	Increase the target item's item length to avoid truncation.

Level:	15

Type:	Error


FRM-40900
FRM-40900:  Unable to allocate record buffer.  Clear form to continue.

Cause:	Failed attempt to allocate memory for a fetched or new record.  The remaining records that are queried are temporarily buffered on disk.  This is an indication that no more temporary files can be written to the disk.

Action:	Clear form and then attempt to continue.  You may have to exit the form and then re-open. Also, make sure there is enough disk space and that you have write privileges to the disk drive and directory.

Level:	>25

Type:	Error


FRM-40901
FRM-40901:  Note: not enough memory to remember all or part of this query.

Cause:	Internal error.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40902
FRM-40902:  SQL statement too large.

Cause:	Application design error.  The form's design includes a SQL command that is more than 2048 characters long.

Action:	Shorten the SQL command.

Level:	>25

Type:	Error


FRM-40903
FRM-40903:  Cannot create output file.

Cause:	You pressed [Print Screen], but screen contents could not be written to a file because of one of the following:

1. You have entered an illegal file name.

2. The operating system does not give you authority to create files.

3. The necessary disk or directory space is not available.

Action:	Check the file name you have entered and correct it if necessary.  If you need additional help, contact your DBA.

Level:	>25

Type:	Error


FRM-40904
FRM-40904:  Program error: unknown operation to be performed on record.

Cause:	Internal error.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40905
FRM-40905:  Unable to buffer more records on disk.

Cause:	Internal error.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40906
FRM-40906:  FATAL ERROR: cannot write a buffered record to disk.

Cause:	Failure while trying to write a buffered record to the disk.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40907
FRM-40907:  FATAL ERROR: cannot read a buffered record from disk.

Cause:	Failure while trying to read a buffered record from the disk.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40908
FRM-40908:  RAM Internal Error: %s

Cause:	An internal error occurred within the form's internal record manager.  Possible causes include:

1. Unable to open the disk buffer file.

2. Read or write error to the disk buffer file.

3. Out of memory.

Action:	Contact your DBA.

Level:	>20

Type:	Error


FRM-40909
FRM-40909:  Internal Error: unknown error %d.

Cause:	Internal error.  Attempted to issue an unknown error message.

Action:	Contact an Oracle support representative.

Level:	>25

Type:	Error


FRM-40910
FRM-40910:  Internal Error: while executing PL/SQL trigger or procedure.

Cause:	An internal error occurred during PL/SQL trigger or procedure as a result of a generation error or file corruption.

Action:	Recompile your form.  Contact an Oracle support representative.

Level:	>25

Type:	Error


FRM-40911
FRM-40911:  Record not created due to sequence number generation error.

Cause:	Internal error.  Either the sequence number object does not exist, or the designer does not have privileges for the sequence number object, or some other fatal database error occurred.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40912
FRM-40912:  WHEN-NEW-RECORD trigger failed.  Record not created.

Cause:	A runtime error occurred in a When-New-Record trigger that caused the trigger to fail. No new record was created.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-40913
FRM-40913:  List of Values maximum exceeded.  Some values are not displayed.

Cause:	Application design error.  Unable to return all the records in the current list of values; the number exceeds the maximum limit.

Action:	Specify no more than 32,767 records to be returned in a list of values.

Level:	>25

Type:	Error


FRM-40914
FRM-40914:  Memory allocation error: unable to complete transaction.

Cause:	Internal error.

Action:	Contact your DBA or an Oracle support representative.

Level:	>25

Type:	Error


FRM-40915
FRM-40915:  Memory allocation error: unable to execute trigger %s.

Cause:	Internal error.

Action:	Contact your DBA or an Oracle support representative.

Level:	>25

Type:	Error


FRM-40916
FRM-40916:  Memory allocation error: unable to execute query.

Cause:	Internal error.

Action:	Contact your DBA or an Oracle support representative.

Level:	>25

Type:	Error


FRM-40917
FRM-40917:  Memory allocation error: unable to lock record.

Cause:	Internal error.

Action:	Contact your DBA or an Oracle support representative.

Level:	>25

Type:	Error


FRM-40918
FRM-40918:  Internal error: unable to initialize Toolkit.

Cause:	Something in your environment or application has prevented Form Builder from initializing the Oracle Toolkit.

Action:	Make certain that Form Builder has been installed properly, your environment contains all of the necessary resource files, and all system dependent guidelines have been followed.

Level:	>25

Type:	Error


FRM-40919
FRM-40919:  Internal SQL statement execution error: %d.

Cause:	Error in the SQL statement Form Builder has tried to execute.

Action:	Check the last SQL statement.

Level:	25

Type:	Error


FRM-40920
FRM-40920:  Unable to create view: low on system resources.

Cause:	Something in your environment or application has prevented view creation.

Action:	Contact your DBA or an Oracle support representative.

Level:	99

Type:	Error


FRM-40921
FRM-40921:  Could not create item: %s.

Cause:	Something in your environment or application has prevented item creation.

Action:	Contact your DBA or an Oracle support representative.

Level:	99

Type:	Error


FRM-40922
FRM-40922:  An OLE error occurred: 0x%x.

Cause:	A built-in called an OLE or OLE-related function which failed.

Action:	You need to lookup the error number in an OLE manual for further details.

Level:	99

Type:	Error


FRM-40923
FRM-40923:  OLE is not supported on this platform.

Cause:	A built-in that required OLE support was called, and your platform does not support OLE.

Action:	Don't call OLE-related built-ins on platforms that don't support OLE.

Level:	99

Type:	Error


FRM-40924
FRM-40924:  Invalid argument index specified.

Cause:	An attempt was made to retrieve a value from the OLE-argument stack whose index was out of bounds for the size of the current OLE-argument stack

Action:	Argument indices range from 1 to the number specified in the last call to FORMS_OLE.InitArgs()

Level:	99

Type:	Error


FRM-40925
FRM-40925:  No space initialized in OleArg for argument.

Cause:	An attempt was made to store too many arguments into the initialized OLE-argument stack.

Action:	Make sure you specify enough space in your call to FORMS_OLE.InitArgs().

Level:	99

Type:	Error


FRM-40926
FRM-40926:  OLE Object is NULL.

Cause:	You cannot operate on a NULL OLE object.

Action:	Do not attempt to call FORMS_OLE built-ins with NULL OLE-objects.

Level:	99

Type:	Error


FRM-40927
FRM-40927:  Variant is not an array.

Cause:	An attempt was made to access a variant as if it contained an array, and it did not.

Action:	You can call FORMS_OLE.Get_Dims() to ensure that you have a variant with an array.  For arrays, the return value for the function is greater than or equal to 1.

Level:	99

Type:	Error


FRM-40928
FRM-40928:  Too many array indices specified.

Cause:	An attempt was made to access a variant that holds an array, but too many array indices were specified.

Action:	You must use the correct number of array indices, the same number as returned by FORMS_OLE.GET_Dims().

Level:	99

Type:	Error


FRM-40929
FRM-40929:  Too few array indices specified.

Cause:	An attempt was made to access a variant that holds an array, but too few array indices were specified.

Action:	You must use the correct number of array indices, the same number as returned by FORMS_OLE.GET_Dims().

Level:	99

Type:	Error


FRM-40930
FRM-40930:  Array index was non-numeric.

Cause:	An attempt was made to access a variant that holds an array, but the supplied array indices were non-numeric and not either ROW or COLUMN.

Action:	The only valid array indices are numbers, which should be separated by columns.  If you're fetching into a table from a variant, ROW and COLUMN can be used as placeholders for the row and column iterators during table construction.

Level:	99

Type:	Error


FRM-40931
FRM-40931:  Cannot populate table because datatype is unsupported.

Cause:	An attempt to populate a table failed because one of its columns used an unsupported datatype.

Action:	Restrict your column types to integers, numbers, strings, and dates.

Level:	99

Type:	Error


FRM-40932
FRM-40932:  Cannot populate variant because table's datatype is unsupported.

Cause:	An attempt to populate a variant failed because one of the source table's columns used an unsupported datatype.

Action:	Restrict your column types to integers, numbers, strings, and dates.

Level:	99

Type:	Error


FRM-40933
FRM-40933:  Cannot populate table because datatype is incorrect.

Cause:	An attempt to populate a table failed because the block's datatype did not match the table's datatype.

Action:	The table datatype must match the datatypes of the block's columns that are being retrieved.

Level:	99

Type:	Error


FRM-40934
FRM-40934:  Cannot populate table because records are out of bounds.

Cause:	An attempt to populate a table failed because an illegal start or end record was specified.

Action:	start_rec and end_rec parameters must fall between 1 and the number of retrievable records.  end_rec may also be ALL_RECORDS.

Level:	99

Type:	Error


FRM-40935
FRM-40935:  Object does not exist locally.

Cause:	An attempt to release an object failed because the 'kill_persistent' parameter was set to FALSE, and no local object existed to release.

Action:	Never release objects you don't own.

Level:	10

Type:	Error


FRM-41000
FRM-41000:  This function is not currently available.

Cause:	You pressed an undefined function key.

Action:	Press [Show Keys] to determine which function key you should have pressed.

Level:	5

Type:	Error


FRM-41001
FRM-41001:  This function is not allowed on this device.

Cause:	You tried to execute the Insert/Replace function.

Action:	No action is necessary.

Level:	5

Type:	Error


FRM-41002
FRM-41002:  Please make a valid selection.

Cause:	You entered an invalid selection number on the block menu; that block does not exist in this form.

Action:	Select an existing block.

Level:	10

Type:	Error


FRM-41003
FRM-41003:  This function cannot be performed here.

Cause:	You tried to perform a function that references a table, but current block does not correspond to any table.

Action:	No action is necessary.  You cannot perform the requested function on this block.

Level:	10

Type:	Error


FRM-41004
FRM-41004:  This function is not allowed in this mode.

Cause:	You pressed a function key that does not work in this mode.

Action:	No action is necessary.

Level:	10

Type:	Error


FRM-41005
FRM-41005:  Internal Error: function key not implemented.

Cause:	You pressed a disabled function key.

Action:	No action is necessary.  You cannot use the function key in the current context unless the form's definition is modified.

Level:	>25

Type:	Error


FRM-41006
FRM-41006:  Cannot find Forms Runtime command.

Cause:	You pressed a function key that has not been defined for your keyboard map.

Level:	>25

Type:	Error


FRM-41007
FRM-41007:  Cursor not in a valid item.  Function key was ignored.

Cause:	You were not in a valid item when you pressed the function key.

Action:	Position the cursor inside the item and press the function key again.

Level:	10

Type:	Error


FRM-41008
FRM-41008:  Undefined function key.  Press %s for list of valid keys.

Cause:	You pressed an undefined function key.

Action:	Press [Show Keys] to determine which function key you should have pressed.

Level:	>25

Type:	Error


FRM-41009
FRM-41009:  Function key not allowed.  Press %s for list of valid keys.

Cause:	You pressed a function key that is not allowed in this environment.

Action:	Press [Show Keys] to determine which function key you should have pressed.

Level:	>25

Type:	Error


FRM-41010
FRM-41010:  Cannot set attribute of the current item.

Cause:	Application design error.  A SET_ITEM statement tried to turn off the Input Allowed property for the current item.

Action:	Eliminate the statement or rewrite the trigger.

Level:	>25

Type:	Error


FRM-41011
FRM-41011:  Undefined attribute.

Cause:	Application design error.  A DISPLAY_ITEM or DISPLAY_PAGE statement tried to set an undefined attribute, or a SET_ITEM_PROPERTY statement tried to set an undefined property.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-41012
FRM-41012:  Undefined item or variable reference.

Cause:	Application design error.  A NAME_IN statement tried to reference a nonexistent item or variable.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-41013
FRM-41013:  Undefined attribute specified for item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure specifies an undefined parameter.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-41014
FRM-41014:  Cannot set attribute of null canvas item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to change some property of a NULL canvas item.

Action:	Move the item to a non-0 page.

Level:	>25

Type:	Error


FRM-41015
FRM-41015:  Cannot set ENTERABLE attribute of the current item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to change the Input Allowed property of the current item.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-41016
FRM-41016:  Cannot set DISPLAYED attribute of the current item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to change the Displayed property of the current item.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-41017
FRM-41017:  Cannot set UPDATE ALLOWED attribute of non-enabled item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to turn on the Update Allowed property of a non-enterable item.

Action:	To turn on the Update Allowed property of an item you must also turn on the Input Allowed property of the item.

Level:	>25

Type:	Error


FRM-41018
FRM-41018:  Cannot set UPDATE_NULL attribute of non-enabled item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to turn on the Update if Null property of a non-enterable item.

Action:	To turn on the Update if Null property of an item you must also turn on the Input Allowed property of the item.

Level:	>25

Type:	Error


FRM-41019
FRM-41019:  Cannot set REQUIRED attribute of non-enabled item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to turn on the Required property of a non-enterable item.

Action:	To turn on the Required property of an item you must also turn on the Input Allowed property of the item.

Level:	>25

Type:	Error


FRM-41020
FRM-41020:  Cannot set ENTERABLE attribute of non-displayed item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to turn on the Input Allowed property of a non-displayed item.

Action:	To turn on the Input Allowed property of an item you must also turn on the Displayed property of the item.

Level:	>25

Type:	Error


FRM-41021
FRM-41021:  Cannot set QUERYABLE attribute of non-displayed item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to turn on the Query Allowed property of a non-displayed item.

Action:	To turn on the Query Allowed property of an item you must also turn on the Displayed property of the item.

Level:	>25

Type:	Error


FRM-41022
FRM-41022:  Cannot set REQUIRED attribute of non-updateable item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to turn on the Required property of a non-updateable item.

Action:	To turn on the Required property of an item you must also turn on either the Update Allowed property or the Update if Null property of the item.

Level:	>25

Type:	Error


FRM-41023
FRM-41023:  Cannot set UPDATE ALLOWED attribute of secure item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to change the Update Allowed property of a database item which the user does not have permission to update.

Action:	Either correct the SET_ITEM statement or grant update permission on the column to the user.

Level:	>25

Type:	Error


FRM-41024
FRM-41024:  Cannot set UPDATE_NULL attribute of secure item %s.%s.

Cause:	Application design error.  A SET_ITEM packaged procedure tried to change the Update if Null property of a database item which the user does not have permission to update.

Action:	Either correct the SET_ITEM statement or grant update permission on the column to the user.

Level:	>25

Type:	Error


FRM-41025
FRM-41025:  Page number %d does not exist.

Cause:	Application design error.  Attempted an operation on a non-existent page.

Action:	Check arguments to page related built-ins.

Level:	>25

Type:	Error


FRM-41026
FRM-41026:  Field does not understand operation.

Cause:	You attempted to perform an operation that is invalid for the given item type.

Action:	Do not attempt to perform the operation on an item to which the operation cannot be applied.


FRM-41027
FRM-41027:  Primary key must be defined for this block.

Cause:	There are no primary key items in the block and one of the following has happ

1. You attempted to set Key_Mode of primary key option on for the block.

2. The Key_Mode is set to Automatic and the datasource to which your are connected does not support UNIQUE key mode.

Action:	Specify one or more primary key items on the block.

Level:	>25

Type:	Error


FRM-41028
FRM-41028:  Invalid property.

Cause:	You passed an invalid property constant to a Get or Set property built-in.

Action:	Verify arguments.

Level:	>25

Type:	Error


FRM-41029
FRM-41029:  Invalid parameter.

Cause:	You attempted to set a form, block, item, or record property to an invalid value.

Action:	Verify arguments to SET_FORM_PROPERTY, SET_BLOCK_PROPERTY, SET_ITEM_PROPERTY, or SET_RECORD_PROPERTY.

Level:	>25

Type:	Error


FRM-41030
FRM-41030:  Cannot reset ITEM_LENGTH of item %s.%s.

Cause:	Application design error.  Attempted to change the length of a fixed length item.

Action:	Statically declare the item to be of the maximum necessary length or change item type.

Level:	>25

Type:	Error


FRM-41031
FRM-41031:  Cannot reset ITEM_LENGTH greater than the allocated buffer.

Cause:	Application design error.  Tried to reset ITEM_LENGTH greater than the allocated buffer.

Action:	Increase item length in the form definition.

Level:	>25

Type:	Error


FRM-41032
FRM-41032:  Cannot set ENABLED attribute of current item %s.%s.

Cause:	A call to SET_ITEM_PROPERTY attempted to set the Enabled attribute of the current item.

Action:	Either correct the call to SET_ITEM_PROPERTY or navigate to another item before setting the Enabled attribute.

Level:	>25

Type:	Error


FRM-41033
FRM-41033:  Cannot set ENABLED attribute of non-displayed item %s.%s.

Cause:	A call to SET_ITEM_PROPERTY attempted to set the Enabled attribute of a non-displayed item.

Action:	First navigate to the item, then set the Enabled attribute with a call to SET_ITEM_PROPERTY.

Level:	>25

Type:	Error


FRM-41034
FRM-41034:  Cannot set NAVIGABLE attribute of non-displayed item %s.%s.

Cause:	A call to SET_ITEM_PROPERTY attempted to set the Navigable attribute of a non-displayed item.

Action:	First navigate to the item, then set the Navigable attribute with a call to SET_ITEM_PROPERTY.

Level:	>25

Type:	Error


FRM-41035
FRM-41035:  Cannot set NAVIGABLE attribute of non-enabled item %s.%s.

Cause:	A call to SET_ITEM_PROPERTY attempted to set the Navigable attribute of a non-enabled item.

Action:	First set the Enabled attribute of the item with a call to SET_ITEM_PROPERTY.  Then set the Navigable property of the item with another call to SET_ITEM_PROPERTY.

Level:	99

Type:	Error


FRM-41036
FRM-41036:  Cannot modify a checkbox that does not allow querying.

Cause:	You attempted to modify a check box that does not allow querying.

Action:	First set the Query Allowed property to True, then the end user may shift and click the check box to enable or disable the item.

Level:	99

Type:	Error


FRM-41037
FRM-41037:  Cannot modify a radio group that does not allow querying.

Cause:	You attempted to modify a radio group that does not allow querying.

Action:	First set the Enabled property to True with a call to SET_RADIO_BUTTON_PROPERTY.

Level:	>25

Type:	Error


FRM-41038
FRM-41038:  Item %s is not a checkbox.

Cause:	A call to CHECKBOX_CHECKED was made to an item which was not a check box.

Action:	Correct the call to CHECKBOX_CHECKED.

Level:	>25

Type:	Error


FRM-41039
FRM-41039:  Invalid Alert ID %d.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_ALERT will be performed.

Level:	>25

Type:	Error


FRM-41040
FRM-41040:  Cannot find radio button: %s.

Cause:	An invalid ID or name was passed to a built-in subprogram.

Action:	Check the name or ID that you entered and try again.

Level:	>25

Type:	Error


FRM-41041
FRM-41041:  Cannot find form module: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_FORM will be performed.

Level:	>25

Type:	Error


FRM-41042
FRM-41042:  No such property for Set_Item_Property.

Cause:	You attempted to set an invalid item property.

Action:	Check the documentation for setting item properties and try again.

Level:	>25

Type:	Error


FRM-41043
FRM-41043:  Cannot find timer: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_TIMER will be performed.

Level:	>25

Type:	Error


FRM-41044
FRM-41044:  Error deleting timer %s

Cause:	An error occurred while executing a DELETE_TIMER built-in.

Action:	Verify that your timer has been created correctly.

Level:	>25

Type:	Error


FRM-41045
FRM-41045:  Cannot find item: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a valid item name/ID was passed to the built-in.

Level:	>25

Type:	Error


FRM-41046
FRM-41046:  Invalid parameter used for Set_Item_Property.

Cause:	An invalid parameter was passed to SET_ITEM_PROPERTY.

Action:	Verify the valid parameters for SET_ITEM_PROPERTY and try again.

Level:	>25

Type:	Error


FRM-41047
FRM-41047:  Cannot navigate out of current block in enter-query mode.

Cause:	An illegal attempt to navigate out of the current block when in Enter Query mode.

Action:	Perform operation before entering query mode.

Level:	>25

Type:	Error


FRM-41048
FRM-41048:  Procedure %s is not valid in a %s trigger.

Cause:	The indicated procedure is not valid when called from the indicated trigger.  The procedure may be a restricted procedure, which cannot be called from any trigger that fires during navigation.

Action:	Correct the invalid trigger.

Level:	20

Type:	Error


FRM-41049
FRM-41049:  You cannot delete this record.

Cause:	You attempted to delete a record on a block that does not allow deletes.

Action:	Do not attempt to delete records in this block until you have set the Delete Allowed block property to True.

Level:	>20

Type:	Error


FRM-41050
FRM-41050:  You cannot update this record.

Cause:	You attempted to update a record on a block that does not allow updates.

Action:	Do not attempt to update records in this block until you have set the Update Allowed block property to True.

Level:	20

Type:	Error


FRM-41051
FRM-41051:  You cannot create records here.

Cause:	You attempted to create records on a block that does not allow inserts.

Action:	Do not attempt to create and insert new records into this block until you have set the Insert Allowed block property to True.

Level:	20

Type:	Error


FRM-41052
FRM-41052:  Cannot find Window: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_WINDOW will be performed.

Level:	20

Type:	Error


FRM-41053
FRM-41053:  Cannot find Canvas: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_CANVAS will be performed.

Level:	20

Type:	Error


FRM-41054
FRM-41054:  No such property for Get_Record_Property.

Cause:	You attempted to get a non-existent record property.

Action:	Verify call to GET_RECORD_PROPERTY for valid property.

Level:	20

Type:	Error


FRM-41055
FRM-41055:  No such property for Set_Record_Property.

Cause:	You attempted to set a non-existent record property.

Action:	Verify call to SET_RECORD_PROPERTY for valid property.

Level:	20

Type:	Error


FRM-41056
FRM-41056:  Cannot find Block: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_BLOCK will be performed.

Level:	>25

Type:	Error


FRM-41057
FRM-41057:  No such property for Set_View_Property.

Cause:	You attempted to set a non-existent view property.

Action:	Verify call to SET_VIEW_PROPERTY for valid property.

Level:	20

Type:	Error


FRM-41058
FRM-41058:  No such property for Get_Item_Property.

Cause:	You attempted to get a non-existent item property.

Action:	Verify call to GET_ITEM_PROPERTY for valid property.

Level:	20

Type:	Error


FRM-41059
FRM-41059:  No such property for Set_Canvas_Property.

Cause:	You attempted to set a non-existent canvas property.

Action:	Verify call to SET_CANVAS_PROPERTY for valid property.

Level:	20

Type:	Error


FRM-41060
FRM-41060:  Cannot disable Primary Key property of only key item.

Cause:	You attempted to turn off the Primary Key property on the last primary key item on a block with one of the following:

1. The Primary Key property.

2. Key mode of the primary key.

3. The database to which you are connected does not support UNIQUE key mode.

Action:	Disable the block properties first.

Level:	20

Type:	Error


FRM-41061
FRM-41061:  No such property for Get_Window_Property.

Cause:	You attempted to get a non-existent window property.

Action:	Verify call to GET_WINDOW_PROPERTY for valid property.

Level:	99

Type:	Error


FRM-41062
FRM-41062:  Cannot find Editor: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_EDITOR will be performed.

Level:	20

Type:	Error


FRM-41063
FRM-41063:  Cannot create Editor.

Cause:	Not enough memory available for Forms Runtime.

Action:	Try calling SHOW_EDITOR again after closing some of your windows.

Level:	20

Type:	Error


FRM-41064
FRM-41064:  Cannot create Timer %s: illegal identifier name.

Cause:	Illegal identifier name.

Action:	Check legal syntax for naming timers.

Level:	99

Type:	Error


FRM-41065
FRM-41065:  Cannot find Menu: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_MENU will be performed.

Level:	20

Type:	Error


FRM-41066
FRM-41066:  No such property for Get_Form_Property.

Cause:	You attempted to get a non-existent form property.

Action:	Verify call to GET_FORM_PROPERTY for valid property.

Level:	20

Type:	Error


FRM-41067
FRM-41067:  Cannot find Menu Item: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_MENU_ITEM will be performed.

Level:	20

Type:	Error


FRM-41068
FRM-41068:  Error in Set_Menu_Item_Property.

Cause:	Invalid call to SET_MENU_ITEM_PROPERTY.

Action:	Verify valid parameters and try again.

Level:	20

Type:	Error


FRM-41069
FRM-41069:  Error in Get_Menu_Item_Property.

Cause:	Invalid call to GET_MENU_ITEM_PROPERTY.

Action:	Verify valid parameters and try again.

Level:	20

Type:	Error


FRM-41070
FRM-41070:  Unknown property for Set_Menu_Item_Property.

Cause:	You attempted to set a non-existent menu item property.

Action:	Verify call to SET_MENU_ITEM_PROPERTY for valid property.

Level:	20

Type:	Error


FRM-41071
FRM-41071:  Unknown property for Get_Menu_Item_Property.

Cause:	You attempted to get a non-existent menu item property.

Action:	Verify call to GET_MENU_ITEM_PROPERTY for valid property.

Level:	20

Type:	Error


FRM-41072
FRM-41072:  Cannot create Group %s

Cause:	Caused by one of the following

1.  Duplicate column names in SQL statement.

2.  Invalid record group name.

3.  Query is invalid.

Action:	Check the group name and/or correct the SQL statement.

Level:	20

Type:	Error


FRM-41073
FRM-41073:  Cannot find Group: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_GROUP will be performed.

Level:	20

Type:	Error


FRM-41074
FRM-41074:  Cannot find Group or Column: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_GROUP or FIND_COLUMN will be performed.

Level:	20

Type:	Error


FRM-41075
FRM-41075:  Error deleting Group.

Cause:	The record group name or ID specified in the call to DELETE_GROUP is invalid, or the record group was not dynamically created.

Action:	Check the record group name or ID, and make sure that the specified record group was dynamically created.

Level:	20

Type:	Error


FRM-41076
FRM-41076:  Error populating Group.

Cause:	Query failed due to an invalid column or table name, or the query and group column structure do not match.

Action:	Check the SQL SELECT statement in your call to POPULATE_GROUP_WITH_QUERY.

Level:	20

Type:	Error


FRM-41077
FRM-41077:  Error deleting Group Row(s).

Cause:	DELETE_GROUP_ROW cannot be used to delete records from a static record group, or you specified an invalid row number.

Action:	Correct the call to DELETE_GROUP_ROW.

Level:	20

Type:	Error


FRM-41078
FRM-41078:  Error resetting Group selection.

Cause:	Record group name or ID specified is invalid.

Action:	Check the record group name or ID and try again.

Level:	20

Type:	Error


FRM-41079
FRM-41079:  Error adding Group column.

Cause:	Caused by one of the following:

1. You cannot add columns to a group that already has rows.

2.  The width of CHAR_COLUMN-typed columns cannot be less than the width of the corresponding database column.

3.  You entered the name of a nonexistent or invalid record group.

4.  You entered the name of a nonexistent or invalid column.

5.  You entered a column type other than CHAR, NUMBER, or DATE.

Action:	You can only add columns to a group after it is created with a call to CREATE_GROUP.  If the group already has rows, delete the rows with DELETE_GROUP_ROW, then add the column.

Level:	20

Type:	Error


FRM-41080
FRM-41080:  Error adding Group row.

Cause:	Caused by one of the following:

1.  You attempted to add rows to a group that is nonexistent or has no columns.

2.  You entered the name of a nonexistent record group.

3.  You provided a row number that is out of range or invalid.

Action:	Create the group and add columns first.  Check the call to ADD_GROUP_ROW to make sure that the record group name and row number are valid.

Level:	20

Type:	Error


FRM-41081
FRM-41081:  Cannot move Item: invalid position.

Cause:	You attempted to move the item to an invalid position on the canvas.

Action:	Make sure the coordinates you chose in your call to SET_ITEM_PROPERTY are valid.

Level:	99

Type:	Error


FRM-41082
FRM-41082:  Cannot resize item: position of item places it off of canvas.

Cause:	The height and/or width you specified in your call to SET_ITEM_PROPERTY is invalid, or the height and/or width you specified causes the item to extend off of the canvas.

Action:	Correct the call to SET_ITEM_PROPERTY.

Level:	99

Type:	Error


FRM-41083
FRM-41083:  No such property for Set_Form_Property

Cause:	You attempted to set a nonexistent form property.

Action:	Verify call to SET_FORM_PROPERTY for valid property.

Level:	20

Type:	Error


FRM-41084
FRM-41084:  Error getting Group Cell.

Cause:	Invalid call to GET_GROUP_CHAR_CELL, GET_GROUP_DATE_CELL, OR GET_GROUP_NUMBER_CELL.

Action:	Make sure the column type is of CHAR, DATE, or NUMBER, respectively.  Check the validity of the row number and column name specified.

Level:	20

Type:	Error


FRM-41085
FRM-41085:  Error getting Group Row count.

Cause:	Invalid call to GET_GROUP_ROW_COUNT.

Action:	Check the record group name and try again.

Level:	20

Type:	Error


FRM-41086
FRM-41086:  Error getting Group selection count.

Cause:	You specified an invalid record group name.  Invalid call to GET_GROUP_SELECTION_COUNT.

Action:	Correct the call to GET_GROUP_SELECTION.

Level:	20

Type:	Error


FRM-41087
FRM-41087:  Error getting Group selection.

Cause:	You specified an invalid record group name or selection number.  Invalid call to GET_GROUP_SELECTION.

Action:	Correct the call to GET_GROUP_SELECTION.

Level:	20

Type:	Error


FRM-41088
FRM-41088:  Cannot set Group selection.

Cause:	You specified an invalid record group name, ID, or row number.

Action:	Correct the call to SET_GROUP_SELECTION.

Level:	20

Type:	Error


FRM-41089
FRM-41089:  Cannot move View: invalid position.

Cause:	The x, y pair specified in the call to SET_VIEW_PROPERTY is invalid.

Action:	Correct the call to SET_VIEW_PROPERTY by making sure that the position specified by your coordinates is on the canvas.

Level:	99

Type:	Error


FRM-41090
FRM-41090:  Invalid item type for go_item: %s.

Cause:	You cannot navigate to the item.

Action:	Check to make sure the item is a navigable item.

Level:	20

Type:	Error


FRM-41091
FRM-41091:  Cannot find LOV: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_LOV will be performed.

Level:	20

Type:	Error


FRM-41092
FRM-41092:  No records in block %s.

Cause:	You attempted to place a value into an item on a block that has no records.

Action:	Put records in the block first.

Level:	20

Type:	Error


FRM-41093
FRM-41093:  Error setting item attribute:  %s.

Cause:	You specified Lock Record and the item was not a text item, or you specify Case Insensitive Query and the data type was not ALPHA or CHAR.

Action:	In the case of Lock Record, make sure that the item is a text item.  When specifying Case Insensitive Query, make sure that the data type is ALPHA or CHAR.

Level:	20

Type:	Error


FRM-41094
FRM-41094:  No such property for Get_View_Property.

Cause:	You attempted to get a non-existent view property.

Action:	Verify call to GET_VIEW_PROPERTY for valid property.

Level:	99

Type:	Error


FRM-41095
FRM-41095:  No such property for Get_Canvas_Property.

Cause:	You attempted to get a non-existent canvas property.

Action:	Verify call to GET_CANVAS_PROPERTY for valid property.

Level:	99

Type:	Error


FRM-41096
FRM-41096:  Cannot resize View: invalid size.

Cause:	The x, y coordinates place the view off the canvas.

Action:	Choose another x, y pair.

Level:	99

Type:	Error


FRM-41097
FRM-41097:  Cannot resize Canvas: invalid size.

Cause:	The x, y coordinates place the view off the window.

Action:	Choose another x, y pair.

Level:	99

Type:	Error


FRM-41098
FRM-41098:  Cannot modify Display Position of a content view.

Cause:	The display position property applies to a stacked canvas-view only.

Action:	Correct the call to SET_VIEW_PROPERTY.

Level:	99

Type:	Error


FRM-41099
FRM-41099:  Cannot modify Size of a content view.

Cause:	The size of a content view is dependent on window size.  Only stacked view sizes may be modified using SET_VIEW_PROPERTY.

Action:	Correct the call to SET_VIEW_PROPERTY.

Level:	99

Type:	Error


FRM-41100
FRM-41100:  Cannot find relation %s.

Cause:	You attempted to get, set, or find using an invalid relation.

Action:	Check call to built-in for correct arguments.

Level:	>25

Type:	Error


FRM-41101
FRM-41101:  No such property for Get_Relation_Property.

Cause:	You attempted to get a non-existent relation property.

Action:	Verify call to GET_RELATION_PROPERTY for valid property.

Level:	99

Type:	Error


FRM-41102
FRM-41102:  No such property for Set_Relation_Property.

Cause:	You attempted to set a non-existent relation property.

Action:	Verify call to SET_RELATION_PROPERTY for valid property.

Level:	99

Type:	Error


FRM-41103
FRM-41103:  No such property value for Set_Relation_Property.

Cause:	Application design error.  Improper relation property value passed to SET_RELATION_PROPERTY built-in.

Action:	Correct call to SET_RELATION_PROPERTY built-in and retry.

Level:	99

Type:	Error


FRM-41104
FRM-41104:  Cannot find Relation: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_RELATION will be performed.

Level:	20

Type:	Error


FRM-41105
FRM-41105:  You cannot query records without a saved parent record.

Cause:	You attempted to query detail records without first creating a master record.

Action:	Create a master record, and then query the detail records.


FRM-41106
FRM-41106:  You cannot create records without a parent record.

Cause:	You attempted to create new detail records without first creating a master record.

Action:	Create a master record, and then add the detail records.


FRM-41107
FRM-41107:  Master delete option for the relation is invalid.

Cause:	An invalid query data source type or an invalid DML data target type is specified for the detail block.

Action:	Verify that the detail block's query data source and the DML data targets are of type table.

Level:	20

Type:	Error


FRM-41200
FRM-41200:  Integration error: invalid product.

Cause:	Invalid product name specified in RUN_PRODUCT.

Action:	Check the RUN_PRODUCT parameters and try again.

Level:	99

Type:	Error


FRM-41201
FRM-41201:  Integration error: communication mode must be SYNCHRONOUS or ASYNCHRONOUS.

Cause:	Invalid communication mode specified in RUN_PRODUCT.

Action:	Check the RUN_PRODUCT parameters and try again.

Level:	20

Type:	Error


FRM-41202
FRM-41202:  Integration error: parameter list %s has no parameters.

Cause:	Parameter list has no arguments.

Action:	Check the specified parameter list for parameters.

Level:	20

Type:	Error


FRM-41203
FRM-41203:  Integration error: invalid parameter list ID.

Cause:	An invalid parameter list ID was passed.

Action:	Check the parameter list ID name and try again.

Level:	20

Type:	Error


FRM-41204
FRM-41204:  Integration error: memory allocation error.

Cause:	An internal error occurred.

Action:	Contact customer support.

Level:	20

Type:	Error


FRM-41205
FRM-41205:  Integration error: %s not a Chart Item

Cause:	The variable type specified for display is not of type Chart Item.

Action:	Specify a Chart Item for the display parameter.

Level:	20

Type:	Error


FRM-41206
FRM-41206:  Integration error: ambiguous item %s.

Cause:	Invalid item name; may be a duplicate.

Action:	Specify the item name with the block name.item name format.

Level:	20

Type:	Error


FRM-41207
FRM-41207:  Integration error: could not find item %s.

Cause:	The item name specified does not exist.

Action:	Check the name for accuracy and try again with the format block name.item name.

Level:	20

Type:	Error


FRM-41208
FRM-41208:  Integration error: execution mode must be BATCH or RUNTIME.

Cause:	Invalid execution mode specified in RUN_PRODUCT.

Action:	Specify either BATCH or RUNTIME for the execmode parameter.

Level:	20

Type:	Error


FRM-41209
FRM-41209:  Integration error: document location must be FILESYSTEM or DB.

Cause:	Invalid document location specified in RUN_PRODUCT.

Action:	Specify either FILESYSTEM or DB for the location parameter.

Level:	20

Type:	Error


FRM-41210
FRM-41210:  Integration error: Null Chart Item

Cause:	A null is specified for the chart item display.

Action:	Check the display item of the RUN_PRODUCT built-in and confirm that it is not null.

Level:	20

Type:	Error


FRM-41211
FRM-41211:  Integration error: SSL failure running another product.

Cause:	There is a problem detected when launching another product.

Action:	Check the RUN_PRODUCT built-in.

Level:	99

Type:	Error


FRM-41212
FRM-41212:  Integration error: invalid communication mode for data exchange

Cause:	User specified an asynchronous RUN_PRODUCT.

Action:	Change to a synchronous RUN_PRODUCT communication mode.

Level:	20

Type:	Error


FRM-41213
FRM-41213:  Unable to connect to the Report server %s.

Cause:	There is a problem connecting to the specified Report server.

Action:	Check the Report server and make sure it is up and running.

Level:	20

Type:	Error


FRM-41214
FRM-41214:  Unable to run report.

Cause:	The report server was unable to run the specified report.

Action:	Check the Report server and make sure it is up and running.

Level:	20

Type:	Error


FRM-41215
FRM-41215:  Invalid server name or jobid.

Cause:	There is a problem decoding the return value from the built-in run_report.

Action:	The return value from the built-in run_report should not be modified before being passed to another report built-in.

Level:	20

Type:	Error


FRM-41216
FRM-41216:  Unable to cancel job.

Cause:	There is a problem cancelling a report job.

Action:	Check the Report server and make sure that the specified job exists.

Level:	20

Type:	Error


FRM-41217
FRM-41217:  Unable to get report job status.

Cause:	There is a problem getting report status for a given report job.

Action:	Check the Report server and make sure that the specified job exists.

Level:	20

Type:	Error


FRM-41218
FRM-41218:  Unable to copy report output.

Cause:	There is a problem copying report output for a given report job.

Action:	Check the Report server and make sure that the specified output file exists.

Level:	20

Type:	Error


FRM-41219
FRM-41219:  Cannot find report: invalid ID.

Cause:	The user has specified an invalid report object name.

Action:	Check the form and make sure that the report object exists.

Level:	20

Type:	Error


FRM-41300
FRM-41300:  Invalid parameter used for Set_Radio_Button_Property.

Cause:	You specified a parameter that does not exist.

Action:	Check the list of legal parameters.

Level:	99

Type:	Error


FRM-41301
FRM-41301:  Invalid parameter used for Set_View_Property.

Cause:	You specified a parameter that does not exist.

Action:	Check the list of legal parameters.

Level:	99

Type:	Error


FRM-41302
FRM-41302:  Invalid parameter used for Set_Canvas_Property.

Cause:	You specified a parameter that does not exist.

Action:	Check the list of legal parameters.

Level:	99

Type:	Error


FRM-41303
FRM-41303:  No such property for Set_Window_Property.

Cause:	You specified a property that does not exist.

Action:	Check the list of legal properties.

Level:	99

Type:	Error


FRM-41304
FRM-41304:  No such property for Set_Block_Property.

Cause:	You specified a property that does not exist.

Action:	Check the list of legal properties.

Level:	99

Type:	Error


FRM-41305
FRM-41305:  No such property for Get_Block_Property.

Cause:	You specified a property that does not exist.

Action:	Check the list of legal properties.

Level:	99

Type:	Error


FRM-41306
FRM-41306:  Invalid parameter used for Set_Window_Property.

Cause:	You specified a parameter that is not valid.

Action:	Check the list of valid parameters.

Level:	99

Type:	Error


FRM-41307
FRM-41307:  Invalid parameter used for Set_Block_Property.

Cause:	You specified a parameter that is not valid.

Action:	Check the list of valid parameters.

Level:	99

Type:	Error


FRM-41308
FRM-41308:  Error unsetting Group selection.

Cause:	You tried to deselect a record or a subset of records that was not selected or is not in the record group.

Action:	Check the records that are expected in the group.

Level:	20

Type:	Error


FRM-41309
FRM-41309:  No such property for Get_Radio_Button_Property.

Cause:	You specified a property that is invalid.

Action:	Check the list of valid properties.

Level:	99

Type:	Error


FRM-41310
FRM-41310:  No such property for Set_Radio_Button_Property.

Cause:	You specified a property that is invalid.

Action:	Check the list of valid properties.

Level:	99

Type:	Error


FRM-41311
FRM-41311:  Invalid argument or argument ordering for %s.

Cause:	You supplied an incorrect argument list.

Action:	Check the list of valid arguments.

Level:	99

Type:	Error


FRM-41312
FRM-41312:  Must have at least one writable item in block.

Cause:	A block with the INSERT_ALLOWED or UPDATE_ALLOWED property set to True must have at least one writable item.  You attempted to make the only remaining base table item in the block not writable by setting either the DERIVED_COLUMN or QUERY_ONLY property to True.

Action:	Set INSERT_ALLOWED or UPDATE_ALLOWED to False for the block, rather than setting DERIVED_COLUMN or QUERY_ALLOWED to False for each item.

Level:	10

Type:	Informative


FRM-41313
FRM-41313:  No such property for Set_Alert_Property.

Cause:	An invalid property has been specified for SET_ALERT_PROPERTY.

Action:	Enter a valid alert property.

Level:	99

Type:	Error


FRM-41314
FRM-41314:  Cannot set Insert Allowed property of current item %s.%s

Cause:	You attempted to set the Insert Allowed property for a non-displayed item.

Action:	The Insert Allowed property is only valid on displayed items.  Make sure the item is displayed.

Level:	99

Type:	Error


FRM-41315
FRM-41315:  Cannot set Insert Allowed property of non-displayed item %s.%s

Cause:	You tried to set Insert Allowed property for a non-displayed item.

Action:	The Insert Allowed property is only valid on displayed items.  Make sure the item is displayed.

Level:	99

Type:	Error


FRM-41316
FRM-41316:  Cannot set Insert Allowed property of disabled item %s.%s

Cause:	You tried to set Insert Allowed property for a disabled item.

Action:	The Insert Allowed property is only valid on enabled items.  Make sure the item is enabled.

Level:	99

Type:	Error


FRM-41317
FRM-41317:  Item is not a radio button %s

Cause:	You tried to use a radio button built-in with an item that is not a radio button.

Action:	Make sure the item is a radio button.

Level:	99

Type:	Error


FRM-41318
FRM-41318:  Item %s is not a VBX item.

Cause:	You tried to use a VBX built-in with an item that is not a VBX item.

Action:	Make sure the item is a VBX item.

Level:	5

Type:	Informative


FRM-41319
FRM-41319:  Invalid property %s specified for VBX item %s.

Cause:	You tried to get or set an invalid property for the specified VBX item.

Action:	Make sure the property is valid for the specified VBX item.

Level:	99

Type:	Error


FRM-41320
FRM-41320:  Unable to get property %s for VBX item %s.

Cause:	Could not get the valid property for the VBX item.

Action:	Check the list of legal properties.

Level:	99

Type:	Error


FRM-41321
FRM-41321:  Unable to set property %s for VBX item %s.

Cause:	Could not set the valid property for the VBX item.

Action:	Check the list of legal properties.

Level:	99

Type:	Error


FRM-41322
FRM-41322:  Invalid event %s for VBX item %s.

Cause:	You tried to get or set an invalid event for the specified VBX item.

Action:	Make sure the event is valid for the specified VBX item.

Level:	99

Type:	Error


FRM-41323
FRM-41323:  Too many parameters for event %s for VBX item %s.

Cause:	You specified too many parameters for the event name for the VBX item.

Action:	Make sure there is a valid number of parameters for the event.

Level:	99

Type:	Error


FRM-41324
FRM-41324:  Too few parameters for event %s for VBX item %s.

Cause:	You specified too few parameters for the event name for the VBX item.

Action:	Make sure there is a valid number of parameters for the event.

Level:	99

Type:	Error


FRM-41325
FRM-41325:  VBX event parameter must be a string.

Cause:	The VBX event parameter is not a string.

Action:	Make sure the VBX event parameter is a string.

Level:	99

Type:	Error


FRM-41326
FRM-41326:  Failed to deliver event %s to VBX item %s.

Cause:	The VBX event failed.

Action:	Make sure the event is valid for the specified VBX item.

Level:	99

Type:	Error


FRM-41327
FRM-41327:  Failed to get default property for VBX item %s.

Cause:	The VBX.GET_VALUE_PROPERTY built-in failed.

Action:	Make sure an initial value is assigned to the VB Control Value property.

Level:	99

Type:	Error


FRM-41328
FRM-41328:  Failed to set default property for VBX item %s.

Cause:	The VBX.SET_VALUE_PROPERTY built-in failed.

Action:	Make sure you are setting a valid value property.

Level:	99

Type:	Error


FRM-41329
FRM-41329:  Item %s is not a List item.

Cause:	You tried to add a list element to an item that is not a list.

Action:	Make sure the item is a List item.

Level:	99

Type:	Error


FRM-41330
FRM-41330:  Could not insert list element into %s.

Cause:	You tried to insert an other values element when the block contained either queried or changed records.

Action:	For more information, refer to help for restrictions on  ADD_LIST_ELEMENT .

Level:	99

Type:	Error


FRM-41331
FRM-41331:  Could not delete element from %s.

Cause:	Caused by one of the following:

You tried to delete the other values element when the block contained either queried or changed records.

You tried to delete an element from a list that does not contain an other values element when the block contained either queried or changed records.

Action:	For more information, refer to help for restrictions on  CLEAR_LIST  and  DELETE_LIST_ELEMENT .

Level:	99

Type:	Error


FRM-41332
FRM-41332:  List element index out of range.

Cause:	Not enough memory.

Action:	Contact your DBA.

Level:	99

Type:	Error


FRM-41333
FRM-41333:  Cannot convert list element value.

Cause:	Could not resolve list element value to a string.

Action:	Make sure list element is a string.

Level:	99

Type:	Error


FRM-41334
FRM-41334:  Invalid record group for list population.

Cause:	You tried to populate a list from a record group that does not exist.

Action:	Make sure the record group exists.

Level:	99

Type:	Error


FRM-41335
FRM-41335:  Populate_List: invalid column type for column 1.

Cause:	You tried to populate a list from a record group that does not exist.

Action:	Make sure the record group exists.

Level:	99

Type:	Error


FRM-41336
FRM-41336:  Populate_List: invalid column type for column 2.

Cause:	The record group does not have a column of the same type.

Action:	Make sure record group has a column of the same type.

Level:	99

Type:	Error


FRM-41337
FRM-41337:  Cannot populate the list from record group.

Cause:	The record group is invalid or the list item does not satisfy the requirements for deleting and adding elements.

Action:	Make sure the record group is valid. For more information about deleting and adding list elements, refer to help for restrictions on  DELETE_LIST_ELEMENT  and  ADD_LIST_ELEMENT .

Level:	99

Type:	Error


FRM-41338
FRM-41338:  Cannot retrieve the list into record group.

Cause:	The record group is invalid.

Action:	Make sure the record group is valid.

Level:	99

Type:	Error


FRM-41339
FRM-41339:  Cannot clear the list.

Cause:	Not enough memory.

Action:	Contact your DBA.

Level:	99

Type:	Error


FRM-41340
FRM-41340:  No such property or value for Set_Application_Property.

Cause:	You specified an invalid property and/or an invalid value for a property.

Action:	Specify a valid property and/or a valid value.

Level:	99

Type:	Error


FRM-41341
FRM-41341:  Invalid cursor shape %s specified.

Cause:	There is a predefined set of cursor types, and an invalid cursor type was specified.

Action:	Specify a valid cursor type.

Level:	99

Type:	Error


FRM-41342
FRM-41342:  Invalid parameter %s specified for VBX event %s.

Cause:	You specified an invalid parameter for a VBX event.

Action:	Check the parameter type.

Level:	99

Type:	Error


FRM-41343
FRM-41343:  Item %s is not an OLE object.

Cause:	Invalid item passed to OLE built-in.

Action:	Specify a valid OLE item.

Level:	99

Type:	Error


FRM-41344
FRM-41344:  OLE object not defined for %s in the current record.

Cause:	An empty OLE container is defined.

Action:	Define an OLE object to reside in the OLE container.

Level:	20

Type:	Error


FRM-41345
FRM-41345:  Cannot find the verb %s for this server.

Cause:	You specified an invalid OLE verb.

Action:	Specify a valid OLE verb.

Level:	99

Type:	Error


FRM-41346
FRM-41346:  Cannot determine the verb count for OLE object %s.

Cause:	Could not communicate with OLE server.

Action:	Re-install the OLE server.

Level:	99

Type:	Error


FRM-41347
FRM-41347:  Invalid verb index for OLE object %s.

Cause:	You provided an index that is greater than the verb count.

Action:	Check the index value.

Level:	99

Type:	Error


FRM-41348
FRM-41348:  OLE server error:  %s.

Cause:	OLE server detects an error.

Action:	Try to resolve the error based on the message from the OLE server.

Level:	99

Type:	Error


FRM-41349
FRM-41349:  OLE object %s cannot execute verb; verb id %d

Cause:	OLE object does not recognize the verb.

Action:	Try to execute another verb.

Level:	99

Type:	Error


FRM-41350
FRM-41350:  OLE object is currently not displayed.

Cause:	You tried to close a server that is not running.

Action:	Ask if the server is active in a record that is not currently active.

Level:	99

Type:	Error


FRM-41351
FRM-41351:  Cannot navigate out of current form.

Cause:	You cannot navigate to an inactive form.

Action:	Check to make sure the form you are navigating to is active.

Level:	99

Type:	Error


FRM-41352
FRM-41352:  Failed to create a new session.

Cause:	You attempted to open a new form with a new session.

Action:	Check the database server.

Level:	99

Type:	Error


FRM-41353
FRM-41353:  Cannot start another call form.

Cause:	You went to a peer form and performed a call form.

Action:	Make sure you are not at a peer form when calling the form.

Level:	99

Type:	Error


FRM-41354
FRM-41354:  Cannot close form %s.

Cause:	Unsuccessful attempt to close a form.

Action:	Make sure the form is open.

Level:	99

Type:	Error


FRM-41355
FRM-41355:  Cannot navigate to form %s.

Cause:	You cannot navigate to an inactive form.

Action:	Check to make sure you are navigating to an active form.

Level:	99

Type:	Error


FRM-41356
FRM-41356:  Invalid method %s for VBX item %s.

Cause:	You specified an invalid method name for the VBX item.

Action:	Specify a valid method name for the VBX item.

Level:	99

Type:	Error


FRM-41357
FRM-41357:  Incorrect number of arguments to method %s for VBX item %s.

Cause:	You specified an incorrect number of arguments to the method for the VBX item.

Action:	Make sure the number of arguments is what the VBX item expects.

Level:	99

Type:	Error


FRM-41358
FRM-41358:  Method %s failed for VBX item %s.

Cause:	You specified an invalid method name for the VBX item.

Action:	Specify a valid method name for the VBX item.

Level:	5

Type:	Informative


FRM-41359
FRM-41359:  The Open_Form session feature is not enabled. Cannot create new session.

Cause:	You do not have the multiple sessioning feature enabled on the database.

Action:	The Open_Form session feature is only available for use against a database with multiple sessioning enabled.

Level:	99

Type:	Error


FRM-41360
FRM-41360:  Invalid value used in Set_Window_Property for window %s.

Cause:	You are using an invalid value when attempting to set a window property.

Action:	Specify a valid window property value.

Level:	99

Type:	Error


FRM-41361
FRM-41361:  Cannot navigate out of current form in Enter-Query mode.

Cause:	You are in Enter-Query mode and trying to navigate to another form when using Open Form.

Action:	Exit Enter-Query mode and try again.

Level:	10

Type:	Error


FRM-41362
FRM-41362:  No such property for Set_Alert_Button_Property.

Cause:	You specified an invalid property for Set_Alert_Button_Property.

Action:	Specify a valid property for Set_Alert_Button_Property.

Level:	99

Type:	Error


FRM-41363
FRM-41363:  No such property for Set_LOV_Column_Property.

Cause:	You specified an invalid property for Set_LOV_Column_Property.

Action:	Specify a valid property for Set_LOV_Column_Property.

Level:	99

Type:	Error


FRM-41364
FRM-41364:  Invalid column number specified for LOV %s.

Cause:	You specified an invalid column number for the LOV.

Action:	Specify a valid column number for the LOV.

Level:	99

Type:	Error


FRM-41365
FRM-41365:  No such property for Set_TabPage_Property.

Cause:	You specified an invalid property for Set_TabPage_Property.

Action:	Specify a valid property for Set_TabPage_Property.

Level:	99

Type:	Error


FRM-41366
FRM-41366:  No such property for Get_TabPage_Property.

Cause:	You specified an invalid property parameter.

Action:	Check the list of valid properties.

Level:	99

Type:	Error


FRM-41367
FRM-41367:  Cannot find TabPage: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to FIND_TABPAGE will be performed.

Level:	99

Type:	Error


FRM-41368
FRM-41368:  Invalid parameter used for Set_TabPage_Property.

Cause:	You specified a parameter that is not valid.

Action:	Check the list of valid parameters.

Level:	99

Type:	Error


FRM-41369
FRM-41369:  Cannot insert a second record into a single-record block.

Cause:	You (or the application) have attempted to insert a second record into a block whose SINGLE_RECORD property is TRUE.

Action:	Don't attempt to insert a record into such a block.

Level:	99

Type:	Error


FRM-41370
FRM-41370:  Cannot modify calculated item %s.%s.

Cause:	Application design error.  The application attempted to assign a value to a calculated item.

Action:	If the calculated item is a formula item, then its formula determines its value at all times.  It may be appropriate to modify the formula.  Or it may be appropriate to change the calculated item to a non-calculated control item whose value is set in various triggers.

Level:	99

Type:	Error


FRM-41371
FRM-41371:  Cannot set INSERT_ALLOWED property of calculated item %s.%s.

Cause:	Application design error.  A SET_ITEM_PROPERTY or SET_ITEM_INSTANCE_PROPERTY built-in attempted to set a calculated item's INSERT_ALLOWED property to TRUE.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-41372
FRM-41372:  Cannot set ITEM_IS_VALID property of calculated item %s.%s.

Cause:	Application design error.  A SET_ITEM_PROPERTY built-in attempted to set a calculated item's ITEM_IS_VALID property to FALSE.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-41373
FRM-41373:  Cannot set LOCK_RECORD property of calculated item %s.%s.

Cause:	Application design error.  A SET_ITEM_PROPERTY built-in attempted to set a calculated item's LOCK_RECORD property to TRUE.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-41374
FRM-41374:  Cannot set PRIMARY_KEY property of calculated item %s.%s.

Cause:	Application design error.  A SET_ITEM_PROPERTY built-in attempted to set a calculated item's PRIMARY_KEY property to TRUE.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-41375
FRM-41375:  Cannot set QUERYABLE property of calculated item %s.%s.

Cause:	Application design error.  A SET_ITEM_PROPERTY built-in attempted to set a calculated item's QUERYABLE property to TRUE.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-41376
FRM-41376:  Cannot set REQUIRED property of calculated item %s.%s.

Cause:	Application design error.  A SET_ITEM_PROPERTY or SET_ITEM_INSTANCE_PROPERTY built-in attempted to set a calculated item's REQUIRED property to TRUE.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-41377
FRM-41377:  Cannot set UPDATEABLE property of calculated item %s.%s.

Cause:	Application design error.  A SET_ITEM_PROPERTY or SET_ITEM_INSTANCE_PROPERTY built-in attempted to set a calculated item's UPDATEABLE property to TRUE.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-41378
FRM-41378:  Cannot set UPDATE_NULL property of calculated item %s.%s.

Cause:	Application design error.  A SET_ITEM_PROPERTY built-in attempted to set a calculated item's UPDATE_NULL property to TRUE.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-41379
FRM-41379:  Cannot recalculate non-formula item %s.%s.

Cause:	Application design error.  A RECALCULATE built-in specified an item which is not a formula item.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-41380
FRM-41380:  Cannot set the blocks query data source.

Cause:	The user attempt to change the block's data source dynamically has failed.

Action:	Check the form and make sure that the specified block is not a control block and the block status is new.

Level:	20

Type:	Error


FRM-41381
FRM-41381:  Cannot set the blocks DML data target source.

Cause:	The user attempt to change the block's DML data target dynamically has failed.

Action:	Check the form and make sure that the specified block is not a control block and the block status is new.

Level:	20

Type:	Error


FRM-41382
FRM-41382:  No such property for Get_Item_Instance_Property.

Cause:	Application design error.  A GET_ITEM_INSTANCE_PROPERTY built-in specified an invalid property.

Action:	The property must be changed to BORDER_BEVEL, INSERT_ALLOWED, NAVIGABLE, REQUIRED, UPDATEABLE, or VISUAL_ATTRIBUTE, or else the call to the built-in must be removed.

Level:	99

Type:	Error


FRM-41383
FRM-41383:  No such property for Set_Item_Instance_Property.

Cause:	Application design error.  A SET_ITEM_INSTANCE_PROPERTY built-in specified an invalid property.

Action:	The property must be changed to BORDER_BEVEL, INSERT_ALLOWED, NAVIGABLE, REQUIRED, UPDATEABLE, or VISUAL_ATTRIBUTE, or else the call to the built-in must be removed.

Level:	99

Type:	Error


FRM-41384
FRM-41384:  Invalid parameter used for Set_Item_Instance_Property.

Cause:	Application design error.  A SET_ITEM_INSTANCE_PROPERTY built-in specified an invalid value for a property.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-41385
FRM-41385:  Maximum number of queried records exceeded.

Cause:	The user specified maximum number of records for a given block is reached.

Action:	Check the forms block and form level properties.

Level:	99

Type:	Informative


FRM-41386
FRM-41386:  Cannot set VISIBLE attribute of tab page containing current item.

Cause:	You tried to set the Visible property for the tab page which contains the current item.

Action:	The Visible property is only valid for tab pages which don't contain the current item.

Navigate to an item on a different tab page or different canvas first.

Level:	99

Type:	Error


FRM-41387
FRM-41387:  Cannot set VISIBLE attribute of last enterable tab page.

Cause:	You tried to set the Visible property for the only enterable tab page on the canvas.

Action:	Make sure there is at least one other enterable tab page on the canvas before trying to set the Visible property.

Level:	99

Type:	Error


FRM-41388
FRM-41388:  Cannot set ENABLED attribute of tab page containing current item.

Cause:	You tried to set the Enabled property for the tab page which contains the current item.

Action:	The property is only valid for tab pages which don't contain the current item.

Navigate to an item on a different tab page or different canvas first.

Level:	99

Type:	Error


FRM-41389
FRM-41389:  Cannot set ENABLED attribute of last enterable tab page.

Cause:	You tried to set the Enabled property for the only enterable tab page on the canvas.

Action:	Make sure there is at least one other enterable tab page on the canvas before trying to set the Enabled property.

Level:	99

Type:	Error


FRM-41390
FRM-41390:  Cannot set REQUIRED property of subordinate mirror item %s.%s.

Cause:	Application design error.  A SET_ITEM_PROPERTY or SET_ITEM_INSTANCE_PROPERTY built-in attempted to set the Required property  of a subordinate mirror item.  Since the form's Runtime Compatibility Mode is 5.0, the Required property will be obtained from the master mirror item (the item specified by the Synchronize with Item property).

Action:	Set the Required property of the master mirror item.

Level:	25

Type:	Error


FRM-41391
FRM-41391:  Cannot find visual attribute: invalid ID.

Cause:	An invalid ID was passed to a built-in subprogram.

Action:	Verify that a proper call to Find_VA will be performed.

Level:	99

Type:	Error


FRM-41392
FRM-41392:  No such property for Get_VA_Property.

Cause:	You attempted to get a non-existent visual attribute property.

Action:	Verify call to Get_VA_Property for a valid property.

Level:	99

Type:	Error


FRM-41393
FRM-41393:  No such property for Set_VA_Property.

Cause:	You attempted to set an invalid visual attribute property.

Action:	Check the documentation for setting visual attribute properties and try again.

Level:	99

Type:	Error


FRM-41394
FRM-41394:  Invalid parameter value used for Set_VA_Property.

Cause:	You attempted to set an invalid value for a visual attribute property.

Action:	Check the documentation for setting visual attribute properties and try again.

Level:	99

Type:	Error


FRM-41395
FRM-41395:  Invalid parameter used for Set_Report_Object_Property.

Cause:	You specified a parameter that does not exist.

Action:	Check the list of legal parameters.

Level:	99

Type:	Error


FRM-41396
FRM-41396:  No such property for Get/Set_Report_Object_Property.

Cause:	You specified a property that does not exist.

Action:	Check the list of legal properties.

Level:	99

Type:	Error


FRM-41397
FRM-41397:  Invalid parameter value used for Set_Graphics_Property.

Cause:	You attempted to set an invalid value for a graphics property.

Action:	Check the documentation for setting graphics properties and try again.

Level:	99

Type:	Error


FRM-41398
FRM-41398:  Unable to set object text in Set_Graphics_Property.

Cause:	Error during attempt to set the text of a graphics object.

Action:	Check that memory isn't low.

Action:	If memory isn't an issue, the form may be corrupted.

Level:	99

Type:	Error


FRM-41399
FRM-41399:  Can only set the text of a Text or Frame graphics object.

Cause:	You attempted to set the text of a non-textual graphics object.

Action:	Check that you specified the correct graphics object and try again.

Level:	99

Type:	Error


FRM-41400
FRM-41400:  No such property for Set_Graphics_Property.

Cause:	You attempted to set an invalid graphics property.

Action:	Check the documentation for setting graphics properties and try again.

Level:	99

Type:	Error


FRM-41401
FRM-41401:  No such property for Get_Graphics_Property.

Cause:	You attempted to get a non-existent graphics property.

Action:	Verify the call to Get_Graphics_Property for a valid property.

Level:	99

Type:	Error


FRM-41800
FRM-41800:  List of Values not available for this field.

Cause:	You pressed [List], but the form does not provide a list of values for this field.

Action:	No action is necessary.

Level:	10

Type:	Informative


FRM-41801
FRM-41801:  Last value retrieved.

Cause:	You pressed [List] and then pressed [Next Item] after the last value in the list was displayed.

Action:	Enter an item value or press [List] again to display the list of possible values.

Level:	10

Type:	Informative


FRM-41802
FRM-41802:  Duplicate record function allowed on new records only.

Cause:	You pressed [Duplicate Record], but the current record is the one that has been fetched from the database.

Action:	No action is necessary.  You can use [Duplicate Record] only when creating a new record.

Level:	10

Type:	Error


FRM-41803
FRM-41803:  No previous record to copy value from.

Cause:	You pressed [Duplicate Item] or [Duplicate Record], but the current record is the first record in the block.

Action:	No action is necessary.  [Duplicate Item] and [Duplicate Record] are meaningless in this context.

Level:	10

Type:	Error


FRM-41804
FRM-41804:  Variable was not entered: %.30s.

Cause:	Your response to the Query Where alert contained a placeholder not used in any of the query items.

Action:	Correct the placeholder in your response, or define it in one of the query items.  Then re-execute the query.

Level:	>25

Type:	Error


FRM-41805
FRM-41805:  Ambiguous item name: %s.

Cause:	Application design error.  Ambiguous item name.

Action:

Level:	>25

Type:	Error


FRM-41806
FRM-41806:  Too many variables used.

Cause:	You used more than 25 substitution variables in your query.

Action:	Reduce the number of substitution variables and re-query.

Level:	>25

Type:	Error


FRM-41809
FRM-41809:  Error initializing Menu.

Cause:	You tried to use the menu component from within Form Builder, and an internal error occurred.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-41810
FRM-41810:  Error creating menu.

Cause:	You tried to use the menu component from within Form Builder, and an internal error occurred.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-41811
FRM-41811:  Error removing menu.

Cause:	You tried to use Menus from within Form Builder, and an internal Menu error occurred.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-41812
FRM-41812:  Error resetting Menu.

Cause:	You tried to use the menu component from within Form Builder, and an internal error occurred.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-41813
FRM-41813:  Form exited by debug mode.

Cause:	You selected the Exit Oracle Forms Runtime option on the Break Processing menu.

Action:	No action is necessary.

Level:	>25

Type:	Working


FRM-41814
FRM-41814:  Invalid page position.

Cause:	Application design error.  A trigger tried to move or resize a view to a page that would cause all or part of the view to display off of the screen.

Action:	Correct the statement.

Level:	>25

Type:	Error


FRM-41815
FRM-41815:  No such property for Get_LOV_Property.

Cause:	You attempted to get a nonexistent LOV property.

Action:	Verify the valid LOV properties and try again.

Level:	>25

Type:	Error


FRM-41816
FRM-41816:  Attempt to create existing timer: %s.

Cause:	Attempted to create a timer that already exists.

Action:	Delete or alter the existing timer before re-creating a new one.

Level:	>25

Type:	Error


FRM-41817
FRM-41817:  No such timer: %s.

Cause:	You attempted to alter or delete a non-existent timer.

Action:	Check the built-in for proper arguments.

Level:	>25

Type:	Error


FRM-41818
FRM-41818:  Toolkit failed to create timer %s :may be out of memory.

Cause:	An internal error occurred while attempting to create a timer, possibly as a result of memory constraints.

Action:	Check and adjust memory quotas as necessary.

Level:	>25

Type:	Error


FRM-41819
FRM-41819:  Timers are not supported on this platform.

Cause:	Illegal attempt to create a timer on a platform where timers are not supported.

Action:	None.  A timer option is unavailable on your platform.

Level:	>25

Type:	Error


FRM-41820
FRM-41820:  Toolkit failed to delete timer: %s.

Cause:	Internal error caused by timer failure.

Action:	Contact customer support.

Level:	>25

Type:	Error


FRM-41821
FRM-41821:  Timer name too long: %s...

Cause:	You attempted to create a timer with a name longer than 30 bytes.

Action:	Retry with a shorter name.

Level:	>25

Type:	Error


FRM-41822
FRM-41822:  Timer name may not be null string.

Cause:	You attempted to create a timer with a null name.

Action:	Retry with a non-null name.

Level:	>25

Type:	Error


FRM-41823
FRM-41823:  Illegal timer interval for timer %s.

Cause:	You attempted to create a timer with an interval less than 1 millisecond.

Action:	Recreate your timer with an interval of at least 1 millisecond.

Level:	>25

Type:	Error


FRM-41824
FRM-41824:  Date/time operation failed for %s.

Cause:	An internal error occurred while attempting to resolve a date/time initial value for an item.

Action:	Contact customer support.

Level:	10

Type:	Error


FRM-41825
FRM-41825:  No such property for Get_LOV_Property.

Cause:	You attempted to get a nonexistent LOV property.

Action:	Verify the valid LOV properties and try again.

Level:	>25

Type:	Error


FRM-41826
FRM-41826:  Cannot replace group; columns don't match LOV.

Cause:	Cannot replace the list of values' current record group with a record group that is incompatible with the LOV column structure.

Action:	Do not attempt to assign this record group to this LOV.

Level:	>25

Type:	Error


FRM-41827
FRM-41827:  Group does not exist.

Cause:	The group name or ID specified is invalid.

Action:	Check the name or ID entered and try again.

Level:	>25

Type:	Error


FRM-41828
FRM-41828:  LOV does not exist.

Cause:	LOV name or ID specified is invalid.

Action:	Check the name or ID entered and try again.

Level:	>25

Type:	Error


FRM-41829
FRM-41829:  Record not created.

Cause:	Application design error.  The record failed to get its initial value.

Action:	Contact the application designer.

Level:	>25

Type:	Error


FRM-41830
FRM-41830:  List of Values contains no entries.

Cause:	The record group underlying the LOV contains no records.

Action:	Check to be sure that any criteria used to reduce a long list LOV did not eliminate all matches.

Level:	>5

Type:	Error


FRM-41832
FRM-41832:  Error: program unit %s in library %s is uncompiled.

Cause:	You called an uncompiled program unit from a library.

Action:	Follow the PL/SQL program error.

Level:	99

Type:	Error


FRM-41833
FRM-41833:  Warning! Program unit %s in library %s is uncompiled.

Cause:	You called an uncompiled program unit in a library when debug mode was specified.

Action:	This is just a warning. Forms Runtime will attempt to compile and run the program unit.

Level:	99

Type:	Informative


FRM-41834
FRM-41834:  Error: Unable to create PECS class %s.

Cause:	Unable to create the PECS data file.

Action:	Check the PECS appendix for the location of the PECS data files.  Check to be sure you have the appropriate privileges on this file, and that the path environment variable is set to a valid path.

Level:	99

Type:	Informative


FRM-41835
FRM-41835:  Canvas %s is not a tab canvas.

Cause:	You tried to perform a tab canvas specific operation on a canvas which is not a tab canvas.

Action:	Make sure the canvas specified is a tab canvas.

Level:	99

Type:	Error


FRM-41836
FRM-41836:  No tab page %s in canvas %s.

Cause:	You tried to perform an operation on a tab page which does not exist in the specified canvas.

Action:	Make sure you specify a tab page which exists in the specified tab canvas.

Level:	99

Type:	Error


FRM-41837
FRM-41837:  Error raising tab page %s.

Cause:	The specified tab page could not be brought to the top (made the current page of the tab canvas).

Action:	Make sure the specified page is enabled, and not hidden.

Level:	99

Type:	Error


FRM-41838
FRM-41838:  Unable to open temporary record buffer file %s.

Cause:	Unable to open file used as temporary record buffer.

Action:	Verify that the file system or directory in which the file resides exists and that you have permissions to read and write to it.

Level:	99

Type:	Error


FRM-41839
FRM-41839:  Disk I/O error on temporary record buffer file %s

Cause:	An I/O error occurred on attempting to read or write a record to the temporary record buffer file.

Action:	Verify that the file system or directory in which the file resides exists, and that you have permissions to read and write to it, and that it contains sufficient space.

Level:	99

Type:	Error


FRM-41840
FRM-41840:  Insufficient main memory for record buffers

Cause:	Unable to allocate memory for a record being created in a block.

Action:	Try restarting application when fewer programs are running concurrently, or on a machine with more memory. The design may need to be changed so that one or more blocks have smaller values for the Records Buffered property.

Level:	99

Type:	Error


FRM-41841
FRM-41841:  Use the debugger-enabled executable if specifying DEBUG=YES.

Cause:	You tried to use the debugger from an executable which doesn't include it.

Action:	Run the other executable (name will vary with operating system), which includes the debugger.

Level:	99

Type:	Error


FRM-41900
FRM-41900:  Run aborted by fatal error.

Cause:	Fatal error caused form to abort.

Action:	Contact your DBA.

Level:	20

Type:	Error


FRM-41901
FRM-41901:  Error:  %d cursors were not closed.

Cause:	Internal error.

Action:	Contact your DBA.

Level:	>25

Type:	Error


FRM-41902
FRM-41902:  Total cursors used %d.

Cause:	This message appears when you run a form with the Statistics preference set to True.

Action:	No action is necessary.

Level:	>25

Type:	Informative


FRM-41903
FRM-41903:  Run aborted by end of input file.

Cause:	Internal error.

Action:	Contact an Oracle support representative.

Level:	>25

Type:	Error


FRM-42015
FRM-42015:  Must specify key file in non-interactive mode.

Cause:	You tried to run the form in non-interactive mode without specifying the name of a key input file at form startup.

Action:	Specify the name of the key file.

Level:	>25

Type:	Error


FRM-42016
FRM-42016:  Read and write files may not have the same name.

Cause:	You attempted to specify the same name for a read and a write file.

Action:	Specify different names for the two files.

Level:	>25

Type:	Error


FRM-42017
FRM-42017:  Module name must be specified.

Cause:	You did not specify a module name.

Action:	Specify a module name.

Level:	>25

Type:	Error


FRM-42100
FRM-42100:  No errors encountered recently.

Cause:	You pressed [Display Error], but no error has occurred recently.

Action:	No action is necessary.

Level:	5

Type:	Informative


FRM-42400
FRM-42400:  Performing event trigger %s.

Cause:	This message is displayed during a trigger when debug mode is specified.

Action:	No action is necessary.

Level:	>25

Type:	Informative


FRM-42401
FRM-42401:  Performing program trigger %s.

Cause:	This message is displayed during a trigger when debug mode is specified.

Action:	No action is necessary.

Level:	>25

Type:	Informative


FRM-42423
FRM-42423:  Cannot execute trigger %s: no compiled state

Cause:	This message is displayed when running a form in debug mode, if the compiled state of a trigger has been destroyed. This can happen if you apply a change to the trigger text and that change results in compilation errors.

Action:	You can recompile the trigger in the debugger or exit the form and start it up again.

Level:	99

Type:	Error


FRM-47000
FRM-47000:  Cannot create Parameter List %s : internal error.

Cause:	Internal error.

Action:	Contact an Oracle support representative.

Level:	99

Type:	Error


FRM-47001
FRM-47001:  Cannot create Parameter List %s : list with this name exists.

Cause:	The name you specified for the parameter list is already in use.

Action:	Specify another name for the parameter list.

Level:	99

Type:	Error


FRM-47002
FRM-47002:  Cannot create Parameter List : name must not be null.

Cause:	The parameter list name cannot be null.

Action:	Specify a name for the parameter list.


FRM-47003
FRM-47003:  Cannot delete Parameter List : internal error.

Cause:	Internal error.

Action:	Contact an Oracle support representative.

Level:	99

Type:	Error


FRM-47004
FRM-47004:  Cannot delete Parameter List : invalid ID.

Cause:	Attempted to pass an invalid parameter list ID.

Action:	Check the list ID name and try again.

Level:	99

Type:	Error


FRM-47005
FRM-47005:  Cannot validate parameter %s : internal error.

Cause:	Internal error.

Action:	Contact an Oracle support representative.

Level:	99

Type:	Error


FRM-47006
FRM-47006:  Cannot create Parameter List '%s' : illegal identifier name.

Cause:	Illegal identifier name.

Action:	Check valid syntax for the identifier.

Level:	99

Type:	Error


FRM-47007
FRM-47007:  Cannot get parameter %s attributes from Parameter List : invalid list ID.

Cause:	Specified an invalid parameter list ID.

Action:	Check the parameter list ID name and try again.

Level:	99

Type:	Error


FRM-47008
FRM-47008:  Cannot add parameter %s to Parameter List %s : internal error.

Cause:	An internal error occurred.

Action:	Contact an Oracle support representative.

Level:	99

Type:	Error


FRM-47009
FRM-47009:  Cannot add parameter %s to Parameter List : invalid list ID.

Cause:	You specified an invalid parameter list ID.

Action:	Check the parameter list ID name and try again.

Level:	99

Type:	Error


FRM-47010
FRM-47010:  Cannot add parameter to Parameter List %s : null key specified.

Cause:	No name specified for the parameter.

Action:	Specify a parameter name <key> in your call to ADD_PARAMETER.

Level:	99

Type:	Error


FRM-47011
FRM-47011:  Cannot add parameter %s to Parameter List %s : incorrect type specified.

Cause:	You specified an invalid parameter type.

Action:	Specify either TEXT_PARAMETER or DATA_PARAMETER.

Level:	99

Type:	Error


FRM-47012
FRM-47012:  Cannot add parameter %s to Parameter List %s : group %s does not exist.

Cause:	Record group name does not exist.

Action:	Check the record group name and try again.

Level:	99

Type:	Error


FRM-47013
FRM-47013:  Cannot add parameter %s to Parameter List %s : parameter with this name exists.

Cause:	Parameter with this name already exists.

Action:	Specify another name for the parameter.

Level:	99

Type:	Error


FRM-47014
FRM-47014:  Cannot delete parameter %s from Parameter List %s : internal error.

Cause:	Internal error.

Action:	Contact an Oracle support representative.

Level:	99

Type:	Error


FRM-47015
FRM-47015:  Cannot delete parameter %s from Parameter List : invalid list ID.

Cause:	Specified an invalid parameter list ID.

Action:	Check the list ID name and try again.

Level:	99

Type:	Error


FRM-47016
FRM-47016:  Cannot delete parameter from Parameter List %s : null key specified.

Cause:	You did not specify a name for the parameter.

Action:	Correct the call to DELETE_PARAMETER by supplying a parameter name.

Level:	99

Type:	Error


FRM-47017
FRM-47017:  Cannot delete parameter %s from Parameter List %s : no such named parameter exists.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You specified a parameter name that does not exist.

Action:	Check the parameter name and try again.

Level:	99

Type:	Error


FRM-47018
FRM-47018:  Cannot set parameter %s attributes in Parameter List %s : internal error.

Cause:	Internal error: you specified an invalid parameter list ID.

Action:	Contact an Oracle support representative.

Level:	99

Type:	Error


FRM-47019
FRM-47019:  Cannot set parameter %s attributes in Parameter List : invalid list ID.

Cause:	You specified an invalid parameter list ID.

Action:	Check the parameter list ID name and try again.

Level:	99

Type:	Error


FRM-47020
FRM-47020:  Cannot set parameter %s attributes in Parameter List %s : no such named parameter exists.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You specified a parameter name that does not exist.

Action:	Check the parameter name and try again.

Level:	99

Type:	Error


FRM-47021
FRM-47021:  No such parameter named %s exists in Parameter List %s.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You specified a parameter name that does not exist.

Action:	Check the name and try again.

Level:	99

Type:	Error


FRM-47022
FRM-47022:  Cannot create Parameter List %s : name is a reserved word.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You specified a name that is a reserved word.

Action:	Specify another name for the parameter list.

Level:	99

Type:	Error


FRM-47023
FRM-47023:  No such parameter named %s exists in form %s.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You specified a parameter name does not exist.

Action:	Check the name and try again.

Level:	99

Type:	Error


FRM-47024
FRM-47024:  Parameter %s type does not match definition in form %s.

Cause:	You specified a parameter type that does not match the definition in the form.

Action:	Specify a parameter type that matches the definition in the form.

Level:	99

Type:	Error


FRM-47025
FRM-47025:  Cannot get parameter %s attributes from Parameter List %s : internal error.

Cause:	Internal error: you specified an invalid parameter list ID.

Action:	Contact an Oracle support representative.

Level:	99

Type:	Error


FRM-47026
FRM-47026:  Cannot get parameter %s attributes from Parameter List %s : no such named parameter exists.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You specified a parameter name does not exist.

Action:	Check the name and try again.

Level:	99

Type:	Error


FRM-47027
FRM-47027:  Cannot add parameter %s to Parameter List %s : invalid key specified .

Cause:	You specified an invalid parameter list ID.

Action:	Check the name and try again.

Level:	99

Type:	Error


FRM-47028
FRM-47028:  Cannot set parameter %s attribute in Parameter List %s : group %s does not exist.

Cause:	You specified an invalid parameter list ID.

Action:	Check the name and try again.

Level:	99

Type:	Error


FRM-47029
FRM-47029:  Invalid parameter list ID in form %s.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You specified a parameter name does not exist.

Action:	Check the ID and try again.

Level:	99

Type:	Error


FRM-47030
FRM-47030:  Value of parameter %s is too long for definition in form %s.

Cause:	You specified a parameter that is too long.

Action:	Specify a parameter that is valid.

Level:	99

Type:	Error


FRM-47031
FRM-47031:  Cannot set value of parameter %s in DEFAULT parameter list: invalid value specified.

Cause:	Application design error.  A built-in (such as SET_PARAMETER_ATTR) is attempting to set the value of a parameter which was defined when the form was designed, but the value specified is not legal for the parameter's datatype.

Action:	The call to the built-in must be modified or removed.

Level:	99

Type:	Error


FRM-47032
FRM-47032:  Cannot set value of parameter %s in DEFAULT parameter list: internal error.

Cause:	An internal error while attempting to set the value of a parameter.

Action:	Contact an Oracle support representative.

Level:	99

Type:	Error


FRM-47033
FRM-47033:  Cannot set value of read-only bind variable %s.

Cause:	Application design error.  The application attempted to assign a value to a bind variable which cannot be programmtically modified.

Action:	The assignment must be removed.

Level:	25

Type:	Error


FRM-47100
FRM-47100:  Cannot read image file %s.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. Form Builder was unable to find or open the file.

3. The data in the file is not in the specified format.

Action:	Check the file name and file format and try again.

Level:	99

Type:	Error


FRM-47101
FRM-47101:  Cannot write image file %s.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. Form Builder was unable to find or open the file.

3. The data in the file is not in the specified format.

Action:	Check the file name, and make sure you have write privileges.

Level:	99

Type:	Error


FRM-47102
FRM-47102:  Cannot perform %s operation on images %s and %s.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. This operation cannot be performed on color images.

Action:	Check to see that both images are black and white.

Level:	99

Type:	Error


FRM-47103
FRM-47103:  Cannot zoom image %s.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. Internal multimedia error caused by trying to scale a null image or invalid image data.

Action:	Check the image name that you want to zoom and try again.

Level:	99

Type:	Error


FRM-47104
FRM-47104:  Invalid image type %s.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. Data in the file name specified does not match the data type specified.

Action:	Check the file name and try again.

Level:	99

Type:	Error


FRM-47105
FRM-47105:  No image name specified.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You did not supply a name to the built-in call.

Action:	Refer to the documentation for the proper syntax for the built-in in question.

Level:	99

Type:	Error


FRM-47106
FRM-47106:  No image type specified.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You did not specify an image type when calling READ_IMAGE_FILE or WRITE_IMAGE_FILE.

Action:	Supply an image type as an argument in your call to READ_IMAGE_FILE or WRITE_IMAGE_FILE.

Level:	99

Type:	Error


FRM-47107
FRM-47107:  Invalid scaling factor %d for Image_Zoom.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You specified an invalid scaling factor.

Action:	Correct the call to IMAGE_ZOOM.

Level:	20

Type:	Error


FRM-47108
FRM-47108:  Item %s is not an image item.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You attempted to perform an image operation on an item that is not an image item.

Action:	Check the item name and try again.

Level:	99

Type:	Error


FRM-47109
FRM-47109:  Cannot locate image file %s.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You specified a file that cannot be found or does not exist.

Action:	Verify that the file exists and the pathname is correct.

Level:	20

Type:	Error


FRM-47110
FRM-47110:  No region was selected for Image_Zoom: %s

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You tried to zoom an image without selecting an image region.

Action:	Select an image region.

Level:	20

Type:	Error


FRM-47111
FRM-47111:  Cannot copy value to item: %s

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You tried to use the COPY built-in on an image item.

Action:	You cannot use the COPY built-in on an image item.

Level:	20

Type:	Error


FRM-47200
FRM-47200:  Item %s is not a sound item.

Cause:	Caused by one of the following:

1. You specified an invalid parameter list ID.

2. You attempted to perform a sound operation on an item that is not a sound item.

Action:	Check the item name and try again.

Level:	99

Type:	Error


FRM-47201
FRM-47201:  Cannot play sound %s.

Cause:	Unable to play the sound in the requested sound item.  The sound output device may be busy.

Action:	Stop other programs directing output to the sound device and try again.

Level:	99

Type:	Error


FRM-47202
FRM-47202:  No sound file name specified.

Cause:	You did not supply a file name to the built-in call.

Action:	Refer to the documentation for the proper syntax for the built-in in question.

Level:	99

Type:	Error


FRM-47203
FRM-47203:  Cannot locate sound file %s.

Cause:	Form Builder was unable to find the file specified in READ_SOUND_FILE.

Action:	Check the file name and try again.

Level:	99

Type:	Error


FRM-47204
FRM-47204:  Cannot read sound file %s.

Cause:	Form Builder was unable to read the sound file, typically because the file type specified did not match the file contents.

Action:	Verify the contents of the sound file.

Level:	99

Type:	Error


FRM-47205
FRM-47205:  No sound type specified.

Cause:	You did not specify a sound type when calling WRITE_SOUND_FILE.

Action:	Supply a sound type as an argument in your call to WRITE_SOUND_FILE.

Level:	99

Type:	Error


FRM-47206
FRM-47206:  Cannot write sound file %s.

Cause:	Form Builder was unable to create the sound file.  The sound data may have been corrupted.

Action:	Contact your Oracle support representative.

Level:	99

Type:	Error


FRM-47207
FRM-47207:  In this release, Play_Sound can only be run against the current item.

Cause:	PLAY_SOUND was invoked against other than the current item.

Action:	Place the input focus in the sound item before calling PLAY_SOUND.

Level:	99

Type:	Error


FRM-47208
FRM-47208:  Cannot create an empty sound file. (%s)

Cause:	WRITE_SOUND_FILE was invoked against a sound item containing no sound data.

Action:	Load sound data into the sound item before calling WRITE_SOUND_FILE.

Level:	99

Type:	Error


FRM-30004
FRM-30004:  Module name must be specified.

Cause:	Module name was not supplied, or the module name you supplied cannot be used.

Action:	Enter a valid module name.


FRM-30009
FRM-30009:  No blocks were entered.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30012
FRM-30012:  Block must have at least one item.

Cause:	You did not enter any items in the block.

Action:	Enter items in the block or recreate the block.


FRM-30013
FRM-30013:  No such item %s in block %s.

Cause:	You referenced an item that does not exist in the current block.

Action:	Check the name of the item, and do one of the following:

1. Remove the reference to the item.

2. Correct the name of the item.


FRM-30014
FRM-30014:  No such block %s.

Cause:	You referenced a block that does not exist in the current form.

Action:	Check the name of the block, and do one of the following:

1. Remove the reference to the block.

2. Correct the name of the block.


FRM-30015
FRM-30015:  Ambiguous item name %s.

Cause:	You entered an item name that exists in more than one block.

Action:	To make the item name unique, specify the block name. Use the block_name.item_name format (e.g., EMP.SALARY).


FRM-30016
FRM-30016:  No such item %s.

Cause:	You referenced an item that does not exist in the current form.

Action:	Check the name of the item, and do one of the following:

1. Remove the reference to the item.

2. Correct the name of the item.


FRM-30018
FRM-30018:  Internal error: Unable to allocate memory.

Cause:	You may be out of memory, or there may be a memory corruption.

Action:	Contact your DBA.


FRM-30020
FRM-30020:  Internal error: Unable to allocate VGS context.

Cause:	An error occurred while trying to allocate VGS context for the layout editor.

Action:	Contact your Oracle support representative.


FRM-30021
FRM-30021:  Internal error: Unable to build VGS boilerplate information.

Cause:	Internal error caused by corrupted boilerplate data.

Action:	Contact your Oracle support representative.


FRM-30028
FRM-30028:  WHERE clause too long.

Cause:	The SQL statement that you entered as part of a V2 trigger is too long.

Action:	Shorten the statement (maximum length = 4096 characters).


FRM-30029
FRM-30029:  Cannot find window %s.

Cause:	The window is set to an invalid parent window.

Action:	Set the window to a valid parent window.


FRM-30032
FRM-30032:  Number of records displayed must be between 1 and 255.

Cause:	The number of records displayed is not in the valid range. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30033
FRM-30033:  Records buffered must exceed records displayed.

Cause:	The number of records buffered was not greater than the number of records displayed. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30040
FRM-30040:  Not a valid item type.

Cause:	You entered an invalid item type. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30041
FRM-30041:  Position of item places it off of canvas.

Cause:	You specified invalid Y coordinates for the item.

Action:	Specify coordinates within a canvas.


FRM-30042
FRM-30042:  Length of item must be between 1 and 133.

Cause:	The item length you entered was not in the valid range. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30043
FRM-30043:  Length of item must be between 1 and 255.

Cause:	The item length you entered was not in the valid range. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30044
FRM-30044:  Display length must be between 1 and 133 but not more than length.

Cause:	The item length you entered was not in the valid range. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30045
FRM-30045:  Query length of item must be 0 (default) or greater than actual length.

Cause:	You entered an invalid query length. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30046
FRM-30046:  Internal error: unable to adjust pointer.

Cause:	An internal compilation error occurred.

Action:	Contact your Oracle support representative.


FRM-30047
FRM-30047:  Cannot resolve item reference %s.

Cause:	The item referenced does not exist.

Action:	Change the reference or create the item.


FRM-30048
FRM-30048:  Unable to find record group %s.

Cause:	The record group specified within the LOV object is invalid.

Action:	Check the record group name or ID specified.


FRM-30049
FRM-30049:  Unable to build column mapping.

Cause:	Reference to record group columns within the LOV object cannot be found.

Action:	Check the column names specified within the LOV object.


FRM-30051
FRM-30051:  Internal error: unable to prepare heaps for output.

Cause:	An internal compilation error occurred.

Action:	Contact your Oracle support representative.


FRM-30052
FRM-30052:  Named visual attribute %s does not exist.

Cause:	You assigned an undefined visual attribute name to an object.

Action:	Check the visual attribute name and try again.


FRM-30053
FRM-30053:  Cannot create unnamed visual attribute.

Cause:	Caused by an internal error, or memory allocation error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30054
FRM-30054:  Cannot find canvas %s.

Cause:	You specified an invalid canvas name or ID specified.

Action:	Check the canvas name or ID and try again.


FRM-30056
FRM-30056:  Warning! Prompt for item %s.%s was truncated.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30057
FRM-30057:  Maximum record length for record group exceeded.

Cause:	You specified too many columns.

Action:	Do not add additional columns to this record group.


FRM-30058
FRM-30058:  Invalid name for a record group column %s.

Cause:	You specified an invalid column name.

Action:	Check the column name and try again.


FRM-30059
FRM-30059:  Duplicate column name %s.

Cause:	You specified a column name that already exits

Action:	Specify a unique column name.


FRM-30060
FRM-30060:  Unable to create column descriptor %s.

Cause:	Internal error, or memory allocation error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30061
FRM-30061:  Unable to remove INTO clause from statement %s.

Cause:	Bind variable substitution error: a SELECT statement within an LOV or record group is incorrect.

Action:	Check the syntax of the SELECT statement, and add the INTO clause.


FRM-30062
FRM-30062:  Unable to perform bind variable substitution for statement %s.

Cause:	Referenced bind variable does not exist.

Action:	Create the variable, or correct the reference.


FRM-30063
FRM-30063:  Unable to open cursor for parse of record group query %s.

Cause:	You may have lost connection with the database.

Action:	Check the database connection, or contact your DBA.


FRM-30064
FRM-30064:  Unable to parse statement %s.

Cause:	A syntax error occurred in the SELECT statement within an LOV or record group.

Action:	Check the statement, and add the FROM clause.


FRM-30065
FRM-30065:  Column type %d not supported.

Cause:	The specified column type was not CHAR, NUMBER, or DATE.

Action:	Change the column type to one supported by Form Builder.


FRM-30069
FRM-30069:  Not a valid trigger name.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30081
FRM-30081:  SQL statement is too long.

Cause:	You entered an SQL statement (as part of a V2 trigger) that exceeds the maximum allowable length.

Action:	Shorten the statement to 4096 characters or less.


FRM-30082
FRM-30082:  Non-SELECT statements not allowed in non-commit triggers.

Cause:	The trigger contains a SQL statement other than a SELECT statement.

Action:	Move the statement to a trigger where the non-SELECT SQL statement is valid.


FRM-30083
FRM-30083:  Unable to find editor %s.

Cause:	The editor name referenced does not exist.

Action:	Create the editor, or delete the reference.


FRM-30084
FRM-30084:  Unable to find LOV %s.

Cause:	The referenced LOV name does not exist.

Action:	Specify another LOV name, or delete the reference.


FRM-30085
FRM-30085:  Unable to adjust form for output.

Cause:	Caused by an internal error, or memory allocation error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30087
FRM-30087:  Unable to create form file %s.

Cause:	You lack privileges in the specified directory, or you do not have the disk space required.

Action:	Contact your DBA to make sure you have the access privileges you need.


FRM-30089
FRM-30089:  Too many pages.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30090
FRM-30090:  Too many boilerplate items.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30091
FRM-30091:  Too many trigger steps.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30092
FRM-30092:  Too many ranges.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30093
FRM-30093:  Too many triggers.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30094
FRM-30094:  Too many item pointers.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30096
FRM-30096:  Could not create form output file %s.

Cause:	An operating system error prevented Form Builder from creating an output file.

Action:	Contact your DBA or an Oracle support representative.


FRM-30100
FRM-30100:  Block must have at least one primary key item.

Cause:	At least one item should be marked as being part of the primary key if one of the following is true:

1. The key mode for the block is either UPDATEABLE_PRIMARY_KEY or NON_UPDATEABLE_PRIMARY_KEY.

2. The key mode for the block is AUTOMATIC but the data source to which you are connected does not support UNIQUE key mode.

Action:	Mark one of the items as being part of the primary key and re-compile.


FRM-30101
FRM-30101:  Too many strings.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30102
FRM-30102:  Could not write all of the output file.

Cause:	An operating system error prevented Form Builder from creating an output file.

Action:	Contact your DBA or an Oracle support representative.


FRM-30109
FRM-30109:  Item %s.%s is right-adjusted and scrolled.

Cause:	An item can be either a scrolled item or a right-adjusted item, but not both.

Action:	Define the item either as scrolled or right-adjusted.


FRM-30110
FRM-30110:  You must enter Y, *Y, **Y, N, *N, or **N.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30112
FRM-30112:  Warning! %s resolves to item in block PARAMETER.

Cause:	You pointed to a field, not a parameter.

Action:	Be sure this is what you intended.


FRM-30113
FRM-30113:  Block must have non-query-only database item.

Cause:	A block that allows updating and inserting must have at least one item derived from the database.

Action:	Create a derived item in the block.


FRM-30118
FRM-30118:  Could not create warning message file %s.

Cause:	An operating system error prevented Form Builder from creating the warning file.

Action:	Contact your DBA or an Oracle support representative.


FRM-30119
FRM-30119:  Errors and warnings written to file %s.

Cause:	Compilation error.

Action:	 Check the errors and warnings in the specified file.


FRM-30120
FRM-30120:  Version 1 macro %s not supported.

Cause:	You used an Forms version 1.0 macro (#MACRO, #MACROIF, or #KEY) that is not supported by later versions of Form Builder.

Action:	Replace the macro with the appropriate later version equivalent.


FRM-30121
FRM-30121:  Error in the INTO clause, or missing FROM clause.

Cause:	A V2-style trigger contains an improper SQL statement.

Action:	Correct the SQL statement.


FRM-30122
FRM-30122:  Invalid line number.

Cause:	An invalid Y position was given for an item. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30123
FRM-30123:  Invalid column number.

Cause:	An invalid X position was given for an item. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30124
FRM-30124:  Too many procedures.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30125
FRM-30125:  Too much library-unit memory.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30129
FRM-30129:  Compilation error on procedure specification for procedure %s.

Cause:	You tried to compile a procedure that contains an invalid specification.

Action:	Correct the specification.


FRM-30130
FRM-30130:  Code given for trigger %s is not an anonymous block.

Cause:	You entered trigger text that was not an anonymous block.

Action:	Rewrite the trigger to make it an anonymous block.


FRM-30131
FRM-30131:  Invalid parameter reference in trigger %s.

Cause:	You entered trigger text that references parameters.

Action:	Remove the parameter references from the trigger. HINT: to use parameters, write a form-level procedure.


FRM-30132
FRM-30132:  Code given for trigger %s is not executable.

Cause:	You entered trigger text that is not executable.

Action:	Rewrite the trigger.


FRM-30133
FRM-30133:  Compilation error on trigger %s.

Cause:	You entered invalid trigger text.

Action:	View compilation errors on the error screen.


FRM-30134
FRM-30134:  Mismatched procedure and unit names for procedure %s.

Cause:	The procedure name does not match the name defined in the procedure text.

Action:	Change the names to match each other.


FRM-30135
FRM-30135:  Code given for procedure %s is not a named unit.

Cause:	You entered an anonymous block when you should have entered a form-level procedure.

Action:	Rewrite the form-level procedure.


FRM-30136
FRM-30136:  Code given for procedure %s is not executable.

Cause:	You entered non-executable code for the specified form-level procedure.

Action:	Rewrite the form-level procedure.


FRM-30137
FRM-30137:  Compilation error on procedure %s.

Cause:	You entered an incorrect form-level procedure.

Action:	See the error screen for the compilation errors.


FRM-30145
FRM-30145:  Too many bind variables.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30148
FRM-30148:  Too much buffer memory.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30149
FRM-30149:  Too many LOVs.

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30150
FRM-30150:  Error in LOV text for item %s.%s.

Cause:	You specified an invalid SQL statement in the LOV.

Action:	Rewrite the SQL statement.


FRM-30152
FRM-30152:  Unable to connect to database.

Cause:	Internal system error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30156
FRM-30156:  Could not close form output file %s.

Cause:	An operating system error prevented Form Builder from closing an output file.

Action:	Contact your DBA or an Oracle support representative.


FRM-30157
FRM-30157:  LONG item length must be between 1 and 65534.

Cause:	Length of the LONG item was not in the valid range. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30158
FRM-30158:  Display length must be between 0 and 133.

Cause:	Display length was not in the valid range. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30159
FRM-30159:  No text in trigger statement.

Cause:	An empty trigger step was found. The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-30161
FRM-30161:  Inconsistent relationship between window %s and its primary canvas %s.

Cause:	The window does not match its primary canvas's window property.

Action:	Check window's primary canvas property or canvas's window property.


FRM-30162
FRM-30162:  Inconsistent relationship between window %s and its horizontal toolbar %s.

Cause:	The window does not match its horizontal toolbar's window property.

Action:	Check window's horizontal toolbar property or toolbar's window property.


FRM-30169
FRM-30169:  Username and password are required.

Cause:	You have not specified your username and password in order to connect to the database.

Action:	Specify your username and password.


FRM-30170
FRM-30170:  Alert must contain at least one button - %s.

Cause:	The alert contains no buttons.

Action:	Create at least one button for the alert.


FRM-30172
FRM-30172:  No such item.

Cause:	You specified an item that does not exist within the referenced record group.

Action:	Correct the reference.


FRM-30173
FRM-30173:  Module contains no canvases.

Cause:	You attempted to compile a form module that does not contain a canvas.

Action:	Define at least one canvas for the form module.


FRM-30174
FRM-30174:  Checked and Unchecked check box values must be distinct.

Cause:	The check box has equal values for the Checked and Unchecked states.

Action:	Check the values and try again.


FRM-30179
FRM-30179:  Cannot find block %s

Cause:	The block name you specified does not exist.

Action:	Check the block name and try again.


FRM-30180
FRM-30180:  No radio buttons in the radio group.

Cause:	A radio group was defined without radio buttons.

Action:	Define at least one radio button for the radio group.


FRM-30182
FRM-30182:  Image item length must be at least 1024..

Cause:	The maximum lenght of the image must exceed 1024.

Action:	Increase the size of your image to the maximum length.


FRM-30184
FRM-30184:  Other Value not found.

Cause:	The Other Value defined does not match one of the valid values or label strings.

Action:	Define a valid Other Value.


FRM-30185
FRM-30185:  Record group %s contains more than one column of type LONG.

Cause:	A record group can contain only one LONG column.

Action:	Do one of the following:

1. Remove all but one of the LONG columns in the record group.

2. Change the types of all but one of the LONG columns in the record group.


FRM-30186
FRM-30186:  Static record group %s contains LONG column.

Cause:	Static record groups cannot contain columns of type LONG.

Action:	Do one of the following:

1. Make the group a query record group.

2. Change the type of the LONG column.


FRM-30187
FRM-30187:  Size of CHAR column in record group must be between 1 and 2000.

Cause:	The size of a character column in the record group was incorrectly specified

Action:	Make sure the sizes of the character columns in the record group are between 1 and 2000


FRM-30188
FRM-30188:  No initial value given, and other values are not allowed (item %s.%s).

Cause:	No initial value given for item.

Action:	Provide an initial value for item.


FRM-30189
FRM-30189:  Cannot find property class %s

Cause:	Internal ORACLE error.

Action:	Contact your DBA or an Oracle support representative.


FRM-30190
FRM-30190:  No list items defined for T-List.

Cause:	You defined an empty T-list.

Action:	Define items in the T-List.


FRM-30191
FRM-30191:  No list items defined for required poplist.

Cause:	You defined an empty poplist.

Action:	Define items in the poplist.


FRM-30193
FRM-30193:  Format mask not allowed on JDATE item %s.%s.

Cause:	Format masks are valid only for NUMBER, DATE, TIME, and DATETIME items.

Action:	Remove the format mask from the JDATE item.


FRM-30195
FRM-30195:  Format mask not allowed on EDATE item %s.%s.

Cause:	Format masks are valid only for NUMBER, DATE, TIME, and DATETIME items.

Action:	Remove the format mask from the EDATE item.


FRM-30196
FRM-30196:  Too many user-named triggers.

Cause:	You have defined more user-named triggers than Forms can allocate memory for.

Action:	Define fewer user-named triggers.


FRM-30197
FRM-30197:  Unable to add row to record group.

Cause:	You must create the record group and add columns before attempting to add rows.

Action:	Make sure the record group you are specifying exists.


FRM-30199
FRM-30199:  Transactional triggers do not exist for this block

Cause:	You referenced a transactional trigger, but none exist for this module.

Action:	Create the trigger, or delete the reference.


FRM-30201
FRM-30201:  Error occurred during form upgrade.

Cause:	An error occurred during an SQL*Forms 3.0 to Forms 4.5 conversion.

Action:	Check accompanying error messages (if any), or contact your DBA or an Oracle support representative.


FRM-30203
FRM-30203:  No items on block %s.

Cause:	You attempted to compile a form module that contains a block with no items.

Action:	Define some items for the block.


FRM-30204
FRM-30204:  Total data length of the items in this block is too large.

Cause:	The field length of the item exceeds the limit.

Action:	Reduce the item field length.


FRM-30205
FRM-30205:  Cannot resolve parameter reference %s.

Cause:	The referenced parameter could not be found.

Action:	Declare the parameter, or remove the reference.


FRM-30207
FRM-30207:  Mouse Navigate must be Yes for combo box item %s.%s

Cause:	The Mouse Navigate property must be set to Yes for a combo box.

Action:	Set the property value to Yes.


FRM-30209
FRM-30209:  Module contains no windows.

Cause:	A form module must have at least one window defined.

Action:	Define a window for the form module.


FRM-30305
FRM-30305:  Cannot open library file %s.

Cause:	The VBX control properties have changed.

Action:	Redefine the VBX properties.


FRM-30306
FRM-30306:  Unable to save the library %s.

Cause:	The VBX control properties have changed.

Action:	Redefine the VBX properties.


FRM-30307
FRM-30307:  Unable to load procedures from the library.

Cause:	The VBX control properties have changed.

Action:	Redefine the VBX properties.


FRM-30308
FRM-30308:  Unable to allocate memory.

Cause:	The VBX control properties have changed.

Action:	Redefine the VBX properties.


FRM-30309
FRM-30309:  No PL/SQL code in the library.

Cause:	The VBX control properties have changed.

Action:	Redefine the VBX properties.


FRM-30311
FRM-30311:  Cannot attach libraries.

Cause:	The VBX control properties have changed.

Action:	Redefine the VBX properties.


FRM-30312
FRM-30312:  Failed to compile the library.

Cause:	The VBX control properties have changed.

Action:	Redefine the VBX properties.


FRM-30213
FRM-30213:  High range value must be greater than low range value.

Cause:	The high range value is greater than the low range value for text items.

Action:	Define a high range value that is greater than the low range value.


FRM-30351
FRM-30351:  No list elements defined for list item.

Cause:	A combo list must contain list elements.

Action:	Define items for a combo list.


FRM-30352
FRM-30352:  Invalid mirror item name %s for item %s.%s.

Cause:	An invalid mirror item name was defined for the item.

Action:	Use a valid mirror item name.


FRM-30353
FRM-30353:  No VBX control file specified for VBX item.

Cause:	No VBX control file is specified.

Action:	Specify a VBX control file in the Form Builder.


FRM-30354
FRM-30354:  No VBX control name specified for VBX item.

Cause:	No VBX control name is specified.

Action:	Specify a VBX control name in the Form Builder.


FRM-30355
FRM-30355:  Too many mirror items specified for item %s.

Cause:	The number of mirror items exceeds the maximum of 100.

Action:	Make sure you do not exceed the maximum number of mirror items.


FRM-30356
FRM-30356:  Too many records displayed for this item.

Cause:	The number of records displayed for the item exceeds the number of records displayed for the block.

Action:	Reduce the number of displayed records for the item.


FRM-30357
FRM-30357:  Item specifies itself as its mirror item.

Cause:	You set an item's Mirror Item property to the item itself.

Action:	Specify another valid item for the mirror item property.


FRM-30358
FRM-30358:  Item's mirror item %s also specifies a mirror item.

Cause:	You set an item's Mirror Item property to an item that also specifies a mirror item.

Action:	Specify an item that is not a mirror item.


FRM-30359
FRM-30359:  Item specifies non-existent canvas %s.

Cause:	You specified a canvas that does not exist.

Action:	Specify a valid canvas.


FRM-30360
FRM-30360:  Alert does not contain the specified default button.

Cause:	You specified a default button that is not part of the alert definition.

Action:	Specify a label for the default button or specify a valid default button.


FRM-30361
FRM-30361:  Invalid initial value for check box.

Cause:	You specified an initial value for a check box item that does not match the values of the Checked or Unchecked states.

Action:	Specify a valid initial value.


FRM-30362
FRM-30362:  Initial value does not match available list elements.

Cause:	You specified a value that does not match a value on the available list of elements.

Action:	Specify a valid value.


FRM-30363
FRM-30363:  Initial value matches none of the radio buttons.

Cause:	You specified a value that is not associated with a radio button in a radio group.

Action:	Specify a value associated with a radio button in the radio group.


FRM-30364
FRM-30364:  Other value matches none of the radio buttons.

Cause:	You specified a value that is not the name of a radio button or a value associated with a radio button from a radio group.

Action:	Specify a name of a radio button in the radio group or a value associated with a radio button from the radio group.


FRM-30367
FRM-30367:  OLE item cannot specify a mirror item.

Cause:	You used an OLE item to specify a mirror item.

Action:	You cannot mirror OLE items. Use another item to specify a mirror item.


FRM-30368
FRM-30368:  Item specifies a tab page %s that does not exist.

Cause:	You specified an invalid tab page name.

Action:	Make sure the tab page name exists on the tab canvas for this item.


FRM-30369
FRM-30369:  Popup menu item specifies non-existent submenu %s.

Cause:	You specified an invalid submenu name.

Action:	Check the submenu name and try again.


FRM-30370
FRM-30370:  Popup menu must have at least one item.

Cause:	The popup menu has no items in it.

Action:	Add at least one menu item to the popup menu.


FRM-30373
FRM-30373:  Invalid command type specified for popup menu item.

Cause:	You selected a command type that is not valid for popup menu items.

Action:	Select a command type that is valid for popup menu items.


FRM-30374
FRM-30374:  Invalid item type for popup menu item.

Cause:	You selected an invalid item type for a popup menu item.

Action:	Select a valid item type.


FRM-30375
FRM-30375:  Datatype for non-Min/Max summary item must be Number.

Cause:	A summary item with a summary function of Count, Sum, Avg, Variance, or Stdev has a datatype other than Number.

Action:	Remove the summary item or change its datatype to Number.


FRM-30376
FRM-30376:  Datatype for Min/Max summary item must match summarized item.

Cause:	A summary item with a summary function of Min or Max has a datatype that does not match the datatype of the summarized item.

Action:	Remove the summary item or change its datatype to match the datatype of the summarized item.


FRM-30377
FRM-30377:  Summary item must reside in single-record block or in same block as summarized item.

Cause:	A summary item resides in a different block from the summarized item, and the summary item's block does not have its Single Record property set to Yes.

Action:	Move the summary item to the block that contains the summarized item, or to a block with the Single Record property set to Yes.


FRM-30378
FRM-30378:  Summarized item must not be summary item and must not reside in single-record block.

Cause:	A summary item specifies one of the following as its summarized item:

1. Another summary item.

2. An item in a block with the Single Record property set to Yes.

Action:	Remove the summary item, or change it to summarize a non-summary item in a block with the Single Record property set to No.


FRM-30379
FRM-30379:  Hint text can not exceed 255 chars.

Cause:	The hint text for the item is longer than 255 characters.

Action:	Reduce the number of characters in the hint text.


FRM-30380
FRM-30380:  There is a circular chain of dependent calculated items:

Cause:	There is a circular chain of calculated items, such that the value of each item in the chain depends on the value of the next item in the chain.

The items in the chain are listed below the error message.

Action:	Remove an item in the chain, or change an item in the chain so that it does not depend on any other item in the chain.

For a formula item, you must ensure that neither the formula nor any function or procedure that it calls refers to any item in the chain.

For a summary item, you must ensure that the item it summarizes is not in the chain.


FRM-30390
FRM-30390:  Warning: Hint property ignored for calculated item %s.%s.

Cause:	The Hint property was specified for a calculated item. It will be ignored.

Action:	No action required.


FRM-30391
FRM-30391:  Warning: Copy Value from Item property ignored for calculated item %s.%s.

Cause:	The Copy Value from Item property was specified for a calculated item. It will be ignored.

Action:	No action required.


FRM-30392
FRM-30392:  Warning: Initial Value ignored for calculated item %s.%s.

Cause:	The Initial Value property was specified for a calculated item. It will be ignored.

Action:	No action required.


FRM-30393
FRM-30393:  Warning: Highest Value Allowed ignored for calculated item %s.%s.

Cause:	The Highest Value Allowed property was specified for a calculated item. It will be ignored.

Action:	No action required.


FRM-30394
FRM-30394:  Warning: Lowest Value Allowed ignored for calculated item %s.%s.

Cause:	The Lowest Value Allowed property was specified for a calculated item. It will be ignored.

Action:	No action required.


FRM-30395
FRM-30395:  Other Values required for calculated item.

Cause:	The Mapping of Other Values property was not specified for a calculated item that is a check box, list item, or radio group.

Action:	Set the Mapping of Other Values property for the item.


FRM-30396
FRM-30396:  Summary Function required for summary item.

Cause:	The Summary Function property was specified as None for a summary item.

Action:	Set the Summary Function property to a value other than None.


FRM-30397
FRM-30397:  Warning: Summary Function ignored for non-summary item %s.%s.

Cause:	The Summary Function property was specified for an item which is not a summary item. It will be ignored.

Action:	No action is necessary. To prevent the warning in the future, set the Summary Function property to None.


FRM-30398
FRM-30398:  Summarized Block Name and Summarized Item Name properties are required for summary items.

Cause:	The Summarized Block Name and Summarized Item Name properties were not set for a summary item.

Action:	Specify values for the properties.


FRM-30399
FRM-30399:  Warning: Summarized Item Name ignored for non-summary item %s.%s.

Cause:	The Summarized Block Name or Summarized Item Name property was specified for an item which is not a summary item. It will be ignored.

Action:	No action required.


FRM-30400
FRM-30400:  Formula required for formula item.

Cause:	The Formula property was not specified for a formula item.

Action:	Specify the Formula property.


FRM-30401
FRM-30401:  Warning: Formula ignored for non-formula item %s.%s.

Cause:	The Formula property was specified for an item which is not a formula item. It will be ignored.

Action:	No action is necessary. To prevent the warning in the future, clear the Formula property.


FRM-30402
FRM-30402:  Calculated item cannot be an LOV return item.

Cause:	A calculated item is specified as a return item in the column mapping for an LOV.

Action:	Remove the return item, or specify an item that is not a calculated item.


FRM-30403
FRM-30403:  Calculated item cannot specify a mirror item, or be specified as a mirror item.

Cause:	A calculated item specifies a Mirror Item, or is specified as a Mirror Item by some other item in the block.

Action:	Remove the Mirror Item property. To make two calculated items effectively mirror each other, make one a formula item whose formula is simply ':' followed by the name of the other calculated item.


FRM-30404
FRM-30404:  Summarized item's Item Type must not be Button, Chart, Image, Sound, or OLE Container.

Cause:	A summary item specifies a summarized item which is a Button, Chart, Image, Sound, or OLE Container. Such an item has no associated data value and thus cannot be summarized.

Action:	Remove the summary item, or change its summarized item to be an item which has an associated data value.


FRM-30405
FRM-30405:  Datatype for Sum/Avg/Variance/Stddev summarized item must be Number.

Cause:	A summary item whose summary function is Sum, Avg, Variance, or Stdev specifies a summarized item with a datatype other than Number.

Action:	Remove the summary item or change its summarized item to have a datatype of Number.


FRM-30406
FRM-30406:  Block with array DML must have required primary key items.

Cause:	The block's DML Array Size property value is greater than 1, but no items have the Primary Key property set to Yes and one of the following is true:

1. The key mode for the block is either UPDATEABLE_PRIMARY_KEY or NON_UPDATEABLE_PRIMARY_KEY.

2. The datasource to which you are connected does not support UNIQUE key mode.

Action:	Do one of the following:

1. Specify a primary key for the data block by setting the Primary Key property value to Yes for one or more items.

2. Set the data block's DML Array Size property to 1.


FRM-30407
FRM-30407:  Block must have at least one database item.

Cause:	The form module contains a data block with no database items.

Action:	Define at least one database item for the data block.


FRM-30408
FRM-30408:  Invalid value.

Cause:	The value entered for the specified datatype is invalid.

Action:	Correct one or more of the following:

1. The datatype of the argument corresponding to the given value in the procedure argument list of the specified procedure.

2. The value of the argument in the procedure argument list of the specified procedure.


FRM-30409
FRM-30409:  Delete Record Behavior for the relation is invalid.

Cause:	The Delete Record Behavior of the relation is incompatible with its detail data block.

Action:	Modify one of the following:

1. The Delete Record Behavior of the relation.

2. The DML Data Target Type/Query Data Source Type of the detail data block. (If the Delete Record Behavior of the relation is Cascading, then the DML Data Target Type of the detail data block must be Table. If the Delete Record Behavior of the relation is Isolated, then the Query Data Source Type of the detail data block must be Table.)


FRM-30410
FRM-30410:  Warning: Single Record property ignored for non-control block %s.

Cause:	A block specifies the 'Single Record' property as 'Yes', but it also specifies a Query Data Source or a DML Data Target.

Action:	No action is necessary. To prevent the warning in the future, set the 'Single Record' property to 'No'.


FRM-30411
FRM-30411:  A memory allocation failed. Re-compile the form, specifying compile_all=yes.

Cause:	A memory allocation failed while calculated item dependency information was being computed.

Action:	Do one of the following. Compile the form module:

1. 'Stand-alone' (not from within Form Builder), specifying that all PL/SQL code is to be compiled.

2. On a machine with more memory.

3. On a machine running fewer concurrent jobs.


FRM-30413
FRM-30413:  Relation has no detail block.

Cause:	A master-detail relation specifies no detail block.

Action:	Specify a detail block.


FRM-30414
FRM-30414:  Relation's detail block does not exist.

Cause:	A master-detail relation specifies a non-existant detail block.

Action:	Specify a detail block that exists.


FRM-30415
FRM-30415:  Relation's detail block is a control block.

Cause:	A master-detail relation specifies a detail block that's a control block.

Action:	Specify a detail block that's a database block.


FRM-30416
FRM-30416:  Relation's master block is a control block.

Cause:	A master-detail relation specifies a master block that's a control block.

Action:	Specify a master block that's a database block.


FRM-30417
FRM-30417:  Relation's detail block is the same as its master block.

Cause:	A master-detail relation specifies a detail block that's the same block as the master block.

Action:	Specify distinct master and detail blocks.


FRM-30418
FRM-30418:  Block contains too many items (more than %d) for current platform.

Cause:	The number of items in this block exceeds the maximum allowable per block.

Action:	Use fewer items in the block, or divide the items into two or more separate blocks.


FRM-30419
FRM-30419:  Block scrollbar specifies a tab page %s that does not exist.

Cause:	A scrollbar is assigned to a tab page which does not exist in the form.

Action:	Check the tab page name and make sure it exists in the owning canvas for this scrollbar.


FRM-30420
FRM-30420:  Cannot compile QUERY-PROCEDURE trigger.

Cause:	Query procedure columns and/or Query procedure arguments are not declared properly.

Action:	Correct the Query procedure column definitions and/or Query procedure argument definitions.


FRM-30421
FRM-30421:  Cannot compile INSERT-PROCEDURE trigger.

Cause:	Insert procedure columns and/or Insert procedure arguments are not declared properly.

Action:	Correct the Insert procedure column definitions and/or Insert procedure argument definitions.


FRM-30422
FRM-30422:  Cannot compile UPDATE-PROCEDURE trigger.

Cause:	Update procedure columns and/or Update procedure arguments are not declared properly.

Action:	Correct the Update procedure column definitions and/or Update procedure argument definitions.


FRM-30423
FRM-30423:  Cannot compile DELETE-PROCEDURE trigger.

Cause:	Delete procedure columns and/or Delete procedure arguments are not declared properly.

Action:	Correct the Delete procedure column definitions and/or Delete procedure argument definitions.


FRM-30424
FRM-30424:  Cannot compile LOCK-PROCEDURE trigger.

Cause:	Lock procedure columns and/or Lock procedure arguments are not declared properly.

Action:	Correct the Lock procedure column definitions and/or Lock procedure argument definitions.


FRM-30425
FRM-30425:  Summarized database item must reside in a block with Query All Records or Precompute Summaries set to Yes.

Cause:	A summary item specifies a summarized item which is a database item in a database block whose Query All Records and Precompute Summaries properties are both set to No.

Action:	Remove the summary item or set the Precompute Summaries or Query All Records properties to Yes for the summarized item's block.


FRM-30426
FRM-30426:  Summarized control item must reside in a control block, or in a block with Query All Records set to Yes.

Cause:	A summary item specifies a summarized item which is a control item in a database block whose Query All Records property is set to No.

Action:	Remove the summary item or set the Precompute Summaries property to No and the Query All Records property to Yes for the summarized item's block.


FRM-30427
FRM-30427:  Summarized control item cannot reside in a block with Precompute Summaries set to Yes.

Cause:	A summary item specifies a summarized control item which is in a block with the Precompute Summaries property set to Yes.

Action:	Remove the summary item or set the Precompute Summaries property to No and the Query All Records property to Yes for the summarized item's block.


FRM-30428
FRM-30428:  Min/Max summarized item cannot reside in a block with Precompute Summaries set to Yes.

Cause:	A summary item with a summary function of Min or Max specifies a summarized item in a block with the Precompute Summaries property set to Yes.

Action:	Remove the summary item or set the Precompute Summaries property to No and the Query All Records property to Yes for the summarized item's block.


FRM-30429
FRM-30429:  Block with Precompute Summaries must specify Query Data Source Type as Table or FROM clause query.

Cause:	A block has its Precompute Summaries property set to Yes, but its Query Data Source Type is set to Procedure or Transactional Triggers.

Action:	Set Precompute Summaries to No.  If the block contains any summarized items, set Query All Records to Yes.


FRM-30430
FRM-30430:  Warning: block %s specifies Precompute Summaries but form's Isolation Mode is not Serializable.

Cause:	A block specifies Precompute Summaries as Yes, but the form does not specify Isolation Mode as Serializable.

Action:	No action is necessary.  However, read consistency cannot be guaranteed.  It is possible that actions by other users can occur between the time that summaries are precomputed and the time at which the query is initiated to populate the block.  Such actions may cause the summary item values not to match the block's contents.


FRM-30431
FRM-30431:  Warning: Duplicate column name %s in block %s.

Cause:	One of the following:

There are multiple items with the same database column name.

The column name of one item matches the item name of an item that does not have a column name.

Action:	Make sure that the database column names for items are unique.


FRM-30432
FRM-30432:  Definition for procedure is not complete.

Cause:	Either the columns or the arguments for the procedure are not specified.

Action:	Enter both the columns and the arguments in the procedure definition.


FRM-30433
FRM-30433:  Query procedure should have only one argument of type REFCURSOR/TABLE and its mode should be IN OUT.

Cause:	The query procedure definition has either:

1. No argument of type TABLE/REFCURSOR.

2. Multiple arguments of type TABLE/REFCURSOR.

3. An argument of type TABLE/REFCURSOR with a mode that is not defined as IN OUT.

Action:	Define the arguments as follows:

1. Define one and only one argument of type TABLE or REFCURSOR.

2. Declare the mode for the TABLE/REFCURSOR argument as IN OUT.


FRM-30434
FRM-30434:  The table argument in the procedure definition should have a type name.

Cause:	The type name for the TABLE argument in the given procedure is not entered.

Action:	Enter the type name for the TABLE argument in the given procedure.


FRM-30435
FRM-30435:  DML procedures should have only one argument of type TABLE and its mode should be IN or IN OUT.

Cause:	DML (Insert, Update, Delete, Lock) procedure defintion has either:

1. No argument of type TABLE.

2. Multiple arguments of type TABLE.

3. An argument of type TABLE with a mode defined as OUT.

Action:	Define the arguments as follows:

1. Define one and only one argument of type TABLE.

2. Declare the mode for the TABLE argument as IN or IN OUT.


FRM-30436
FRM-30436:  Parent window not specified for canvas.

Cause:	The canvas does not have a window specified to contain it. Default results are as follows:

1. In Forms 4.0, the canvas is attached to the ROOT_WINDOW.

2. In a Forms 4.5 application, the ROOT_WINDOW may not exist, so the canvas is automatically attached to the first window in the Object Navigator hierarchy.

3. In 5.0, it is possible to reference forms and override properties like Window Name. Thus, you always should set the Window Name property for the canvas.

Action:	Set the Window Name property for the canvas.


FRM-30437
FRM-30437:  Warning: POST-CHANGE trigger ignored for subordinate mirror item %s.%s.

Cause:	A POST-CHANGE trigger was specified for a subordinate mirror item.  Since the form's Runtime Compatibility Mode is 5.0, the POST-CHANGE trigger will be obtained from the master mirror item (the item specified by the Synchronize with Item property).

Action:	Specify the POST-CHANGE trigger in the master mirror item.


FRM-30438
FRM-30438:  Warning: WHEN-VALIDATE-ITEM trigger ignored for subordinate mirror item %s.%s.

Cause:	A WHEN-VALIDATE-ITEM trigger was specified for a subordinate mirror item.  Since the form's Runtime Compatibility Mode is 5.0, the WHEN-VALIDATE-ITEM trigger will be obtained from the master mirror item (the item specified by the Synchronize with Item property).

Action:	Specify the WHEN-VALIDATE-ITEM trigger in the master mirror item.


FRM-30439
FRM-30439:  Warning: ON-SEQUENCE-NUMBER trigger ignored for subordinate mirror item %s.%s.

Cause:	An ON-SEQUENCE-NUMBER trigger was specified for a subordinate mirror item.  Since the form's Runtime Compatibility Mode is 5.0, the ON-SEQUENCE-NUMBER trigger will be obtained from the master mirror item (the item specified by the Synchronize with Item property).

Action:	Specify the ON-SEQUENCE-NUMBER trigger in the master mirror item.


FRM-30440
FRM-30440:  Warning: Copy Value from Item ignored for subordinate mirror item %s.%s.

Cause:	The Copy Value from Item property was specified for a subordinate mirror item.  Since the form's Runtime Compatibility Mode is 5.0, the Copy Value from Item property will be obtained from the master mirror item (the item specified by the Synchronize with Item property).

Action:	Specify the Copy Value from Item property in the master mirror item.


FRM-30441
FRM-30441:  Warning: Initial Value ignored for subordinate mirror item %s.%s.

Cause:	The Initial Value property was specified for a subordinate mirror item.  Since the form's Runtime Compatibility Mode is 5.0, the Initial Value property will be obtained from the master mirror item (the item specified by the Synchronize with Item property).

Action:	Specify the Initial Value property in the master mirror item.


FRM-30442
FRM-30442:  Warning: Required property ignored for subordinate mirror item %s.%s.

Cause:	The Required property was specified for a subordinate mirror item.  Since the form's Runtime Compatibility Mode is 5.0, the Required property will be obtained from the master mirror item (the item specified by the Synchronize with Item property).

Action:	Specify the Required property in the master mirror item.


FRM-30443
FRM-30443:  Warning: Highest Value Allowed ignored for subordinate mirror item %s.%s.

Cause:	The Highest Value Allowed property was specified for a subordinate mirror item.  Since the form's Runtime Compatibility Mode is 5.0, the Highest Value Allowed property will be obtained from the master mirror item (the item specified by the Synchronize with Item property).

Action:	Specify the Highest Value Allowed property in the master mirror item.


FRM-30444
FRM-30444:  Warning: Lowest Value Allowed ignored for subordinate mirror item %s.%s.

Cause:	The Lowest Value Allowed property was specified for a subordinate mirror item.  Since the form's Runtime Compatibility Mode is 5.0, the Lowest Value Allowed property will be obtained from the master mirror item (the item specified by the Synchronize with Item property).

Action:	Specify the Lowest Value Allowed property in the master mirror item.


FRM-30445
FRM-30445:  Use of the Include REF Item property requires non-null Alias property.

Cause:	The Include REF Item property for this block is TRUE, which causes the creation of a new hidden item called REF that contains the object ID for this block.  The column name for this new item is 'REF(a)' where 'a' is the value of the block's Alias property.  The Alias property must not be null.

Action:	Specify a non-null value for the block's Alias property.


FRM-31601
FRM-31601:  Options -e, -g, -m, -p, and -r are mutually exclusive.

Cause:	You specified more than one of these options.

Action:	These options are mutually exclusive; do not use them in combination.


FRM-31602
FRM-31602:  No module name specified.

Cause:	You did not specify a module name.

Action:	Specify a module name.


FRM-31603
FRM-31603:  No username to grant/revoke.

Cause:	You tried to grant Form Builder access to a user, or revoke access, but you did not specify the user.

Action:	Re-execute the command and specify the username.


FRM-31605
FRM-31605:  Module %s unknown.

Cause:	You tried to access a module that does not exist in the database.

Action:	Make sure the module name is correct and try again.


FRM-31606
FRM-31606:  Could not open file %s.

Cause:	Either file privileges are set incorrectly, or the library you attempted to open is invalid.

Action:	Recompile the module library and try again.


FRM-31616
FRM-31616:  Warning! No items defined for menu %s.

Cause:	You are generating a module that has a menu which contains no items.

Action:	No action required.


FRM-31627
FRM-31627:  Circular reference detected in menu module.

Cause:	The menu module you tried to compile contains circular references (instances where a menu item calls a menu that is above it in the hierarchy).

Action:	Isolate and resolve the circular reference(s).


FRM-31628
FRM-31628:  Item references an undefined menu.

Cause:	The item references a submenu that is not part of the module.

Action:	Define a submenu as part of the module or make the item reference a submenu that is part of the module.


FRM-31629
FRM-31629:  Build errors written to file %s.

Cause:	Compilation error.

Action:	Refer to errors and warnings in the specified file.


FRM-31631
FRM-31631:  Could not close file %s.

Cause:	An operating system error prevented Form Builder from closing an output file.

Action:	Contact your DBA or an Oracle support representative.


FRM-31633
FRM-31633:  Main menu %s not found in module.

Cause:	The menu name specified does not exist in this module.

Action:	Make sure a menu with this name exists.


FRM-31634
FRM-31634:  Error writing file %s.

Cause:	You lack privileges in the specified directory, or you do not have the disk space required.

Action:	Contact your DBA to make sure you have the access privileges you need.


FRM-31635
FRM-31635:  No menu in specified file.

Cause:	The file was loaded, but no menu module was found in the file.

Action:	Make sure the file is a MMB file.


FRM-31637
FRM-31637:  Error performing upgrade.  Upgrade aborted.

Cause:	SQL error deleted while performing menu upgrade.

Action:	Make sure you are running as SYSTEM, and  both Oracle Forms 4.5 and the menu tables are correctly installed.


FRM-31639
FRM-31639:  No modules to upgrade.

Cause:	No module was specified that does not already exist in Oracle Forms 4.5 tables.

Action:	Make sure that no menu module with this name already exists in Oracle Forms 4.5.


FRM-31640
FRM-31640:  Submenu name not specified.

Cause:	A menu item of type menu has no menu specified.

Action:	Specify a submenu for the menu item.


FRM-31641
FRM-31641:  Radio group items must have radio group name specified.

Cause:	Menu item was defined as type radio button, but no radio group was specified.

Action:	Specify a radio group name.


FRM-31643
FRM-31643:  Menu %s does not exist.

Cause:	The menu item was defined as type menu, but the menu it refers to does not exist.

Action:	Create a menu with this name.


FRM-31644
FRM-31644:  Menu %s has no items.

Cause:	You did not supply choices for a menu.

Action:	Edit your form to supply items within the menu.


FRM-31645
FRM-31645:  Only one instance of each magic menu type per module is allowed.

Cause:	You used more than one instance of a specific magic menu type.

Action:	Delete all but one instance of each magic menu type.


FRM-31646
FRM-31646:  Magic menu item %s has invalid command type.

Cause:	You selected a command type that is not valid for the specific magic menu item.

Action:	Select a command type that is compatible with the current magic menu item type.


FRM-31649
FRM-31649:  Label for menu item %s is too long.

Cause:	You specified a menu item label which has more than the maximum allowable number of characters.

Action:	Shorten the menu item label.


FRM-31650
FRM-31650:  Name of menu item %s is too long.

Cause:	You specified a menu item name which has more than the maximum allowable number of characters.

Action:	Shorten the menu item name.


FRM-31651
FRM-31651:  No PL/SQL source code in menu item %s.

Cause:	You specified a menu item name which has command type PL/SQL but has no Command Text.

Action:	Either change the command type to Null, or specify some Command Text.


FRM-32009
FRM-32009:  Premature end of file at line %05d.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-32010
FRM-32010:  Input file sequence error at line %05d.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-32011
FRM-32011:  File doesn't contain valid Run Form source.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-32035
FRM-32035:  Illegal field type (%s) in %s.%s.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-32036
FRM-32036:  Warning! Prompt above line 1 for %s.%s.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-32037
FRM-32037:  Warning! Prompt doesn't fit beside field %s.%s.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-32041
FRM-32041:  Expected: %s:    %s

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-32042
FRM-32042:  Error (line %05d): expected Yes/No answer, received %s.

Cause:	You entered something other than Yes or No.

Action:	Answer either Yes or No.


FRM-32051
FRM-32051:  Illegal command in form text at line %05d.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.

Cause:	The error commonly occurs when the .INP file is edited.

Action:	Contact your DBA if the .INP file was not edited.


FRM-32079
FRM-32079:  Invalid initial value for given datatype.

Cause:	You specified an invalid initial value for the given datatype.

Action:	Specify a valid initial value for the given datatype.


FRM-32080
FRM-32080:  Invalid range value for given datatype.

Cause:	You specified an invalid range value for the given datatype.

Action:	Specify a valid range value for the given datatype.


FRM-32081
FRM-32081:  Invalid default parameter value for given datatype.

Cause:	You specified an invalid default parameter value for the given datatype.

Action:	Specify a valid default parameter value for the given datatype.


FRM-32082
FRM-32082:  Invalid value for given item type.

Cause:	You tried to specify a value for the initial value property or other values property that exceeds the value of the maximum length property.

Action:	Specify a value that does not exceed the value of the maximum length property.


FRM-32083
FRM-32083:  Value length is too long for maximum length of item.

Cause:	You specified an value length that is longer than the maximum length of the item.

Action:	Specify a shorter value.


FRM-32084
FRM-32084:  Type of item is not compatible with mirror item %s.

Cause:	You specified an item that is an incompatible mirror item property.

Action:	Specify a valid mirror item property.


FRM-32085
FRM-32085:  Strip_Source requires output filename.

Cause:	You failed to specify an output file name when generating a library from the command line.

Action:	Specify an output file name.


FRM-32086
FRM-32086:  Bind Variable :%s parse failed at <%s>.

Cause:	The bind variable could not be parsed due to an invalid format.

Action:	Change to a valid format.


FRM-32087
FRM-32087:  Bind Variable :%s binds to more than one object.

Cause:	The bind variable is ambiguous since it binds to more than one object.

Action:	Make sure the bind variable binds to one object only.


FRM-99999
FRM-99999:   Error %d occurred.  See the release notes file (relnotes) for information about this error.

Cause:	An error occurred; the error is documented in the release notes file.

Action:	See the release notes file.


FRM-10200
FRM-10200:  Illegal function in this context.

Cause:	You pressed a key that is not valid in this context.

Action:	Press [Show Keys] to view a list of valid function keys.


FRM-10201
FRM-10201:  No parameters needed.

Cause:	You pressed [Enter Application Parameters] or [Enter Menu Parameters], but none are required in this context.

Action:	No action required.


FRM-10202
FRM-10202:  Menus are nested too deeply.

Cause:	You tried to select an item that would nest menus more than 10 deep.

Action:	Press [Main Menu] to return to the main menu, then navigate to the menu of your choice.


FRM-10203
FRM-10203:  Selected item is not in this menu.

Cause:	In a full-screen menu, you entered a number that exceeds the maximum number of menu items.

Action:	Choose an item that is on this menu.


FRM-10204
FRM-10204:  No command defined for the selected background item.

Cause:	You pressed [Background Menu n], where n was greater than the maximum number on the background menu.

Action:	No action required. Press [Show Background Menu] to see the valid background menu items.


FRM-10205
FRM-10205:  Menu %s not found.

Cause:	In the choice field of a full-screen menu, you entered a menu name that does not exist in this application or is not found in the library.

Action:	No action is required if the menu does not exist in the application. If it does, recompile the library.


FRM-10206
FRM-10206:  Dynamic memory exhausted.

Cause:	Form Builder has run out of memory.

Action:	Contact your DBA.


FRM-10207
FRM-10207:  No background menu present.

Cause:	You pressed [Show Background Menu], but no background menu exists.

Action:	No action required.


FRM-10208
FRM-10208:  Parameter %s not found.

Cause:	A menu item referenced an undefined parameter.

Action:	Contact your DBA.


FRM-10209
FRM-10209:  No next menu from background in this context.

Cause:	The application attempted to navigate to a named menu from the background menu.

Action:	No action required.


FRM-10210
FRM-10210:  Response required.

Cause:	You did not enter a required parameter, or you left the choice field blank in a full-screen menu.

Action:	Make an entry.


FRM-10211
FRM-10211:  Field must be filled completely.

Cause:	You partially entered a parameter that must be entered completely.

Action:	Enter enough data to completely fill the field.


FRM-10212
FRM-10212:  Login failed for this username and password.

Cause:	You specified an illegal username and password.

Action:	Check the username and password and try again.


FRM-10213
FRM-10213:  Login procedure terminated.

Cause:	You failed to logon to ORACLE three times in a row.

Action:	No action required. If you are a valid user, check your user name and password.


FRM-10214
FRM-10214:  No authorization to run any application.

Cause:	You are not a valid user of any module in Form Builder.

Action:	No action required. If you think that you should be a valid user, ask your DBA to grant you access to the module you wish to run.


FRM-10215
FRM-10215:  No help available.

Cause:	You pressed [Help], but none is available for this item.

Action:	No action required.


FRM-10216
FRM-10216:  Failed to spawn a command to the operating system.

Cause:	The operating system could not spawn a sub-process.

Action:	Refer to the error message that the operating system issued.


FRM-10217
FRM-10217:  No authorization for any item in selected menu.

Cause:	You tried to move to a menu that has no items you can access.

Action:	Check the menu name you entered and try again.


FRM-10218
FRM-10218:  Error for menu %s.

Cause:	Form Builder could not read the library information for this menu, or an invalid menu name was specified.

Action:	Recompile the library or correct the menu name.


FRM-10219
FRM-10219:  Item number is invalid.

Cause:	In a full-screen menu, you entered an invalid number in the choice field.

Action:	Check the item number and re-enter it.


FRM-10220
FRM-10220:  No detailed help available for this item.

Cause:	You pressed [Help], but none is available for this menu item.

Action:	No action required.


FRM-10221
FRM-10221:  Cannot read file %s.

Cause:	Either file privileges are set incorrectly, or the library you tried to open is invalid.

Action:	Recompile the application library and try again.


FRM-10222
FRM-10222:  Menu %s was created by an old version of Forms Compiler.

Cause:	You are using a newer version of Form Builder than the one that created this menu module.

Action:	Recompile the menu module and re-execute the command.


FRM-10223
FRM-10223:  Application parameter module does not exist.

Cause:	The parameter information could not be located in the library. This may be due to a library file that is invalid, or one that contains a different application.

Action:	Recompile the application library and try again. If this is unsuccessful, contact your DBA.


FRM-10224
FRM-10224:  Application bind variable module does not exist.

Cause:	The bind variable information could not be located in the library. This may be due to an invalid library file.

Action:	Recompile the application library and try again. If this is unsuccessful, contact your DBA.


FRM-10225
FRM-10225:  Could not read parameter data.

Cause:	The application library is invalid.

Action:	Recompile the application library and try again. If this is unsuccessful, contact your DBA.


FRM-10226
FRM-10226:  Could not read bind variable data.

Cause:	The application library is invalid.

Action:	Recompile the application library and try again. If this is unsuccessful, contact your DBA.


FRM-10227
FRM-10227:  Too many menu parameters.

Cause:	The application contains more menu parameters than can be used on your operating system.

Action:	Revise and recompile the application, or contact your DBA.


FRM-10228
FRM-10228:  Could not read help text.

Cause:	The application library is invalid.

Action:	Recompile the application library and try again. If this is unsuccessful, contact your DBA.


FRM-10229
FRM-10229:  Could not close file %s.

Cause:	Operating system error or internal error.

Action:	Contact your DBA.


FRM-10230
FRM-10230:  Application procedure module does not exist.

Cause:	The procedure information could not be located in the library. This may be due to an invalid library file.

Action:	Recompile the application library and try again. If this is unsuccessful, contact your DBA.


FRM-10231
FRM-10231:  Could not read procedure data.

Cause:	The application library is invalid.

Action:	Recompile the application library and try again. If this is unsuccessful, contact your DBA.


FRM-10233
FRM-10233:  Navigational procedures/macros not valid in current menu style.

Cause:	You tried to use the full-screen, navigational packaged procedures, or macros in the pull-down or menu bar display style.

Action:	Notify your DBA.


FRM-10234
FRM-10234:  Semicolon missing in macro statement.

Cause:	The command line specified for this item has a syntax error.

Action:	Notify your DBA.


FRM-10235
FRM-10235:  Macro %s not found.

Cause:	The menu designer specified an undefined macro to be executed.

Action:	Notify your DBA.


FRM-10236
FRM-10236:  No procedure/macro specified.

Cause:	The menu designer has specified a blank command.

Action:	Notify your DBA.


FRM-10237
FRM-10237:  Argument(s) not allowed for this procedure/macro.

Cause:	The menu designer specified an argument to a command that does not take arguments.

Action:	Notify your DBA.


FRM-10238
FRM-10238:  Error executing %s.  Check argument(s).

Cause:	The menu designer specified an argument to a command that does not take arguments.

Action:	Notify your DBA.


FRM-10239
FRM-10239:  Cannot read form by that name.

Cause:	Form Builder tried to read a form that does not exist in the current directory.

Action:	Notify your DBA.


FRM-10240
FRM-10240:  Form name not specified.

Cause:	Forms Runtime command did not give the name of a form to execute.

Action:	Notify your DBA.


FRM-10241
FRM-10241:  Illegal operation when Form Builder is active.

Cause:	The menu designer specified a built-in or macro that cannot be used when Form Builder calls Forms Runtime.

Action:	Notify your DBA.


FRM-10242
FRM-10242:  Cannot call linked-in Forms from Form Builder.

Cause:	The menu designer specified a call to linked-in Forms from within Form Builder.

Action:	Notify your DBA.


FRM-10243
FRM-10243:  Error occurred during invocation of Form Builder.

Cause:	A call to Forms Runtime failed.

Action:	Notify your DBA.


FRM-10244
FRM-10244:  Application %s does not exist.

Cause:	The application name you specified does not exist in the database, or you do not have access privileges to it.

Action:	Check the application name and try again, or contact your DBA.


FRM-10245
FRM-10245:  Already on first item.

Cause:	You pressed [Previous Item] from the first item in the parameter form.

Action:	No action required. You cannot go to an item prior to the first item in a parameter form.


FRM-10246
FRM-10246:  Error executing packaged procedure - inactive form.

Cause:	The menu designer specified a built-in that cannot be executed in the current context.

Action:	Notify your DBA.


FRM-10247
FRM-10247:  No active items in root menu of application.

Cause:	You tried to open an application but its root menu has no items that you can access. The root menu is either the application's main menu or another menu specified when Form Builder called Forms Designer.

Action:	Notify your DBA.


FRM-10248
FRM-10248:  No direct menu selection allowed when using a root menu.

Cause:	The root menu is not the module's main menu, because Form Builder specified another root menu when calling Forms Designer.

Action:	No action required. You can only use direct menu selection when the module's main menu is the root menu.


FRM-10249
FRM-10249:  No authorization to run application %s.

Cause:	You are not a valid user of the application you tried to run.

Action:	No action required. If you think you should be a valid user, ask your DBA to grant you access privileges to the application.


FRM-10251
FRM-10251:  Unsupported command type 4 switch used (-e,-i,-r,-w).

Cause:	This menu option attempted to run a form, but specified a command line argument for Forms Runtime which is invalid when running a form from a menu.

Action:	Notify your DBA.


FRM-10252
FRM-10252:  Unknown command type 4 switch used.

Cause:	This menu option attempted to run a form, but specified an unknown command line argument for Forms Runtime.

Action:	Notify your DBA.


FRM-10253
FRM-10253:  File name must be entered.

Cause:	You have not entered a name (or you have deleted a name) for the file.

Action:	You must enter a file name.


FRM-10254
FRM-10254:  Cannot open file for screen shot.

Cause:	The operating system could not open a file (e.g. permission problems, lack of disk space).

Action:	Resolve the operating system condition that caused the error.


FRM-10255
FRM-10255:  Error occurred during printing of screen shot.

Cause:	The operating system had trouble with a file.

Action:	Resolve the operating system condition that caused the error.


FRM-10256
FRM-10256:  User is not authorized to run Form Builder Menu.

Cause:	You are not enrolled in Form Builder. You do not have SELECT permission on the Form Builder base tables.

Action:	Notify your DBA.


FRM-10257
FRM-10257:  User is not authorized to select specified option.

Cause:	You tried to select a menu item to which you do not have access.

Action:	Choose another item or notify your DBA.


FRM-10258
FRM-10258:  Specified menu is already active.

Cause:	You tried to navigate to the current menu.

Action:	No action required.


FRM-10259
FRM-10259:  Invalid null argument to packaged procedure or function.

Cause:	You did not specify an argument to a built-in, or the argument is invalid.

Action:	Check the online Help for the proper built-in syntax.


FRM-10260
FRM-10260:  No active items in selected menu.

Cause:	You do not have access privileges for any items in this menu.

Action:	Contact your DBA for access privileges if you think you should have access to the items on this menu.


FRM-10261
FRM-10261:  Menu %s was created by a new version of Forms Compiler.

Cause:	You are using an old version of Forms Runtime with a new version of Forms Compiler.

Action:	Upgrade to new version of Forms Runtime.


FRM-10262
FRM-10262:  Cannot put radio items, check boxes, or separators in menu bar.

Cause:	You attempted to put radio items, check boxes, or separators in menu bar.

Action:	Put these items in a submenu.


FRM-10263
FRM-10263:  Cannot find icon file for iconic menu item.

Cause:	No directory name for this icon.

Action:	Contact the person who created the menu application.


FRM-10264
FRM-10264:  Specified menu item does not exist.

Cause:	You specified a menu item that does not exist in the form.

Action:	Try retyping the name or choose another item name.


FRM-10265
FRM-10265:  Library was created by an old version of Forms Compiler.

Cause:	Form Builder cannot use library.

Action:	Recompile the library with current version of Forms Compiler.


FRM-10266
FRM-10266:  Library was created by a new version of Forms Compiler.

Cause:	Form Builder cannot use library.

Action:	Recompile the library with current version of Forms Compiler.


FRM-10267
FRM-10267:  Help type magic menu item must be placed on top-level menu.

Cause:	You placed a help magic menu item on a submenu.

Action:	Move the help magic menu item to the top-level menu (main menu).


FRM-10268
FRM-10268:  Error: Program unit %s in library %s is uncompiled.

Cause:	You called an uncompiled program unit from a library.

Action:	Follow the PL/SQL program error.


FRM-10269
FRM-10269:  Warning! Program unit %s in library %s is uncompiled.

Cause:	In debug Forms Runtime, you called an uncompiled program unit in a library.

Action:	This is just a warning. Forms Runtime will attempt to compile and run the program unit.


FRM-10270
FRM-10270:  Cannot attach library %s while opening menu %s.

Cause:	The specified library file is attached to the given menu, but cannot be located in the search path for PL/SQL libraries.

Action:	Make sure the library file can be located before attempting to run with the specified menu again. For example, have it in the working directory.


FRM-10402
FRM-10402:  No such application present.

Cause:	The requested application could not be found in order to be documented.

Action:	Make sure that the correct application name is specified.


FRM-10409
FRM-10409:  Cannot close file.

Cause:	Operating system error or internal error.

Action:	Contact your DBA.


FRM-10410
FRM-10410:  Wrong descriptor area selected.


FRM-10411
FRM-10411:  Unable to allocate dynamic memory for descriptor area.


FRM-10412
FRM-10412:  Non-supported ORACLE datatype selected.


FRM-21011
FRM-21011:  PL/SQL unhandled exception %s.


Preferences

General Tab Preferences

Save Before Building

Build Before Running

Suppress Hints

Use System Editor

Color Palette

Color Mode

Printer

Run Modules Asynchronously

Access Tab Preferences

Access

Subclassing Path

Wizards Tab Preferences

Welcome Dialog

Wizard Welcome Pages

Runtime Tab Preferences

Buffer_Records in File

Debug Messages

Array Processing

Optimize SQL Processing

Optimize Transaction Mode Processing

Statistics

Display Block Menu

Query Only Mode

Quiet Mode

HTML File Name


Options Dialog

Designer Tab Options

Color Mode

Color Palette

Generate Before Run

Object Access

Printer

Run Modules Asynchronously

Save

Suppress Hints

Save Before Generate

Suppress Hints

Use System Editor

Runtime Tab Options

Array Processing

Buffer Records in File

Debug Mode

Display Block Menu

Optimize SQL Processing

Optimize Transaction Mode Processing

Query Only Mode

Quiet Mode

Statistics


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).


About image types

You can incorporate two types of images into a Form Builder application:

•	Graphic Objects  A graphic object is a static image (either vector or bitmap) that you import from the file system or database and use as a static graphical element in your application.  Graphic objects are often used as background pictures.  When you save and compile a form module, graphic objects are incorporated into the .FMB and .FMX files.  You can manipulate graphic objects in the Layout Editor as you would other objects.

•	Image Items  An image item is an interface control that stores and/or displays either vector or bitmap images.  Like other items that store values, an image item can be a data block item (that relates directly to a database column) or a control item.  When you save and compile a form module, image items are incorporated into the .FMB and .FMX files, but no image file is actually associated with an image item until the item is populated at runtime.

At runtime, end users can navigate to and select image items, but cannot navigate to or select graphic objects.


About image formats

Form Builder supports numerous graphics file formats.  The table below indicates the format type (bitmap image or vector drawing), and shows whether the format can be used for graphic objects or image items.

Format	Graphic Text and Objects	Image  Items	Feature	Compression
BMP	Y	Read/Write	Monochrome, 4 and 8-bit LUT, 24-bit RGB	none
JFIF	Y	Read/Write	24-bit RGB	JPEG
PCX	Y	Read Only	Monochrome; 2, 4, and 8-bit LUT; 1, 2, and 8-bit RGB	RLE
PICT 1 & 2	Y	Read/Write	Monochrome; 2, 4, and 8-bit LUT; 16 and 24-bit RGB, vector/object graphics	Packbits
GIF	Y	Read/Write	8-bit LUT	LZW
CALS	Y	Read/Write	Monochrome	CCITT G4 (FAX)
PCD	Y	Read Only	Monochrome, 4 and 8-bit LUT, 24-bit RGB	(Kodak)
RAS	Y	Read/Write	Monochrome, 4 and 8-bit LUT, 24-bit RGB	RLW
TIFF 4, 5, & 6	Y	Read/Write	Monochrome, 8-bit gray, 4 and 8-bit LUT, 24-bit RGB, Planar data, Tiled data, Intel byte order, Motorola byte order, Photometric interpretation, MSB/LSB	Packbits, CCITT G3 (FAX), CCITT G4 (FAX), LZW, LZW with horizontal difference, JPEG


About image items and memory allocation

  Related Topics

When you create image items in a data block, Form Builder allocates the necessary memory for records that are fetched from the database, regardless of whether that record is currently displayed.

To conserve client memory when displaying large image items, reduce the number of records that are buffered for the block (i.e., the number of records Form Builder should attempt to fetch at one time).  To do this, you can set the Number of Records Buffered block property.  The minimum allowable setting is the value of the Number of Records Displayed block property + 2.

Note:  Images and drawings are always stored in the database in their own format, unless you set the Image Format property for the image item.  Thus, if you set the Image Format property to GIF for an image item, then execute READ_IMAGE_FILE to populate the item with a TIFF file, and then issue a commit, Form Builder inserts the image in the corresponding LONG RAW column in GIF format (if possible).

Note also that PCX and PCD can be read from the file system but cannot be written with WRITE_IMAGE_FILE.


Importing a graphic object

To import a graphic object:

1	In the Layout Editor, choose File [image] Import [image] Image to display the import image dialog.

2	Click a radio button (either Database or File) to specify whether the image you are importing is from the database or from the file system, then type the name of your image.

3	To specify the graphics format of the image, select a value from the Format (valid only for images stored in the file system).

4	Select a value from the Quality poplist to specify the graphic quality of the image.

Note:  To optimize image quality and memory-consumption, set the image quality and image dither options to balance the trade-off between the two.  To set these options, select the image in the Layout Editor, then choose Format [image] Graphics Options [image] Image.

5	Click OK to import the image.

Form Builder places the imported graphic object in the center of the drawing area.  (When you import a graphic object into your form, you place it on a specific canvas.)

Tip:  Remember that you can place interface items on top of graphic objects.  For instance, you might place buttons on top of a map to allow end users to get information about specific regions.


Creating an image item

To create an image item:

1	In the Object Navigator, click the plus icon [image] beside the desired block node.

Form Builder expands the block node and displays its subnodes.

2	Click the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon beside the new item to display the Property Palette.

5	Under the General node, set the Item Type property to Image.

6	Use the Property Palette or Layout Editor to set the image item's display appearance.

Keep the following in mind when working with image items:

•	The datatype of an image item is preset to LONG RAW (the Datatype property does not appear on the Property Palette for an image item).

•	Set the Compression Quality property to tell Form Builder the degree to which you wish the image to be compressed when it is read into the form.  This compression occurs regardless of whether the image file was compressed in the file system.

•	Set the Sizing Style property to tell Form Builder how to display images that are larger than the image item's border.  Choose Crop to have Form Builder display the image at its actual size, even if a portion of the image lies outside the image item's borders. Choose Adjust if you want Form Builder to scale the image so it fits entirely inside the image item's borders.


Populating an image item

  Related Topics

Recall that although the definition of an image item is stored as part of the form module .FMB and .FMX files, no image file is actually associated with an image item until the item is populated at runtime.

Image items can be populated in the following ways:

•	a fetch from a LONG RAW database column

An image item in a data block is populated automatically when the end user or the application executes a query in the block.  When a fetched image is modified or replaced, Form Builder marks that record as Changed, and the next commit operation saves the new image to the corresponding LONG RAW column in the database.

Note:  You cannot write a SELECT statement to select a LONG RAW value INTO an image item.

•	executing the READ_IMAGE_FILE built-in to read an image from the file system

(To dynamically write an image from an image item out to a file, use the built-in procedure WRITE_IMAGE_FILE.)

•	paste an image from the clipboard into an empty image item.

At runtime, simply cut or copy an image to the clipboard, click in an empty image item, then choose Edit [image] Paste.  The pasted image adopts the scaling of the image item into which you paste it.  Adjust the image item's Sizing Style property accordingly -- either Crop or Adjust.


Manipulating image items at runtime

  Related Topics

Image items can be manipulated at runtime in two ways:  by end users (with the image palette, if it's displayed), and programmatically.

Using the Image Palette  If you set an image item's Show Palette property to Yes, Form Builder will display an image-manipulation palette adjacent to the item at runtime.  End users then can use the three palette tools to manipulate the image inside.

The three image-manipulation palette tools are:

•	the Image Palette Zoom button  Zoom:  click the tool, then repeatedly click the image to incrementally reduce the amount of the source image displayed within the image item's borders.

•	  Pan:  click the tool and use the grab hand to pan unseen portions of the source image into view (valid only if the source image extends beyond at least one border of the image item).

•	  Rotate:  click the tool, then repeatedly click the image to rotate it clockwise in 90-degree increments.

Manipulating Image Items Programmatically  To respond to image item events, use the following triggers:

•	When-Image-Activated (fires when the end user double-clicks an image item)

•	When-Image-Pressed (fires when an end user clicks or double-clicks on an image item)

You also can use the IMAGE_ZOOM built-in to the manipulate the images contained in image items.


Creating a chart item

To create a chart item:

1	In the Object Navigator, click the desired block.

2	Choose Tools [image] Layout Editor.

3	In the Layout Editor, click  [image]  in the toolbar, then follow the wizard to create a chart item.


Creating graphic text

  Related Topics

To create graphic text:

1	In the Layout Editor, click the Text tool in the tool palette.

2	Click in the region where you want to place text.

3	Type the desired text.

The text object's bounding box grows as you enter text.  Use carriage returns to wrap to the next line as desired.

4	Click outside the text object's bounding box to exit text mode.

Note:  When the Scalable Bounding Box option in the Text Drawing Options dialog is enabled, you can create a graphic text object by clicking and dragging until the bounding box is the size you want.  Text wraps to the next line automatically when you reach the right side of the text object's bounding box.  To invoke the Graphics Options dialog, select Format [image] Graphics Options [image] Text.  To enable the Scalable Bounding Box option, click Fixed Bounding Box.


Editing graphic text

To edit graphic text:

1	Click the Text tool in the Layout Editor tool palette.

2	Click the graphic text object you want to edit.

The text insertion point appears in the text object.

3	Edit the text as desired.

4	Click outside the text object's bounding box to exit text mode.


Creating line graphics

  Related Topics

To create rectangles, lines, ellipses, and arcs:

1	in the Layout Editor, select the tool you want to use by clicking the tool in the tool palette.

2	Position the pointer where you want to start drawing the graphic.

3	Click and drag until the graphic is the size you want, then release.

Note:  When you create a new arc the default sweep angle is 90 degrees.  You can use the Reshape tool to change the default angle.

To create polygons and polylines:

1	In the Layout Editor, select the Polygon or Polyline tool.

2	Position the pointer where you want the first segment to start and click once.

3	Move the pointer until the first line segment is the length and angle you want, then click to mark the endpoint of the segment.

4	Continue clicking and moving to define each segment of the polygon.

5	Double-click to mark the endpoint of the last segment.

When you use the Polygon tool, Form Builder adds a final line segment to connect the end point to the start point.

To use the Freehand tool:

1	Select the Freehand tool.

2	Position the pointer where you want to start drawing.

3	Click and drag to draw the desired freehand graphic.


Constraining graphic tools

You can constrain the operation of graphic tools by holding down the [Constrain] key (Shift on most platforms).

Constrained tools operate as follows:

Tool	Constrained Result
Ellipse	Circle
Line, Polygon	Horizontal, vertical, or diagonal angles
Polyline, Rectangle	Horizontal, vertical, or diagonal angles
Rectangle	Square
Rounded Rectangle	Rounded square
Arc	Circle


About creating interface items

When you create an item, you either insert a new item into a block or you modify an existing item by converting its type.


About buttons

  Related Topics

Buttons are interface items that end users select to execute commands or initiate actions.  Buttons can be used to initiate navigation, display LOVs, invoke an editor or window, commit data in a form, issue a query, or perform almost any other operation that can be coded with PL/SQL.

Form Builder supports two button styles: text and iconic. Text buttons are displayed with a text label on the button. Iconic buttons are displayed with a bitmapped graphic on the button and are often used in toolbars for this reason.

Runtime Behavior  On GUI platforms, a text button is displayed as a rectangle with a text label inside that describes the button's action.  On character mode platforms, a text button appears as a text string enclosed by parentheses.

Iconic buttons are displayed as graphic icons, without text labels.  Iconic buttons can be displayed only on GUI platforms.

Note:  On Microsoft Windows, button color attributes are controlled exclusively by the Color facility in the Control Panel.  To define button color attributes (button face, button shadow, button text color, button or highlight), you must use the Color facility.


About navigating to buttons

  Related Topics

End users navigate to buttons by using the mouse or a Form Builder function key.  When the end user uses a function key to navigate to a button, button visitation is determined by the button's position in the Object Navigator.


About selecting buttons

  Related Topics

End users select a button by clicking it with the mouse.  The command or action associated with the button is initiated when the mouse button is released.  The input focus can be in any item in the form when the button is selected, and end users do not have to navigate to the button before selecting it.

End users can also select a button by navigating to it and pressing [Select].  The cursor remains in the button unless the button command moves it to a different item.


Creating a button

  Related Topics

To create a button:

1	In the Object Navigator, click the plus icon [image] beside the desired block node.

Form Builder expands the block node and displays its subnodes.

2	Click the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon beside the new item to display the Property Palette.

5	Under the General node, set the Item Type property to Push Button.

6	Under the Database node, set the Database Item property to No.

Note: When you create an item in a data block, Form Builder assumes the item is a data item and sets its Database Item property to Yes. Data Items are automatically included in an SELECT, UPDATE, and INSERT statements issued to the database. If the item you are creating is an interface item in a data block, you must explicitly set its Database Item property to No.

7	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign it to a canvas.


Adding a button label

  Related Topics

To add a label for a text button:

1	In the Object Navigator, double-click the object icon next to the desired button to display the Property Palette.

2	Under the Functional node, type the desired text in the Label property field.

Tip:  Make sure that the button is large enough to display the label text.  You can see view the button in the Layout Editor to see how the text label will fit in the button.


Defining an iconic button

  Related Topics

To make a button an iconic button:

1	In the Object Navigator, double-click the icon next to the desired button to display the Property Palette.

2	Under the Functional node:

•	set the Iconic property to Yes

•	set the Icon Filename property to the name of the icon.  When defining the Icon Filename property, do not include the icon file extension.  For example, enter MY_ICON, not MY_ICON.ICO.

Note:  At runtime, Form Builder searches for the icon in the path specified by the environment variable for your system (UI60_ICON on Microsoft Windows).


Defining a default button

  Related Topics

To designate a button as the default button:

1	In the Object Navigator, double-click the object icon next to the desired button to display the Property Palette.

2	Under the Functional node, set the Default Button property to Yes.


Manipulating buttons at runtime

  Related Topics

Form Builder provides triggers that you can use to respond to interface events that occur when the end user manipulates a button.

Executing Button Code  In order for a button to execute or initiate a command, you must attach a When-Button-Pressed trigger that fires when the button is selected.

When the Button Pressed event occurs, that is, when an end user clicks on the button, Form Builder executes the code in the When-Button-Pressed trigger.

The following example shows a When-Button-Pressed trigger that calculates a total from the values stored in two text items:

When-Button-Pressed trigger:

:order.total := :order.qty * :order.price

Setting Button Properties Programmatically  You can set and get button properties programmatically with the following built-in subprograms:

•	CONVERT_OTHER_VALUE

•	DISPLAY_ITEM

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


About check boxes

  Related Topics

A check box is a two-state control that indicates whether a certain condition or value is on or off, true or false.

Runtime Behavior  On GUI platforms, a check box is displayed as small, square box with a text label to the right.  On character mode platforms, a check box appears in square brackets.

The display state of a check box is always either checked or unchecked. End users toggle the state of a check box by clicking it with the mouse or by navigating to the check box and pressing [Select].

On most GUIs, the text in the check box label is "hot."  That is, end users can toggle the check box by clicking either the check box element or the text label itself.

In Enter Query mode, the end user can exclude a check box as query criteria by setting the check box state to undefined.  When a check box is in the undefined state, it appears disabled.  Note that the undefined state is valid only in Enter Query mode.


About check box values; check boxes, values
About check box values

  Related Topics

Check boxes store CHAR, NUMBER, or DATE values.  The value of a check box can be set by a fetch from a corresponding database column, by end user input via item manipulation, or through initial value or runtime assignment.  Similarly, the value of a check box can be committed to the database through standard commit processing.

When you define a check box, you specify what value you want the check box to represent as checked and what value you want it to represent as unchecked.

For instance, consider a check box that indicates whether or not a customer has been approved for credit.  When you define the check box, you could specify the Value when Checked to be 'CREDIT_OK' and the Value when Unchecked to be 'NO_CREDIT'.

When a customer record is fetched, the check box stores the value retrieved from its corresponding database column.  If the fetched value is 'NO_CREDIT,' the check box is displayed in the unchecked state (off).  If the end user activates the check box to toggle it to the checked state (on), the check box value changes to the checked value, 'CREDIT_OK.'

Check Boxes and Other Values  When you create a check box, you must specify how you want it to handle any fetched or assigned value that is not one of the values represented by the checked or unchecked states.  (Note that the undefined state is used only in Enter Query mode.  A value cannot be associated with the undefined state).

You can specify that a check box handle such Other Values in one of three ways:

•	reject Other Values as Not Allowed

•	display Other Values as the checked state

•	display Other Values as the unchecked state

In the previous example, you might specify that the Credit Approved check box display any Other Values as unchecked (off).  Then, if a fetched record were to return the value 'PENDING', the check box would be unchecked, indicating that the customer's credit had not yet been approved.  In this example, only the value 'CREDIT_OK' sets the state of the check box to checked, and all Other Values are displayed as unchecked.

When a value other than the checked or unchecked value is fetched or assigned to a check box, the state of the item can be either checked or unchecked, but the value of the item remains the Other Value until a new value is fetched or assigned, or until the end user toggles the state of the check box.

The following table shows the possible states and values for the example check box:

Fetched or Assigned Value	Check Box State	Check Box Value	State/Value After End User Toggles Check Box
CREDIT_OK	checked	CREDIT_OK	unchecked/NO_CREDIT
NO_CREDIT	unchecked	PENDING	checked/CREDIT_OK
PENDING	unchecked	PENDING	checked/CREDIT_OK
123ABC	unchecked	123ABC	checked/CREDIT_OK


Creating a check box

  Related Topics

To create a check box:

1	In the Object Navigator, click the plus icon [image] beside the desired block node.

Form Builder expands the block node and displays its subnodes.

2	Click the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon next to the newly created item to display the Property Palette.

5	Under the General node, set the Item Type property to Check Box.

6	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign it to a canvas.

7	Create a label for the check box by entering the desired text in the Label property field, found in the Functional node.

The check box label displays to the right of the check box element at runtime.

8	Specify the values you want the check box to display as "checked" and "unchecked" in the Value when Checked and Value when Unchecked property fields, respectively. These properties are found in the Functional node.

For example, if you want the check box to be "checked," or On, whenever its stored value is XYZ, enter the string XYZ in the Value when Checked property field.

Note:  The values you enter cannot be longer than the number of characters specified in the Maximum Length property.

Tip:  If you want a check box to display a Null value as checked or unchecked, leave either the Value when Checked or Value when Unchecked property blank. The corresponding state of checked or unchecked should be used in the Check Box Mapping of Other Values property:

•	If you want a Null value to be displayed as checked, set Check Box Mapping of Other Values to Checked.

•	If you want a Null value to be displayed as unchecked, set Check Box Mapping of Other Values to Unchecked. Otherwise, Other Values will result in an invalid value error message.

9	Set the Check Box Mapping of Other Values property, in the Functional node, to specify how you want the check box to handle other values.

The Check Box Mapping of Other Values property determines how the check box handles values that are not specified in the Value when Checked and Value when Unchecked property fields.

•	Choose Checked if you want the check box to be checked when its value is set to any value other than those entered in the Value when Checked and Value when Unchecked property fields.

•	Choose Unchecked if you want the check box to be unchecked when its value is any value other than those entered in the Value when Checked and Value when Unchecked property fields.

•	Choose Not Allowed if you want the check box to reject any value other than those entered in the Value when Checked and Value when Unchecked property fields as invalid.  When an invalid Other Value is fetched or assigned to the check box, the record is silently rejected.

Note:  The Check Box Mapping of Other Values property applies only to check box values fetched from the database or assigned programmatically at runtime.  When end users toggle a check box on or off, the value of the check box is either the Value when Checked or Value when Unchecked--never an Other Value.


About check box initial values

  Related Topics

You can enter an initial value for a check box in the Initial Value property field.  The initial value specifies the initial value of the item, and thus determines whether the check box is initially checked or unchecked.

You must specify a valid initial value unless

•	the Check Box Mapping of Other Values property is set to Checked or Unchecked, or

•	the value associated with Checked or Unchecked is Null.

Note:  The initial value does not get assigned until Form Builder creates a record in the block.  A check box in a Null record, that is, a record that has not yet been initialized, appears unchecked.


Specifying an initial value for a check box

  Related Topics

To specify an initial value for a check box:

1	In the Object Navigator, doube-click the object icon beside the check box for which you want to specify the initial value. This will display the Property Palette.

2	Under the Data node, set the Initial Value property to the desired value.


Manipulating check boxes at runtime

  Related Topics

Form Builder provides triggers that you can use to respond to interface events that occur when the end user manipulates a check box.

Executing Check Box Code   In order for a check box to execute or initiate a command, you must attach a When-Checkbox-Changed trigger to it that fires when the check box is selected.

When the Checkbox Changed event occurs, that is, when an end user selects the check box, Form Builder executes the code in the When-Checkbox-Changed trigger.

Setting Check Box Properties Programmatically  You can set and get check box properties programmatically with the following built-in subprogram routines:

•	CONVERT_OTHER_VALUE

•	DISPLAY_ITEM

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


About display items

  Related Topics

Display items are similar to text items with the exception that display items only store and display fetched or assigned values.  Display items are generally used as graphic or as conditional text.

It is advantageous to use display items when possible, because they require less memory than a text items.

Runtime Behavior  End users cannot navigate to display items or edit display item values.

Note:  Multi-line display items do not automatically wrap text between characters or words; multiple line values break only at newline characters.


Creating a display item

  Related Topics

To create a display item:

1	In the Object Navigator, click the plus icon [image] beside the desired block node.

Form Builder expands the block node and displays its subnodes.

2	Click the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon next to the newly created item to display the Property Palette.

5	Under the General node, set the Item Type property to Display Item.

6	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign it to a canvas.


About formatting display item values with format masks

  Related Topics

You can format single-line display items with format masks.  When a format mask is assigned to a display item, any value fetched or assigned to the item is displayed in the format specified by the mask.

The following example shows how a format mask affects a NUMBER value:

Format Mask	Fetched Value	Displayed Value
$9,999,999.99	3246000	$3,246,000.00

Format Masks and Data Types A format mask can be applied to display items with the following data types:

•	NUMBER

•	DATE and DATETIME

•	CHAR

The format mask must be compatible with the data type of the display item.


Assigning a format mask to a display item

  Related Topics

To assign a format mask to a display item:

1	In Object Navigator, double-click the object icon beside the desired display item.

2	Under the General node, enter the characters of the format mask directly in the Format Mask property field.

3	Make sure the display item's data type as specified in the Data Type property (Property Palette Data node) is compatible with the format mask.

4	Make sure the display item's Maximum Length property is set to allow the text item to store any additional characters that will be embedded by the format mask.

Note:  The setting of NLS parameters will affect the default formats.


Display item format mask symbols for NUMBER values

 Examples 	     Related Topics

The following table shows the symbols most commonly used in numeric format masks.

Symbol	Description
9	Represents 1 numeric character.  The number of 9's determines how many digits the text item can display.
0	Displays leading zeroes when present.
$	Prefix number with a dollar sign.
B	Displays preceding zeroes as blank spaces.
MI	Displays "-" after a negative value.
PR	Displays negative value in <angle brackets>.
,  (comma)	Displays a comma in this position as required.
. (decimal)	Displays a decimal in this position.

Embedded Characters in NUMBER Values  You can embed a character string in a NUMBER value by enclosing it in quotes in the format mask.  Embedded characters are usually used in fixed-length values such as standard part numbers and telephone numbers.

The following format mask embeds dashes in numeric values:

Format Mask	Displayed Value
999"-"99"-"9999	566-23-5733

The position of an embedded string is fixed within the display item, and does not change depending on how many digits are in the stored value.


Display item format mask symbols for NUMBER values examples

Example

The following table shows examples of format masks for NUMBER values:

Format Mask	Number Entered	Result
999	223.4	223
$9,999.99	3445.34	$3,445.34
999"-"999"-"9999"	4083543957	408-354-3957
99.9	00027.48	27.5
099.9	00027.48	00027.5
B99.9	00027.48	27.5
99.9MI	-24	24.0-
99.99"%"	66.17	66.17%


Display item format mask symbols for DATE values

 Examples 	     Related Topics

The following table shows the symbols most commonly used in date and datetime ormat masks.

Symbol	Description
9	Represents one numeric character.  The number of 9's determines the number of digits the text item can display.
MM	Month (01-12).
MON	Name of month, 3-letter abbreviation.
MONTH	Name of month, padded with blank spaces to length of 9 characters.
DD	Day of month (1-31).
DY	Name of day, 3-letter abbreviation.
DAY	Name of day, padded with blanks to length of 9 characters.
YYYY,YYY, YY, or Y	4, 3, 2, or 1-digit year.
TH	Ordinal number (e.g., "DDTH" for "15TH").
SP	Spelled out number (e.g.,, "DDSP" for "FIFTEEN").
SPTH or THSP	Spelled out ordinal number (e.g.,, "DDSPTH" for "FIFTEENTH"
FM	Prefix used with symbols such as MONTH and DAY to suppress padding added by these symbols.  Also suppresses leading zeroes for number symbols such as HH and MM.  FM is a toggle.  If FM appears twice in a date format model,, blank padding and leading zeroes are suppressed for elements after the first FM,, and are re-enabled after the second.

Embedded Characters in DATE and DATETIME Values  To embed a character string in a date format mask, enclose it in quotes.  Spaces and punctuation characters (/ .  , : ' - ) can be embedded in a date format mask without enclosing them in quotes.

For example:

Format Mask	Displayed Value
"Today's date is " fmDAY, fmMONTH DDTH	Today's date is Tuesday, March 16TH


Display item format mask symbols for DATE values examples

Example

The following table shows examples of format masks for DATE values:

Format Mask	Result
MM/DD/YYYY	03/15/1995
MONTH 15 YYYY	MARCH 15 1995
fmMONTH 15 1995	MARCH 15 1995
Day, "the" DDTH "of" fmMonth	Wednesday, the 15TH of March
J	2449792


Display item format mask symbols for CHAR values

 Examples 	     Related Topics

The following table shows the symbols most commonly used in CHAR format masks.

Symbol	Description
FM	Fill mode:  accept string as typed, do not right justify.  Allows end user input string to be shorter than the format mask
X	Any alphabetic, numeric, or special character.  End user input string must be exact length specified by format mask.
9	Numeric characters only.  End user input string must be exact length specified by format mask.
A	Alphabetic characters only.  End user input string must be exact length specified by format mask.


Display item format mask symbols for CHAR values examples

Example

Format Mask	Result
XXAA	Will accept: --ab, abcd, 11ab; will not accept: --11, ab11, or ab--(must use XX to accept hyphens and other special characters).
XXXX	Will accept any combination of alphabetic, numeric, or special characters: --ab, abcd, 11ab, --11, ab11, or ab--.  Will accept 1234 or abcd; will not accept 123 or abc.  (To accept input string shorter than mask, use FMXXXX.)
FMXX99	Will accept ab12, ab1, ab followed by two spaces; will not accept 12ab or abcd.  (To produce the Form Builder Version 3.0 Alpha datatype, use FMAAAAAA.)


About list items

  Related Topics

A list item is a list of text elements that can be displayed as either a poplist, Tlist, or combo box.

A list item displays a fixed number of elements.  Each element in a list is a text string up to 30 characters long.  At runtime, you can programmatically evaluate, add, or remove list elements.

Runtime Behavior

Poplist	The poplist style list item appears initially as a single field (similar to a text item field).  When the end user selects the list icon, a list of available choices appears.
Tlist	The Tlist style list item appears as a rectangular box which displays a fixed number of values.  When the Tlist contains values that cannot be displayed (due to the displayable area of the item), a vertical scroll bar appears, allowing the end user to view and select undisplayed values.
Combo Box	The combo box style list item combines the features found in poplists and text items. It displays fixed values and can accept a user-entered value.

Note:  Values entered by the end user do not automatically become permanent entries in the list. To make them part of the list, use the ADD_LIST_ELEMENT built-in subprogram.

The combo box list item appears as an empty box with an icon to the right.  The user can enter text directly into the combo field or click the list icon to display a list of available values.


About list element values

  Related Topics

When you create a list item you must associate a data value with each element in the list.  When an end user selects an element, the value of the list item changes to the value associated with that element.  Similarly, when a value is fetched from the database or assigned to the list programmatically, the list element whose value matches the fetched or assigned value becomes the selected element in the list.

A list item can also store a fetched or assigned value that is not one of the values associated with a specific element in the list.  When you define a list item, you must specify how you want it to handle such Other Values.  You can do so in one of two ways:

•	Specify that the list item reject Other Values as Not Allowed.

•	Specify which element in the list is to be selected when the value of the list item is an Other Value.

Note:  Because combo box list items accept end user-entered data, you do not have to define an Other Value for combo box list items.

List Items and Null Values You can assign a Null value (either programmatically or via a query) to any list item, whether it be combo-box, poplist, or Tlist.  This is true even if the list item is mandatory, does not allow other values, and does not contain an explicitly specified null-valued element.

Any list item can display a null, even if the list item contains no explicitly specified null-valued element and does not allow other values.  When a Null value is fetched or assigned to a list item, the Null element (blank) is the currently selected element in the list.  The runtime appearance of a Null list item depends on the display style:

•	For a poplist, an implicit null element is temporarily inserted into the list.

•	For a Tlist, none of the elements are highlighted.

•	For a combo box, no text is displayed in the list item.

In Enter Query mode, end users can set the value of a list item to Null when they do not want the list item's value to be included in the query criteria:

•	For a poplist, end users exclude the item by selecting the Null (blank) element.

•	For a Tlist, end users exclude the item by deselecting the currently selected element.

•	For a combo box, end users exclude the item by leaving the element blank.

Keep in mind also that the value of an item is Null when the block does not yet have any records.  Form Builder creates a record when navigation to the block occurs.

Thus, even if you have defined an initial value for the list item by setting the Default property, that value does not get assigned until the Create Record event occurs for the block.  You can force navigation to occur programmatically with built-in subprogram routines such as GO_BLOCK and GO_ITEM.

Setting a poplist’s or Tlist’s Required property may affect the values the list will display:  When selected, an instance of a poplist will display an extra null value if its current value is Null or if its effective Required property is false.  When selecting the current value of an instance of a Tlist, it will be unselected (leaving the Tlist with no selected value) if its effective Required property is false.   But if its effective Required property is true, selecting a Tlist instance’s current value will have no effect. The value will stay selected.


Creating a list item

  Related Topics

To create a list item:

1	In the Object Navigator, click the plus icon [image] beside the desired block node.

Form Builder expands the block node and displays its subnodes.

2	Click the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon next to the newly created item to display the Property Palette.

5	Under the General node, set the Item Type property to List Item.

6	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign it to a canvas.

7	Specify the display style for the list by setting the List Style property (under the Functional node) to Poplist, Tlist, or Combo Box.  Poplist is the default.

8	Double-click the Elements in List property (also under the Functional node) to display the List Item Elements dialog, then enter the elements exactly as you want them to appear in the list item at runtime.

Tip:  To insert a new element in the list, press [Down] or [Insert Element].  To remove an element from the list, press [Remove Element].

Note:  As an alternative to defining list item values at design time, you can also add list elements individually at runtime by using the ADD_LIST_ELEMENT built-in subprogram, or you can populate the list from a record group at runtime using the POPULATE_LIST built-in. If you populate the list from a record group, be sure that the record group you are using to populate the list contains the relevant values before you call POPULATE_LIST. If the record group is a static record group, it will already contain the appropriate values. Otherwise, you should populate the group at runtime using one of the record group subprograms.

9	Associate a value with each element in the list by entering the desired value in the List Item Value field, then click OK.

The List Item Value field displays the value associated with the element currently highlighted in the List Elements column.  The values you assign to each element must be compatible with the datatype (CHAR, NUMBER, or DATE) of the list item.

Tip:  To assign a Null value to an element, leave the List Item Value field blank.

Note:  The value for an element cannot be longer than the number of characters specified by the list item's Maximum Length property.

10	You must specify how you want a list item to handle a fetched or assigned value that is not one of the values associated with a specific element.  To do so, set the list item's Mapping of Other Values property, under the Functional node:

•	Leave the Mapping of Other Values property blank to indicate that other values are not allowed for this item. Any queried record that contains a value that does not match one of the values associated with an element in the list is silently rejected.  Any attempt to assign an other value is disallowed.

•	Enter a value that evaluates to one of the values associated with a specific element, or to the name of one of the elements.

Note:  The Mapping of Other Values property applies only to list element values fetched from the database or assigned programmatically at runtime.  When end users select an element, the value of the list item is always the value associated with that element--never an Other Value.


About list item initial values

  Related Topics

You must specify a valid Initial Value unless a) the list item accepts Other Values or b) the value associated with one of the list elements is Null.

Note:  If you are relying on the initial value to initialize the selection state of the list, remember that initial values do not get assigned until Form Builder creates a record in the block.


Specifying an initial value for a list item

  Related Topics

To specify an initial value for a list item:

1	In the Object Navigator, double-click the object icon beside the desired list item to display the Property Palette.

2	Under the Data node, set the Initial Value property to the desired value.


Manipulating list items at runtime

  Related Topics

Form Builder provides triggers that you can use to respond to interface events that occur when the end user manipulates a list item.

•	When-List-Activated

•	When-List-Changed

At runtime, you can programmatically add, remove, modify, or evaluate elements in a list item by using the following built-in subprograms:

•	ADD_LIST_ELEMENT

•	CONVERT_OTHER_VALUE

•	DELETE_LIST_ELEMENT

•	GET_LIST_ELEMENT_COUNT

•	GET_LIST_ELEMENT_LABEL

•	GET_LIST_ELEMENT_VALUE

•	POPULATE_LIST

•	RETRIEVE_LIST


About adding list elements

  Related Topics

You can add list elements by adding elements one at a time or by populating a list item with values contained in a record group.

You can add values to a list item by using these built-in subprograms:

•	ADD_LIST_ELEMENT

•	POPULATE_LIST


Adding a single list element

  Related Topics

To add a single element to a list item, use the ADD_LIST_ELEMENT built-in subprogram.

When you call ADD_LIST_ELEMENT, you indicate which list item will receive the new element by specifying the list name, list index, label, and the value to add.

In the following example, the value "1994" is added to a list item called calendar.

Add_List_Element('calendar',list_index,'1994','1994');


Adding multiple list elements

 Examples 	  Related Topics

To replace the elements in the list item completely, use the POPULATE_LIST built-in subprogram.  This subprogram removes the contents of the current list item and then populates the list item with the values from a record group.

A record group is an internal Form Builder data structure that has a column/row framework similar to a database table.  One advantage to populating a list item with record group values is that record groups (query and non-query) can be constructed dynamically at runtime.

Note:  In order to populate a list item from a record group, the record group must be created at runtime and it must have two columns with type CHAR.  Column one must contain list label values and column two must contain list element values.

When you call POPULATE_LIST, you indicate which list item will receive the record group values by specifying list ID and record group name.


Adding multiple list elements examples

The following example creates a two column query record group and then populates a list item with the values from the record group.

DECLARE
    group_id     RecordGroup;
    list_id      Item := Find_Item('list_item1');
    status       NUMBER;
BEGIN
/*
**  Create a two column query record group called
**  product_name.
*/
    group_id := Create_Group_From_Query('product_names','SELECT
       product.name, product.name FROM product');
    status := Populate_Group('product_names');
/*
**  Populate the list item with the values from the
**  product_name record group.
*/
    Populate_List(list_id,group_id);
END;


Retrieving and storing list elements in a record group

 Examples 	  Related Topics

To retrieve and store (create a "snapshot" of) the contents of a list to a record group, use the RETRIEVE_LIST built-in subprogram.  Storing the contents of a list item allows you to restore the list with its former contents.

When you call RETRIEVE_LIST, you indicate which list to retrieve by specifying the list ID and the record group ID.

In order to retrieve the contents of a list into a record group, the record group must have two columns with type CHAR.  Column one must contain list label values and column two must contain list element values.


Retrieving and storing list elements in a record group examples

The following example retrieves the contents of the current list item ('list_item1') into a record group (orders), creates a two column query record group (product_names), and then populates the list item with the values from the product_names record group.

DECLARE
/*
**  Create the two column non-query record group called
**  orders.  This record group will contain the list item
**  values.  Assign its id to the variable, group_id.
*/
    group1_id    RecordGroup;
    group2_id    RecordGroup
    col1_id      GroupColumn;
    col2_id      GroupColumn;
    it_id        Item := Find_Item('list_item1');
    status       NUMBER;

BEGIN
    group1_id := Create_Group('orders');
/*
**  Add two columns to the new group, using group1_id to
**  identify the group and then retrieve the list item values
**  into the record group.
*/
    col1_id := Add_Group_Column(group1_id,'col1',CHAR_COLUMN,50);
    col2_id := Add_Group_Column(group1_id,'col2',CHAR_COLUMN,50);

    Add_Group_Row(group1_id,1);
    Add_Group_Row(group1_id,2);
    Retrieve_List(it_id, 'orders');
/*
**  Create a two column query record group called product_names.
*/
    group2_id := Create_Group_From_Query('product_names','SELECT
        product.name,product.name FROM product');
    status := Populate_Group('product_names');
/*
**  Populate the list item with the values from the
**  product_names record group.
*/
    Populate_List(it_id,'product_names');
END;


About deleting list elements

  Related Topics

You can delete list elements one at a time or you can clear the entire list.

There are three built-in subprograms that can be used to delete elements from a list item:

•	CLEAR_LIST

•	DELETE_LIST_ELEMENT

Note:  Do not delete a list element or clear a list if the list item's Mapping of Other Values property is set to No and a query is open.  Doing so may cause Form Builder to be unable to display records that have already been fetched.

For example, assume that a list item contains the values A, B, and C and the Mapping of Other Values property is set to No.  Assume also that these values have been fetched from the database ( a query is open).  At this point, if you delete a list element, an error will occur because Form Builder will attempt to display the previously fetched values (A, B, and C), but will be unable to because an element was deleted.

Before deleting an element, check for open queries and then use the ABORT_QUERY built-in subprogram to close any open queries.


Deleting a single list element

  Related Topics

To delete a specific element from a list item, use the DELETE_LIST_ELEMENT built-in subprogram.

When you call DELETE_LIST_ELEMENT, you indicate which element to delete by specifying the list name or ID and the list element index.

List Element	List Index	List Value
1993	1	1993
1994	2	1994
1995	3	1995

For example, if you specify:

Delete_List_Element('calendar',1);

the value '1993' will be deleted from the list item.


Deleting all list elements

  Related Topics

To delete the contents of a list item, use the CLEAR_LIST built-in subprogram.  When you call CLEAR_LIST, you indicate which list to clear by specifying either the list ID or name.

For example,

Clear_List(list_id);


About radio groups

  Related Topics

A radio group is an interface control that displays a fixed number of options that are mutually exclusive.  Each option is represented by an individual radio button.

A radio group can include any number of radio buttons.  Radio buttons can be sized, positioned, and formatted independently of one another.

Runtime Behavior  End users select a different radio button by clicking with the mouse, or by navigating to the button and pressing [Select].  Selecting a radio button deselects the previously selected radio button in the same radio group. At runtime, only one radio button in a radio group can be selected at any time.


About radio group values

  Related Topics

When you create a radio group, you associate a specific data value with each radio button in the group.  When an end user selects a radio button, the value of the radio group changes to the value that you associated with the selected button.

For example, consider a radio group with three radio buttons that allows end users to specify which of three warehouses should fill an order.  The radio button labels are New York, Chicago, and San Francisco.

The values associated with each radio button are numeric warehouse IDs:

Label	Associated Value
New York	100
Chicago	200
San Francisco	300

Selecting the radio button labeled New York sets the value of the radio group to 100 (the warehouse ID).  When the end user commits the order, the value 100 is inserted in the corresponding database column.  Similarly, when a value is fetched or assigned to the radio group, the radio button whose value matches the fetched value becomes the selected button in the group.

Radio Groups and Other Values  A radio group can store a fetched or assigned value that is not one of the values that you associated with a specific radio button in the group.  When you create a radio group, you must specify how you want it to handle such Other Values.  You can do so in one of two ways:

•	Specify that the list item reject Other Values as invalid.

•	Specify which element in the list is to be selected when the value of the list item is an Other Value.

In the preceding example, you could specify that the radio button labeled "New York" be the currently selected button whenever an Other Value is fetched or assigned to the radio group.  In this instance, the fetched value 149 would be an Other Value, and the radio button labeled "New York" would become the currently selected button.

Note that when an Other Value is fetched or assigned to a radio group, the designated radio button becomes the currently selected button, but the value of the item remains the Other Value until a new value is fetched or assigned, or until the end user selects a different button.


Creating a radio group

  Related Topics

When you create a radio group, you either insert a new radio group into a block or you modify an existing item by converting its type to Radio Group.

After creating a radio group, you can create radio button labels, specify radio button values, set display properties, and so on.

To create a radio group with radio buttons:

1	In the Object Navigator, click the plus icon [image] beside the desired block node.

Form Builder expands the block node and displays its subnodes.

2	Click the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon next to the newly created item to display the Property Palette.

5	Under the General node, set the Item Type property to Radio Group.

6	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign it to a canvas.

7	In the Object Navigator, click the plus icon [image] beside the newly created radio group.

8	Click the Radio Buttons node.

9	Click the Create button [image] in the toolbar.

A new radio button with a default name is inserted under the Radio Buttons node.

10	Double-click the object icon next to the newly created radio button to display the Property Palette.

11	Create a label for the radio button by entering the desired text in the Label property field under the Functional node.

12	Enter a value for the currently selected radio button in the Radio Button Value property field, under the Functional node.  The values you assign to each radio button must be compatible with the datatype (CHAR, NUMBER, or DATE) of the radio group.

When an end user selects this radio button, Form Builder sets the value of the radio group item to the value entered in the Radio Button Value property field.  Similarly, the current radio button will be the selected button in the group whenever the value specified in the Radio Button Value field is fetched or assigned to the radio group item.

Tip:  To assign a Null value to a radio button, leave the Radio Button Value property field blank.

Note:  The Radio Button Value cannot be longer than the number of characters specified by the radio group's Maximum Length property.

13	Specify how you want the radio group to handle a fetched or assigned value that is not one of the values associated with a specific radio button.  To do so, set the Mapping of Other Values property for the radio group, under the Functional node:

•	Leave the Mapping of Other Values property blank to indicate that other values are not allowed for this item. Any queried record that contains a value that does not match one of the button values is silently rejected.  Any attempt to assign an Other Value is not allowed.

•	Enter a value that evaluates to the name of one of the radio buttons or to the value associated with one of the radio buttons.

Note:  The Mapping of Other Values property applies only to radio group values fetched from the database or assigned programmatically at runtime.  When end users select a radio button, the value of the radio group is always the value associated with the selected radio button and can never be an Other Value.

Tip:  It is good practice to make it visually clear to end users which radio buttons are part of the same radio group.  You can do this by grouping radio buttons together on a canvas, and, when necessary, separating the group from other items with graphic objects or text.


About radio group initial values

  Related Topics

You must specify a valid initial value unless

•	the radio group accepts Other Values, or

•	the value associated with one of the radio buttons in the group is Null.

Note:  If you are depending on the initial value to initialize the button selection state of the radio group, remember that the initial value does not get assigned until Form Builder creates a record in the block.  A radio group in a Null record, that is, a record that has not yet been initialized, is displayed with no radio button selected.


Specifying an initial value for a radio group

  Related Topics

To specify an initial value for a radio group:

1	In the Object Navigator, double-click the object icon beside the desired radio group to display the Property Palette.

2	Under the Data node, set the Initial Value property to the desired value.


Manipulating radio groups at runtime

  Related Topics

Form Builder provides triggers that you can use to respond to interface events that occur when the end user manipulates a radio group.

Executing Radio Button Code   In order for a radio button to execute a command or initiate a command, you must attach a When-Radio-Changed trigger to it that fires when the radio button is selected.

When the Radio Button event occurs, that is, when an end user selects the radio button, Form Builder executes the code in the When-Radio-Changed trigger.

Setting Radio Button Properties Programmatically  You can set and get radio button properties programmatically with the following built-in subprogram routines:

•	CONVERT_OTHER_VALUE

•	DISPLAY_ITEM

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY


About text items

  Related Topics

A text item is an interface control that displays and allows editing of text. The text is displayed in a field in either single or multi-line format.

Runtime Behavior  A text item appears as an empty rectangular box or container.  By default, an editor can be invoked from any text item.


Creating a text item

  Related Topics

To create a text item:

1	In the Object Navigator, click the plus icon [image] beside the desired block node.

Form Builder expands the block node and displays its subnodes.

2	Click the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon next to the newly created item to display the Property Palette.

5	Under the General node, set the Item Type property to Text Item. (This is the default setting when a new item is created.)

6	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign it to a canvas.


About text item data types

  Related Topics

Form Builder supports multiple data types.  When possible, use the standard Form Builder data types.  These data types are based on native ORACLE data types, and offer better performance and application portability.

Form Builder supports the following standard data types:

•	CHAR

•	NUMBER

•	DATE

•	DATETIME

•	LONG

The Form Builder V3 data types are included only for backward compatibility.  You can obtain the same formatting characteristics by using standard Form Builder data types (above) with a format mask and/or the Alignment property.   The Form Builder V3 data types are:

•	ALPHA

•	EDATE

•	INT (integer)

•	JDATE (Julian date)

•	MONEY

•	RINT (right integer)

•	RMONEY (right money)

•	RNUMBER (right number)

•	TIME


Changing a text item's data type

  Related Topics

To change a text item's data type:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Data node, set the Data Type property to the desired data type.

The default data type for text items is CHAR.


About single-line and multi-line text items

  Related Topics

Form Builder supports both single-line and multi-line text items.

The Multi-line property (under the Functional node) determines whether a text item displays a single line of text or multiple lines of text.  The number of characters that can fit on one line is determined by the width of the text item and the font assigned to the item.  A multi-line text item stores multiple lines of text by wrapping text to the next line when the end of one line is reached.

Form Builder processes a carriage return in a single-line text item as a NEXT_ITEM event.  A carriage return in a multi-line text item moves the cursor to the start of the next line.

Tip:  Single-line text items use less memory than multi-line text items.  Always use a single-line text item unless the application specifically requires multi-line functionality.

Single-line and Multi-line Properties  The following table shows the properties that are specific to either single- or multi-line text items:

Property	Single-line	Multi-line
Scroll Bar	No	Yes
Wrap Style	No	Yes
Secure	Yes	No
Auto Skip	Yes	No
Format Mask	Yes	No


Making a text item multi-line

  Related Topics

To make a text item multi-line:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Functional node, set the Multi-line property to Yes.

Tip:  Setting the Multi-line property to Yes gives a text item the ability to store multiple lines of text, but it does not automatically make the item large enough to display multiple lines.  You need to set the Width, Height, Font Size, and Maximum Length properties to ensure that the desired number of lines and characters are displayed.

Note:  The data type of a multi-line text item must be CHAR, ALPHA, or LONG.


About wrap style for multi-line text items

  Related Topics

You can specify different text wrapping styles for multi-line text items.

None	No text wrapping is performed. Any text exceeding the width of the field is not shown.
Character	The text breaks after the last visible character, and further characters are displayed on the next line.
Word	The text breaks after the last visible complete word, and further words/characters are displayed on the next line.


Specifying the wrap style for multi-line text items

  Related Topics

To specify the wrap style for multi-line text items:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Functional node, set the Wrap Style property to None, Character, or Word.


About vertical scroll bars in multi-line text items

  Related Topics

You can add scroll bars to your multi-line text items.  Scroll bars allow the end user to scroll up and down when viewing text item data.

Form Builder draws the scroll bar inside the text item's bounding rectangle.  Adding a scroll bar can thus reduce the number of characters that fit within the text item's border.


Adding a vertical scroll bar to a multi-line text item

  Related Topics

To add a scroll bar to a multi-line text item:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Physical node, set the Show Vertical Scroll Bar property to Yes.


About text item maximum length

  Related Topics

You can specify the maximum number of characters a text item or display item can store.  Form Builder enforces the maximum length independently of the item's Height and Width properties.

A single-line text item is scrollable when it can store more characters than it is capable of displaying.  Form Builder scrolls the value in the text item horizontally as the end user enters characters so that the cursor remains visible.

The number of characters that a text item can display is determined by a combination of factors, including the width of the text item, the font attributes, and the runtime platform.  Some experimentation may be required to derive the optimum settings for the Maximum Length and Size properties.


Specifying maximum length for a text item

  Related Topics

To specify a text item's maximum length:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Data node, specify the maximum number of storable characters in the Maximum Length property field.

Note:  If the item is a base table item, the Maximum Length property should not be set greater than the width of the corresponding database column.


About required text item values

  Related Topics

You can require end users to enter a value into a text item before navigating out of the item.

Form Builder enforces the Required property as follows:

•	End users cannot navigate out of the text item by pressing [Next Item] until the text item contains a valid value.

•	End users cannot commit the record until the required text item contains a valid value.


Making a text item value required

  Related Topics

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Data node, set the Required property to Yes.

Note:  When you create a block through the default block facility, Form Builder automatically sets the Required property to Yes for any text item that relates to a column that has the NOT NULL column constraint.  Refer to the SQL Language Reference Manual for information on column constraints.


About fixed-length values for text items

  Related Topics

You can require end users to enter a fixed number of characters in a text item by setting the Fixed Length property under the Data node.  The Fixed Length property helps ensure the validity of values that always have the same number of characters, such as telephone numbers, product numbers, order numbers, and so on.


Requiring a fixed-length value for a text item

  Related Topics

To require a fixed length value:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Data node, set the Maximum Length property to the desired value.

3	Set the Fixed Length property (also under the Data node) to Yes.

When Fixed Length is set to Yes, a text item is valid only if it contains the number of characters specified by the Maximum Length property.

Note:  Form Builder accepts Null values in a fixed length text item, provided that the text item does not have the Required property On.


About specifying a valid range of values for a text item

  Related Topics

A text item can be specified to accept only values within a certain range. This range is defined by the Highest Allowed Value and Lowest Allowed Value properties, found in the Data node of the Property Palette. The item will accept any values within the defined range, inclusive of the high and low values specified. If either the Highest Allowed Value or the Lowest Allowed Value is left blank, there will be no upper or lower bound on the range, respectively. If both properties are left blank, no bounds are enforced.


Specifying a valid range of values for a text item

  Related Topics

To define a range of acceptable values:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Data node, specify the minimum valid value in the Lowest Allowed Value property field and then the maximum valid value in the Highest Allowed Value property field. Both properties can be found in the Data node.


About restricting text items to upper or lower case

  Related Topics

You can have Form Builder automatically convert an end user-entered value to upper or lower case text with the Case Restriction property.  The Case Restriction property applies only to values entered by the end user; it does not alter fetched or assigned values.

Form Builder enforces the Case Restriction property as follows:

Case Restriction	Result
Mixed	Form Builder displays text as it is entered.
Upper	Form Builder converts lower case characters to upper case.
Lower	Form Builder converts upper case characters to lower case.


Restricting a text item to upper or lower case

  Related Topics

To restrict user-entered text in a text item to upper or lower case:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Functional node, set the Case Restriction property to Mixed, Upper, or Lower.


About justification

  Related Topics

Data displayed in a text item can be justified in one of three ways: left, center, or right. You can specify this in the Justification property field, in the Functional node of the Property Palette.

Note:  Setting right or center alignment for a scrollable text item can result in displayed values being aligned in such a way that they are hidden from the end user.  Also, some window managers may not display centered or right-aligned text.


Specifying justification

  Related Topics

To specify justification:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Functional node, set the Justification property node to either Left, Right, or Center.


About hiding text item values

  Related Topics

You can hide the value stored in a single-line text item by designating the item as secure.  For example, a password text item can be made secure so that end user input does not echo to the screen.


Hiding text item values

  Related Topics

To hide the value entered into a text item:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Functional node, set the Conceal Data property to Yes.


About automatic skip

  Related Topics

The automatic skip feature speeds data entry by eliminating the need for end users to explicitly navigate from a single-line text item to the next item in the navigation sequence.

When the Auto Skip property is enabled, the input focus automatically moves to the next navigable item when the end user enters or changes the last character in the text item's value.

Form Builder identifies the last character in a value based on the item's Maximum Length property.


Specifying automatic skip

  Related Topics

To specify auto skip:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Functional node, set the Automatic Skip property to Yes.


About maintaining cursor position

  Related Topics

You can control the location of the cursor within a text item with the Keep Cursor Position property, under the Functional node.

When Keep Cursor Position is set to Yes, Form Builder places the cursor in the text item exactly where it was when the text item last had the input focus.  (If the text item has not had the input focus during the current session, the Keep Cursor Position property has no effect.)


Maintaining cursor position in a text item

  Related Topics

To maintain cursor position in a text item:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Functional node, set the Keep Cursor Position property to Yes.


About formatting text item values with format masks

  Related Topics

You can format numbers and dates in single-line text items with format masks.  When a format mask is assigned to a text item, any value entered by the end user or fetched or assigned to the item is displayed in the format specified by the mask.

The following example shows how a format mask affects a NUMBER value:

Format Mask	Fetched Value	Displayed Value
$9,999,999.99	3246000	$3,246,000.00

A format mask can also be used to automatically embed special characters, such as dashes and monetary symbols, in values entered by end users.

Format Masks and Data Types A format mask can be applied to text items with the following data types:

•	NUMBER

•	DATE

•	DATETIME

•	TIME

The format mask must be compatible with the data type of the text item.  For example, the following format mask can be used only with a DATETIME text item because only this type has both the date and time information that this format mask requires:

Format Mask	Displayed Value
DDfmMONTH YYYY HH:MI	12 JUNE 1994 12:32


Assigning a format mask to a text item

  Related Topics

To assign a format mask to a text item:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the Data node, enter the characters of the format mask directly in the Format Mask property field.

Note:

•	The item's data type must be compatible with the format mask.

•	The text item's Maximum Length property must be  set to allow the text item to store any additional characters that will be embedded by the format mask.

•	The setting of NLS parameters will affect the default formats.


Text item format mask symbols for NUMBER values

 Examples 	  Related Topics

The following table shows the symbols most commonly used in numeric format masks.

Symbol	Description
9	Represents 1 numeric character.  The number of 9's determines how many digits the text item can display.
0	Displays leading zeroes when present.
$	Prefix number with a dollar sign.
B	Displays preceding zeroes as blank spaces.
MI	Displays "-" after a negative value.
PR	Displays negative value in <angle brackets>.
,  (comma)	Displays a comma in this position as required.
. (decimal)	Displays a decimal in this position.

Embedded Characters in NUMBER Values  You can embed a character string in a NUMBER value by enclosing it in quotes in the format mask.  Embedded characters are usually used in fixed-length values such as standard part numbers and telephone numbers.

The following format mask embeds dashes in numeric values:

Format Mask	Displayed Value
999"-"99"-"9999	566-23-5733

The position of an embedded string is fixed within the text item, and does not change depending on how many digits are in the stored value.


Text item format mask symbols for NUMBER values examples

Example

The following table shows examples of format masks for NUMBER values:

Format Mask	Number Entered	Result
999	223.4	223
$9,999.99	3445.34	$3,445.34
999"-"999"-"9999"	4083543957	408-354-3957
99.9	00027.48	27.5
099.9	00027.48	00027.5
B99.9	00027.48	27.5
99.9MI	-24	24.0-
99.99"%"	66.17	66.17%


Text item format mask symbols for DATE values
Text item format mask symbols for DATE and DATETIME values

 Examples 	  Related Topics

The following table shows the symbols most commonly used in date/time format masks.

Symbol	Description
9	Represents one numeric character.  The number of 9's determines the number of digits the text item can display.
MM	Month (01-12).
MON	Name of month, 3-letter abbreviation.
MONTH	Name of month, padded with blank spaces to length of 9 characters.
DD	Day of month (1-31).
DY	Name of day, 3-letter abbreviation.
DAY	Name of day, padded with blanks to length of 9 characters.
YYYY,YYY, YY,  or Y	4, 3, 2, or 1-digit year.
HH or HH12	Hour of day (1-12).
HH24	Hour of day (0-23).
MI	Minute (0-59).
SS	Second (0-59).
AM or A.M. or PM or P.M.	Meridian indicator.
TH	Ordinal number (e.g., "DDTH" for "15TH").
SP	Spelled out number (e.g.,, "DDSP" for "FIFTEEN").
SPTH or THSP	Spelled out ordinal number (e.g.,, "DDSPTH" for "FIFTEENTH"
FM	Prefix used with symbols such as MONTH and DAY to suppress padding added by these symbols.  Also suppresses leading zeroes for number symbols such as HH and MM.  FM is a toggle.  If FM appears twice in a date format model,, blank padding and leading zeroes are suppressed for elements after the first FM,, and are re-enabled after the second.

Embedded Characters in DATE Values  To embed a character string in a date/time format mask, enclose it in double quotes.  (Note:  you cannot embed double quotes themselves as characters in a mask.  In other words, attempting to have something like DD”MM appear by coding the mask as DD”””MM will produce unexpected results.)

Spaces and punctuation characters (/ .  , : ' - ) can be embedded in a date/time format mask without enclosing them in double quotes.

Examples:

Format Mask	Displayed Value
"Today's date is " fmDAY, fmMONTH DDTH	Today's date is Tuesday, March 16TH


Text item format mask symbols for DATE values examples
Text item format mask symbols for DATE and DATETIME values examples

Example

The following table shows examples of format masks for DATE and DATETIME values:

Format Mask	Data Type	Result
MM/DD/YYYY	DATE	03/15/1995
MONTH 15 YYYY	DATE	MARCH 15 1995
fmMONTH 15 1995	DATE	MARCH 15 1995
Day, "the" DDTH "of" fmMonth	DATE	Wednesday, the 15TH of March
J	DATE	2449792
HH:MI PM	TIME	10:30 PM
HH24:MI	TIME	20:30
MM-DD-YY  HH:MI AM	DATETIME	03-15-95  06:30 AM
fmMM-DD-YY fmHH:MI AM	DATETIME	3-15-95  06:30 AM
fmMonth YY	DATETIME	March 95


About format masks for dates

  Related Topics

Form Builder uses a format mask to perform conversion operations on dates in a variety of circumstances:

•	when it is necessary to convert a date to a string or a string to a date

•	when it is necessary to convert a user-entered date for display in an error message.

There are different format masks for different date conversion operations.  Any format mask you create yourself (via the Format_Mask property) is attached to one particular item.  Such masks exist only if you specifically create them.  The other date format masks used by Form Builder are general, and are used for all date items in a particular situation.  These general-purpose masks always exist; however, you can control their settings.

The various conversion operations, and the format mask Form Builder uses for each, are shown in the following two tables (date to string, and string to date).  The masks are explained after the tables.

The settings of all of these date format masks can be controlled.  Some you can set via properties at design time.  Others can be set via the runtime operating system's environment variables.

In general, it is advisable to do the following:

•	avoid creating format masks for individual items unless it is truly necessary.  Form Builder will use one of its general purpose masks for any item not having its own mask.  The general purpose masks are usually adequate.  Hard-coding individual masks makes portability and internationalization difficult.

•	actively set the general masks and coordinate their values.  Avoid the default values, unless you want consistency with Release 4.5 behavior.  (Setting the mask values is explained in more detail under each individual mask below.)

Operation Requiring Date-to-String Conversion	Format Mask Used
Formatting operations:
Displaying a value in an item that has a format mask	That item's format mask
Displaying a value in an item that does not have a format mask	Output
Displaying a value in a date LOV column	Output
Internal Forms operations:
Getting :SYSTEM.CURRENT_DATETIME	Builtin
Getting :SYSTEM.EFFECTIVE_DATE	Builtin
Setting a CHAR return item from a date LOV column	Builtin (see note)
Setting a CHAR item's initial value from $$DATE$$, $$DATETIME$$, $$DBDATE$$, or $$DBDATETIME$$	Builtin (see note)
GET_ITEM_PROPERTY(item, DATABASE_VALUE)	Builtin (see note)
GET_ITEM_PROPERTY(item, ITEM_DEFAULT_VALUE)	Builtin (see note)
GET_ITEM_PROPERTY(item, RANGE_HIGH/LOW)	Builtin (see note)
GET_LIST_ELEMENT_VALUE(item, value)	Builtin
GET_PARAMETER_ATTR(list, key, paramtype, value)for a date parameter defined at design time	Builtin
NAME_IN(variable)	Builtin
PL/SQL:
TO_CHAR(value, format_mask) in PL/SQL	That format mask
TO_CHAR(value) in PL/SQL	PLSQL
Implicit conversion in PL/SQL	PLSQL
Database SQL (includes database SQL embedded in PL/SQL):
TO_CHAR(value, format mask) in database SQL	That format mask
TO_CHAR(value) in database SQL	Database
Implicit conversion in database SQL	Database
Storing a date value returned by database SQL into a Forms CHAR variable	Database
Converting a Forms date variable when it needs to be inserted into or compared against a CHAR column	Database
PL/SQL debugging:
Displaying the value of an item or a parameter in the debugger	Builtin
Displaying the value of a local PL/SQL variable in the Debugger	PLSQL
Note:

If you set your form's Runtime_Compatibility_Mode property to 4.5, then this conversion operation uses the Output format mask instead.

Operation Requiring String-to-Date Conversion	Format Mask Used
Formatting operations:
Extracting a value from an item that has a format mask	That item's format mask
Extracting a value from an item that does not have a format mask	Input
Internal Forms operations:
Setting :SYSTEM.EFFECTIVE_DATE	Builtin
Setting a DATE/DATETIME return item from a CHAR LOV column	Builtin (see note)
Setting a DATE/DATETIME item's initial value from a CHAR variable (using colon notation)	Builtin (see note)
ADD_LIST_ELEMENT(item, index, label, value)	Builtin
SET_PARAMETER_ATTR(list, key, paramtype, value) for a date parameter defined at design time	Builtin
COPY(value, variable)	Builtin
DEFAULT_VALUE(value, variable)	Builtin
PL/SQL:
TO_DATE(value, format_mask)	That format mask
TO_DATE(value) in PL/SQL	PLSQL
Implicit conversion in PL/SQL	PLSQL
Database SQL (includes database SQL embedded in PL/SQL):
TO_DATE(value, format_mask) in database SQL	That format mask
TO_DATE(value) in database SQL	Database
Implicit conversion in database SQL	Database
Storing a CHAR value returned by database SQL into a Forms DATE variable	Database
Converting a Forms CHAR variable when it needs to be inserted into or compared against a date column	Database
PL/SQL debugging:
Setting the value of an item or a parameter in the debugger	Builtin
Setting the value of a local PL/SQL variable in the debugger	PLSQL
Note:

If you set your Form's Runtime_Compatibility_Mode property to 4.5, then this conversion operation uses the Input format mask instead.

Types of date format masks

Form Builder uses the following date format masks:

1	User-created date format masks for individual items

2	PLSQL date format mask

3	Builtin date format mask

4	Database date format mask

5	Input date format mask

6	Output date format mask

7	Error date format mask

1.  Individual item's date format mask

You create and set these masks through the Format_Mask property.  As noted above, avoid creating these individual masks if the general-purpose masks will suffice.

2.  PLSQL date format mask

You set this mask in the PLSQL_Date_Format property.  It is STRONGLY RECOMMENDED that for new applications, you set this property to a mask containing full century and time information.  It is also recommended that you use the same setting for the Builtin date format mask.  (See the example below.)

3.  Builtin date format mask

You set this mask in the Builtin_Date_Format property .  It is STRONGLY RECOMMENDED that for new applications, you set this property to a mask containing full century and time information.  It is also recommended that you use the same setting for the PLSQL date format mask.  (See the example below.)

4.  Database date format mask

Each database session within a Forms application has a single Database date format mask.  This mask is used by the database server to convert a string to a date value, or vice versa, in the course of evaluating a query.

A default value for this mask is established by the Oracle Server's NLS_DATE_FORMAT (or NLS_LANG or NLS_TERRITORY) initialization parameter.  This can be overridden in all new database sessions for a particular client, by setting the client's NLS_LANG and NLS_DATE_FORMAT environment variables.

Within a Forms application, the mask value can be further overridden on a session-by-session basis, by issuing an ALTER SESSION.  It may simplify an application's logic if it is set to the same format mask as the application's PLSQL_Date_Format and Builtin_Date_Format properties.  (See the following example.)

Note that if you do an OPEN_FORM with the SESSION option specified, then the opened form will have a new database session; therefore, you might want to alter its session, as well.

Example for PLSQL, Builtin, and Database mask creation

To create and coordinate these masks, the PRE-FORM trigger in the application's initial form could contain:

   SET_APPLICATION_PROPERTY(PLSQL_DATE_FORMAT,     'YYYY/MM/DD HH24:MI:SS');

   SET_APPLICATION_PROPERTY(BUILTIN_DATE_FORMAT,   'YYYY/MM/DD HH24:MI:SS');

   FORMS_DDL('ALTER SESSION SET NLS_DATE_FORMAT = ''YYYY/MM/DD HH24:MI:SS''');

5.  Input date format mask

The Input date format mask (actually a set of masks) is used to extract a value from an item which has no format mask.  That is, the mask is used to convert a user-entered string into a native-format date value.

The system administrator or end user may set the environment variables FORMS60_USER_DATE_FORMAT and FORMS60_USER_DATETIME_FORMAT to specify the format masks used to extract values from items of type DATE and DATETIME, respectively.  In each case, multiple format masks may be specified, separated by vertical bars. When converting a user-entered string, the format masks are used in the order specified, until a conversion succeeds or until the format masks are exhausted.

For example, these runtime environment variables might be set as follows:

   FORMS60_USER_DATE_FORMAT       FXFMDD-MM-RRRR

   FORMS60_USER_DATETIME_FORMAT   FXFMDD-MM-RRRR HH24:MI:SS|FXFMDD-MM-RRRR HH24:MI

This would force the end user to enter values into DATE items (with no format mask) in the format exemplified by 31-6-97.  (The RRRR enables years between 1950 and 2049 to be entered with the century omitted).  But for DATETIME items, the end user could enter values either in the format exemplified by 31-6-97 13:45:30 or else in the format exemplified by 31-6-97 13:45 (which would be interpreted as 31-6-97 13:45:00).

If either of these two runtime environment variables is not defined, then Form Builder will construct default format masks, as explained below.

6.  Output date format mask

The Output date format mask is used to display a value in an item which has no format mask, or in an LOV column.  There are actually two such masks, one for DATE items and LOV columns, and one for DATETIME items. (DATETIME LOV columns do not exist.).  The system administrator or end user may set the environment variables FORMS60_OUTPUT_DATE_FORMAT and FORMS60_OUTPUT_DATETIME_FORMAT to specify these format masks explicitly.

If FORMS60_OUTPUT_DATE_FORMAT is not defined, but FORMS60_USER_DATE_FORMAT is defined, then the Output date format mask for DATE items is derived from FORMS60_USER_DATE_FORMAT by taking the first format mask (the value up to the first vertical bar) and stripping out all occurrences of FX and FM.

For example, if FORMS60_OUTPUT_DATE_FORMAT is not defined and FORMS60_USER_DATE_FORMAT is defined to be FXFMDD-MM-RRRR|FXFM-MON-RRRR, then the Output date format mask for DATE items is DD-MM-RRRR.

If neither FORMS60_OUTPUT_DATE_FORMAT nor FORMS60_USER_DATE_FORMAT is defined, then Form Builder will construct default format masks, as explained below.

There are similar rules for DATETIME items.

7.  Error date format mask

There is also an Error format mask, which Form Builder uses in producing certain error messages that are issued when an end user enters an invalid value into a date item.  (There are actually two such masks -- one for DATE items and one for DATETIME items.)

For example:

   FRM-50012: Date must be entered in a format like <error_date_format>

   FRM-50025: Date/time must be entered in a format like <error_datetime_format>

The system administrator or end user may set the environment variables FORMS60_ERROR_DATE_FORMAT and FORMS60_ERROR_DATETIME_FORMAT to specify these format masks explicitly.

If FORMS60_ERROR_DATE_FORMAT is not defined, but FORMS60_USER_DATE_FORMAT is defined, then the Error date format mask for DATE items is simply taken to be the entire value FORMS60_USER_DATE_FORMAT, including vertical bars.

If neither FORMS60_ERROR_DATE_FORMAT nor FORMS60_USER_DATE_FORMAT is defined, then Form Builder will construct default format masks, as explained below.

There are similar rules for DATETIME items.

Default values for the Input, Output, and Error masks

If the runtime environment variables FORMS60_USER_DATE_FORMAT and FORMS60_USER_DATETIME_FORMAT are not both set, then the rules above do not specify all of the Input, Output, and Error format masks for DATE items and DATETIME items.  It is recommended that these environment variables both be set.  That will avoid having the complex rules below come into play.

In general, Form Builder assigns default values that provide compatibility with Release 4.5 and earlier.  The behavior in those releases may actually differ slightly in some cases, but in such cases the behavior in prior releases is considered to be erroneous.

The following rules distinguish between DATE2 and DATE4 items (see Builtin_Date_Format property for details), with the additional proviso that an LOV column whose datatype is DATE is considered to be a DATE2 object.  Note that there are no DATETIME LOV columns, and LOV columns do not directly participate in builtins.

Form Builder starts with the format mask derived from the current NLS environment. This may be specified explicitly by setting the environment variable NLS_DATE_FORMAT.  Otherwise, NLS will compute a default format mask based on the current language.  Call this NLS format mask "<YY_mask>".

Next, Form Builder computes a second format mask (call it "<YYYY_mask>") from <YY_mask> as follows:  If <YY_mask> contains "YY" but not "YYYY", then <YYYY_mask> is set to <YY_mask>, but with the "YY" replaced by "YYYY". Similarly, "yy", "RR", or "rr" will be replaced by "yyyy", "RRRR", or "rrrr" in <YYYY_mask>.  Otherwise, <YYYY_mask> is set to <YY_mask>.

Given the above, the remaining unspecified Input format masks for DATE2, DATE4, and DATETIME objects become:

   DATE2:    FXFM<YY_mask>

   DATE4:    FXFM<YYYY_mask>

   DATETIME: FXFM<YYYY_mask> HH24:MI:SS

             FXFM<YYYY_mask> HH24:MI

The leading FXFM is omitted if the format mask already contains an FX or FM.

Next, any occurrences of FX and FM are removed from <YY_mask> and <YYYY_mask>.

Given the above, the remaining unspecified Output format masks become:

   DATE2:    <YY_mask>

   DATE4:    <YYYY_mask>

   DATETIME: <YYYY_mask> HH24:MI:SS

Finally, for the remaining unspecified Error format masks, the first occurrence (if any) of RR, rr, RRRR, or rrrr in <YY_mask> and <YYYY_mask> is replaced by the corresponding number of Y’s or y’s.

Given the above, the remaining unspecified Error format masks become:

   DATE2:    <YY_mask>

   DATE4:    <YYYY_mask>

   DATETIME: <YYYY_mask> HH24:MI[:SS]


About assigning a List of Values (LOV) to a text item

  Related Topics

You can assign a list of values (LOV) to a text item using the List of Values property, under the List of Values (LOV) node.  Once an LOV is assigned to a text item, end users can display the LOV by pressing [List] whenever the input focus is in the text item.

LOVs are reusable objects and must be defined separately in the Property Palette.


Assigning a List of Values (LOV) to a text item

  Related Topics

To assign a List of Values (LOV) to a text item:

1	In the Object Navigator, double-click the object icon beside the text item to which you want to attach the LOV. This will display the Property Palette.

2	Under the List of Values (LOV) node, select the desired LOV from the List of Values property poplist.


Manipulating text items at runtime

  Related Topics

Form Builder provides triggers that you can use to respond to interface events that occur when the end user manipulates a text item.

Executing Text Item Code  In order for a text item to execute a command or initiate a command, you must attach a When-New-Item-Instance trigger to it that fires when the end user navigates to the text item.

When the new item event occurs, Form Builder executes the code in the When-New-Item-Instance trigger.

Setting Text Item Properties Programmatically  You can set and get text item properties programmatically with the following built-in subprograms:

•	CONVERT_OTHER_VALUE

•	DISPLAY_ITEM

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


About JavaBeans
About adding JavaBeans

  Related Topics

You can extend your WebForm application’s function by including JavaBeans.

JavaBeans are program units that are written in Java and conform to the JavaBean specification. JavaBeans can be integrated with your application to perform specialized functions that augment your forms’ capabilities.

See the Introduction to Pluggable Java Components for more information about the value and characteristics of JavaBeans.

Providing a container for the Bean

To have the JavaBean integrate correctly with your application, you must provide a container for it. This container (sometimes also called a wrapper) must implement a WebForms-defined interface, called the IView interface.

If the JavaBean is also going to communicate with the form during runtime, then your container must also extend the VBean class.  (The VBean class implements the IView interface.)  By extending the VBean class, your container can take advantage of the CustomListener and can dispatch custom events.

In the constructor of the container, you instantiate the JavaBean. Your container can implement various event listeners, and you can register the container as a listener for various events handled by the JavaBean. Also, you can register properties and set the properties in the handler that is passed into the init() method. These properties can be shared with the form.


How to add JavaBeans
How to add JavaBeans:  overview

  Related Topics  [image]  Example

Follow these general steps to add a JavaBean to your WebForms application. Both the form and the Java component require some special coding.

In your form:

1	Within your form at design time, create a Bean Area as an item (Item Type property). The end user will see the JavaBean in this item in the user interface.

2	In this Bean Area item, set its Implementation Class property to name the Java container/wrapper class you will create for your JavaBean. (See Java steps below.)  This name must be fully-qualified (that is, oracle.forms.-----). This name establishes the primary connection between your form and your JavaBean.

3	If communication will be needed with the JavaBean while it is running, code Set_Custom_Property built-ins and When-Custom-Item-Event triggers in your form to send and receive information.

In your Java component:

1	Write a container/wrapper class for your JavaBean. (You can use the JDeveloper product to perform this general task.)  More specifically:
a)  Have your container class extend VBean. A VBean class file is provided as part of the WebForms product package. VBean implements the IView interface and extends LWContainer.
b)  Implement your event listeners.
c)  Register your user-defined properties. Those properties are then accessible in the form, using those same names.
d) Implement handlers to handle any events that will be received from the form.
e)  Set the properties on the handler that is passed into the init() method.
f)  If needed, set up the dispatching of custom events that will communicate with the form.

2	Compile the container/wrapper class you wrote in step 1. The compiler should be on the same ClassPath as the WebForms Java components, pointing to either the Java directory or the WebForms JAR file.

3	Store the JavaBean and its class so that the WebServer can find them at runtime. It is usually more efficient to have them on the server machine than on the end-user client. The WebForms applet codebase directory is the first location searched, followed by the ClassPath of the server.


Communicating with a JavaBean

  Related Topics  [image]  Example

Mechanisms for communicating

At runtime, communication between the form and the JavaBean’s container takes place through these facilities:

•	A Java CustomListener and CustomEvents

•	The system variables System.Custom_Item_Event and System.Custom_Item_Event_Parameters

•	The Set_Custom_Property built-in in the form

•	The When-Custom-Item-Event trigger in the form

CustomListener and CustomEvents

The form provides a CustomListener interface, and an associated CustomEvent class. In its initiation procedure at runtime, the form’s Handler registers a CustomListener with the JavaBean container/wrapper. Then, during execution, the JavaBean container/wrapper communicates with the form by sending custom events to it via that CustomListener. This follows the standard AWT event mechanism. (Your container/wrapper must extend VBean, which supplies the CustomListener and CustomEvents.)

public interface CustomListener extends EventListener {

    public void customActionPerformed(CustomEvent event);

}

public class CustomEvent extends java.util.EventObject {

    public CustomEvent(Object source, ID name);

    public string getName();

}

Registering and setting properties

For elements in the container/wrapper to be known in the form, they must be registered. You register your events, properties, and methods in your container by calling ID.registerProperty.

When events, properties, and methods have been registered in the container, they can be known and accessed by those same names in the form.

Here is an example of an event registration:

     private static final ID MOUSEPRESSED = ID.registerProperty(“MousePressed”);

The When-Custom-Item-Event trigger

This trigger is used in the form to receive control and information from the JavaBean container during runtime. Forms registers a CustomListener with each bean container it instantiates. When the container dispatches a custom event during runtime, the listener is automatically activated and it fires the associated When_Custom_Item_Event trigger in the form. The CustomEvent contains the event name in its PropertyID.

When the When-Custom-Item-Event trigger is activated in the form, it can access the name of the event from the system variable System.Custom_Item_Event. The trigger can also can access properties set since the last time the trigger was executed. The system accumulates these in the system variable System.Custom_Item_Event_Parameters. It clears this variable when the trigger exits.

For example, assume the following event code in the container/wrapper:

     public void mousePressed(MouseEvent event)

     {

        Integer xobj = new Integer(event.getX());

        Integer yobj = new Integer(event.getY());

        try

        {

            mHandler.setProperty(X_POS, xobj);

            mHandler.setProperty(Y_POS, yobj);

        }

        CustomEvent ce = new CustomEvent(mHandler, MOUSEPRESSED);

        dispatchCustomEvent(ce);

     }

This mousePressed event could be handled in the form in a When-Custom-Item-Event trigger as follows:

BeanValListHdl := get_parameter_list(:SYSTEM.Custom_Item_Event_Parameters);	EventName      := :SYSTEM.Custom_Item_Event;

:event_name    := EventName;

if (EventName = 'MousePressed') then

       .

       .

User-defined JavaBean properties are only accessible in the form from within this trigger. The client does not send user-defined properties to the server until the custom event is dispatched. These properties are available from the client, however, if the bean container's getProperty method supports them.

The Set_Custom_Property Built-in

You can set registered properties of the JavaBean from a Forms trigger by calling the Set_Custom_Property built-in. Invoking this built-in causes setProperty() to be called in the corresponding JavaBean container. The built-in passes a value parameter of type String, Integer, or Boolean. (If the name passed in the built-in is not registered in the JavaBean container, the built-in fails silently.)


About adding custom user interface elements
About adding custom user interface components

  Related Topics

Instead of using the standard WebForms-supplied components in your application’s user interface, you can use your own custom-designed components. For example, you could substitute an oval-shaped push button for the standard Forms rectangular shape.

The user interface elements (i.e., control item types) that can be replaced are:

•	Check Box

•	List Item  (a combination of ComboBox, TList, and PopList)

•	Push Button (Regular and Iconic)

•	Radio Group

•	Text Item  (a combination of Multi-line TextArea and TextField)

The standard user interface components implement WebForm’s IView interface. By creating your own class for your custom user interface component that implements this interface, your custom component can substitute for the standard component and be integrated into your Forms application.


How to add custom user interface elements
How to add custom user interface components

  Related Topics   [image]  Examples

There are several ways you can customize your user interface using Java:

•	Extend one of the standard, supplied WebForms classes.

•	Extend a non-WebForms class.

•	Create a container class.

•	Create a new type of interface element.

Each type of customization has its own steps, explained below.

To extend an existing Forms class

1	Create your own implementation by extending one of the existing Forms-supplied user interface classes, which thus creates your own new class. (The Forms-supplied classes are listed below.)

2	If needed, override setProperty() and/or getProperty() methods to handle properties.

3	Store your class in the Forms codebase

4	Identify your class in the Implementation Class property of the user interface item in your form.

To extend a non-WebForms class

1	Create a new class by extending some other class, but have it implement the IView interface. (The class to be extended could be a class from the JFL or a third-party class.)

2	Include getProperty and setProperty methods. These must handle the properties that Forms specifies normally for that class of user-interface item.

3	Store the class in the Forms codebase

4	Identify the class in the Implementation Class property of the user interface item in your form..

To create a container class

1	Create a container class that implements the IView interface.

2	Create your new user-interface element within this container.

3	Write your own getProperty and setProperty methods to handle the properties, such that the appropriate methods on the component are invoked.

4	Make sure that listeners are added to the user interface component to monitor end-user actions on the interface component.

5	Identify the class in the Implementation Class property of the user interface item in your form.

To create a new type of interface element

1	Create your own class for the new element type.

2	Have the new class implement the IView interface.

3	Implement whatever methods the class requires.

4	Identify the class in the Implementation Class property of the user interface item in your form.

Forms-supplied classes for user interface items

The Forms-supplied class definitions for user interface components are:

•	VButton

•	VCheckbox

•	VComboBox

•	Vimage

•	VPopList

•	VRadioButton

•	VTextArea

•	VTextField

•	VTList

Oracle Look and Feel

To obtain the appearance of interface components offered by the Oracle Look and Feel (for example, rounded buttons),  add <param name = “LookAndFeel” value = “Oracle”> and <param name = “LookAndFeel” value = “ColorScheme”> to the html file.


Adding custom user interface components:  examples

Example 1:  Extending an existing Forms class

import oracle.forms.ui.VButton;

import oracle.ewt.button.PushButton;

public class      SingleButton

       extends    VButton

{

    public SingleButton()

    {

        super();

        setLeftmost(true);

        setRightmost(true);

    }

}

Example 2:  Creating a new class by extending a different class

package oracle.forms.jfcplug;

import com.sun.java.swing.*;

import com.sun.java.swing.border.*;

import com.sun.java.swing.event.*;

import java.awt.*;

import java.awt.event.*;

import java.util.EventListener;

import oracle.forms.handler.IHandler;

import oracle.forms.properties.ID;

import oracle.forms.ui.IView;

public class       VJCheckBox

       extends     JCheckBox

       implements  IView

{

    /* Instance counter used to generate default names */

    private static int   sInstanceCounter;

    /* Helper class to handle the IView interface */

    private IHandler     mHandler;

    private int          mInstance;

    /**

    ** Constructs a new JCheckBox.

    */

    public VJCheckBox()

    {

        super();

        mInstance = sInstanceCounter++;

    }

    /**

    ** Implementation of IView interface

    **

    ** @param handler - message handler associated with this view.

    ** @see IView

    */

    public void init(IHandler handler)

    {

        mHandler = handler;

    }

    /**

    ** Implementation of IView interface

    **

    ** @see IView

    */

    public void destroy()

    {

    }

    /**

    ** Implementation of IView interface

    **

    ** @param id - property id

    ** @return the value of the property id

    ** @see IView

    */

    public Object getProperty(ID id)

    {

        switch  ( id.toID() )

        {

           case ID.INDEX_BOUNDS:

               return getBounds();

           case ID.INDEX_ENABLED:

               return isEnabled() ? Boolean.TRUE : Boolean.FALSE;

           case ID.INDEX_LANGUAGE_DIRECTION:

               return mDirection;

           case ID.INDEX_LOCATION:

               return getLocation();

           case ID.INDEX_SIZE:

               return getSize();

           case ID.INDEX_VISIBLE:

               return isVisible() ? Boolean.TRUE : Boolean.FALSE;

           case ID.INDEX_UI_PARENT:

               return getParent();

            case ID.INDEX_LABEL:

                return getText();

            case ID.INDEX_VALUE:

                return isSelected() ? Boolean.TRUE : Boolean.FALSE;

            default:

                return null;

        }

    }

    /**

    ** Implementation of IView interface

    **

    ** @param id    - property to be set.

    ** @param value - value of the property id.

    ** @return      - true(if the property could be set), false otherwise.

    ** @see IView

    */

    public boolean setProperty(ID id, Object value)

    {

        switch  ( id.toID() )

        {

            case ID.INDEX_BACKGROUND:

               Color bgColor = (Color) value;

               setBackground(bgColor);

               return true;

            case ID.INDEX_ENABLED:

               setEnabled(toBoolean(value));

               return true;

            case ID.INDEX_FOCUS:

               // Only settable to true:-)

               if ( value == Boolean.TRUE )

               {

                   cp.requestFocus();

               }

               return true;

            case ID.INDEX_FONT:

               setFont((Font) value);

               return true;

            case ID.INDEX_FOREGROUND:

               Color fgColor = (Color) value;

               setForeground(fgColor);

               return true;

            case ID.INDEX_LANGUAGE_DIRECTION:

               // Adjust the alignment to conform to the new lang direction

               // setDirection((LanguageDirection)value);

               return true;

            case ID.INDEX_LOCATION:

               setLocation((Point) value);

               return true;

            case ID.INDEX_SIZE:

               Point pt = (Point) value;

               setSize(pt.x, pt.y);

               return true;

            case ID.INDEX_VISIBLE:

               setVisible(((Boolean)value).booleanValue());

               return true;

            case ID.INDEX_LABEL:

                setText((String)value);

                return true;

            case ID.INDEX_VALUE:

                setSelected(((Boolean)value).booleanValue());

                return true;

            default:

                return false;

        }

    }

    /**

    ** Implementation of IView interface

    **

    ** @param type     - Class type of the listener.

    ** @param listener - Listener object.

    ** @see IView

    */

    public void addListener(Class type, EventListener listener)

    {

        if ( type == FocusListener.class )

        {

            addFocusListener((FocusListener) listener);

        }

        else if ( type == KeyListener.class )

        {

            addKeyListener((KeyListener) listener);

        }

        else if ( type == MouseListener.class )

        {

            addMouseListener((MouseListener) listener);

        }

        else if ( type == MouseMotionListener.class )

        {

            addMouseMotionListener((MouseMotionListener) listener);

        }

        else if ( type == ItemListener.class )

        {

            addItemListener((ItemListener) listener);

        }

    }

    /**

    ** Implementation of IView interface

    **

    ** @param type     - Class type of the listener.

    ** @param listener - Listener object.

    ** @see IView

    */

    public void removeListener(Class type, EventListener listener)

    {

        if ( type == FocusListener.class )

        {

            removeFocusListener((FocusListener) listener);

        }

        else if ( type == KeyListener.class )

        {

            removeKeyListener((KeyListener) listener);

        }

        else if ( type == MouseListener.class )

        {

            removeMouseListener((MouseListener) listener);

        }

        else if ( type == MouseMotionListener.class )

        {

            removeMouseMotionListener((MouseMotionListener) listener);

        }

        else if ( type == ItemListener.class )

        {

            removeItemListener((ItemListener) listener);

            return;

        }

    }

    /**

    ** Implementation of IView interface

    **

    ** @param child - Object to be added( or inserted in Lists, Choice)

    ** @param index - The position of insertion. For add's, this is -1.

    ** @see IView

    */

    public void add(Object child, int index)

    {

        // Not supported

    }

    /**

    ** Implementation of IView interface

    **

    ** @child -  Element to be deleted from the list.

    ** @see IView

    */

    public void remove(Object child)

    {

        // Not supported

    }

    /**

    ** Implementation of IView interface

    */

    public void removeAll()

    {

        // Not supported

    }

    /**

    ** Implement getDefaultName() to return a default name of

    ** the form <ClassName># where # is the instance number

    ** of the CheckBox

    */

    protected String getDefaultName()

    {

        return getClass().getName() + mInstance;

    }

}


The IView interface

  Related Topics

To create a JavaBean or a custom version of a user interface element that will run with your WebForms application, you must supply a view class, that is, a Java class that implements the IView interface and that supports the properties and listeners specific to that kind of view.

The supplied VBean class extends the IView interface. Therefore, if you are creating a JavaBean container that extends VBean, you automatically obtain the IView interface.

A class that implements IView must have a constructor that takes no arguments.

Contents of the IView interface:

public interface IView

{

   public void init (IHandler handler);

   public void destroy ();

   public Object getProperty(ID id);

   public boolean setProperty (ID id, Object value);

   public void addListener (Class type, EventListener listener);

   public void removeListener (Class type, EventListener listener);

   public void paint (Graphics g);

   public void repaint (Rectangle r);

   public void add (Object child, int index);

   public void remove (Object child);

   public void removeAll ();

   public boolean contains (int x, int y);

}

Functional details of the IView interface:

public void init (IHandler handler)

The handler calls this method immediately after the WebForms applet constructs the object. The method passes the view object a reference to its handler and gives it a chance to perform initialization.

public void destroy ()

The WebForms applet calls this method to eliminate the object. The method releases any system resources that the object holds.

public Object getProperty (ID id)

This method returns the value of the requested property (identified by id). The view object must support the properties appropriate to its type (see below). If this object does not support the specified property, the method returns null.

public boolean setProperty (ID id, Object value)

This method sets the value of the requested property (identified by id) to the value in Object value. The view object must support the properties appropriate to its type (see Properties and listeners). If this object does not support the specified property, the method returns FALSE. Otherwise, it returns TRUE.

public void addListener (Class type, EventListener listener)

This method adds a listener of the specified name and type to the view object. The view object must support the listeners appropriate to its type (see Properties and listeners).

public void removeListener (Class type, EventListener listener)

This method removes the specified listener from the view object.

public void paint (Graphics g)

The handler calls this method to paint the view object, using the specified AWT Graphics object.

public void repaint (Rectangle r)

This method invalidates and repaints the specified rectangle. If the rectangle is null, the method invalidates and repaints the entire object.

public void add (Object child, int index)

This method adds the specified child to this object. It is added at the position specified by the index. To add the child at the end of the index, specify an index of -1.

public void remove (Object child)

This method removes the specified child from this object.

public void removeAll ()

This method removes all of this object’s children.

public boolean contains (int x, int y)

This method returns a value of true if the specified point (x, y) is in the selection region of the component. Otherwise, it returns a value of false.


Properties and listeners needed for user interface component classes

  Related Topics

All user-interface components use the IView interface, but different types of interface elements have different sets of properties and provide listeners for different events. This section lists the different types of interface elements and the properties and listeners that each must support.

There is inheritance of interface component properties and listeners. For each interface element listed here, an Inherited Requirements item lists the requirements for the interface element preceding it in the inheritance hierarchy. For example, the ComboBoxes element lists PopLists’ properties and  listeners as Inherited Requirements. ComboBoxes must, therefore, also include PopLists’ Inherited Requirements (which are the Common Properties and Listeners).  Note that all components require the Common Properties and Listeners.

The properties listed include the name, type, and requirements for each interface element. Each property must be handled in the getProperty() and/or setProperty() methods of the IView interface as appropriate to the requirements of the property. The gettable requirement corresponds to getProperty() and the settable requirement corresponds to setProperty().

Examples: The BACKGROUND property (in Common Properties) is both gettable and settable, so BACKGROUND should be handled in both the getProperty() and setProperty() methods. The UI_PARENT property (in Common Properties) is only gettable, so UI_PARENT should be handled in the getProperty() method only.

Unless otherwise specified, listeners are part of Javasoft's abstract windowing toolkit (AWT). Documentation is  available from Javasoft. The names use standard Java terminology.

The same class is used to represent text buttons and iconic buttons.

Common properties and listeners

Required properties and listeners for all interface elements:

Properties	Type	Requirements
BACKGROUND	Color	Gettable, Settable
BGPATTERN	Image	Gettable, Settable
BOUNDS	Rectangle	Gettable, Settable
ENABLED	Boolean	Gettable, Settable
FOCUS	Boolean	Gettable, Settable
FONT	Font	Gettable, Settable
FOREGROUND	Color	Gettable, Settable
LANGUAGE_DIRECTION	LanguageDirection  (static instances are LEFT_TO_RIGHT, RIGHT_TO_LEFT, or DEFAULT)	Gettable, Settable
LOCATION	Point	Gettable, Settable
MNEMONIC	Character	Gettable, Settable
SIZE	Point	Gettable, Settable
UI_PARENT	Container	Gettable
VISIBLE	Boolean	Gettable, Settable
Listeners
FocusListener
KeyListener
MouseListener
MouseMotionListener
Inherited Requirements
None
Bean area properties and listeners

Required properties and listeners:

Properties	Type	Requirements
BORDER_BEVEL	BorderBevel  (static instances are PLAIN, RAISED, LOWERED, or NONE)	Gettable, Settable
Listener
CustomListener
Inherited Requirements
Include all Common properties and listeners
Buttons

Required properties and listeners:

Properties	Type	Requirements
IMAGE	Image	Gettable, Settable
IS_DEFAULT	Boolean	Gettable, Settable
LABEL	String
Listeners
ActionListener
Inherited Requirements
Include all Common properties and listeners
Checkboxes

Required properties and listeners:

Properties	Type	Requirements
LABEL	String	Gettable, Settable
VALUE	Boolean	Gettable, Settable
Listeners
ItemListener
Inherited Requirements
Include all Common properties and listeners
ComboBoxes

Required properties and listeners:

Properties	Type	Requirements
CASE_FOLD	CaseRestriction	Gettable, Settable
MAX_LENGTH	Integer	Gettable, Settable
SELECT	Integer	Settable
USERTEXT	String	Gettable
Listeners
SelectionListener
TextListener
Inherited Requirements
Include all PopList properties and listeners
Images

Required properties and listeners:

Properties	Type	Requirements
BORDER_BEVEL	BorderBevel  (static instances are PLAIN, RAISED, LOWERED, or NONE)	Gettable, Settable
CANVAS_ORIGIN	Point	Gettable, Settable
SCALE	Integer	Gettable, Settable
SCROLL_POSITION	Point	Gettable
SCROLL_STYLE	ImageScrollPolicy  (static instances are HORIZONTAL, VERTICAL, BOTH, or NONE)	Gettable, Settable
VALUE	Image	Gettable, Settable
VIEWPORT_SIZE	Dimension	Gettable
Listeners
(no new listeners)
Inherited Requirements
Include all Common properties and listeners
PopLists

Required properties and listeners:

Properties	Type	Requirements
COUNT	Integer	Gettable
SELECT	Integer	Settable
SELECTEDINDEX	Integer	Gettable
Listeners
DropDownListener
ItemListener
Inherited Requirements
Include all Common properties and listeners
RadioButtons

Required properties and listeners:

Properties	Type	Requirements
GROUPLEADER	Boolean	Gettable, Settable
LABEL	String	Gettable, Settable
LOCALSTATE	Boolean	Gettable
RADIOGROUP	Iview	Gettable
VALUE	Boolean	Gettable, Settable
Listeners
ItemListener
Inherited Requirements
Include all Common properties and listeners
Multi-Line and regular TEdits (Text Component) properties and listeners

Required properties and listeners:

Properties	Type	Requirements
ALIGNMENT	Alignment  (static instances are START, RIGHT, LEFT, CENTER, or END)	Gettable, Settable
BORDER_BEVEL	BorderBevel  (static instances are PLAIN, RAISED, LOWERED, or NONE)	Gettable, Settable
CAN_TAKE_FOCUS	Boolean	Gettable, Settable
CASE_FOLD	CaseRestriction  (static instances are UPPERCASE, LOWERCASE, or NONE)	Gettable, Settable
CURSOR_POSITION	Integer	Gettable, Settable
EDITABLE	Boolean	Gettable, Settable
MAX_LENGTH	Integer	Gettable, Settable
SELECTION	Point	Gettable, Settable
VALUE	String	Gettable, Settable
Listeners
TextListener
Inherited Requirements
Include all Common properties and listeners
Multi-Line TEdits (TextArea) properties and listeners

Required properties and listeners:

Properties	Type	Requirements
VSBARPOLICY	Boolean	Gettable, Settable
WRAP_STYLE	WrapStyle  (static instances are CHARACTER, WORD, or NONE)	Gettable, Settable
Listeners
(no new listeners)
Inherited Requirements
Include all Text Component properties and listeners
Non-Multi-Line TEdits (TextField)

Required properties and listeners:

Properties	Type	Requirements
SECURE	Boolean	Gettable, Settable
Listeners
(no new listeners)
Inherited Requirements

Include all Text Component properties and listeners

TLists

Required properties and listeners:

Properties	Type	Requirements
COUNT	Integer	Gettable
DESELECT	Integer	Settable
MAKEVISIBLE	Integer	Settable
SELECT	Integer	Settable
SELECTEDINDEX	Integer	Gettable
Listeners
ActionListener
ItemListener
Inherited Requirements
Include all Common properties and listeners


Including a JavaBean and custom controls:  example

  Related Topics

The following example shows how to include a JavaBean in a Forms application. This particular JavaBean (called sunw.demo.juggler.Juggler) is an animated graphic, whose animation speed can be adjusted by the end user through a choice of controls on the display.

In the form

In the form, you create a Bean Area item, and then have its Implementation Class property identify the implementation class that is the defining container or wrapper for the JavaBean itself. In this example, the bean area item is called JUGGLER_BEAN, and its full Implementation Class name is oracle.forms.pjc.demo.JugglerWrapper.

In the form, there are also various control items for the end user:  a freeze/restart button, faster and slower buttons for the animation speed, and also a slider-type speed control. (This slider is implemented by a separate JavaBean and JavaBean wrapper.)

By using PL/SQL-based triggers and built-ins in the form, the example gets and sets the properties defined within the wrapper classes. By registering the events, methods, and properties of the actual JavaBean as properties of the wrapper class, it is possible to control the JavaBean programmatically by simply setting the appropriate property in the wrapper. In the form, the properties of the JavaBean are accessed by using the SET_CUSTOM_PROPERTY built-in. JavaBean events are captured by using the When-Custom-Item-Event trigger.

The items and associated triggers can be seen in this object navigator view of the form:

The container/wrapper for the Juggler JavaBean

Remember that for a JavaBean to communicate at runtime with a form, the wrapper’s class definition must extend the VBean class. The VBean class definition itself is supplied as part of the WebForms product package. (VBean also extends IView.)

package oracle.forms.pjc.demo;

import java.applet.*;

import java.awt.*;

import java.awt.event.*;

import java.beans.*;

import oracle.forms.properties.ID;

import oracle.forms.handler.IHandler;

import oracle.forms.ui.CustomEvent;

import oracle.forms.ui.VBean;

public class      JugglerWrapper

       extends    VBean

       implements MouseListener

{

    private Component    mComp;

    private IHandler     mHandler;

// Java Bean EVENTS registered as properties of 'wrapper' implementation class

   private static final ID MOUSEPRESSED = ID.registerProperty("MousePressed");

   private static final ID MOUSEENTERED = ID.registerProperty("MouseEntered");

   private static final ID MOUSEEXITED  = ID.registerProperty("MouseExited");

// Java Bean PROPERTIES registered as properties of 'wrapper' implementation

// class

   private static final ID X_POS      = ID.registerProperty("MouseX");

   private static final ID Y_POS      = ID.registerProperty("MouseY");

   private static final ID ARATE      = ID.registerProperty("AnimationRate");

// Java Bean METHODS registered as properties of 'wrapper' implementation class

   private static final ID STOP       = ID.registerProperty("StopJuggling");

   private static final ID START      = ID.registerProperty("StartJuggling");

   private static final ID SETRATE    = ID.registerProperty("SetAnimationRate");

   private static final ID GETRATE    = ID.registerProperty("GetAnimationRate");

    public JugglerWrapper()

    {

        super();

        try

        {

            ClassLoader cl = getClass().getClassLoader();

            Object obj = Beans.instantiate(cl, "sunw.demo.juggler.Juggler");

            mComp = (Component) obj;

            mComp.setVisible(true);

            mComp.setEnabled(true);

            add("Center", mComp);

            if ( mComp instanceof Applet )

            {

                Applet apl = (Applet) Beans.getInstanceOf(mComp, Applet.class);

                apl.start();

            }

        }

        catch ( Exception e )

        {

        }

    }

    public void init(IHandler    handler)

    {

        super.init(handler);

        mHandler = handler;

        mComp.addMouseListener(this);

    }

    public void destroy()

    {

        if ( mComp instanceof Applet )

        {

            Applet apl = (Applet) Beans.getInstanceOf(mComp, Applet.class);

            apl.destroy();

            apl.stop();

        }

    }

    public boolean setProperty(ID pid, Object value)

    {

    if ( pid == STOP )

        {

            if ( ((Integer)value).intValue() == 1)

            {

              ((sunw.demo.juggler.Juggler)mComp).stopJuggling();

            }

            return true;

        }

        else if ( pid == START )

        {

            if ( ((Integer)value).intValue() == 1)

            {

              ((sunw.demo.juggler.Juggler)mComp).startJuggling();

            }

            return true;

        }

        else if ( pid == SETRATE )

        {

            ((sunw.demo.juggler.Juggler)mComp).setAnimationRate(

                                                 ((Integer)value).intValue());

             return true;

        }

    return super.setProperty(pid, value);

    }

    public void mouseClicked(MouseEvent event)

    {

    }

    public void mouseEntered(MouseEvent event)

    {

        CustomEvent ce = new CustomEvent(mHandler, MOUSEENTERED);

        dispatchCustomEvent(ce);

    }

    public void mouseExited(MouseEvent event)

    {

        CustomEvent ce = new CustomEvent(mHandler, MOUSEEXITED);

        dispatchCustomEvent(ce);

    }

    public void mousePressed(MouseEvent event)

    {

        Integer xobj = new Integer(event.getX());

        Integer yobj = new Integer(event.getY());

        try

        {

            mHandler.setProperty(Y_POS, yobj);

            mHandler.setProperty(X_POS, xobj);

        }

        catch (Exception e)

        {

        }

        CustomEvent ce = new CustomEvent(mHandler, MOUSEPRESSED);

        dispatchCustomEvent(ce);

    }

    public void mouseReleased(MouseEvent event)

    {

    }

}

Receiving information from the JavaBean via the When-Custom-Item-Event trigger

In this example, the form has a When-Custom-Item-Event trigger attached to the bean area item for the Juggler Bean. When that JavaBean’s container/wrapper dispatches a custom event, this trigger is executed. The trigger runs the PL/SQL procedure called Juggler_event_trap (shown below):

Note that the procedure in the form looks at the System.Custom_Item_Event and System.Custom_Item_Event_Parameters fields to find out the event name and to obtain the values that were set in the container/wrapper.

Note also that the event name and the X and Y mouse coordinate values that are being passed are registered properties in the container/wrapper.

PROCEDURE Juggler_event_trap IS

  BeanHdl        Item;

BeanValListHdl ParamList;

paramType      Number;

EventName      VarChar2(20);

CurrentValue   number(4);

XPos           Number(4);

YPos           Number(4);

Begin

BeanValListHdl := get_parameter_list(:SYSTEM.Custom_Item_Event_Parameters);	EventName      := :SYSTEM.Custom_Item_Event;

:event_name    := EventName;

if (EventName = 'MousePressed') then

   get_parameter_attr(BeanValListHdl,'MouseX',ParamType, CurrentValue);

   XPos := CurrentValue;

   get_parameter_attr(BeanValListHdl,'MouseY',ParamType, CurrentValue);

   YPos := CurrentValue;

   MsgBox('If you click at '||to_Char(XPos)||'/'||to_Char(YPos)||' again I may drop these beans');

  end if;

End;

A JavaBean slider control

In this example, there are also control items in the form’s user interface that allow the end user to vary the animation speed of the juggler JavaBean.

One of these controls is a Bean Area item called EWT_SLIDER. Its full implementation Class property is oracle.forms.pjc.demo.EwtSliderWrapper, which is the container/wrapper shown below:

/**

** Simple JavaBean Wrapper. It allows the EWT Slider control component to be

** embedded within the form. The slider allows the end user to control the juggler bean’s animation speed.

*/

package oracle.forms.pjc.demo;

import java.applet.*;

import java.awt.*;

import java.awt.event.*;

import java.beans.*;

import oracle.ewt.slider.Slider;

import oracle.ewt.meter.BoundedRangeModelImpl;

import oracle.forms.properties.ID;

import oracle.forms.handler.IHandler;

import oracle.forms.ui.CustomEvent;

import oracle.forms.ui.VBean;

public class      EwtSliderWrapper

       extends    VBean

       implements PropertyChangeListener

{

    private Component             mComponent;

    private IHandler              mHandler;

    private BoundedRangeModelImpl mSliderRange;

    // Java Bean EVENTS registered as properties of 'wrapper' implementation class

    private static final ID VALUECHANGED = ID.registerProperty("ValueChanged");

    // Java Bean PROPERTIES registered as properties of 'wrapper' implementation

    // class

    private static final ID VALUE           = ID.registerProperty("Value");

    private static final ID MAXVALUE        = ID.registerProperty("MaxValue");

    private static final ID MINVALUE        = ID.registerProperty("MinValue");

    // Java Bean METHODS registered as properties of 'wrapper' implementation class

    private static final ID SETVALUE        = ID.registerProperty("SetValue");

    private static final ID GETVALUE        = ID.registerProperty("GetValue");

    private static final ID GETMAXVALUE     = ID.registerProperty("GetMaximum");

    private static final ID GETMINVALUE     = ID.registerProperty("GetMinimum");

    public void init(IHandler    handler)

    {

        super.init(handler);

        mHandler    = handler;

        mSliderRange = new BoundedRangeModelImpl(0,300,125);

        mComponent  = new Slider(mSliderRange);

        mSliderRange.addPropertyChangeListener(this);

        mComponent.setEnabled(true);

        add("Center", mComponent);

    }

    public boolean setProperty(ID pid, Object value)

    {

        return super.setProperty(pid, value);

    }

   public void propertyChange(PropertyChangeEvent event)

    {

         String PropName = event.getPropertyName();

         if (PropName.equals("value"))

         {

           Integer SliderValue = new Integer(mSliderRange.getValue());

           try

           {

           mHandler.setProperty(VALUE, SliderValue);

           }

           catch (Exception e)

           {

           }

           CustomEvent ce = new CustomEvent(mHandler, VALUECHANGED);

           dispatchCustomEvent(ce);

         }

    }

}

In the form, a When-Custom-Item-Event trigger is attached to the EWT_Slider Bean Area item. When the end-user moves the slide on the display, the above JavaBean container becomes aware through its PropertyChangeListener. The container dispatches a custom event, which results in this trigger being fired in the form. The trigger executes the following PL/SQL procedure, called Slider_Event_Trap.

After this procedure picks up the changed values from the System.Custom_Item_Event_Parameters, it uses the Set_Custom_Property built-in to pass those changed values along to the Juggler JavaBean.

PROCEDURE Slider_Event_Trap IS

  BeanHdl          Item;

BeanValListHdl   ParamList;

paramType        Number;

EventName        VarChar2(20);

CurrentValue     Number(4);

NewAnimationRate Number(4);

Begin

-- Update data items and Display fields with current radius information

BeanValListHdl := get_parameter_list(:SYSTEM.Custom_Item_Event_Parameters);

EventName      := :SYSTEM.Custom_Item_Event;

:event_name    := EventName;

if (EventName = 'ValueChanged') then

   get_parameter_attr(BeanValListHdl,'Value',ParamType, CurrentValue);

   NewAnimationRate := (300 - CurrentValue);

   :Animation_Rate  := NewAnimationRate;

     set_custom_property('Juggler_Bean', ALL_ROWS, 'SetAnimationRate', NewAnimationRate);

elsif (EventName = 'mouseReleased') then

   get_parameter_attr(BeanValListHdl,'Value',ParamType, CurrentValue);

     set_custom_property('Juggler_Bean', ALL_ROWS, 'SetAnimationRate', CurrentValue);

  end if;

End;

Other Java buttons in the form

The form also has several custom user interface components. These are created by extending the exisiting Forms VButton class, as follows:

/**

** Here, the 'Oracle Look & Feel' buttons are enhanced by subclassing the

** standard EWT PushButton Class and calling one of the available methods.

**

** Use of both setLeftmost() & setRightmost() function causes the Left & Right

** edges of the button to be rounded (allows for the creation of a stand-alone

** rounded style button)

*/

import oracle.forms.ui.VButton;

import oracle.ewt.button.PushButton;

public class      SingleButton

       extends    VButton

{

    public SingleButton()

    {

        super();

        setLeftmost(true);

        setRightmost(true);

    }

}

/**

** Here, the 'Oracle Look & Feel' buttons are enhanced by subclassing the

** standard EWT PushButton Class and calling one of the available methods.

**

** Use of the setLeftmost() function causes the left edge of the button to be

** rounded (for use at the left end of a group of buttons)

*/

import oracle.forms.ui.VButton;

import oracle.ewt.button.PushButton;

public class       LeftButton

       extends     VButton

{

    public LeftButton()

    {

        super();

        setLeftmost(true);

    }

}

(The RightButton definition, which is similar to the above LeftButton, is not shown here.)

Other Java-related Triggers in the form

There are also several When-Button-Pressed triggers in the form. The following When-Button-Pressed trigger, for example, is attached to the Start-Stop control item button in the form. It is used to execute the following procedure, which freezes or restarts the animated action of the juggler display.

Notice that the StartJuggling and StopJuggling properties referenced in the Set_Custom_Property builtins are also registered properties in the container/wrapper for the Juggler JavaBean.

PROCEDURE Start_Stop_Juggling IS

BtnHdl    Item;

BtnLabel  VarChar2(10);

BeanHdl   Item;

BEGIN

BtnHdl := find_item('START_STOP_BTN');

if NOT id_null(BtnHdl) then

   BtnLabel := get_item_property(BtnHdl, LABEL);

   BeanHdl  := find_item('JUGGLER_BEAN');

   if NOT id_Null(BeanHdl) then

      if BtnLabel = 'Start Me!' then

         set_custom_property(BeanHdl, ALL_ROWS, 'StartJuggling', 1);

         set_item_property       (BtnHdl, LABEL,           'Stop Me!');

        elsif BtnLabel = 'Stop Me!' then

         set_custom_property(BeanHdl, ALL_ROWS, 'StopJuggling', 1);

         set_item_property       (BtnHdl,  LABEL,         'Start Me!');

        end if;

     end if;

  end if;

END;


Focus and key events for bean area components

For bean area components in a Forms applet, the developer must add functionality so that the bean area components can enjoy focus and navigation consistent with other Forms components. The bean area (bean wrapper class) must implement the FocusListener and KeyListener interfaces and all of the components in a bean area must also register the bean area as a FocusListener and KeyListener. Finally, the developer must implement methods that pass registered properties (from the VBean class) and the event object to create focus and navigation consistent with other Forms components.

Focus events

The server does not automatically know about the input focus changes within a bean area. For the server to know a component in a bean area has the focus, the developer must use the registered property FOCUS_EVENT, defined in VBean. Using FOCUS_EVENT, bean area components can achieve mouse focus consistent with the rest of the components in a Forms applet. This allows the user to call help that is context-sensitive to the bean area.

How to use the FOCUS_EVENT registered property

The following are the initial requirements for using FocusListener and the registered property FOCUS_EVENT:

•	A bean area (bean wrapper class) implements the FocusListener interface.

•	All components in the bean wrapper class registers the bean wrapper as a FocusListener.

When a component in a bean area gets the focus, invoke the mHandler.setProperty() method with the registered property FOCUS_EVENT and the JDK’s FocusEvent as its arguments. FOCUS_EVENT is a registered property defined in VBean. The mHandler.setProperty() method tells the server that the bean area has the focus. The server does not track the focus to the individual component level of bean areas.

Focus events code example

This section explains the use of the FocusListener interface and FOCUS_EVENT registered property using code snippets. The complete sample class code is included at the end of the this section.

To use the FocusListener interface:

Implement FocusListener. Note that the class must also extend VBean. This example class is called BeanWrapper.

public class BeanWrapper

       extends VBean

       implements FocusListener, KeyListener

{

    // the Handler object passed to the view by Forms

    private IHandler mHandler;

Create the components. This example bean area includes four push buttons for four user choices.

    PushButton beanButton1 = new PushButton("BeanButton1");

    PushButton beanButton2 = new PushButton("BeanButton2");

    PushButton beanButton3 = new PushButton("BeanButton3");

    PushButton beanButton4 = new PushButton("BeanButton4");

Initialize the class, registering the FocusListener for each component. Note that addFocusListener is set for the bean area and each of the push buttons.

    // initialise the class

    public void init(IHandler handler)

    {

        super.init(handler);

        mHandler = handler;

        add(beanButton1,BorderLayout.NORTH);

        add(beanButton2,BorderLayout.EAST);

        add(beanButton3,BorderLayout.WEST);

        add(beanButton3,BorderLayout.SOUTH);

        addFocusListener(this);

        beanButton1.addFocusListener(this);

        beanButton2.addFocusListener(this);

        beanButton3.addFocusListener(this);

        beanButton4.addFocusListener(this);

    }

The focusGained() method gets called when the bean area or any of its children (components) gets the focus. FocusEvent, the standard JDK event object, is passed into the focusGained() method. The following is a typical example of the focusGained() method.

The beanButton1.requestFocus() method assigns the focus to the first component in the bean area when the bean area (wrapper) gets the focus. Invoke the mHandler.setProperty() method using the registered property FOCUS_EVENT and the event object (e) to tell the server the bean area has the focus.

    public void focusGained(FocusEvent e)

    {

        if (e.getComponent() == this)

        {

            beanButton1.requestFocus();

        }

        try

        {

            mHandler.setProperty(FOCUS_EVENT, e);

        }

        catch ( Exception ex )

        {

        }

    }

    public void focusLost(FocusEvent e)

    {

    }

Key events

Keystrokes from form items and bean area items in a Forms applet should produce consistent results. By default, Ctrl+K invokes the runtime Keys help screen for the form item that has focus. Tab moves the input focus from the current to the next form item. Shift+PageDown moves the input focus to the first form item in the next block. By default, however, keystrokes on bean area items do not produce these results.

To maintain consistent input focus and keystroke navigation in a Forms applet that contains a bean area, send most keystrokes from a bean area to the server using the KeyListener, KEY_EVENT registered property, and the mHandler.setProperty(KEY_EVENT, e) method. The server then performs the appropriate action. For example, pressing Ctrl+K causes the server to display the runtime Keys help screen for the bean area that has focus and pressing Shift+PageDown causes the server to move the focus to the first form item in the next block.

In some bean area keyboard navigation, however, it is important to not send certain keystrokes—some instances of Tab and Shift+Tab—to the server, depending on the position of the component in the bean area. The general rule is to send all bean area keystrokes to the server that should move the focus from the bean area. For keystrokes that move the focus between components in the same bean area, for example, Tab and Shift+Tab, do not send the keystrokes to the server.

Sending Tab and Shift+Tab keystrokes from a bean area component to the server causes the server to move the focus from the bean area to the next or previous form item respectively. With this in mind, there are situations where Tab and Shift+Tab keystrokes should be sent to the server: for the first component in a bean area, send Shift+Tab to the server, and for the last component in a bean area, send Tab to the server.

It is the responsibility of the developer to program what keystrokes are sent and what keystrokes are not sent to the server for components in a bean area.

Example

Background:

A form contains several items. A bean area is one of these items and it is located between other items. The bean area contains 4 push buttons.

Objective:

The user should be able to invoke standard form actions such as COMMIT and NEXT BLOCK using keystrokes from the bean area. The user should be able to press Tab to move the focus to the next push button in the bean area and press Shift+Tab to move the focus to the previous item in the bean area. When the user presses Tab from the last push button in the bean area, the focus should move to the next form item. When the user presses Shift+Tab from the first push button in the bean area, the focus should move to the previous form item.

Default Behavior:

Without implementing KeyListener, the KEY_EVENT registered property, and invoking the mHandler.setProperty(KEY_EVENT, e) method for the bean area components, no keystrokes are sent to the server. Tab and Shift+Tab move the input focus between bean area components. The server does not receive any keystrokes when keys are pressed to move focus from the bean area (for example, Shift+PageDown), so the form item with the apparent new focus may not really have the focus at the server. Pressing Ctrl+K for runtime Keys help displays runtime Keys help for the item the server identifies as having focus, which might be a different form item than the one that appears to have the focus. The next navigation keystroke, for example Tab, might produce a different result than expected because the navigation starts from the form item that the server identifies as having the focus. When keystrokes are not sent to the server, the server and client get out of sync on what is the current item.

Solution:

Implement KeyListener, use the KEY_EVENT registered property, and invoke the mHandler.setProperty(KEY_EVENT, e) method to send most keystrokes to the server. Choose to send or not to send Tab and Shift+Tab keystrokes for each of the push buttons to the server to move the focus as indicated in the objective.

Push Button 1:

When the user presses Tab from the last form item before the bean area, push button 1 in the bean area gets the focus. When the user presses Tab from push button 1, push button 2 gets the focus. The Tab keystroke should not be sent to the server, because sending the Tab keystroke causes the server to move the focus from the bean area to the next form item after the bean area.

When the user presses Shift+Tab from push button 1, the form item before the bean area must get the focus. The Shift+Tab keystrokes must be sent to the server, because sending the Shift+Tab keystrokes causes the server to move the focus to the previous form item. If the Shift+Tab keystrokes are not sent to the server, the server and client get out of sync on what is the current item.

Push Buttons 2 and 3 :

When the user presses Tab from push button 2, push button 3 gets the focus and again, the keystroke must not be sent to the server. (The same condition applies for pressing Tab from push button 3.) If the user presses Shift+Tab from push button 2, 3, or 4, the previous push button in the bean area gets the focus. These keystrokes should not be sent to the server. Whenever the focus is lost by one bean area component and gained by another, Tab and Shift+Tab keystrokes should not be sent to the server.

Push Button 4:

When the user presses Tab from push button 4, the last push button in the bean area, the keystroke must be sent to the server, because sending the Tab keystroke causes the server to move the focus from the bean area to the next form item. When the user presses Shift+Tab from push button 4 in the bean area, push button 3 gets the focus. Because the focus does not leave the bean area, the Shift+Tab keystrokes must not be sent to the server.

Summary

If the focus is on an element in the bean area and the user presses keystrokes that should move the focus out the bean area, send those keystrokes to the server. If the focus is on an element in the bean area and the user presses keystrokes that should move the focus to another element within that bean area, do not send those keystrokes to the server.

What keystrokes are not sent to the server depend on the element’s position in the bean area.

•	For the first component in a bean area, send all keystrokes except Tab to the server.

•	For the last component in a bean area, send all keystrokes except Shift+Tab to the server.

•	For all other components (except the first and last) in a bean area, send all keystrokes except Tab and Shift+Tab to the server.

How to use the KEY_EVENT registered property

To send the necessary keystrokes to the server for bean area components in a Forms applet, the developer must first implement the KeyListener interface:

The following are the initial requirements for using KeyListener:

•	A bean area (bean wrapper class) implements the KeyListener interface.

•	All components in the bean wrapper class registers the bean wrapper as a KeyListener.

With all components having registered KeyListener to the bean area, send all keystrokes except certain instances of Tab and/or Shift+Tab to the server depending on whether the keystrokes move the focus out of the bean area. Use the keyPressed() method of the KeyListener interface to filter keystrokes. For keystrokes that need to be sent to the server, the developer must invoke the mHandler.setProperty() method with the registered property KEY_EVENT (defined in VBean) and the JDK’s KeyEvent as its arguments.

Key events code example

This section explains the use of the KeyListener interface using code snippets. This example also includes FocusListener information. The complete sample class code is included at the end of the this section.

To use the KeyListener interface:

Implement KeyListener. Note that the class must also extend VBean. This example class is called BeanWrapper.

public class BeanWrapper

       extends VBean

       implements FocusListener, KeyListener

{

    // the Handler object passed to our view by Forms

    private IHandler mHandler;

Create the components. This example bean area includes four push buttons.

    PushButton beanButton1 = new PushButton("BeanButton1");

    PushButton beanButton2 = new PushButton("BeanButton2");

    PushButton beanButton3 = new PushButton("BeanButton3");

    PushButton beanButton4 = new PushButton("BeanButton4");

Initialize the class, implementing the KeyListener for each component. Note that addKeyListener is invoked on each of the push buttons.

    // initialise the class

    public void init(IHandler handler)

    {

        super.init(handler);

        mHandler = handler;

        add(beanButton1,BorderLayout.NORTH);

        add(beanButton2,BorderLayout.EAST);

        add(beanButton3,BorderLayout.WEST);

        add(beanButton3,BorderLayout.SOUTH);

        addFocusListener(this);

        beanButton1.addFocusListener(this);

        beanButton2.addFocusListener(this);

        beanButton3.addFocusListener(this);

        beanButton4.addFocusListener(this);

        beanButton1.addKeyListener(this);

        beanButton2.addKeyListener(this);

        beanButton3.addKeyListener(this);

        beanButton4.addKeyListener(this);

    }

The keyPressed() method gets called when any component in the bean area has the focus and the user presses any key. KeyEvent, the standard JDK key event object, is passed into the keyPressed() method.

The following is a typical example of the keyPressed() method used with several components in a bean area.

The conditions that follow include all of the push buttons in the bean area. For the first component of the bean area, send all keystrokes except Tab to the server. But do send the Shift+Tab keystrokes to the server to move the focus back out of the bean area and send all other keystrokes that invoke standard form actions such as displaying the runtime Keys help screen (Ctrl+K) and NEXT BLOCK (Shift+PageDown).

The first condition describes the event for the first component in the bean area, beanButton1. The e.getSource() method tests whether beanButton1 is pressed. The e.getKeyCode() method tests whether a keystroke is Tab (KeyEvent.VK_TAB). If the key sequence pressed does not include Tab, in the else statement, invoke the mHandler.setProperty() method using the registered property KEY_EVENT and the event object (e) to send the keystrokes to the server.

If Shift+Tab is pressed, invoke the mHandler.setProperty() method using the registered property KEY_EVENT and the event object (e) to send the keystrokes to the server.

    public void keyPressed(KeyEvent e)

    {

        if ( e.getSource() == beanButton1 )

        {

            /*

            ** For the first component in the bean area, send all

            ** keystrokes except Tab to the server. Also, send

            ** Shift+Tab to the server.

            */

            if ( (e.getKeyCode() == KeyEvent.VK_TAB) )

            {

                if (e.isShiftDown() )

                {

                    try

                    {

                        mHandler.setProperty(KEY_EVENT, e);

                    }

                    catch ( Exception ex )

                    {

                    }

                }

            }

            else

            {

                try

                {

                    mHandler.setProperty(KEY_EVENT, e);

                }

                catch ( Exception ex )

                {

                }

            }

        }

This condition describes the event for the last component (beanButton4) in the bean area. The e.getSource() method tests whether beanButton4 is pressed. The e.getKeyCode() method tests whether the key sequence is not Shift+Tab. If the key sequence is not Shift+Tab, invoke the mHandler.setProperty() method using the registered property KEY_EVENT and the event object (e) to send the key sequence to the server.

        else if ( e.getSource() == beanButton4 )

        {

            /*

            ** For the last component in the bean area, send all

            ** keystrokes except Shift+Tab to the server.

            */

            if ( !((e.getKeyCode() == KeyEvent.VK_TAB) && (e.isShiftDown())) )

            {

                try

                {

                    mHandler.setProperty(KEY_EVENT, e);

                }

                catch ( Exception ex )

                {

                }

            }

        }

For the remaining components of the bean area that are neither the first nor last components, send all keystrokes except Tab and Shift+Tab to the server. This example code is for the next components in the bean area, beanButton2 and beanButton3.

The e.getSource() method tests whether beanButton2 or beanButton3 is pressed. The e.getKeyCode() method tests whether the keystroke is not a Tab (KeyEvent.VK_TAB). If the keystroke is not Tab, invoke the mHandler.setProperty() method using the registered property KEY_EVENT and the event object (e) to send the keystrokes to the server.

        else if ( (e.getSource() == beanButton2) ||

                  (e.getSource() == beanButton3) )

        {

            /*

            ** For all the remaining components in the bean area,

            ** send all keystrokes except Tab and Shift+Tab

            ** to the server.

            */

            if ( !(e.getKeyCode() == KeyEvent.VK_TAB) )

            {

                try

                {

                    mHandler.setProperty(KEY_EVENT, e);

                }

                catch ( Exception ex )

                {

                }

            }

        }

}

Key events for one component in a bean area

If your bean area contains only one component (for example, beanButton1), send all key strokes on the component to the server. You must implement the KeyListener and use the keyPressed() method, but you can execute the mHandler.setProperty() method immediately.

The following example shows the code for the keyPressed() method for a single push button, beanbutton1, in a bean area.

public void keyPressed(KeyEvent e)

{

    try

    {

        mHandler.setProperty(KEY_EVENT, e);

    }

    catch ( Exception ex )

    {

    }

}

Complete code example for focus and key events

package oracle.forms.demos;

import oracle.forms.properties.ID;

import oracle.forms.handler.IHandler;

import oracle.forms.ui.CustomEvent;

import oracle.forms.properties.ID;

import oracle.forms.handler.IHandler;

import oracle.forms.ui.VBean;

import oracle.ewt.button.PushButton;

import java.awt.Component;

import java.awt.event.FocusEvent;

import java.awt.event.FocusListener;

import java.awt.event.KeyEvent;

import java.awt.event.KeyListener;

import java.awt.BorderLayout;

public class BeanWrapper

       extends VBean

       implements FocusListener, KeyListener

{

    // the Handler object passed to the view by Forms

    private IHandler mHandler;

    PushButton beanButton1 = new PushButton("BeanButton1");

    PushButton beanButton2 = new PushButton("BeanButton2");

    PushButton beanButton3 = new PushButton("BeanButton3");

    PushButton beanButton4 = new PushButton("BeanButton4");

    public BeanWrapper()

    {

        super();

    }

    // initialise the class

    public void init(IHandler handler)

    {

        super.init(handler);

        mHandler = handler;

        add(beanButton1,BorderLayout.NORTH);

        add(beanButton2,BorderLayout.EAST);

        add(beanButton3,BorderLayout.WEST);

        add(beanButton3,BorderLayout.SOUTH);

        addFocusListener(this);

        beanButton1.addFocusListener(this);

        beanButton2.addFocusListener(this);

        beanButton3.addFocusListener(this);

        beanButton4.addFocusListener(this);

        beanButton1.addKeyListener(this);

        beanButton2.addKeyListener(this);

        beanButton3.addKeyListener(this);

        beanButton4.addKeyListener(this);

    }

    public void focusGained(FocusEvent e)

    {

        if (e.getComponent() == this)

        {

            beanButton1.requestFocus();

        }

        try

        {

            mHandler.setProperty(FOCUS_EVENT, e);

        }

        catch ( Exception ex )

        {

        }

    }

    public void focusLost(FocusEvent e)

    {

    }

    /*

    ** If a particular key sequence causes the navigation to stay inside

    ** the bean area i.e. one the components of the bean area loses

    ** focus and the other component of bean area gains focus, then

    ** we do not want to send the keystrokes to the server. Otherwise,

    ** we do want to send the keystrokes to the server.

    **

    ** A key sequence is sent to the server by invoking

    ** mHandler.setProperty(KEY_EVENT, e).

    **

    ** For example, if the focus is on the first component(beanButton1) of

    ** the bean area, and if the user presses Tab, then the focus will be

    ** transferred to the second component(beanButton2) of the bean area.

    ** Since beanButton2 is inside the bean area, we do not want to send the

    ** keystrokes to the server. If instead of Tab the user presses

    ** Shift+Tab, then the focus needs to transferred to the previous form

    ** item, which is outside the bean area. In this case, we need to send

    ** the keystrokes to the server so that the server can determine the

    ** previous form item to which the focus should be transferred.

    **

    ** Similarly, if the focus is on  the last component(beanButton4) of the

    ** bean area, and if the user presses Tab, then the focus needs to be

    ** transferred to the next form item, which is outside the bean area.

    ** In this case, we do want to send the keystrokes to the server so

    ** that it can determine the next form item to which the focus should be

    ** transferred. If instead of Tab the user presses Shift+Tab, then

    ** the focus needs to be transferred to the previous component

    ** (beanButton3) in the bean area. Since beanButton3 is inside the bean

    ** area, we do not need to send the keystrokes to the server.

    **

    ** For other components in the bean area, such as beanButton2 and

    ** beanButton3, we do not want to send Tab and Shift+Tab to the form

    ** server. This is because both of them cause focus to be transferred

    ** to a bean area component. Anything else should be sent to the

    ** server.

    */

    public void keyPressed(KeyEvent e)

    {

        if ( e.getSource() == beanButton1 )

        {

            /*

            ** For the first component in the bean area, send all

            ** keystrokes except Tab to the server. Also, send

            ** Shift+Tab to the server.

            */

            if ( (e.getKeyCode() == KeyEvent.VK_TAB) )

            {

                if (e.isShiftDown() )

                {

                    try

                    {

                        mHandler.setProperty(KEY_EVENT, e);

                    }

                    catch ( Exception ex )

                    {

                    }

                }

            }

            else

            {

                try

                {

                    mHandler.setProperty(KEY_EVENT, e);

                }

                catch ( Exception ex )

                {

                }

            }

        }

        else if ( e.getSource() == beanButton4 )

        {

            /*

            ** For the last component in the bean area, send all

            ** keystrokes except Shift+Tab to the server.

            */

            if ( !((e.getKeyCode() == KeyEvent.VK_TAB) && (e.isShiftDown())) )

            {

                try

                {

                    mHandler.setProperty(KEY_EVENT, e);

                }

                catch ( Exception ex )

                {

                }

            }

        }

        else if ( (e.getSource() == beanButton2) ||

                  (e.getSource() == beanButton3) )

        {

            /*

            ** For all the remaining components in the bean area,

            ** send all keystrokes except Tab and Shift+Tab

            ** to the server.

            */

            if ( !(e.getKeyCode() == KeyEvent.VK_TAB) )

            {

                try

                {

                    mHandler.setProperty(KEY_EVENT, e);

                }

                catch ( Exception ex )

                {

                }

            }

        }

    }

    public void keyTyped(KeyEvent e)

    {

    }

    public void keyReleased(KeyEvent e)

    {

    }

    public boolean setProperty(ID pid, Object value)

    {

        return super.setProperty(pid,value);

    }

    public String toString()

    {

        return ("BeanArea Wrapper");

    }

}


Working with Libraries


About libraries

A library is a collection of subprograms, including user-named procedures, functions, and packages.

Libraries provide a convenient means of storing client-side program units and sharing them among multiple applications.

Once you create a library, you can attach it to any other form, menu, or library module.  Then, you can call library program units from triggers, menu item commands, and user-named routines you write in the modules to which you have attached the library.

The same library can be attached to multiple forms and menus.  Conversely, a single form or menu can have more than one attached library.

Libraries can also be attached to other libraries.  When a library attaches another library, program units in the first library can reference program units in the attached library.

Libraries support dynamic loading --that is, a library's program units are loaded into an application only when needed.  This can significantly reduce the runtime memory requirements of an application.


About global libraries

Global libraries can be shared across open forms.  A single copy of the PL/SQL library is stored in memory and is accessible by all forms.  Global libraries save memory, improve performance, and provide a mechanism for easy passing of array structures across forms.


About library file formats

.PLL	The library .PLL file contains both library source code and the compiled, platform-specific p-code (executable code).  The .PLL file is created or updated when you save your library module.  In addition, when you save your library module, the changes are reflected in each module to which the library is attached.

.PLX	The library .PLX file is a platform-specific executable that contains no source.

When you are ready to deploy your application, you will probably want to generate a version of your library that contains only the compiled p-code, without any source.  You can generate a .PLX file from Form Builder or from the command line.

Note:  When you attach a library to a module in Form Builder, you attach the .PLL version of the library. At runtime, Form Builder looks for a .PLX file by that name in the default search paths. If no .PLX file is present, Form Builder looks for the .PLL file by that name.

.PLD	The .PLD file is a text format file, and can be used for source-controlling your library files.


Creating a library

To create a library:

1	In the Object Navigator, create a library module.

To create a library, choose File [image] New [image] Library.

Or

Select the Libraries node and then choose Navigator [image] Create.

Note: You cannot change the name of a library module by editing it in the Object Navigator, as you can with forms and menus. Instead, the library name is updated automatically when you save the library.

2	To create a program unit, expand the desired library node, select the Program Units node, and then choose Navigator [image] Create.

The New Program Unit dialog appears.

3	Specify the program unit Name and its Type (either Procedure, Function, Package Spec, or Package Body).  Choose OK.

The PL/SQL Editor appears.

4	In the PL/SQL Editor, define your program unit and then choose Compile to compile and apply your modifications.  Choose Close to dismiss the editor.

Note: Because Form Builder cannot execute uncompiled program units at runtime, you must compile your library program units at design time.

Choose File [image] Compile to compile any uncompiled library program units, or choose File [image] Compile All to compile all library program units.

5	Choose File [image] Save to save the library module to a file or to the database.


Attaching a library to a module

To attach a library to a module:

1	In the Object Navigator, open the desired form, menu, or library module.

To open a module, choose File [image] Open and then specify the module type to open.

Note:  When you attach a library to a module in Form Builder, you attach the .PLL version of the library. At runtime, Form Builder looks for a .PLX file by that name in the default search paths. If no .PLX file is present, Form Builder uses the .PLL file by that name.

2	Expand the module and then select the Attached Libraries node.  Choose Navigator [image] Create to attach a library.

3	Specify the name of the library to attach.

Tip:  You should not specify a library path when attaching libraries.  Path names for library attachments are stored internally and, as a result, are not portable.  Instead, you should specify the name of the library and rely on the Form Builder' standard search path to locate your library at runtime.

When searching for attached libraries at runtime,  Form Builder first searches the current directory and then the directories listed in the PATH (FORMSxx_PATH and ORACLE_PATH) environment variables.

Note:  If you specify a library path, Form Builder prompts you to confirm the specified path.

If you confirm, at runtime, Form Builder will search for your library based strictly on the specified path; Form Builder will not search the specified path and then perform the standard search, as well.

If you do not confirm, Form Builder removes the path and saves the library name.  At runtime, Form Builder searches the standard search path to locate your library.

4	Save the active form or menu module to incorporate the library attachment in the module definition.

Note:  Attached libraries are read-only.  You cannot edit an attached library; you can only reference the program units within it.  To edit a library module, open it in the Object Navigator and use the PL/SQL Editor to edit program units.


Editing a library

You cannot edit or view library program units from the Attached Libraries node in the Object Navigator.  To edit or view library program units, you must open the library module itself.

When you edit a library, your modifications are not reflected in any modules the library is attached to until you save your changes.

To modify a library that is already attached to a module:

1	In the Object Navigator, open the library module and then add, edit, or remove program units from the library as desired.

2	Save the library module.

The changes are reflected in each module to which the library is attached.


Calling library program units

After you create a library and attach it to the desired module, you can call library program units from that module using the same syntax you would use if the program units were defined locally.  For example, to call a procedure named color_current_record in an attached library, you would simply write the name of the procedure in your form trigger:

color_current_record;

To refer to the contents of a library package, use standard PL/SQL dot notation, as shown here:

package_name.object

When Form Builder encounters a call to a program unit, it first looks for the program unit in the current module, then searches the attached libraries.

When you attach more than one library to the same module, you can specify the default library search order by sequentially ordering your library attachments in the Object Navigator.


Accessing forms bind variables in library program units

Because library modules are compiled independently of forms and menus, form bind variables (the values of form items, system and global variables, and parameters) are always outside the scope of library program units.  Consequently, you cannot refer directly to form bind variables in a library program unit.  For instance, a user-named procedure or function in a library cannot refer to the following objects:

•	:block_name.item_name

•	:GLOBAL.variable_name

•	:SYSTEM.variable_name

•	:PARAMETER.my_param

Instead, use the NAME_IN subprogram function to indirectly reference the values of bind variables:

•	Name_In('block_name.item_name')

•	Name_In('GLOBAL.variable_name')

•	Name_In('SYSTEM.variable_name')

Use the COPY subprogram procedure to indirectly set the values of bind variables:

•	Copy('28876', 'block_name.item_name');

•	Copy('standard', 'GLOBAL.variable_name');

•	Copy('FALSE', 'System.Supress_Working');

When COPY is used to set the value of a form item in a library routine, that item is marked as CHANGED.  This behavior can affect subsequent validation and commit processing.

Whenever possible, you should write library program units that rely on IN and IN OUT parameters for passing data between the form or menu module and the library.  You can also use function return values for this purpose.  When you call a library procedure that uses parameters, you can pass bind variable references as actual parameters, as shown here:

my_library_procedure(:form_block.form_item,:System.Cursor_Block);


About LOVs

  Related Topics

An LOV is a scrollable popup window that provides the end user with either a single or multi-column selection list.

LOVs provide the following functionality:

•	LOVs can be displayed by end user request (when an LOV is available), when the end user navigates to a text item with an associated LOV, or programmatically, independent of any specific text item.

•	LOV auto-reduction and search features allow end users to locate specific values.

•	LOV values that are selected by the end user can be assigned to form items according to the return items you designate.

•	At design time, an LOV can be attached to one or more text items in the form.

•	LOV values are derived from record groups.

At runtime, Form Builder displays the <LIST> lamp on the status line whenever an LOV is available.  Once invoked, either programmatically or by end user request, an LOV appears in a modal window, allowing the end user to select a single value.

An LOV remains displayed until the end user dismisses it by either selecting a value or choosing Cancel.

End users cannot work in other windows when an LOV is displayed.  End users can move and resize LOVs if the runtime window manager supports doing so.

Auto-reduction and Search Features  End users can use the LOV auto-reduction and search features to locate a value in a list.

To use auto-reduction, end users type the desired entry directly in the list pane of the LOV window.  As each character is entered, Form Builder reduces the list to only those values that match the string being entered.  Pressing [Delete Backwards] expands the reduced list of choices.  Auto-reduction works by comparing the string entered by the end user with the values in the first column displayed in the LOV.

If the LOV to be displayed contains a long list of possible values, the LOV window will display with only the column titles (and no values) displayed. Once the user enters a reduction string into the Find field and a query is performed on this reduction string, the resulting LOV values will be displayed beneath the column titles. The LOV will then resume its normal appearance and behavior, and the end user can select a value from the list or further reduce it by expanding the reduction string.

End users can use the search feature to locate a match for a specific text string and to do wildcard searches.  To use the search feature, the end user moves to the LOV's Find field and enters the search criteria string, then chooses the Find button to execute the search.  Form Builder shortens the list to those choices whose first column values match the end user's search criteria.  Note that if the end user precedes the search criteria with a "%" symbol, Form Builder will perform a search on all LOV columns.

End users can press the TAB key to move between the LOV list pane and the Find field.

Note:  The LOVs in the Form Builder interface have the same auto-reduction and searching functionality as the LOVs you create for your own applications.


About LOV values and record groups

LOV values are derived from an internal data structure called a record group.  When you define an LOV, you associate it with a named record group.

A record group has a column/row framework that is similar to a database table.  The LOV is the interface object that allows end users to view, scroll, and select records currently stored in the underlying record group.

A record group can have an unlimited number of columns of type CHAR, LONG, NUMBER, or DATE, provided that the total number of columns does not exceed 64K.

When you create an LOV, you specify which of the columns in the underlying record group should be displayed in the LOV window.  Record group columns are always displayed in the LOV window in the order that they occur in the record group.

Because LOVs and record groups are separate objects, you can create multiple LOVs based on the same record group.  For example, you might create two LOVs based on the same 4-column record group, each of which might display different columns from that record group.

Record Group Values  The actual values in a record group come from one of two sources:

•	the execution of a SELECT statement that you associated with the record group at design time (query record group)

•	an array of static values that you associated with the record group at design time (static record group)

Note:  By default, when an LOV is based on a query record group (a record group that has an associated SELECT statement), Form Builder executes the query each time the LOV is displayed, and fetches all of the records that meet the record group query criteria.  This functionality ensures that the LOV always displays current database values.


About LOV return items

  Related Topics

When you create an LOV you specify which columns from the underlying record group should be included in the LOV.  You can designate a return item for any column that you include in the LOV.  When the end user selects a choice from the LOV, Form Builder assigns the values from the columns in the selected record to their corresponding return items.

This feature enables end users to fill in a text item by selecting values from an LOV.  Typically, end users navigate to the text item and then press [List of Values] to invoke a list of entries that are valid for that item.  When the end user selects a value, Form Builder automatically returns that value into the text item.  Using an LOV saves keystrokes during data-entry and ensures that the value entered is valid for that item.

This feature can also be used to populate form items with values from hidden columns.  A hidden column is any column that was included in the LOV structure but whose values are not displayed in the LOV window.  (Remember that you specify which columns from the underlying record group are included in the LOV when you define the LOV.)

Consider an LOV that displays customer names.  The LOV is based on a query record group that includes columns from the Customer table, including name, id, phone, and contact.  There is a return item for each column in the LOV.

The end user can invoke the LOV by pressing [List of Values] from the cust_block.name text item.  When the end user selects a customer name from the LOV, Form Builder returns all of the information about that customer into the corresponding return items.


Creating an LOV

  Next Step	    Related Topics

To create an LOV using the LOV Wizard:

1	In the Object Navigator, click the LOVs node.

2	Click the Create button [image] in the toolbar.

3	In the New LOV dialog, choose Use the LOV Wizard.

Note: You can use the LOV Wizard to create an LOV based on an existing query record group, a new query record group (which you will create during the Wizard process), or an existing static record group. If you need to create an LOV based on a new static record group, first create the new static record group, and then use the LOV Wizard to create the LOV.

To create an LOV manually:

1	In the Object Navigator, click the LOVs node.

2	Click the Create button [image] in the toolbar.

3	In the New LOV dialog, choose Build a new LOV manually.

A new, generically-named LOV is created and displayed in the Object Navigator.

4	In the Object Navigator, double-click the object icon beside the new LOV to display the Property Palette.

5	Use the Property Palette to set the desired properties for the new LOV.


Modifying the query SELECT statement for an existing LOV

  Related Topics

To modify the query SELECT statement for an existing LOV:

1	Select the LOV in the Object Navigator.

2	Select Tools [image] LOV Wizard.

3	Click the Record Group tab at the top of the Wizard.

or

1	In the Object Navigator Record Groups node, double-click the object icon next to the record group on which the desired LOV is based to display the Property Palette.

2	Under the Functional node, change the Record Group Query property appropriately.

Note: Any other LOVs based on this record group may be affected by the change to the record group's query. Using the LOV Wizard enables you to create automatically a new record group based on the modified query and base the LOV on this new record group.


Viewing columns associated with an LOV

  Related Topics

To view the columns associated with an LOV:

1	Select the LOV in the Object Navigator.

2	Select Tools [image] LOV Wizard.

3	Click the Column Display tab at the top of the Wizard.

or

1	In the Object Navigator LOVs node, double-click the object icon beside the desired LOV to display the Property Palette.

2	Under the Functional node, double-click on Column Mapping Properties.

The LOV Column Mapping dialog appears, and Form Builder displays the names of the LOV’s columns in the LOV's Column Names list.


Removing a column from an LOV

  Related Topics

To remove a column from an LOV:

1	Select the LOV in the Object Navigator.

2	Select Tools [image] LOV Wizard.

3	Click the Columns tab at the top of the Wizard.

4	Columns listed under LOV Columns are those that are currently included in the LOV. To remove a single column, select the desired column and click [image]. To remove all the columns, click [image].

or

1	In the Object Navigator LOVs node, double-click the object icon beside the desired LOV to display the Property Palette.

2	Under the Functional node, double-click on Column Mapping Properties.  The LOV Column Mapping dialog appears.

3	Select the column to remove in the Column Name list and press [Delete Element].


Adding a column to an LOV

  Related Topics

To add a column to an LOV:

1	Select the LOV in the Object Navigator.

2	Select Tools [image] LOV Wizard.

3	Click the Columns tab at the top of the Wizard.

4	Columns listed under Record Group Columns are those that are not currently included in the LOV. To add a single column, select the desired column and click [image]. To add all the columns, click [image].

or

1	In the Object Navigator LOVs node, double-click the object icon beside the desired LOV to display the Property Palette.

2	Under the Functional node, double-click on Column Mapping Properties.  The LOV Column Mapping dialog appears.

3	Type the name of the record group column you wish to add to the LOV in the Column Names list.

4	Set the Display Width property to the width in appropriate units (points, pixels, centimeters, inches, or characters as specified by the form's Coordinate System property) that you want Form Builder to reserve for the column in the LOV window.

Note: The Display Width property defaults to the width specified for the column in the record group.  If the record group is a query record group, the default width is the width of the corresponding database column at the time the record group was created.

Tip:  To add extra space between columns in the LOV window, set the Display Width wider than the column's default width. Note, however, that as an exception to this rule, you cannot increase the width between a NUMBER column and a non-NUMBER column by increasing the display width for the NUMBER column because LOVs display numbers right-justified.

For example, assume that your LOV contains 3 columns: column 1 and 3 are type CHAR and column 2 is type NUMBER.  To increase the width between each column, increase the Display Width for columns 1 and 3.


Hiding a column in an LOV

  Related Topics

To hide a column in an LOV:

1	Select the LOV in the Object Navigator.

2	Select Tools [image] LOV Wizard.

3	Click the Column Display tab at the top of the Wizard.

4	All columns in the LOV are listed in the table. For any column you want to hide, change the Width value to zero in the table.

or

1	In the Object Navigator LOVs node, double-click the object icon beside the desired LOV to display the Property Palette.

2	Under the Functional node, double-click on Column Mapping Properties.  The LOV Column Mapping dialog appears.

3	Select the desired column and then set the Display Width property to zero.  (Note that hidden columns, like displayed columns, can still be assigned to return items.)


Creating an LOV column title

  Related Topics

To create a column title:

1	Select the LOV in the Object Navigator.

2	Select Tools [image] LOV Wizard.

3	Click the Column Display tab at the top of the Wizard.

4	All columns in the LOV are listed in the table. Change the Title value for the column  to the desired column title.

or

1	In the Object Navigator LOVs node, double-click the object icon beside the desired LOV to display the Property Palette.

2	Under the Functional node, double-click on Column Mapping Properties.  The LOV Column Mapping dialog appears.

3	Select the desired column in the Column Names list and then enter the desired title in the Column Title property field.

Tip:  When creating titles, consider the column's display width.  Form Builder truncates a title that does not fit in the display width reserved for the values in that column.  (Remember that changing the font size of the LOV text can change the number of characters that fit in a given display width.)


About specifying LOV return items

  Related Topics

You can specify a return item for any column in the LOV.  When an end user selects a choice from the LOV, Form Builder assigns the selected value to the corresponding return item.

The return item can be an item in the current form, a global variable, or a form parameter.  Enter the name of the return item using the appropriate syntax:

An item:	customer.name
A global variable	GLOBAL.my_global
A form parameter:	PARAMETER.my_parameter
(Do not preface the object name with a colon.)

Note:  The data type of the return item must be compatible with the data type of the value being returned.

Remember that you can designate a return item for a hidden column (a column with its Display Width set to zero).

The return items can be specified using column properties or in the record group query SELECT statement of an LOV based on a query record group.


Specifying LOV return items using column properties

  Related Topics

To specify an LOV return item:

1	Select the LOV in the Object Navigator.

2	Select Tools [image] LOV Wizard.

3	Click the Column Display tab at the top of the Wizard.

4	All columns in the LOV are listed in the table. Change the Return Value for the column to the name of the desired return item. You can use the Look up return item button to help you find the correct return item for the column.

or

1	In the Object Navigator LOVs node, double-click the object icon beside the desired LOV to display the Property Palette.

2	Under the Functional node, double-click on Column Mapping Properties.  The LOV Column Mapping dialog appears.

3	Select the desired column in the Column Names list.

4	In the Return Item field, enter a name (item, global variable, or parameter).

Tip:   If you do not want a column to be returned, leave the Return Item property blank.


Specifying LOV return items in the SELECT statement

  Related Topics

To specify a return item in the SELECT statement:

If you are creating an LOV based on a query record group, you can specify return items in the SELECT statement.

From the New LOV dialog, add the appropriate INTO clause in your SELECT statement and then click OK.

For example, assume you want all of the information about a customer to be returned into the appropriate form items whenever an end user chooses a name from the customer LOV.  To do so, you might write the following SELECT statement when you create the record group in the New LOV dialog:

SELECT id, name, contact, phone
INTO :cust.id, :cust.name :cust.contact, :cust.phone
FROM CUSTOMER;

When you choose the OK button to create the record group, Form Builder parses the SELECT statement and inserts the names of the return items in the Return Item field for you automatically.

The order of the return items referenced in the INTO clause must correspond to the order of the database columns referenced in the SELECT clause.

Note:  The INTO clause establishes the relationship between the LOV and the return items but does not affect the definition of the resulting record group.  When you view the new record group in the Property Palette, you see only the SELECT statement without the INTO clause.  It is the LOV itself that is associated with the return items, not the record group object.


About validating text items using LOV values

  Related Topics

When you attach an LOV to a text item, you can set the optional Validate from List property to have Form Builder validate the value of the text item against the values in the LOV.

When Validate from List is set to Yes, Form Builder compares the current value of the text item to the values in the first column displayed in the LOV whenever the validation event occurs:

•	If the value in the text item matches one of the values in the first column of the LOV, validation succeeds, the LOV is not displayed, and processing continues normally.

•	If the value in the text item does not match one of the values in the first column of the LOV, Form Builder displays the LOV and uses the text item value as the search criteria to automatically reduce the list.

For example, if the end user enters the first three digits of a 6-digit product code and then tries to navigate to the next item, Form Builder displays the LOV and auto-reduces the list to display all of the codes that have the same first three digits.

•	If the end user selects a value from the LOV, Form Builder dismisses the LOV and assigns the selected values to their corresponding return items.

When you use an LOV for validation, Form Builder always marks a text item as Valid if the end user selects a choice from the LOV.  Thus, it is your responsibility to ensure that a) the text item to which the LOV is attached is defined as a return item for the first column displayed in the LOV and b) the values in the LOV will actually be valid.

Note:  Although the item is marked as valid internally, the When-Validate-Item trigger still fires if present.

Note also that the first column displayed in the LOV may not be the first column in the LOV's underlying record group, as some record group columns may not have been included in the LOV structure, or may be hidden columns.


Using LOV values to validate text items

  Related Topics

To use LOV values to validate a text item:

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the List of Values (LOV) node, set the Validate from List property to Yes.


About attaching LOVs to text items

  Related Topics

You can attach an LOV to one or more text items in a form.  When the end user or the application navigates to a text item to which an LOV is attached, Form Builder displays the LOV list lamp on the status line to indicate that an LOV is available.  End users can invoke the LOV by pressing [List of Values].

Or, if you set the LOV's Automatic Display property to Yes, Form Builder displays the LOV automatically when the end user navigates to the text item.


Attaching an LOV to a text item at design time

  Next Step	    Related Topics

To attach an existing LOV to a text item:

1	Select the LOV in the Object Navigator.

2	Select Tools [image] LOV Wizard.

3	Click the Items tab at the top of the Wizard.

4	The items listed under Return Items are those to which the LOV returns a value when the user selects it. To attach the LOV to one of these items, select the item and click [image]. To attach the LOV to all of these items, click [image].

or

1	In the Object Navigator, double-click the object icon beside the desired text item to display the Property Palette.

2	Under the List of Values (LOV) node, set the LOV property by entering the name of the LOV you want to attach to the text item.

3	Set the LOV's display coordinates by setting the List X Position and List Y Position properties.

Tip:  Leave the coordinates set to 0,0 (the default) if you want Form Builder to use the LOV's default display position.   Change the List X/Y Position properties to any values other than 0,0 if you want to override the LOV's default display position.


Attaching an LOV programmatically at runtime

  Related Topics

You can attach an LOV to a text item programmatically with the SET_ITEM_PROPERTY built-in subprogram. The following example attaches the LOV called lov2 to the text item called emp.empno:

Set_Item_Property('emp.empno',LOV_NAME,'lov2');

Conversely, to find out which LOV is attached to a text item, call GET_ITEM_PROPERTY:

IF Get_Item_Property('emp.empno',LIST) = 'lov1' THEN
   Set_Item_Property('emp.empno',LIST,'lov2');
END IF;

If you need to know whether a text item currently has an LOV attached, you can call GET_ITEM_PROPERTY with the LIST constant:

IF Get_Item_Property('emp.empno',LIST) = 'TRUE' THEN...


Displaying an LOV programmatically

There are two built-in subprograms that can be used to display an LOV:

•	LIST_VALUES

•	SHOW_LOV

Using LIST_VALUES to Display an LOV  The LIST_VALUES procedure displays an LOV if the following runtime conditions exist:

•	the current item in the form is a text item

•	the text item has an LOV attached to it

The LIST_VALUES procedure is often called from a When-New-Item-Instance trigger to display an LOV when the end user or the application navigates to a text item that has an attached LOV.

The LIST_VALUES procedure can also be called from a Key-LISTVAL trigger.  This trigger fires when an end user presses [List of Values].  By calling LIST_VALUES from a Key-LISTVAL trigger, you can augment default form processing for the [List of Values] key.

Recall that Form Builder displays an LOV by default when the end user presses [List of Values] in a text item to which there is an LOV attached. You can duplicate this default functionality by writing a Key-LISTVAL trigger that calls the LIST_VALUES procedure:

Key-LISTVAL Trigger:

List_Values;

This trigger, as written, is of little value since it merely duplicates default Form Builder functionality.  However, using a Key-LISTVAL trigger allows you to add subsequent PL/SQL statements that execute after the LOV is displayed, but before Form Builder returns to the normal event sequence.

In the following example, an IF statement is added to the previous trigger:

Key-LISTVAL Trigger:

List_Values;
IF :customer.id IS NULL THEN
   Go_Item ('customer.id');
END IF;

In this example, when an end user enters the text item and presses [List of Values], Form Builder displays the attached LOV, in this case, a list of customer names.  After the end user selects a customer from the list, the trigger navigates to another item if the value of one of the return items (customer.id) is NULL.

Remember that end users can dismiss an LOV without making a selection; any PL/SQL statements that execute after the LIST_VALUES procedure should be written accordingly.

Using SHOW_LOV to Display an LOV  The SHOW_LOV function displays an indicated LOV at the specified display coordinates.  Unlike LIST_VALUES, SHOW_LOV does not require that the LOV be attached to a text item.  For example, you can use SHOW_LOV to allow end users to invoke an LOV by clicking a button or selecting a menu item.

The SHOW_LOV function is a BOOLEAN function that returns TRUE if the end user makes a selection from the LOV and FALSE if the end user cancels the LOV without making a selection.

The simplest way to call the SHOW_LOV function is to assign the return value of SHOW_LOV to a dummy variable, as shown in the following When-Button-Pressed trigger.

When-Button-Pressed Trigger:

DECLARE
   dummy	 BOOLEAN;
BEGIN
   dummy := Show_LOV('my_lov',15,10);
END;

The display coordinates specified in the SHOW_LOV argument list (15 and 10) override the LOV's default coordinates.

If you want to take some action based on whether the end user made a selection or canceled the LOV, you could structure your trigger as follows:

When-Button-Pressed Trigger:

IF Show_LOV('my_lov',15,10) THEN
/* the end user made a selection and Form Builder returned
** the selected column values to the corresponding
** return items so do something here
*/
Message('Good Choice!');
ELSE
/* The end user canceled the LOV without making a selection
** so do something else instead
*/
Message('Please enter a value.');
END IF;

In this example, the SHOW_LOV function is used as the test condition for an IF-THEN-ELSE construct.  If the end user selects a choice from the list, the condition is TRUE and Form Builder executes the first set of conditional statements.

If the end user cancels the LOV without making a selection, the condition is FALSE and Form Builder executes the second set of conditional statements.


Reusing an LOV

You can display the same LOV at more than one place in an application.  This technique is useful for applications that allow end users to access the same information in more than one context.  For example, you might want end users to be able to select a customer name from an LOV when they enter a new order and also when they generate a monthly billing statement.

To use an LOV in more than one place in an application, you could assign the column values from the selected record to different return items depending on application context.

You can accomplish this by using global variables or form parameters as return items in conjunction with the SHOW_LOV built-in subprogram.

For example, you might define an LOV based on a 4-column record group that returns values into 4 global variables, named GLOBAL.one through GLOBAL.four.

When you write the trigger to display the LOV, you also assign the values of the global variable return items to the form items appropriate for the current application context:

Trigger Text:

IF Show_LOV('generic_lov') THEN
/* The end user made a selection and Form Builder assigned
** the selected values to the global variable return items.
** Now assign those values to the appropriate form items:
*/
   :block_A.item1 := :GLOBAL.one;
   :block_A.item2 := :GLOBAL.two;
   :block_A.item3 := :GLOBAL.three;
   :block_A.item4 := :GLOBAL.four;
END IF;


Setting LOV properties at runtime

You can use the following built-in subprograms to get and set LOV properties at runtime:

•	GET_LOV_PROPERTY

•	SET_LOV_PROPERTY

The procedure SET_LOV_PROPERTY can be used to set the following LOV properties:

•	GROUP_NAME

•	Size

•	X Position, Y Position

By setting the GROUP_NAME property, you can replace an LOV's underlying record group with a different record group.  The following example associates a record group named new_group with the LOV named my_lov, by setting the GROUP_NAME property:

Set_LOV_Property('my_lov',GROUP_NAME,'new_group');

The new record group remains associated with the LOV for the duration of the session, or until it is replaced again by a call to SET_LOV_PROPERTY.

When you replace an LOV's record group with a different record group, the new record group must:

•	exist in the form when SET_LOV_PROPERTY is called

•	have column names and types that match the column names and types in the record group being replaced


Using an LOV with a REF column

The following example illustrates use of an LOV with an Oracle8 REF column.  This technique can be used for REF lookups until full PL/SQL coding support becomes available.

From an object table called O_EMP, create a block called O_EMP having these items:

  MGR

  DEPTREF

  EMPNO

  ENAME

  JOB

  SAL

  COMM

  MGR_ENAME

  DEPTREF_DNAME

Create a record group, called RG, with the following query.  (Note that o is the alias for the o_emp table in this example.)

  select o.ename from o_emp o

Create a record group, called MGRS, with the following query.

  select ref(o) refemp, o.ename from o_emp o

Create an LOV, also called MGRS, based on the MGRS record group.  This LOV is attached to the MGR_ENAME item.

Create a WHEN-VALIDATE-ITEM trigger attached to the MGR_ENAME item.  This trigger contains the following code:

  DECLARE

     mgrref   VARCHAR2(128);
     mgrrec   NUMBER;

  BEGIN

     mgrrec := POPULATE_GROUP(‘mgrs’);
     mgrrec := GET_GROUP_RECORD_NUMBER(‘mgrs.ename’, :o_emp.mgr_ename);

     IF mgrrec <> 0 THEN

          mgrref := GET_GROUP_CHAR_CELL(‘mgrs.refemp’, mgrrec);
          COPY(mgrref, ‘o_emp.mgr’);

     ELSE

          MESSAGE(‘Manager name not found’);
          RAISE FORM_TRIGGER_FAILURE;

     END IF;

  END;

The above code gets the REF value and puts it into a local varchar2 variable, and then copies it into the item.  The above code is equivalent to the PL/SQL statement

:o_emp.mgr := get_group_char_cell(‘mgrs.refemp’, mgrref);.


LOV Wizard: Welcome page

  Next Step	  Related Topics

About the LOV Wizard

The LOV Wizard enables you to create and modify a list of values (LOV). An LOV is a scrollable popup window that provides the user with a single- or multi-column selection list. You can use the LOV Wizard to create an LOV based on an existing record group or a new record group populated by a SQL query.

The LOV Wizard is Re-entrant

The LOV Wizard can operate in re-entrant mode.  In re-entrant mode, you can use the LOV Wizard to modify an existing LOV, even if the LOV was not originally created using the Layout Wizard.

To invoke the LOV Wizard in re-entrant mode, select an existing LOV in the Object Navigator and choose Tools [image] LOV Wizard. In re-entrant mode, you can navigate through the wizard's pages using tabs at the top of the window.

Navigating in the LOV Wizard

The LOV Wizard provides six buttons to help you navigate through its pages:

•	Cancel  Cancel any changes you have made and exit the wizard

•	Help  Display online help for the current wizard page.

•	Back  Navigate to the previous page in the wizard.

•	Next  Navigate to the next page in the wizard.

•	Apply  Apply changes you have made without exiting the wizard (re-entrant mode only).

•	Finish  Save any changes you have made and exit the wizard.

In the re-entrant LOV Wizard, you can also navigate by means of the tabs at the top of the Wizard pages. The arrow buttons to the right of the tabs enable you to see tabs that are not visible beyond the edge of the Wizard.

Note: If you click Next or Back before you have entered all required information for a particular wizard page, the wizard prevents you from navigating away from the page. Similarly, if you have not entered all required information into the wizard when you click Apply or Finish, the wizard automatically places you onto the page where data is missing or incorrect.

Display Page Next Time

The LOV Wizard Welcome Page is automatically displayed the first time you invoke the LOV Wizard. If you do not wish this page to display on future invocations of the wizard, uncheck the Display this page next time checkbox. This setting can also be changed in the Preferences dialog box.


LOV Wizard: LOV Source page

  Next Step 	   Related Topics	  About the LOV Wizard

To specify the source for the new LOV:

1	If the new LOV is to be based on a new record group, select the New Record Group based on a query radio button. (You will specify the query for this new record group on a subsequent wizard page.)

Note: The LOV Wizard does not support the creation of LOVs based on new static record groups. You can, however, base your LOV on an existing static record group. See below.

2	If the new LOV is to be based on an existing record group, select the Existing Record Group radio button. Select the desired record group in the drop-down list. This list displays the names of all available query and static record groups in the form.


LOV Wizard: Record Group page

  Related Topics	  About the LOV Wizard

This page is displayed only when the LOV Wizard is used in re-entrant mode to modify an existing LOV based on a query record group.

If you use the re-entrant LOV Wizard to modify the record group query on which the LOV is based, you may choose to modify the existing record group, or instead to create a new record group based on the modified query. If you choose to modify the existing record group, note that any other LOVs based on the same record group may be affected by the change.


LOV Wizard: SQL Query page

  Next Step	  Related Topics	  About the LOV Wizard

Use this page to specify the SQL query that will be used to construct the record group on which the LOV will be based. This page is displayed only when a new LOV is being created.

If you selected an existing record group on the LOV Source page, or if you are using the wizard in re-entrant mode, the text field on this page will already contain the SQL query on which the selected record group is based.

To specify or modify the SQL query:

1	To enter the query directly, type the appropriate SQL code directly into the text field in the middle of the page.

2	To use Forms Developer Query Builder to help you build the query, click the Build SQL Query button.

3	To import a SQL query from a file, click the Import SQL Query button.

To check the syntax of the SQL query in the text field:

Click the Check Syntax button. (If you are not already connected to the database, this will invoke the Connect dialog. You must connect to the database before the query syntax can be checked.)

To connect to the database:

Click the Connect button.

Note: If on the LOV Source page you choose to base the LOV on an existing static record group, this page will not be displayed, and you will skip automatically to the Column Properties page.


LOV Wizard: Column Selection page

  Next Step	  Related Topics	  About the LOV Wizard

The columns in an LOV are a subset or the entire set of the columns in the record group on which the LOV is based. Use this page to choose the columns that will be included in the LOV.

To select columns to be included in the LOV:

1	To add an individual column to the LOV:

•	Select the column in the Record Group Columns list.

•	Click the [image] button.

2	To include all columns in the LOV:

•	Click the [image] button.

3	To remove an individual column from the LOV:

•	Select the column in the LOV Columns list.

•	Click the [image] button.

4	To remove all columns from the LOV:

•	Click the [image] button.


LOV Wizard: Column Display page

  Next Step  	  Related Topics	  About the LOV Wizard

Use this page to specify display properties for the columns you have included in the LOV.

The table lists the LOV column names and their properties:

•	Title  The LOV column title. The default column title is the name of the record group column.

•	Width  The LOV column display width. The default column value width depends on the data type and width of the corresponding record group column. You can specify a column width of 0 to indicate that the column should be included but not displayed in the LOV.

•	Return Value A parameter or global variable name to which the column value should be assigned. The default value is NULL. This is an optional item.

The Look Up Return Item button displays a list of all the items and parameters in a form. The items are prefixed with the block name (block_name.item_name) and the parameters will be prefixed with the word parameter (parameter.parameter_name). Select an entry in this list and then click OK to copy the entry into the Return Value field of the selected column.

To change a column property:

1	Select the appropriate field in the table.

2	Enter the desired value.

Note: The LOV column names cannot be edited, because they are taken from the record group on which the LOV is based.

The Automatically Size Columns checkbox specifies whether the LOV column widths should be determined automatically. (If the column width is set to 0, the column is always hidden, regardless of how Automatically Size Columns is set.) This checkbox sets the LOV property Automatic Column Width.

•	If Automatically Size Columns is checked, Form Builder determines the column width at runtime by using the greater of the following two values:

•	the column width specified for the column

•	the column width needed to completely display the column title

•	If Automatically Size Columns is unchecked, the specified column width is used, even if the column title is partially hidden.


LOV Wizard: LOV Display page

  Next Step	  Related Topics	  About the LOV Wizard

Use this page to control the appearance, size, and position of the LOV dialog shown at runtime.

•	LOV Title  Title of the LOV dialog box.

•	Width  Width of the LOV dialog box.

•	Height  Height of the LOV dialog box.

Form Builder can automatically position your LOV at runtime near the field from which it was invoked. Alternatively, you can manually specify a position at which the LOV will be placed when it is invoked. If you select this option, you must specify coordinates:

•	Top  Distance between the top of the LOV window and the top of the display area.

•	Left  Distance between the left border of the LOV window and the left border of the display area.


LOV Wizard: Advanced Options page

  Next Step 	  Related Topics	  About the LOV Wizard

Use this page to set the following advanced properties. (If you are not familiar with the use of these properties, it is recommended that you accept the default values as they are displayed.)

•	Record Group Fetch Size  Specifies the size of the record group to be fetched. A larger fetch size reduces the number of fetches required to obtain the record group. If the LOV is based on a static record group, this field will be disabled.

•	Filter Before Display  If checked, no records are displayed when the LOV is first invoked at runtime. The user can enter a value in the Find field and press the Find button, and then only records that satisfy the entered criteria will be displayed. If not checked, all records will be displayed in the LOV when it is invoked.

•	Automatically Refresh LOV  If checked, the records displayed in the LOV will be queried every time the LOV is invoked. If not checked, the records retrieved on the initial LOV invocation will be cached and reused on subsequent invocations.


LOV Wizard: Items page

  Next Step	  Related Topics	  About the LOV Wizard

Use this page to attach your LOV to some or all of the return items you specified on the Column Display page of the LOV Wizard.

When the user or the application navigates to a text item to which an LOV is attached, Form Builder displays the LOV list lamp on the status line to indicate that an LOV is available. Users can invoke the LOV by pressing [List of Values].

If you specified any return items on the Column Display page, they will be listed in the "Return Items" column. Items to which the LOV is assigned are listed in the "Assigned Items" column.

To attach the LOV to an item:

1	To attach the LOV to a single item:

•	Select the item in the Return Items list.

•	Click the [image] button.

2	To attach the LOV to all items:

•	Click the [image] button.

3	To detach the LOV from a single item:

•	Select the column in the Return Items list.

•	Click the [image] button.

4	To detach the LOV from all items:

•	Click the [image] button.


LOV Wizard: Finish page

  Related Topics	  About the LOV Wizard

What's next?

When you click Finish, the LOV Wizard closes, and your new LOV (and associated record group, if appropriate) is created.

You can further customize the appearance and behavior of your LOV by modifying its properties in the Property Palette. Select the LOV in the Object Navigator and choose Tools [image] Property Palette. You can also modify the LOV in the LOV Wizard by selected the LOV in the Object Navigator and choosing Tools [image] LOV Wizard.


Layout Wizard: Welcome page
About the Layout Wizard

  Next Step	  Related Topics

About the Layout Wizard

The Layout Wizard enables you to quickly and easily layout the items of a data block.  The wizard displays the items in a frame on a canvas, and lays them out in one of several layout styles.

Use the Layout Wizard to complete the following tasks:

•	select or create a canvas (layout surface) on which to place a frame and data block items

•	select data block items to display in the layout, and the data types of the items

•	set item prompts, width and height

•	select a layout style and title for the frame containing your layout

•	specify the number of records in the frame, and the distance between those records

•	display a scrollbar

The Layout Wizard is re-entrant

A powerful quality of the Layout Wizard is its ability to operate in re-entrant mode.  This means you can use the Layout Wizard to modify the layout of an existing frame—even if the frame was not originally created with the Layout Wizard.

To invoke the Layout Wizard in re-entrant mode, select an existing frame in the Object Navigator (under the Canvases node) or Layout Editor, and choose Tools [image] Layout Wizard.

Navigating in the Layout Wizard

The Layout Wizard provides six buttons to help you navigate your way through its pages:

•	Cancel  cancel all changes you have made (if any), and exit the wizard

•	Help  display online help text for the current page of the wizard

•	Back  navigate to the previous page in the wizard

•	Next  navigate to the next page in the wizard

•	Apply  apply changes you have made without exiting the wizard (re-entrant wizard only)

•	Finish  save changes you have made with the wizard (if any), and exit the wizard

Note:  If you click Next or Back before you have entered all necessary information for a particular wizard page, the wizard prevents you from navigating to the next (or previous) page.  Similarly, if you have not entered all necessary information into the wizard when you click Apply or Finish, the wizard automatically places you onto the page where you can finish entering the required data.


Layout Wizard: Canvas page

  Next Step 	  About the Wizard

To select a canvas:

1	On the Canvas page, select a canvas name from the Canvas poplist.

You can select an existing canvas, or create a new canvas.

2	If you select (New Canvas), select a canvas type from the Type poplist.

For more information about the choices available, see About canvas types

If you select Tab from the Type poplist, you also must specify a tab page from the Tab Page poplist.

Note:  The Canvas page is not available in the re-entrant Layout Wizard;  to move a frame to another canvas, use the Layout Editor to cut and paste the frame to the new canvas.


Layout Wizard: Data Block page

  Next Step	  About the Wizard

To display data block items in the frame:

1	On the Data Block page, select a block from the Data Block poplist.

Note:  If you accessed the Layout Wizard directly from the Data Block Wizard, the Data Block poplist is disabled.

2	Select the data block item(s) from the Available Items list that you wish to display in the frame.

3	To add item(s) to the frame's layout, select the item(s) and:

•	click  [image]  to move the selected item(s) from the Available Items list to the Displayed Items list (to move all available items, click  [image] ).

or

•	drag-and-drop the item(s) from the Available Items list to the Displayed Items list.

•	When you move an item from the Available Items list to the Displayed Items list, the wizard places the item on the frame's canvas and sets its Displayed property to Yes.

4	To move an item or items out of the Displayed Items list (and thus out of the frame), select the item(s) and:

•	click  [image]  or  [image] .

or

•	drag-and-drop the item(s) from the Displayed Items list to the Available Items list.

When you move an item from the Displayed Items list to the Available Items list, the wizard removes the item from the frame's canvas and sets its Displayed property to No.

5	For each item you move to the Displayed Items list, use the Item Type poplist to specify a datatype.

Note:  If the item is a radio group, select the item in the Displayed Items list, then use the View poplist to change the wizard's focus (from the radio group itself to the radio buttons that comprise the group).  That way you can reorder the radio buttons, or set the prompt, width or height of a radio button (on the Items page).


Layout Wizard: Items page

  Next Step	  About the Wizard

To set item prompt, width and height:

•	On the Items page, specify prompt text, width, and height for each item displayed in the frame's layout.

A prompt is a textual label that is physically attached to an item.  If you update the layout of the data block items in the Layout Editor, moving an item also will move its prompt.

Note:  The units for item width and height are displayed at the top of the Items page.  To change the unit of measurement for items, set the Coordinate System property (form-level).


Layout Wizard: Style page

  Next Step	  About the Wizard

To select a layout style for the frame:

•	On the Style page, click a radio button to choose between a form layout and a tabular layout.

Form layout style is well-suited for a single-record block, while tabular layout style is better-suited for a data block that displays multiple records.

Note:  The Layout Wizard supports most format choices.  If you wish to create an unusual layout (for example, have a tabular layout with a horizontal orientation), you can do so outside the Wizard by manually setting the appropriate properties.


Layout Wizard: Rows page

  Next Step	  About the Wizard

To set frame title and record properties:

1	On the Rows page, enter the title you wish to display at the top of the frame in the Title field.

2	In the Records Displayed field, enter the number of records you wish to display in the frame (the default is 1).

If the layout style of the frame is:

•	Form—common when the data block is a master block—set the number of displayed records to 1.

•	Tabular—common when the data block is a detail block—adjust the number of displayed records to display the desired number of detail records.

3	In the Distance Between Records field, enter the physical distance (measured in the form's coordinate system units) with which to separate the records displayed in the frame.

4	To display a scrollbar adjacent to the frame (both at design-time and runtime), set the Display Scrollbar checkbox to checked. Scrollbars are typically useful for multi-record blocks.


Layout Wizard: Finish page

  About the Wizard

What's next?

Having finished laying out the items of the data block in a frame, you are ready to exit the Layout Wizard and continue work on the application.  When you click Finish, the wizard will close the Layout Wizard, and automatically display the layout of your frame in the Layout Editor, one of Form Builder's design tools.

Hint:  To further customize the appearance and functionality of the frames in your form, you can set various frame-related properties in the Property Palette.  Select the frame in the Object Navigator (under the Canvases node), and choose Tools [image] Property Palette.


About menus

  Related Topics

Menus are lists of items that end users use to select specific functions or operations.  Each item on a menu represents a command or a submenu.

Form Builder supports three basic menu types:

•	form menus

•	menu toolbars

•	popup menus

Form Menus  A form menu typically includes standard form-level commands for navigation, editing, and database interaction.  Every form runs with one of the following form menus:

•	default

•	custom

•	none

Menu Toolbars  If you create any type of custom form menu module for your form, you also can derive a menu toolbar from that form menu.  A menu toolbar displays selected menu items (from the current form menu) as icons on a horizontal or vertical ribbon.

Popup Menus  In addition to one form menu, each form can include any number of popup menus.  Popup menus are context-sensitive menus attached to individual canvases and items within a form.


About menu design

  Related Topics

Simplicity and ease of use are important attributes of any menu system.  When designing menus, your primary goal is to provide end users with quick and intuitive access to commonly-used functions and commands.  A few basic guidelines to building effective menus are as follows:

•	group similar commands together on a menu

•	limit the number of items on any menu to no more than 10

•	create submenus to further categorize similar menu items

Menu Editor  Form Builder provides a very powerful design tool for creating and modifying menus—the Menu Editor.  While you can use the Object Navigator and Property Palette to create menus hierarchically, use the Menu Editor if you prefer to see the physical structure of a menu as you build it.  The Menu Editor allows you to create and arrange menu objects easily and quickly.


About the default form menu

  Related Topics

The default form menu is an internal component of Form Builder; it is not a separate menu module (i.e., it is not a workable file).  Form Builder automatically attaches the default form menu to any new form you create, unless you specify otherwise.  The only time you must explicitly attach the default menu to a form is when the form's Menu Module property previously has been modified.

The default form menu includes standard commands that correspond to Forms Runtime function keys:

Action	Edit	Query	Block	Record	Field	Help
Save*	Cut*	Enter*	Previous*	Previous*	Previous	Help*
Clear all	Copy*	Execute*	Next*	Next*	Next	Keys
Print*	Paste*	Cancel*	Clear	Scroll up	Clear	Display error
Print Setup*	Edit	Last Criteria		Scroll down	Duplicate	Debug
Exit*	Display List	Count hits		Insert*
		Fetch next set		Remove*
				Lock*
				Duplicate
				Clear
About the default form menu toolbar

Default Menu Toolbar  If you attach the default form menu to a form, Form Builder attaches the default menu toolbar to the form automatically.  The menu toolbar consists of iconified buttons on a toolbar (placed at the top of your form, beneath the pull-down form menu) that are "shortcuts" to many default form menu items.  (Items from the default form menu that appear on the default menu toolbar are marked with an asterisk (*) in the table above.


Attaching the default form menu

To attach the default form menu to a form module:

1	In the Object Navigator, double-click the form module.

2	In the Property Palette, under the Functional node, set the Menu Module property to DEFAULT.

Note:  To run a form without a form menu, leave the Menu Module property field empty.


About custom form menu modules

  Related Topics

If you want to create a custom form menu module for your application (instead of using the default form menu), you have two options:

•	modify the menudef.mmb menu module

•	create a new form menu module from scratch

If you create any type of custom form menu for your form, you also can derive a menu toolbar from that form menu.  A menu bar displays selected menu items (from the current form menu) as icons on a horizontal or vertical ribbon.


About the menudef.mmb menu module

  Related Topics

Form Builder ships with a ready-made menu module (menudef.mmb) that has the exact same menu items as the default form menu.  Since the menudef.mmb menu module is a file copy of the default form menu, you can modify it as much as you like.  You need not worry about permanently changing the default form menu itself;  since it is an internal component, and not a file, it will alway be available to you in its original state.

If you modify the menudef.mmb menu module, note that its item commands are implemented with DO_KEY built-ins (which execute key triggers, thereby allowing end users to execute commands from either the menu or the keyboard).  To maintain consistent functionality, be sure to use DO_KEY builtins when you add menu item commands to the menudef.mmb module.


Modifying the menudef.mmb menu module

  Related Topics

To modify the menudef.mmb menu module:

1	In the Object Navigator, click the Menus node.

2	Click the Open button in the toolbar.

3	In the dialog, select menudef.mmb, then click OK.

Hint:  The menudef.mmb menu module is located in the /demos/dfltmenu directory, as specified in your ORACLE.INI file, or the WIN32 registry.

4	Use the Object Navigator or the Menu Editor to add new menu objects to (or modify the existing menu objects of) the menudef.mmb file.

5	Save, compile, and attach the modified menu module to your form module.

Remember to rename the menu module after you modify it, so you can distinguish between the original and the modified versions.


About building a form menu module from scratch

  Related Topics

If the default menu doesn't suit your needs, and you don't want to start with the menudef.mmb menu module and modify it, then you can create your own menu module from the ground up.  You can use the Object Navigator, Menu Editor, and Property Palette to create all menu objects necessary to create a form menu.

Building a form menu from scratch involves the following steps:

•	In the Object Navigator, create a new menu module.

•	Use the Object Navigator or Menu Editor to create menu objects (a main menu, individual menus and submenus, and menu items)

•	Assign commands to menu items.

•	Save and compile the menu module.

•	Attach the menu module to a form module.


Saving and compiling a custom form menu module

To save and compile a custom form menu module:

1	In the Object Navigator, select the menu module.

2	Choose File [image] Save or File [image] Save As to save the menu module.

Note:  You can save .MMB menu modules in the file system or in the database.

Warning:  If saving a modified version of the menudef.mmb menu module, you may wish to save it under a different filename.  This way you can create additional form menu modules (based on the original menudef.mmb module) at a later date.

3	Choose File [image] Administration [image] Compile File to compile the menu module.

Form Builder creates a runtime menu file with an .MMX filename extension.  (Menu executables are stored in the file system, not in the database.)


Attaching a custom form menu module

  Related Topics

To attach a custom form menu module to a form module:

1	In the Object Navigator, double-click the form module's object icon.

2	In the Property Palette, under the Functional node, set the Menu Module property to the filename of the runtime menu file (the .MMX filename extension is optional).

Note:  You must have previously saved and compiled the menu module in order to attach it your form module.

3	Set the Menu Source property to Yes (the default).

4	Choose File [image] Administration [image] Compile File to compile the form module.

Once you attach a menu module to a form module, Form Builder automatically loads the .MMX menu file when the form is run.


About deploying custom form menu modules

Custom form menu modules are separate from form modules.  Accordingly, if you deploy a form module with either a modified version of menudef.mmb or a form menu built from scratch, you must provide two executable files:

•	.FMX  (form module executable)

•	.MMX  (form menu module executable)

Depending on your application, you may need to deliver several form and menu module executables.  Multiple forms can share the same menu, or each form can invoke a different menu.

Note:  At runtime, an application can have only one form menu module active at a time.


About menu toolbars

  Related Topics

When you create a custom form menu, you can specify that some of its items appear on a menu toolbar  (a toolbar of iconified buttons that represent individual items from your form menu), also called a Smartbar.

If you use a custom form menu, you must explicitly assign individual menu items to a menu toolbar;  you also must provide icons to represent the associated buttons on the menu toolbar;  if you use the default form menu, Form Builder attaches a default menu toolbar to your form automatically.

You can assign menu items to a horizontal or vertical menu toolbar.  Form Builder locates a horizontal menu toolbar at the very top of a form (just beneath the pull-down form menu), while a vertical menu toolbar appears at the far left of a form (to the left of any existing toolbar canvas).


Creating a menu toolbar

  Related Topics

To create a menu toolbar:

1	In the Object Navigator, select the menu item you wish to place on a menu toolbar.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Functional node, set the item's Visible in Horizontal Menu Toolbar or Visible in Vertical Menu Toolbar property (or both) to Yes.

Note:  You can place a menu item on both horizontal and vertical menu toolbars.

4	In the Icon Filename property field, enter the fully-qualified directory path and filename (without filename suffix) for the icon that will represent the menu item button in the toolbar.


About popup menus

  Related Topics

Popup menus are context-sensitive menus—attached to a form's items and canvases—that allow end users to quickly access common functions and commands.  Popup menus are top-level objects in the Object Navigator (similar to alerts, blocks, canvases, etc.) and belong to a form module (as opposed to form menus, which belong to a separate menu module).

Items on a popup menu should be contextual to the menu's associated object(s).  For example, you would not include text-editing items on the popup menu for a 2-digit numeric item.  (You might include such items on the popup menu for a multi-line text item, however.)

Attaching a Popup Menu  The relationship between a popup menu and items/canvases (to which it is attached) is similar to the relationship between forms and form menus:

•	you can attach a single popup menu to one or more canvases or items

•	each canvas or item can support one and only one popup menu

Runtime Behavior  End users display a popup menu by placing focus on an item or canvas, and invoking the menu according to the standard for their runtime platform.  (Microsoft Windows and Motif end users click the right mouse button, for example, while Macintosh requires a keystroke sequence.)  The menu's top-left corner appears at the focal point, so users can locate and select the correct menu item easily and quickly.


Creating a popup menu

  Related Topics

To create a popup menu:

1	In the Object Navigator, click the Popup Menus node, and click  the Create button  in the toolbar.

Form Builder creates a popup menu and gives it a default name, such as MENU1.

2	In the Object Navigator or Menu Editor, create a main popup menu, submenus (if any), and menu items.

3	Assign commands to the menu items.

4	Attach the popup menu to items and canvases.


Attaching a popup menu to an item or canvas

  Related Topics

To attach a popup menu to an item or canvas:

1	In the Object Navigator, under the Blocks or Canvases node, click the object icon of an item or canvas (or both).

Note:  You can attach a popup menu to any type of canvas, and to any type of item except check, radio, iconic, and OLE.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Functional node, select a popup menu from the Popup Menu property poplist.

Hint:  To simultaneously attach the same popup menu to multiple items and canvases, select the items and canvases before you display the Property Palette.


About menu objects

  Related Topics

Whether you are creating custom form menus or popup menus, you must be familiar with creating and manipulating menu objects—the building blocks of Form Builder menus.

There are three types of menu objects:

•	modules

•	menus

•	items

Each menu module contains one or more menus (including a main menu, individual menus, and submenus).  Each menu contains one or more menu items (including associated commands).

Like form objects, menu objects:

•	Have parentage.  For example, menu modules own menus, while menus own menu items.

•	Have properties you can manipulate to define runtime functionality.  To view menu or item properties, select a menu or item in the Object Navigator or Menu Editor, and display the Property Palette.

•	Can be independently moved, copied, or deleted.  Note that if you move, copy, or delete a menu, you also move, copy, or delete any associated submenu(s) and menu item(s).


About object names and labels

  Related Topics

When working with menu objects, you should be familiar with three related properties:

•	Name (menu property).  An internal name, useful for referring to the menu in code.

•	Name (item property).  An internal name, useful for referring to the menu item in code.

•	Label (item property).  An external label for the menu item, used only in the GUI.

Default Names and Labels

When you create a new menu (including the main menu, individual menus, and submenus) or a new menu item, Form Builder creates defaults for:

•	Menu name (such as MENU17).  Form Builder displays menu names in the Object Navigator and Property Palette (Name property).

•	Item name (such as ITEM8).  Form Builder displays menu item names in the Object Navigator and Property Palette (Name property).

•	Item label (such as <New_Item>).  Form Builder displays menu item labels in the Menu Editor and Property Palette (Label property).

You can use the default names and labels in your PL/SQL code and GUI, or you can change them to suit your needs.

Use the Object Navigator or Property Palette to modify menu and item names.  Use the Property Palette or Menu Editor to modify item labels.


Changing menu object names

  Related Topics

To change the name of a menu or item:

1	In the Object Navigator, click a menu's or item's object icon to select it.

2	Do one of the following:

•	Click the name to enter edit mode.  The name displays in reverse, and the cursor changes to an I-beam.  Type in the new name and press [Enter].

•	Double-click the item's object icon to display the Property Palette.  Under the General node, change the Name property of the menu object.

Form Builder reflects the name change both in the Object Navigator and in the Property Palette.

Note:  If Form Builder displays the error

  FRM_15500: Valid and unique object name must be entered.

you may have violated the PL/SQL naming conventions, perhaps by including an embedded space or invalid punctuation.


Changing menu object labels

  Related Topics

To change the label of a menu item:

1	In the Object Navigator, click the menu item.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Functional node, set the Label property.

Form Builder reflects the label change in both the Property Palette and Menu Editor.

Note:  Labels can contain more than one word and any punctuation character.  For instance, "Show Keys" and "Options..." both are valid item labels.


Referencing menu objects in code

 Examples

To refer to a menu object in PL/SQL code, use menu_name.item_name syntax.  Use this syntax to:

•	attach commands to menu items

•	initialize check or radio menu items

•	change menu start-up code

•	enable/disable menu items dynamically

Main Menu Items  Items on the main menu belong to the main menu only—and not to the individual menus they own.  In the default form menu, for example, QUERY is an item on MAIN_MENU, but is not an item on QUERY_MENU (the menu it owns).  The items on QUERY_MENU are Enter, Execute, Last Criteria, Cancel, Count Hits, and Fetch Next Set.

To refer to the main menu QUERY item in code, use the syntax:

   main_menu.query  (and not query_menu.query)


Referencing menu objects in code examples

/* Dynamically disable the ENTER item on the QUERY menu */

SET_MENU_ITEM_PROPERTY(query.enter, enabled, property_false);


Opening an existing menu module

To open an existing menu module:

1	Choose File [image] Open.

Form Builder displays the Open dialog.

2	Locate and select the existing menu module you wish to open.

Note:  You also can specify the name of the menu module at the command line when you start the Form Builder:

ifbld60 std_menu.mmb

Form Builder opens the menu module and displays it in the Object Navigator.


Creating a new menu module

  Related Topics

To create a new menu module from scratch:

1	Select the Menus node in the Object Navigator and click  the Create button  in the toolbar.

Form Builder creates a new menu module in the Object Navigator with a default name, such as MODULE1.

2	Replace the default name with a more meaningful name.


About menus and menu items

  Related Topics

Once you have a menu module active in the Object Navigator, you can create menus and menu items, including:

•	a main menu (the top-level menu, displayed by default as a horizontal strip)

•	individual menus and submenus (lower-level menus, displayed by default as vertical lists of menu items)

•	menu items

You can use both the Object Navigator and the Menu Editor to create menus and items.  If you prefer to work in:

•	Graphical format, use the Menu Editor.  (You may prefer using the Menu Editor, as it allows you to see connections between menus and items visually.)

•	Hierarchical outline format, use the Object Navigator.


Creating menus and menu items

  Related Topics

To create menus and menu items in the Object Navigator:

Within the current menu module, select either the Menus or Items node, and click  the Create button  in the toolbar.

Form Builder creates the menu or item and gives it a default name, such as MENU5 or ITEM20.


About menu item commands

  Related Topics

For every form menu item and popup menu item you create, you must set the Menu Item Type and a Command Type properties.  These menu-item-level properties determine the appearance and functionality of each menu item.

The following menu item types are available:

•	Plain

•	Check

•	Radio

•	Separator

•	Magic

The most common menu item type is Plain;  the other menu types are used to customize the appearance and functionality of a menu.

After you select a valid menu item type, you must specify a valid command type and (sometimes) the command text for the item.

Valid command types are:

•	Null  (required if the menu item is a separator)

•	Menu  (required if the menu item calls a submenu)

•	PL/SQL  (the default;  required if menu item executes PL/SQL commands)

•	Plus

•	Form

•	Macro

Note:  In this release of Form Builder, Plus, Form, and Macro command types are available for backward-compatibility only.  Plus, Form, and Macro command types will not be supported in the next major release of Form Builder.


Assigning commands to menu items

 Examples	     Related Topics

To assign a command to a menu item:

1	In the Object Navigator or Menu Editor, select the menu item.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Functional node, set the Menu Item Type and Command Type properties.

4	Double-click the Command Text property field.

5	In the PL/SQL Editor, type the code to define the menu item's command

6	Click Compile, then click Close.


Assigning commands to menu items examples

/* Create a menu item that displays a message to the
** end user:
**
** Create a menu item (on any menu) and give it a name of
** DISP_MSG and a label "Display Message". In the Property
** Palette, verify that the item's Menu Item Type property
** is set to Plain, and its Command Type property is set to
** PL/SQL. Double-click the Command Text property field to
** display the PL/SQL Editor. Enter the following:*/

   MESSAGE('To infinity and beyond!');


About special menu items

 Restrictions	    Related Topics

Use special menu items to customize the appearance and functionality of a menu.  In addition to items of type Plain (the default), Form Builder supports four additional menu item types:

•	Check

•	Radio

•	Separator

•	Magic


About special menu items restrictions

•	The availability and appearance of each special menu item is platform-specific.  For example, if a particular platform displays check boxes as diamonds, it is not possible to make them display as squares.

•	Do not use check or radio items on the main menu (menu bar) or popup menus.

•	Do not use separator items in the main menu.

•	Do not set the Keyboard Accelerator, Icon, or Hint properties for a magic menu item.

•	You can use each magic menu item only once in a menu module.  For example, you cannot define the magic item Copy on two different menus in the same module.


About check and radio menu items

  Related Topics

A check item is displayed as a visual indicator, such as a box, that appears checked (representing On) or unchecked (representing Off) to indicate its current state.  Selecting a check item at runtime toggles it to its opposite state.

A radio item is displayed as a visual indicator, such as a circle, that appears filled (representing On) or unfilled (representing Off) to indicate its current state.  Selecting an unselected radio item in the group deselects the currently-selected item.  A radio item must belong to a menu radio group of two or more related items, of which one and only one always must be On.  Items of the same group must be displayed contiguously on the same menu.


About check and radio item commands

Commands are optional for check and radio menu items.

If you wish to assign a command to a check or radio item, follow the same procedure you use to assign commands to a menu item of type Plain.  Form Builder executes commands when the item's state or value is changed:

•	Check item:  when an end user toggles the item to its opposite state (On to Off, or Off to On)

•	Radio item:  when an end user changes the value of the radio group (i.e., selects a different radio button)

To create a check or radio item that does not execute a command, you must set the item's Command Type property to Null.  Use a Null Command Type (and empty Command Text) for a check or radio item that allows end users to define an operating mode or set a context for operations in the application.  For example, a group of radio items might allow end users to specify the level of detail they want to see when querying data in a block.


About check and radio item states

 Examples

When a menu is loaded at form startup, the default states of check and radio menu items are as follows:

Item Type	Default State
Check	Unselected (Off)
Radio (first in group)	Selected (On)
Radio (all others in group)	Unselected (Off)

You can use the built-ins GET_MENU_ITEM_PROPERTY and SET_MENU_ITEM_PROPERTY to derive and modify the current state of check and radio items.

When using either of these built-ins, the first parameter to specify is the name of the menu item.  Use the following syntax:

   menu_name.item_name


About check and radio item states examples

 /* Set the state of a Show Details check menu item to On: */

   SET_MENU_ITEM_PROPERTY('query.show_dtls',
                          checked,
                          property_on);


About separator menu items

A separator menu item is displayed as a horizontal line (or other platform-specific visual element), and is useful for visually grouping related items on the same menu.  For example, you could use a separator to isolate the radio items of one radio group from other menu items.  You must set a separator item's Command Type property to Null.  End users cannot select a separator menu item.


About magic menu items

  Related Topics

Magic items provide a way to quickly create menu items for standard functions available in most GUI applications.  Form Builder provides the following magic item types:

•	About

•	Copy

•	Clear

•	Cut

•	Paste

•	Help

•	Quit

•	Undo

•	Window

Note: The About, Help, and Window magic menu items are not supported for popup menus.


About magic item default appearance and functionality

The appearance (style and position) of a magic item is defaulted to the standard of the runtime platform GUI.  Where applicable, default accelerator keys are assigned to magic items.

Some magic items include default functionality.  For example, the Cut item—typically placed on an Edit menu—is automatically enabled or disabled depending on whether text or image elements have been selected.  Invoking the Cut command deletes the selected element and places it on the clipboard.  If you create a Cut magic item, Form Builder automatically provides an accelerator key and command statement for you.

The following table describes the valid command types for each type of magic menu item and indicates whether the item provides default functionality, or whether you must define your own command.

Magic Item	Command Type	Default	Functionality?
About, Undo	Any but Menu	No	You must assign a command to perform the desired function.
Clear, Copy, Cut, Paste	Null	Yes	These items perform the default operations indicated by their names.
Help	Menu	No	You must define the submenu to be called by the Help item, and you must assign commands to the items on that submenu.
Quit	Null	Yes	The Quit item prompts the end user to save changes (if any) and exits the form.
Window	Null or Menu	Yes	The Window item invokes a default submenu that lists all open windows.  End users can activate a window by selecting it from the submenu.If you define your own submenu to be invoked by the Window item, Form Builder combines its items with the list of open windows, and creates a single submenu.  Item order on the combined submenu is undefined.

Note:  If you change the Menu Item Type property of an existing magic item to Plain, its Magic Item Type property is retained, but no longer applies.  Though not required, you should reset the Magic Item Type property to None for consistency purposes.


Creating special menu items

  Related Topics

To create a special menu item:

1	Add a new item to a menu.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Functional node, change the item's Menu Item Type property from Plain (the default) to either Check, Radio, Separator, or Magic.

If creating:

•	a radio item, you must assign it to a radio group.  Select the item in the Object Navigator, and enter the correct name in the Menu Item Radio Group property field.  (Radio-group names are internal and are not displayed at runtime.)

•	a magic item, also select the desired item type from the Magic Item property poplist.

4	Set the item's Command Type property.

5	If necessary, enter the Command Text for the item.


Displaying icons in menu items

To display an icon in a menu item:

1	In the Object Navigator or Menu Editor, select the desired menu item.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Functional node, type the icon resource filename in the Icon Filename property field.

If Form Builder locates the icon file, it displays the icon in place of the item's label in the Menu Editor.  Otherwise the icon reference is ignored and Form Builder displays the item's label instead.

Note:  You can display icons as menu items in pull-down menus, but only if your runtime platform supports this feature.  For more information, refer to the Form Builder documentation specific to your operating system.


Defining menu access keys

Menu access keys provide end users with keyboard shortcuts for selecting menu items (without using the mouse).  Applications with keyboard shortcuts offer both the usability of a menu-driven interface and the efficiency of keyboard commands.

A menu access key is indicated by a special character in a menu item's label.  For example, the letter S might be the menu access key for the Save menu item, and therefore appears underlined at runtime.  To invoke the Save command, an end user either could use the mouse, or could press a keystroke combination such as Alt-S.  (Different GUIs use different command keys to activate menu mnemonics.)  In character mode, end users press [Menu] to access the menu, then press menu access keys to select items.

Default Menu Access Key  By default, the access key for a menu item is the first upper-case letter in the item's label.  If there are no upper- case letters, the first character is the menu access key.  For example, the letter "a" is the default menu access key for the following menu items:

   abort      sAve

User-defined Menu Access Keys  You can override the default menu access key—and explicitly create your own—by placing an ampersand (&) to the left of the desired character in the menu item's label:

   &Abort      Sav&e

The ampersand will not appear at runtime, and the character you select as the menu access key can be either upper- or lower-case:

   Abort      Save

Note:  To include a literal "&" in a menu item label, enter two consecutive ampersands (&&).


Assigning accelerator keys to menu items

  Related Topics

A keyboard accelerator is a function key or key sequence that end users can press to execute the menu item command.  Form Builder provides five logical accelerator keys--[Accelerator1] through [Accelerator5]--that you can assign to menu items in each form.

To assign an accelerator key to a menu item:

1	In the Object Navigator or Menu Editor, select the menu item.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Functional node, type the name of the logical accelerator key you want to assign to the item in the Keyboard Accelerator property field.  For example, enter Accelerator1.

4	In Oracle Terminal, associate the logical accelerator key to a physical device key or key sequence, such as Ctrl-P.


About pull-down form menus

  Related Topics

A standard pull-down menu consists of three levels:

Level	Display	Function
Main	Horizontal	Items display individual menus. Items on a main menu are titles—they do not execute commands.
Individual	Vertical	Items either execute commands or invoke submenus.
Submenu	Vertical, to right of menu item	Items provide additional choices related to an item on an individual menu.

Note:  While you can create multiple levels of nested submenus, this practice is not recommended since it hinders quick access to submenu items. To maximize usability, you may want to limit submenus to one level.  In addition, usability experts recommend limiting the number of items on a menu to nine.


Running a form menu in pull-down style

To run a form menu in pull-down style:

1	In the Object Navigator, select the form module.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Functional node, set the Menu Style property to Pull-down.


About tear-off menus

A tear-off menu is a menu that end users can drag away from the menu bar and reposition elsewhere on the screen.  You can enable tear-off functionality for any menu, provided your window-manager supports this feature.

To create a tear-off menu:

1	In the Object Navigator or Menu Editor, select the desired menu.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Functional node, set the Tear-Off Menu property to Yes.


Getting and setting menu properties programmatically

Form Builder provides built-in subprograms for finding menu items, and getting and setting menu properties programmatically:

•	FIND_MENU_ITEM

•	GET_MENU_ITEM_PROPERTY

•	SET_MENU_ITEM_PROPERTY


Displaying and hiding menus programmatically

  Related Topics

In a multiple-form application, several form modules can share the same menu, or each can invoke a different menu when it becomes the active form in the session.  When Form A executes the CALL_FORM built-in procedure to invoke Form B, arguments to the CALL_FORM procedure specify whether Form B should inherit Form A's menu or display its own menu.

At runtime, however, an application can have only one form menu module active at a time.  To handle the juggling of form menu modules, Form Builder provides the following built-in routines that allow you to show, hide, and replace the active menu in a Form Builder application.

HIDE_MENU	Hides the current menu.
REDISPLAY_MENU	Redisplays the current menu.
REPLACE_MENU	Replaces the current menu with another menu or with no menu.
SHOW_MENU	Displays the current menu.


About PL/SQL code in menu modules

  Related Topics

To programmatically control and manipulate menus at runtime, you can use PL/SQL in:

•	menu item commands

•	user-named subprograms

•	startup code


About using PL/SQL code in menu item commands

  Related Topics

Structurally, PL/SQL menu item commands are similar to form triggers.  In addition to standard application functions such as navigation, validation, and database interaction, you can use PL/SQL menu item commands to:

•	invoke a form (in the same session) using the OPEN_FORM, CALL_FORM or NEW_FORM built-in procedures.

•	execute operating system commands using the HOST built-in routine.  Parameters to the HOST routine specify the operating system command to execute, whether or not Form Builder clears the current form from the screen, and whether or not Form Builder waits to be prompted by the end user before returning to the current form or does so automatically after the command is executed.

•	invoke other Oracle tools (such as Form Builder Forms Runtime, Report Builder (included with Reports Developer), or Graphics Builder) using the built-in procedure RUN_PRODUCT, which provides integration between Form Builder and other Oracle tools by allowing you to pass parameters and data values to the called tool.

•	call the DO_KEY built-in, which executes the key trigger that corresponds to the specified built-in routine.  If no such trigger exists, the specified routine executes.  This behavior is analogous to an end user pressing the corresponding function key.

•	use the EXECUTE_TRIGGER built-in, which allows you to refer directly to the values of form items.  Since a direct reference from the menu item itself is not allowed, write a user-named routine or anonymous block that uses a direct reference, place it in a user-named trigger, then use EXECUTE_TRIGGER to call that trigger.


Referencing form objects in PL/SQL menu item commands

Form menus are reusable modules that you compile separately from forms.  Accordingly, to reference form objects in PL/SQL menu item commands, you must code differently than if you were referencing the same object in a trigger or user-named routine within a form.  The following restrictions apply:

•	You cannot directly reference the value of a Form Builder object; instead, use the NAME_IN built-in function to determine the object's current value.

  IF :emp.title = 'MANAGER'            -- incorrect

  IF NAME_IN('emp.title') = 'MANAGER'  -- correct

Note:  The value returned by the NAME_IN function is a character string.  However, you also can use NAME_IN to return numbers and dates as character strings, and then convert those strings to the appropriate data types.

•	You cannot use direct assignment to set the value of a Form Builder object;  instead, use the COPY built-in procedure.

  :product.name := 'PUMP';        -- incorrect

  COPY('PUMP', 'product.name');   -- correct


Writing user-named subprograms

  Related Topics

You can use the PL/SQL Editor to create user-named subprograms (routines) in a menu module, just as you would in a form module.  A user-named subprogram can be called from any menu item (of command type PL/SQL), provided the item and subprogram belong to the same menu module.


About menu startup code

  Related Topics

Form Builder executes menu startup code when a menu is loaded into memory at form startup, or as the result of a call to the CALL_FORM, NEW_FORM, or REPLACE_MENU built-in procedures.  Startup code is optional, and can be used to perform the following tasks:

•	Initialize substitution parameters and global variables.

•	Programmatically set the initial display state of menu items:  for example, to enable or disable a menu item.

•	Programmatically set the initial selection state of check and radio menu items.


Writing menu startup code

To write startup code for a menu:

1	In the Object Navigator, select the desired menu module.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Functional node, double-click the Startup Code property field.

4	In the PL/SQL Editor, enter the/SQL code you want Form Builder to execute on menu startup.

5	Click Compile, then click Close.

Note:  Startup code can include anonymous blocks and calls to built-in subprograms.   However, like restriction on writing PL/SQL code for menu item commands, you cannot directly reference the values of form objects in startup code.


About substitution parameters

  Related Topics

Substitution parameters are two-letter variables (such as RN or PQ) that you can reference in menu item command statements.  Form Builder provides six built-in substitution parameters;  you also can define your own substitution parameters.

You can programmatically set the value of a substitution parameter, or you can require end users to interactively provide a value at runtime. When an end user selects an item with a command that includes a substitution parameter, Form Builder displays the Enter Parameter Values dialog and prompts the end user to enter a value.  Form Builder then executes the menu command using the value provided by the end user.


Built-in substitution parameters

The value of a built-in substitution parameter is predefined and always initialized by Form Builder at runtime.  For example, the value of the built-in parameter UN is the current end user's username.  Accordingly, Form Builder never will prompt the end user for the value of UN.

Parameter	Description
UN	Current username
PW	Current password
AD	Directory where the current menu's runtime file is stored (as specified by the menu module Menu Filename and Menu Directory properties)
SO	Current menu item (Selected Option)
TT	Terminal type that was used to log in
LN	Current language preference, as indicated by the NLS_LANG environment variable


Creating substitution parameters

To define a user-named substitution parameter:

1	In the Object Navigator, under Menu Modules, select Parameters, and click the Create icon in the toolbar.

Form Builder creates a new parameter.

2	Edit the name of the new parameter.

Parameter names must be two alphabetic characters.

3	Choose Tools [image] Property Palette.

4	In the Property Palette, set the properties for the parameter.


Substitution parameter properties

Set the following properties to define substitution parameters:

Property	Description
Case Restriction	Converts the end user-supplied value to the case specified (None, Upper, or Lower).
Default Value	The default value for the parameter.  Displayed in the parameter value field when the prompt dialog appears.
Fixed Length	Specifies that the value entered by the end user must have the maximum number of characters allowed by the Size property.
Hint	Instructive or descriptive text that displays in the message line when the prompt dialog appears.
Name	The parameter name (must be two characters).
Parameter Menus	(Applies only to full-screen menus.) The names of the menus with which you want the parameter to be associated.
Prompt	Text string that defines the parameter value field in the Enter Parameter Values dialog (for example, Report Name or Customer ID).
Required	Determines whether the end user is required to supply a value for the parameter.  Setting Required to No allows end users to leave the parameter value Null.
Secure	Determines whether the end user-supplied value is echoed to the screen as it is entered.  Set Secure to Yes to hide a password value as it is entered.
Size	Specifies the maximum number of characters for the parameter value.


Referencing substitution parameters in code

 Examples

Depending on where you refer to a substitution parameter, you must attach the correct prefix to the left of the parameter.  To use a substitution parameter in:

•	menu item command statements, use an ampersand (&RN).

•	PL/SQL routines, use a colon (:SS).

You can reference the values of menu substitution parameters in triggers and user-named routines defined in the current form, provided the parameters are defined in the current menu module.

Form Builder does not automatically display the Enter Parameter Values dialog when you reference a substitution parameter in a PL/SQL-type menu item command.  Instead, you must explicitly invoke the dialog by calling the QUERY_PARAMETER built-in.

Note:  When you call the QUERY_PARAMETER built-in, you must enclose the parameter reference in single quotes.  Also, you can obtain any number of parameter values in a single call to QUERY_PARAMETER.

You can use the following built-in subprograms to display and prompt for substitution parameter values programmatically:

•	APPLICATION_PARAMETER

•	QUERY_PARAMETER

•	MENU_PARAMETER (full-screen menus only)


Referencing substitution parameters in code examples

 /* Example 1: The following menu item command invokes
** SQL*Plus and runs a command file. It includes three
** substitution parameters: */

   SQLPLUS &UN/&PW @&CF

/* The UN and PW parameters are Form Builder built-ins.
** The CF parameter represents the  SQL*Plus command file
** to be run. When the end user selects this menu item, the
** Enter Parameter Values dialog appears, allowing the end
** user to enter the name of the command file. */

/* Example 2: The following procedure first invokes the
** Enter Parameter Values dialog to allow the end user to
** provide the name of a report to be run by Oracle Report
** Builder. It then references the substitution parameter
** as an argument to the RUN_PRODUCT procedure: */

  QUERY_PARAMETER('&RN');
  RUN_PRODUCT(REPORTS,:RN,SYNCHRONOUS,RUNTIME,
              FILESYSTEM,pl_id,NULL);


About menu security

  Related Topics

Use role-based menu security to control access to menus and items in your menu modules.  Customizing menus this way lets you provide a subset of functionality for each category of end user that uses your application, thereby avoiding the need to create multiple applications that perform duplicate functions.  For example, while two departments in a company might both use the same application, employees in Department A might have access to parts of the application that are unavailable to employees of Department B.

In particular, you can grant end users access to:

•	all menu items in a module

•	specified menu items only

Security features also make applications easier to use.  Form Builder allows you to simplify the application interface by choosing to hide or disable  menu items that are not available to the current end user.


About implementing menu security

To implement menu security, follow these basic steps:

•	Create database roles and assign user names to them—either through Form Builder, or directly in the database.

•	Assign roles to the menu module, using the Module Roles property.  (Before you can grant a role access to individual menu items, you must assign the role to the menu module.)

•	Grant roles access to individual menu items (using the Menu Item Roles property).

•	Set the menu module property Use Security to Yes.

•	Compile the menu module.

•	Compile the form module.

Note:  The FRM50_ENABLED_ROLES view must exist in the database for menu security to function properly.  FRM50_ENABLED_ROLES is automatically created as part of the Form Builder 5.0 table scripts that run during installation if you choose the "Create database tables" option.  If you did not choose that option, you or your DBA must logon as SYSTEM and run the SQL script FRM50SEC.SQL (located in the Form Builder SQL directory).


About the Use Security menu module property

To set the Use Security property:

1	In the Menu Editor or Object Navigator, select the menu module.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Menu Security node, set the Use Security property:

Yes	Form Builder will enforce security.
No	Form Builder will ignore security.
4	Choose File [image] Administration [image] Compile File to compile the menu module.

The Use Security menu module property specifies whether Form Builder should enforce menu security at runtime.  Form Builder does not enforce menu security at runtime unless the Use Security property was set to Yes when you compiled the menu module (to create the .MMX file).  If you compile the menu module with the Use Security property set to No, all end users will have access to all menu items.

Tip:  To circumvent role-based menu security while testing an application, set the Use Security property to No and compile the menu module.  When done testing, reset the Use Security property to Yes and recompile the menu module.


About database roles

  Related Topics

Form Builder enforces menu security on the basis of database roles--lists of users that, because of their job responsibilities, have similar requirements for access to information.  For example, you might create roles named Managers and Clerks.

You create roles once, and then use them to provide:

•	Database-level access privileges, including table privileges (such as inserting data in tables)

•	System privileges (such as connecting to the database)

•	Application security (by limiting access to certain menu items)

Once you create a role, you can assign that role to individual menu items.  When you limit menu item access to to certain roles, only end users who have been granted that role can select the menu item at runtime.

Menu security based on database roles is independent of a particular menu module.  In other words, once a role has been defined, developers subsequently can grant that role access to any menu module or menu item.

Note:  To enforce menu security features, the application must be connected to the database at runtime, since Form Builder interrogates the database at startup to determine the roles to which the current end user belongs.


About creating and granting database roles

  Related Topics

When planning application security, define roles so that all object and system privileges necessary to perform a certain task are granted to a single role.  This will simplify application maintenance, since adding a new end user will require granting one role, instead of granting all the individual privileges.

Before you can grant security to menu items (on an item-by-item basis), you first must choose the subset of roles you want to grant to the menu module.  For example, the DBA may grant 50 roles access to a particular database.  For a specific application using that database, however, you may want to grant access to only 10 of those roles.

Granting a role access to a menu module does not grant that role access to any menu items.  Rather, once you grant a role access to the menu module, it will appear in the Menu Item Roles property list for all menu items in the module.

Once you grant a role access to a menu module, you can grant the role access to individual menu items to the module.

You can create and grant roles two ways:

•	Directly in the database (issue GRANT statements)

•	In the Form Builder Role List dialog (Form Builder issues the database commands for you)

Whether you implement security directly in the server or through Form Builder, the underlying SQL commands are the same.  Use:

•	CREATE ROLE to create a role.

•	GRANT to bestow privileges upon the role, and then to give a particular user an entire "collection" of privileges.

•	ALTER USER...DEFAULT ROLE to control which roles will default to enabled on connection for a specific user.  The DBA defines default roles for end users, so the related privileges will be enabled automatically when they log on.

Form Builder menu security is based on the roles granted to an end user, regardless of whether the role is currently enabled (via SET ROLE).  However, since table privileges depend on the role being enabled, you must include the necessary DBMS_SESSION.SET ROLE() command in your application (unless you enable roles by default).

Tip:  If an end user tries querying a block based on a table and gets the error message ORACLE Error--Unable to Perform..., most likely the end user does not have access to that database table because the appropriate role is not set.  You need to either:

•	Enable the appropriate roles as default roles for that end user.

or

•	Explicitly set the roles in your application, using the DBMS_SESSION.SET ROLE() command.


Creating database roles

To create a database role:

1	Choose File [image] Administration [image] Database Roles to invoke the Role List dialog.

If the Database Roles menu item is disabled, you do not have role administration privileges.  Ask any developer who has DBA privileges to grant you CREATE ROLE, DROP ROLE, and GRANT ROLE privileges.

2	Click New to invoke the Role dialog.

3	Enter a name in the Role Name field.

4	Add users to the role by entering their user names in the User Name column.

5	Set the role's Debug, OS Command, and Background Menu privileges:

Debug	Set to True to let end users run in debug mode by pressing [Debug Mode].
OSCommand	Set to True to let end users exit to the operating system and enter commands by pressing [Enter 1 OS Command] or [Enter > 1 OS Command].
Background Menu	Set to True to let end users display the background menu window by pressing[Show BGM].

When an end user is a member of a role with the above privileges, Form Builder displays the corresponding lamp (<DBG>, <OSC> or <BGM>) on the status line at runtime.

6.	Click OK to accept the role definition and return to the Role List.

7.	To define another role, repeat steps 2 - 6.  When finished, click Save to save the role definitions to the database.


Modifying existing database roles

To modify an existing database role (e.g., to add new users):

1	Choose File [image] Administration [image] Database Roles to invoke the Role List dialog.

If the Database Roles menu item is disabled, you do not have role administration privileges.  Ask any developer who has DBA privileges to grant you CREATE ROLE, DROP ROLE, and GRANT ROLE privileges.

2	Select the role you want to modify, then click Edit.

The Role dialog appears, allowing you to modify the role as desired.

3	To:

•	add a user to a role, navigate to the User Name column, and press [Create Element]  (usually mapped to Ctrl-Insert).

•	delete a user from a role, select the user's name, then press [Delete Element]  (usually mapped to Ctrl-Delete).

4	Click OK.

Form Builder returns to the Role List dialog.

5	Click Save.


Deleting existing database roles

To delete an existing database role:

1	Choose File [image] Administration [image] Database Roles to invoke the Role List dialog.

If the Database Roles menu item is disabled, you do not have role administration privileges.  Ask any developer who has DBA privileges to grant you CREATE ROLE, DROP ROLE, and GRANT ROLE privileges.

2	Select the role you want to delete.

3	Click Remove.

Form Builder displays a message asking you to confirm the deletion.

4	Click Delete.

5	Click Save.


Granting database roles access to menu modules

To grant roles access to a menu module:

1	In the Object Navigator, select the menu module.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Menu Security node, double-click the Module Roles property field to display the Menu Module Roles dialog.

4	Enter the names of the roles to wish you want to grant access to the menu module.

5	Click OK.


Granting database roles access to menu items

To grant database roles access to menu items:

1	In the Object Navigator, select the menu item.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the Menu Security node, double-click the Item Roles property field to display the Menu Item Roles dialog.

Form Builder displays the names of roles with access to the module in the Roles list.  Roles with access to the currently-selected menu item are highlighted; roles without access are displayed in normal style.

Note:  If the list is empty, no roles have been granted access to the menu module.  You must grant roles access to the module before you can assign access to menu items.

4	To grant a role access to the current menu item, use the mouse to select and deselect roles in the list (deselecting a role revokes an item's access):

•	Click to select or deselect (the mouse click is a toggle)

•	Shift-click to select more than one contiguous role

•	Control-click to deselect a previously-selected role, independent of any other roles in the list

5	Set the Display without Privilege property to specify how Form Builder should display the item to end users who don't have access to the item:

Yes	Item will be displayed, but disabled.  On most platforms, disabled items are displayed with reduced contrast (or grayed) to indicate that the item is unavailable.
No	Item will be hidden completely.

Tip:  To simultaneously grant a role access to several menu items, select multiple items by Shift-clicking or Control-clicking in the Object Navigator, and then set the Menu Item Roles property once for all selected items.


About manipulating database roles at runtime

  Related Topics

If you use database roles to manage database object privileges and Form Builder application menu security, you may want to check and set database roles at runtime.  For example, you can check the SESSION_ROLES data dictionary view to determine what roles or privileges are enabled for the current user.

Also, you can query these additional views to check database role information dynamically at runtime:

•	ROLE_ROLE_PRIVS

•	ROLE_SYS_PRIVS

•	ROLE_TAB_PRIVS

•	USER_ROLE_PRIVS

For maximum security, the role could require a password to SET.  In this way, a Form Builder application could SET the role at startup by providing a password encrypted within the form, thus automatically granting access to all of the database objects necessary to run that form.


Setting and checking database roles at runtime

 Examples

To set a database role:

   DBMS_SESSION.SET_ROLE('payroll');

To set a role with a password:

   DBMS_SESSION.SET_ROLE('payroll IDENTIFIED BY PASSWORD xyz001');

(For security reasons, the password could be provided as a variable.)

If the user did not have the role defined as a default role (which would automatically enable the related privileges at logon), then the only time the user would have access privileges to the database object would be while running the form, which is the preferred behavior.  Since menu security is based on roles which have been granted, not only the ones currently enabled (or SET), your application must programmatically enable the roles as necessary.

Note:  For information about database commands, refer to the Oracle7 or Oracle8 Server documentation.

To check and set database roles dynamically at runtime:

The DBMS_SESSION package includes a procedure (SET_ROLE) and a corresponding function (IS_ROLE_SET) to test  the result of the procedure.


Setting and checking database roles at runtime examples

 /* Use the DBMS_SESSION package (including the SET_ROLE
** procedure and corresponding function IS_ROLE_SET) to set
** and check roles from a Form Builder application.
** SET_THE_ROLE: Attempts to set the role passed as a
** parameter. If the role requires a password, then pass
** the string 'ROLENAME IDENTIFIED BY PASSWORD' rather than
** simply passing 'ROLENAME' as the argument.
** Returns:     TRUE    if successful at setting the role
**              FALSE   otherwise.*/

FUNCTION SET_THE_ROLE(fp_rname VARCHAR2)
RETURN BOOLEAN IS

   /* ORA-1979: Missing or invalid password... */

   wrong_password exception;
   pragma exception_init(wrong_password, -1979);

   /* ORA-1919: Role does not exist */

   role_does_not_exist exception;
   pragma exception_init(role_does_not_exist, -1919);

BEGIN

   /* Call the Stored Procedure to perform the SET ROLE  */

   DBMS_SESSION.SET_ROLE(fp_rname);
   RETURN(TRUE);

EXCEPTION

   /* Handle the two probable errors */

   WHEN role_does_not_exist
      OR wrong_password THEN
      RETURN(FALSE);

END;

/* Using this procedure, you could implement a simple
** PRE-FORM trigger: */

   IF NOT(DBMS_SESSION.IS_ROLE_SET('payroll') OR
     SET_THE_ROLE('payroll')) THEN
        MESSAGE('You are not authorized to run Payroll.');
        PAUSE;
        RAISE FORM_TRIGGER_FAILURE;
        END IF;
   END IF;


About mouse events, triggers, and system variables

  Related Topics

There are several mouse events that can occur at runtime.  For example, when an operator clicks the mouse on an item, the item clicked can signal whether it received a single or a double-click.

You can execute a command or initiate an action whenever one of the following mouse events occurs:

•	operator presses the mouse down

•	operator presses the mouse down and releases the mouse button

•	operator clicks the mouse

•	operator double-clicks the mouse

•	operator moves the mouse into a canvas or item

•	operator moves the mouse out of a canvas or item

•	operator moves the mouse


Creating a mouse event trigger

  Related Topics

Creating a mouse event trigger to respond to a mouse event allows you to initiate an action whenever the specified mouse event occurs.

Mouse  Trigger	Description
When-Mouse-Down	Initiates an action when the operator presses down the mouse button within an item or canvas.
When-Mouse-Up	Initiates an action when the operator presses down and releases the mouse button within an item or canvas.
When-Mouse-Click	Initiates an action when the operator clicks the mouse within an item or canvas.  Clicking the mouse consists of the mouse down and up events.
When-Mouse-DoubleClick	Initiates an action when the operator double-clicks the mouse within an item or canvas.  Double-clicking the mouse consists of the mouse click, mouse down, and mouse up events.
When-Mouse-Enter	Initiates an action when the operator moves the mouse into an item or canvas.
When-Mouse-Leave	Initiates an action when the operator moves the mouse out of an item or canvas.
When-Mouse-Move	Initiates an action when the operator moves the mouse within an item or canvas.


Using mouse event system variables

  Related Topics

When any of the mouse events occur, Form Builder initializes the appropriate mouse event system variable (see below) and executes the corresponding mouse trigger.

Note:  Mouse system variables are set immediately before a mouse trigger is fired.  To guarantee that your mouse system variables are updated, you should only use the mouse system variables within mouse triggers.

Mouse Event  System Variable	Value
SYSTEM.MOUSE_BUTTON_PRESSED	The number of the button, either 1, 2, or 3 (left, middle, or right) that was pressed.
SYSTEM.MOUSE_BUTTON_SHIFT_STATE	The shift modifier pressed during the mouse click.
SYSTEM.MOUSE_ITEM	The name of the item the mouse is currently in.
SYSTEM.MOUSE_CANVAS	The name of the canvas which the mouse is currently in.
SYSTEM.MOUSE_X_POS	The current mouse X-coordinate on the canvas according to the coordinate system except when used within a When-Mouse-Enter trigger.  When using a When-Mouse-Enter trigger, SYSTEM.MOUSE_X_POS represents the X-coordinate relative to the item entered, not the item position on the canvas.
SYSTEM.MOUSE_Y_POS	The current mouse Y-coordinate on the canvas according to the coordinate system except when used within a When-Mouse-Enter trigger.  When using a When-Mouse-Enter trigger, SYSTEM.MOUSE_Y_POS represents the Y-coordinate relative to the item entered, not the item position on the canvas.
SYSTEM.MOUSE_RECORD	The record number of the record the mouse is in.
SYSTEM.MOUSE_RECORD_OFFSET	The offset from the first visible record that the mouse is in.

Note:  Form Builder does not perform mouse navigation internally to fire the mouse triggers.  As a result, mouse move, enter, and leave can fire on the non-current item, or on an item that does not contain a record (for example, the fifth record in a multi-record block which is in Enter Query mode).


Performing actions based on the mouse button pressed

 Examples	     Related Topics

You can initiate an action based on which button the operator presses, whether the button pressed is button 1, 2 or 3.

You can also initiate an action based on a single click, a double-click, a single click combined with a shift modifier, and other combinations.

Button Number Pressed  To initiate an action based on the mouse button pressed, use a When-Mouse-Click trigger in conjunction with the SYSTEM.MOUSE_BUTTON_PRESSED system variable.

Single or Double-click  To perform an action when the operator clicks or double-clicks the mouse, use either a When-Mouse-Click or a When-Mouse-DoubleClick trigger.


Performing actions based on the mouse button pressed examples
Performing actions based on the mouse button pressed example

The following example demonstrates how to determine which mouse button is pressed when the operator clicks the mouse.

/* **  Trigger:  When-Mouse-Click */

 DECLARE

   the_button_pressed  VARCHAR(1);

   BEGIN

     the_button_pressed := :System.Mouse_Button_Pressed;

   IF the_button_pressed = '1' THEN

     Show_Window('options_window');

   END IF;

 END;


Performing actions based on mouse location

 Examples	     Related Topics

You can initiate an action based on the mouse's current location, whether the mouse is in an item, record, coordinate area, or canvas.

Mouse in Item  To determine which item the mouse is in, use a When-Mouse-Move trigger in conjunction with the SYSTEM.MOUSE_ITEM system variable.

Mouse Coordinates  To initiate an action based on the current X and Y mouse coordinates, use a When-Mouse-Move trigger in conjunction with the  SYSTEM.MOUSE_X_POS and SYSTEM.MOUSE_Y_POS system variables.

Mouse in Record  To perform an action based on the record number the mouse is in, use When-Mouse-Move or a When-Mouse-Click trigger in conjunction with the SYSTEM.MOUSE_RECORD system variable.


Performing actions based on mouse location examples

/* **  Trigger:  When-Mouse-Move */

 DECLARE

    mouse_location   varchar(50);

 BEGIN

    mouse_location := :System.Mouse_Item;

 END;

In the following example, the SYSTEM.MOUSE_X_POS and SYSTEM.MOUSE_Y_POS system variables are used within a When-Mouse-Click trigger to dynamically reposition items.

DECLARE

    item_to_move       VARCHAR(50);

    the_button_pressed VARCHAR(50);

    target_x_position  VARCHAR(3);

    target_y_position  VARCHAR(3);

 BEGIN

 /* **  Get the name of the item that was clicked. */

    item_to_move := :System.Mouse_Item;

    the_button_pressed := :System.Mouse_Button_Pressed;

 /* **  If the mouse was clicked on an area of a canvas that is

    **  not directly on top of another item, move the item to

    **  the new mouse location. */

    IF item_to_move IS NOT NULL AND the_button_pressed = '2' THEN

      target_x_position := :System.Mouse_X_Pos);

      target_y_position := :System.Mouse_Y_Pos);

      Set_Item_Property(item_to_move,position,target_x_position,target_y_position);

      target_x_position := NULL;

      target_y_position := NULL;

      item_to_move := NULL;

    END IF;

 END;

In the following example, the SYSTEM.MOUSE_CANVAS system variable is used within a When-Mouse_Move trigger to determine which canvas the mouse is in.

DECLARE

    canvas_name  VARCHAR(50);

 BEGIN

    canvas_name := :System.Mouse_Canvas;

 END;

To determine which window the mouse is in, add the following line to the example above:

window_name := :Get_View_Property(canvas_name,window_name);


What is a multiple-form application?

A multiple-form application is designed to open more than one form module during a single Forms Runtime session.  Every Forms Runtime session begins the same way—with a single form module being loaded into memory.  Once the first form module begins execution, it can programmatically invoke any number of additional form modules, which, in turn, can invoke still other forms.  Such modular application development can provide advantages both at design time and during deployment.

When a form module programmatically invokes another, Form Builder looks for the new module in the appropriate directory and then loads it into memory.  When you deliver a multiple-form application to end users, all .FMX, .MMX, and .PLL (form, menu, and library) files that will be called during the session must reside in the working directory or search path defined for your system.


Invoking Form Builder programmatically
Invoking another form programmatically

  Related Topics

To programmatically invoke another form module, a form can execute three built-in Form Builder procedures:

•	OPEN_FORM  (opens a separate, independent form)

•	NEW_FORM  (replaces the current form with a different form)

•	CALL FORM  (calls a modal form)

When a form executes OPEN_FORM to invoke another form, the first form remains displayed, and end users can navigate between the forms as desired.  An opened form can share the same database session as the form from which it was invoked, or it can create a separate session of its own.  For most GUI applications, using OPEN_FORM is the preferred way to implement multiple-form functionality.

When a form executes NEW_FORM to invoke another form, Form Builder exits the first form and releases its memory, and then loads the new form (i.e., the second form completely replaces the first.  If changes are pending in the first form, Form Builder will prompt the end user to save them before the new form is loaded.

When a form executes CALL_FORM to invoke another form, the called form is modal with respect to the calling form. Any windows that belong to the calling form are not usable until the called form is exited and control returns to the calling form.

Both OPEN_FORM and CALL_FORM allow you to leave the calling form displayed.  Using this technique, you can integrate forms so tightly that end users are not aware that they are invoking separate forms.

Form Builder maintains any locks (obtained by a form) across both OPEN_FORM (in the same session), CALL_FORM and NEW_FORM procedure calls.  Thus, a called form automatically has the same locks as its calling form.

CALL_FORM is an unrestricted procedure, OPEN_FORM and NEW_FORM are restricted.  Therefore, CALL_FORM is valid in Enter Query mode, while OPEN_FORM and NEW_FORM are not.


Multiple-form applications and the root window

  Related Topics

When you use OPEN_FORM or CALL_FORM to create a multiple-form application, usually you should avoid defining a root window in any of the form modules that you plan to display at the same time.  At runtime, only one root window can be displayed at a time, even in a multiple-form application.  This means that if the first canvas displayed by Form B is a content view assigned to the root window, it will display in the root window of Form A, not in a separate root window of its own.  As a result, Form B's content canvas will hide any Form A canvases already displayed in the root window.  For most multiple-form applications, this is not the desired behavior.

If you must use a root window, you can prevent the second form from hiding the first.  Make sure that the target canvas (displayed by the second form) is one of the following:

•	a content canvas or stacked canvas assigned to a window other than the root window

•	a stacked canvas assigned to the root window

When the target canvas is assigned to a different window, Form Builder displays the second form in a separate window, and the first form's root window display remains unchanged.

When the target canvas is a stacked canvas assigned to the root window, Form Builder displays it in the first form's root window. However, if the stacked canvas is smaller than the content canvas (usually the case), the first form's content canvas remains at least partially visible.


Invoking independent forms with OPEN_FORM

  Related Topics

To programmatically open another form, execute the OPEN_FORM built-in procedure:

OPEN_FORM('stocks');

By default, Form Builder immediately activates the opened form and sets focus in the form's first navigable item.  To explicitly specify this default behavior, include the optional ACTIVATE parameter:

OPEN_FORM('stocks', activate);

When you open a form with ACTIVATE specified, Form Builder ignores (and never executes) any trigger statements that follow the call to OPEN_FORM.

If you do not want Form Builder to place focus in the opened form, include the NO_ACTIVATE parameter:

OPEN_FORM('stocks', no_activate);

When you open a form with NO_ACTIVATE specified, Form Builder executes any trigger statements that follow the call to OPEN_FORM after the opened form has been loaded into memory and its initial start-up triggers (if any) have been fired.

Whether you open a form with ACTIVATE or NO_ACTIVATE, Form Builder will fire any triggers in the opened form that normally would fire at form start-up.  Potentially, these could include Pre-Form, When-New-Form-Instance, When-New-Block-Instance, When-New-Record-Instance, and When-New-Item-Instance triggers.

To close an independent form, execute the CLOSE_FORM procedure:

CLOSE_FORM('stocks');


Navigation between independent forms

  Related Topics

Navigation between forms in a multiple-form application can occur when the end user navigates with the mouse, or when a form calls one of the following navigational built-in procedures:

•	GO_FORM

•	NEXT_FORM

•	PREVIOUS_FORM

GO_FORM takes one parameter that specifies the name of the target form:

GO_FORM('schedule');

NEXT_FORM and PREVIOUS_FORM navigate to the next or previous form in the same order the forms were opened at runtime:

NEXT_FORM;
PREVIOUS_FORM;

Many triggers fire in response to navigational events, including Pre- and Post- triggers (Pre-Block, Post-Record, etc.) and When-New-Instance triggers (When-New-Block-Instance, When-New-Item-Instance, etc.).  When you build a multiple-form application, you should understand how navigation affects trigger processing.

In a multiple-form application, each open form has one item that is the current item for that form.  If you use GO_FORM, NEXT_FORM, PREVIOUS_FORM or EXIT_FORM to programmatically initiate navigation to an open form, the target item is always the current item in the target form.  For example, when Form A opens and activates Form B, Form Builder sets focus to the current item in Form B.  If Form B subsequently calls EXIT_FORM or PREVIOUS_FORM, Form Builder returns focus to the current item in Form A—in this case, the item that was current when Form A opened Form B.

Keep in mind the following points when navigating between independent forms:

•	No validation occurs in the starting form.  It is possible to navigate out of a field that is currently invalid provided that the target field is in a different form.  Upon returning to the starting form and attempting to navigate within that form, normal validation is enforced.

•	With a few exceptions, no triggers fire.  The only exceptions are When-Window-Deactivated (fires in the initiating form), and When-Window-Activated (fires in the target form).  The Pre-, Post- and When-New-Instance triggers do not fire when navigating between forms.

When an end user uses the mouse to navigate from Form A to Form B, the target item can be either the current item in Form B or another item in Form B.

If the end user clicks:

•	the current item in Form B, no triggers fire

•	any other item in Form B, triggers fire that normally would fire when navigation occurs from the current item in Form B to the target item, and validation occurs as required.  In other words, form processing proceeds exactly as it would if the end user were navigating from the current item in Form B to the target item, without regard to any external forms.


Opening forms in different database sessions

  Related Topics

At runtime, Form Builder automatically establishes and manages a single connection to ORACLE.  By default, one user session is created for this connection.  However, the multiple-sessioning feature of ORACLE allows a single client to establish multiple sessions within a single connection.  ORACLE transaction-management and read-consistency features all are implemented at the session level, so creating multiple sessions allows a single user to have multiple, independent transactions.

Record-locking and read-consistency behavior for two forms in different sessions is the same as it would be for two independent clients with separate connections.  When two independent forms access the same table, it is possible for one form to obtain a lock that would prevent the other form from accessing records in the table.

In a multiple-form application, you have the option to create an independent session whenever one form opens another form with the OPEN_FORM procedure.  By default, Form Builder does not issue a savepoint when you open a form, and the opened form shares the same session as the form from which it was opened.

The following examples open a form without creating a new session, and are equivalent:

OPEN_FORM('stocks'); -- default; NO_SESSION is implicit

OPEN_FORM('stocks',
          activate,
          no_session) -- NO_SESSION is explicit (for clarity)

To open a form in its own independent session, use the SESSION parameter.  This statement opens the STOCKS form in its own session, and sets focus to it immediately:

OPEN_FORM('stocks',
          activate,
          session);

Commit Processing  When a form initiates a COMMIT, Form Builder performs validation and commit processing for each open form sharing the same session as the initiating form.  Forms are processed in a sequence defined by the order in which they were opened, starting with the form that initiated the COMMIT.  If an error occurs during commit processing, Form Builder returns input focus to the form that initiated the COMMIT.

Savepoint and Rollback  When you call OPEN_FORM with the NO_SESSION parameter (the default), Form Builder does not issue a savepoint for the form as it does when you use CALL_FORM.  If Form A opens Form B, both forms share the same session.  If Form B executes CLEAR_FORM (which performs an implicit ROLLBACK), Form Builder rolls back all changes made in Form A and Form B.

Creating independent sessions is usually appropriate for forms that access different tables and manage transactions that are logically independent.  For example, an order-entry form might have a menu option to invoke an appointment calendar form.  If the appointment calendar is opened in the same session as the order-entry form, end users must simultaneously commit changes made to both forms.  If the calendar form is opened in a separate session, however, end users can enter a new appointment and save it to the database independently, without having to commit in the order entry form.

Note:  Forms Runtime must have the Session option set to On when you execute OPEN_FORM with the session_mode parameter set to SESSION.  If the Session option is set to Off, Form Builder issues an error and does not open the indicated form.  To set the Forms Runtime Session option to On, set the FORMS50_SESSION environment variable to TRUE.  When you set the FORMS50_SESSION variable, all Forms Runtime invocations inherit its setting, unless you override the environment variable by setting the Session option from the Forms Runtime command line.


Opening multiple instances of the same form

  Related Topics

It is common in multiple-form applications to allow end users to open multiple instances of the same form.  This technique is useful for applications that allow end users to perform similar functions on different record sets, particularly when it is useful for each form to be managed within a separate transaction session.

When you programmatically open the same form n times, you have n instances of that form displayed on the screen and stored in memory.  To refer to a specific instance of a form—by calling GO_FORM or CLOSE_FORM, for example—you must use the internal ID of the form instance  (You cannot use the name of the form, since it is common to all instances of the same form.)

Once a form is open, use the built-in function FIND_FORM to obtain its internal ID:

DECLARE
  form_id   FORMMODULE;
BEGIN
  OPEN_FORM('stocks', no_activate);
  form_id := FIND_FORM('stocks');
  :GLOBAL.formid := TO_CHAR(form_id.id);
END;

In this example, a variable of type FormModule (a native Form Builder type) is declared.  Once the STOCKS form is opened, its internal ID is assigned to the variable by the FIND_FORM function.  The instance identifier then is converted to CHAR and assigned to a global variable.

Once stored in a global variable, you can retrieve the instance identifier at any time for operations on the specific form instance.  The following example passes the instance identifier to the built-in procedure GO_FORM:

DECLARE
  form_id   FORMMODULE;
BEGIN
  form_id.id := TO_NUMBER(:GLOBAL.formid);
  GO_FORM(form_id);
END;

The GO_FORM procedure takes a parameter of type FormModule, so the first step is to declare a variable of that type to hold the instance ID currently held in the global variable.  Notice also that the instance identifier must be cast to NUMBER to be a valid FormModule value.

To store the instance identifier for several different forms, combine global variables with the COPY built-in procedure:

DECLARE
  form_id FORMMODULE;
  temp    CHAR(10);
BEGIN
  -- Initialize a counter, open the STOCKS form, and
  -- store its internal ID in form_id
  --
  DEFAULT_VALUE('1', 'GLOBAL.counter');
  OPEN_FORM('stocks', NO_ACTIVATE);
  form_id := FIND_FORM('stocks');
  --
  -- The COPY() procedure reads only global variables
  -- and item values, so put the instance identifier in
  -- in a a temporary global variable
  --
  :GLOBAL.temp_var := TO_CHAR(form_id.id);
  --
  -- Now assign the ID to the next occurrence of the global
  -- variable :GLOBAL.form<x>, where x is the counter value
  --
  COPY(NAME_IN('GLOBAL.temp_var'),
               'GLOBAL.form' || :GLOBAL.counter);
  :GLOBAL.counter := TO_NUMBER(:GLOBAL.counter) +1;
END;

This example creates a set of global variables (:GLOBAL.form1, :GLOBAL.form2, etc.) which contain the instance identifiers for each open form.  You then can use the appropriate variable for programmatic operations on a specific form.


Replacing the current form with NEW_FORM

  Related Topics

To replace the current form in an application, execute the NEW_FORM built-in procedure:

NEW_FORM(formmodule_name     CHAR,
         rollback_mode       NUMBER,
         query_mode          NUMBER,
         parameterlist_name  CHAR);

The FormModule_Name parameter is required;  all others are optional.  If you leave the optional parameters unspecified, Form Builder runs the new form using the defaults for those parameters.  Thus,

NEW_FORM('form_b');

is logically equivalent to

NEW_FORM('form_b',
         to_savepoint,
         no_query_only);

If the calling form was itself a called form (i.e., invoked with the CALL_FORM procedure), the new form assumes the parent form's position in the call stack.  Further, Form Builder runs the new form with the same CALL_FORM parameters (HIDE or NO_HIDE, DO_REPLACE or NO_REPLACE, and QUERY_ONLY or NO_QUERY_ONLY) as the calling form.


Calling modal forms with CALL_FORM

  Related Topics

To programmatically invoke, or call, another form by, execute the CALL_FORM built-in procedure:

CALL_FORM(formmodule_name     CHAR,
          display             NUMBER,
          switch_menu         NUMBER,
          query_mode          NUMBER,
          parameterlist_name  CHAR);

The FormModule_Name parameter is required;  all others are optional.  If you leave the optional parameters unspecified, Form Builder runs the called form using the default values for those parameters.  Thus,

CALL_FORM('form_b');

is logically equivalent to

CALL_FORM('form_b',
          HIDE,
          NO_REPLACE,
          NO_QUERY_ONLY);

CALL_FORM loads the indicated form while leaving the calling form loaded.  For example, when Form A calls Form B, Form B becomes the active form in the session, but Form A remains in memory.  If the end user exits Form B, Form A again becomes the active form.  Form B, in turn, can execute the CALL_FORM procedure to invoke Form C.  When successive forms are loaded via the CALL_FORM procedure, the resulting module hierarchy is known as the call form stack.

When a form calls another form with CALL_FORM, the called form is modal with respect to the calling form.  Windows that belong to the calling form are not usable until the called form is exited and control returns to the calling form.

In contrast to the NEW_FORM procedure, CALL_FORM does not exit the current form and release its associated memory before running the new form at the current position in the call form stack.

When you execute CALL_FORM, you can specify whether the calling form should remain displayed by passing an appropriate constant for the display parameter.  Valid constants are HIDE (the default) and NO_HIDE.  The following procedure call invokes Form B and leaves Form A (the calling form) displayed:

CALL_FORM('form_B',
          NO_HIDE);

Only the called form is active, and end users cannot navigate to items in the calling form until they exit the called form.


Exiting from a called form

By default, Form Builder exits a form when any of the  the following operations occurs:

•	EXIT_FORM procedure

•	NEW_FORM procedure

•	Exit command on the default Action menu

•	[Exit/Cancel] key

When a called form exits, control returns to the calling form, and processing resumes where it left off.  This means that the trigger, menu item command, or user-named routine that executed the CALL_FORM procedure resumes processing at the statement immediately following the CALL_FORM procedure call.


Allowing end users to quit from a called form

It is often desirable to allow end users to quit an application from a called form, rather than requiring them to explicitly exit each form in the call stack.  You can accomplish this by using a global variable that indicates whether the end user wants to quit the entire session or return to the calling form.  (Global variables are visible across called forms.)

For example, the called form might have a button labeled QUIT that allows end users to quit the entire application from a called form. The When-Button-Pressed trigger for each button sets the value of a global variable to indicate that the end user wants to either quit the session or return to the calling form.

When-Button-Pressed Trigger on QUIT button in Called Form B:

:GLOBAL.quit_check := 'quit';
Exit_Form;

Then, in the calling form, read the value of the global variable immediately after the CALL_FORM procedure statement:

Trigger Text in Calling Form A:

CALL_FORM('form_b');
/*
** The following statements execute immediately after
** returning from the called form.
*/
IF :GLOBAL.quit_check = 'quit' THEN
  exit_form;
END IF;


Calling a form in query-only mode

When you call a form with CALL_FORM or NEW_FORM, you can specify whether the called form should run in normal mode or query-only mode.  A form in query-only mode can query the database but cannot perform inserts, updates, or deletes.

To specify the query mode for a called form, supply the appropriate constant for the query_mode parameter in the CALL_FORM or NEW_FORM argument list.  Valid constants are NO_QUERY_ONLY (normal mode) and QUERY_ONLY.

For example,

CALL_FORM('form_b',
          no_hide,
          no_replace,
          query_only);

  or

NEW_FORM('form_b',
         to_savepoint,
         no_query_only);

Note:  Form Builder runs any form called from a form in query-only mode as a QUERY_ONLY form, even if the CALL_FORM or NEW_FORM syntax specifies that the called form is to run in NO_QUERY_ONLY (normal) mode.


Using CALL_FORM with OPEN_FORM in the same application

 Examples	   Restrictions

When you execute CALL_FORM to invoke a modal form, the calling form is disabled until the end user exits the called form (and returns to the calling form).  When a calling form is disabled, its windows are greyed out, and end users are unable to set focus to items in the form.

A called form can in turn call another form.  The result is three forms loaded in memory one of which is active and available to the end user.  When successive forms are loaded with the CALL_FORM procedure, the resulting module hierarchy is known as the call form stack.


Using CALL_FORM with OPEN_FORM in the same application restrictions

When you invoke multiple forms in the same application with the built-in procedures OPEN_FORM and CALL_FORM, be aware of the following restrictions:

•	Navigation  You cannot navigate programmatically to a disabled form in a call form stack.

•	Calling Forms  An open form cannot execute the CALL_FORM procedure if a chain of called forms has been initiated by another open form.


Using CALL_FORM with OPEN_FORM in the same application examples

•	Consider the following example:  (1) form A calls form B,  (2) form B opens form C,  (3) form C opens form D, and  (4) form B calls Form E.  At this point, three forms are active and navigable (C, D and E), and two are disabled and non-navigable (A and B).  Any attempt to navigate programmatically to forms A or B will raise an error.  Together, forms A, B and E represent the current call form stack in the application.  If form C attempts to call a form, an error will occur since an open form cannot execute CALL_FORM when there is an existing stack of called forms initiated by another form (form A in this case).  Before form C can successfully execute CALL_FORM, the end user or the application must exit form E (to return to form B), then exit form B (to close out the call form stack).  If form D exits, focus returns to the form from which D was opened (form C in this case).  If C then exits, focus returns to form E, even though form B originally opened form C.  This occurs because B currently is disabled because it issued a CALL_FORM to invoke form E.


Managing commit-processing when using CALL_FORM

In a multiple-form application, both called forms and calling forms can issue DML commands to lock records, commit changes, and roll back posted changes.  This section describes concepts and techniques for managing commit processing across called forms.


Posting vs. commiting

If your application requires database transactions to span called forms, you need to understand the difference between posting and committing.

During a default commit operation, Form Builder issues the SQL statements necessary to update, delete, or insert records that have been marked in the form as changed, deleted, or inserted.  Form Builder then issues the COMMIT statement to commit these transactions in the database.

Posting consists of writing updates, deletions, and insertions in the form to the database, but not committing these transactions to the database.  You can explicitly cause Form Builder to post without committing by executing the POST built-in procedure.

When an application executes the POST procedure, Form Builder does all of the default validation and commit processing, but does not issue the COMMIT statement to finalize these transactions.

Since posted transactions have been written to the database, Form Builder does not have to maintain the status of the affected records across called forms.  More importantly, because these transactions have not been committed, they can be rolled back programmatically.  You can take advantage of this functionality to manage transactions across called forms.


What is post-only mode?

When a calling form has pending updates or deletes that have not been explicitly posted, Form Builder runs the called form in post-only mode.  Further, any form called from a form running in post-only mode will also be in post-only mode.

In post-only mode, no commits or full rollbacks are allowed.  Any attempt to commit returns the message:

FRM-40403: A calling form has unposted changes. Commit not allowed.

If an end user makes changes to records in the called form and then issues the default Exit command, Form Builder displays the alert:

Do you want to Post the changes you have made?

This functionality maintains any locks obtained by a calling form until control is returned to that form.


About savepoints and rollbacks

When all of the forms in an application have the Savepoint Mode property On (the default), Form Builder issues a savepoint each time a form is loaded into memory at form startup, or via NEW_FORM or CALL_FORM (no savepoint is issued when a form is invoked with OPEN_FORM). When an application invokes multiple forms, these savepoints separate database transactions into segments that correspond to specific form modules.

Since Form Builder issues a savepoint for each called form, your application can post and roll back changes in individual forms without affecting changes in other forms that were active during the session.


Rolling back changes

The built-in procedures EXIT_FORM and NEW_FORM are similar in that both result in Form Builder leaving the current form; the difference between them is that while EXIT_FORM merely leaves the current form, NEW_FORM names another form to be loaded in its place.  In both cases, Form Builder must either preserve or roll back changes that were made in the current form before exiting.  In addition to EXIT_FORM and NEW_FORM, a CLEAR_FORM operation also either preserves or rolls back changes.

You can control whether changes in a form are preserved or rolled back when the following operations occur:

•	a form executes the EXIT_FORM built-in procedure

•	the end user selects the Exit item on the default Action menu (this is equivalent to calling EXIT_FORM with default parameters)

•	a form executes the NEW_FORM built-in procedure

•	a form executes the CLEAR_FORM built-in procedure

•	the end user selects the Clear All command from the default Action menu (this is equivalent to calling CLEAR_FORM with default parameters)

Whether changes are preserved or rolled back depends on the rollback mode specified for these operations.

When you call the EXIT_FORM, NEW_FORM, or CLEAR_FORM procedures, the rollback mode is determined by the constant you supply for the rollback_mode parameter:  TO_SAVEPOINT, NO_ROLLBACK, or FULL_ROLLBACK.


About rollback mode parameters

The TO_SAVEPOINT, NO_ROLLBACK, and FULL_ROLLBACK parameters are predefined numeric constants, and should be entered without single quotes, as shown in the following examples:

CLEAR_FORM(ask_commit, to_savepoint);
NEW_FORM('my_form', no_rollback);
EXIT_FORM(ask_commit, full_rollback);

Rollback Parameter	Description
TO_SAVEPOINT	The default.  Form Builder rolls back uncommitted changes (including posted changes) to the last savepoint.  If the form is a called form, any changes that were posted in the calling form are preserved.  But changes in the current form or locks acquired are lost.
NO_ROLLBACK	Form Builder does not issue a rollback, and posted changes are preserved.  (Unposted changes in the current form are lost.) When calling a new form or exiting a called form, any locks that were obtained by the current form remain in effect.
FULL_ROLLBACK	Form Builder rolls back all uncommitted changes pending in the current session (including posted changes).  This includes changes made in the current form, posted changes made in forms that called the current form, and posted changes made in forms that were called by the current form.

Note that full rollbacks are not allowed when a form is in post-only mode, and calling a procedure with the FULL_ROLLBACK parameter returns an error such as:

FRM-40739: Clear_Form with FULL_ROLLBACK not allowed in post-only form.


Default rollback mode

The default rollback mode for the CLEAR_FORM, NEW_FORM, and EXIT_FORM procedures is TO_SAVEPOINT.  Thus, the statements

CLEAR_FORM;
NEW_FORM('form_name');
EXIT_FORM;

are logically equivalent to

CLEAR_FORM(ask_commit, to_savepoint);
NEW_FORM('form_name', to_savepoint);
EXIT_FORM(ask_commit, to_savepoint);

Note:  Form Builder interprets a ROLLBACK statement in a PL/SQL block as a CLEAR_FORM built-in procedure with no parameters.


Modifying the CLEAR_ALL and EXIT commands

  Related Topics

Form Builder's default form menu provides a Clear All command on the Action menu that allows end users to roll back changes in a form.  By default, the Clear All item is functionally equivalent to executing the CLEAR_FORM procedure with default parameters:

CLEAR_FORM(ask_commit, to_savepoint);

Similarly, the Exit item on the Action menu is functionally equivalent to calling the EXIT_FORM procedure with default parameters:

EXIT_FORM(ask_commit, to_savepoint);

Since these menu items map directly to key commands, you can change their functionality by writing an appropriate Key trigger.  For example, you might want to change the default behavior of the Clear All menu item to roll back all changes in the session, including changes posted in calling forms.  To do so, you could write the following Key-CLRFRM ("clear-form") trigger to cause a full rollback:

CLEAR_FORM(no_commit, full_rollback);

Similarly, you can change the rollback mode for the Exit menu item to NO_ROLLBACK, so that changes posted in the current form are not rolled back on exit.  To do so, write the following Key-Exit trigger:

EXIT_FORM(ask_commit, no_rollback);


Using posting and rollback mode to manage transactions

 Examples

Although an application can include more than one form module, it can process only one database transaction at a time.  A commit operation in a form commits updates, inserts, and deletes pending for the entire application session, rather than for any individual form in the application.  This means that a commit issued by Form B can commit changes that were posted by Form A.  Similarly, a rollback command can roll back changes that were posted in forms other than the current form.

When you build an application with multiple forms, you can use posting and rollback mode to control commit processing across called forms.

When changes are posted in the calling form, the called form does not run in post-only mode, and end users can issue a commit from the called form.  The following steps illustrate this sequence, and show how posting allows a called form to commit changes that were made in the calling form:

1	Update or delete records in Form A.

2	Post in Form A.

3	Call Form B.

4	Insert, update, or delete records in Form B.

5	Commit in Form B.  (This commits the changes made in Form B and the posted changes in Form A.)

6	Exit Form B.


Using posting and rollback mode to manage transactions examples

/* EXAMPLE 1: Committing from a Called Form

** Form Builder runs called forms in post-only mode when there
** are unposted changes in the calling form. Although post-only
** mode is useful in many applications, externalizing it to
** end-users can add complexity to your application's interface.
** For some applications, it may be better to prevent forms
** from running in post-only mode altogether. To do so, design
** the application so changes are explicitly posted before
** another form is called. To post changes in a form, execute
** the POST built-in procedure just prior to calling a form
** with the CALL_FORM or NEW_FORM procedure.  For example, you
** can include the POST procedure in the menu item command or
** When-Button-Pressed trigger that calls the next form:
*/
POST;
IF (system.form_status <> 'QUERY') THEN
  CALL_FORM('form_b', no_hide);
END IF;

/* EXAMPLE 2: Committing Changes in the Calling Form
**            from the Called Form
**
** Use posting to allow a calling form to commit changes posted in
** a called form. The following steps illustrate this sequence:
**
** 1. Update or delete records in Form A.
** 2. Call Form B. (Form B is in post-only mode because changes
**    were made in Form A that were not explicitly posted.)
** 3. Insert, update, or delete records in Form B.
** 4. Post in Form B.
** 5. Exit Form B with NO_ROLLBACK parameter.
** 6. Commit in Form A. (This commits changes made in Form A and
**    changes posted in Form B.)
**
** When Form B exits and returns control to Form A (step 5),
** the rollback mode is set to NO_ROLLBACK to preserve changes
** that were posted in Form B.


Checking for changed records

If the POST built-in is executed when there are no changes to be posted, Form Builder displays the error message:

FRM-40405: No changes to post.

To avoid this error, before attempting to post, check the system variable SYSTEM.FORM_STATUS to verify that at least one record in the form has been validated as CHANGED:

ENTER;
IF system.form_status = 'CHANGED' THEN
  POST;
END IF;
CALL_FORM('form_b', no_hide);

Since the default rollback mode when exiting a form is TO_SAVEPOINT, you must explicitly override this functionality to avoid a rollback.  For example, if the end user selects the Exit item on the default Action menu, changes made in the called form will be lost. To override the default Exit command, you might write the following trigger:

Key-EXIT Trigger:

IF system.form_status = 'CHANGED' THEN
  POST;
END IF;
EXIT_FORM(no_commit, no_rollback);

You can use this same technique when you leave the current form by executing the NEW_FORM procedure instead of EXIT_FORM.

IF system.form_status = 'CHANGED' THEN
  POST;
END IF;
NEW_FORM(no_commit, no_rollback);

In this case, changes posted by the called form can then be committed by the new form that takes its place.


Getting information about the call form stack

 Examples	     Related Topics

You can use the built-in function GET_APPLICATION_PROPERTY to get information about the call form stack in a multiple-form application, including the following:

•	the name of the current form (parameter CURRENT_FORM)

•	the name of the form that called the current form (parameter CALLING_FORM)

•	the username and password of the current end user (parameters USERNAME and PASSWORD)


Getting information about the call form stack examples

/* Determine which form called the current form

** (with CALL_FORM)
*/
DECLARE
  parent_form  CHAR(20);
BEGIN
  parent_form := GET_APPLICATION_PROPERTY(calling_form);
  IF parent_form = 'form_A' THEN
    POST;
    EXIT_FORM(no_commit, no_rollback);
  ELSE
    COMMIT_FORM;
    EXIT_FORM;
  END IF;
END;


Suppressing post and commit transaction messages

When you build multiple-form applications, you might want to suppress messages regarding transaction posting and committing.  To do so, set the SYSTEM.MESSAGE_LEVEL system variable to 5 just before a post or commit, then reset it to the desired value.


Passing parameters to forms

  Related Topics

When you invoke a form with the procedures OPEN_FORM, CALL_FORM, or NEW_FORM, you can pass values for form parameters from the calling form to the called form.

To pass parameter values from one form to another, each parameter and its value must be in a parameter list.  Parameter lists are internal, three-column data structures that contain the key (name), the type  (Text_Parameter or Data_Parameter) and the value of each parameter on the list.

The parameters whose values are being passed must have been defined in the called form at design time.  That is, the called form must be expecting a value for each of the parameters included in the parameter list it receives from the calling form.

You can define parameters in a form in the Object Navigator at design time and also programmatically at runtime.  The properties of a parameter include Name, Parameter Data Type, Length, and Parameter Initial Value.  Parameter lists must be created programmatically with the built-in routines CREATE_PARAMETER_LIST and ADD_PARAMETER.

Parameter values are not visible across multiple forms.  Thus, even if there is a parameter named p1 defined in both Form A and Form B, each form has a separate context, and setting the value of p1 in Form B has no effect on the value of p1 in Form A.  For this reason, parameters are useful in multiple-form applications primarily as inputs to a form when it is first invoked.

If your application requires variables whose values are visible across called forms, you should use global variables. Global variables are visible across called forms, and remain active until they are explicitly deleted with the ERASE built-in procedure, or until the session ends.


Passing a parameter list

 Examples	     Related Topics

A parameter list is passed from one form to another as the last argument to the OPEN_FORM, CALL_FORM, or NEW_FORM built-in procedures:


Passing a parameter list examples

/* In this example, a parameter list named form_a_parms is

** created and its object ID is assigned to a variable named
** p_list.  A text parameter named p1 then is added to the
** list with ADD_PARAMETER, and its value is set to "BICYCLE."
** Finally, the parameter list is passed to Form B as the last
** argument to the OPEN_FORM procedure. For this example to
** work, a form parameter named p1 must have been declared in
** Form B at design time, and its datatype and length must be
** compatible with the value being passed.
*/
DECLARE
  p_list  PARAMLIST;
BEGIN
  p_list := CREATE_PARAMETER_LIST('form_a_parms');
  ADD_PARAMETER(p_list, 'p1', text_parameter, 'BICYCLE');
  OPEN_FORM('form_b', activate, no_session, p_list);
END;


The default parameter list

 Examples

Each form includes a built-in parameter list named Default.  The Default parameter list contains all of the form parameters that were defined in the form at design time.  For example, if you define parameters p1, p2, and p3 in Form A at design time, they  are automatically included in the Default parameter list for Form A.


The default parameter list examples

/* Like any other parameter list, the Default parameter

** list can be passed to a called form by including it in
** the argument list of the OPEN_FORM, CALL_FORM, or
** NEW_FORM built-in procedures.
*/
DECLARE
  p_list  PARAMLIST;
BEGIN
  p_list := GET_PARAMETER_LIST('default');
  OPEN_FORM('form_b', activate, no_session, 'default');
END;


Initial values of parameters in a called form

The following table shows how the initial values of parameters in the called form are determined by the parameter list being passed by the calling form with OPEN_FORM, CALL_FORM, or NEW_FORM.  It assumes that there are corresponding parameters in Form A (the calling form) and Form B (the called form).

If Form A passes...	Form B's corresponding parameters are set to...
no parameter list	Default parameter values specified in Form B at design time.  (If no default value was specified, the parameter value defaults to NULL.)
Default parameter list	The current values of the corresponding parameters in Form A.
Programmatically- created parameter list	The values specified for the parameters when they were put in the parameter list with ADD_PARAMETER.


Parameter validation

 Examples	     Related Topics

When you pass the Default parameter list to a form, Form Builder validates the individual parameters against the parameters defined in the called form as follows:

•	Each parameter in the list must have been defined in the called form at design time.  If you pass an undefined parameter, OPEN_FORM, NEW_FORM, and CALL_FORM will fail, and Form Builder will issue an error message:  FRM-47023: No such parameter named <parameter name> exists in <form module name>.

•	The datatype and length of the parameter defined in the called form must be compatible with the parameter value being passed.  (Values in a parameter list are untyped strings, whereas form parameters are declared as type CHAR, NUMBER, or DATE.)  If the parameter is incompatible with the value, OPEN_FORM, NEW_FORM, or CALL_FORM will fail, and Form Builder will issue an error message: FRM-47024: Parameter <parameter name> type does not match definition in <name of called form>.

You can modify the Default parameter list by adding and deleting parameters with the built-in procedures ADD_PARAMETER and DELETE_PARAMETER.


Parameter validation examples

/* To avoid a validation error, you can remove unwanted

** parameters from the list before passing it to a form.
** For example, if Form B requires only parameters p1 and
** p2, you could remove p3 from the list before passing
** the list to Form B.
*/
DECLARE
  p_list  PARAMLIST;
BEGIN
  p_list := GET_PARAMETER_LIST('default');
  DELETE_PARAMETER(p_list, 'p3');
  OPEN_FORM('form_b', activate, no_session, 'default');
END;


Integrating form and menu modules

Just as multiple form modules can be combined into a single application, so too can multiple menu modules be used as needed.  You can design an application so that several form modules share the same menu module, or have each form in the application run its own menu.  How menus are loaded in multiple-form applications depends on whether you are using OPEN_FORM, NEW_FORM, or CALL_FORM.


OPEN_FORM menu functionality

When you use OPEN_FORM to create multiple-form applications, each form module has its own menu module.  When the end user navigates between forms, the menu for the current form becomes the current menu for the application.  Note that on Microsoft Windows, the MDI display style dictates that the menu for the current form should be displayed on the MDI application window. This means that as end users navigate between forms, only the menu for the current form will be displayed.


NEW_FORM menu functionality

When you use NEW_FORM to create multiple-form applications, Form Builder always loads the new form's menu module, even if it is the same module used by the calling form.

The only exception to this rule is if the form that executes the NEW_FORM procedure is itself a called form that was invoked with the NO_REPLACE parameter.  In this case, the new form inherits the NO_REPLACE restriction, and runs under the calling form's menu.


CALL_FORM menu functionality

When you use CALL_FORM to create multiple-form applications, the switch_menu parameter determines whether Form Builder loads a different menu or retains the current menu.  Valid constants for the switch_menu parameter include DO_REPLACE and NO_REPLACE.

The NO_REPLACE parameter value (the default) causes Form Builder to keep the current menu module.  DO_REPLACE causes Form Builder to replace the current menu module with the menu that was attached to the called form at design time (either the default Form Builder menu or a custom menu module).

For example,

CALL_FORM('form_b', hide, do_replace);

runs Form B with the menu that was attached to Form B at design time,  rather than keeping the current menu.


Creating a master menu

In multiple-form applications, it is common to create a front-end form that exists only to display the application's main menu.  Items on the main menu can then invoke individual form modules that perform specific application functions.  To create a master menu that invokes other forms, first create a form module with no blocks or items, then attach your master menu module to that form.

Invoking Forms from a Master Menu with OPEN_FORM  When items on a master menu invoke forms with OPEN_FORM, each independent form has its own menu.  You cannot specify that an independent form use the current menu.

Invoking Forms from a Master Menu with NEW_FORM  When items on the master menu invoke forms with the NEW_FORM built-in procedure, the menu module attached to each form is loaded when that form is invoked.  When all of the forms in an application share the same menu, reloading the same menu each time a new form is invoked (and potentially querying the database each time) may be unacceptable.

To avoid this problem, create a start-up form that exists only to call the front-end form (and its master menu) by executing CALL_FORM with the NO_REPLACE parameter.  With this design, Form Builder does not reload the menu each time a different form is invoked from the main menu.  Since the front-end form is itself a called form, any form modules invoked with the NEW_FORM procedure automatically inherit the NO_REPLACE restriction, and run under the master menu.

Invoking Forms from a Master Menu with CALL_FORM  When items on the master menu invoke forms with the CALL_FORM built-in procedure, you can specify whether called forms should inherit the master menu with the switch_menu parameter (DO_REPLACE or NO_REPLACE).


Using the REPLACE_MENU built-in procedure

  Related Topics

You can use the REPLACE_MENU built-in procedure to dynamically replace the current form's menu with a different menu:

For example, to replace the current menu with a menu called my_new_menu you could write the following procedure call:

REPLACE_MENU('my_new_menu');


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 index 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.


Using the Layout Wizard to arrange items

To use the Layout Wizard to arrange items:

1	In the Object Navigator, click the desired block.

2	Choose Tools [image] Layout Wizard to invoke a wizard that guides you through the process of arranging items.


Selecting an object

To select an object:

1	In the Layout Editor, click the Select tool in the tool palette.

2	Click the desired object.


Selecting objects in a region

To select objects in a region:

1	In the Layout Editor, click the Select tool in the tool palette.

2	Click and drag until the selection rectangle encloses the objects you want to select.


Adding an object to the current selection

To add an object to the current selection:

1	In the Layout Editor, click the Select tool in the tool palette.

2	Press the Control key while clicking the desired object.


Selecting all objects

To select all objects in the workspace:

1	Choose Edit [image] Select All.


Deselecting an object

To deselect an object:

1	Click anywhere outside the object's bounding box.

Note: To deselect an object in a multiple selection, Shift-click on the object to deselect only that object.


Moving an object

  Related Topics

To move an object:

1	In the Layout Editor, click the Select tool in the tool palette.

2	Click and drag the object to the desired location.

Note: To move more than one object at a time, select the objects, then click and drag any selected object to move all of the objects in the selection.


Moving a selection incrementally

  Related Topics

To move a selection incrementally:

1	In the Layout Editor, select the desired object.

2	Press the [Up], [Down], [Left], or [Right] arrow keys.

Note: When grid snap is turned off, the arrow keys move the current selection one pixel at a time in the direction indicated.  When grid snap is turned on, the arrow keys move the current selection the distance of one snap point. To define snap point increments in the Ruler Settings dialog, select Format [image] Layout Options [image] Ruler.


Constraining a move

  Related Topics

To constrain a move:

1	In the Layout Editor, press [Constrain] (Shift on most platforms) while dragging the selected object.


Resizing an object

  Related Topics

To resize an object:

1	In the Layout Editor, click the desired object.

2	Resize the object by dragging one of its selection handles.


Making an object the same size

To make objects the same size:

1	In the Layout Editor, select the desired objects.

2	Choose Arrange [image] Size Objects.

3	In the dialog, specify whether you want the selected objects to be the same height and/or width as the smallest selected object, the largest selected object, or an average of all selected objects.  If you want to enter a specific width or height value, choose Custom.

4	Click OK to accept the size parameters.


Aligning an object

To align an object:

1	In the Layout Editor, click the desired object.

2	Choose Arrange [image] Align Objects.

3	In the dialog, specify how you want the selected objects to be aligned.  A single object can be aligned to the grid. Multiple selected objects can be aligned to the grid or to each other. You can specify horizontal and/or vertical alignment options.

4	Click OK to accept the settings.

Note: Once you define alignment settings in the Alignment Settings dialog, you can apply these settings to any selection of two or more objects.  To do so, first select the objects you want to align, then select Arrange [image] Repeat Alignment.


Centering an object

To center an object:

When the View [image] Show Canvas menu option is enabled, the canvas itself is a selectable object.  You can center objects in the middle of a canvas by doing the following:

1	In the Layout Editor, click the desired object.

2	Choose Arrange [image] Align Objects.

3	Set both Horizontal and Vertical alignment to Align Center.


About grouping objects

  Related Topics

You can select multiple objects to create a group. You can then manipulate the group as a single object.  For example, you might want to group several objects together and then move the group as a unit, without changing the relative positions of the objects in the group.


Grouping objects

  Related Topics

To group objects:

1	In the Layout Editor, select the desired objects.

2	Choose Arrange [image] Group.

The new group is automatically selected, and you can manipulate it as you would a single object. To separate a group, first select it, then choose Arrange [image] Ungroup.

You can select and manipulate a group or the individual objects in a group. For example, to move a group, position the Select tool on any object in the group, then click and drag.  To resize a group, use the Select tool to drag one of the group's selection handles.


Regrouping objects

To regroup an object:

1	In the Layout Editor, click the desired objects.

2	Choose Arrange [image] Group Operations [image] Add to Group .

The new group is automatically selected, and you can manipulate it as you would a single object. To separate a group, first select it, then choose Arrange [image] Ungroup.


About overlapping objects

  Related Topics

Objects can be placed on a canvas so that their bounding rectangles overlap.  An object in front of another object may partially or completely obscure the object it overlaps.

Form Builder manages the stacking order of items and graphic objects differently:  When an item and a graphic object overlap, the item is placed in front of the graphic object, regardless of their creation order. When two graphic objects overlap, the object that was created most recently is placed in front of the other object.


Ordering overlapping objects

  Related Topics

To reorder overlapping graphic objects:

1	In the Layout Editor, click the object you want to reorder.

2	Click the Bring to Front or Send to Back button in the toolbar.


About frames

  Related Topics

A frame is a graphic object that appears on a canvas.  You use frames to arrange the items within a block.

When you arrange items within a frame, you can, for example, create a form-style arrangement, define the distance between items and prompts, specify margins and offsets, and so on.

Frames provide these benefits:

•	a frame is an object with properties

When you associate a frame with a block, the items in the block are automatically arranged within the frame.

•	each frame can be associated with a block

•	frames can be subclassed or included within the Object Library to enforce visual standards

You can store frames within the Object Library to provide a method of enforcing standards across a project or organization.  You can create a series of "style sheets" for different types of blocks (single record, multi-record, or master-detail, for example).  To reuse a frame that is stored in the Object Library, simply drag the desired frame to a canvas, then run the Layout Wizard to arrange an existing block within it.

•	frames can be manipulated in the Object Navigator, Layout Editor, and Property Palette

•	frames can be visible or invisible

If a frame is visible, it is displayed as a beveled rectangle.  The contents of a frame appear within the frame's border.

•	the Layout Wizard uses frames to arrange items


About arranging items within frames

  Related Topics

Arranging the items within a form is an iterative process.

Initially, you use the Layout Wizard to arrange the items in a block. Later, you fine-tune the arrangement by setting individual frame properties.  As a final option, you can also make manual layout changes within the Layout Editor.

Usage Notes

•	When you specify that a block should be arranged within a frame, Form Builder arranges each item within the frame, except for those items that appear on the Null canvas.

•	By default, a frame's layout is updated automatically each time the frame is positioned, resized, or whenever a frame property is modified.

When you resize or reposition a frame, Form Builder automatically arranges the the objects within a frame at the new location or based on the new size.  Remember that a frame is not a container object, rather it defines the region within which the layout takes place.

•	If you want to manually arrange the objects within a frame by dragging objects in the Layout Editor, you should set the frame Update Layout property to Locked.  Manual modifications (dragging) should not be made until the layout is relatively stable since these types of changes can be lost.

•	If you want to resize a frame, you must set the frame's Shrinkwrap property to No.  By default, Form Builder removes the blank space within a frame.

•	When you add an item to a block that is already arranged within a frame, you must update the layout in order to arrange the new item within the frame.

•	When you remove an item from a frame (via the Layout Wizard), Form Builder sets the item's Canvas property to Null.

Restrictions

•	A frame can only be associated with one block.  A frame can only contain the items from the block that it is associated with; a frame cannot contain items from multiple blocks.


Creating a frame

  Next Step	    Related Topics

To create a frame:

Choose Tools [image] Layout Wizard to display a wizard that guides you through the process of creating a frame.

Or,

1	In the Layout Editor, click the Frame button in the tool palette.

2	Click and drag to create a frame.


Arranging items within a frame

  Related Topics

To arrange items within a frame:

In the Object Navigator, click the desired block, then choose Tools [image] Layout Wizard to invoke a wizard that guides you through the process of arranging items within a frame.

Or,

1	In the Layout Editor, double-click the frame object to display the Property Palette.

2	Under the Layout Frame node, set the Layout Data Block property to the name of the desired block.  This block will be arranged within the frame.


Creating a tabular arrangement within a frame

 Show Me	    Related Topics

To create a tabular arrangement within a frame:

Choose Tools [image] Layout Wizard to display a wizard that guides you through the process.

Or,

1	In the Layout Editor, double-click the desired frame to display the Property Palette.

2	Under the Layout Frame node, set the Layout Style property to Tabular.


Creating a form-style arrangement within a frame

 Show Me	    Related Topics

To create a tabular arrangement within a frame:

Choose Tools [image] Layout Wizard to display a wizard that guides you through the process.

Or,

1	In the Layout Editor, double-click the desired frame to display the Property Palette.

2	Under the Layout Frame node, set the Layout Style property to Form.


Adding an item to a frame

  Related Topics

To add objects to a frame:

Choose Tools [image] Layout Wizard to display a wizard that guides you through the process of adding items to a frame.

Or,

1	In the Layout Editor, create the desired item.

2	Specify which block the new item belongs to by choosing a block from the Block field.  The Block field is located in the upper region of the Layout Editor. Click the drop-down list box to display a list of all blocks.

3	Double-click the item to display the Property Palette.

4	Under the Physical node, set the Canvas property to the appropriate canvas.

Tip: The canvas you specify must be the canvas that the block's other items appear on.  For example, if BLOCK1's items appear on CANVAS1, you must set the newly created item's Canvas property to CANVAS1.

5	In the Layout Editor, click the frame.

6	Click the Update Layout button in the toolbar.


Removing an item from a frame

  Related Topics

To remove an item from a frame:

Choose Tools [image] Layout Wizard to display a wizard that guides you through the process of removing items from a frame.

Or,

1	In the Layout Editor, double-click the desired item to display the Property Palette.

2	Under the Physical node, set the Canvas property to Null.


Updating a frame's layout

  Related Topics

To update a frame's layout:

1	In the Layout Editor, click the frame.

2	Click the Update Layout button in the toolbar.


Moving a frame

  Related Topics

To move a frame:

In the Layout Editor, click and drag the frame to the desired location.

Note:  When you move a frame,  Form Builder automatically recreates the frame's layout at the new location if the frame's Update Layout property is set to Automatically (the default).


Resizing a frame

  Related Topics

To resize a frame:

1	In the Layout Editor, double-click the desired frame to display the Property Palette.

2	Under Layout Frame, set the Shrinkwrap property to No.

3	In the Layout Editor, resize the frame by dragging one of its selection handles.

When you resize a frame,  Form Builder, automatically recreates the frame's layout based on the new size if the frame's Update Layout property is set to Automatically (the default).


Deleting a frame

  Related Topics

To delete a frame:

1	In the Layout Editor, select the frame.

2	Choose Edit [image] Clear.


Moving an item within a frame

  Related Topics

To move an item within a frame

1	In the Layout Editor, click and drag the item to the desired location.

Tip:  If you are fine-tuning the layout within a frame by dragging an item to a new location, you should set the Frame's Update Layout property to Locked, otherwise your changes will be lost when the frame's layout is next updated.


Resizing an item within a frame

To resize an item within a frame

Choose Tools [image] Layout Wizard to display a wizard that guides you through the process of resizing an item within a frame.

Or,

1	In the Layout Editor, click the desired item.

2	Resize the object by dragging one of its selection handles.


Aligning all items within a frame

 Show Me	    Related Topics

To align items within a frame

1	In the Layout Editor, double-click the desired frame to display the Property Palette.

2	Under the Layout Frame node:

•	Set the Layout Style property to Form.

•	Set the Frame Alignment property to either Start, End, Center, Fill, or Column.


Aligning a single item within a frame

  Related Topics

To align a single item within a frame:

1	In the Layout Editor, double-click the desired frame to display the Property Palette.

2	Under the Layout Frame node, set the Single Object Alignment property to either Start, End, or Center.


Defining the distance between the frame and its items

 Show Me

To define the distance between the frame and its items:

1	In the Layout Editor, double-click the desired frame to display the Property Palette.

2	Under the Layout Frame node:

•	Set the Horizontal Margin property to the desired distance.

•	Set the Vertical Margin property to the desired distance.


Horizontal and Vertical Margin showme
Horizontal and Vertical Margins


Defining the distance between the items within a frame

 Show Me

To define the distance between objects within a frame:

1	In the Layout Editor, double-click the desired frame to display the Property Palette.

2	Under the Layout Frame node:

•	Set the Horizontal Object Offset property to the desired distance.

•	Set the Vertical Object Offset property to the desired distance.


Horizontal and Vertical Object Offset showme
Horizontal and Vertical Object Offsets


Aligning prompts within a frame

 Show Me

To align a prompt with its item:

1	In the Layout Editor, double-click the desired frame to display the Property Palette.

2	Under the Layout Frame node:

•	Set the Start Prompt Alignment property to either Start, End, or Center.

Or,

•	Set the Top Prompt Alignment property to Start, End, or Center.


Start Prompt and Top Prompt Alignment showme
Start Prompt and Top Prompt Alignment

Start Prompt Alignment

Top Prompt Alignment


Defining prompt offset within a frame

 Show Me

To define the distance between a prompt and its item

1	In the Layout Editor, double-click the desired frame to display the Property Palette.

2	Under the Layout Frame node:

•	Set the Start Prompt Offset property to the desired distance if prompts are attached to the start of their items.

Or,

•	Set the Top Prompt Offset property to the desired distance if prompts are attached to the top of their items.


Start Prompt and Top Prompt Offset showme
Start Prompt and Top Prompt Offset

Start Prompt Offset

  Top Prompt Offset


About prompts

  Related Topics

A prompt is the text label that appears with and relates to an item.  Each interface control can have a prompt associated with it. For example, a check box contains a text label, or prompt, next to it.

Prompts differ from graphic text (such as text box items) in that prompts are directly linked to an item. For example, when you move an item in the Layout Editor, Form Builder relocates the item and its prompt together to the new location.

Form Builder provides several properties that allow you to arrange and manage prompts and to specify a prompt's visual appearance.


Associating a prompt with an item

  Related Topics

To associate a prompt with an item:

1	In the Layout Editor, select exactly one item and and one text object.

2	Click the Associate prompt button in the Layout Editor toolbar.

Under the Prompt node in the Property Palette, view the associated text label in the Prompt property field.


Creating a prompt

  Related Topics

To create a prompt:

1	In the Layout Editor, double-click the desired item to display the Property Palette.

2	Under the Prompt node, type the desired text label in the Prompt property field.


Defining a prompt's display style

  Related Topics

To define a prompt's display style:

1	In the Layout Editor, double-click the desired prompt to display the Property Palette.

2	Under the Prompt node, set the Prompt Display Style property to either Hidden, First Record, or All Records.


Justifying a prompt

  Related Topics

To justify a prompt:

1	In the Layout Editor, double-click the desired prompt to display the Property Palette.

2	Under the Prompt node, set the Prompt Justification property to either Left, Right, Center, Start, or End.


Defining a prompt's attachment edge

  Related Topics

To define a prompt's attachment edge:

1	In the Layout Editor, double-click the desired prompt to display the Property Palette.

2	Under the Prompt node, set the Prompt Attachment Edge property to either Start, End, Top, or Bottom.


Aligning a prompt with its item

  Related Topics

To define a prompt's alignment with its item:

1	In the Layout Editor, double-click the desired prompt to display the Property Palette.

2	Under the Prompt node, set the Prompt Alignment property to either Start, End, or Center.


Defining the distance between a prompt and its item

  Related Topics

To define the distance between a prompt and its item:

1	In the Layout Editor, double-click the desired prompt to display the Property Palette.

2	Under the Prompt node, set the Prompt Attachment Offset property to the desired distance.


Defining a prompt's alignment offset

  Related Topics

To define a prompt's alignment offset:

1	In the Layout Editor, double-click the desired prompt to display the Property Palette.

2	Under the Prompt node, set the Prompt Alignment Offset property to the desired distance.


About formatting items in the Layout Editor

When you set the font, color, and pattern attributes of items in the Layout Editor, Form Builder updates the appropriate item properties in the Property Palette.

Because items are rendered in the style appropriate to the runtime platform, some item attributes are predefined and cannot be set in the Layout Editor:

•	You cannot make items transparent. The No Fill option on the Fill Color palette is valid only for graphic objects/text. If you want a text item or display item to display only text, set the Bevel property to None and make the item's Fill Color the same color as the canvas.

•	You cannot specify line width for items. The Format [image] Line Width menu command is valid only for graphic objects/text. Set the Bevel property to control item borders.

•	You cannot specify the line color for items. The Line Color color palette is valid only for graphic objects/text.

•	You cannot specify the bevel setting for items. The Format [image] Bevel menu command is valid only for graphic objects/text.

When you format an item in the Layout Editor, Form Builder implicitly sets the item's Visual Attribute Group property to Custom. If an item is inheriting visual attributes from a named visual attribute, setting its properties in the Layout Editor breaks the association with the named visual attribute. If an item is inheriting visual attributes from a property class, setting those attributes in the Layout Editor overrides the inherited settings.


About color palettes

The default color choices available to you in the Layout Editor and the Property Palette are derived from the current color palette. Color palettes can be edited, saved to the file system or the database, and imported as desired.

The default color palette has the following characteristics:

1	The upper-left region of the palette contains 16 commonly used colors with the following names: black, white, green, darkgreen, gray, dark gray, cyan, dark cyan, red, darkred, blue, darkblue, yellow, darkyellow, magenta, dark magenta.

2	The lower-left region of the palette contains eight empty cells into which you can place custom defined colors.

3	The next four 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'.

4	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, 88% blue, and 0% green is named `r100b88g0').

•	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.


Setting an object's color attributes

  Related Topics

To set an object's color attributes:

1	In the Layout Editor, click the desired object.

2	In the Layout Editor toolbar, click [image] (the fill color tool), [image] (the line color tool), or [image] (the text color tool) to display the Color dialog box.

3	Click a color from the palette.

4	Click OK.

Note: On Microsoft Windows, the color of button text is always determined by the settings specified in the Control Panel Color settings dialog, and cannot be specified in the Layout Editor.


Setting an object's pattern attributes

  Related Topics

To set an object's pattern attributes:

1	In the Layout Editor, double-click the desired object to display the Property Palette.

2	Under the Color node, double-click the Fill Pattern property to display the Fill Pattern Palette.

3	Select a pattern from the palette.


Setting an object's font attributes

  Related Topics

To set an object's font attributes:

1	In the Object Navigator, double-click the desired object's icon to display the Property Palette.

2	Under the Font node, set the following properties:

•	Font Name

•	Font Size

•	Font Weight

•	Font Style

•	Font Spacing


About hierarchical trees

  Related Topics

The hierarchical tree displays data in the form of a standard navigator, similar to those used in Forms Developer.

You can populate a hierarchical tree with values contained in a Record Group or Query Text. At runtime, you can programmatically add, remove, modify, or evaluate elements in a hierarchical tree.

The amount of data displayed at any one time depends upon the expansion of individual data nodes, whether through built-ins or a user clicking on a node. The data set generally will be initially specified in Form Builder, and may be modified or entirely replaced at runtime.


Creating a hierarchical tree

 Examples 	  Related Topics

To create a hierarchical tree:

1	In the Object Navigator, click the plus icon [image] beside the desired block node.

Form Builder expands the block node and displays its subnodes.

2	Click the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon beside the new item to display the Property Palette.

5	Under the General node, set the Item Type property to Hierarchical Tree.

6	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign it to a canvas.


Adding data to a hierarchical tree

 Examples 	  Related Topics

You can add data to a tree view by:

•	Populating a tree with values contained in a record group or query by using the Populate_Tree built-in.

•	Adding data to a tree under a specific node by using the Add_Tree_Data built-in.

•	Modifying elements in a tree at runtime by using built-in subprograms.

•	Adding or deleting nodes and the data elements under the nodes.

Note: All built-ins are located in the FTREE built-in package.


Adding a Node to a Hierarchical Tree
Adding nodes to a hierarchical tree

 Examples 	  Related Topics

You can add a node to a hierarchical tree one at a time or by populating a tree with values contained in a record group or query.

You can add values to a tree by using these built-in subprograms:

•	Add_Tree_Node

•	Delete_Tree_Node

•	Find_Tree_Node

•	Get_Tree_Node_Parent

•	Get_Tree_Node_Property

•	Get_Tree_Property

•	Get_Tree_Selection

•	Set_Tree_Node_Property

•	Set_Tree _Property

•	Set_Tree_Selection

Note: If you need to reference the pseudo root of the tree, use the constant FTREE.ROOT_NODE.  All built-ins are located in the FTREE built-in package.


Specifying a default value for a hierarchical tree
Specifying an initial value for a hierarchical tree

  Related Topics

To specify an initial value for a hierarchical tree:

1	In the Object Navigator, double-click the object icon beside the desired hierarchical tree object to display the Property Palette.

2	Under the Functional node, indicate the Record Group or Query Text that contains the initial values.

Note: These are indicators of the initial values, but nothing appears without populating the tree with the Populate_Tree built-in.


 Format of data used to populate a hierarchical tree

  Related Topics

The columns in the record groups or queries used to populate a hierarchical tree are:

•	Initial state

•	Node tree depth

•	Label for the node

•	Icon for the node

•	Data

For example, the data in the table below would produce the following hierarchical tree:

  +  - Car

  |

  -  - Airplane

     | - Boeing

     | - Boeing

Initial State	Depth	Label	Icon	Data
-1	1	'Car'	''	'car'
0	2	'Honda'	''	'civic'
1	1	'Airplane'	''	'plane'
0	2	'Boeing'	''	'747'
0	2	'Boeing'	''	'757'


Manipulating a hierarchical tree at runtime

  Related Topics

Form Builder provides triggers that you can use to respond to events that occur when the end user interacts with the hierarchical tree at runtime.

•	When-Tree-Node-Activated

•	When-Tree-Node-Expanded

•	When-Tree-Node-Selected

At runtime, you can programmatically add, remove, modify, or evaluate elements in a hierarchical tree by using the following built-in subprograms:

•	Add_Tree_Data

•	Add_Tree_Node

•	Delete_Tree_Node

•	Find_Tree_Node

•	Get_Tree_Node_Parent

•	Get_Tree_Selection

•	Populate_Group From_Tree

•	Populate_Tree

•	Set_Tree_Selection

Note: All built-ins are located in the FTREE built-in package.


Setting hierarchical tree item properties

  Related Topics

To set a hierarchical tree item property in Form Builder:

1	In the Object Navigator, double-click the object icon beside the desired hierarchical tree.

2	In the Property Palette, select the property you want to set.

3	Set the selected property to the desired setting.

You can set properties during runtime by using the following built-ins:

•	Get_Tree_Node_Property

•	Get_Tree_Property

•	Set_Tree_Node_Property

•	Set_Tree _Property

Note: All built-ins are located in the FTREE built-in package.


Populating a hierarchical tree

  Related Topics

You can populate a hierarchical tree with values contained in a Record Group or Query Text by using the following built-in subprogram:

•	Populate_Tree

•	Add_Tree_Data

Note: All built-ins are located in the FTREE built-in package.


Creating a hierarchical tree example

-- Hierarchical Tree Example

--

-- The first action will typically be to populate the

-- hierarchical tree (htree) with data.

DECLARE

   htree   ITEM;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Sets the record group and causes the data to display.

   Ftree.Set_Tree_Property(htree, Ftree.RECORD_GROUP, 'record_group5');

END;

-- Tree Node Expansion Example

--

-- This code will expand all nodes in a tree.

DECLARE

   htree   ITEM;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Find the root node of the tree.

   node  := Ftree.Find_Tree_Node(htree, '');

   -- Loop through all nodes and expand each one if it is collapsed.

   WHILE NOT Ftree.ID_NULL(node) LOOP

      state := Ftree.Get_Tree_Node_Property(htree, node, Ftree.NODE_STATE);

      IF state = Ftree.COLLAPSED_NODE THEN

         Ftree.Set_Tree_Node_Property(htree, node, Ftree.NODE_STATE, Ftree.EXPANDED_NODE);

      END IF;

      node := Ftree.Find_Tree_Node(htree, '', search_root => node);

   END LOOP;

END;

-- Delete Tree Node Example

--

-- This code will delete all tree nodes marked as selected.  See the

-- Ftree.Set_Tree_Selection built-in for a definition of "selected".

DECLARE

   htree         ITEM;

   num_selected  NUMBER;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Find the number of nodes marked as selected.

   num_selected := Ftree.Get_Tree_Property(htree, Ftree.SELECTION_COUNT);

   -- Loop through nodes and delete them. Since nodes are internally

   -- re-numbered when one is deleted, be sure to loop in reverse

   -- order from last to first.

   FOR j IN num_selected..1 LOOP

      Ftree.Delete_Tree_Node(htree, Ftree.Get_Tree_Selection(htree, j));

   END LOOP;

END;


About ActiveX and OLE

  Related Topics

Object Linking and Embedding(OLE) was introduced to support the cooperation of separate applications presenting a single compound document.  Compound documents link or embed one or more documents together solving the problem of integrating different object types in a single document.  For instance, a compound document can be a Form module document that contains objects from other applications such as word processor documents or spreadsheet documents.

Extending the compound document solution to address the larger scope of sharing services, the Component Object Model (COM) was introduced as OLE2.  OLE2 provides automation, a COM-based technology that includes a standard programmatic interface.  For example, Microsoft Excel is capable of being a toolbox as well as an end-user application.  OLE became synonmous for most technologies based on COM.

Today, ActiveX replaces OLE as the term for COM-based technologies.  OLE, once again, refers to object linking and embedding in compound documents.

ActiveX controls, originally known as OLE controls or OCXs make use of both the ActiveX and OLE technologies.  An ActiveX control is a stand alone software component that provides a user interface and sends events to clients, all according to the standards defined by COM.  It is an OLE server application that is entirely embedded in an application with OLE client capabilities.


About ActiveX and OLE in Form Builder

  Related Topics

Instead of one monolithic application that provides you with almost every feature that you want, component objects and good integration can provide you with a light-weight custom application to suit all your needs.

Word processor documents, spreadsheet documents, knob controls, and video clips are examples of component objects that can enhance the capabilities of your form.  Instead of recreating functionality that already exists, you can access these capabilities by exploiting the ActiveX and OLE support in Form Builder.  Component objects provide specialty services not available in Form Builder.  It is used to enhance the client application, providing additional, self-contained functionality.


ActiveX support in Form Builder

  Related Topics

Form Builder provides support for ActiveX controls.  ActiveX controls are reusable components that can be embedded in your Form Builder Application.  Form Builder acts as an ActiveX control container.

The ActiveX Control item type creates a container for your ActiveX control.  An ActiveX control is not a separate application, but a server that plugs into an ActiveX container.

It is recommended that you use ActiveX controls in blocks with the Single Record property set to Yes.  The Single Record property is not applicable to multiple record blocks.  It is advised that you set the Single Record property to Yes, because single records are immediately initialized when Forms Runtime starts up.  For multiple records, each record is not initialized until you navigate to the record.  Without initialization, the ActiveX control item is empty, giving the impression that no ActiveX control is available.

Each ActiveX control exposes a set of properties, methods, and events.  Properties define the ActiveX control's physical and logical attributes, methods define actions that the ActiveX control can perform, and  events denote some change in status in the ActiveX control.  A client application manipulates an ActiveX control by writing values to and obtaining values from its properties, invoking methods that are used to get and set properties, and intercepting and acting on events.

ActiveX controls are a special type of dynamic library.  A single ActiveX file that is distributed with the .OCX extension can contain more than one class of ActiveX objects.

ActiveX controls are not a variety of VBX.  VBX controls function strictly in 16-bit applications; they do not function in a 32-bit environment.  ActiveX controls can provide you with functionality similar to VBX controls in a 32-bit environment.

A significant amount of effort is required to develop your own ActiveX controls or OLE servers, therefore it is recommended that you use ActiveX controls and OLE servers developed and distributed by third party vendors.  Documentation that accompanies the ActiveX controls and OLE servers contain information on properties, methods, and events.


About adding ActiveX controls to forms

  Related Topics

ActiveX controls should only be added to single record blocks.  Form Builder automatically initializes the ActiveX control when it is in a single-record block.  When you add an ActiveX control to a multi-record block, only the first instance of the ActiveX control is initialized at startup, the other instances remain unitialized until you navigate to that instance.  Uninitialized controls appear blank, giving the impression that there is no control available for those item instances.  To create a single-record block, set the Number of Records Displayed block property to 1, or set the the Number of Items Displayed property (for the ActiveX control container)to 1.

ActiveX Controls export interfaces that expose methods and events.  Form Builder imports the methods and events in PL/SQL, enabling you to interact with ActiveX Controls in the native Form Builder environment.

Form Builder displays the imported methods under the Program Units node in the Object Navigator.  You can access these OLE methods from your application by using the STANDARD and OLE2 built-in packages.


Adding an ActiveX control to your application

  Related Topics

To add an ActiveX control to your application:

1	Create an ActiveX Control container.

2	Insert an ActiveX Control.

3	Import the desired ActiveX control  methods and events.

4	Write the appropriate PL/SQL code to interact with the ActiveX control:

•	Call property accessors.

•	Invoke methods.

•	Respond to events.


Creating an ActiveX control container

  Next Step	  Related Topics

To create an ActiveX Control container:

1	In the Object Navigator, click the plus icon [image] beside the desired block node.

Form Builder expands the block node and displays its subnodes.

2	Click the Items node.

3	Click the Create button [image] in the toolbar.

4	Double-click the object icon next to the newly created item to display the Property Palette.

5	Under the General node, set the Item Type property to ActiveX Control.

6	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign it to a canvas.


Inserting an ActiveX control in a form

  Next Step	  Related Topics

To insert an ActiveX control in a form:

1	In the Layout Editor, select the ActiveX control container.

2	From the pop-up menu (right-click on Windows) choose Insert Object to display the Insert Object dialog box.

3	Click the desired control, then click OK.

4	In the Layout Editor, double-click the ActiveX control container to display the Property Palette.

5	Under the Functional node:

•	Set the OLE Class property; each OLE Class contains a number of controls.

•	Set the desired control and container Properties.


Importing ActiveX control methods and events packages

  Related Topics

To import ActiveX Control methods and events:

1	Choose Program [image] OLE Importer to display the OLE Importer dialog box.

2	Select the desired OLE Class, then select the desired OLE methods and events.

3	Click OK.


Interacting with an ActiveX control

  Related Topics

You can interact with ActiveX controls in many ways:

•	Setting and Getting ActiveX control properties

•	Invoking ActiveX control methods

•	Responding to ActiveX control events


Setting and getting ActiveX control properties

 Restrictions	  Related Topics

There are several ways to set and get ActiveX property values:

•	bind variable syntax

•	property accessors (PL/SQL procedures)

•	control properties dialog from the Property Palette


Setting and Getting ActiveX Control Properties examples restrictions
Setting and getting ActiveX control property restrictions

•	:item('ActXitm').OCX.server_name.property_name does not compile if the server_name is not on your machine.

•	On non-Microsoft Windows platforms, the compiler may give you a warning because ActiveX control property types cannot be determined on the UNIX platform.

•	Your form will not compile if the ActiveX control exports different property names for different languages


ActiveX control properties using bind variable syntax

 Examples

To set and get ActiveX control properties using bind variable syntax:

 Use bind variable syntax to assign or retrieve property values.

For example, :item('block_name.item_name').ocx.server_name.property,

where 	block_name	 is the name of the data block,

item_name	 is the name of the ActiveX control,

server_name	 is the name of the ActiveX server,

property	 is the name of the ActiveX property being accessed.


ActiveX control properties using bind variable syntax examples

 Restrictions

/* Setting an ActiveX control property using bind variable syntax */

:item('ActXitem').OCX.Spindial.spindialctrl.1.Needleposition:=
:item('ActXitem').OCX.Spindial.spindialctrl.1.Needleposition + 1;

ActXitem is the name of the item, Spindial.spindialctrl.1 is the name of the ActiveX control server, and Needleposition is the name of the property.

The following code also works if your system.cursor_item is an ActiveX control:
:form.cursor_item.OCX.spindial.spindialctrl.1.Needlposition :=
:form.cursor_item.OCX.spindial.spindialctrl.1.Needlposition + 1;


ActiveX control properties using property accessors

 Examples

To set and get ActiveX control properties using property accessors:

Use the property accessor functions to get a property value, and use the property accessor procedures to set a property value.


ActiveX control properties using property accessors examples

 Restrictions

/* Getting an ActiveX control property using get accessor */

tblname varchar2;
tblname := table_pkg.TableName(:item('Oblk.Oitm').interface);

table_pkg is the name of the program unit created from the OLE Importer.  TableName is the name of the property accessor. Oblk is the name of the block and Oitm is the name of the item.


Setting ActiveX properties

 Restrictions

To Set ActiveX properties in the Property Palette:

1	In the Object Navigator, double-click the object icon next to the ActiveX Control item to display the Property Palette.

2	Click the Control Properties property.

The Control Property dialog appears.

3	Set the Control Properties accordingly.

4	Click OK.


Invoking ActiveX control methods

 Examples	     Related Topics

You can access methods exposed by an ActiveX control with the program units generated from the OLE Importer.  Call any of the methods in any of the packages available under the Program Units node.

Note:  Some OLE servers such as Microsoft Excel use variant types.  Because many of the methods for these particular servers require the use of variant types, the STANDARD built-in package provides you with the procedures and functions to do the necessary conversion to and from variant types.  The lifetime and scope of a variant type is limited to a trigger; variant memory space is released when a trigger exits.   However, you can extend the lifetime and scope of a variant type by setting the persistent parameter in To_Variant() to TRUE and assigning the results to a global variable.  Global variants must be explicitly destroyed using Destroy_Variant().  Similarly, OLE objects created with Create_OleObj() are global in scope (the persistent parameter defaults to TRUE).  You must explicitly call Release_Obj() to release global objects.


Invoking ActiveX Control Methods examples
Invoking ActiveX control method examples

Example 1

/* Getting a cell value from a Spread Table ActiveX control using the GetCellByColRow method provided in the SpreadTable package */

DECLARE
Cur_Row number;
Cur_Col number;
OLEObj OleObj;

BEGIN
Cur_Row:=SpreadTable.CurrentRow(:ITEM('BLK.ITM').interface);
Cur_Col:=SpreadTable.CurrentCol(:ITEM('BLK.ITM').interface);
OLEObj:=SpreadTable.GetCellByColRow(:ITEM('BLK.ITM').interface,
                                        Cur_Col,
                                        Cur_Row);
END;


Responding to ActiveX control events

 Examples	     Related Topics

ActiveX controls generate events.  Form Builder exposes these events in the events package created from the OLE Importer.  The events are defined by the ActiveX control.  Each event is associated with a PL/SQL procedure defined in the events package.  The procedures are named according to an internal numeric representation as defined by the control.  When the control fires an event, the code in the procedure is automatically executed.  You are responsible for providing the code to respond to the event.  Type directly into the event package body and compile the package.

All event procedures are restricted; that is, go_item cannot be called from within the procedure code.  However, there are instances when the same event may apply to multiple items and a go_item is necessary--this is the unrestricted case.  In the unrestricted case, you need to do the following:  In the On-Dispatch-Trigger (block or form level), call DISPATCH_EVENT(RESTRICTED_ALLOWED).  There is no need to explicitly call the event procedure because it will automatically be called following the On-Dispatch trigger code.

Note: Initialization events for ActiveX controls do not fire in Forms Runtime.  These initialization events are intentionally disabled.  Instead, you can use when-new-item-instance or when-new-record-instance in place of the control's native initialization events.

When an ActiveX control fires an event, there are two ways Forms Runtime can deal with the event: directly call the appropriate restricted procedure provided by any of the events packages available under Program Units node, or call the the ON-DISPATCH-EVENT trigger.

Procedure names are determined by an internal number that represent the corresponding event.  The restricted procedure produced by an event has an application programming interface similar to the following:

PROCEDURE /*Click*/ event4294966696(interface OleObj);

The procedure is created and you are responsible for providing the course of action that should take place within the procedure.  Note that the procedures run in restricted mode.

When calling the event procedure by way of the ON-DISPATCH-EVENT trigger, you can explicitly define whether the procedure is run in restricted or unrestricted mode by using the FORMS4W.DISPATCH_EVENT call.  When defining a restricted procedure, OUT parameters are not observed.


Responding to ActiveX Control Events examples
Responding to ActiveX control event examples

Example 1

/*

The event procedure will be called directly to increase the value of a field when a mouse click event is detected.
*/
PROCEDURE /*Click*/ event4294966696(ocxitem)
BEGIN
:SYSTEM.TRIGGER_ITEM := ocxitem;
:block.value := :block.value + 1;
END;

Example 2

/*

ON-DISPATCH-EVENT trigger
*/
BEGIN
IF SYSTEM.CUSTOM_ITEM_EVENT = 4294966696 THEN
/*when event occurs, allow it to apply to different items */.
FORMS4W.DISPATCH_EVENT(RESTRICTED_ALLOWED);
ELSE
/*run the default, that does not allow applying any other 	item */
FORMS4W.DISPATCH_EVENT(RESTRICTED_UNALLOWED);
ENDIF;
END;


Handling the FORMS_OLE_FAILURE exception

 Examples	     Related Topics

When a failure is detected in handling an ActiveX Control method, an FRM message appears or the FORMS_OLE_FAILURE exception is raised.  When a FORMS_OLE_FAILURE exception is raised, you can get more detailed information regarding the cause of the exception by calling the LAST_OLE_EXCEPTION built-in.


Handling the FORMS_OLE_FAILURE exception examples

Example

/*

Handling the exception raised as a result of calling: Var_To_Number(To_Variant('Jane'));
An exception is raised because Jane is not a number.
*/
DECLARE
ExceptNum number;

BEGIN
ExceptNum := LAST_OLE_EXCEPTION('Excel',
'Range Method Fail',
'Excel.hlp',
110);
END;


Registering ActiveX controls

  Related Topics

You must register all ActiveX controls.  If you install an ActiveX control using the installation program supplied with the ActiveX control, the registration is most likely taken care of by the installation program.

For manual registration of ActiveX controls, use regActiveX32.exe or regsvr32.exe; both are available with Microsoft development tools and from ActiveX control vendors.

Supporting Files

Most ActiveX controls require a supporting DLL such as the Microsoft Foundation Class runtime library, mfc40.dll.  The DLL must be in the \WINDOWS\SYSTEM directory or in the search path.  If the DLL is out of date or missing, your ActiveX control will not register properly.  Most reputable ActiveX control suppliers provide documentation regarding the version and name of the DLLs required; some even supply and install them along with the ActiveX controls.

Moving ActiveX Control Files

At installation, the directories in which the ActiveX control is installed are registered in the Windows Registration Database in Windows 95 and Windows NT, making the ActiveX Control visible to your development environment.  If you move the ActiveX Control to a different directory, or rename the directory, the information in the registry is no longer valid.  If you find it necessary to move the ActiveX Control or rename its directory, use regsrv32.exe or regActiveX.exe utilities provided with most Microsoft development products to re-register the ActiveX in its new location.


Deploying ActiveX controls with your application

  Related Topics

Deploying an application that uses an ActiveX control at runtime requires that you also deploy the ActiveX control.  You must properly register the ActiveX control on the runtime machine.  The supporting DLLs should be copied to the appropriate locations--WINDOWS\SYSTEM folder, WINDOWS folder, or a folder in the DLL search path.

ActiveX controls, whether distributed by third party ActiveX control vendors or bundled with application development tools, may require that you pay additional fees or obtain additional licenses prior to distributing the ActiveX control.


OLE support in Form Builder

  Related Topics

Form Builder provides support for OLE, acting as an OLE container, supporting compound documents and OLE automation.  The OLE container item type creates a container for your OLE object.

Form Builder as an OLE container application offers the following:

•	Embedding and linking of OLE server objects into Form Builder OLE containers.

•	In-place activation of embedded contents in Form Builder OLE containers.

•	Programmatic access to OLE objects, properties, and methods through OLE automation support from PL/SQL.

•	Seamless storage of OLE objects in a database in LONG RAW columns.

An OLE container is an item in Form Builder.  An OLE object is linked to or embedded in an OLE container.  OLE objects can be datasource items or control items.

Form Builder supports OLE in-place activation which allows you to access menus and toolbars from OLE server applications to edit embedded OLE objects while you are in Form Builder.

Form Builder also supports OLE automation.  Using PL/SQL, you can invoke commands and functions that are exposed by OLE servers supporting OLE automation.

From Form Builder, you can save OLE objects to a database, as well as query OLE objects from a database.  OLE objects are saved as LONG RAW columns in the database.  When linked objects are saved, only the image and the link information are retained in the database.  The contents of a linked object remains in a linked source file.  Saving an embedded object retains all the contents of an embedded object in the database.

An example of using OLE in Form Builder is an application that integrates Microsoft Word documents in a form module.  The integration of a form module and Microsoft Word document provides you with access to features from both Form Builder and Microsoft Word.  You can format the Microsoft Word document with any of the text processing features from Microsoft Word, and you can use all of the Form Builder features for displaying and manipulating the data from the database.

The characteristics of an OLE object in Form Builder depends on the properties of the OLE container which determine how OLE objects are activated, displayed, and manipulated.


About embedded and linked objects

  Related Topics

An OLE server application creates OLE objects that are embedded or linked in an OLE container application; OLE containers store and display OLE objects.  Applications can be OLE server applications, OLE container applications, or both.  Form Builder is an OLE container application, and Microsoft Word is an example of an OLE server application.

An embedded OLE object is created by an OLE server application and is embedded in a Form Builder form module.  An embedded object is stored as part of a form module or as a LONG RAW column in a database.  Embedded objects can be queried as OLE container items.

An example of object embedding is to insert a spreadsheet in an OLE container of a form module.  The spreadsheet is stored as part of the form module or as a LONG RAW column in a database; there is no separate source file containing the spreadsheet.

A linked OLE is created by an OLE server application.  A linked object is stored in a separate source file that is created from an OLE server application.  An image representation of the linked object and the information about the location of the linked object's source file is stored in a form module or as a LONG RAW column in a database.  The content of the linked object is not stored as part of a form module or as a LONG RAW column in a database; it is retained in a separate file known as the linked source file.

An example of object linking is to link a word processor document in a form module.  An image of the document appears in the OLE container of the form module and the location of the document is stored as part of the form module or as a LONG RAW column in a database.


About OLE servers and OLE containers

  Related Topics

Applications that support OLE can be OLE servers, OLE containers, or both.  An OLE server application creates OLE objects that are embedded or linked in OLE containers.  Examples of OLE servers are Microsoft Word and Microsoft Excel.

Unlike OLE server applications, OLE container applications do not create documents for embedding and linking.  Instead, OLE container applications provide a place to store, display, and manipulate objects that are created by OLE server applications.  Form Builder is an example of an OLE container application.

Many of the options available for manipulating an OLE object in an OLE container application are determined by the OLE server application.  For instance, options from the OLE popup menu, also known as OLE verbs, are exposed by the OLE server application.  The information contained in the registration database, such as object classes available for linking and embedding, also depends on the OLE server application.


About the registration database

  Related Topics

OLE server applications can create many object classes.  The object classes that an OLE server can create are installed in a registration database.

The registration database stores a set of classes that categorize OLE objects.  The information in the registration database determines the object classes that are available for embedding and linking in OLE containers.  OLE server applications export a set of classes that become members of the registration database.  Each computer has a single registration database.  If the registration database does not already exist when an OLE server application is installed, one is created.

A single OLE server application can add many OLE classes to the registration database.  The process of adding classes to the registration database is transparent and occurs during the installation of an OLE server application.  For instance, when Microsoft Excel is installed, several classes are added to the registration database; some of the classes that are installed in the registration database include Excel Application, Excel Application 5, Excel Chart, Excel Sheet, ExcelMacrosheet, and ExcelWorkSheet.


About OLE activation styles

  Related Topics

An OLE object is activated from a Form Builder OLE container with in-place activation or external activation.  Activating an OLE object allows access to features from the OLE server application that originated the OLE object.  In-place activation and external activation are possible only if the OLE server application that originated the OLE object is accessible.

Both in-place activation and external activation also depend on the OLE activation property settings of the OLE container.  The OLE activation property settings are specified in Form Builder.  If the OLE server application is accessible, the activation property settings of the OLE container determine whether in-place activation or external activation occurs when an embedded OLE object is activated.  Linked objects can only be activated with external activation; in-place activation does not apply to linked objects, even if the OLE In-place Activation property is set to Yes.  Activation of an OLE object is possible in Form Builder and during Forms Runtime.


About In-place Activation

  Related Topics

In-place activation occurs when an OLE container and its embedded object remain in place when activated; Form Builder remains surrounding the OLE container.  In-place activation is available for embedded objects, but it is not available for linked objects.

When an object is activated, the object appears inside a hatched border.  To deactivate in-place activation, click anywhere outside the hatched border.

During in-place activation, some menu options of the OLE server application replace Form Builder menu options.  If the window containing the OLE container has a toolbar, in-place activation also replaces the Form Builder toolbar with the OLE server application toolbar.  Replacing menu options and toolbars provide access to features that are available from the OLE server application.  Form Builder menu options and toolbars reappear when you deactivate in-place activation.


About External Activation

  Related Topics

External activation occurs when an OLE object appears in a separate window that is opened by an object's originating OLE server application.  Because an OLE server application starts up with its own windows, Form Builder menu options and toolbars remain intact during external activation.  External activation is available for both embedded and linked objects.

When an OLE object is activated, the object's originating OLE server application is launched, and the OLE object appears in a separate OLE server application window.  The separate window has the menu options and toolbars of the OLE server application.  To deactivate external activation, you must explicitly exit the OLE server application.

When the contents of a linked source file is modified with external activation, a linked object can be updated manually or automatically.  Manual updates require an explicit instruction for an object to reflect changes from a linked source file.  Automatic updates occur as soon as you modify a linked source file.


About OLE automation

 Examples	     Related Topics

OLE automation allows an OLE server application to expose a set of commands and functions that can be invoked from an OLE container application.  OLE automation provides a way for an OLE container application to use the features of an OLE server application to manipulate an OLE object from the OLE container environment.

In Form Builder, you can use PL/SQL to access any command or function that is exposed by an OLE server application. The STANDARD package provides a PL/SQL Application Programming Interface for creating, manipulating, and accessing the commands and functions.


About OLE Automation examples
OLE automation examples

Example 1

/*

Set the value of a single cell in Microsoft Excel using the automatically generated PL/SQL methods.
*/

DECLARE
/* Create a variable of variant type. */
Variant OleVar;

BEGIN
/* Find the range of the cells you want to interact with */
Variant := EXCEL_WORKSHEET.ole_Range(
                              :CTRL.interface,
                               To_Variant('A1'));

/* Set cell A1 to contain 20 */
EXCEL_RANGE.Value(
           Var_to_Obj(Variant),
           To_Variant('20'));
END;

Example 2

/*

Get the value of a range of cells in Microsoft Excel for populating a PL/SQL table.  The PL/SQL table can be used as a block data source.
*/

DECLARE
TYPE myrec IS RECORD (
    x varchar2(10),
    y varchar2(10),
    z varchar2(10));

TYPE mytable is TABLE OF myrec
    INDEX BY BINARY_INTEGER;

TableXYZ mytable;
Range OleVar;
Value OleVar;

BEGIN
/* Find the range of cells you want to interact with */
Range := EXCEL_WORKSHEET.ole_Range(
                            :CTRL.interface,
                            To_Variant('A1:C3'));

/* Get the value of cells in the range from A1 to C3 */
Value := EXCEL_RANGE.Value(Var_to_Obj(Range));

/* Populate PL/SQL Table; can access cell values using PL/SQL Syntax such as TableXYZ(1).x, TableXYZ(1).y, TableXYZ(2).x, TableXYZ(2).y, etc. */
Var_to_Table(Value,TableXYZ);
END;

Example 3:

/*

Populate a Microsoft Excel worksheet by obtaining values from a PL/SQL table.
*/

DECLARE
TYPE myrec IS RECORD (
    x varchar2(10),
    y varchar2(10),
    z varchar2(10));

TYPE mytable is TABLE OF myrec
    INDEX BY BINARY_INTEGER;

TableXYZ mytable;
TableVals OleVar;

BEGIN
/* Converts PL/SQL table to variant type */
TableVals := To_Variant(TableXYZ);

/* Set Microsoft Excel Worksheet to contain values from PL/SQL table */
Excel_Range.Value(Var_to_Obj(TableVals),TableVals);
END;

Example 4:

/*

Populate a block with a Microsoft Excel Worksheet.  Base the block on the following stored procedure.
*/

/* This example assumes the range of cells specified is valid */

PROCEDURE Excel_to_Block(tablename mytable,
                         excel_range_spec varchar)
DECLARE
Range OleVar;
Value OleVar;

BEGIN
/* Find the range of cells you want to interact with */
Range := Excel_Worksheet.Ole_Range(
                    :excel.interface,
                    To_Variant(excel_range_spec));

/* Get the value of cells in the range excel_range_spec */
Value := Excel_Range.Value(Var_to_Obj(Range));

/* Populate PL/SQL table with values from Microsoft Excel Worksheet */
Var_to_Table(Value,tablename);
END;


About when to embed or link OLE objects

  Related Topics

Whether an OLE object is embedded or linked depends how often an OLE object is updated, how an OLE object is shared, how the source document is accessed, and if there are storage constraints.

Use object embedding when:

•	The object that being embedded does not have to be the most current version of data because updating is performed from within a form module instead of a standalone document.

•	The object does not need to be included in more than one document, so that changes are only necessary in the object embedded in the form module and nowhere else.

•	The source document cannot be accessed if the object is linked.  In this case, only a single form module needs to be maintained and not a form module in addition to the source document.

•	The form module size is not a concern, because with embedding, the size of the form module increases by approximately the size of the embedded object.

Use object linking when:

•	The object being linked has to be the most current version of data because updating is performed from outside a form module on a standalone document.

•	The object needs to be included in more than one document, so that changes affect multiple form modules and other documents.

•	The source document can always be accessed if the object is linked.

•	The form module size is a concern: Linking, unlike embedding, does not increase the size of the form module by the size of the object.


About OLE in Form Builder

  Related Topics

Though OLE objects are active in both the Form Builder and Forms Runtime, the OLE container property values determine OLE functionality at both design-time and runtime.

In Form Builder, you determine the criteria for OLE object activation, representation, and operation by setting the OLE container properties.  For example, when the Show OLE Pop-up Menu property is set to Yes, the OLE popup menu is an option in Form Builder and Forms Runtime.  The OLE popup menu appears when the mouse cursor is in the OLE container and the right mouse button is pressed.  When the Show OLE Popup Menu property is set to No, the OLE pop-up menu is not an option in Forms Runtime. The OLE popup menu can offer an array of operations that you can use with OLE objects.

In Form Builder, you can restrict the object classes for embedding and linking in an OLE container at runtime.  For example, if you specify that the object class of an OLE container is restricted to the ExcelWorkSheet class, only a Microsoft Excel worksheet can be an OLE object in the OLE container.  If no object class restriction is specified, any OLE object that is categorized as an object class in the registration database is a potential OLE object in the OLE container.

When an OLE container is created, the properties associated with the OLE container are initially set to default values.  The OLE container properties are divided into the following three groups of properties:

•	Activation Properties

OLE Activation Style

OLE In-place Activation

OLE Inside-Out Support

•	OLE Popup Menu Properties

OLE Popup Menu Items

Show OLE Popup Menu

•	OLE Tenant Properties

OLE Class

OLE Resize Style

OLE Tenant Aspect

OLE Tenant Types

Show OLE Tenant Type

Activation properties specify whether editing an OLE object is performed with in-place activation or external activation.  OLE popup menu properties determine if an OLE popup menu is available and what options appear on the OLE popup menu.  OLE Tenant Properties specify conditions that are required for an OLE object in an OLE container.

You can manually insert OLE objects in an OLE container from Form Builder. The OLE object that you insert into an OLE container adheres to the OLE container property settings.  Inserting an OLE object into an OLE container from Form Builder initializes the OLE container.  The initialization of an OLE container determines the initial content of the OLE container during Forms Runtime.  During Forms Runtime, any form query from a LONG RAW column of the database to populate the OLE container overwrites the content that is used for initialization purposes.


About OLE in Forms Runtime

  Related Topics

The ability to display and manipulate an object in Forms Runtime is determined by the OLE container properties that are defined in Form Builder.  Forms Runtime attributes include activation style, OLE popup menu options, and OLE tenant properties.

The OLE Tenant Aspect property determines how an OLE object is viewed.  For instance, when the OLE Tenant Aspect property is set to Icon, any OLE object that you insert in the OLE container appears as an icon.

During Forms Runtime, you can manually insert an OLE object into an OLE container (if the properties on the item allow it), or you can query the database for an OLE object to populate the OLE container.  When you manually insert an OLE object during Forms Runtime, the OLE object appears in the OLE container until the record is cleared.  The OLE object that you insert into an OLE container adheres to the OLE container property settings.  For any subsequent record queries, the OLE container appears in a state as defined in Form Builder or populated with an OLE object from the database.

You can also query the database for an OLE object to populate an OLE container.  Each record query populates an OLE container with an OLE object from the database.  A query to the database for an OLE object can only be made for an OLE container item.  An OLE object's data type in the database is LONG RAW.  When queried, an OLE object is displayed according to the property settings of the OLE container.  Similarly, the operations permitted on the OLE object depend on the property settings of the OLE container.  The properties of an OLE container are not saved as part of an OLE object.


OLE Variant Types

The following table lists the OLE variant types, and shows the equivalent Forms Developer VT-TYPE identifier.

OLE-Defined Variant Type	Interpretation in Forms Developer
VT_BLOB	VT_UNKNOWN
VT_BLOB_OBJECT	VT_UNKNOWN
VT_BOOL	Boolean
VT_BSTR	String
VT_BYREF	16384.  This may be added to any type below to indicate "pointer-to"
VT_CARRAY	- unsupported
VT_CF	- unsupported
VT_CLSID	- unsupported
VT_CY	- unsupported
VT_DATE	Date
VT_DISPATCH	OLE object pointer capable of OLE automation calls
VT_EMPTY	Uninitialized member
VT_ERROR	Error field
VT_FILETIME	VT_DATE
VT_HRESULT	VT_ERROR
VT_INT	Integer
VT_I1	Signed one-byte integer
VT_I2	Signed two-byte integer
VT_I4	Signed four-byte integer
VT_I8	- unsupported
VT_LPSTR	VT_BSTR
VT_LPWSTR	VT_BSTR
VT_NULL	Null
VT_PTR	Untyped pointer
VT_R4	Four-byte floating point number
VT_R8	Eight-byte floating point number
VT_STORAGE	VT_UNKNOWN
VT_STORED_OBJECT	VT_UNKNOWN
VT_STREAM	VT_UNKNOWN
VT_STREAMED_OBJECT	VT_UNKNOWN
VT_UINT	Unsigned four-byte integer
VT_UI1	Unsigned one-byte integer
VT_UI2	Unsigned two-byte integer
VT_UI4	Unsigned four-byte integer
VT_UNKNOWN	OLE object pointer
VT_USERDEFINED	Typed data
VT_VARIANT	Any type


Array Types for OLE Support

  Related Topics

Array Type or Subtype	Definition
VT_TYPE	A subtype in the form of a PLS_INTEGER. For more information, see OLE Variant Types.
OLE_SAFEARRAYBOUND	A record containing two fields: • count PLS_INTEGER.   Count is the number of items in the array. • lbound PLS_INTEGER.   The default value for lbound is 1.
OLE_SAFEARRAYBOUNDS	A table containing records of type OLE_SAFEARRAYBOUND. Table access is INDEX BY BINARY_INTEGER. This array type is used in the CREATE_VAR and GET_VAR_BOUNDS functions.
ITEMS_IN_BLOCK	A table having the form VARCHAR2(30). Table access is INDEX BY BINARY_INTEGER.


Specifiers for OLE Arrays

  Examples	  Related Topics

Several of the built-ins that work with OLE arrays provide a parameter for indicating which parts of the array are to be used.  In the discussions of those built-ins, the parameter is denoted as arrspec.

If you don't include an arrspec parameter, the entire array will be processed.

Syntax

The parameter can have multiple sub-parameters, which correspond to the dimensions of the OLE array:

'nth dimension,...  3rd dimension, 2nd dimension, 1st dimension'

The arrspec parameter is coded as a character string, of type VARCHAR2.  The string must be enclosed in single quotes, with the sub-parameters separated by commas and spaces.  (Note that the sub-parameters must be in positional order.)

Specify as many of these sub-parameters as necessary to identify the part of the array you want selected.

Sub-parameters that identify specific instances of a dimension must be  integer constants.

The sub-parameters for the 2nd and 1st dimensions can also be the keywords ROW and CONSTANT.  Used in the 2nd dimension position, ROW specifies that all rows should be selected.  Used in the 1st dimension position, COLUMN indicates that all columns should be selected.

An arrspec value of '7, 3' would select the 3rd instance dimension of the 7th row.

An arrspec value of '7, COLUMN' would select the entire 7th row (all columns of the 7th row).

An arrspec value of '2, 6, 9' would select the 2nd sub-element of the 9th column of the 6th row.

An arrspec value of '5' would select the 5th element of a one-dimensional array.

Controlling the Fill Pattern

When a function moves data between an OLE array and a PL/SQL table, processing is normally done in row-into-row fashion.  However, you can override this and specify a different mapping.  This is done by using the sub-parameter keywords COLUMN and ROW in a special manner.

As explained above, when used in their normal positions in the sub-parameter list, these keywords indicate that all instances of that dimension are to be selected.  However, the keywords can also be used outside of their normal positions to indicate a different fill pattern for that position's dimension.

Used in other than its normal position, the COLUMN keyword's relative position in the sub-parameter list identifies a dimension of the array, and indicates that that dimension is to be placed in the column dimension of the receiving table.  Similarly, the ROW keyword indicates that whatever array dimension is denoted by the keyword's relative sub-parameter position is to be placed in the row dimension of the receiving table.

For example, in an arrspec of 'COLUMN, ROW', the COLUMN keyword is in the 2nd dimension position (the row position), and the ROW keyword is in the 1st dimension position (the column position).  This arrspec would result in moving the array's 2nd dimension (its rows) into the receiving table's columns.  And it would place the array's first dimension (its columns) into the receiving table's rows.

Table Sizes

The size of the receiving PL/SQL table should be sufficient to accommodate the selected array data.  This is especially important if columns will be rotated to become rows.


Specifiers for OLE arrays more examples

More complex selections and manipulations are also possible.

For example, to select all of the 4th sub-elements of all the columns in the 5th row, an arrspec of '4, 5, COLUMN' or '4, 5, ROW' would be used.  The 4 indicates the 4th instance of the 3rd dimension of the array (this dimension is here called sub-elements).  The 5 indicates the 5th instance of the 2nd dimension (that is, the 5th row).  The COLUMN or ROW keyword indicates two things.  First, that all of the contents of the array's first dimension (its columns) should be selected.  Secondly, it indicates the column's receiving position or orientation in the table.

If we specify '4, 5, COLUMN', then the normal mapping is followed.  In this case, the 4th sub-element of each column in the 5th row in the array is moved into the 4th sub-element position of each column in the 5th row of the receiving table.  There is no re-orientation.

If we specify '4, 5, ROW', then again the 4th sub-element of each column in the 5th row in the array is selected.  However, because we have specified the keyword ROW in the column position in the sub-parameter list, the data will be moved into the first position of each row of the receiving table.  (More specifically, into the 4th sub-element positions of each first column position in as many rows as it takes to receive the original number of columns in the array.)


Adding an OLE object to your application

  Related Topics

To add an OLE object to your application:

1	Create an OLE container .

2	Embed or link the OLE object.

3	Import OLE methods and properties .

4	Write the appropriate PL/SQL code to interact with the OLE Automation methods.


Creating an OLE container

Next Step 	  Related Topics

To create an OLE container:

1	In the Object Navigator, click the plus icon [image] beside the desired block node.

Form Builder expands the block node and displays its subnodes.

2	Click the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon next to the newly created item to display the Property Palette.

5	Under the General node, set the Item Type property to OLE container.

6	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign it to a canvas.


About embedding an OLE object

Next Step 	  Related Topics

An OLE object that you manually insert into an OLE container from Form Builder initializes the OLE container for Forms Runtime.  If you manually insert an OLE object during Forms Runtime, the OLE object appears in the OLE container until the record is cleared.  For any subsequent record queries, the OLE container appears in a state as defined in the Form Builder or populated with an OLE object from the database.

Access to the Insert Object option on the OLE popup menu is necessary for manual insertion of an OLE object into an OLE container.  Create a new OLE object to insert into an OLE container, or embed an OLE object from an existing file into an OLE container.


Embedding a new OLE object

  Related Topics

To embed a new OLE object:

1	Create an OLE container with the OLE Tenant Types property set to Any or Embedded.

Make sure the Show OLE Popup Menu property is set to Yes, and the Insert Object item of the OLE Popup Menu Items is set to Display and Enable.

2	In the Layout Editor, move the mouse cursor on the OLE container and access the OLE popup menu (right -click on Microsoft Windows platforms).  From the OLE popup menu, choose Insert Object.

The Insert Object dialog box appears.

3	From the Insert Object dialog box, click Create New.

4	Choose an object type from the Object Type list

5	Click OK.

The OLE server application starts up.

6	Create the object in the OLE server application.

7	Exit the OLE server application.


Embedding an OLE object from an existing file

  Related Topics

To embed an object from an existing file:

1	Create an OLE container with the OLE Tenant Types property set to Any or Embedded.

Make sure the Show OLE Popup Menu property is set to Yes, and the Insert Object item of the OLE Popup Menu Items is set to Display and Enable.

2	In the Layout Editor, move the mouse cursor on the OLE container and access the OLE popup menu (right -click on Microsoft Windows platforms).  From the OLE popup menu, choose Insert Object.

The Insert Object dialog box appears.

3	From the Insert Object dialog box, click Create from File.

4	Specify the file name of the object to embed.

You can use the Browse option to help locate the file.  If you use the Browse option, click OK from the Browse dialog after selecting a file.

5	After you determine the file name, click OK on the Insert Object dialog.


Linking an OLE object

  Next Step	  Restrictions 	  Related Topics

To link an object:

1	Create an OLE container with the OLE Tenant Types property set to Any or Linked.

Make sure the Show OLE Popup Menu property is set to Yes, and the Insert Object item of the OLE Popup Menu Items is set to Display and Enable.

2	In the Layout Editor, move the mouse cursor on the OLE container and access the OLE popup menu (right -click on Microsoft Windows platforms).  From the OLE popup menu, choose Insert Object.

The Insert Object dialog box appears.

3	From the Insert Object dialog box, click Create from File.

4	Specify the file name of the object to link.

You can use the Browse option to help locate the file.  If you use the Browse option, click OK from the Browse dialog box after selecting a file.

5	In the Insert Object dialog, check the Link check box.

6	Click OK.


Linking an OLE object restrictions

Because linked objects contain information about the location of an OLE object, you can only link OLE objects from existing files.  You cannot create an object when you are trying to link, because the location of new objects is not yet established.


About displaying an OLE object

  Related Topics

You can display an OLE object as any of the following:

•	the content of the OLE object as it appears in the OLE server

•	an icon of the OLE server application that originated the OLE object

•	a thumbnail preview of the OLE object that appears in a reduced view

Specify the display option with the OLE Tenant Aspect property.  Or, choose Display As Icon on the Insert Object dialog box of the OLE popup menu.  When you select Display As Icon, an icon appears in the OLE container to represent the embedded or linked object.  Display As Icon overrides the value of the OLE Tenant Aspect property.


Displaying an object as an icon using Display As Icon

  Related Topics

To display an object as an icon using Display As Icon:

1	Create an OLE container.

2	From the Insert Object dialog box, determine the object to embed or link.

3	Check the Display As Icon check box.

When you select Display As Icon, the current icon that represents the OLE server application that originated the OLE object for insertion is displayed in the Insert Object dialog box.  Icon selections can be changed by selecting Change Icon.

The Change Icon dialog shows the current icon selection and the default icon selection.  You can change both the current and default icon selections by selecting the desired icon.  Different icons are stored in different files.  After selecting an icon, click OK from the Change Icon dialog box.

4	Click OK.


About editing an OLE object

  Related Topics

Edit an embedded or linked object by activating the OLE object.  This causes the OLE server application that originated the OLE object to start up.

When the OLE server application is not available on your computer, editing can be performed by permanently or temporarily converting the OLE object to another format.

When an embedded object is modified in Form Builder, changes are immediately reflected in the form module, because embedded objects are stored as part of the form module.

When a source file of a linked object is modified, the linked object is updated automatically or manually.  Automatic updates reflect modifications to an OLE object immediately.  Manual updates require that you select Update Now from the Links dialog after the modification of a document.

Automatic or manual updating is set in the Links dialog.  Through the Links dialog, you can open a linked source file for editing, change links of an OLE object to link to other sources, or  break links completely.  Broken links leave only a fixed image of an OLE object in an OLE container; no information about the location of the linked source file is retained.


Updating a linked object automatically

  Related Topics

To update a linked object automatically:

1	In the Layout Editor, click on the OLE container.

Make sure the Show OLE Popup Menu property is set to Yes, and the Links item of the OLE Popup Menu Items is set to Display and Enable.

2	Move the mouse cursor on the OLE container and access the OLE popup menu (right -click on Microsoft Windows platforms), choose Links.

The Links dialog box appears.  The Links dialog box shows the current update option for the selected linked source file.

3	Select the Automatic radio button that appears next to the Update label.

4	Click Close.


Opening an OLE linked source file

  Related Topics

To open a linked source file from the Links dialog box:

1	In the Layout Editor, click on the OLE container.

Make sure the Show OLE Popup Menu property is set to Yes, and the Links item of the OLE Popup Menu Items is set to Display and Enable.

2	Move the mouse cursor on the OLE container and access the OLE popup menu (right -click on Microsoft Windows platforms), choose Links.

The Links dialog box appears.  The Links dialog box shows the current links to source files.

3	Select a link to a source file.

4	Click Open Source.

The OLE server application that originated the linked source file starts up.

5	Edit the linked source file.

6	Exit the OLE server application to save your changes and return to Form Builder.


Changing an existing OLE link

  Related Topics

To change an existing link from one linked source file to another:

1	In the Layout Editor, click on the OLE container.

Make sure the Show OLE Popup Menu property is set to Yes, and the Links item of the OLE Popup Menu Items is set to Display and Enable.

2	Move the mouse cursor on the OLE container and access the OLE popup menu (right -click on Microsoft Windows platforms), choose Links.

The Links dialog box appears.  The Links dialog shows the current links to source files.

3	Select a link to a source file, and click Change Source.

The Change Source dialog box appears.

4	Select another linked source file.

5	Click OK to establish a new link.

6	Click Close.


Breaking a link to a linked source file

  Related Topics

To break a link to a linked source file:

1	In the Layout Editor, click on the OLE container.

Make sure the Show OLE Popup Menu property is set to Yes, and the Links item of the OLE Popup Menu Items is set to Display and Enable.

2	Move the mouse cursor on the OLE container and access the OLE popup menu (right -click on Microsoft Windows platforms), choose Links.

The Links dialog box appears.  The Links dialog shows the current links to source files.

3	Choose a link to a source file, and click Break Link.  Notice the link is removed from the Links dialog box.

4	Click Close.


About converting OLE objects

  Related Topics

Convert an OLE object from one format to another in order to edit the OLE object when the OLE server application that originated the object is not available.

The convert option is available on the Object submenu of the OLE popup menu.  Either permanently convert the object to a new format, or temporarily convert the object to a new format for editing.

Because linked object source files are not part of a form module, you cannot convert linked objects from one format to another in Form Builder.  You can only convert linked objects from the source level.


Converting an embedded OLE object

To convert an embedded OLE object:

1	In the Layout Editor, click on the OLE container.

Make sure the Show OLE Popup Menu property is set to Yes, and the Object item of the OLE Popup Menu Items is set to Display and Enable.

2	With the mouse cursor on the OLE container access the OLE pop-up menu (right-click on Windows).  From the OLE popup menu, choose Object [image] Convert.

The Convert dialog box appears which shows the current object type and the conversion possibilities.

3	Select a conversion object type.

4	Choose either Convert To or Activate As.  Convert To permanently alters the format of the object to the selected object type.  Activate As is a temporary conversion that  provides a method for editing or viewing an object when an OLE server application cannot be found.

5	Click OK.


Importing OLE library interfaces

  Related Topics

To import OLE methods:

1	Choose Program [image] Import OLE Library Interfaces…

The Import OLE Library Interfaces dialog box appears.

2	Select an OLE Class.

The methods and events packages appear for the selected OLE class.

3	Ctrl-click on the desired methods packages.

4	Check the Methods check box to import the method.

5	Check the Properties check box to import the get and set accessors for properties.

6	Click OK.

In the Object Navigator, notice the newly created packages under the Program Units node.

Note: OLE objects export interfaces that expose methods.  Form Builder imports the methods in PL/SQL.  You can interact with OLE objects in the native Form Builder environment.


Interacting with OLE objects

  Related Topics

You can interact with OLE Objects in two ways:

•	Setting and Getting OLE properties

•	Invoking OLE methods


Setting and getting OLE properties

 Restrictions	 Examples	     Related Topics

There are two ways to set and get OLE property values:

•	bind variable syntax

•	property accessors (PL/SQL procedures)

To set and get OLE properties using bind variable syntax:

Use the :item('block_name.item_name').ocx.server_name.property bind variable syntax to assign or retrieve property values, where block_name is the name of the data block, item_name is the name of the ActiveX control item, server_name is the name of the ActiveX server object, and property is the name of the ActiveX control property being accessed.

To set and get OLE properties using property accessors:

Use the property accessor functions to get a property value, and use the property accessor procedures to set a property value.


Setting and getting OLE properties examples

 Restrictions

Example 1

/* Setting an OLE property using bind variable syntax */

:item('OLEitem').OCX.SpreadSheet.CellForeGroundColor:=
:item('OLEitem').OCX.SpreadSheet.CellForeGroundColor + 1;

OLEitem is the name of the item, SpreadSheet is the name of the OLE control server, and CellForeGroundColor is the name of the property.

Example 2

/* Setting an OLE property using set accessor */

Variant OleVar;
Variant := EXCEL_WORKSHEET.ole_Range(:CTRL.interface,
To_variant('A1'));

EXCEL_WORKSHEET is the name of the package created from the OLE Importer.  OLE_RANGE is the name of the property accessor.


Setting and getting OLE properties examples restrictions

•	:item('OLEitm').OCX.server_name.property_name does not compile if the server_name is not on your machine.

•	On platforms other than Microsoft Windows, the compiler may give you a warning because OLE property types cannot be determined on the UNIX platform.

•	Your form will not compile if the OLE object exports different property names for different languages.

•	The OLE property being accessed cannot be of type variant.


About invoking OLE automation methods

 Examples	     Related Topics

Access methods exposed by an OLE object with the program units generated from the OLE Importer.  Call any of the methods provided in any of the packages available under the Program Units node.

Note:  Some OLE servers such as Microsoft Excel use variant types.  Because many of the methods for these particular servers require the use of variant types, the STANDARD built-in package provides you with the procedures and functions to do the necessary conversion to and from variant types.  The lifetime and scope of a variant type is limited to a trigger; variant memory space is released when a trigger exits.   However, you can extend the lifetime and scope of a variant type by setting the persistent parameter in To_Variant() to TRUE and assigning the results to a global variable.  Global variants must be explicitly destroyed using Destroy_Variant().  Similarly, OLE objects created with Create_OleObj() are global in scope (the persistent parameter defaults to TRUE).  You must explicitly call Release_Obj() to release global objects.


Invoking OLE automation methods examples

Example 1

/*

Set the value of a single cell in Microsoft Excel using the automatically generated PL/SQL methods.
*/

DECLARE
/* Create a variable of variant type. */
Variant OleVar;

BEGIN
/* Find the range of the cells you want to interact with */
Variant := EXCEL_WORKSHEET.ole_Range(
                              :CTRL.interface,
                               To_Variant('A1'));

/* Set cell A1 to contain 20 */
EXCEL_RANGE.Value(
           Var_to_Obj(Variant),
           To_Variant('20'));
END;


About the Open API

  Related Topics

The Form Builder Open API is an advanced feature for C/C++ developers that have a thorough understanding of Form objects and their relations.

Form Builder exposes an open application programming interface to create or modify form modules (.fmb files).  The open application programming interface (Open API) offers the power and flexibility to create or modify form modules in a non-interactive environment.  It is designed with the C/C++ programmer in mind.


About Open API header files

  Related Topics

A set of C header files provides the Open APIs.  There is one C header file per object type.  Here is a list of Form Builder object types and the corresponding header files:

Attached Library	d2falb.h
Alert	d2falt.h
Block	d2fblk.h
Canvas	d2fcnv.h
Data Source Argument	d2fdsa.h
Data Source	d2fdsc.h
Editor	d2fedt.h
Form Module	d2ffmd.h
Form Parameter	d2ffpm.h
Graphics Object	d2fgra.h
Item	d2fitm.h
LOV column mapping	d2flcm.h
LOV	d2flov.h
Menu Module	d2fmmd.h
Menu Item	d2fmni.h
Menu	d2fmnu.h
Menu Parameter	d2fmpm.h
Generic Object	d2fob.h
Object Group	d2fobg.h
Object Group Child	d2fogc.h
Object Library	d2folb.h
Object Library Tab	d2folt.h
Program Unit	d2fpgu.h
Property Class	d2fppc.h
Property	d2fpr.h
Record Group	d2frcg.h
Record Group Column Specification	d2frcs.h
Radio Button	d2frdb.h
Relation	d2frel.h
Report	d2frpt.h
Tab Page	d2ftbp.h
Trigger	d2ftrg.h
Visual Attribute	d2fvat.h
Window	d2fwin.h

Here is a group of C header files that do not correspond to specific Form Builder objects, but contain information relevant to using the Open API:

API context manipulation functions	d2fctx.h
Lists all objects and all properties	d2fdef.h
Utilities for manipulating properties	d2fpr.h
Errors	d2ferr.h
Native ORACLE types	oratypes.h


About Open API objects and relations

  Related Topics

This diagram illustrates Form Builder objects and their relations.


Open API properties by object

  Related Topics

Every Form Builder Open API object includes a set of Open API properties.

API Properties by Object

Alerts

Attached Libraries

Blocks

Canvases

Data Source Arguments

Data Source Columns

Editors

Form Modules

Form Parameters

Graphics

Items

List of Values Column Mapping

List of Values

Menu Objects

Menu Modules

Menu Items

Menu Parameters

Objects (Generic Objects)

Object Groups

Object Group Children

Object Libraries

Program Units

Property Classes

Radio Buttons

Record Groups

Record Group Column Specification

Relation Objects

Report Objects

Tab Pages

Triggers

Visual Attributes

Windows


Alert object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_ALT_MSG	Message
D2FP_ALT_STY	Alert Style
D2FP_BACK_COLOR	Background Color
D2FP_BTN_1_LBL	Button 1 Label
D2FP_BTN_2_LBL	Button 2 Label
D2FP_BTN_3_LBL	Button 3 Label
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_DFLT_ALT_BTN	Default Alert Button
D2FP_FILL_PAT	Fill Pattern
D2FP_FONT_NAM	Font Name
D2FP_FONT_SIZE	Font Size
D2FP_FONT_SPCING	Font Spacing
D2FP_FONT_STY	Font Style
D2FP_FONT_WGHT	Font Weight
D2FP_FORE_COLOR	Foreground Color
D2FP_LANG_DIR	Language Direction
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SOURCE	D2FP_SOURCE
D2FP_TITLE	Title
D2FP_VAT_NAM	Visual Attribute Group
D2FP_VAT_OBJ	D2FP_VAT_OBJ
D2FP_WHITE_ON_BLACK	White on Black


Attached library object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_LIB_LOC	PL/SQL Library Location
D2FP_LIB_SRC	PL/SQL Library Source
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_PREVIOUS	D2FP_PREVIOUS


Block object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_BACK_COLOR	Background Color
D2FP_BLK_DESCRIPTION	Data Block Description
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_DB_BLOCK	Database Block
D2FP_DEL_ALLOWED	Delete Allowed
D2FP_DEL_PROC_NAM	Delete Procedure Name
D2FP_DML_ARY_SIZ	DML Array Size
D2FP_DML_DAT_NAM	DML Data Target Name
D2FP_DML_DAT_TYP	DML Data Target Type
D2FP_ENFRC_COL_SECURITY	Enforce Column Security
D2FP_ENFRC_PRMRY_KEY	Enforce Primary Key
D2FP_FILL_PAT	Fill Pattern
D2FP_FONT_NAM	Font Name
D2FP_FONT_SIZE	Font Size
D2FP_FONT_SPCING	Font Spacing
D2FP_FONT_STY	Font Style
D2FP_FONT_WGHT	Font Weight
D2FP_FORE_COLOR	Foreground Color
D2FP_INSRT_ALLOWED	Insert Allowed
D2FP_INSRT_PROC_NAM	Insert Procedure Name
D2FP_ITEM	D2FP_ITEM
D2FP_KEY_MODE	Key Mode
D2FP_LANG_DIR	Language Direction
D2FP_LOCK_MODE	Locking Mode
D2FP_LOCK_PROC_NAM	Lock Procedure Name
D2FP_LST_IN_BLK_MNU	Listed In Block Menu
D2FP_MAX_QRY_TIME	Maximum Query Time
D2FP_MAX_RECS_FETCHED	Max_Records_Fetched
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NAVIGATION_STY	Navigation Style
D2FP_NEXT	D2FP_NEXT
D2FP_NXT_NAVIGATION_BLK_OBJ	D2FP_NXT_NAVIGATION_BLK_OBJ
D2FP_NXT_NAVIGATION_BLK_NAM	Next Navigation Block
D2FP_OPT_HINT	Optimizer Hint
D2FP_ORDER_BY_CLAUSE	ORDER BY Clause
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PRECOMP_SUMM	D2FP_PRECOMP_SUMM
D2FP_PREV_NAVIGATION_BLK_NAM	Previous Navigation Block
D2FP_PREV_NAVIGATION_BLK_OBJ	D2FP_PREV_NAVIGATION_BLK_OBJ
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_QRY_ALL_RECS	Query All Record
D2FP_QRY_ALLOWED	Query Allowed
D2FP_QRY_DAT_SRC_NAM	Query Data Source Name
D2FP_QRY_DAT_SRC_TYP	Query Data Source Type
D2FP_REC_ORNT	Record Orientation
D2FP_REC_VAT_GRP_NAM	Current Record Visual Attribute Group
D2FP_REC_VAT_GRP_OBJ	D2FP_REC_VAT_GRP_OBJ
D2FP_RECS_BUFFERED_COUNT	Number or Records Buffered
D2FP_RECS_DISP_COUNT	Number of Records Displayed
D2FP_RECS_FETCHED_COUNT	Records_to_Fetch
D2FP_REL	D2FP_REL
D2FP_REV_DIR	Reverse Direction
D2FP_SCRLBR_CNV_NAM	Scroll Bar Canvas
D2FP_SCRLBR_CNV_OBJ	D2FP_SCRLBR_CNV_OBJ
D2FP_SCRLBR_HGT	Scroll Bar Height
D2FP_SCRLBR_ORNT	Scroll Bar Orientation
D2FP_SCRLBR_TBP_NAM	Scroll Bar Tab Page
D2FP_SCRLBR_TBP_OBJ	D2FP_SCRLBR_TBP_OBJ
D2FP_SCRLBR_WID	Scroll Bar Width
D2FP_SCRLBR_X_POS	Scroll Bar X Position
D2FP_SCRLBR_Y_POS	Scroll Bar Y Position
D2FP_SHOW_SCRLBR	Show Scroll Bar
D2FP_SNGL_REC	Single Record
D2FP_SOURCE	D2FP_SOURCE
D2FP_TRIGGER	D2FP_TRIGGER
D2FP_UPDT_ALLOWED	Update Allowed
D2FP_UPDT_CHANGED_COLS	Update Changed Columns Only
D2FP_UPDT_PROC_NAM	Update Procedure Name
D2FP_VAT_NAM	Visual Attribute Group
D2FP_VAT_OBJ	D2FP_VAT_OBJ
D2FP_WHERE_CLAUSE	WHERE Clause
D2FP_WHITE_ON_BLACK	White on Black


Canvas object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_BACK_COLOR	Background Color
D2FP_BEVEL	Bevel
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_CNV_TYP	Canvas Type
D2FP_COMMENT	Comments
D2FP_FILL_PAT	Fill Pattern
D2FP_FONT_NAM	Font Name
D2FP_FONT_SIZE	Font Size
D2FP_FONT_SPCING	Font Spacing
D2FP_FONT_STY	Font Style
D2FP_FONT_WGHT	Font Weight
D2FP_FORE_COLOR	Foreground Color
D2FP_GRAPHIC	D2FP_GRAPHIC
D2FP_HEIGHT	Width/Height
D2FP_LANG_DIR	Language Direction
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_POPUP_MNU_NAM	Popup Menu
D2FP_POPUP_MNU_OBJ	D2FP_POPUP_MNU_OBJ
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_RAISE_ON_ENT	Raise On Entry
D2FP_SHOW_HORIZ_SCRLBR	Show Horizontal Scroll Bar
D2FP_SHOW_VERT_SCROLL	Show Vertical Scroll Bar
D2FP_SOURCE	D2FP_SOURCE
D2FP_TAB_ATT_EDGE	Tab Attachment Edge
D2FP_TAB_PAGE	Tab Page
D2FP_TAB_STY	Tab Style
D2FP_VAT_NAM	Visual Attribute Group
D2FP_VAT_OBJ	D2FP_VAT_OBJ
D2FP_VISIBLE	Visible
D2FP_VPRT_HGT	Viewport Height
D2FP_VPRT_WID	Viewport Width
D2FP_VPRT_X_POS	Viewport X Position
D2FP_VPRT_X_POS_ON_CNV	Viewport X Position on Canvas
D2FP_VPRT_Y_POS	Viewport Y Position
D2FP_VPRT_Y_POS_ON_CNV	Viewport Y Position on Canvas
D2FP_WHITE_ON_BLACK	White on Black
D2FP_WIDTH	Width/Height
D2FP_WND_NAM	Window
D2FP_WND_OBJ	D2FP_WND_OBJ


Datasource argument object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_DSA_MODE	D2FP_DSA_MODE
D2FP_DSA_NAM	D2FP_DSA_NAM
D2FP_DSA_TYP	D2FP_DSA_TYP
D2FP_DSA_TYPE_NAM	D2FP_DSA_TYP_NAM
D2FP_DSA_VAL	D2FP_DSA_VAL
D2FP_NEXT	D2FP_NEXT
D2FP_PREVIOUS	D2FP_PREVIOUS


Datasource column object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_DSC_LEN	D2FP_DSC_LEN
D2FP_DSC_MANDATORY	D2FP_DSC_MANDATORY
D2FP_DSC_NAM	D2FP_DSC_NAM
D2FP_DSC_PRECISION	D2FP_DSC_PRECISION
D2FP_DSC_SCALE	D2FP_DSC_SCALE
D2FP_DSC_TYP	D2FP_DSC_TYPE
D2FP_NEXT	D2FP_NEXT
D2FP_PREVIOUS	D2FP_PREVIOUS


Editor object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_BACK_COLOR	Background Color
D2FP_BTM_TTL	Bottom Title
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_FILL_PAT	Fill Pattern
D2FP_FONT_NAM	Font Name
D2FP_FONT_SIZE	Font Size
D2FP_FONT_SPCING	Font Spacing
D2FP_FONT_STY	Font Style
D2FP_FONT_WGHT	Font Weight
D2FP_FORE_COLOR	Foreground Color
D2FP_HEIGHT	Width/Height
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SHOW_HORZ_SCRLBR	Show Horizontal Scroll Bar
D2FP_SHOW_VERT_SCRLBR	Show Vertical Scroll Bar
D2FP_SOURCE	D2FP_SOURCE
D2FP_TITLE	Title
D2FP_VAT_NAM	Visual Attribute Group
D2FP_VAT_OBJ	D2FP_VAT_OBJ
D2FP_WHITE_ON_BLACK	White on Black
D2FP_WIDTH	Width/Height
D2FP_WRAP_STY	Wrap Style
D2FP_X_POS	X Position/Y Position
D2FP_Y_POS	X Position/Y Position


Form module object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_ALERT	D2FP_ALERT
D2FP_ATT_LIB	D2FP_ATT_LIB
D2FP_BLOCK	D2FP_BLOCK
D2FP_CANVAS	D2FP_CANVAS
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_CONSOLE_WIN	Console Window
D2FP_CRSR_MODE	Cursor Mode
D2FP_EDITOR	Editor
D2FP_FORM_PARAM	D2FP_FORM_PARAM
D2FP_FRST_NAVIGATION_BLK_NAM	First Navigation Block
D2FP_FRST_NAVIGATION_BLK_OBJ	D2FP_FIRST_NAVIGATION_BLK_OBJ
D2FP_HORZ_TLBR_CNV	Horizontal Toolbar Canvas
D2FP_INIT_MNU	Initial Menu
D2FP_INTERACTION_MODE	Interaction Mode
D2FP_ISOLATION_MODE	Isolation Mode
D2FP_LANG_DIR	Language Direction
D2FP_LOV	List of Values
D2FP_MAX_QRY_TIME	Maximum Query Time
D2FP_MAX_RECS_FETCHED	Max_Records_Fetched
D2FP_MENU	D2FP_MENU
D2FP_MNU_MOD	Menu Module
D2FP_MNU_ROLE	Menu Module Roles
D2FP_MNU_SRC	Menu Source
D2FP_MNU_STY	Menu Style
D2FP_MOUSE_NAVIGATION_LMT	Mouse Navigation Limit
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OBJ_GRP	D2FP_OBJ_GRP
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_PROG_UNIT	D2FP_PROG_UNIT
D2FP_PROP_CLASS	Property Class
D2FP_REC_GRP	Record Group
D2FP_REC_VAT_GRP_NAM	Current Record Visual Attribute Group
D2FP_REC_VAT_GRP_OBJ	D2FP_REC_VAT_GRP_OBJ
D2FP_REPORT	D2FP_REPORT
D2FP_SVPNT_MODE	Savepoint Mode
D2FP_TITLE	Title
D2FP_TRIGGER	D2FP_TRIGGER
D2FP_USE_3D_CNTRLS	Use 3D Controls
D2FP_VALIDATION_UNIT	Validation Unit
D2FP_VERT_TLBR_CNV	Vertical Toolbar Canvas
D2FP_VIS_ATTR	D2FP_VIS_ATTR
D2FP_WINDOW	Window


Form parameter object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_MAX_LEN	Maximum Length
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PARAM_DAT_TYPE	Parameter Data Type
D2FP_PARAM_INIT_VAL	Parameter Initial Value
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SOURCE	D2FP_SOURCE


Graphics object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_ALLOW_EXPANSION	Allow Expansion
D2FP_ALLOW_MLT_LIN_PRMPTS	Allow Multi-Line Prompts
D2FP_ALLOW_STRT_ATT_PRMPTS	Allow Start-Attached Prompts
D2FP_ALLOW_TOP_ATT_PRMPTS	Allow Top-Attached Prompts
D2FP_ARROW_STY	Line Arrow Style
D2FP_BEVEL	Bevel
D2FP_CAP_STY	Object Edge Cap Style
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_CLIP_HGT	Height of Clipping Rectangle
D2FP_CLIP_WID	Width of Clipping Rectangle
D2FP_CLIP_X_POS	X-origin of Clipping Rectangle
D2FP_CLIP_Y_POS	Y-origin of Clipping Rectangle
D2FP_CLOSED	Polygon Flag/Arc Closure
D2FP_CORNER_RADIUS_X	X-origin of Radius for Corner of Rounded Rectangle
D2FP_CORNER_RADIUS_Y	Y-origin of Radius for Corner of Rounded Rectangle
D2FP_CSTM_SPCING	Custom Spacing for Text Object
D2FP_DASH_STY	Dash Style for Object Edge
D2FP_DISP_QLTY	Display Quality
D2FP_DIST_BTWN_RECS	Distance Between Records
D2FP_DITHER	Graphics Dithers Image
D2FP_EDGE_BACK_COLOR	Object Edge Background Color
D2FP_EDGE_FORE_COLOR	Object Edge Foreground Color
D2FP_END_ANGLE	End Angle
D2FP_FIXED_BOUNDING_BX	Fixed Size of Object Bounding Box
D2FP_FONT_SCALEABLE	Point Size Scales with Object
D2FP_FRAME_ALIGN	Frame Alignment
D2FP_FRAME_TTL	Frame Title
D2FP_FRAME_TTL_ALIGN	Frame Title Alignment
D2FP_FRAME_TTL_BACK_COLOR	Frame Title Background Color
D2FP_FRAME_TTL_FILL_PAT	Frame Title Fill Pattern
D2FP_FRAME_TTL_FONT_NAM	Frame Title Font Name
D2FP_FRAME_TTL_FONT_SIZ	Frame Title Font Size
D2FP_FRAME_TTL_FONT_SPCING	Frame Title Font Spacing
D2FP_FRAME_TTL_FONT_STY	Frame Title Font Style
D2FP_FRAME_TTL_FONT_WGHT	Frame Title Font Weight
D2FP_FRAME_TTL_FORE_COLOR	Frame Title Foreground Color
D2FP_FRAME_TTL_OFST	Frame Title Offset
D2FP_FRAME_TTL_SPCING	Frame Title Spacing
D2FP_FRAME_TTL_VAT_NAM	Frame Title Visual Attribute Group
D2FP_FRAME_TTL_VAT_OBJ	D2FP_FRAME_TTL_VAT_OBJ
D2FP_GRA_DIST_BTWN_RECS	Graphics Distance Between Records
D2FP_GRA_FONT_NAM	Graphics Font Name
D2FP_GRA_FONT_SIZ	Graphics Font Size
D2FP_GRA_FONT_STY	Graphics Font Style
D2FP_GRA_TEXT	Graphics Text
D2FP_GRAPHIC	D2FP_GRAPHIC
D2FP_GRAPHICS_TYP	Graphics Object Type
D2FP_HEIGHT	Width/Height
D2FP_HORZ_JST	Horizontal Justification of Text Object
D2FP_HORZ_MARGN	Horizontal Margin
D2FP_HORZ_OBJ_OFST	Horizontal Object Offset
D2FP_HORZ_ORGN	Horizontal Position Relative to Origin
D2FP_INVISIBLE	Text Invisible
D2FP_JOIN_STY	Join Style of Objects Edge
D2FP_LANG_DIR	Language Direction
D2FP_LAYOUT_DATA_BLK_NAM	Layout Data Block
D2FP_LAYOUT_STY	Layout Style
D2FP_LIN_SPCING	Line Spacing
D2FP_LIN_WID	Line Width
D2FP_MAX_OBJS	Maximum Objects Per Line
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_POINT	Font Point Size
D2FP_RECS_DISP_COUNT	Number of Records Displayed
D2FP_ROTATION_ANGLE	Rotation Angle
D2FP_SCRLBR_ALIGN	Scroll Bar Alignment
D2FP_SCRLBR_WID	Scroll Bar Width
D2FP_SHRINKWRAP	Shrinkwrap
D2FP_SNGL_OBJ_ALIGN	Single Object Align
D2FP_SOURCE	D2FP_SOURCE
D2FP_STRT_ANGLE	Start Angle
D2FP_STRT_PRMPT_ALIGN	Start Prompt Alignment
D2FP_STRT_PRMPT_OFST	Start Prompt Offset
D2FP_TBP_NAM	D2FP_TBP_NAM
D2FP_TBP_OBJ	D2FP_TBP_OBJ
D2FP_TOP_PRMPT_ALIGN	Top Prompt Alignment
D2FP_TOP_PRMPT_OFST	Top Prompt Offset
D2FP_TTL_READING_ORDR	Title Reading Order
D2FP_UPDT_LAYOUT	Update Layout
D2FP_VERT_FILL	Vertical Fill
D2FP_VERT_JST	Vertical Justification
D2FP_VERT_MARGN	Vertical Margin
D2FP_VERT_OBJ_OFST	Vertical Object Offset
D2FP_VERT_ORGN	Vertical Position Relative to Origin
D2FP_WIDTH	Width/Height
D2FP_WRAP_TXT	Wrap Text
D2FP_X_POS	X Position/Y Position
D2FP_Y_POS	X Position/Y Position


Item object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_ACCESS_KEY	Access Key
D2FP_AUDIO_CHNNLS	Audio Channels
D2FP_AUTO_HINT	Display Hint Automatically
D2FP_AUTO_SKP	Auto Skip
D2FP_BACK_COLOR	Background Color
D2FP_BEVEL_STY	Bevel
D2FP_CALC_MODE	Calculation Mode
D2FP_CASE_INSENSITIVE_QRY	Case Insensitive Query
D2FP_CASE_RSTRCTION	Case Restriction
D2FP_CHK_BX_OTHER_VALS	Check Box Mapping of Other Values
D2FP_CHKED_VAL	Checked
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_CMPRSSION_QLTY	Compression_Quality
D2FP_CNV_NAM	Canvas
D2FP_CNV_OBJ	D2FP_CNV_OBJ
D2FP_COL_NAM	Column Name
D2FP_COMM_MODE	Communication Mode
D2FP_COMMENT	Comments
D2FP_COMPRESS	Compress
D2FP_CONCEAL_DATA	Conceal Data
D2FP_COPY_VAL_FROM_ITM	Copy Value from Item
D2FP_DAT_SRC_BLK	Data Source Block
D2FP_DAT_SRC_X_AXS	Data Source X Axis
D2FP_DAT_SRC_Y_AXS	Data Source Y Axis
D2FP_DAT_TYP	Data Type
D2FP_DB_ITM	Database Item
D2FP_DFLT_BTN	Default Button
D2FP_DISP_QLTY	Display Quality
D2FP_DIST_BTWN_RECS	Distance Between Records
D2FP_EDT_NAM	Editor
D2FP_EDT_OBJ	D2FP_EDT_OBJ
D2FP_EDT_X_POS	Editor X Position, Editor Y Position
D2FP_EDT_Y_POS	Editor X Position, Editor Y Position
D2FP_ENABLED	Enabled
D2FP_EXEC_MODE	Execution Mode
D2FP_FILL_PAT	Fill Pattern
D2FP_FIXED_LEN	Fixed Length
D2FP_FLNAM	File_Name
D2FP_FMT_MSK	Format Mask
D2FP_FONT_NAM	Font Name
D2FP_FONT_SIZE	Font Size
D2FP_FONT_SPCING	Font Spacing
D2FP_FONT_STY	Font Style
D2FP_FONT_WGHT	Font Weight
D2FP_FORE_COLOR	Foreground Color
D2FP_FORMULA	Formula
D2FP_HEIGHT	Width/Height
D2FP_HIGHEST_ALLOWED_VAL	Highest Allowed Value/Lowest Allowed Value
D2FP_HINT	Hint
D2FP_ICON_FLNAM	Icon Filename
D2FP_ICONIC	Iconic
D2FP_IMG_DPTH	Image Depth
D2FP_IMG_FMT	Image Format
D2FP_INIT_KBRD_DIR	Initial Keyboard Direction
D2FP_INIT_VAL	Initial Value
D2FP_INSRT_ALLOWED	Insert Allowed
D2FP_ITM_TYP	Item Type
D2FP_ITMS_DISP	Number of Items Displayed
D2FP_JUSTIFICATION	Justification
D2FP_KBRD_NAVIGABLE	Keyboard Navigable
D2FP_KEEP_CRSR_POS	Keep Cursor Position
D2FP_LABEL	Label
D2FP_LANG_DIR	Language Direction
D2FP_LOCK_REC	Lock Record
D2FP_LOV_NAM	List X Position
D2FP_LOV_OBJ	D2FP_LOV_OBJ
D2FP_LOV_X_POS	List of Values
D2FP_LOV_Y_POS	List Y PositionLOVPOSITY
D2FP_LOWEST_ALLOWED_VAL	Highest Allowed Value/Lowest Allowed Value
D2FP_LST_ELEMENT_COUNT	List Element Count
D2FP_LST_STY	List Style
D2FP_MAX_LEN	Maximum Length
D2FP_MLT_LIN	Multi-Line
D2FP_MODULE	D2FP_MODULE
D2FP_MOUSE_NAVIGATE	Mouse Navigate
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_NXT_NAVIGATION_ITM_OBJ	D2FP_NXT_NAVIGATION_ITM_OBJ
D2FP_NXT_NAVIGATION_ITM_NAM	Next Navigation Item
D2FP_ACTIVEX_CLASS	OLE Class
D2FP_ACTIVEX_VAL_PROP	Control Properties
D2FP_OLE_ACT_STY	OLE Activation Style
D2FP_OLE_CLASS	OLE Class
D2FP_OLE_IN_PLACE_ACT	OLE In-place Activation
D2FP_OLE_INSD_OUT_SUPPORT	OLE Inside-Out Support
D2FP_OLE_POPUP_MNU_ITMS	OLE Pop Up Menu Items
D2FP_OLE_RESIZ_STY	OLE Resize Style
D2FP_OLE_SHOW_POP_UP_MNU	OLE Show Pop Up Menu
D2FP_OLE_SHOW_TNNT_TYP	Show OLE Tenant Type
D2FP_OLE_TNNT_ASPCT	OLE Tenant Aspect
D2FP_OLE_TNNT_TYP	OLE Tenant Types
D2FP_OTHER_VALS	Mapping of Other Values
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_POPUP_MNU_NAM	Pop Up Menu
D2FP_POPUP_MNU_OBJ	D2FP_POPUP_MNU_OBJ
D2FP_POPUP_VA_OBJ	D2FP_POPUP_VA_OBJ
D2FP_PREV_NAVIGATION_ITM_NAM	Previous Navigation Item Name
D2FP_PREV_NAVIGATION_ITM_OBJ	D2FP_PREV_NAVIGATION_ITM_OBJ
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_PRMPT	Prompt
D2FP_PRMPT_ALIGN	Prompt Alignment
D2FP_PRMPT_ALIGN_OFST	Prompt Alignment Offset
D2FP_PRMPT_ATT_EDGE	Prompt Attachment Edge
D2FP_PRMPT_ATT_OFST	Prompt Attachement Offset
D2FP_PRMPT_BACK_COLOR	Prompt Background Color
D2FP_PRMPT_DISP_STY	Prompt Display Style
D2FP_PRMPT_FILL_PAT	Prompt Fill Pattern
D2FP_PRMPT_FONT_NAM	Prompt Font Name
D2FP_PRMPT_FONT_SIZ	Prompt Font Size
D2FP_PRMPT_FONT_SPCING	Prompt Font Spacing
D2FP_PRMPT_FONT_STY	Prompt Font Style
D2FP_PRMPT_FONT_WGHT	Prompt Font Weight
D2FP_PRMPT_FORE_COLOR	Prompt Foreground Color
D2FP_PRMPT_JST	Prompt Justification
D2FP_PRMPT_READING_ORDR	Prompt Reading Order
D2FP_PRMPT_VAT_NAM	Prompt Visual Attribute Group
D2FP_PRMPT_VAT_OBJ	D2FP_PRMPT_VAT_OBJ
D2FP_PRMRY_KEY	Primary Key
D2FP_QRY_ALLOWED	Query Allowed
D2FP_QRY_LEN	Query Length
D2FP_QRY_ONLY	Query Only
D2FP_RAD_BUT	D2FP_RAD_BUT
D2FP_READING_ORDR	Reading Order
D2FP_REC_VAT_GRP_NAM	Current Record Visual Attribute Group
D2FP_REC_VAT_GRP_OBJ	D2FP_REC_VAT_GRP_OBJ
D2FP_RENDERED	Rendered
D2FP_REQUIRED	Required
D2FP_SHOW_FAST_FWD	Show Fast Forward Button
D2FP_SHOW_HORZ_SCRLBR	Show Horizonatal Scrollbar
D2FP_SHOW_PALETTE	Show Palette
D2FP_SHOW_PLAY	Show Play Button
D2FP_SHOW_REC	Show Record Button
D2FP_SHOW_REWIND	Show Rewind Button
D2FP_SHOW_SLIDER	Show Slider
D2FP_SHOW_TIME	Show Time Indicator
D2FP_SHOW_VERT_SCRLBR	Show Vertical Scroll Bar
D2FP_SHOW_VOLUME	Show Volume Control
D2FP_SIZING_STY	Sizing Style
D2FP_SND_FMT	Sound Format
D2FP_SND_QLTY	Sound Quality
D2FP_SOURCE	D2FP_SOURCE
D2FP_SUMM_BLK_NAM	Summarized Block
D2FP_SUMM_FUNC	Summarized Function
D2FP_SUMM_ITM_NAM	Summarized Item
D2FP_SYNC_ITM_NAM	Synchronize with Item
D2FP_SYNC_ITM_OBJ	D2FP_SYNC_ITM_OBJ
D2FP_TBP_NAM	D2FP_TBP_NAM
D2FP_TBP_OBJ	D2FP_TBP_OBJ
D2FP_TOOLTIP	Tooltip
D2FP_TOOLTIP_VAT_GRP	Tooltip Visual Attribute Group
D2FP_TRIGGER	D2FP_TRIGGER
D2FP_UNCHKED_VAL	Value When Unchecked
D2FP_UPDT_ALLOWED	Update Allowed
D2FP_UPDT_COMMIT	Update Commit
D2FP_UPDT_IF_NULL	Update Only if NULL
D2FP_UPDT_QRY	Update Query
D2FP_VALIDATE_FROM_LIST	Validate From List
D2FP_VAT_NAM	Visual Attribute Group
D2FP_VAT_OBJ	D2FP_VAT_OBJ
D2FP_VISIBLE	Visible
D2FP_WHITE_ON_BLACK	White on Black
D2FP_WIDTH	Width/Height
D2FP_WRAP_STY	Wrap Style
D2FP_X_POS	X Position/Y Position
D2FP_Y_POS	X Position/Y Position


LOV column mapping object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_DISP_WID	Display Width
D2FP_NAME	Name
D2FP_RTRN_ITM	Return Item
D2FP_TITLE	Title


List of values (LOV) object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_AUTO_COL_WID	Automatic Column Width
D2FP_AUTO_DISP	Automatic Display
D2FP_AUTO_POS	Automatic Position
D2FP_AUTO_RFRSH	Automatic Refresh
D2FP_AUTO_SKP	Automatic Skip
D2FP_AUTO_SLCT	Automatic Select
D2FP_BACK_COLOR	Back Color
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COL_MAP	Column Mapping Properties
D2FP_COMMENT	Comments
D2FP_FILL_PAT	Fill Pattern
D2FP_FLTR_BEFORE_DISP	Filter Before Display
D2FP_FONT_NAM	Font Name
D2FP_FONT_SIZE	Font Size
D2FP_FONT_SPCING	Font Spacing
D2FP_FONT_STY	Font Style
D2FP_FONT_WGHT	Font WeightFONTWGT
D2FP_FORE_COLOR	Foreground Color
D2FP_HEIGHT	Width/Height
D2FP_LANG_DIR	Language Direction
D2FP_LST_TYP	List Type
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OLD_LOV_TXT	Old LOV Text
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_REC_GRP_NAM	Record Group
D2FP_REC_GRP_OBJ	D2FP_REC_GRP_OBJ
D2FP_SOURCE	D2FP_SOURCE
D2FP_TITLE	Title
D2FP_VAT_NAM	Visual Attribute Group
D2FP_VAT_OBJ	D2FP_VAT_OBJ
D2FP_WHITE_ON_BLACK	White on Black
D2FP_WIDTH	Width/Height
D2FP_X_POS	X Position/Y Position
D2FP_Y_POS	X Position/Y Position


Menu object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_BTM_TTL	Bottom Title
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_MNU_ITM	Menu Item Type
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SOURCE	D2FP_SOURCE
D2FP_SUB_TTL	Subtitle
D2FP_TEAR_OFF_MNU	Tear-Off Menu
D2FP_TITLE	Title


Menu module object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_ATT_LIB	D2FP_ATT_LIB
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_MAIN_MNU	Main Menu
D2FP_MENU	D2FP_MENU
D2FP_MNU_DESCRIPTION	Menu Description
D2FP_MNU_DRCTRY	Menu Directory
D2FP_MNU_FLNAM	Menu Filename
D2FP_NAME	Name
D2FP_OBJ_GRP	D2FP_OBJ_GRP
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PROP_CLASS	Property Class
D2FP_SHARE_LIB	Share Library with Form
D2FP_SHORT_NAM	Short Name
D2FP_STRTUP_CODE	Startup Code
D2FP_USE_SECURITY	Use Security


Menu item object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COM_TXT	Command Text
D2FP_COM_TYP	Command Type
D2FP_COMMENT	Comments
D2FP_DISP_NO_PRIV	Display without Privilege
D2FP_ENABLED	Enabled
D2FP_FONT_NAM	Font Name
D2FP_FONT_SIZE	Font Size
D2FP_FONT_SPCING	Font Spacing
D2FP_FONT_STY	Font Style
D2FP_FONT_WGHT	Font Weight
D2FP_HINT	Hint
D2FP_HLP_DESCRIPTION	Help
D2FP_ICON_FLNAM	Icon Filename
D2FP_ICON_IN_MNU	Iconic
D2FP_KBRD_ACC	Keyboard Accelerator
D2FP_LABEL	Label
D2FP_MAGIC_ITM	Magic Item
D2FP_MNU_ITM_CODE	D2FP_MNU_ITM_CODE
D2FP_MNU_ITM_RAD_GRP	Menu Item Radio Group
D2FP_MNU_ITM_TYP	Menu Item Type
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SOURCE	D2FP_SOURCE
D2FP_SUB_MNU_NAM	D2FP_SUB_MNU_NAM
D2FP_SUB_MNU_OBJ	D2FP_SUB_MNU_OBJ
D2FP_VAT_NAM	Visual Attribute Group
D2FP_VAT_OBJ	D2FP_VAT_OBJ
D2FP_VISIBLE	Visible
D2FP_VSBL_IN_HORZ_MNU_TLBR	Visible in Horizontal/Vertical Menu Toolbar
D2FP_VSBL_IN_MENU	Visible in Menu
D2FP_VSBL_IN_VERT_MNU_TLBR	Visible in Horizontal/Vertical Menu Toolbar


Menu parameter object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_ASSOC_MENUS_COUNT	D2FP_ASSOC_MENUS_COUNT
D2FP_ASSOC_MNUS	Associated Menus
D2FP_CASE_RSTRCTION	Case Restriction
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_CONCEAL_DATA	Conceal Data
D2FP_FIXED_LEN	Fixed Length
D2FP_HINT	Hint
D2FP_LABEL	Label
D2FP_MAX_LEN	Maximum Length
D2FP_MNU_PARAM_INIT_VAL	Menu Parameter Initial Value
D2FP_NAME	Name
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_REQUIRED	Required


Object (generic object) API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_ACCESS_KEY
Access Key
D2FP_ALERT
D2FP_ALERT
D2FP_ALLOW_EXPANSION
Allow Expansion
D2FP_ALLOW_MLT_LIN_PRMPTS
Allow Multi-Line Prompts
D2FP_ALLOW_STRT_ATT_PRMPTS
Allow Start-Attached Prompts
D2FP_ALLOW_TOP_ATT_PRMPTS
Allow Top-Attached Prompts
D2FP_ALT_MSG
Message
D2FP_ALT_STY
Alert Style
D2FP_ARROW_STY
Line Arrow Style
D2FP_ASSOC_MENUS_COUNT
D2FP_ASSOC_MENUS_COUNT
D2FP_ASSOC_MNUS
Associated Menus
D2FP_ATT_LIB
D2FP_ATT_LIB
D2FP_AUDIO_CHNNLS
Audio Channels
D2FP_AUTO_COL_WID
Automatic Column Width
D2FP_AUTO_DISP
Automatic Display
D2FP_AUTO_HINT
Display Hint Automatically
D2FP_AUTO_POS
Automatic Position
D2FP_AUTO_QRY
Automatic Query
D2FP_AUTO_RFRSH
Automatic Refresh
D2FP_AUTO_SKP
Automatic Skip
D2FP_AUTO_SLCT
Automatic Select
D2FP_BACK_COLOR
Background Color
D2FP_BEVEL
Bevel
D2FP_BTN_1_LBL
Button 1 Label
D2FP_BTN_2_LBL
Button 2 Label
D2FP_BTN_3_LBL
Button 3 Label
D2FP_CALC_MODE
Calculation Mode
D2FP_CANVAS
D2FP_CANVAS
D2FP_CAP_STY
Object Edge Cap Style
D2FP_CASE_INSENSITIVE_QRY
Case Insensitive Query
D2FP_CASE_RSTRCTION
Case Restriction
D2FP_CHK_BX_OTHER_VALS
Check Box Mapping of Other Values
D2FP_CHKED_VAL
Checked
D2FP_CLIENT_INFO
D2FP_CLIENT_INFO
D2FP_CLIP_HGT
Height of Clipping Rectangle
D2FP_CLIP_WID
Width of Clipping Rectangle
D2FP_CLIP_X_POS
X-origin of Clipping Rectangle
D2FP_CLIP_Y_POS
Y-origin of Clipping Rectangle
D2FP_CLOSED
Polygon Flag/Arc Closure
D2FP_CLS_ALLOWED
Close Allowed
D2FP_CMPRSSION_QLTY
Compression Quality
D2FP_CNV_NAM
Canvas
D2FP_CNV_OBJ
D2FP_CNV_OBJ
D2FP_CNV_TYP
Canvas Type
D2FP_COL_DAT_TYP
D2FP_COL_DAT_TYP
D2FP_COL_MAP
Column Mapping Properties
D2FP_COL_NAM
Column Name
D2FP_COL_SPEC
Column Specifications
D2FP_COL_VALS_COUNT
D2FP_COL_VALS_COUNT
D2FP_COM_TXT
Command Text
D2FP_COM_TYP
Command Type
D2FP_COMM_MODE
Communication Mode
D2FP_COMMENT
Comments
D2FP_COMPRESS
Compress
D2FP_CONCEAL_DATA
Conceal Data
D2FP_CONSOLE_WIN
Console Window
D2FP_COPY_VAL_FROM_ITM
Copy Value from Item
D2FP_CORNER_RADIUS_X
X-origin of Radius for Corner of Rounded Rectangle
D2FP_CORNER_RADIUS_Y
Y-origin of Radius for Corner of Rounded Rectangle
D2FP_CRSR_MODE
Cursor Mode
D2FP_CSTM_SPCING
Custom Spacing for Text Object
D2FP_DASH_STY
Dash Style for Object Edge
D2FP_DAT_SRC_BLK
Data Source Block
D2FP_DAT_SRC_X_AXS
Data Source X Axis
D2FP_DAT_SRC_Y_AXS
Data Source Y Axis
D2FP_DAT_TYP
Data Type
D2FP_DB_BLOCK
Database Block
D2FP_DB_ITM
Database Item
D2FP_DEFERRED
Deferred
D2FP_DEL_ALLOWED
Delete Allowed
D2FP_DEL_PROC_NAM
Delete Procedure Name
D2FP_DEL_REC
Delete Record Behavior
D2FP_DETAIL_BLK
Detail Block
D2FP_DFLT_ALT_BTN
Default Alert Button
D2FP_DFLT_BTN
Default Button
D2FP_DISP_IN_KBRD_HLP
Display in Keyboard Help
D2FP_DISP_NO_PRIV
Display without Privilege
D2FP_DISP_QLTY
Display Quality
D2FP_DISP_WID
Display Width
D2FP_DIST_BTWN_RECS
Distance Between Records
D2FP_DITHER
Graphics Dithers Image
D2FP_DML_ARY_SIZ
DML Array Size
D2FP_DML_DAT_NAM
DML Data Target Name
D2FP_DML_DAT_TYP
DML Data Target Type
D2FP_DSA_MODE
D2FP_DSA_MODE
D2FP_DSA_NAM
D2FP_DSA_NAM
D2FP_DSA_TYP
D2FP_DSA_TYP
D2FP_DSA_TYPE_NAM
D2FP_DSA_TYP_NAM
D2FP_DSA_VAL
D2FP_DSA_VAL
D2FP_DSC_LEN
D2FP_DSC_LEN
D2FP_DSC_MANDATORY
D2FP_DSC_MANDATORY
D2FP_DSC_NAM
D2FP_DSC_NAM
D2FP_DSC_PRECISION
D2FP_DSC_PRECISION
D2FP_DSC_SCALE
D2FP_DSC_SCALE
D2FP_DSC_TYP
D2FP_DSC_TYP
D2FP_EDGE_BACK_COLOR
Object Edge Background Color
D2FP_EDGE_FORE_COLOR
Object Edge Foreground Color
D2FP_EDITOR
Editor
D2FP_EDT_NAM
Editor
D2FP_EDT_OBJ
D2FP_EDT_OBJ
D2FP_EDT_X_POS
Editor X Position, Editor Y Position
D2FP_EDT_Y_POS
Editor X Position, Editor Y Position
D2FP_ENABLED
Enabled
D2FP_END_ANGLE
End Angle
D2FP_ENFRC_COL_SECURITY
Enforce Column Security
D2FP_ENFRC_PRMRY_KEY
Enforce Primary Key
D2FP_EXEC_HIERARCHY
Execution Style
D2FP_EXEC_MODE
Execution Mode
D2FP_FILL_PAT
Fill Pattern
D2FP_FIRE_IN_QRY
Fire in Enter-Query Mode
D2FP_FIXED_BOUNDING_BX
Fixed Size of Object Bounding Box
D2FP_FIXED_LEN
Fixed Length
D2FP_FLNAM
File_Name
D2FP_FLTR_BEFORE_DISP
Filter Before Display
D2FP_FMT_MSK
Format Mask
D2FP_FONT_NAM
Font Name
D2FP_FONT_SCALEABLE
Point Size Scales with Object
D2FP_FONT_SIZE
Font Size
D2FP_FONT_SPCING
Font Spacing
D2FP_FONT_STY
Font Style
D2FP_FONT_WGHT
Font Weight
D2FP_FORE_COLOR
Foreground Color
D2FP_FORM_PARAM
D2FP_FORM_PARAM
D2FP_FORMULA
Formula
D2FP_FRAME_ALIGN
Frame Alignment
D2FP_FRAME_TTL
Frame Title
D2FP_FRAME_TTL_ALIGN
Frame Title Alignment
D2FP_FRAME_TTL_BACK_COLOR
Frame Title Background Color
D2FP_FRAME_TTL_FILL_PAT
Frame Title Fill Pattern
D2FP_FRAME_TTL_FONT_NAM
Frame Title Font Name
D2FP_FRAME_TTL_FONT_SIZ
Frame Title Font Size
D2FP_FRAME_TTL_FONT_SPCING
Frame Title Font Spacing
D2FP_FRAME_TTL_FONT_STY
Frame Title Font Style
D2FP_FRAME_TTL_FONT_WGHT
Frame Title Font Weight
D2FP_FRAME_TTL_FORE_COLOR
Frame Title Foreground Color
D2FP_FRAME_TTL_OFST
Frame Title Offset
D2FP_FRAME_TTL_SPCING
Frame Title Spacing
D2FP_FRAME_TTL_VAT_NAM
Frame Title Visual Attribute Group
D2FP_FRAME_TTL_VAT_OBJ
D2FP_FRAME_TTL_VAT_OBJ
D2FP_FRST_NAVIGATION_BLK_NAM
First Navigation Block
D2FP_FRST_NAVIGATION_BLK_OBJ
D2FP_FIRST_NAVIGATION_BLK_OBJ
D2FP_GRA_FONT_NAM
Graphics Font Name
D2FP_GRA_FONT_SIZ
Graphics Font Size
D2FP_GRA_FONT_STY
Graphics Font Style
D2FP_GRA_TEXT
Graphics Text
D2FP_GRAPHIC
D2FP_GRAPHIC
D2FP_GRAPHICS_TYP
Graphics Object Type
D2FP_HEIGHT
Width/Height
D2FP_HIDE_ON_EXIT
Hide on Exit
D2FP_HIGHEST_ALLOWED_VAL
Highest Allowed Value/Lowest Allowed Value
D2FP_HINT
Hint
D2FP_HLP_DESCRIPTION
Help
D2FP_HORZ_JST
Horizontal Justification of Text Object
D2FP_HORZ_MARGN
Horizontal Margin
D2FP_HORZ_OBJ_OFST
Horizontal Object Offset
D2FP_HORZ_ORGN
Horizontal Position Relative to Origin
D2FP_HORZ_TLBR_CNV
Horizontal Toolbar Canvas
D2FP_HTB_CNV_NAME
Horizontal Toolbar Canvas
D2FP_ICON_FLNAM
Icon Filename
D2FP_ICON_IN_MNU
Iconic
D2FP_ICONIC
Iconic
D2FP_IMG_DPTH
Image Depth
D2FP_IMG_FMT
Image Format
D2FP_INHRT_MNU
Inherit Menu
D2FP_INIT_KBRD_DIR
Initial Keyboard Direction
D2FP_INIT_MNU
Initial Menu
D2FP_INIT_VAL
Initial Value
D2FP_INSRT_ALLOWED
Insert Allowed
D2FP_INSRT_PROC_NAM
Insert Procedure Name
D2FP_INTERACTION_MODE
Interaction Mode
D2FP_ISOLATION_MODE
Isolation Mode
D2FP_ITEM
D2FP_ITEM
D2FP_ITM_TYP
Item Type
D2FP_ITMS_DISP
Number of Items Displayed
D2FP_JOIN_COND
Join Condition
D2FP_JOIN_STY
Join Style of Objects Edge
D2FP_JUSTIFICATION
Justification
D2FP_KBRD_ACC
Keyboard Accelerator
D2FP_KBRD_HLP_TXT
Keyboard Help Description
D2FP_KBRD_NAVIGABLE
Keyboard Navigable
D2FP_KBRD_STATE
Keyboard State
D2FP_KEEP_CRSR_POS
Keep Cursor Position
D2FP_KEY_MODE
Key Mode
D2FP_LABEL
Label
D2FP_LANG_DIR
Language Direction
D2FP_LAYOUT_DATA_BLK_NAM
Layout Data Block
D2FP_LAYOUT_STY
Layout Style
D2FP_LIB_LOC
PL/SQL Library Location
D2FP_LIB_SRC
PL/SQL Library Source
D2FP_LIN_SPCING
Line Spacing
D2FP_LIN_WID
Line Width
D2FP_LOCK_MODE
Locking Mode
D2FP_LOCK_PROC_NAM
Lock Procedure Name
D2FP_LOCK_REC
Lock Record
D2FP_LOV
List of Values
D2FP_LOV_NAM
List X Position
D2FP_LOV_OBJ
D2FP_LOV_OBJ
D2FP_LOV_X_POS
List of Values
D2FP_LOV_Y_POS
List Y Position
D2FP_LOWEST_ALLOWED_VAL
Highest Allowed Value/Lowest Allowed Value
D2FP_LST_ELEMENT_COUNT
List Element Count
D2FP_LST_IN_BLK_MNU
Listed In Block Menu
D2FP_LST_STY
List Style
D2FP_LST_TYP
List Type
D2FP_MAGIC_ITM
Magic Item
D2FP_MAIN_MNU
Main Menu
D2FP_MAX_LEN
Maximum Length
D2FP_MAX_OBJS
Maximum Objects Per Line
D2FP_MAX_QRY_TIME
Maximum Query Time
D2FP_MAX_RECS_FETCHED
Max_Records_Fetched
D2FP_MAXIMIZE_ALLOWED
Maximize Allowed
D2FP_MENU
D2FP_MENU
D2FP_MINIMIZE_ALLOWED
Minimized Allowed
D2FP_MINIMIZE_TTL
Minimize Title
D2FP_MLT_LIN
Multi-Line
D2FP_MNU_DESCRIPTION
Menu Description
D2FP_MNU_DRCTRY
Menu Directory
D2FP_MNU_FLNAM
Menu Filename
D2FP_MNU_ITM
Menu Item Type
D2FP_MNU_ITM_CODE
D2FP_MNU_ITM_CODE
D2FP_MNU_ITM_RAD_GRP
Menu Item Radio Group
D2FP_MNU_ITM_TYP
Menu Item Type
D2FP_MNU_MOD
Menu Module
D2FP_MNU_PARAM
D2FP_MNU_PARAM
D2FP_MNU_PARAM_INIT_VAL
Menu Parameter Initial Value
D2FP_MNU_ROLE
Menu Module Roles
D2FP_MNU_SRC
Menu Source
D2FP_MNU_STY
Menu Style
D2FP_MODAL
Modal
D2FP_MODULE
D2FP_MODULE
D2FP_MOUSE_NAVIGATE
Mouse Navigate
D2FP_MOUSE_NAVIGATION_LMT
Mouse Navigation Limit
D2FP_MV_ALLOWED
Move Allowed
D2FP_NAME
Name
D2FP_NAVIGATION_STY
Navigation Style
D2FP_NEXT
D2FP_NEXT
D2FP_NXT_NAVIGATION_BLK_OBJ
D2FP_NXT_NAVIGATION_BLK_OBJ
D2FP_NXT_NAVIGATION_BLK_NAM
Next Navigation Block
D2FP_NXT_NAVIGATION_ITM_OBJ
D2FP_NXT_NAVIGATION_ITM_OBJ
D2FP_NXT_NAVIGATION_ITM_NAM
Next Navigation Item
D2FP_OBJ_GRP
D2FP_OBJ_GRP
D2FP_OBJ_GRP_CHILD_REAL_OBJ
D2FP_OBJ_GRP_CHILD_REAL_OBJ
D2FP_ACTIVEX_CLASS
OLE Class
D2FP_ACTIVEX_VAL_PROP
Control Properties
D2FP_OG_CHILD
D2FP_OG_CHILD
D2FP_OLD_LOV_TXT
Old LOV Text
D2FP_OLE_ACT_STY
OLE Activation Style
D2FP_OLE_CLASS
OLE Class
D2FP_OLE_IN_PLACE_ACT
OLE In-place Activation
D2FP_OLE_INSD_OUT_SUPPORT
OLE Inside-Out Support
D2FP_OLE_POPUP_MNU_ITMS
OLE Pop Up Menu Items
D2FP_OLE_RESIZ_STY
OLE Resize Style
D2FP_OLE_SHOW_POP_UP_MNU
OLE Show Pop Up Menu
D2FP_OLE_SHOW_TNNT_TYP
Show OLE Tenant Type
D2FP_OLE_TNNT_ASPCT
OLE Tenant Aspect
D2FP_OLE_TNNT_TYP
OLE Tenant Types
D2FP_OPT_HINT
Optimizer Hint
D2FP_ORDER_BY_CLAUSE
ORDER BY Clause
D2FP_OTHER_VALS
Mapping of Other Values
D2FP_OWNER
D2FP_OWNER
D2FP_PAR_FLNAM
D2FP_PAR_FLNAM
D2FP_PAR_FLPATH
D2FP_PAR_FLPATH
D2FP_PAR_MODSTR
D2FP_PAR_MODSTR
D2FP_PAR_MODTYP
D2FP_PAR_MODTYPE
D2FP_PAR_MODULE
D2FP_PAR_MODULE
D2FP_PAR_NAM
D2FP_PAR_NAME
D2FP_PARAM_DAT_TYP
Parameter Data Type
D2FP_PARAM_INIT_VAL
Parameter Initial Value
D2FP_PGU_TXT
D2FP_PGU_TXT
D2FP_POPUP_MNU_NAM
Pop Up Menu
D2FP_POPUP_MNU_OBJ
D2FP_POPUP_MNU_OBJ
D2FP_POPUP_VA_OBJ
D2FP_POPUP_VA_OBJ
D2FP_PRECOMP_SUMM
D2FP_PRECOMP_SUMM
D2FP_PREV_NAVIGATION_BLK_NAM
Previous Navigation Block
D2FP_PREV_NAVIGATION_BLK_OBJ
D2FP_PREV_NAVIGATION_BLK_OBJ
D2FP_PREV_NAVIGATION_ITM_NAM
Previous Navigation Item Name
D2FP_PREV_NAVIGATION_ITM_OBJ
D2FP_PREV_NAVIGATION_ITM_OBJ
D2FP_PREVIOUS
D2FP_PREVIOUS
D2FP_PRMPT
Prompt
D2FP_PRMPT_ALIGN
Prompt Alignment
D2FP_PRMPT_ALIGN_OFST
Prompt Alignment Offset
D2FP_PRMPT_ATT_EDGE
Prompt Attachment Edge
D2FP_PRMPT_ATT_OFST
Prompt Attachement Offset
D2FP_PRMPT_BACK_COLOR
Prompt Background Color
D2FP_PRMPT_DISP_STY
Prompt Display Style
D2FP_PRMPT_FILL_PAT
Prompt Fill Pattern
D2FP_PRMPT_FONT_NAM
Prompt Font Name
D2FP_PRMPT_FONT_SIZ
Prompt Font Size
D2FP_PRMPT_FONT_SPCING
Prompt Font Spacing
D2FP_PRMPT_FONT_STY
Prompt Font Style
D2FP_PRMPT_FONT_WGHT
Prompt Font Weight
D2FP_PRMPT_FORE_COLOR
Prompt Foreground Color
D2FP_PRMPT_JST
Prompt Justification
D2FP_PRMPT_READING_ORDR
Prompt Reading Order
D2FP_PRMPT_VAT_NAM
Prompt Visual Attribute Group
D2FP_PRMPT_VAT_OBJ
D2FP_PRMPT_VAT_OBJ
D2FP_PRMRY_CNV
Primary Canvas
D2FP_PRMRY_KEY
Primary Key
D2FP_PROG_UNIT
D2FP_PROG_UNIT
D2FP_PROP_CLASS
Property Class
D2FP_PRVNT_MSTRLESS_OPS
Prevent Masterless Operations
D2FP_QRY_ALL_RECS
Query All Record
D2FP_QRY_ALLOWED
Query Allowed
D2FP_QRY_DAT_SRC_NAM
Query Data Source Name
D2FP_QRY_DAT_SRC_TYP
Query Data Source Type
D2FP_QRY_LEN
Query Length
D2FP_QRY_ONLY
Query Only
D2FP_RAD_BUT
D2FP_RAD_BUT
D2FP_RAISE_ON_ENT
Raise On Entry
D2FP_RDB_VAL
Radio Button Value
D2FP_READING_ORDR
Reading Order
D2FP_REC_GRP
Record Group
D2FP_REC_GRP_FETCH_SIZ
D2FP_REC_GRP_FETCH_SIZEz
D2FP_REC_GRP_NAM
Record Group
D2FP_REC_GRP_OBJ
D2FP_REC_GRP_OBJ
D2FP_REC_GRP_QRY
Record Group Query
D2FP_REC_GRP_TYP
Record Group Type
D2FP_REC_ORNT
Record Orientation
D2FP_REC_VAT_GRP_NAM
Current Record Visual Attribute Group
D2FP_REC_VAT_GRP_OBJ
D2FP_REC_VAT_GRP_OBJ
D2FP_RECS_BUFFERED_COUNT
Number or Records Buffered
D2FP_RECS_DISP_COUNT
Number of Records Displayed
D2FP_RECS_FETCHED_COUNT
Records_to_Fetch
D2FP_REL
D2FP_REL
D2FP_RENDERED
Rendered
D2FP_REPORT
D2FP_REPORT
D2FP_REQUIRED
Required
D2FP_RESIZE_ALLOWED
Resize Allowed
D2FP_REV_DIR
Reverse Direction
D2FP_ROTATION_ANGLE
Rotation Angle
D2FP_RPT_DESTINATION_FMT
Report Destination Format
D2FP_RPT_DESTINATION_NAM
Report Destination Name
D2FP_RPT_DESTINATION_TYP
Report Destination Type
D2FP_RPT_PARAMS
Other Reports Parameters
D2FP_RPT_SRVR
Report Server
D2FP_RTRN_ITM
Return Item
D2FP_SCRLBR_ALIGN
Scroll Bar Alignment
D2FP_SCRLBR_CNV_NAM
Scroll Bar Canvas
D2FP_SCRLBR_CNV_OBJ
D2FP_SCRLBR_CNV_OBJ
D2FP_SCRLBR_HGT
Scroll Bar Height
D2FP_SCRLBR_ORNT
Scroll Bar Orientation
D2FP_SCRLBR_TBP_NAM
Scroll Bar Tab Page
D2FP_SCRLBR_TBP_OBJ
D2FP_SCRLBR_TBP_OBJ
D2FP_SCRLBR_WID
Scroll Bar Width
D2FP_SCRLBR_X_POS
Scroll Bar X Position
D2FP_SCRLBR_Y_POS
Scroll Bar Y Position
D2FP_SHARE_LIB
Share Library with Form
D2FP_SHORT_NAM
Short Name
D2FP_SHOW_FAST_FWD
Show Fast Forward Button
D2FP_SHOW_HORZ_SCRLBR
Show Horizonatal Scrollbar
D2FP_SHOW_PALETTE
Show Palette
D2FP_SHOW_PLAY
Show Play Button
D2FP_SHOW_REC
Show Record Button
D2FP_SHOW_REWIND
Show Rewind Button
D2FP_SHOW_SCRLBR
Show Scroll Bar
D2FP_SHOW_SLIDER
Show Slider
D2FP_SHOW_TIME
Show Time Indicator
D2FP_SHOW_VERT_SCRLBR
Show Vertical Scroll Bar
D2FP_SHOW_VOLUME
Show Volume Control
D2FP_SHRINKWRAP
Shrinkwrap
D2FP_SIZING_STY
Sizing Style
D2FP_SND_FMT
Sound Format
D2FP_SND_QLTY
Sound Quality
D2FP_SNGL_OBJ_ALIGN
Single Object Align
D2FP_SNGL_REC
Single Record
D2FP_SOURCE
D2FP_SOURCE
D2FP_STRT_ANGLE
Start Angle
D2FP_STRT_PRMPT_ALIGN
Start Prompt Alignment
D2FP_STRT_PRMPT_OFST
Start Prompt Offset
D2FP_STRTUP_CODE
Startup Code
D2FP_SUB_MNU_NAM
D2FP_SUB_MNU_NAM
D2FP_SUB_MNU_OBJ
D2FP_SUB_MNU_OBJ
D2FP_SUB_TTL
Subtitle
D2FP_SUMM_BLK_NAM
Summarized Block
D2FP_SUMM_FUNC
Summarized Function
D2FP_SUMM_ITM_NAM
Summarized Item
D2FP_SVPNT_MODE
Savepoint Mode
D2FP_SYNC_ITM_NAM
Synchronize with Item
D2FP_SYNC_ITM_OBJ
D2FP_SYNC_ITM_OBJ
D2FP_TAB_ATT_EDGE
Tab Attachment Edge
D2FP_TAB_PAGE
Tab Page
D2FP_TAB_STY
Tab Style
D2FP_TBP_NAM
D2FP_TBP_NAM
D2FP_TBP_OBJ
D2FP_TBP_OBJ
D2FP_TEAR_OFF_MNU
Tear-Off Menu
D2FP_TITLE
Title
D2FP_TOOLTIP
Tooltip
D2FP_TOOLTIP_VAT_GRP
Tooltip Visual Attribute Group
D2FP_TOP_PRMPT_ALIGN
Top Prompt Alignment
D2FP_TOP_PRMPT_OFST
Top Prompt Offset
D2FP_TRG_STY
Trigger Style
D2FP_TRG_TXT
Trigger Text
D2FP_TRG_TYP
Trigger Type
D2FP_TRIGGER
D2FP_TRIGGER
D2FP_TTL_READING_ORDR
Title Reading Order
D2FP_UNCHKED_VAL
Value When Unchecked
D2FP_UPDT_ALLOWED
Update Allowed
D2FP_UPDT_CHANGED_COLS
Update Changed Columns Only
D2FP_UPDT_COMMIT
Update Commit
D2FP_UPDT_IF_NULL
Update Only if NULL
D2FP_UPDT_LAYOUT
Update Layout
D2FP_UPDT_PROC_NAM
Update Procedure Name
D2FP_UPDT_QRY
Update Query
D2FP_USE_SECURITY
Use Security
D2FP_USE_3D_CNTRLS
Use 3D Controls
D2FP_VALIDATE_FROM_LIST
Validate From List
D2FP_VALIDATION_UNIT
Validation Unit
D2FP_VAT_NAM
Visual Attribute Group
D2FP_VAT_OBJ
D2FP_VAT_OBJ
D2FP_VAT_TYP
D2FP_VAT_TYP
D2FP_VERT_FILL
Vertical Fill
D2FP_VERT_JST
Vertical Justification
D2FP_VERT_MARGN
Vertical Margin
D2FP_VERT_OBJ_OFST
Vertical Object Offset
D2FP_VERT_ORGN
Vertical Position Relative to Origin
D2FP_VERT_TLBR_CNV
Vertical Toolbar Canvas
D2FP_VIS_ATTR
D2FP_VIS_ATTR
D2FP_VISIBLE
Visible
D2FP_VPRT_HGT
Viewport Height
D2FP_VPRT_WID
Viewport Width
D2FP_VPRT_X_POS
Viewport X Position
D2FP_VPRT_X_POS_ON_CNV
Viewport X Position on Canvas
D2FP_VPRT_Y_POS
Viewport Y Position
D2FP_VPRT_Y_POS_ON_CNV
Viewport Y Position on Canvas
D2FP_VSBL_IN_HORZ_MNU_TLBR
Visible in Horizontal/Vertical Menu Toolbar
D2FP_VSBL_IN_MENU
Visible in Menu
D2FP_VSBL_IN_VERT_MNU_TLBR
Visible in Horizontal/Vertical Menu Toolbar
D2FP_VTB_CNV_NAME
Vertical Toolbar Canvas
D2FP_WHERE_CLAUSE
WHERE Clause
D2FP_WHITE_ON_BLACK
White on Black
D2FP_WIDTH
Width/Height
D2FP_WIN_STY
Window Style
D2FP_WINDOW
Window
D2FP_WND_NAM
Window
D2FP_WND_OBJ
D2FP_WND_OBJ
D2FP_WRAP_STY
Wrap Style
D2FP_WRAP_TXT
Wrap Text


Object group API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_MODULE	D2FP_MODULE
D2FP_NEXT	D2FP_NEXT
D2FP_OG_CHILD	D2FP_OG_CHILD
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SOURCE	D2FP_SOURCE


Object group child API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OBJ_GRP_CHILD_REAL_OBJ	D2FP_OBJ_GRP_CHILD_REAL_OBJ
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SOURCE	D2FP_SOURCE


Object library API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OBJ_COUNT	D2FP_OBJ_COUNT
D2FP_OBJ_LIB_TAB	D2FP_OBJ_LIB_TAB
D2FP_PREVIOUS	D2FP_PREVIOUS


Program unit object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PGU_TXT	D2FP_PGU_TXT
D2FP_PGU_TYP	D2FP_PGU_TYP
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SOURCE	D2FP_SOURCE


Property class object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SOURCE	D2FP_SOURCE
D2FP_TRIGGER	D2FP_TRIGGER


Radio button object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_ACCESS_KEY	Access Key
D2FP_BACK_COLOR	Back Color
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_DIST_BTWN_RECS	Distance Between Records
D2FP_ENABLED	Enabled
D2FP_FILL_PAT	Fill Pattern
D2FP_FONT_NAM	Font Name
D2FP_FONT_SIZE	Font Size
D2FP_FONT_SPCING	Font Spacing
D2FP_FONT_STY	Font Style
D2FP_FONT_WGHT	Font Weight
D2FP_FORE_COLOR	Foreground Color
D2FP_HEIGHT	Width/Height
D2FP_LABEL	Label
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_PRMPT	Prompt
D2FP_PRMPT_ALIGN	Prompt Alignment
D2FP_PRMPT_ALIGN_OFST	Prompt Alignment Offset
D2FP_PRMPT_ATT_EDGE	Prompt Attachment Edge
D2FP_PRMPT_ATT_OFST	Prompt Attachement Offset
D2FP_PRMPT_BACK_COLOR	Prompt Background Color
D2FP_PRMPT_DISP_STY	Prompt Display Style
D2FP_PRMPT_FILL_PAT	Prompt Fill Pattern
D2FP_PRMPT_FONT_NAM	Prompt Font Name
D2FP_PRMPT_FONT_SIZ	Prompt Font Size
D2FP_PRMPT_FONT_SPCING	Prompt Font Spacing
D2FP_PRMPT_FONT_STY	Prompt Font Style
D2FP_PRMPT_FONT_WGHT	Prompt Font Weight
D2FP_PRMPT_FORE_COLOR	Prompt Foreground Color
D2FP_PRMPT_JST	Prompt Justification
D2FP_PRMPT_READING_ORDR	Prompt Reading Order
D2FP_PRMPT_VAT_NAM	Prompt Visual Attribute Group
D2FP_PRMPT_VAT_OBJ	D2FP_PRMPT_VAT_OBJ
D2FP_RDB_VAL	Radio Button Value
D2FP_SOURCE	D2FP_SOURCE
D2FP_VAT_NAM	Visual Attribute Group
D2FP_VAT_OBJ	D2FP_VAT_OBJ
D2FP_VISIBLE	Visible
D2FP_WHITE_ON_BLACK	White on Black
D2FP_WIDTH	Width/Height
D2FP_X_POS	X Position/Y Position
D2FP_Y_POS	X Position/Y Position


Record group object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COL_SPEC	Column Specifications
D2FP_COMMENT	Comments
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_REC_GRP_FETCH_SIZ	D2FP_REC_GRP_FETCH_SIZ
D2FP_REC_GRP_QRY	Record Group Query
D2FP_REC_GRP_TYP	Record Group Type
D2FP_SOURCE	D2FP_SOURCE


Record group column specification API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COL_DAT_TYP	D2FP_COL_DAT_TYP
D2FP_COL_VALS_COUNT	D2FP_COL_VALS_COUNT
D2FP_MAX_LEN	Maximum Length
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_PREVIOUS	D2FP_PREVIOUS


Relation object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_AUTO_QRY	Automatic Query
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_DEFERRED	Deferred
D2FP_DEL_REC	Delete Record Behavior
D2FP_DETAIL_BLK	Detail Block
D2FP_JOIN_COND	Join Condition
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_PRVNT_MSTRLESS_OPS	Prevent Masterless Operations
D2FP_SOURCE	D2FP_SOURCE


Report object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMM_MODE	Communication Mode
D2FP_COMMENT	Comments
D2FP_DAT_SRC_BLK	Data Source Block
D2FP_EXEC_MODE	Execution Mode
D2FP_FLNAM	File_Name
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_RPT_DESTINATION_FMT	Report Destination Format
D2FP_RPT_DESTINATION_NAM	Report Destination Name
D2FP_RPT_DESTINATION_TYP	Report Destination Type
D2FP_RPT_PARAMS	Other Reports Parameters
D2FP_RPT_SRVR	Report Server
D2FP_SOURCE	D2FP_SOURCE


Tab page object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_GRAPHIC	D2FP_GRAPHIC
D2FP_LABEL	Label
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SOURCE	D2FP_SOURCE


Trigger object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_COMMENT	Comments
D2FP_DISP_IN_KBRD_HLP	Display in Keyboard Help
D2FP_EXEC_HIERARCHY	Execution Style
D2FP_FIRE_IN_QRY	Fire in Enter-Query Mode
D2FP_KBRD_HLP_TXT	Keyboard Help Description
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_SOURCE	D2FP_SOURCE
D2FP_TRG_STY	Trigger Style
D2FP_TRG_TXT	Trigger Text
D2FP_TRG_TYP	Trigger Type


Visual attribute object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_BACK_COLOR	Back Color
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_FILL_PAT	Fill Pattern
D2FP_FONT_NAM	Font Name
D2FP_FONT_SIZE	Font Size
D2FP_FONT_SPCING	Font Spacing
D2FP_FONT_STY	Font Style
D2FP_FONT_WGHT	Font Weight
D2FP_FORE_COLOR	Foreground Color
D2FP_MODULE	D2FP_MODULE
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_PRMPT_BACK_COLOR	Prompt Background Color
D2FP_PRMPT_FILL_PAT	Prompt Fill Pattern
D2FP_PRMPT_FONT_NAM	Prompt Font Name
D2FP_PRMPT_FONT_SIZ	Prompt Font Size
D2FP_PRMPT_FONT_SPCING	Prompt Font Spacing
D2FP_PRMPT_FONT_STY	Prompt Font Style
D2FP_PRMPT_FONT_WGHT	Prompt Font Weight
D2FP_PRMPT_FORE_COLOR	Prompt Foreground Color
D2FP_SOURCE	D2FP_SOURCE
D2FP_VAT_TYP	D2FP_VAT_TYP
D2FP_WHITE_ON_BLACK	White on Black


Window object API properties

  Related Topics

The left column includes properties as they appear in the header files of the Open API.  The right column is the corresponding property name as it appears in the Form Builder interface.

D2FP_BACK_COLOR	Back Color
D2FP_BEVEL	Bevel
D2FP_CLIENT_INFO	D2FP_CLIENT_INFO
D2FP_CLS_ALLOWED	CLOSE ALLOWED
D2FP_COMMENT	Comments
D2FP_FILL_PAT	Fill Pattern
D2FP_FONT_NAM	Font Name
D2FP_FONT_SIZE	Font Size
D2FP_FONT_SPCING	Font Spacing
D2FP_FONT_STY	Font Style
D2FP_FONT_WGHT	Font Weight
D2FP_FORE_COLOR	Foreground Color
D2FP_HEIGHT	Width/Height
D2FP_HIDE_ON_EXIT	Hide on Exit
D2FP_HTB_CNV_NAME	Horizontal Toolbar Canvas
D2FP_ICON_FLNAM	Icon Filename
D2FP_INHRT_MNU	Inherit Menu
D2FP_LANG_DIR	Language Direction
D2FP_MAXIMIZE_ALLOWED	Maximize Allowed
D2FP_MINIMIZE_ALLOWED	Minimized Allowed
D2FP_MINIMIZE_TTL	Minimize Title
D2FP_MODAL	Modal
D2FP_MODULE	D2FP_MODULE
D2FP_MV_ALLOWED	Move Allowed
D2FP_NAME	Name
D2FP_NEXT	D2FP_NEXT
D2FP_OWNER	D2FP_OWNER
D2FP_PAR_FLNAM	D2FP_PAR_FLNAM
D2FP_PAR_FLPATH	D2FP_PAR_FLPATH
D2FP_PAR_MODSTR	D2FP_PAR_MODSTR
D2FP_PAR_MODTYP	D2FP_PAR_MODTYPE
D2FP_PAR_MODULE	D2FP_PAR_MODULE
D2FP_PAR_NAM	D2FP_PAR_NAME
D2FP_PREVIOUS	D2FP_PREVIOUS
D2FP_PRMRY_CNV	Primary Canvas
D2FP_RESIZE_ALLOWED	Resize Allowed
D2FP_SHOW_HORZ_SCRLBR	Show Horizontal Scroll Bar
D2FP_SHOW_VERT_SCRLBR	Show Vertical Scroll Bar
D2FP_SOURCE	D2FP_SOURCE
D2FP_TITLE	Title
D2FP_VAT_NAM	Visual Attribute Group
D2FP_VAT_OBJ	D2FP_VAT_OBJ
D2FP_VTB_CNV_NAME	Vertical Toolbar Canvas
D2FP_WHITE_ON_BLACK	White on Black
D2FP_WIDTH	Width/Height
D2FP_WIN_STY	Window Style
D2FP_X_POS	X Position/Y Position
D2FP_Y_POS	X Position/Y Position


Open API objects

  Related Topics

API Objects

Alerts

Attached Libraries

Blocks

Canvases

Data Source Arguments

Data Source Columns

Editors

Form Modules

Form Parameters

Graphics

Items

List of Values Column Mapping

List of Values

Menu Objects

Menu Modules

Menu Items

Menu Parameters

Objects (Generic Objects)

Object Groups

Object Group Children

Object Libraries

Program Units

Property Classes

Radio Buttons

Record Groups

Record Group Column Specification

Relation Objects

Report Objects

Tab Pages

Triggers

Visual Attributes

Windows


Alert object API
Alert object

  Related Topics

This object is a modal window that displays a message notifying the operator of some application condition.


Attached library object

  Related Topics

This object is a read-only library module that represents a collection of subprograms, including user-named procedures, functions, and packages, that can be called from other modules in the application.


Block object

  Related Topics

This object represents a logical container for grouping related items into a function unit for storing, displaying, and manipulating records.  Only item objects contained in a block are visible in the application interface.


Canvas object

  Related Topics

This object represents a background entity on which you place interface items, such as check boxes, radio groups, and text items.  There are four types of canvas objects: Content, Stacked, Horizontal Toolbar, and Vertical Toolbar.


D2FP_CLIENT_INFO

D2FP_CLIENT_INFO is used by the client to attach additional data to Form Builder objects.  Please note that additional data that is used by the client is not saved in the .fmb file; D2FP_CLIENT_INFO is undefined in subsequent instantiations of Form Builder.


D2FP_MODULE

D2FP_MODULE is used to return the handle to a module object—a form, object library, or menu.


D2FP_NEXT

D2FP_NEXT is used to return the handle to the next object on the list that is of the same type. For instance, D2FP_NEXT can be used to obtain the handle to the next Alert object.  For the last object on the list, D2FP_NEXT returns NULL.


D2FP_OWNER

D2FP_OWNER is used to return the handle to the owner of the object.  For instance,  D2FP_OWNER returns a handle to the owning block for an item because a block owns an item.


D2FP_PREVIOUS

D2FP_PREVIOUS is used to return the handle to the previous object on the list that is of the same type. For an Alert object, D2FP_PREVIOUS returns the handle to the previous Alert object.  For the first object on the list, D2FP_PREVIOUS returns NULL.


D2FP_SOURCE

D2FP_SOURCE is used to return the handle to the source object.  This property only applies to subclassed objects.


D2FP_VAT_OBJ

D2FP_VAT_OBJ is used to return the handle to the visual attribute group objects.


D2FP_PAR_FLNAM

D2FP_PAR_FLNAM is used to return the parent object's filename.  This property only applies to subclassed objects.


D2FP_PAR_FLPATH

D2FP_PAR_FLPATH is used to return the parent object's file paths.  This property only applies to subclassed objects.


D2FP_PAR_MODSTR

D2FP_PAR_MODSTR is used to return the parent object's module string.  This property only applies to subclassed objects.


D2FP_PAR_MODTYP

D2FP_PAR_MODTYP is used to return the parent object's module type.  This property only applies to subclassed objects.


D2FP_PAR_MODULE

D2FP_PAR_MODULE is used to return the parent object's module.  This property only applies to subclassed objects.


D2FP_PAR_NAM

D2FP_PAR_NAM is used to return the parent object's name.  This property only applies to subclassed objects.


D2FP_LIB_LOC

D2FP_LIB_LOC is used to return the physical location of the PL/SQL library.


D2FP_LIB_SRC

D2FP_LIB_SRC is used to return the library source of the PL/SQL library.


D2FP_PRECOMP_SUMM

2FP_PRECOMP_SUMM is used to return the sum for a calculated item.


D2FP_NXT_NAVIGATION_BLK_OBJ

D2FP_NXT_NAVIGATION_BLK_OBJ is used to return the handle to the object that is known as the next navigation block, or block with the next higher sequence number.


D2FP_PREV_NAVIGATION_BLK_OBJ

D2FP_PREV_NAVIGATION_BLK_OBJ is used to return the handle to the object that is known as the previous navigation block.


D2FP_NXT_NAVIGATION_ITM_OBJ

D2FP_NXT_NAVIGATION_ITM_OBJ is used to return the handle to the object that is known as the next navigation block.


D2FP_PREV_NAVIGATION_ITM_OBJ

D2FP_PREV_NAVIGATION_ITM_OBJ is used to return the handle to the object that is known as the previous navigation block, or block with the next lower sequence number.


D2FP_REC_VAT_GRP_OBJ

D2FP_REC_VAT_GRP_OBJ is used to return the handle to the current record visual attribute group object.


D2FP_REL

D2FP_REL is used to return the handle to the list of relation objects.


D2FP_SCRLBR_CNV_OBJ

D2FP_SCRLBR_CNV_OBJ is the handle to the list of scroll bar canvas objects.


D2FP_SCRLBR_TBP_OBJ

D2FP_SCRLBR_TBP_OBJ is the handle to the list of scroll bar tab page objects.


D2FP_TRIGGER

D2FP_TRIGGER is used to return the handle to the list of trigger objects.


D2FP_GRAPHIC

D2FP_GRAPHIC is used to return the handle to the list of graphic objects.


D2FP_POPUP_MNU_OBJ

D2FP_POP_MENU_OBJ is used to return the handle to the list of popup menu objects.


D2FP_WND_OBJ

D2FP_WND_OBJ is used to return the handle to the list of window objects.


D2FP_DSA_MODE

D2FP_DSA_MODE is used to return the mode—IN, OUT, IN OUT—for a data source argument.


D2FP_DSA_NAM

D2FP_DSA_NAM is used to return the name of a data source argument.


D2FP_DSA_TYP

D2FP_DSA_TYP is used to return the data type of a data source argument.


D2FP_DSA_TYP_NAM

D2FP_DSA_TYP_NAM is used to return the name of a data source argument type.


D2FP_DSA_VAL

D2FP_DSA_VAL is used to return the value of a data source argument.


D2FP_DSC_LEN

D2FP_DSC_LEN is used to return the length of a data source column.


D2FP_DSC_MANDATORY

D2FP_DSC_MANDATORY is used to return a value indicating whether a data source column is mandatory.


D2FP_DSC_NAM

D2FP_DSC_NAM is used to return the name of a data source column.


D2FP_DSC_PRECISION

D2FP_DSC_PRECISION is used to return the precision of a data source column.


D2FP_DSC_SCALE

D2FP_DSC_SCALE is used to return the scale of a data source column.


D2FP_DSC_TYPE

D2FP_DSC_TYPE is used to return the data type of a data source column.


D2FP_ALERT

D2FP_ALERT is used to return the handle to the list of alert objects.


D2FP_ATT_LIB

D2FP_ATT_LIB is used to return the handle to the list of attached library objects.


D2FP_BLOCK

D2FP_BLOCK is used to return the handle to the list of block objects.


D2FP_CANVAS

D2FP_CANVAS is used to return the handle to the list of canvas objects.


D2FP_FORM_PARAM

D2FP_FORM_PARAM is used to return the handle to the list of item objects.


D2FP_FIRST_NAVIGATION_BLK_OBJ

D2FP_FIRST_NAVIGATION_BLK_OBJ is used to return the handle to the first navigable block object.


D2FP_MENU

D2FP_MENU is used to return the handle to the list of menu objects.


D2FP_PROG_UNIT

D2FP_PROG_UNIT is used to return the handle to the list of program unit objects.


D2FP_REPORT

D2FP_REPORT is used to return the handle to the list of report objects.


D2FP_OBJ_GRP

D2FP_OBJ_GRP is used to return the handle to the list of object group objects.


D2FP_VIS_ATTR

D2FP_VIS_ATTR is used to return the handle to the list of visual attribute objects.


D2FP_OBJ_COUNT

D2FP_OBJ_COUNT is used to return the number of objects in an object library.


D2FP_OBJ_LIB_TAB

D2FP_OBJ_LIB_TAB is used to return the handle to the list of object library tabs.


D2FP_ITEM

D2FP_ITEM is used to return the handle to the list of item objects.


D2FP_FRAME_TTL_VAT_OBJ

D2FP_FRAM_TTL_VAT_OBJ is used to return the handle to the list of frame title visual attribute objects.


D2FP_TBP_OBJ

D2FP_TBP_OBJ is used to return the handle to the list of tab page objects.


D2FP_CNV_OBJ

D2FP_CNV_OBJ is used to return the handle to the list of canvas objects.


D2FP_EDT_OBJ

D2FP_EDT_OBJ is used to return the handle to the list of editor objects.


D2FP_LOV_OBJ

D2FP_LOV_OBJ is used to return the handle to the list of LOV objects.


D2FP_POPUP_VA_OBJ

D2FP_POPUP_VA_OBJ is used to return the handle to the list of popup visual attribute objects.


D2FP_PRMPT_VAT_OBJ

D2FP_PRMPT_VAT_OBJ is used to return the handle to the list of prompt visual attribute objects.


D2FP_SYNC_ITM_OBJ

D2FP_SYNC_ITM_OBJ is used to return the handle to the list of synchronize item objects.


D2FP_REC_GRP_OBJ

D2FP_REC_GRP_OBJ is used to return the handle to the list of record group objects.


D2FP_LIST_ELEMENT_COUNT

D2FP_LIST_ELEMENT_COUNT is used to return the number of elements in a list element object.


D2FP_RAD_BUT

D2FP_RAD_BUT is used to return the handle to the list of radio buttons.


D2FP_MNU_ITM_CODE

D2FP_MENU_ITM_CODE is used to return the handle to the menu item source code.


D2FP_SUB_MNU_NAM

D2FP_SUB_MNU_NAM is used to return the name of a a sub menu.


D2FP_SUB_MNU_OBJ

D2FP_SUB_MNU_OBJ is used to return the handle to the list of sub menus.


D2FP_VAT_TYP

D2FP_VAT_TYP is used to return the visual attribute type


D2FP_COL_VALS_COUNT

D2FP_COL_VALS_COUNT is used to return the number of values associated with column name in the column specification object.


D2FP_COL_DAT_TYP

D2FP_COL_DAT_TYP is used to return the data type property for the column specification object.


D2FP_PGU_TXT

D2FP_PGU_TXT is used to return the program unit text.


D2FP_PGU_TYP

D2FP_PGU_TYP is used to return the program unit type.


D2FP_OBJ_GRP_CHILD_REAL_OBJ

D2FP_OBJ_GRP_CHILD_REAL_OBJ is used to return handle to the object group child's real object.


D2FP_ASSOC_MENUS_COUNT

D2FP_ASSOC_MENUS_COUNT is used to return the number of associated menus


D2FP_OG_CHILD

D2FP_OG_CHILD is used to return a handle to the first child of the object group.


D2FP_MNU_PARAM

D2FP_MNU_PARAM is used to return a handle to the first menu parameter.


Data source argument object

  Related Topics

This object specifies the names, datatypes, and values of the arguments that are to be passed to a procedure for querying data.


Data source column object

  Related Topics

This object specifies the names and datatypes of the columns associated with the block's query data source.


Editor object

  Related Topics

This object enables the operator to edit text.  There are three types of editor objects: default editor, system editor, and user-named editor.


Form module object

  Related Topics

This object represents a collection of objects and code routines.  Some of the objects you can define in a form module include windows, text items (fields), check boxes, buttons, alerts, lists of values, and blocks of PL/SQL code called triggers.


Form parameter object

  Related Topics

This object provides a simple mechanism for you to define and set the values of inputs that are required by a form at startup. Form parameters are variables of type CHAR, NUMBER, or DATE that you define at design time.


Graphics object

  Related Topics

This object represents a collection of graphical boilerplate objects which can be placed on a canvas object.  You can create following graphical objects: rectangles, ellipses, polygons, rounded rectangles, text boilerplate objects, lines, arcs, polylines, and free-form boilerplate objects (freehand objects).


Item object

  Related Topics

This object displays information to operators and enables them to interact with your application.  Item objects include the following types: bean area, button, chart item, check box, display item, image, list item, OLE container, radio group, text item, user area, and VBX control.


LOV column mapping object

  Related Topics

This object represents the individual columns within a list of values (LOV)  object.  Once you create a LOV object, you must create a LOV column mapping object (using d2flcmcr_Create()) for each column of the LOV object.


List of values (LOV) object

  Related Topics

This object represents an internal Form Builder data structure that has a column/row framework similar to a database table.

An LOV object is a scrollable popup window that provides the end user with either a single or multi-column selection list.


Menu object

  Related Topics

This object specifies the string that displays on the message line when the end user navigates to the menu, for applications running on character mode in the pull-down and bar menu display styles.  In full-screen display style, this object represents the string that identifies the menu module.  Every form runs with one of the following menu objects: a default menu that is built into every form, a custom menu that you can define as a separate module and then attach to your form for runtime execution, or no menu at all.


Menu module object

  Related Topics

This object represents a collection of menus (a main menu and any number of submenu objects) and menu item commands that together make up an application menu.


Menu item object

  Related Topics

This object specifies the type of menu item: Plain, Check, Magic, Radio, or Separator.  The type determines how the item is displayed and whether the item can have an associated command.


Menu parameter object

  Related Topics

This object represents the name of the individual menu(s) in the module with which the parameter is associated. When the operator navigates to a menu that has an associated parameter, Form Builder prompts the operator to enter a value in the Enter Parameter Values dialog.


Object (generic object)

  Related Topics

This object enables you to programmatically propagate all changes to all of the associated objects contained on a specific form.


Object group object

  Related Topics

This object is a container for a group of objects.  You define an object group when you want to package related objects so you can copy or subclass them in another module.

Object groups provide a way to bundle objects into higher-level building blocks that can be used in other parts of an application and in subsequent development projects.


Object group child object

  Related Topics

This object represents a child object of an object group container.


Object library object

  Related Topics

This object provides an easy method of reusing objects and enforcing standards across the entire development organization.

You can use the Object Library to create, store, maintain, and distribute standard and reusable objects.

In addition, by using Object Libraries, you can rapidly create applications by dragging and dropping predefined objects to your form.


Program unit object

  Related Topics

This object represents a named PL/SQL function or procedure that you write in a form, menu, or library module.  Although trigger objects are the primary mechanism for adding programmatic control to a Form Builder application, this object supplements trigger objects by allowing you to reuse code without having to enter it in multiple triggers.


Property class object

  Related Topics

This object is a named object that contains a list of properties and their associated settings.  Once you create a property class you can base other objects on it.  An object based on a property class can inherit the settings of any property in the class that is appropriate for that object.


Radio button object

  Related Topics

This object represents a mutually-exclusive option displayed on a radio group interface control.  This object can be sized, positioned, and formatted independently of other radio button objects.


Record group object

  Related Topics

This object represents an internal Form Builder data structure that has a column/row framework similar to a database table.  However, unlike database tables, record groups are separate objects that belong to the form module in which they are defined.  A record group object an have an unlimited number of columns of type CHAR, LONG, NUMBER, or DATE provided that the total number of columns  does not exceed 64K.  Record group object column names cannot exceed 30 characters.


Record group column specification object

  Related Topics

This object represents the individual columns within a record group object.  Once you create a record group object, you must create a record group column specification object (using d2frcscr_Create())  for each column of the record group object.


Relation object

  Related Topics

This logical object specifies the relationship between one master block and one corresponding detail block.  In the Object Navigator, the relation object appears under the block that is the master block in the relation.

When you create a relation, Form Builder generates the triggers and PL/SQL procedures required to enforce coordination between the master and detail blocks.  The actual code that Form Builder generates depends on how you define the properties of the relation.


Report object

  Related Topics

This object represents a report module that is built using the Oracle Report Builder.


Tab Page object

  Related Topics

This object displays a subset of the information displayed on the entire tab canvas.  A tab canvas allows you to group and display a large amount of information on a single dynamic canvas object.  A tab canvas can contain one or more tab page objects.


Trigger object

  Related Topics

This object represents a block of code you write to add functionality to a default application. Every trigger object has a name, and contains one or more PL/SQL statements.  A trigger object encapsulates PL/SQL code so that you can associate it with an event, and execute and maintain it as a distinct object.


Visual attribute object

  Related Topics

This object represents a named visual attribute that should be applied to an object at runtime.  A visual attribute defines a collection of font, color, and pattern attributes that determine the appearance of an object.


Window object

  Related Topics

This object specifies the window in which the canvas object is displayed at runtime.


About Open API functions by objects

  Related Topics

This section describes the functions as they appear in the header files of the Open API. Functions are organized by the associated Forms Open API object. Each function includes the argument list and a short description.

For a complete description of the various possible Open API function return codes, refer to the “About Open API function return codes” section.

API Functions by Objects

Alerts

Attached Libraries

Blocks

Canvases

Data Source Arguments

Data Source Columns

Editors

Form Modules

Form Parameters

Graphics

Items

List of Values Column Mapping

List of Values

Menu Objects

Menu Modules

Menu Items

Menu Parameters

Objects (Generic Objects)

Object Groups

Object Group Children

Object Libraries

Program Units

Property Classes

Radio Buttons

Record Groups

Record Group Column Specification

Relation Objects

Report Objects

Tab Pages

Triggers

Visual Attributes

Windows


Alert object functions

  Related Topics

This section describes the functions of the Form Builder Open API Alert object.

d2faltcr_Create( d2fctx *pd2fctx, d2fob *parent, d2falt **ppd2falt, text *name );

This function creates an alert object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new alert object in parent, a handle for the function to store the newly-created alert object in ppd2falt, and the name of the new object in name.

This function returns D2FS_D2FS_SUCCESS if it is able to create the new alert object and store it in ppd2falt.

d2faltde_Destroy( d2fctx *pd2fctx, d2falt *pd2falt );

This function destroys the specified alert object.  You specify a pointer to the context in pd2fctx and a pointer to the alert object you want to destroy in pd2falt.

d2faltdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2alt *pd2falt_src, d2falt **ppd2falt_dst, text *new_name );

This function duplicates the specified alert object.  You specify a pointer to the context in pd2fctx, the new parent in new_parent, the alert source in pd2falt_src, a handle for the function to store the alert destination in ppd2falt_dst, and a pointer for the name of the new alert object (new_name).

This function returns D2FS_SUCCESS if it is able to duplicate the specified alert object and store it at the ppd2falt_dst location.

d2faltgb_GetBoolProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified alert object.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, the property number in pnum, and a pointer to pprp to store the boolean property value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2faltgn_GetNumProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified alert object.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, the property number in pnum, and a pointer to pprp, to store the numeric property value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2faltgt_GetTextProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified alert object.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified alert object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2faltgo_GetObjectProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified alert object.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property value in pprp.

d2faltgp_GetBlobProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2faltsb_SetBoolProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum, boolean prp );

This function sets the value of the specified alert object boolean property.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, the property number in pnum, and the boolean property value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2faltsn_SetNumProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum, number prp );

This function sets the value of the specified alert object number property.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, the property number in pnum, and the number property value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2faltst_SetTextProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum, text *prp );

This function sets the value of the specified alert object text property.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, the property number in pnum, and a pointer to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2faltso_SetObjectProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum, dvoid *prp );

This function sets the object of the specified alert object property.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, a property number in pnum, and a pointer to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2faltsp_SetBlobProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2falthp_HasProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum );

This function queries the specified alert object for the specified property. You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2faltip_InheritProp( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum );

This function enables the specified alert object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2faltii_IspropInherited( d2fctx *pd2fctx, d2falt *pd2falt, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2faltsc_SubClass( d2fctx *pd2fctx, d2falt *pd2falt, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified alert object (pd2falt) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the alert object in pd2falt, a pointer to the parent object in parent, and a boolean flag to indicate if the function saves the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fnb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2faltis_IsSubclassed	( d2fctx *pd2fctx, d2falt *pd2falt );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the alert object in pd2falt.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Attached library object functions

  Related Topics

This section describes the functions of the Form Builder Open API Attached Library object.

d2falbat_Attach( d2fctx *pd2fctx, d2fob *parent, d2falb **ppd2falb, boolean db, text *name );

This function attaches the specified library to a database (such as a form,  menu, or PL/SQL library) or file system. You specify a pointer to the context in pd2fctx, a pointer to where you want the library attached in parent, a handle for the returned attached library in ppd2falb, a boolean flag to indicate whether the library resides in a database or a file system in db, and a pointer to the name of the library in name.

If you set db to TRUE, the Forms API searches for the specified library (the name passed in name) in a database.  If db is set to FALSE, the library resides in a file system and the Forms API searches the file system for the specified library and then attaches it.  For example, if you want to attach a library to a form module and the library resides in the file system, set db to FALSE.

d2falbdt_Detach( d2fctx *pd2fctx, d2falb *pd2falb );

This function detaches the specified library from a database or file system. You specify a pointer to the context in pd2fctx and a pointer the attached library in ppd2falb.

d2falbgb_GetBoolProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified attached library.  You specify a pointer to the context in pd2fctx, a pointer to the attached library in pd2falb, the property number in pnum, and a pointer to pprp, to store the boolean property value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2falbgn_GetNumProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified attached library.  You specify a pointer to the context in pd2fctx, a pointer to the attached library in pd2falb, the property number in pnum, and a pointer to pprp, to store the retrieved numeric property value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2falbgt_GetTextProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified attached library.  You specify a pointer to the context in pd2fctx, a pointer to the attached library in pd2falb, the property number in pnum, and a handle to an array of characters for the function to store the text property value (pprp).

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified attached library in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2falbgo_GetObjectProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified attached library.  You specify a pointer to the context in pd2fctx, a pointer to the attached library in pd2falb, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2falbgp_GetBlobProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the attached library in pd2falb, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2falbsb_SetBoolProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum, boolean prp );

This function sets the value of the specified attached library boolean property.  You specify a pointer to the context in pd2fctx, a pointer to the attached library in pd2falb, the property number in pnum, and the boolean property value in prp.

This function returns D2FS_SUCCESS if it sets the specified boolean property with the value you specify in prp.

d2falbsn_SetNumProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum, number prp );

This function sets the value of the specified attached library number property.  You specify a pointer to the context in pd2fctx, a pointer to the attached library in pd2falb, the property number in pnum, and the number property value in prp.

This function returns D2FS_SUCCESS if it sets the specified number property with the value you specify in prp.

d2falbst_SetTextProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum, text *prp );

This function sets the value of the specified attached library text property.  You specify a pointer to the context in pd2fctx, a pointer to the attached library in pd2falb, the property number in pnum, and a pointer to the text property value in prp.

This function returns D2FS_SUCCESS if it is sets the specified text property with the value stored in prp.

d2falbso_SetObjectProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum, dvoid *prp );

This function sets the object of the specified attached library property.  You specify a pointer to the context in pd2fctx, a pointer to the attached library in pd2falb, a property number in pnum, and a pointer to the object property value in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2falbsp_SetBlobProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the attached library object in pd2falb, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2falbhp_HasProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum );

This function queries the specified attached library for the specified property. You specify a pointer to the context in pd2fctx, a pointer to the attached library in pd2falb, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2falbip_InheritProp( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum );

This function enables the specified attached library to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the attached library object in pd2falb, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2falbii_IspropInherited( d2fctx *pd2fctx, d2falb *pd2falb, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the attached library object in pd2falb, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Block object functions

  Related Topics

This section describes the functions of the Form Builder Open API Block object.

d2fblkcr_Create( d2fctx *pd2fctx, d2fob *parent, d2fblk **ppd2fblk, text *name );

This function creates a block.  You specify a pointer to the context in pd2fctx, , a pointer to the parent of the new block object in parent, a handle for the function to store the newly-created block object in ppd2fblk, and a pointer to name, for the name of the new object.

This function returns D2FS_SUCCESS if it is able to create a new block in ppd2fblk.

d2fblkde_Destroy( d2fctx *pd2fctx, d2fblk *pd2fblk );

This function destroys the specified block.  You specify a pointer to the context in pd2fctx and a pointer to the block object you want to destroy in pd2fblk.

d2fblkdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2blk *pd2fblk_src, d2fblk **ppd2fblk_dst, text *new_name );

This function duplicates the specified block.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the block source in pd2fblk_src, a handle for the function to store the destination in ppd2fblk_dst, and a pointer for the name of the new block (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified block and place it in the ppd2fblk_dst location.

d2fblkco_CompileObj( d2fctx *pd2fctx, d2fblk *pd2fblk );

This function compiles all of the PL/SQL code associated with the specified block.  You specify a pointer to the context in pd2fctx and a pointer to the object you want to compile in pd2fblk.

For example, you might use this function to compile all of the trigger objects attached to a block, and all of the trigger objects attached to all item objects in a block.

d2fblkgb_GetBoolProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified block.  You specify a pointer to the context in pd2fctx, a pointer to the block in pd2fblk, the property number in pnum, and a pointer to pprp, to store the boolean property value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fblkgn_GetNumProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified block.  You specify a pointer to the context in pd2fctx, a pointer to the block in pd2fblk, the property number in pnum, and a pointer to pprp, to store the numeric property value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fblkgt_GetTextProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified block.  You specify a pointer to the context in pd2fctx, a pointer to the block in pd2fblk, the property number in pnum, and a handle to an array of characters for the function to store the text property value in pprp.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified block in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fblkgo_GetObjectProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified block.  You specify a pointer to the context in pd2fctx, a pointer to the block in pd2fblk, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fblkgp_GetBlobProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the block object in pd2fblk, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fblksb_SetBoolProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum, boolean prp );

This function sets the value of the specified block boolean property.  You specify a pointer to the context in pd2fctx, a pointer to the block in pd2fblk, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fblksn_SetNumProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum, number prp );

This function sets the value of the specified block number property.  You specify a pointer to the context in pd2fctx, a pointer to the block in pd2fblk, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fblkst_SetTextProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum, text *prp );

This function sets the value of the specified block text property.  You specify a pointer to the context in pd2fctx, a pointer to the block in pd2fblk, the property number in pnum, and a pointer to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fblkso_SetObjectProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum, dvoid *prp );

This function sets the object of the specified block property.  You specify a pointer to the context in pd2fctx, a pointer to the block in pd2fblk, a property number in pnum, and a pointer to the object property value in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fblksp_SetBlobProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the block object in pd2fblk, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fblkhp_HasProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum );

This function queries the specified block for the specified property. You specify a pointer to the context in pd2fctx, a pointer to the block in pd2fblk, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fblkip_InheritProp( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum );

This function enables the specified block to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the block object in pd2fblk, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fblkii_IspropInherited( d2fctx *pd2fctx, d2fblk *pd2fblk, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the block object in pd2fblk, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fblksc_SubClass( d2fctx *pd2fctx, d2fblk *pd2fblk, d2fob *parent, boolean keep_path);

This function returns D2FS_YES if the specified block (pd2fblk) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the block in pd2fblk, a pointer to the parent object in parent, and a boolean flag to indicate if the function saves the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fnb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fblkis_IsSubclassed	( d2fctx *pd2fctx, d2fblk *pd2fblk );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the block object in pd2fblk.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Canvas object functions

  Related Topics

This section describes the functions of the Form Builder Open API Block object.

d2fcnvcr_Create( d2fctx *pd2fctx, d2fob *parent, d2fcnv **ppd2fcnv, text *name );

This function creates a canvas.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new canvas object in parent, a handle for the function to store the newly-created canvas object in ppd2fcnv, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new canvas in ppd2fcnv.

d2fcnvde_Destroy( d2fctx *pd2fctx, d2fcnv *pd2fcnv );

This function destroys the specified canvas.  You specify a pointer to the context in pd2fctx and a pointer to the canvas you want to destroy in pd2fcnv.

d2fcnvdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2cnv *pd2fcnv_src, d2fcnv **ppd2fcnv_dst, text *new_name );

This function duplicates the specified canvas.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the canvas source in pd2fcnv_src, a handle for the function to store the destination in ppd2fcnv_dst, and a pointer for the name of the new canvas (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified canvas and place it at the ppd2fcnv_dst location.

d2fcnvco_CompileObj( d2fctx *pd2fctx, d2fcnv *pd2fcnv );

This function compiles all of the PL/SQL code associated with the specified canvas. You specify a pointer to the context in pd2fctx and a pointer to the object you want to compile in pd2fcnv.

For example, you might use this function to compile all of the trigger objects attached to a canvas, and all of the trigger objects attached to all item objects on a canvas.

d2fcnvgb_GetBoolProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified canvas.  You specify a pointer to the context in pd2fctx, a pointer to the canvas in pd2fcnv, the property number in pnum, and a pointer to pprp, to store the boolean property value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fcnvgn_GetNumProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified canvas.  You specify a pointer to the context in pd2fctx, a pointer to the canvas in pd2fcnv, the property number in pnum, and a pointer to pprp, to store the numeric property value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fcnvgt_GetTextProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified canvas.  You specify a pointer to the context in pd2fctx, a pointer to the canvas in pd2fcnv, the property number in pnum, and a handle to an array of characters for the function to store the text property value in pprp.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified canvas in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fcnvgo_GetObjectProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified canvas.  You specify a pointer to the context in pd2fctx, a pointer to the canvas in pd2fcnv, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fcnvgp_GetBlobProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the canvas object in pd2fcnv, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fcnvsb_SetBoolProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum, boolean prp );

This function sets the value of the specified canvas boolean property.  You specify a pointer to the context in pd2fctx, the canvas in pd2fcnv, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fcnvsn_SetNumProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum, number prp );

This function sets the value of the specified canvas number property.  You specify a pointer to the context in pd2fctx, the canvas in pd2fcnv, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fcnvst_SetTextProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum, text *prp );

This function sets the value of the specified canvas text property.  You specify a pointer to the context in pd2fctx, the canvas in pd2fcnv, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fcnvso_SetObjectProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum, dvoid *prp );

This function sets the object of the specified canvas property.  You specify a pointer to the context in pd2fctx, the canvas in pd2fcnv, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fcnvsp_SetBlobProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the canvas object in pd2fcnv, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fcnvhp_HasProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum );

This function queries the specified canvas for the specified property. You specify a pointer to the context in pd2fctx, the canvas in pd2fcnv, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fcnvip_InheritProp( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum );

This function enables the specified canvas to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the canvas object in pd2fcnv, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fcnvii_IspropInherited( d2fctx *pd2fctx, d2fcnv *pd2fcnv, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the canvas object in pd2fcnv, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fcnvsc_SubClass( d2fctx *pd2fctx, d2fcnv *pd2fcnv, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified canvas (pd2fcnv) becomes a subclass of the specified parent (parent). You specify a pointer to the context in pd2fctx, a pointer to the canvas in pd2fcnv, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fnb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fcnvis_IsSubclassed	( d2fctx *pd2fctx, d2fcnv *pd2fcnv );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the canvas object in pd2fcnv.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Context object functions

  Related Topics

This section describes the functions of the Form Builder Open API Context object.

d2fctxcr_Create( d2fctx **pd2fctx, d2fctxa *d2fctx_attr );

This function creates the context.  You specify a handle for the Forms API to store the newly-created context in pd2fctx and a pointer to the attribute structure in pd2fctx_attr.

In order to create this context, you must define the actual attribute structure (d2fctxa) shown below:

   typedef struct d2fctxa

   {

       ub4 mask_d2fctxa;

       dvoid *cdata_d2fctxa;       /* Client data     */

       d2fmalc d2fmalc_d2fctxa;

       d2fmfre d2fmfre_d2fctxa;

       d2fmrlc d2fmrlc_d2fctxa;

   } d2fctxa;

d2fctxde_Destroy( d2fctx *pd2fctx );

This function destroys the specified context.  You specify a pointer to the context in pd2fctx.

Note that you need to call this function last, once you are finished using the Forms API.

d2fctxsa_SetAttributes( d2fctx *pd2fctx, d2fctxa *pd2fctx_attr );

This function sets the specified attributes in your attribute structure.  You specify a pointer to the context in pd2fctx, and a pointer to the attribute structure in pd2fctx_attr.

Note that you can use this function anytime you need to pass in client data or memory callbacks.

d2fctxga_GetAttributes( d2fctx *pd2fctx, d2fctxa *pd2fctx_attr );

This function gets the specified attributes from your attribute structure.  You specify a pointer to the context in pd2fctx and a pointer to the attribute structure in pd2fctx_attr.

Note that you can use this function anytime you need to retrieve client data or memory callbacks.

d2fctxcn_Connect( d2fctx *pd2fctx, text *con_str, dvoid *phstdef );

This function connects you to the specified database.  You specify a pointer to the context in pd2fctx , a pointer to the connect string in con_str, and optionally, an hstdef pointer (phstdef).

Note that the phstdef argument is supplied for advanced users who want to share an hstdef-enabled connection (the hstdef structure is externalized by the PL/SQL API) rather than establish a second connection and potentially slow performance.  The hstdef pointer contains information about the database connection.  If you set phstdef to NULL, the Forms API establishes a connection to the database you specify in con_str; otherwise, the function checks that the hstdef connection is valid and then uses the hstdef pointer to make the database connection.  If the pstdef pointer is invalid or not connected, an error is returned.  Most users should pass in a NULL pointer for the phstdef argument.

d2fctxdc_Disconnect( d2fctx *pd2fctx );

This function disconnects you from the current database connection.

d2fctxbv_BuilderVersion( d2fctx *pd2fctx, number *version );

This function returns the current version of the Forms Designer.  You specify a pointer to the context in pd2fctx and a pointer to version number in version.


Datasource argument object functions

  Related Topics

This section describes the functions of the Form Builder Open API Data Source Argument object.

d2fdsacr_Create( d2fctx *pd2fctx, d2fob *parent, d2fdsa **ppd2fdsa, text *name );

This function creates a data source argument.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new data source argument in parent, a handle for the function to store the newly-created data source argument object in ppd2fdsa, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create and store a new data source argument in ppd2fdsa.

d2fdsade_Destroy( d2fctx *pd2fctx, d2fdsa *pd2fdsa );

This function destroys the specified data source argument.  You specify a pointer to the context in pd2fctx and a pointer to the data source argument you want to destroy in pd2fdsa.

d2fdsadu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2dsa *pd2fdsa_src, d2fdsa **ppd2fdsa_dst, text *new_name );

This function duplicates the specified data source argument.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the data source argument source in pd2fdsa_src, a handle for the function to store the destination in ppd2fdsa_dst, and a pointer for the name of the new data source argument (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified data source argument and store it at the ppd2fdsa_dst location.

d2fdsagb_GetBoolProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified data source argument.  You specify a pointer to the context in pd2fctx, the data source argument in pd2fdsa, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fdsagn_GetNumProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified data source argument.  You specify a pointer to the context in pd2fctx, the data source argument in pd2fdsa, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fdsagt_GetTextProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified data source argument.  You specify a pointer to the context in pd2fctx, the data source argument in pd2fdsa, the property number in pnum, and a handle to an array of characters for the function to store the text property value in pprp.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified data source argument in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fdsago_GetObjectProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified data source argument.  You specify a pointer to the context in pd2fctx, the data source argument in pd2fdsa, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fdsagp_GetBlobProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the data source argument object in pd2fdsa, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fdsasb_SetBoolProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum, boolean prp );

This function sets the value of the specified data source argument boolean property.  You specify a pointer to the context in pd2fctx, the data source argument in pd2fdsa, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fdsasn_SetNumProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum, number prp );

This function sets the value of the specified data source argument number property.  You specify a pointer to the context in pd2fctx, the data source argument in pd2fdsa, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fdsast_SetTextProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum, text *prp );

This function sets the value of the specified data source argument text property.  You specify a pointer to the context in pd2fctx, the data source argument in pd2fdsa, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fdsaso_SetObjectProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum, dvoid *prp );

This function sets the object of the specified data source argument property.  You specify a pointer to the context in pd2fctx, the data source argument in pd2fdsa, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fdsasp_SetBlobProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the data source argument object in pd2fdsa, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fdsahp_HasProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum );

This function queries the specified data source argument for the specified property. You specify a pointer to the context in pd2fctx, the data source argument in pd2fdsa, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fdsaip_InheritProp( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum );

This function enables the specified data source argument to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the data source argument object in pd2fdsa, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fdsaii_IspropInherited( d2fctx *pd2fctx, d2fdsa *pd2fdsa, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the data source argument object in pd2fdsa, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Datasource column object functions

  Related Topics

This section describes the functions of the Form Builder Open API Data Source Column object.

d2fdsccr_Create( d2fctx *pd2fctx, d2fob *parent, d2fdsc **ppd2fdsc, text *name );

This function creates a data source column.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new data source column object in parent, a handle for the function to store the newly-created object in ppd2fdsc, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new data source column in ppd2fdsc.

d2fdscde_Destroy( d2fctx *pd2fctx, d2fdsc *pd2fdsc );

This function destroys the specified data source column.  You specify a pointer to the context in pd2fctx and a pointer to the data source column you want to destroy in pd2fdsc.

d2fdscdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2dsc *pd2fdsc_src, d2fdsc **ppd2fdsc_dst, text *new_name );

This function duplicates the specified data source column.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the data source column source in pd2fdsc_src, a handle for the function to store the destination in ppd2fdsc_dst, and a pointer for the name of the new data source column (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified data source column and place it at the ppd2fdsc_dst location.

d2fdscgb_GetBoolProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified data source column.  You specify a pointer to the context in pd2fctx, the data source column in pd2fdsc, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fdscgn_GetNumProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified data source column.  You specify a pointer to the context in pd2fctx, the data source column in pd2fdsc, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fdscgt_GetTextProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified data source column.  You specify a pointer to the context in pd2fctx, the data source column in pd2fdsc, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified data source column in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fdscgo_GetObjectProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified data source column.  You specify a pointer to the context in pd2fctx, the data source column in pd2fdsc, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fdscgp_GetBlobProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the data source column object in pd2fdsc, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fdscsb_SetBoolProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum, boolean prp );

This function sets the value of the specified data source column boolean property.  You specify a pointer to the context in pd2fctx, the data source column in pd2fdsc, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fdscsn_SetNumProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum, number prp );

This function sets the value of the specified data source column number property.  You specify a pointer to the context in pd2fctx, the data source column in pd2fdsc, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fdscst_SetTextProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum, text *prp );

This function sets the value of the specified data source column text property.  You specify a pointer to the context in pd2fctx, the data source column in pd2fdsc, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fdscso_SetObjectProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum, dvoid *prp );

This function sets the object of the specified data source column property.  You specify a pointer to the context in pd2fctx, the data source column in pd2fdsc, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fdscsp_SetBlobProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the data source column object in pd2fdsc, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fdschp_HasProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum );

This function queries the specified data source column for the specified property. You specify a pointer to the context in pd2fctx, the data source column in pd2fdsc, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fdscip_InheritProp( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum );

This function enables the specified data source column to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the data source column object in pd2fdsc, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fdscii_IspropInherited( d2fctx *pd2fctx, d2fdsc *pd2fdsc, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the data source column object in pd2fdsc, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Editor object functions

  Related Topics

This section describes the functions of the Form Builder Open API Editor object.

d2fedtcr_Create( d2fctx *pd2fctx, d2fob *parent, d2fedt **ppd2fedt, text *name );

This function creates an editor.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new editor object in parent, a handle for the function to store the newly-created object in ppd2fedt, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new editor in ppd2fedt.

d2fedtde_Destroy( d2fctx *pd2fctx, d2fedt *pd2fedt );

This function destroys the specified editor.  You specify a pointer to the context in pd2fctx and a pointer to the editor you want to destroy in pd2fedt.

d2fedtdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2edt *pd2fedt_src, d2fedt **ppd2fedt_dst, text *new_name );

This function duplicates the specified editor.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the editor source in pd2fedt_src, a handle for the function to store the destination in ppd2fedt_dst, and a pointer for the name of the new editor (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified editor and place it at the ppd2fedt_dst location.

d2fedtgb_GetBoolProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified editor.  You specify a pointer to the context in pd2fctx, the editor in pd2fedt, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fedtgn_GetNumProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified editor.  You specify a pointer to the context in pd2fctx, the editor in pd2fedt, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fedtgt_GetTextProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified editor.  You specify a pointer to the context in pd2fctx, the editor in pd2fedt, the property number in pnum, and a pointer to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified editor in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fedtgo_GetObjectProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified editor.  You specify a pointer to the context in pd2fctx, the editor in pd2fedt, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fedtgp_GetBlobProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the editor object in pd2fedt, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fedtsb_SetBoolProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum, boolean prp );

This function sets the value of the specified editor boolean property.  You specify a pointer to the context in pd2fctx, the editor in pd2fedt, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fedtsn_SetNumProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum, number prp );

This function sets the value of the specified editor number property.  You specify a pointer to the context in pd2fctx, the editor in pd2fedt, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fedtst_SetTextProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum, text *prp );

This function sets the value of the specified editor text property.  You specify a pointer to the context in pd2fctx, the editor in pd2fedt, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fedtso_SetObjectProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum, dvoid *prp );

This function sets the object of the specified editor property.  You specify a pointer to the context in pd2fctx, the editor in pd2fedt, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fedtsp_SetBlobProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the editor object in pd2fedt, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fedthp_HasProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum );

This function queries the specified editor for the specified property. You specify a pointer to the context in pd2fctx, the editor in pd2fedt, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fedtip_InheritProp( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum );

This function enables the specified editor to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the editor object in pd2fedt, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fedtii_IspropInherited( d2fctx *pd2fctx, d2fedt *pd2fedt, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the editor object in pd2fedt, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fedtsc_SubClass( d2fctx *pd2fctx, d2fedt *pd2fedt, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified editor (pd2fedt) becomes a subclass of the specified parent (parent). You specify a pointer to the context in pd2fctx, a pointer to the editor in pd2fedt, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fnb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fedtis_IsSubclassed	( d2fctx *pd2fctx, d2fedt *pd2fedt );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the editor object in pd2fedt.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Form module object functions

  Related Topics

This section describes the functions of the Form Builder Open API Form Module object.

d2ffmdcr_Create( d2fctx *pd2fctx, d2fob *parent, d2ffmd **ppd2ffmd, text *name );

This function creates a form module.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the form module object in parent, a handle for the function to store the newly-created object in ppd2ffmd, and the name of the new object in name.

d2ffmdde_Destroy( d2fctx *pd2fctx, d2ffmd *pd2ffmd );

This function destroys the specified form module.  You specify a pointer to the context in pd2fctx and a pointer to the form module you want to destroy in pd2ffmd.

d2ffmddl_Delete( d2fctx *pd2fctx, text *name, boolean db );

This function deletes the specified form module.  You specify a pointer to the context in pd2fctx, a pointer to a text string for the name of the form module, and a boolean flag to indicate if the form module is to be deleted from a database (for example, an open library, a form module, or a menu module) in db.

If db is TRUE, the Forms API assumes that you want to delete the specified form module from a database; if db is FALSE, the Forms API searches the file system for the specified form module and then deletes it.

d2ffmddu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2fmd *pd2ffmd_src, d2ffmd **ppd2ffmd_dst, text *new_name );

This function duplicates the specified form module.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the form module source in pd2ffmd_src, a handle for the function to store the destination in ppd2ffmd_dst, and a pointer for the name of the new form module (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified form module and place it at the ppd2ffmd_dst location.

d2ffmdco_CompileObj ( d2fctx *pd2fctx, d2ffmd *pd2ffmd );

This function compiles all of the PL/SQL code associated with the specified form module. You specify a pointer to the context in pd2fctx and a pointer to the object you want to compile in pd2ffmd.

For example, you might use this function to compile all of the trigger objects attached to a form module, and all of the trigger objects attached to all item objects on a form module.

d2ffmdcf_CompileFile( d2fctx *pd2fctx, d2ffmd *pd2ffmd );

This function compiles a .fmb file and creates a generated .fmx file.  You specify the context (pd2fctx) and a pointer to a form module object (pd2ffmd).

d2ffmdld_Load ( d2fctx *pd2fctx, d2ffmd **ppd2ffmd, text *formname, boolean db );

This function loads the specified form module.  You specify the context (pd2fctx), a handle to a pointer for the function to use to store the form module (ppd2ffmd), the name of the form module (formname), and a boolean flag (db) to indicate if the form module is in a database.

If db is TRUE, the Forms API searches for the specified form module in the database.  Note that this assumes that you have connected to some database.  You must call d2fctx_Connect() before you load a form module from a database.

d2ffmdsv_Save ( d2fctx *pd2fctx, d2ffmd *pd2ffmd, text *formname, boolean db );

This function saves the specified form module.  You specify the context (pd2fctx), a pointer to the form module (pd2ffmd), the name of the specified form module (formname), and a boolean flag (db) that indicates if the form module is to be saved in a database.

If db is TRUE, the Forms API saves the specified form module in the database.  Note that this assumes that you have connected to some database previously.  You must call d2fctx_Connect() before you save a form module to a database.

Note that if you want to save the form module with the default name (the name supplied at create time), you must pass NULL as the text string in formname.  If you want to save the form module as some other name, then pass in that text string in formname.

d2ffmdfv_FileVersion ( d2fctx *pd2fctx, text *formname, boolean db, number *version );

This function returns the version of the form module. You specify the context (pd2fctx), the form module name (formname), a boolean flag (db) to indicate if the form module is in a database or the file system, and a pointer for the version returned by the function (version).

Note that you should call this function prior to calling the d2ffmdld_Load() function, since the file version will change once you load the form module.

d2ffmdgb_GetBoolProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified form module.  You specify a pointer to the context in pd2fctx, the form module in pd2ffmd, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2ffmdgn_GetNumProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified form module.  You specify a pointer to the context in pd2fctx, the form module in pd2ffmd, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2ffmdgt_GetTextProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified form module.  You specify a pointer to the context in pd2fctx, the form module in pd2ffmd, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified form module in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2ffmdgo_GetObjectProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified form module.  You specify a pointer to the context in pd2fctx, the form module in pd2ffmd, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2ffmdgp_GetBlobProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the form module object in pd2ffmd, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2ffmdsb_SetBoolProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum, boolean prp );

This function sets the value of the specified form module boolean property.  You specify a pointer to the context in pd2fctx, the form module in pd2ffmd, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2ffmdsn_SetNumProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum, number prp );

This function sets the value of the specified form module number property.  You specify a pointer to the context in pd2fctx, the form module in pd2ffmd, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2ffmdst_SetTextProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum, text *prp );

This function sets the value of the specified form module text property.  You specify a pointer to the context in pd2fctx, the form module in pd2ffmd, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2ffmdso_SetObjectProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum, dvoid *prp );

This function sets the object of the specified form module property.  You specify a pointer to the context in pd2fctx, the form module in pd2ffmd, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2ffmdsp_SetBlobProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the form module object in pd2ffmd, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2ffmdhp_HasProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum );

This function queries the specified form module for the specified property. You specify a pointer to the context in pd2fctx, the form module in pd2ffmd, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ffmdip_InheritProp( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum );

This function enables the specified form module to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the form module object in pd2ffmd, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ffmdii_IspropInherited( d2fctx *pd2fctx, d2ffmd *pd2ffmd, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the form module object in pd2ffmd, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Form parameter object functions

  Related Topics

This section describes the functions of the Form Builder Open API Form Parameter object.

d2ffpmcr_Create( d2fctx *pd2fctx, d2fob *parent, d2ffpm **ppd2ffpm, text *name );

This function creates a form parameter object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new form parameter object in parent, a handle for the function to store the newly-created object in ppd2ffpm, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new form parameter object in ppd2ffpm.

d2ffpmde_Destroy( d2fctx *pd2fctx, d2ffpm *pd2ffpm );

This function destroys the specified form parameter object.  You specify a pointer to the context in pd2fctx and a pointer to the form parameter object you want to destroy in pd2ffpm.

d2ffpmdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2fpm *pd2ffpm_src, d2ffpm **ppd2ffpm_dst, text *new_name );

This function duplicates the specified form parameter object.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the form parameter object source in pd2ffpm_src, a handle for the function to store the destination in ppd2ffpm_dst, and a pointer for the name of the new form parameter object (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified form parameter object and place it at the ppd2ffpm_dst location.

d2ffpmgb_GetBoolProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified form parameter object.  You specify a pointer to the context in pd2fctx, the form parameter object in pd2ffpm, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2ffpmgn_GetNumProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified form parameter object.  You specify a pointer to the context in pd2fctx, the form parameter object in pd2ffpm, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2ffpmgt_GetTextProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified form parameter object.  You specify a pointer to the context in pd2fctx, the form parameter object in pd2ffpm, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified form parameter object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2ffpmgo_GetObjectProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified form parameter object.  You specify a pointer to the context in pd2fctx, the form parameter object in pd2ffpm, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2ffpmgp_GetBlobProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the form parameter object in pd2ffpm, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2ffpmsb_SetBoolProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum, boolean prp );

This function sets the value of the specified form parameter object boolean property.  You specify a pointer to the context in pd2fctx, the form parameter object in pd2ffpm, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2ffpmsn_SetNumProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum, number prp );

This function sets the value of the specified form parameter object number property.  You specify a pointer to the context in pd2fctx, the form parameter object in pd2ffpm, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2ffpmst_SetTextProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum, text *prp );

This function sets the value of the specified form parameter object text property.  You specify a pointer to the context in pd2fctx, the form parameter object in pd2ffpm, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2ffpmso_SetObjectProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum, dvoid *prp );

This function sets the object of the specified form parameter object property.  You specify a pointer to the context in pd2fctx, the form parameter object in pd2ffpm, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2ffpmsp_SetBlobProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the form parameter object in pd2ffpm, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2ffpmhp_HasProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum );

This function queries the specified form parameter object for the specified property. You specify a pointer to the context in pd2fctx, the form parameter object in pd2ffpm, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ffpmip_InheritProp( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum );

This function enables the specified form parameter object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the form parameter object in pd2ffpm, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ffpmii_IspropInherited( d2fctx *pd2fctx, d2ffpm *pd2ffpm, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the form parameter object in pd2ffpm, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ffpmsc_SubClass( d2fctx *pd2fctx, d2ffpm *pd2ffpm, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified form parameter object (pd2ffpm) becomes a subclass of the specified parent (parent). You specify a pointer to the context in pd2fctx, a pointer to the form parameter object in pd2ffpm, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2ffpmis_IsSubclassed	( d2fctx *pd2fctx, d2ffpm *pd2ffpm );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the form parameter object in pd2ffpm.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Graphics object functions

  Related Topics

This section describes the functions of the Form Builder Open API Graphics object.

d2fgracr_Create( d2fctx *pd2fctx, d2fob *parent, d2fgra **ppd2fgra, text *name );

This function creates a graphics object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new graphics object in parent, a handle for the function to store the newly-created object in ppd2fgra, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new graphics object in ppd2fgra.

d2fgrade_Destroy( d2fctx *pd2fctx, d2fgra *pd2fgra );

This function destroys the specified graphics object.  You specify a pointer to the context in pd2fctx and a pointer to the graphics object you want to destroy in pd2fgra.

d2fgradu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2gra *pd2fgra_src, d2fgra **ppd2fgra_dst, text *new_name );

This function duplicates the specified graphics object.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the graphics object source in pd2fgra_src, a handle for the function to store the destination in ppd2fgra_dst, and a pointer for the name of the new graphics object (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified graphics object and place it at the ppd2fgra_dst location.

d2fgragb_GetBoolProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified graphics object.  You specify a pointer to the context in pd2fctx, the graphics object in pd2fgra, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fgragn_GetNumProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified graphics object.  You specify a pointer to the context in pd2fctx, the graphics object in pd2fgra, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fgragt_GetTextProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified graphics object.  You specify a pointer to the context in pd2fctx, the graphics object in pd2fgra, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified graphics object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fgrago_GetObjectProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified graphics object.  You specify a pointer to the context in pd2fctx, the graphics object in pd2fgra, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fgragp_GetBlobProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the graphics object in pd2fgra, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fgrasb_SetBoolProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum, boolean prp );

This function sets the value of the specified graphics object boolean property.  You specify a pointer to the context in pd2fctx, the graphics object in pd2fgra, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fgrasn_SetNumProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum, number prp );

This function sets the value of the specified graphics object number property.  You specify a pointer to the context in pd2fctx, the graphics object in pd2fgra, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fgrast_SetTextProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum, text *prp );

This function sets the value of the specified graphics object text property.  You specify a pointer to the context in pd2fctx, the graphics object in pd2fgra, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fgraso_SetObjectProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum, dvoid *prp );

This function sets the object of the specified graphics object property.  You specify a pointer to the context in pd2fctx, the graphics object in pd2fgra, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fgrasp_SetBlobProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the graphics object in pd2fgra, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fgrahp_HasProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum );

This function queries the specified graphics object for the specified property. You specify a pointer to the context in pd2fctx, the graphics object in pd2fgra, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fgraip_InheritProp( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum );

This function enables the specified graphics object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the graphics object in pd2fgra, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fgraii_IspropInherited( d2fctx *pd2fctx, d2fgra *pd2fgra, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the graphics object in pd2fgra, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fgrasc_SubClass( d2fctx *pd2fctx, d2fgra *pd2fgra, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified graphics object (pd2fgra) becomes a subclass of the specified parent (parent). You specify a pointer to the context in pd2fctx, a pointer to the graphics object in pd2fgra, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fgrais_IsSubclassed	( d2fctx *pd2fctx, d2fgra *pd2fgra );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the graphics object in pd2fgra.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Item object functions

  Related Topics

This section describes the functions of the Form Builder Open API Item object.

d2fitmcr_Create( d2fctx *pd2fctx, d2fob *parent, d2fitm **ppd2fitm, text *name );

This function creates an item object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new item object in parent, a handle for the function to store the newly-created object in ppd2fitm, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new item in ppd2fitm.

d2fitmde_Destroy( d2fctx *pd2fctx, d2fitm *pd2fitm );

This function destroys the specified item.  You specify a pointer to the context in pd2fctx and a pointer to the item you want to destroy in pd2fitm.

d2fitmdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2itm *pd2fitm_src, d2fitm **ppd2fitm_dst, text *new_name );

This function duplicates the specified item.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the item source in pd2fitm_src, a handle for the function to store the destination in ppd2fitm_dst, and a pointer for the name of the new item (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified item and place it at the ppd2fitm_dst location.

d2fitmco_CompileObj( d2fctx *pd2fctx, d2fitm *pd2fitm );

This function compiles all of the PL/SQL code associated with the specified item. You specify a pointer to the context in pd2fctx and a pointer to the object you want to compile in pd2fitm.

For example, you might use this function to compile all of the trigger objects attached to an item.

d2fitmile_InsertListElem( d2fctx *pd2fctx, d2fitm *pd2fitm, number index, text *label, text *value );

This function inserts the specified item and its associated value into the list.  You specify a pointer to the context in pd2fctx, a pointer to the item object in pd2fitm, the index of the list element (into the list of elements) in index, a pointer to the name of the list element in label, and a pointer to the value of the list element in value.

Note that this function is valid only for item objects of type “List Element”.

This function returns D2FS_SUCCESS if it inserts the specified list element into the list.

d2fitmile_DeleteListElem( d2fctx *pd2fctx, d2fitm *pd2fitm, number index );

This function deletes the specified item and its associated value from the list.  You specify a pointer to the context in pd2fctx, a pointer to the item object in pd2fitm, and the index of the list element into the list of elements in index.

Note that this function is valid only for item objects of type “List Element”.

This function returns D2FS_SUCCESS if it deletes the specified list element from the list.

d2fitmile_GetListElem( d2fctx *pd2fctx, d2fitm *pd2fitm, number index, text **label, text **value );

This function retrieves the name and value for the specified list element. You specify a pointer to the context in pd2fctx, a pointer to the item object in pd2fitm, the index of the list element into the list of elements in index, a handle to a pointer for the name of the list element in label, and a handle to a pointer for the value of the list element in value.

Note that this function is valid only for item objects of type “List Element”.

This function returns D2FS_SUCCESS if it stores the name and value of the specified list element in label and text, respectively.

d2fitmgb_GetBoolProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified item.  You specify a pointer to the context in pd2fctx, the item in pd2fitm, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fitmgn_GetNumProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified item.  You specify a pointer to the context in pd2fctx, the item in pd2fitm, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fitmgt_GetTextProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified item.  You specify a pointer to the context in pd2fctx, the item in pd2fitm, the property number in pnum, and a pointer to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified item in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fitmgo_GetObjectProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified item.  You specify a pointer to the context in pd2fctx, the item in pd2fitm, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fitmgp_GetBlobProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the item object in pd2fitm, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fitmsb_SetBoolProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum, boolean prp );

This function sets the value of the specified item boolean property.  You specify a pointer to the context in pd2fctx, the item in pd2fitm, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fitmsn_SetNumProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum, number prp );

This function sets the value of the specified item number property.  You specify a pointer to the context in pd2fctx, the item in pd2fitm, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fitmst_SetTextProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum, text *prp );

This function sets the value of the specified item text property.  You specify a pointer to the context in pd2fctx, the item in pd2fitm, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fitmso_SetObjectProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum, dvoid *prp );

This function sets the object of the specified item property.  You specify a pointer to the context in pd2fctx, the item in pd2fitm, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fitmsp_SetBlobProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the item object in pd2fitm, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fitmhp_HasProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum );

This function queries the specified item for the specified property. You specify a pointer to the context in pd2fctx, the item in pd2fitm, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fitmip_InheritProp( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum );

This function enables the specified item to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the item object in pd2fitm, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fitmii_IspropInherited( d2fctx *pd2fctx, d2fitm *pd2fitm, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the item object in pd2fitm, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fitmsc_SubClass( d2fctx *pd2fctx, d2fitm *pd2fitm, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified item (pd2fitm) becomes a subclass of the specified parent (parent). You specify a pointer to the context in pd2fctx, a pointer to the item in pd2fitm, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fitmis_IsSubclassed	( d2fctx *pd2fctx, d2fitm *pd2fitm );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the item object in pd2fitm.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


LOV column mapping object functions

  Related Topics

This section describes the functions of the Form Builder Open API LOV Column Mapping object.

d2flcmcr_Create( d2fctx *pd2fctx, d2fob *parent, d2flcm **ppd2flcm, text *name );

This function creates an LOV column mapping object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new LOV column mapping object in parent, a handle for the function to store the newly-created object in ppd2flcm, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new LOV column mapping in ppd2flcm.

d2flcmde_Destroy( d2fctx *pd2fctx, d2flcm *pd2flcm );

This function destroys the specified LOV column mapping.  You specify a pointer to the context in pd2fctx and a pointer to the LOV column mapping object you want to destroy in pd2flcm.

d2flcmdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2lcm *pd2flcm_src, d2flcm **ppd2flcm_dst, text *new_name );

This function duplicates the specified LOV column mapping.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the LOV column mapping source in pd2flcm_src, a handle for the function to store the destination in ppd2flcm_dst, and a pointer for the name of the new LOV column mapping (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified LOV column mapping and place it at the ppd2flcm_dst location.

d2flcmgb_GetBoolProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified LOV column mapping.  You specify a pointer to the context in pd2fctx, the LOV column mapping in pd2flcm, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2flcmgn_GetNumProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified LOV column mapping.  You specify a pointer to the context in pd2fctx, the LOV column mapping in pd2flcm, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2flcmgt_GetTextProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified LOV column mapping.  You specify a pointer to the context in pd2fctx, the LOV column mapping in pd2flcm, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified LOV column mapping in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2flcmgo_GetObjectProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified LOV column mapping.  You specify a pointer to the context in pd2fctx, the LOV column mapping in pd2flcm, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2flcmgp_GetBlobProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the LOV column mapping object in pd2flcm, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2flcmsb_SetBoolProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum, boolean prp );

This function sets the value of the specified LOV column mapping boolean property.  You specify a pointer to the context in pd2fctx, the LOV column mapping in pd2flcm, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2flcmsn_SetNumProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum, number prp );

This function sets the value of the specified LOV column mapping number property.  You specify a pointer to the context in pd2fctx, the LOV column mapping in pd2flcm, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2flcmst_SetTextProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum, text *prp );

This function sets the value of the specified LOV column mapping text property.  You specify a pointer to the context in pd2fctx, the LOV column mapping in pd2flcm, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2flcmso_SetObjectProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum, dvoid *prp );

This function sets the object of the specified LOV column mapping property.  You specify a pointer to the context in pd2fctx, the LOV column mapping in pd2flcm, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2flcmsp_SetBlobProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the LOV column mapping object in pd2flcm, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2flcmhp_HasProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum );

This function queries the specified LOV column mapping for the specified property. You specify a pointer to the context in pd2fctx, the LOV column mapping in pd2flcm, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2flcmip_InheritProp( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum );

This function enables the specified LOV column mapping to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the LOV column mapping object in pd2flcm, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2flcmii_IspropInherited( d2fctx *pd2fctx, d2flcm *pd2flcm, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the LOV column mapping object in pd2flcm, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


List of values (LOV) object functions

  Related Topics

This section describes the functions of the Form Builder Open API List of Values (LOV) object.

d2flovcr_Create( d2fctx *pd2fctx, d2fob *parent, d2flov **ppd2flov, text *name );

This function creates a list of values (LOV).  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new LOV object in parent, a handle for the function to store the newly-created object in ppd2flov, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new LOV in ppd2flov.

d2flovde_Destroy( d2fctx *pd2fctx, d2flov *pd2flov );

This function destroys the specified list of values (LOV).  You specify a pointer to the context in pd2fctx and a pointer to the LOV object you want to destroy to be destroyed in pd2flov.

d2flovdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2lov *pd2flov_src, d2flov **ppd2flov_dst, text *new_name );

This function duplicates the specified list of values (LOV).  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the LOV source in pd2flov_src, , a handle for the function to store the destination in ppd2flov_dst, and a pointer for the name of the new LOV in new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified LOV and place it at the ppd2fitm_dst location.

d2flovgb_GetBoolProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified list of values (LOV).  You specify a pointer to the context in pd2fctx, the LOV in pd2flov, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2flovgn_GetNumProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified list of values (LOV).  You specify a pointer to the context in pd2fctx, the LOV in pd2flov, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2flovgt_GetTextProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified list of values (LOV).  You specify a pointer to the context in pd2fctx, the LOV in pd2flov, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified LOV in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2flovgo_GetObjectProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified list of values (LOV).  You specify a pointer to the context in pd2fctx, the LOV in pd2flov, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2flovgp_GetBlobProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the list of values (LOV) object in pd2flov, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2flovsb_SetBoolProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum, boolean prp );

This function sets the value of the specified LOV boolean property.  You specify a pointer to the context in pd2fctx, the LOV in pd2flov, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2flovsn_SetNumProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum, number prp );

This function sets the value of the specified list of values (LOV) number property.  You specify a pointer to the context in pd2fctx, the LOV in pd2flov, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2flovst_SetTextProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum, text *prp );

This function sets the value of the specified list of values (LOV) text property.  You specify a pointer to the context in pd2fctx, the LOV in pd2flov, the property number in pnum, and a pointer to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2flovso_SetObjectProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum, dvoid *prp );

This function sets the object of the specified list of values (LOV) property.  You specify a pointer to the context in pd2fctx, the LOV in pd2flov, a property number in pnum, and a pointer to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2flovsp_SetBlobProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the list of values (LOV) object in pd2flov, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2flovhp_HasProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum );

This function queries the specified list of values (LOV) for the specified property. You specify a pointer to the context in pd2fctx, the LOV in pd2flov, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2flovip_InheritProp( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum );

This function enables the specified list of values (LOV) to inherit the specified property. You specify a pointer to the context in pd2fctx, the LOV in pd2flov, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2flovii_IspropInherited( d2fctx *pd2fctx, d2flov *pd2flov, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the LOV object in pd2flov, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2flovsc_SubClass( d2fctx *pd2fctx, d2flov *pd2flov, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified list of values (LOV) (pd2flov) becomes a subclass of the specified parent (parent). You specify a pointer to the context in pd2fctx, a pointer to the list of values in pd2flov, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2flovis_IsSubclassed	( d2fctx *pd2fctx, d2flov *pd2flov );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the list of values (LOV) object in pd2flov.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Menu object functions

  Related Topics

This section describes the functions of the Form Builder Open API Menu object.

d2fmnucr_Create( d2fctx *pd2fctx, d2fob *parent, d2fmnu **ppd2fmnu, text *name );

This function creates a menu.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new menu object in parent, a handle for the function to store the newly-created object in ppd2fmnu, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new menu in ppd2fmnu.

d2fmnude_Destroy( d2fctx *pd2fctx, d2fmnu *pd2fmnu );

This function destroys the specified menu.  You specify a pointer to the context in pd2fctx and a pointer to the menu you want to destroy in pd2fmnu.

d2fmnudu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2mnu *pd2fmnu_src, d2fmnu **ppd2fmnu_dst, text *new_name );

This function duplicates the specified menu.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the menu source in pd2fmnu_src, , a handle for the function to store the destination in ppd2fmnu_dst, and a pointer for the name of the new menu (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified menu and place it at the ppd2fmnu_dst location.

d2fmnugb_GetBoolProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified menu.  You specify a pointer to the context in pd2fctx, the menu in pd2fmnu, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fmnugn_GetNumProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified menu.  You specify a pointer to the context in pd2fctx, the menu in pd2fmnu, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fmnugt_GetTextProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified menu.  You specify a pointer to the context in pd2fctx, the menu in pd2fmnu, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified menu in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fmnugo_GetObjectProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified menu.  You specify a pointer to the context in pd2fctx, the menu in pd2fmnu, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fmnugp_GetBlobProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the menu object in pd2fmnu, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fmnusb_SetBoolProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum, boolean prp );

This function sets the value of the specified menu boolean property.  You specify a pointer to the context in pd2fctx, the menu in pd2fmnu, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fmnusn_SetNumProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum, number prp );

This function sets the value of the specified menu number property.  You specify a pointer to the context in pd2fctx, the menu in pd2fmnu, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fmnust_SetTextProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum, text *prp );

This function sets the value of the specified menu text property.  You specify a pointer to the context in pd2fctx, the menu in pd2fmnu, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fmnuso_SetObjectProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum, dvoid *prp );

This function sets the object of the specified menu property.  You specify a pointer to the context in pd2fctx, the menu in pd2fmnu, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fmnusp_SetBlobProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the menu object in pd2fmnu, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fmnuhp_HasProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum );

This function queries the specified menu for the specified property. You specify a pointer to the context in pd2fctx, the menu in pd2fmnu, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmnuip_InheritProp( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum );

This function enables the specified menu to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the menu in pd2fmnu, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmnuii_IspropInherited( d2fctx *pd2fctx, d2fmnu *pd2fmnu, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the menu object in pd2fmnu, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmnusc_SubClass( d2fctx *pd2fctx, d2fmnu *pd2fmnu, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified menu (pd2fmnu) becomes a subclass of the specified parent (parent). You specify a pointer to the context in pd2fctx, a pointer to the menu in pd2fmnu, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fmnuis_IsSubclassed	( d2fctx *pd2fctx, d2fmnu *pd2fmnu );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the menu object in pd2fmnu.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Menu module object functions

  Related Topics

This section describes the functions of the Form Builder Open API Menu Module object.

d2fmmdcr_Create( d2fctx *pd2fctx, d2fob *parent, d2fmmd **ppd2fmmd, text *name );

This function creates a menu module.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new menu module object in parent, a handle for the function to store the newly-created object in ppd2fmmd, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new menu module in ppd2fmmd.

d2fmmdde_Destroy( d2fctx *pd2fctx, d2fmmd *pd2fmmd );

This function destroys the specified menu module.  You specify a pointer to the context in pd2fctx and a pointer to the menu module you want to destroy in pd2fmmd.

d2fmmddl_Delete( d2fctx *pd2fctx, text *name, boolean db );

This function deletes the specified menu module.  You specify a pointer to the context in pd2fctx, the name of the menu module in name, and a boolean flag to indicate if the menu module is part of a database in db.

If db is TRUE, the Forms API assumes that you want to delete the specified menu module (the name passed in name) from a database.  If db is FALSE, the menu module is part of a file system and the Forms API searches the file system for the specified menu module and then deletes it.

d2fmmddu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2mmd *pd2fmmd_src, d2fmmd **ppd2fmmd_dst, text *new_name );

This function duplicates the specified menu module.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the menu module source in pd2fmmd_, a handle for the function to store the destination in ppd2fmmd_dst, and a pointer for the name of the new menu module (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified menu module and place it at the ppd2fmmd_dst location.

d2fmmdco_CompileObj( d2fctx *pd2fctx, d2fmmd *pd2fmmd );

This function compiles all of the PL/SQL code associated with the specified menu module. You specify a pointer to the context in pd2fctx and a pointer to the object you want to compile in pd2fmmd.

For example, you might use this function to compile all of the trigger objects attached to a menu module, and all of the trigger objects attached to all item objects in a menu module.

d2fmmdcf_CompileFile( d2fctx *pd2fctx, d2fmmd *pd2fmmd );

This function compiles an FMB file and creates a generated FMX file.  You specify the context (pd2fctx) and a pointer to a menu module (pd2fmmd).

d2fmmdld_Load( d2fctx *pd2fctx, d2fmmd **ppd2fmmd, text *menuname, boolean db );

This function loads the specified menu module.  You specify the context (pd2fctx), a handle to a pointer for the function to use to store the menu module (ppd2fmmd), the name of the menu module (menuname), and a boolean flag (db) to indicate if the menu module is in a database.

If you set db to TRUE, the Forms API searches for the specified menu module in the database.  Note that this assumes that you have connected to some database.  You must call d2fctx_Connect() before you load a menu module from a database.

d2fmmdsv_Save( d2fctx *pd2fctx, d2fmmd *pd2fmmd, text *menuname, boolean db );

This function saves the specified menu module.  You specify the context (pd2fctx), a pointer to the menu module (pd2fmmd), the name of the specified menu module (menuname), and a boolean flag (db) that indicates if the menu module is to be stored in a database.

If you set db to TRUE, the Forms API saves the specified menu module in the database.  Note that this assumes that you have connected to some database previously.  You must call d2fctx_Connect() before you save a menu module to a database.

If you want to save the menu module with the default name (the name supplied at create time), you must pass NULL as the text string in menuname.  If you want to save the form module as some other name, then pass in that text string in menuname.

d2fmmdfv_FileVersion( d2fctx *pd2fctx, text *menuname, boolean db, number version );

This function returns the version of the menu module. You specify the context (pd2fctx), the menu module name (menuname), a boolean flag (db) to indicate if the menu module is in a database or the file system, and a pointer for the version returned by the function (version).

Note that you should call this function prior to calling the d2fmmdld_Load() function, since the file version will change once you load the menu module.

d2fmmdar_AddRole( d2fctx *pd2fctx, d2fmmd *pd2fmmd, number index, text *role_name );

This function adds a security “role” to the specified menu module.  You specify a pointer to the context in pd2fctx, a pointer to the menu module in pd2fmmd, the index into the role list where the Forms API will store this role in index, and the name of the role to be added to the list in role_name.

The “AddRole”, “RemoveRole”, and “GetRole” functions enable you to specify which security roles have access to a particular menu module.

Note that there is a Forms API property called D2FP_ROLE_COUNT that you can use to retrieve the count of all roles for a specific menu module.

Note that if you do not specify the menu module roles at the module level, you won’t have access to them at the menu item level.

d2fmmdrr_RemoveRole( d2fctx *pd2fctx, d2fmmd *pd2fmmd, number index );

This function removes the specified security “role” from the specified menu module.  You specify a pointer to the context in pd2fctx, a pointer to the menu module in pd2fmmd, and the index into the role list where the Forms API will remove this role in index.

The “AddRole”, “RemoveRole”, and “GetRole” functions enable you to specify which security roles have access to a particular menu module.

Note that there is a Forms API property called D2FP_ROLE_COUNT that you can use to retrieve the count of all roles for a specific menu module.

Note that if you do not specify the menu module roles at the module level, you won’t have access to them at the menu item level.

d2fmmdgr_GetRole( d2fctx *pd2fctx, pd2fmmd *pd2fmmd, number index, text **role_name );

This function retrieves the specified security role from a menu module. You specify a pointer to the context in pd2fctx, a pointer to the menu module in pd2fmmd, the index into the role list which the Forms API uses to retrieve this role in index, and a handle for the function to store the name of the role in role_name.

The “AddRole”, “RemoveRole”, and “GetRole” functions enable you to specify which security roles have access to a particular menu module.

Note that there is a Forms API property called D2FP_ROLE_COUNT that you can use to retrieve the count of all roles for a specific menu module.

Note that if you do not specify the menu module roles at the module level, you won’t have access to them at the menu item level.

d2fmmdgb_GetBoolProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified menu module.  You specify a pointer to the context in pd2fctx, the menu module in pd2fmmd, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fmmdgn_GetNumProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified menu module.  You specify a pointer to the context in pd2fctx, the menu module in pd2fmmd, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fmmdgt_GetTextProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified menu module.  You specify a pointer to the context in pd2fctx, the menu module in pd2fmmd, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified menu module in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fmmdgo_GetObjectProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified menu module.  You specify a pointer to the context in pd2fctx, the menu module in pd2fmmd, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fmmdgp_GetBlobProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the menu module object in pd2fmmd, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fmmdsb_SetBoolProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum, boolean prp );

This function sets the value of the specified menu module boolean property.  You specify a pointer to the context in pd2fctx, the menu module in pd2fmmd, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fmmdsn_SetNumProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum, number prp );

This function sets the value of the specified menu module number property.  You specify a pointer to the context in pd2fctx, the menu module in pd2fmmd, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fmmdst_SetTextProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum, text *prp );

This function sets the value of the specified menu module text property.  You specify a pointer to the context in pd2fctx, the menu module in pd2fmmd, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fmmdso_SetObjectProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum, dvoid *prp );

This function sets the object of the specified menu module property.  You specify a pointer to the context in pd2fctx, the menu module in pd2fmmd, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fmmdsp_SetBlobProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the menu module object in pd2fmmd, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fmmdhp_HasProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum );

This function queries the specified menu module for the specified property. You specify a pointer to the context in pd2fctx, the menu module in pd2fmmd, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmmdip_InheritProp( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum );

This function enables the specified menu module to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the menu module in pd2fmmd, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmmdii_IspropInherited( d2fctx *pd2fctx, d2fmmd *pd2fmmd, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the menu module object in pd2fmmd, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Menu item object functions

  Related Topics

This section describes the functions of the Form Builder Open API Menu Item object.

d2fmnicr_Create( d2fctx *pd2fctx, d2fob *parent, d2fmni **ppd2fmni, text *name );

This function creates a menu item.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new menu item object in parent, a handle for the function to store the newly-created object in ppd2fmni, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new menu item in ppd2fmni.

d2fmnide_Destroy( d2fctx *pd2fctx, d2fmni *pd2fmni );

This function destroys the specified menu item.  You specify a pointer to the context in pd2fctx and a pointer to the menu item you want to destroy in pd2fmni.

d2fmnidu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2mni *pd2fmni_src, d2fmni **ppd2fmni_dst, text *new_name );

This function duplicates the specified menu item.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the menu item source in pd2fmni_src, , a handle for the function to store the destination in ppd2fmni_dst, and a pointer for the name of the new menu item (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified menu item and place it at the ppd2fmni_dst location.

d2fmnico_CompileObj( d2fctx *pd2fctx, d2fmni *pd2fmni );

This function compiles all of the PL/SQL code associated with the specified menu item. You specify a pointer to the context in pd2fctx and a pointer to the object you want to compile in pd2fmni.

For example, you might use this function to compile all of the trigger objects attached to a menu item.

d2fmnild_Load( d2fctx *pd2fctx, d2fmni **ppd2fmni, text *menuname, boolean db );

This function loads the specified menu item.  You specify the context (pd2fctx), a handle to a pointer for the function to use to store the menu item (ppd2fmni), the name of the menu item (menuname), and a boolean flag (db) to indicate if the menu item is in a database.

If you set db to TRUE, the Forms API searches for the specified menu item in the database.  Note that this assumes that you have connected to some database.  You must call d2fctx_Connect() before you load a form module from a database.

d2fmniar_AddRole( d2fctx *pd2fctx, d2fmni *pd2fmni, number index, text *role_name );

This function adds a security “role” to the specified menu item.  You specify a pointer to the context in pd2fctx, a pointer to the menu item in pd2fmni, the index into the role list where the Forms API will store this role in index, and the name of the role to be added to the list in role_name.

The “AddRole”, “RemoveRole”, and “GetRole” functions enable you to specify which security roles have access to a particular menu item.

Note that there is a Forms API property called D2FB_ROLE_COUNT that you can use to retrieve the count of all roles for a specific menu item.

Note that if you do not specify the menu module roles at the module level, you won’t have access to them at the menu item level.

d2fmnirr_RemoveRole( d2fctx *pd2fctx, d2fmni *pd2fmni, number index );

This function removes the specified security “role” from the specified menu item.  You specify a pointer to the context in pd2fctx, a pointer to the menu module in pd2fmni, and the index into the role list where the Forms API will remove this role in index.

The “AddRole”, “RemoveRole”, and “GetRole” functions enable you to specify which security roles have access to a particular menu item.

Note that there is a Forms API property called D2FB_ROLE_COUNT that you can use to retrieve the count of all roles for a specific menu item.

Note that if you do not specify the menu module roles at the module level, you won’t have access to them at the menu item level.

d2fmnigr_GetRole( d2fctx *pd2fctx, pd2fmni *pd2fmni, number index, text **role_name );

This function retrieves the specified security role from a menu item. You specify a pointer to the context in pd2fctx, a pointer to the menu module in pd2fmni, the index into the role list which the Forms API uses to retrieve this role in index, and a handle for the function to store the name of the role in role_name.

The “AddRole”, “RemoveRole”, and “GetRole” functions enable you to specify which security roles have access to a particular menu item.

Note that there is a Forms API property called D2FB_ROLE_COUNT that you can use to retrieve the count of all roles for a specific menu item.

Note that if you do not specify the menu module roles at the module level, you won’t have access to them at the menu item level.

d2fmnigb_GetBoolProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified menu item.  You specify a pointer to the context in pd2fctx, the menu item in pd2fmni, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fmnign_GetNumProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified menu item.  You specify a pointer to the context in pd2fctx, the menu item in pd2fmni, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fmnigt_GetTextProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified menu item.  You specify a pointer to the context in pd2fctx, the menu item in pd2fmni, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified menu item in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fmnigo_GetObjectProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified menu item.  You specify a pointer to the context in pd2fctx, the menu item in pd2fmni, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fmnigp_GetBlobProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the menu item object in pd2fmni, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fmnisb_SetBoolProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum, boolean prp );

This function sets the value of the specified menu item boolean property.  You specify a pointer to the context in pd2fctx, the menu item in pd2fmni, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fmnisn_SetNumProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum, number prp );

This function sets the value of the specified menu item number property.  You specify a pointer to the context in pd2fctx, the menu item in pd2fmni, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fmnist_SetTextProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum, text *prp );

This function sets the value of the specified menu item text property.  You specify a pointer to the context in pd2fctx, the menu item in pd2fmni, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fmniso_SetObjectProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum, dvoid *prp );

This function sets the object of the specified menu item property.  You specify a pointer to the context in pd2fctx, the menu item in pd2fmni, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fmnisp_SetBlobProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the menu item object in pd2fmni, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fmnihp_HasProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum );

This function queries the specified menu item for the specified property. You specify a pointer to the context in pd2fctx, the menu item in pd2fmni, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmniip_InheritProp( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum );

This function enables the specified menu item to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the menu item object in pd2fmni, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmniii_IspropInherited( d2fctx *pd2fctx, d2fmni *pd2fmni, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the menu item object in pd2fmni, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmmisc_SubClass( d2fctx *pd2fctx, d2fmmi *pd2fmmi, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified menu item (pd2fmmi) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the menu item in pd2fmni, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fmmiis_IsSubclassed	( d2fctx *pd2fctx, d2fmmi *pd2fmni );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the menu object in pd2fmnu.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Menu parameter object functions

  Related Topics

This section describes the functions of the Form Builder Open API Menu Parameter object.

d2fmpmcr_Create( d2fctx *pd2fctx, d2fob *parent, d2fmpm **ppd2fmpm, text *name );

This function creates a menu parameter object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new menu parameter object in parent, a handle for the function to store the newly-created object in ppd2fmpm, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new menu parameter object in ppd2fmpm.

d2fmpmde_Destroy( d2fctx *pd2fctx, d2fmpm *pd2fmpm );

This function destroys the specified menu parameter object.  You specify a pointer to the context in pd2fctx and a pointer to the menu parameter object you want to destroy in pd2fmpm.

d2fmpmdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2mpm *pd2fmpm_src, d2fmpm **ppd2fmpm_dst, text *new_name );

This function duplicates the specified menu parameter object.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the menu parameter object source in pd2fmpm_src, a handle for the function to store the destination in ppd2fmpm_dst, and a pointer for the name of the new menu parameter object (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified menu parameter object and place it at the ppd2fmpm_dst location.

d2fmpmaam_AddAssocMenu( d2fctx *pd2fctx, d2fmpm *pd2fmpm, number index, text *menu_name);

This function adds the associated menu to the specified menu parameter object.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, the index into the menu list where the Forms API stores this associated menu in index, and the name of the menu to be added to the list in menu_name.

Note that there is a Forms API property called D2FP_ASSOC_MENU_COUNT that you can use to retrieve the count of all associated menus for a specific menu parameter object.

d2fmpmram_RemoveAssocMenu( d2fctx *pd2fctx, d2fmpm *pd2fmpm, number index );

This function removes the associated menu from the specified menu parameter object.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, and the index into the menu list where the Forms API finds and removes this associated menu in index.

Note that there is a Forms API property called D2FP_ASSOC_MENU_COUNT that you can use to retrieve the count of all associated menus for a specific menu parameter object.

d2fmpmgam_GetAssocMenu( d2fctx *pd2fctx, d2fmpm *pd2fmpm, number index, text **menu_name );

This function retrieves the associated menu for the specified menu parameter object.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, the index into the menu list where the Forms API finds this associated menu in index, and a handle to menu_name for the function to store the name of the menu to be retrieved.

Note that there is a Forms API property called D2FP_ASSOC_MENU_COUNT that you can use to retrieve the count of all associated menus for a specific menu parameter object.

d2fmpmgb_GetBoolProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified menu parameter object.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fmpmgn_GetNumProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified menu parameter object.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fmpmgt_GetTextProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified menu parameter object.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, the property number in pnum, and a pointer to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified menu parameter object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fmpmgo_GetObjectProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified menu parameter object.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fmpmgp_GetBlobProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the menu parameter object in pd2fmpm, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fmpmsb_SetBoolProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum, boolean prp );

This function sets the value of the specified menu parameter object boolean property.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fmpmsn_SetNumProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum, number prp );

This function sets the value of the specified menu parameter object number property.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fmpmst_SetTextProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum, text *prp );

This function sets the value of the specified menu parameter object text property.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fmpmso_SetObjectProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum, dvoid *prp );

This function sets the object of the specified menu parameter object property.  You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fmpmsp_SetBlobProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the menu parameter object in pd2fmpm, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fmpmhp_HasProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum );

This function queries the specified menu parameter object for the specified property. You specify a pointer to the context in pd2fctx, the menu parameter object in pd2fmpm, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmpmip_InheritProp( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum );

This function enables the specified menu parameter object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the menu parameter object in pd2fmpm, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmpmii_IspropInherited( d2fctx *pd2fctx, d2fmpm *pd2fmpm, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the menu parameter object in pd2fmpm, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fmpmsc_SubClass( d2fctx *pd2fctx, d2fmpm *pd2fmpm, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified menu parameter object (pd2fmpm) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the menu parameter object in pd2fmpm, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fmpmis_IsSubclassed	( d2fctx *pd2fctx, d2fmpm *pd2fmpm );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the menu parameter object in pd2fmpm.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Object (generic object) functions

  Related Topics

This section describes the functions of the Form Builder Open API Object (generic object).

d2fobfo_FindObj( d2fctx *pd2fctx, d2fob *owner, text *name, d2fotyp objtyp, d2fob **ppd2fob );

This function returns the specified object.  You specify a pointer to the context in pd2fctx, a pointer to the object’s parent in parent, a pointer to a text string for the name of the specified object in name, the object type in objtyp, and a handle for the function to return the object in ppd2fob.

For example, if you want to find a particular trigger object under a block, you need to pass in the block as the  parent, the name of the specific trigger object, and D2FFO_TRIGGER (the object type).

d2fobmv_Move( d2fctx *pd2fctx, d2fob *pd2fob, d2fob *pd2fob_nxt );

This function  moves the specified object around the list of objects.  You specify a pointer to the context in pd2fctx, a pointer to the object in pd2fob, and the object that should directly follow this object (once moved) in pd2fob_nxt.

Note that if you want to place the specified object at the top of the list, pass the first object in pd2fob_nxt; if you want to place the object at the end of the list, set pd2fob_nxt to NULL.

d2fobgb_GetBoolProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified object (generic object).  You specify a pointer to the context in pd2fctx, the object in pd2fob, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fobgn_GetNumProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified object.  You specify a pointer to the context in pd2fctx, the object in pd2fob, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fobgt_GetTextProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified object.  You specify a pointer to the context in pd2fctx, the object in pd2fob, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fobgo_GetObjectProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified object.  You specify a pointer to the context in pd2fctx, the object in pd2fob, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fobgp_GetBlobProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the specified object in pd2fob, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fobsb_SetBoolProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum, boolean prp );

This function sets the value of the specified object boolean property.  You specify a pointer to the context in pd2fctx, the object in pd2fob, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fobsn_SetNumProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum, number prp );

This function sets the value of the specified object number property.  You specify a pointer to the context in pd2fctx, the object in pd2fob, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fobst_SetTextProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum, text *prp );

This function sets the value of the specified object text property.  You specify a pointer to the context in pd2fctx, the object in pd2fob, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fobso_SetObjectProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum, dvoid *prp );

This function sets the object of the specified object property.  You specify a pointer to the context in pd2fctx, the object in pd2fob, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fobsp_SetBlobProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the specified object in pd2fob, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fobhp_HasProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum );

This function queries the specified object for the specified property. You specify a pointer to the context in pd2fctx, the object in pd2fob, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fobip_InheritProp( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum );

This function enables the specified object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the object in pd2fob, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fobii_IspropInherited( d2fctx *pd2fctx, d2fob *pd2fob, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the object in pd2fob, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fobsc_SubClass( d2fctx *pd2fctx, d2fob *pd2fob, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified object (pd2fob) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the object in pd2fob, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fobis_IsSubclassed	( d2fctx *pd2fctx, d2fob *pd2fob );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the specified object in pd2fob.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fobqt_QueryType( d2fctx *pd2fctx, d2fob *pd2fob, d2fotyp *objtyp );

This function returns D2FS_SUCCESS if the specified object type exists and stores the object in pd2fob.  You specify a pointer to the context in pd2fctx, a pointer for the returned object (pd2fob), and a pointer for the specified object type (objtyp).

This function is particularly useful if you have a traversal function that traverses all of your objects in a Form.  By using this function, you are able to gain access to all of the actual objects in your form.


Object group object functions

  Related Topics

This section describes the functions of the Form Builder Open API Object Group object.

d2fobgcr_Create( d2fctx *pd2fctx, d2fob *parent, d2fobg **ppd2fobg, text *name );

This function creates an object group.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new object group object in parent, a handle for the function to store the newly-created object in ppd2fobg, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new object group in ppd2fobg.

d2fobgde_Destroy( d2fctx *pd2fctx, d2fobg *pd2fobg );

This function destroys the specified object group.  You specify a pointer to the context in pd2fctx and a pointer to the object group you want to destroy in pd2fobg.

d2fobgdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2obg *pd2fobg_src, d2fobg **ppd2fobg_dst, text *new_name );

This function duplicates the specified object group.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the object group source in pd2fobg_src, a handle for the function to store the destination in ppd2fobg_dst, and a pointer for the name of the new object group (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified object group and place it at the ppd2fobg_dst location.

d2fobggb_GetBoolProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified object group.  You specify a pointer to the context in pd2fctx, the object group in pd2fobg, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fobggn_GetNumProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified object group.  You specify a pointer to the context in pd2fctx, the object group in pd2fobg, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fobggt_GetTextProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified object group.  You specify a pointer to the context in pd2fctx, the object group in pd2fobg, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified object group in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fobggo_GetObjectProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified object group.  You specify a pointer to the context in pd2fctx, the object group in pd2fobg, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fobggp_GetBlobProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the object group in pd2fobg, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fobgsb_SetBoolProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum, boolean prp );

This function sets the value of the specified object group boolean property.  You specify a pointer to the context in pd2fctx, the object group in pd2fobg, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fobgsn_SetNumProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum, number prp );

This function sets the value of the specified object group number property.  You specify a pointer to the context in pd2fctx, the object group in pd2fobg, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fobgst_SetTextProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum, text *prp );

This function sets the value of the specified object group text property.  You specify a pointer to the context in pd2fctx, the object group in pd2fobg, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fobgso_SetObjectProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum, dvoid *prp );

This function sets the object of the specified object group property.  You specify a pointer to the context in pd2fctx, the object group in pd2fobg, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fobgsp_SetBlobProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the specified object group in pd2fobg, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fobghp_HasProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum );

This function queries the specified object group for the specified property. You specify a pointer to the context in pd2fctx, the object group in pd2fobg, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fobgip_InheritProp( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum );

This function enables the specified object group to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the object group in pd2fobg, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fobgii_IspropInherited( d2fctx *pd2fctx, d2fobg *pd2fobg, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the object group in pd2fobg, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fobgsc_SubClass( d2fctx *pd2fctx, d2fong *pd2fobg, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified object group (pd2fobg) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the object group in pd2fobg, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fobgis_IsSubclassed	( d2fctx *pd2fctx, d2fobg *pd2fobg );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the specified object group in pd2fobg.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Object group child object functions

  Related Topics

This section describes the functions of the Form Builder Open API Object Group Child object.

d2fogcgcr_Create( d2fctx *pd2fctx, d2fogc *parent, d2fogc **ppd2fogc, text *name );

This function creates an object group child.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new object group child object in parent, a handle for the function to store the newly-created object in ppd2fogc, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new object group in ppd2fogcg.

d2fogcgde_Destroy( d2fctx *pd2fctx, d2fogc *pd2fogc );

This function destroys the specified object group child.  You specify a pointer to the context in pd2fctx and a pointer to the object group child you want to destroy in pd2fogc.

d2fogcgdu_Duplicate( d2fctx *pd2fctx, d2fogc *new_parent, d2ogc *pd2fogc_src, d2fogc **ppd2fogc_dst, text *new_name );

This function duplicates the specified object group child.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the object group child source in pd2fogc_src, a handle for the function to store the destination in ppd2fogc_dst, and a pointer for the name of the new object group child (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified object group child and place it at the ppd2fogcg_dst location.

d2fogcggb_GetBoolProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified object group child.  You specify a pointer to the context in pd2fctx, the object group child in pd2fogc, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fogcggn_GetNumProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified object group child.  You specify a pointer to the context in pd2fctx, the object group child in pd2fogc, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fogcggt_GetTextProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified object group child.  You specify a pointer to the context in pd2fctx, the object group child in pd2fogc, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified object group child in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fogcggo_GetObjectProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified object group child.  You specify a pointer to the context in pd2fctx, the object group child in pd2fogc, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fogcggp_GetBlobProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the object group child object in pd2fogc, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fogcgsb_SetBoolProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum, boolean prp );

This function sets the value of the specified object group child boolean property.  You specify a pointer to the context in pd2fctx, the object group child in pd2fogc, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fogcgsn_SetNumProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum, number prp );

This function sets the value of the specified object group child number property.  You specify a pointer to the context in pd2fctx, the object group child in pd2fogc, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fogcgst_SetTextProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum, text *prp );

This function sets the value of the specified object group child text property.  You specify a pointer to the context in pd2fctx, the object group child in pd2fogc, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fogcgso_SetObjectProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum, dvoid *prp );

This function sets the object of the specified object group child property.  You specify a pointer to the context in pd2fctx, the object group child in pd2fogc, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fogcgsp_SetBlobProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the specified object group child object in pd2fogc, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fogcghp_HasProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum );

This function queries the specified object group child for the specified property. You specify a pointer to the context in pd2fctx, the object group child in pd2fogc, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fogcgip_InheritProp( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum );

This function enables the specified object group child to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the object group child in pd2fogc, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fogcgii_IspropInherited( d2fctx *pd2fctx, d2fogc *pd2fogc, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the object group child object in pd2fogc, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Object library object functions

  Related Topics

This section describes the functions of the Form Builder Open API Object Library object.

d2folbcr_Create( d2fctx *pd2fctx, d2fob *parent, d2folb **ppd2folb, text *name );

This function creates an object library.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new object library object in parent, a handle for the function to store the newly-created object in ppd2folb, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new object library in ppd2folb.

d2folbde_Destroy( d2fctx *pd2fctx, d2folb *pd2folb );

This function destroys the specified object library.  You specify a pointer to the context in pd2fctx and a pointer to the object library you want to destroy in pd2folb.

d2folbdl_Delete( d2fctx *pd2fctx, text *name, boolean db );

This function deletes specified object library.  You specify a pointer to the context in pd2fctx, a pointer to a text string for the name of the object library in name, and a boolean flag to indicate if the object library is to be deleted from a database (for example, an open library, a form module, or a menu module) in db.

If db is TRUE, the Forms API assumes that you want to delete the specified object library from a database; if db is FALSE, the Forms API searches the file system for the specified object library and then deletes it.

d2folbdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2olb *pd2folb_src, d2folb **ppd2folb_dst, text *new_name );

This function duplicates the specified object library.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the object library source in pd2folb_src, a handle for the function to store the destination in ppd2folb_dst, and a pointer for the name of the new object library (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified object library and place it at the ppd2folb_dst location.

d2folbao_AddObj( d2fctx *pd2fctx, d2folb *pd2folb, d2folt *pd2folt, d2fob *pd2fob, d2fob **ppd2fob, boolean replace );

This function adds a copy of the specified object to an object library.  You specify a pointer to the context in pd2fctx, a pointer to the object library in pd2folb, a pointer to the tab page object in pd2folt, a pointer to the object you want to add to the object library in pd2fob, a handle for the function to return the newly-created object in ppd2fob, and a boolean flag, replace, to indicate what the function should do in the event that an object already exists with this name.

If an object of the same name and type already exists and if you set replace to TRUE, the function replaces the existing object with the new object; if it is set to FALSE, the function returns an error (D2FS_OBJNOTUNIQUE).

d2folbro_RemoveObj( d2fctx *pd2fctx, d2folb *po2olb, d2fob *pd2fob );

This function removes the specified object from an object library. You specify a pointer to the context in pd2fctx, a pointer to the object library in pd2folb, and a pointer to the object you want to remove from the object library in pd2fob.

d2folbf2_Findobjbypos( d2fctx *pd2fctx, d2folb *pd2folb, number pos, d2fob **ppret_obj);

This function returns the specified object’s position within the object library.  You specify a pointer to the context in pd2fctx, a pointer to an object library in pd2folb, the position of the object in the object library in pos, and a handle to the returned object in ppret_obj.

Note that there is a Forms API property called D2FP_OBJ_COUNT that you can use to retrieve the count of all associated objects for a specific object library.

d2folbld_Load( d2fctx *pd2fctx, d2folb **pd2folb, text *olibname, boolean db );

This function loads the specified object library.  You specify the context (pd2fctx), a handle to a pointer for the function to use to store the object library (ppd2folb), the name of the object library (olibname), and a boolean flag (db) to indicate if the object library is in a database.

If you set db to TRUE, the Forms API searches for the specified object library in the database.  Note that this assumes that you have connected to some database.  You must call d2fctx_Connect() before you load a object library from a database.

d2folbsv_Save( d2fctx *pd2fctx, d2folb *pd2folb, text *olibname, boolean db );

This function saves the specified object library.  You specify the context (pd2fctx), a pointer to the object library (pd2folb), the name of the specified object library (olibname), and a boolean flag (db) that indicates if the object library is to be saved in a database.

If you set db to TRUE, the Forms API saves the specified object library in the database.  Note that this assumes that you have connected to some database previously.  You must call d2fctx_Connect() before you save a object library to a database.

If you want to save the object library with the default name (the name supplied at create time), you must pass NULL as the text string in olibname.  If you want to save the object library as some other name, then pass in that text string in olibname.

d2folbfv_FileVersion( d2fctx *pd2fctx, text *olibname, boolean db, number *version );

This function returns the version of the file. You specify the context (pd2fctx), the object library name (olibname), a boolean flag (db) to indicate if the object library is in a database or the file system, and a pointer for the version returned by the function (version).

Note that you should call this function prior to calling the d2folbld_Load() function, since the file version will change once you load the object library.

d2folbgb_GetBoolProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified object library.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2folbgn_GetNumProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified object library.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2folbgt_GetTextProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified object library.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified object library in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2folbgo_GetObjectProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified object library.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2folbgp_GetBlobProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the object library in pd2folb, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2folbsb_SetBoolProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum, boolean prp );

This function sets the value of the specified object library boolean property.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2folbsn_SetNumProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum, number prp );

This function sets the value of the specified object library number property.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2folbst_SetTextProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum, text *prp );

This function sets the value of the specified object library text property.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2folbso_SetObjectProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum, dvoid *prp );

This function sets the object of the specified object library property.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2folbsp_SetBlobProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the specified object library in pd2folb, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2folbhp_HasProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum );

This function queries the specified object library for the specified property. You specify a pointer to the context in pd2fctx, the object library in pd2folb, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2folbip_InheritProp( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum );

This function enables the specified object library to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the object library in pd2folb, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2folbii_IspropInherited( d2fctx *pd2fctx, d2folb *pd2folb, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the object library object in pd2folb, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2folbss_SetSmartclass( d2fctx *pd2fctx, d2folb *pd2folb, d2fob *pd2fob, boolean state);

This function sets the specified object library as a member of a smart class.  You specify a pointer to the context in pd2fctx, a pointer to an object library object in pd2folb, a pointer to the object you want to become a smart class member in pd2fob, and a boolean toggle in state to indicate to the Forms API whether to set the specified object as a member of a smart class.  If state is set to TRUE, the Forms API flags the specified object as a smart class member; if state is set to FALSE, the Forms API sets the object as a non-member of the smart class.

d2folbis_IsSmartclassed( d2fctx *pd2fctx, d2folb *pd2folb, d2fob *pd2fob );

This function returns D2FS_YES if the specified object (pd2fob) is a smart class.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, and the object in pd2fob.

d2folbsd_SetDesc ( d2fctx *pd2fctx, d2folb *pd2folb, d2fob *pd2fob, text *desc );

This function returns D2FS_SUCCESS if the Forms API sets the short description for the specified object.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, the object in pd2fob, and a pointer to the actual short description in desc.

d2folbgd_GetDesc ( d2fctx *pd2fctx, d2folb *pd2folb, d2fob *pd2fob, text **desc );

This function returns D2FS_SUCCESS if the Forms API retrieves the short description for the specified object.  You specify a pointer to the context in pd2fctx, the object library in pd2folb, the object in pd2fob, and a handle for the function to return the short description in desc.


Program unit object functions

  Related Topics

This section describes the functions of the Form Builder Open API Program Unit object.

d2fpgucr_Create( d2fctx *pd2fctx, d2fob *parent, d2fpgu **ppd2fpgu, text *name );

This function creates a program unit.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new program unit object in parent, a handle for the function to store the newly-created object in ppd2fpgu, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new program unit in ppd2fpgu.

d2fpgude_Destroy( d2fctx *pd2fctx, d2fpgu *pd2fpgu );

This function destroys the specified program unit.  You specify a pointer to the context in pd2fctx and a pointer to the program unit you want to destroy in pd2fpgu.

d2fpgudu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2pgu *pd2fpgu_src, d2fpgu **ppd2fpgu_dst, text *new_name );

This function duplicates the specified program unit.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the program unit source in pd2fpgu_src, a handle for the function to store the destination in ppd2fpgu_dst, and a pointer for the name of the new program unit (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified program unit and place it at the ppd2fpgu_dst location.

d2fpguco_CompileObj ( d2fctx *pd2fctx, d2fpgu *pd2fpgu );

This function compiles all of the PL/SQL code associated with the specified program unit. You specify a pointer to the context in pd2fctx and a pointer to the object you want to compile in pd2fpgu.

For example, you might use this function to compile all of the trigger objects attached to a program unit, and all of the trigger objects attached to all item objects in a program unit.

d2fpgugb_GetBoolProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified program unit.  You specify a pointer to the context in pd2fctx, the program unit in pd2fpgu, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fpgugn_GetNumProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified program unit.  You specify a pointer to the context in pd2fctx, the program unit in pd2fpgu, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fpgugt_GetTextProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified program unit.  You specify a pointer to the context in pd2fctx, the program unit in pd2fpgu, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified program unit in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fpgugo_GetObjectProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified program unit.  You specify a pointer to the context in pd2fctx, the program unit in pd2fpgu, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fpgugp_GetBlobProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the program unit object in pd2fpgu, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fpgusb_SetBoolProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum, boolean prp );

This function sets the value of the specified program unit boolean property.  You specify a pointer to the context in pd2fctx, the program unit in pd2fpgu, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fpgusn_SetNumProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum, number prp );

This function sets the value of the specified program unit number property.  You specify a pointer to the context in pd2fctx, the program unit in pd2fpgu, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fpgust_SetTextProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum, text *prp );

This function sets the value of the specified program unit text property.  You specify a pointer to the context in pd2fctx, the program unit in pd2fpgu, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fpguso_SetObjectProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum, dvoid *prp );

This function sets the object of the specified program unit property.  You specify a pointer to the context in pd2fctx, the program unit in pd2fpgu, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fpgusp_SetBlobProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the program unit object in pd2fpgu, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fpguhp_HasProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum );

This function queries the specified program unit for the specified property. You specify a pointer to the context in pd2fctx, the program unit in pd2fpgu, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fpguip_InheritProp( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum );

This function enables the specified program unit to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the program unit object in pd2fpgu, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fpguii_IspropInherited( d2fctx *pd2fctx, d2fpgu *pd2fpgu, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the program unit object in pd2fpgu, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fpgusc_SubClass( d2fctx *pd2fctx, d2fpgu *pd2fpgu, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified program unit (pd2fpgu) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the program unit in pd2fpgu, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fpguis_IsSubclassed	( d2fctx *pd2fctx, d2fpgu *pd2fpgu );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the program unit object in pd2fpgu.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Property class object functions

  Related Topics

This section describes the functions of the Form Builder Open API Property Class object.

d2fppccr_Create( d2fctx *pd2fctx, d2fob *parent, d2fppc **ppd2fppc, text *name );

This function creates a property class object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new property class object in parent, a handle for the function to store the newly-created object in ppd2fppc, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new property class in ppd2fppc.

d2fppcde_Destroy( d2fctx *pd2fctx, d2fppc *pd2fppc );

This function destroys the specified property class.  You specify a pointer to the context in pd2fctx and a pointer to the property class you want to destroy in pd2fppc.

d2fppcdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2ppc *pd2fppc_src, d2fppc **ppd2fppc_dst, text *new_name );

This function duplicates the specified property class.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the property class source in pd2fppc_src, a handle for the function to store the destination in ppd2fppc_dst, and a pointer for the name of the new property class (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified property class and place it at the ppd2fppc_dst location.

d2fppcrp_RemoveProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum );

This function removes the specified property from the property class.  You specify a pointer to the context in pd2fctx, the property class in pd2fppc, and the property number of the property to be removed in pnum.

This function returns D2FS_SUCCESS if the specified property has been removed.

d2fppcgb_GetBoolProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified property class.  You specify a pointer to the context in pd2fctx, the property class in pd2fppc, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fppcgn_GetNumProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified property class.  You specify a pointer to the context in pd2fctx, the property class in pd2fppc, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fppcgt_GetTextProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified property class.  You specify a pointer to the context in pd2fctx, the property class in pd2fppc, the property number in pnum, and a pointer to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified property class in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fppcgo_GetObjectProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified property class.  You specify a pointer to the context in pd2fctx, the property class in pd2fppc, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fppcgp_GetBlobProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the property class object in pd2fppc, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fppcsb_SetBoolProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum, boolean prp );

This function sets the value of the specified property class boolean property.  You specify a pointer to the context in pd2fctx, the property class in pd2fppc, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fppcsn_SetNumProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum, number prp );

This function sets the value of the specified property class number property.  You specify a pointer to the context in pd2fctx, the property class in pd2fppc, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fppcst_SetTextProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum, text *prp );

This function sets the value of the specified property class text property.  You specify a pointer to the context in pd2fctx, the property class in pd2fppc, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fppcso_SetObjectProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum, dvoid *prp );

This function sets the object of the specified property class property.  You specify a pointer to the context in pd2fctx, the property class in pd2fppc, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fppcsp_SetBlobProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the property class object in pd2fppc, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fppchp_HasProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum );

This function queries the specified property class for the specified property. You specify a pointer to the context in pd2fctx, the property class in pd2fppc, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fppcip_InheritProp( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum );

This function enables the specified property class to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the property class in pd2fppc, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fppcii_IspropInherited( d2fctx *pd2fctx, d2fppc *pd2fppc, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the property class object in pd2fppc, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fppcsc_SubClass( d2fctx *pd2fctx, d2fppc *pd2fppc, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified property class (pd2fppc) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the property class in pd2fppc, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fppcis_IsSubclassed	( d2fctx *pd2fctx, d2fppc *pd2fppc );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the property class object in pd2fppc.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Radio button object functions

  Related Topics

This section describes the functions of the Form Builder Open API Radio Button object.

d2frdbcr_Create( d2fctx *pd2fctx, d2fob *parent, d2frdb **ppd2frdb, text *name );

This function creates a radio button object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new radio button object in parent, a handle for the function to store the newly-created object in ppd2frdb, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new radio button in ppd2frdb.

d2frdbde_Destroy( d2fctx *pd2fctx, d2frdb *pd2frdb );

This function destroys the specified radio button.  You specify a pointer to the context in pd2fctx and a pointer to the radio button object you want to destroy in pd2frdb.

d2frdbdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2rdb *pd2frdb_src, d2frdb **ppd2frdb_dst, text *new_name );

This function duplicates the specified radio button.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the radio button source in pd2frdb_src, a handle for the function to store the destination in ppd2frdb_dst, and a pointer for the name of the new radio button (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified radio button and place it at the ppd2frdb_dst location.

d2frdbgb_GetBoolProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified radio button.  You specify a pointer to the context in pd2fctx, the radio button in pd2frdb, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2frdbgn_GetNumProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified radio button.  You specify a pointer to the context in pd2fctx, the radio button in pd2frdb, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2frdbgt_GetTextProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified radio button.  You specify a pointer to the context in pd2fctx, the radio button in pd2frdb, the property number in pnum, and a pointer to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified radio button in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2frdbgo_GetObjectProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified radio button.  You specify a pointer to the context in pd2fctx, the radio button in pd2frdb, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2frdbgp_GetBlobProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the radio button object in pd2frdb, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2frdbsb_SetBoolProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum, boolean prp );

This function sets the value of the specified radio button boolean property.  You specify a pointer to the context in pd2fctx, the radio button in pd2frdb, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2frdbsn_SetNumProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum, number prp );

This function sets the value of the specified radio button number property.  You specify a pointer to the context in pd2fctx, the radio button in pd2frdb, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2frdbst_SetTextProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum, text *prp );

This function sets the value of the specified radio button text property.  You specify a pointer to the context in pd2fctx, the radio button in pd2frdb, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2frdbso_SetObjectProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum, dvoid *prp );

This function sets the object of the specified radio button property.  You specify a pointer to the context in pd2fctx, the radio button in pd2frdb, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2frdbsp_SetBlobProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the radio button object in pd2frdb, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2frdbhp_HasProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum );

This function queries the specified radio button for the specified property. You specify a pointer to the context in pd2fctx, the radio button in pd2frdb, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frdbip_InheritProp( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum );

This function enables the specified radio button to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the radio button in pd2frdb, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frdbii_IspropInherited( d2fctx *pd2fctx, d2frdb *pd2frdb, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the radio button object in pd2frdb, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frdbsc_SubClass( d2fctx *pd2fctx, d2frdb *pd2frdb, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified radio button (pd2frdb) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the radio button in pd2frdb, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2frdbis_IsSubclassed	( d2fctx *pd2fctx, d2frdb *pd2frdb );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the radio button object in pd2frdb.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Record group object functions

  Related Topics

This section describes the functions of the Form Builder Open API Record Group object.

d2frcgcr_Create( d2fctx *pd2fctx, d2fob *parent, d2frcg **ppd2frcg, text *name );

This function creates a record group object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new record group object in parent, a handle for the function to store the newly-created object in ppd2frcg, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new record group object in ppd2frcg.

d2frcgde_Destroy( d2fctx *pd2fctx, d2frcg *pd2frcg );

This function destroys the specified record group object.  You specify a pointer to the context in pd2fctx and a pointer to the record group object you want to destroy in pd2frcg.

d2frcgdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2rcg *pd2frcg_src, d2frcg **ppd2frcg_dst, text *new_name );

This function duplicates the specified record group object.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the record group object source in pd2frcg_src, a handle for the function to store the destination in ppd2frcg_dst, and a pointer for the name of the new record group object (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified record group object and place it at the ppd2frcg_dst location.

d2frcggb_GetBoolProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified record group object.  You specify a pointer to the context in pd2fctx, the record group object in pd2frcg, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2frcggn_GetNumProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified record group object.  You specify a pointer to the context in pd2fctx, the record group object in pd2frcg, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2frcggt_GetTextProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified record group object.  You specify a pointer to the context in pd2fctx, the record group object in pd2frcg, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified record group object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2frcggo_GetObjectProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified record group object.  You specify a pointer to the context in pd2fctx, the record group object in pd2frcg, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2frcggp_GetBlobProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the record group object in pd2frcg, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2frcgsb_SetBoolProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum, boolean prp );

This function sets the value of the specified record group object boolean property.  You specify a pointer to the context in pd2fctx, the record group object in pd2frcg, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2frcgsn_SetNumProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum, number prp );

This function sets the value of the specified record group object number property.  You specify a pointer to the context in pd2fctx, the record group object in pd2frcg, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2frcgst_SetTextProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum, text *prp );

This function sets the value of the specified record group object text property.  You specify a pointer to the context in pd2fctx, the record group object in pd2frcg, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2frcgso_SetObjectProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum, dvoid *prp );

This function sets the object of the specified record group object property.  You specify a pointer to the context in pd2fctx, the record group object in pd2frcg, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2frcgsp_SetBlobProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the record group object in pd2frcg, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2frcghp_HasProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum );

This function queries the specified record group object for the specified property. You specify a pointer to the context in pd2fctx, the record group object in pd2frcg, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frcgip_InheritProp( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum );

This function enables the specified record group object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the record group object in pd2frcg, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frcgii_IspropInherited( d2fctx *pd2fctx, d2frcg *pd2frcg, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the record group object in pd2frcg, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frcgsc_SubClass( d2fctx *pd2fctx, d2frcg *pd2frcg, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified record group object (pd2frcg) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the record group object in pd2frcg, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2frcgis_IsSubclassed	( d2fctx *pd2fctx, d2frcg *pd2frcg );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the record group object in pd2frcg.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Record group column specification object functions

  Related Topics

This section describes the functions of the Form Builder Open API Record Group Column Specification object.

d2frcscr_Create( d2fctx *pd2fctx, d2fob *parent, d2frcs **ppd2frcs, text *name );

This function creates a record group column specification.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new record group column specification object in parent, a handle for the function to store the newly-created object in ppd2frcs, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new record group column specification in ppd2frcs.

d2frcsde_Destroy( d2fctx *pd2fctx, d2frcs *pd2frcs );

This function destroys the specified record group column specification.  You specify a pointer to the context in pd2fctx and a pointer to the record group column specification you want to destroy in pd2frcs.

d2frcsdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2rcs *pd2frcs_src, d2frcs **ppd2frcs_dst, text *new_name );

This function duplicates the specified record group column specification.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the record group column specification source in pd2frcs_src, a handle for the function to store the destination in ppd2frcs_dst, and a pointer for the name of the new record group column specification (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified record group column specification and place it at the ppd2frcs_dst location.

d2frcsir_InsertRow( d2fctx *pd2fctx, d2frcs *pd2frcs, number index, text *dat );

This function inserts a row into the specified record group specification object.  You specify a pointer to the context in pd2fctx, a pointer to the record group specification object in pd2frcs, the index into the row list where the function is to insert the row in index, and a pointer to the data in dat.

Note that you need to first create a record group object, then you need to create a new record group column object, and finally, you can insert rows into that associated column value.

Note that there is a Forms API property called D2FP_COL_VALS_COUNT that you can use to retrieve the count of all columns for a record group column specification.

d2frcsdr_DeleteRow( d2fctx *pd2fctx, d2frcs *pd2frcs, number index );

This function deletes the specified row from the specified record group specification object.  You specify a pointer to the context in pd2fctx, a pointer to the record group specification object in pd2frcs, and the index into the row list where the function is to delete the row in index.

Note that there is a Forms API property called D2FP_COL_VALS_COUNT that you can use to retrieve the count of all columns for a record group column specification.

d2frcsgr_GetRow( d2fctx *pd2fctx, d2frcs *pd2frcs, number index, text **dat );

This function retrieves a row from the specified record group specification object.  You specify a pointer to the context in pd2fctx, a pointer to the record group specification object in pd2frcs, the index into the row list where the function is to retrieve the row in index, and handle for the function to return the row in dat.

Note that there is a Forms API property called D2FP_COL_VALS_COUNT that you can use to retrieve the count of all columns for a record group column specification.

d2frcsgb_GetBoolProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified record group column specification.  You specify a pointer to the context in pd2fctx, the record group column specification in pd2frcs, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2frcsgn_GetNumProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified record group column specification.  You specify a pointer to the context in pd2fctx, the record group column specification in pd2frcs, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2frcsgt_GetTextProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified record group column specification.  You specify a pointer to the context in pd2fctx, the record group column specification in pd2frcs, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified record group column specification in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2frcsgo_GetObjectProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified record group column specification.  You specify a pointer to the context in pd2fctx, the record group column specification in pd2frcs, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2frcsgp_GetBlobProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the record group column specification object in pd2frcs, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2frcssb_SetBoolProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum, boolean prp );

This function sets the value of the specified record group column specification boolean property.  You specify a pointer to the context in pd2fctx, the record group column specification in pd2frcs, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2frcssn_SetNumProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum, number prp );

This function sets the value of the specified record group column specification number property.  You specify a pointer to the context in pd2fctx, the record group column specification in pd2frcs, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2frcsst_SetTextProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum, text *prp );

This function sets the value of the specified record group column specification text property.  You specify a pointer to the context in pd2fctx, the record group column specification in pd2frcs, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2frcsso_SetObjectProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum, dvoid *prp );

This function sets the object of the specified record group column specification property.  You specify a pointer to the context in pd2fctx, the record group column specification in pd2frcs, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2frcssp_SetBlobProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the record group column specification object in pd2frcs, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2frcshp_HasProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum );

This function queries the specified record group column specification for the specified property. You specify a pointer to the context in pd2fctx, the record group column specification in pd2frcs, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frcsip_InheritProp( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum );

This function enables the specified record group column specification to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the record group column specification object in pd2frcs, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frcsii_IspropInherited( d2fctx *pd2fctx, d2frcs *pd2frcs, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the record group column specification object in pd2frcs, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Relation object functions

  Related Topics

This section describes the functions of the Form Builder Open API Relation object.

d2frelcr_Create( d2fctx *pd2fctx, d2fob *parent, d2frel **ppd2frel, text *name );

This function creates a relation object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new relation object in parent, a handle for the function to store the newly-created object in ppd2frel, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new relation in ppd2frel.

d2frelde_Destroy( d2fctx *pd2fctx, d2frel *pd2frel );

This function destroys the specified relation.  You specify a pointer to the context in pd2fctx and a pointer to the relation object you want to destroy in pd2frel.

d2frelup_Update( d2fctx *pd2fctx, d2frel *pd2frel );

This function updates the specified relation object.  You specify a pointer to the context in pd2fctx and a pointer to the relation object in pd2frel.

With conventional Forms objects, you first create an object, and then you begin setting and retrieving its object properties.  Relation objects require an additional step after you create it to “instantiate” the object. So, with relation objects, you first create them, then you set specific properties of the relation object, and then you call this update function.  If you do not call this function, the relation object is not complete and the behavior is undefined.  The relation object subsequently exists in an “unstable” state (if you actually tried to do anything with an unstable relation object, the Forms API returns an error).

d2freldu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2rel *pd2frel_src, d2frel **ppd2frel_dst, text *new_name );

This function duplicates the specified relation.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the relation source in pd2frel_src, a handle for the function to store the destination in ppd2frel_dst, and a pointer for the name of the new relation (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified relation and place it at the ppd2frel_dst location.

d2frelgb_GetBoolProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified relation.  You specify a pointer to the context in pd2fctx, the relation in pd2frel, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2frelgn_GetNumProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified relation.  You specify a pointer to the context in pd2fctx, the relation in pd2frel, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2frelgt_GetTextProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified relation.  You specify a pointer to the context in pd2fctx, the relation in pd2frel, the property number in pnum, and a pointer to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified relation in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2frelgo_GetObjectProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified relation.  You specify a pointer to the context in pd2fctx, the relation in pd2frel, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2frelgp_GetBlobProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the relation object in pd2frel, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2frelsb_SetBoolProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum, boolean prp );

This function sets the value of the specified relation boolean property.  You specify a pointer to the context in pd2fctx, the relation in pd2frel, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2frelsn_SetNumProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum, number prp );

This function sets the value of the specified relation number property.  You specify a pointer to the context in pd2fctx, the relation in pd2frel, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2frelst_SetTextProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum, text *prp );

This function sets the value of the specified relation text property.  You specify a pointer to the context in pd2fctx, the relation in pd2frel, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2frelso_SetObjectProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum, dvoid *prp );

This function sets the object of the specified relation property.  You specify a pointer to the context in pd2fctx, the relation in pd2frel, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2frelsp_SetBlobProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the relation object in pd2frel, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2frelhp_HasProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum );

This function queries the specified relation for the specified property. You specify a pointer to the context in pd2fctx, the relation in pd2frel, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frelip_InheritProp( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum );

This function enables the specified relation to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the relation object in pd2frel, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frelii_IspropInherited( d2fctx *pd2fctx, d2frel *pd2frel, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the relation object in pd2frel, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Report object functions

  Related Topics

This section describes the functions of the Form Builder Open API Report object.

d2frptcr_Create( d2fctx *pd2fctx, d2fob *parent, d2frpt **ppd2frpt, text *name );

This function creates a report object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new report object in parent, a handle for the function to store the newly-created object in ppd2frpt, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new report object in ppd2frpt.

d2frptde_Destroy( d2fctx *pd2fctx, d2frpt *pd2frpt );

This function destroys the specified report object.  You specify a pointer to the context in pd2fctx and a pointer to the report object you want to destroy in pd2frpt.

d2frptdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2rpt *pd2frpt_src, d2frpt **ppd2frpt_dst, text *new_name );

This function duplicates the specified report object.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the report object source in pd2frpt_src, a handle for the function to store the destination in ppd2frpt_dst, and a pointer for the name of the new report object (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified report object and place it at the ppd2frpt_dst location.

d2frptgb_GetBoolProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified report object.  You specify a pointer to the context in pd2fctx, the report object in pd2frpt, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2frptgn_GetNumProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified report object.  You specify a pointer to the context in pd2fctx, the report object in pd2frpt, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2frptgt_GetTextProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified report object.  You specify a pointer to the context in pd2fctx, the report object in pd2frpt, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified report object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2frptgo_GetObjectProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified report object.  You specify a pointer to the context in pd2fctx, the report object in pd2frpt, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2frptgp_GetBlobProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the report object in pd2frpt, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2frptsb_SetBoolProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum, boolean prp );

This function sets the value of the specified report object boolean property.  You specify a pointer to the context in pd2fctx, the report object in pd2frpt, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2frptsn_SetNumProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum, number prp );

This function sets the value of the specified report object number property.  You specify a pointer to the context in pd2fctx, the report object in pd2frpt, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2frptst_SetTextProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum, text *prp );

This function sets the value of the specified report object text property.  You specify a pointer to the context in pd2fctx, the report object in pd2frpt, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2frptso_SetObjectProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum, dvoid *prp );

This function sets the object of the specified report object property.  You specify a pointer to the context in pd2fctx, the report object in pd2frpt, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2frptsp_SetBlobProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the report object in pd2frpt, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2frpthp_HasProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum );

This function queries the specified report object for the specified property. You specify a pointer to the context in pd2fctx, the report object in pd2frpt, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frptip_InheritProp( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum );

This function enables the specified report object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the report object in pd2frpt, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frptii_IspropInherited( d2fctx *pd2fctx, d2frpt *pd2frpt, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the report object in pd2frpt, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2frptsc_SubClass( d2fctx *pd2fctx, d2frpt *pd2frpt, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified report object (pd2frpt) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the report in pd2frpt, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2frptis_IsSubclassed	( d2fctx *pd2fctx, d2frpt *pd2frpt );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the report object in pd2frpt.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Tab page object functions

  Related Topics

This section describes the functions of the Form Builder Open API Tab Page object.

d2ftbpcr_Create( d2fctx *pd2fctx, d2fob *parent, d2ftbp **ppd2ftbp, text *name );

This function creates a tab page object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new tab page object in parent, a handle for the function to store the newly-created object in ppd2ftbp, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new tab page object in ppd2ftbp.

d2ftbpde_Destroy( d2fctx *pd2fctx, d2ftbp *pd2ftbp );

This function destroys the specified tab page object.  You specify a pointer to the context in pd2fctx and a pointer to the tab page object you want to destroy in pd2ftbp.

d2ftbpdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2tbp *pd2ftbp_src, d2ftbp **ppd2ftbp_dst, text *new_name );

This function duplicates the specified tab page object.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the tab page object source in pd2ftbp_src, , a handle for the function to store the destination in ppd2ftbp_dst, and a pointer for the name of the new tab page object (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified tab page object and place it at the ppd2ftbp_dst location.

d2ftbpgb_GetBoolProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified tab page object.  You specify a pointer to the context in pd2fctx, the tab page object in pd2ftbp, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2ftbpgn_GetNumProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified tab page object.  You specify a pointer to the context in pd2fctx, the tab page object in pd2ftbp, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2ftbpgt_GetTextProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified tab page object.  You specify a pointer to the context in pd2fctx, the tab page object in pd2ftbp, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified tab page object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2ftbpgo_GetObjectProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified tab page object.  You specify a pointer to the context in pd2fctx, the tab page object in pd2ftbp, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2ftbpgp_GetBlobProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the tab page object in pd2ftbp, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2ftbpsb_SetBoolProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum, boolean prp );

This function sets the value of the specified tab page object boolean property.  You specify a pointer to the context in pd2fctx, the tab page object in pd2ftbp, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2ftbpsn_SetNumProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum, number prp );

This function sets the value of the specified tab page object number property.  You specify a pointer to the context in pd2fctx, the tab page object in pd2ftbp, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2ftbpst_SetTextProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum, text *prp );

This function sets the value of the specified tab page object text property.  You specify a pointer to the context in pd2fctx, the tab page object in pd2ftbp, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2ftbpso_SetObjectProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum, dvoid *prp );

This function sets the object of the specified tab page object property.  You specify a pointer to the context in pd2fctx, the tab page object in pd2ftbp, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2ftbpsp_SetBlobProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the tab page object in pd2ftbp, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2ftbphp_HasProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum );

This function queries the specified tab page object for the specified property. You specify a pointer to the context in pd2fctx, the tab page object in pd2ftbp, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ftbpip_InheritProp( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum );

This function enables the specified tab page object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the tab page object in pd2ftbp, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ftbpii_IspropInherited( d2fctx *pd2fctx, d2ftbp *pd2ftbp, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the tab page object in pd2ftbp, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ftbpsc_SubClass( d2fctx *pd2fctx, d2ftbp *pd2ftbp, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified tab page object (pd2ftbp) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the tab page object in pd2ftbp, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2ftbpis_IsSubclassed	( d2fctx *pd2fctx, d2ftbp *pd2ftbp );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the tab page object in pd2ftbp.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Trigger object functions

  Related Topics

This section describes the functions of the Form Builder Open API Trigger object.

d2ftrgcr_Create( d2fctx *pd2fctx, d2fob *parent, d2ftrg **ppd2ftrg, text *name );

This function creates a trigger object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new trigger object in parent, a handle for the function to store the newly-created object in ppd2ftrg, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new trigger object in ppd2ftrg.

d2ftrgde_Destroy( d2fctx *pd2fctx, d2ftrg *pd2ftrg );

This function destroys the specified trigger object.  You specify a pointer to the context in pd2fctx and a pointer to the trigger object you want to destroy in pd2ftrg.

d2ftrgdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2trg *pd2ftrg_src, d2ftrg **ppd2ftrg_dst, text *new_name );

This function duplicates the specified trigger object.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the trigger object source in pd2ftrg_src, a handle for the function to store the destination in ppd2ftrg_dst, and a pointer for the name of the new trigger object (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified trigger object and place it at the ppd2ftrg_dst location.

d2ftrgco_CompileObj( d2fctx *pd2fctx, d2ftrg *pdftrg);

This function compiles all of the PL/SQL code associated with the specified trigger object (pdftrg). You specify a pointer to the context in pd2fctx and a pointer to the object you want to compile in pd2ftrg.

d2ftrggb_GetBoolProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified trigger object.  You specify a pointer to the context in pd2fctx, the trigger object in pd2ftrg, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2ftrggn_GetNumProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified trigger object.  You specify a pointer to the context in pd2fctx, the trigger object in pd2ftrg, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2ftrggt_GetTextProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified trigger object.  You specify a pointer to the context in pd2fctx, the trigger object in pd2ftrg, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified trigger object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2ftrggo_GetObjectProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified trigger object.  You specify a pointer to the context in pd2fctx, the trigger object in pd2ftrg, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2ftrggp_GetBlobProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the trigger object in pd2ftrg, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2ftrgsb_SetBoolProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum, boolean prp );

This function sets the value of the specified trigger object boolean property.  You specify a pointer to the context in pd2fctx, the trigger object in pd2ftrg, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2ftrgsn_SetNumProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum, number prp );

This function sets the value of the specified trigger object number property.  You specify a pointer to the context in pd2fctx, the trigger object in pd2ftrg, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2ftrgst_SetTextProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum, text *prp );

This function sets the value of the specified trigger object text property.  You specify a pointer to the context in pd2fctx, the trigger object in pd2ftrg, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2ftrgso_SetObjectProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum, dvoid *prp );

This function sets the object of the specified trigger object property.  You specify a pointer to the context in pd2fctx, the trigger object in pd2ftrg, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2ftrgsp_SetBlobProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the trigger object in pd2ftrg, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2ftrghp_HasProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum );

This function queries the specified trigger object for the specified property. You specify a pointer to the context in pd2fctx, the trigger object in pd2ftrg, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ftrgip_InheritProp( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum );

This function enables the specified trigger object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the trigger object in pd2ftrg, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ftrgii_IspropInherited( d2fctx *pd2fctx, d2ftrg *pd2ftrg, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the trigger object in pd2ftrg, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2ftrgsc_SubClass( d2fctx *pd2fctx, d2ftrg *pd2ftrg, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified trigger object (pd2ftrg) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the trigger object in pd2ftrg, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2ftrgis_IsSubclassed	( d2fctx *pd2fctx, d2ftrg *pd2ftrg );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the trigger object in pd2ftrg.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Visual attribute object functions

  Related Topics

This section describes the functions of the Form Builder Open API Visual Attribute object.

d2fvatcr_Create( d2fctx *pd2fctx, d2fob *parent, d2fvat **ppd2fvat, text *name );

This function creates a visual attribute object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new visual attribute object in parent, a handle for the function to store the newly-created object in ppd2fvat, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new visual attribute object in ppd2fvat.

d2fvatde_Destroy( d2fctx *pd2fctx, d2fvat *pd2fvat );

This function destroys the specified visual attribute object.  You specify a pointer to the context in pd2fctx and a pointer to the visual attribute object you want to destroy in pd2fvat.

d2fvatdu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2vat *pd2fvat_src, d2fvat **ppd2fvat_dst, text *new_name );

This function duplicates the specified visual attribute object.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the visual attribute object source in pd2fvat_src, a handle for the function to store the destination in ppd2fvat_dst, and a pointer for the name of the new visual attribute object (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified visual attribute object and place it at the ppd2fvat_dst location.

d2fvatco_CompileObj( d2fctx *pd2fctx, d2fvat *pdfvat);

This function compiles all of the PL/SQL code associated with the specified visual attribute object (pd2fvat). You specify a pointer to the context in pd2fctx and a pointer to the object you want to compile in pd2fvat.

d2fvatgb_GetBoolProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified visual attribute object.  You specify a pointer to the context in pd2fctx, the visual attribute object in pd2fvat, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fvatgn_GetNumProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified visual attribute object.  You specify a pointer to the context in pd2fctx, the visual attribute object in pd2fvat, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fvatgt_GetTextProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified visual attribute object.  You specify a pointer to the context in pd2fctx, the visual attribute object in pd2fvat, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified visual attribute object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fvatgo_GetObjectProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified visual attribute object.  You specify a pointer to the context in pd2fctx, the visual attribute object in pd2fvat, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fvatgp_GetBlobProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the visual attribute object in pd2fvat, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fvatsb_SetBoolProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum, boolean prp );

This function sets the value of the specified visual attribute object boolean property.  You specify a pointer to the context in pd2fctx, the visual attribute object in pd2fvat, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fvatsn_SetNumProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum, number prp );

This function sets the value of the specified visual attribute object number property.  You specify a pointer to the context in pd2fctx, the visual attribute object in pd2fvat, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fvatst_SetTextProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum, text *prp );

This function sets the value of the specified visual attribute object text property.  You specify a pointer to the context in pd2fctx, the visual attribute object in pd2fvat, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fvatso_SetObjectProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum, dvoid *prp );

This function sets the object of the specified visual attribute object property.  You specify a pointer to the context in pd2fctx, the visual attribute object in pd2fvat, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fvatsp_SetBlobProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the visual attribute object in pd2fvat, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fvathp_HasProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum );

This function queries the specified visual attribute object for the specified property. You specify a pointer to the context in pd2fctx, the visual attribute object in pd2fvat, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fvatip_InheritProp( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum );

This function enables the specified visual attribute object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the visual attribute object in pd2fvat, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fvatii_IspropInherited( d2fctx *pd2fctx, d2fvat *pd2fvat, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the visual attribute object in pd2fvat, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fvatsc_SubClass( d2fctx *pd2fctx, d2fvat *pd2fvat, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified visual attribute object (pd2fvat) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the visual attribute object in pd2fvat, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fvatis_IsSubclassed	( d2fctx *pd2fctx, d2fvat *pd2fvat );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the visual attribute object in pd2fvat.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


Window object functions

  Related Topics

This section describes the functions of the Form Builder Open API Window object.

d2fwincr_Create( d2fctx *pd2fctx, d2fob *parent, d2fwin **ppd2fwin, text *name );

This function creates a window object.  You specify a pointer to the context in pd2fctx, a pointer to the parent of the new window object in parent, a handle for the function to store the newly-created object in ppd2fwin, and the name of the new object in name.

This function returns D2FS_SUCCESS if it is able to create a new window object in ppd2fwin.

d2fwinde_Destroy( d2fctx *pd2fctx, d2fwin *pd2fwin );

This function destroys the specified window object.  You specify a pointer to the context in pd2fctx and a pointer to the window object you want to destroy in pd2fwin.

d2fwindu_Duplicate( d2fctx *pd2fctx, d2fob *new_parent, d2win *pd2fwin_src, d2fwin **ppd2fwin_dst, text *new_name );

This function duplicates the specified window object.  You specify a pointer to the context in pd2fctx, a pointer to the new parent in new_parent, a pointer to the window object source in pd2fwin_src, a handle for the function to store the destination in ppd2fwin_dst, and a pointer for the name of the new window object (new_name).

This function returns D2FS_SUCCESS if it is able duplicate the specified window object and place it at the ppd2fwin_dst location.

d2fwinco_CompileObj( d2fctx *pd2fctx, d2fwin *pdfwin);

This function compiles all of the PL/SQL code associated with the specified window (pd2fwin). You specify a pointer to the context in pd2fctx and a pointer to the object you want to compile in pd2fwin.

For example, you might use this function to compile all of the trigger objects attached to a window, and all of the trigger objects attached to all item objects in a window.

d2fwingb_GetBoolProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum, boolean *pprp );

This function retrieves a property of type boolean for the specified window object.  You specify a pointer to the context in pd2fctx, the window object in pd2fwin, the property number in pnum, and a pointer to pprp, to store the boolean value.

This function returns D2FS_SUCCESS if it stores the value of the boolean property in pprp.

d2fwingn_GetNumProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum, number *pprp );

This function retrieves a property of type number (an actual scalar constant) for the specified window object.  You specify a pointer to the context in pd2fctx, the window object in pd2fwin, the property number in pnum, and a pointer to pprp, to store the numeric value.

This function returns D2FS_SUCCESS if it stores the value of the number property in pprp.

d2fwingt_GetTextProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum, text **pprp );

This function retrieves a  property of type text for the specified window object.  You specify a pointer to the context in pd2fctx, the window object in pd2fwin, the property number in pnum, and a handle to an array of characters in pprp for the function to store the text property value.

This function returns D2FS_SUCCESS if it fills the supplied array with a copy of the text property value for the specified window object in pprp.

Note that the client is responsible for freeing the text returned by this function.

d2fwingo_GetObjectProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum, dvoid **pprp );

This function retrieves a property of type object of the specified window object.  You specify a pointer to the context in pd2fctx, the window object in pd2fwin, a property number in pnum, and a handle to pprp, for the function to store the object property value.

This function returns D2FS_SUCCESS if it stores a handle to the desired object property in pprp.

d2fwingp_GetBlobProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum, dvoid **pprp );

This function retrieves the value from the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the window object in pd2fwin, a property number in pnum, and a handle to pprp, for the function to provide access to the client-specified value.

This function returns D2FS_SUCCESS if it stores a handle to the desired client-specified property in pprp.

d2fwinsb_SetBoolProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum, boolean prp );

This function sets the value of the specified window object boolean property.  You specify a pointer to the context in pd2fctx, the window object in pd2fwin, the property number in pnum, and the boolean value in prp.

This function returns D2FS_SUCCESS if it sets the boolean property with the value you specify in prp.

d2fwinsn_SetNumProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum, number prp );

This function sets the value of the specified window object number property.  You specify a pointer to the context in pd2fctx, the window object in pd2fwin, the property number in pnum, and the number value in prp.

This function returns D2FS_SUCCESS if it sets the number property with the value you specify in prp.

d2fwinst_SetTextProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum, text *prp );

This function sets the value of the specified window object text property.  You specify a pointer to the context in pd2fctx, the window object in pd2fwin, the property number in pnum, and a handle to the text value in prp.

This function returns D2FS_SUCCESS if it sets the specified text property with the value stored in prp.

d2fwinso_SetObjectProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum, dvoid *prp );

This function sets the object of the specified window object property.  You specify a pointer to the context in pd2fctx, the window object in pd2fwin, a property number in pnum, and a handle to the object property in prp.

This function returns D2FS_SUCCESS if it sets the specified object property with the value stored in prp.

d2fwinsp_SetBlobProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum, dvoid *prp );

This function sets the client-specified handle.  You specify a pointer to the context in pd2fctx, a pointer to the window object in pd2fwin, a property number in pnum, and a pointer to the client-specified value in prp.

This function returns D2FS_SUCCESS if it sets the client-specified handle with the value stored in prp.

d2fwinhp_HasProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum );

This function queries the specified window object for the specified property. You specify a pointer to the context in pd2fctx, the window object in pd2fwin, and a property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has the specified property; otherwise, the function can return a number of possible return values, depending on the circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fwinip_InheritProp( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum );

This function enables the specified window object to inherit the specified property. You specify a pointer to the context in pd2fctx, a pointer to the window object in pd2fwin, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the object has been modified to inherit the specified property; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fwinii_IspropInherited( d2fctx *pd2fctx, d2fwin *pd2fwin, ub2 pnum );

This function verifies that the specified object’s property is inherited, as is, from its parent object.  You specify a pointer to the context in pd2fctx, a pointer to the window object in pd2fwin, and the property number in pnum.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the property is inherited from the specified object’s parent; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.

d2fwinsc_SubClass( d2fctx *pd2fctx, d2fwin *pd2fwin, d2fob *parent, boolean keep_path);

This function returns D2FS_SUCCESS if the specified window object (pd2fwin) becomes a subclass of the specified parent (parent).  You specify a pointer to the context in pd2fctx, a pointer to the window in pd2fwin, a pointer to the parent object in parent, and a boolean flag to save the path to the parent object in keep_path.

Note that the Forms API uses the boolean keep_path argument to save the actual path information.  It is recommended that you do not set keep_path to TRUE since this information may be lost if you move to another machine.  If keep_path is set to TRUE, the Forms API saves the actual path in the .fmb file.  Therefore, the next time the form is loaded, depending on how the environment variable Forms 4.5 or 5.0 path is defined, the Forms API searches for the parent form in one of the specified directories defined by the environment variable.

d2fwinis_IsSubclassed	( d2fctx *pd2fctx, d2fwin *pd2fwin );

This function verifies that the specified object is a subclass of another object. You specify a pointer to the context in pd2fctx and a pointer to the window object in pd2fwin.

If the function succeeds, it returns D2FS_YES or D2FS_NO, depending on whether the specified object is a subclass of another object; otherwise, the function can return a number of possible return values, depending on the specific circumstances. For a complete list of the valid Open Forms API return values, refer to the “About Open API function return codes” section.


About Open API function return codes

  Related Topics

This section describes the various possible Form Builder Open API function return codes.

D2FS_SUCCESS

This return code indicates that the operation succeeded.

D2FS_FAIL

This return code indicates that the operation failed.

D2FS_YES

This return code indicates that the operation returned “YES”.

D2FS_NO

This return code indicates that the operation returned “NO”.

D2FS_BADARG

This return code indicates that one of the arguments is bad.

D2FS_BADCONTEXT

This return code indicates that a bad context has been provided.

D2FS_BADPROP

This return code indicates that the specified property is bad.

D2FS_BADTYPE

This return code indicates that the object type is unknown.

D2FS_DONTHAVE

This return code indicates that the object does not have the specified property.

D2FS_GENFAILED

This return code indicates that the generation failed.

D2FS_INVALIDDATA

This return code indicates that the data passed in is invalid.

D2FS_INVALIDINDEX

This return code indicates that the index is invalid.

D2FS_NOMEMORY

This return code indicates that you are out of memory.

D2FS_NOINSTANCEHANDLE

This return code indicates that the initialization failed because a NULL instance handle was received.

Note that this return code applies to Microsoft Windows platforms only.

D2FS_NOMSGFILE

This return code indicates that the specified message file was not found.

D2FS_NOTCONNECTED

This return code indicates that you are not connected to a database.

D2FS_NOTIMPLEMENTED

This return code indicates that the operation is not currently available.

D2FS_NOTTRANSMODE

This return code indicates that the function can only be called in translation mode.

D2FS_NULLCONTAINER

This return code indicates that the operation returned a NULL pointer to the object.

D2FS_NULLDATA

This return code indicates that NULL data was passed in to the function.

D2FS_NULLOBJ

This return code indicates that the operation returned a NULL object.

D2FS_NULLPROPERTY

This return code indicates that the operation returned a NULL property.

D2FS_OBJNOTFOUND

This return code indicates that the specified object was not found.

D2FS_OBJNOTUNIQUE

This return code indicates that the operation failed because the object being created/placed was not unique.  An object with this name already exists.

D2FS_TYPEMISMATCH

This return code indicates that the type you passed in does not match the actual object.

D2FS_WARN

This return code indicates that the operation failed partially, however, the error was not fatal.

D2FS_WRONGOBJ

This return code indicates that you have supplied an unexpected object.

D2FS_WRONGPARENT

This return code indicates that you have specified an unexpected parent.


Open API macros by objects

  Related Topics

This section describes the macros as they appear in the header files of the Form Builder Open API. Functions are organized by the associated Forms Open API object. Each macro includes the argument list and a short description.

API Macros by Objects

Alerts

Attached Libraries

Blocks

Canvases

Data Source Arguments

Data Source Columns

Editors

Form Modules

Form Parameters

Graphics

Items

List of Values Column Mapping

List of Values

Menu Objects

Menu Modules

Menu Items

Menu Parameters

Objects (Generic Objects)

Object Groups

Object Group Children

Object Libraries

Program Units

Property Classes

Radio Buttons

Record Groups

Record Group Column Specification

Relation Objects

Report Objects

Tab Pages

Triggers

Visual Attributes

Windows


Alert object macros

  Related Topics

This section describes the macros of the Form Builder Open API Alert object.

d2faltg_alt_msg( ctx, obj, val );

This macro returns the value of the D2FP_ALT_MSG property of the alert object as type text.

d2faltg_alt_sty( ctx, obj, val );

This macro returns the value of the D2FP_ALT_STY property of the alert object as type number.

d2faltg_back_color( ctx, obj, val );

This macro returns the value of the Background Color property of the alert object as type text.

d2faltg_btn_1_lbl( ctx, obj, val );

This macro returns the value of the Button Number 1 property of the alert object as type text.

d2faltg_btn_2_lbl( ctx, obj, val );

This macro returns the value of the Button Number 2 property of the alert object as type text.

d2faltg_btn_3_lbl( ctx, obj, val );

This macro returns the value of the Button Number 3 property of the alert object as type text.

d2faltg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the alert object as a type dvoid pointer.

d2faltg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the alert object as type text.

d2faltg_dflt_alt_btn( ctx, obj, val );

This macro returns the value of the Default Alert Button property of the alert object as type number.

d2faltg_fill_pat( ctx, obj, val );

This macro returns the value of the Fill Pattern property of the alert object as type text.

d2faltg_font_nam( ctx, obj, val );

This macro returns the value of the Font Name property of the alert object as type text.

d2faltg_font_siz( ctx, obj, val );

This macro returns the value of the Font Size property of the alert object as type number.

d2faltg_font_spcing( ctx, obj, val );

This macro returns the value of the Font Spacing property of the alert object as type number.

d2faltg_font_sty( ctx, obj, val );

This macro returns the value of the Font Style property of the alert object as type number.

d2faltg_font_wght( ctx, obj, val );

This macro returns the value of the Font Weight property of the alert object as type number.

d2faltg_fore_color( ctx, obj, val );

This macro returns the value of the Foreground Color property of the alert object as type text.

d2faltg_lang_dir( ctx, obj, val );

This macro returns the value of the Language Direction property of the alert object as type number.

d2faltg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the alert object as type object.

d2faltg_name( ctx, obj, val );

This macro returns the value of the Name property of the alert object as type text.

d2faltg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the alert object as type object.

d2faltg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the alert object as type object.

d2faltg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the alert object as type text.

d2faltg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the alert object as type text.

d2faltg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the alert object as type number.

d2faltg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the alert object as type number.

d2faltg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the alert object as type text.

d2faltg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the alert object as type text.

d2faltg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the alert object as type object.

d2faltg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the alert object as type object.

d2faltg_title( ctx, obj, val );

This macro returns the value of the Title property of the alert object as type text.

d2faltg_vat_nam( ctx, obj, val );

This macro This macro returns the value of the Visual Attribute Group property of the alert object as type text.

d2faltg_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_VAT_OBJ property of the alert object as type object.

d2faltg_white_on_black( ctx, obj, val );

This macro returns the value of the D2FP_WHITE_ON_BLACK property of the alert object as type boolean.

d2falts_alt_msg( ctx, obj, val );

This macro sets the value of the Alert Message property of the alert object.

d2falts_alt_sty( ctx, obj, val );

This macro sets the value of the Style property of the alert object.

d2falts_back_color( ctx, obj, val );

This macro sets the value of the Background Color property of the alert object.

d2falts_btn_1_lbl( ctx, obj, val );

This macro sets the value of the Button Number 1 property of the alert object.

d2falts_btn_2_lbl( ctx, obj, val );

This macro sets the value of the Button Number 2 property of the alert object.

d2falts_btn_3_lbl( ctx, obj, val );

This macro returns the value of the Button Number 3 property of the alert object.

d2falts_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the alert object.

d2falts_comment( ctx, obj, val );

This macro sets the value of the Comments property of the alert object.

d2falts_dflt_alt_btn( ctx, obj, val );

This macro sets the value of the Default Alert Button property of the alert object.

d2falts_fill_pat( ctx, obj, val );

This macro sets the value of the Fill Pattern property of the alert object.

d2falts_font_nam( ctx, obj, val );

This macro sets the value of the Font Name property of the alert object.

d2falts_font_siz( ctx, obj, val );

This macro sets the value of the Font Size property of the alert object.

d2falts_font_spcing( ctx, obj, val );

This macro sets the value of the Font Spacing property of the alert object.

d2falts_font_sty( ctx, obj, val );

This macro sets the value of the Font Style property of the alert object.

d2falts_font_wght( ctx, obj, val );

This macro sets the value of the Font Weight property of the alert object.

d2falts_fore_color( ctx, obj, val );

This macro sets the value of the Foreground Color property of the alert object.

d2falts_lang_dir( ctx, obj, val );

This macro sets the value of the Language Direction property of the alert object.

d2falts_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the alert object.

d2falts_name( ctx, obj, val );

This macro sets the value of the Name property of the alert object.

d2falts_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the alert object.

d2falts_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the alert object.

d2falts_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the alert object.

d2falts_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the alert object.

d2falts_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the alert object.

d2falts_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the alert object.

d2falts_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the alert object.

d2falts_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM  property of the alert object.

d2falts_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the alert object.

d2falts_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the alert object.

d2falts_title( ctx, obj, val );

This macro sets the value of the Title property of the alert object.

d2falts_vat_nam( ctx, obj, val );

This macro sets the value of the Visual Attribute Group property of the alert object.

d2falts_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_VAT_OBJ property of the alert object.

d2falts_white_on_black( ctx, obj, val );

This macro sets the value of the White on Black property of the alert object.


Attached library object macros

  Related Topics

This section describes the macros of the Form Builder Open API Attached Library object.

d2falbg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the attached library as a type dvoid pointer.

d2falbg_comment( ctx, obj, val );

This macro returns the value of the Comment property of the attached library as type text.

d2falbg_lib_loc( ctx, obj, val );

This macro returns the value of the PL/SQL Library Location property of the attached library as type text.

d2falbg_lib_src( ctx, obj, val );

This macro returns the value of the PL/SQL Library Source property of the attached library as type number.

d2falbg_name( ctx, obj, val );

This macro returns the value of the Name property of the attached library as type text.

d2falbg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the attached library as type object.

d2falbg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the attached library as type object.

d2falbs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the attached library.

d2falbs_comment( ctx, obj, val );

This macro sets the value of the Comment property of the attached library.


Block object macros

  Related Topics

This section describes the macros of the Form Builder Open API Block object.

d2fblkg_back_color( ctx, obj, val );

This macro returns the value of the Background Color property of the block as type text.

d2fblkg_blk_description( ctx, obj, val );

This macro returns the value of the Data Block Description property of the block as type text.

d2fblkg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the block as a type dvoid pointer.

d2fblkg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the block as type text.

d2fblkg_db_blk( ctx, obj, val );

This macro returns the value of the Database Block property of the block as type boolean.

d2fblkg_del_allowed( ctx, obj, val );

This macro returns the value of the Delete Allowed property of the block as type boolean.

d2fblkg_del_dat_src_arg( ctx, obj, val );

This macro returns the value of the Delete Data Source Argument property of the block as type object.

d2fblkg_del_dat_src_col( ctx, obj, val );

This macro returns the value of the Delete Data Source Column property of the block as type object.

d2fblkg_del_proc_nam( ctx, obj, val );

This macro returns the value of the Delete Procedure Name property of the block as type text.

d2fblkg_dml_ary_siz( ctx, obj, val );

This macro returns the value of the DML Array Size property of the block as type number.

d2fblkg_dml_dat_nam( ctx, obj, val );

This macro returns the value of the DML Data Target Name property of the block as type text.

d2fblkg_dml_dat_typ( ctx, obj, val );

This macro returns the value of the DML Data Target Type property of the block as type number.

d2fblkg_enfrc_col_security( ctx, obj, val );

This macro returns the value of the Enforce Column Security property of the block as type boolean.

d2fblkg_enfrc_prmry_key( ctx, obj, val );

This macro returns the value of the Enforce Primary Key property of the block as type boolean.

d2fblkg_fill_pat( ctx, obj, val );

This macro returns the value of the Fill Pattern property of the block as type text.

d2fblkg_font_nam( ctx, obj, val );

This macro returns the value of the Font Name property of the block as type text.

d2fblkg_font_siz( ctx, obj, val );

This macro returns the value of the Font Size property of the block as type number.

d2fblkg_font_spcing( ctx, obj, val );

This macro returns the value of the Font Spacing property of the block as type number.

d2fblkg_font_sty( ctx, obj, val );

This macro returns the value of the Font Style property of the block as type number.

d2fblkg_font_wght( ctx, obj, val );

This macro returns the value of the Font Weight property of the block as type number.

d2fblkg_fore_color( ctx, obj, val );

This macro returns the value of the Foreground Color property of the block as type text.

d2fblkg_ins_dat_src_arg( ctx, obj, val );

This macro returns the value of the D2FP_INS_DAT_SRC_ARG property of the block as type object.

d2fblkg_ins_dat_src_col( ctx, obj, val );

This macro returns the value of the D2FP_INS_DAT_SRC_COL property of the block as type object.

d2fblkg_insrt_allowed( ctx, obj, val );

This macro returns the value of the Insert Allowed property of the block as type boolean.

d2fblkg_insrt_proc_nam( ctx, obj, val );

This macro returns the value of the Insert Procedure Name property of the block as type text.

d2fblkg_item( ctx, obj, val );

This macro returns the value of the D2FP_ITEM property of the block as type object.

d2fblkg_key_mode( ctx, obj, val );

This macro returns the value of the Key Mode property of the block as type number.

d2fblkg_lang_dir( ctx, obj, val );

This macro returns the value of the Language Direction property of the block as type number.

d2fblkg_lock_dat_src( ctx, obj, val );

This macro returns the value of the Lock Data Source property of the block as type object.

d2fblkg_lock_dat_src_col( ctx, obj, val );

This macro returns the value of the Lock Data Source Column property of the block as type object.

d2fblkg_lock_mode( ctx, obj, val );

This macro returns the value of the Locking Mode property of the block as type number.

d2fblkg_lock_proc_nam( ctx, obj, val );

This macro returns the value of the Lock Procedure Name property of the block as type text.

d2fblkg_lst_in_blk_mnu( ctx, obj, val );

This macro returns the value of the Listed In Block Menu property of the block as type boolean.

d2fblkg_max_qry_time( ctx, obj, val );

This macro returns the value of the Maximum Query Time property of the block as type number.

d2fblkg_max_recs_fetched( ctx, obj, val );

This macro returns the value of the D2FP_MAX_RECORDS_FETCHED property of the block as type number.

d2fblkg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the block as type object.

d2fblkg_name( ctx, obj, val );

This macro returns the value of the Name property of the block as type text.

d2fblkg_navigation_sty( ctx, obj, val );

This macro returns the value of the Navigation Style property of the block as type number.

d2fblkg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the block as type object.

d2fblkg_nxt_navigation_blk_nam( ctx, obj, val );

This macro returns the value of the D2FP_NXT_NAVIGATION_BLK_OBJ property of the block as type text.

d2fblkg_nxt_navigation_blk_obj( ctx, obj, val );

This macro returns the value of the Next Navigation Block property of the block as type object.

d2fblkg_opt_hint( ctx, obj, val );

This macro returns the value of the Optimizer Hint property of the block as type text.

d2fblkg_ordr_by_clause( ctx, obj, val );

This macro returns the value of the ORDER BY Clause property of the block as type text.

d2fblkg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the block as type object.

d2fblkg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the block as type text.

d2fblkg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the block as type text.

d2fblkg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the block as type number.

d2fblkg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_MODTYPE property of the block as type number.

d2fblkg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the block as type text.

d2fblkg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAME property of the block as type text.

d2fblkg_precomp_summ( ctx, obj, val );

This macro returns the value of the D2FP_PRECOMP_SUMMNO property of the block as type boolean.

d2fblkg_prev_navigation_blk_nam( ctx, obj, val );

This macro returns the value of the Previous Navigation Block property of the block as type text.

d2fblkg_prev_navigation_blk_obj( ctx, obj, val );

This macro returns the value of the D2FP_PREV_NAVIGATION_BLK_OBJ property of the block as type object.

d2fblkg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the block as type object.

d2fblkg_qry_all_recs( ctx, obj, val );

This macro returns the value of the Query All Record property of the block as type boolean.

d2fblkg_qry_allowed( ctx, obj, val );

This macro returns the value of the Query Allowed property of the block as type boolean.

d2fblkg_qry_dat_src_arg( ctx, obj, val );

This macro returns the value of the Query Data Source Name property of the block as type object.

d2fblkg_qry_dat_src_col( ctx, obj, val );

This macro returns the value of the Query Data Source Column property of the block as type object.

d2fblkg_qry_dat_src_nam( ctx, obj, val );

This macro returns the value of the Query Data Source Name property of the block as type text.

d2fblkg_qry_dat_src_typ( ctx, obj, val );

This macro returns the value of the Query Data Source Type property of the block as type number.

d2fblkg_rec_ornt( ctx, obj, val );

This macro returns the value of the Record Orientation property of the block as type number.

d2fblkg_rec_vat_grp_nam( ctx, obj, val );

This macro returns the value of the Current Record Visual Attribute Group property of the block as type text.

d2fblkg_rec_vat_grp_obj( ctx, obj, val );

This macro returns the value of the D2FP_REC_VAT_GRP_OBJ property of the block as type object.

d2fblkg_recs_buffered_count( ctx, obj, val );

This macro returns the value of the Number of Records Buffered property of the block as type number.

d2fblkg_recs_disp_count( ctx, obj, val );

This macro returns the value of the Number of Records Displayed property of the block as type number.

d2fblkg_recs_fetched_count( ctx, obj, val );

This macro returns the value of the D2FP_RECS_FETCHED_COUNT property of the block as type number.

d2fblkg_rel( ctx, obj, val );

This macro returns the value of the D2FP_REL property of the block as type object.

d2fblkg_rev_dir( ctx, obj, val );

This macro calls returns the value of the Reverse Direction property of the block as type boolean.

d2fblkg_scrlbr_cnv_nam( ctx, obj, val );

This macro returns the value of the Scroll Bar Canvas property of the block as type text.

d2fblkg_scrlbr_cnv_obj( ctx, obj, val );

This macro returns the value of the D2FP_SCRLBR_CNV_OBJ property of the block as type object.

d2fblkg_scrlbr_hgt( ctx, obj, val );

This macro returns the value of the Scroll Bar Height property of the block as type number.

d2fblkg_srclbr_ornt( ctx, obj, val );

This macro returns the value of the Scroll Bar Orientation property of the block as type number.

d2fblkg_scrlbr_tbp_nam( ctx, obj, val );

This macro returns the value of the Scroll Bar Tab Page property of the block as type text.

d2fblkg_scrlbr_tbp_obj( ctx, obj, val );

This macro returns the value of the D2FP_SCRLBR_TSP_OBJ property of the block as type object.

d2fblkg_scrlbr_wid( ctx, obj, val );

This macro returns the value of the Scroll Bar Width property of the block as type number.

d2fblkg_scrlbr_x_pos( ctx, obj, val );

This macro returns the value of the Scroll Bar X Position property of the block as type number.

d2fblkg_scrlbr_y_pos( ctx, obj, val );

This macro returns the value of the Scroll Bar Y Position property of the block as type number.

d2fblkg_show_scrlbr( ctx, obj, val );

This macro returns the value of the Show Scroll Bar property of the block as type boolean.

d2fblkg_sngl_rec( ctx, obj, val );

This macro returns the value of the Single Record property of the block as type boolean.

d2fblkg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the block as type object.

d2fblkg_trigger( ctx, obj, val );

This macro returns the value of the D2FP_TRIGGER property of the block as type object.

d2fblkg_upd_dat_src_arg( ctx, obj, val );

This macro returns the value of the Update Data Source Argument property of the block as type object.

d2fblkg_upd_dat_src_col( ctx, obj, val );

This macro returns the value of the Update Data Source Column property of the block as type object.

d2fblkg_updt_allowed( ctx, obj, val );

This macro returns the value of the Update Allowed property of the block as type boolean.

d2fblkg_updt_changed_cols( ctx, obj, val );

This macro returns the value of the Update Changed Columns Only property of the block as type boolean.

d2fblkg_updt_proc_name( ctx, obj, val );

This macro returns the value of the Update Procedure Name property of the block as type text.

d2fblkg_vat_nam( ctx, obj, val );

This macro returns the value of the Visual Attribute Group property of the block as type text.

d2fblkg_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_VAT_OBJ property of the block as type object.

d2fblkg_where_clause( ctx, obj, val );

This macro returns the value of the WHERE Clause property of the block as type text.

d2fblkg_white_on_black( ctx, obj, val );

This macro returns the value of the White on Black property of the block as type boolean.

d2fblks_back_color( ctx, obj, val );

This macro sets the value of the Background Color property of the block.

d2fblks_blk_description( ctx, obj, val );

This macro sets the value of the Data Block Description property of the block.

d2fblks_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the block.

d2fblks_comment( ctx, obj, val );

This macro sets the value of the Comments property of the block.

d2fblks_db_blk( ctx, obj, val );

This macro sets the value of the Database Block property of the block.

d2fblks_del_allowed( ctx, obj, val );

This macro sets the value of the Delete Allowed property of the block.

d2fblks_del_dat_src_arg( ctx, obj, val );

This macro sets the value of the Delete Data Source Argument property of the block.

d2fblks_del_dat_src_col( ctx, obj, val );

This macro sets the value of the Delete Data Source Column property of the block.

d2fblks_del_proc_nam( ctx, obj, val );

This macro sets the value of the Delete Procedure Name property of the block.

d2fblks_dml_ary_siz( ctx, obj, val );

This macro sets the value of the DML Array Size property of the block.

d2fblks_dml_dat_nam( ctx, obj, val );

This macro sets the value of the DML Data Target Name property of the block.

d2fblks_dml_dat_typ( ctx, obj, val );

This macro sets the value of the DML Data Target Type property of the block.

d2fblks_enfrc_col_security( ctx, obj, val );

This macro sets the value of the Enforce Column Security property of the block.

d2fblks_enfrc_prmry_key( ctx, obj, val );

This macro sets the value of the Enforce Primary Key property of the block.

d2fblks_fill_pat( ctx, obj, val );

This macro sets the value of the Fill Pattern property of the block.

d2fblks_font_nam( ctx, obj, val );

This macro sets the value of the Font Name property of the block.

d2fblks_font_siz( ctx, obj, val );

This macro sets the value of the Font Size property of the block.

d2fblks_font_spcing( ctx, obj, val );

This macro sets the value of the Font Spacing property of the block.

d2fblks_font_sty( ctx, obj, val );

This macro sets the value of the Font Style property of the block.

d2fblks_font_wght( ctx, obj, val );

This macro sets the value of the Font Weight property of the block.

d2fblks_fore_color( ctx, obj, val );

This macro sets the value of the Foreground Color property of the block.

d2fblks_ins_dat_src_arg( ctx, obj, val );

This macro sets the value of the D2FP_INS_DAT_SRC_ARG property of the block.

d2fblks_ins_dat_src_col( ctx, obj, val );

This macro sets the value of the D2FP_INS_DAT_SRC_COL property of the block.

d2fblks_insrt_allowed( ctx, obj, val );

This macro sets the value of the Insert Allowed property of the block.

d2fblks_insrt_proc_nam( ctx, obj, val );

This macro sets the value of the Insert Procedure Name property of the block.

d2fblks_item( ctx, obj, val );

This macro sets the value of the D2FP_ITEM property of the block.

d2fblks_key_mode( ctx, obj, val );

This macro sets the value of the Key Mode property of the block.

d2fblks_lang_dir( ctx, obj, val );

This macro sets the value of the Language Direction property of the block.

d2fblks_lock_dat_src( ctx, obj, val );

This macro sets the value of the Lock Data Source property of the block.

d2fblks_lock_dat_src_col( ctx, obj, val );

This macro sets the value of the Lock Data Source Column property of the block.

d2fblks_lock_mode( ctx, obj, val );

This macro sets the value of the Locking Mode property of the block.

d2fblks_lock_proc_nam( ctx, obj, val );

This macro sets the value of the Lock Procedure Name property of the block.

d2fblks_lst_in_blk_mnu( ctx, obj, val );

This macro sets the value of the Listed In Block Menu property of the block.

d2fblks_max_qry_time( ctx, obj, val );

This macro sets the value of the Maximum Query Time property of the block.

d2fblks_max_recs_fetched( ctx, obj, val );

This macro sets the value of the Max Records Fetched property of the block.

d2fblks_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the block.

d2fblks_name( ctx, obj, val );

This macro sets the value of the Name property of the block.

d2fblks_navigation_sty( ctx, obj, val );

This macro sets the value of the Navigation Style property of the block.

d2fblks_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the block.

d2fblks_nxt_navigation_blk_nam( ctx, obj, val );

This macro sets the value of the D2FP_NXT_NAVIGATION_BLK_OBJ property of the block.

d2fblks_nxt_navigation_blk_obj( ctx, obj, val );

This macro sets the value of the Next Navigation Block property of the block.

d2fblks_opt_hint( ctx, obj, val );

This macro sets the value of the Optimizer Hint property of the block.

d2fblks_ordr_by_clause( ctx, obj, val );

This macro sets the value of the ORDER BY Clause property of the block.

d2fblks_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the block.

d2fblks_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the block.

d2fblks_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the block.

d2fblks_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the block.

d2fblks_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_MODTYPE property of the block.

d2fblks_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the block.

d2fblks_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAME property of the block.

d2fblks_precomp_summ( ctx, obj, val );

This macro sets the value of the D2FP_PRECOMP_SUMMNO property of the block.

d2fblks_prev_navigation_blk_nam( ctx, obj, val );

This macro sets the value of the Previous Navigation Block property of the block.

d2fblks_prev_navigation_blk_obj( ctx, obj, val );

This macro sets the value of the D2FP_PREV_NAVIGATION_BLK_OBJ property of the block.

d2fblks_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the block.

d2fblks_qry_all_recs( ctx, obj, val );

This macro sets the value of the Query All Record property of the block.

d2fblks_qry_allowed( ctx, obj, val );

This macro sets the value of the Query Allowed property of the block.

d2fblks_qry_dat_src_arg( ctx, obj, val );

This macro sets the value of the Query Data Source Name property of the block.

d2fblks_qry_dat_src_col( ctx, obj, val );

This macro sets the value of the Query Data Source Column property of the block.

d2fblks_qry_dat_src_nam( ctx, obj, val );

This macro sets the value of the Query Data Source Name property of the block.

d2fblks_qry_dat_src_typ( ctx, obj, val );

This macro sets the value of the Query Data Source Type property of the block.

d2fblks_rec_ornt( ctx, obj, val );

This macro sets the value of the Record Orientation property of the block.

d2fblks_rec_vat_grp_nam( ctx, obj, val );

This macro sets the value of the Current Record Visual Attribute Group property of the block.

d2fblks_rec_vat_grp_obj( ctx, obj, val );

This macro sets the value of the D2FP_REC_VAT_GRP_OBJ property of the block.

d2fblks_recs_buffered_count( ctx, obj, val );

This macro sets the value of the Number of Records Buffered property of the block.

d2fblks_recs_disp_count( ctx, obj, val );

This macro sets the value of the Number of Records Displayed property of the block.

d2fblks_recs_fetched_count( ctx, obj, val );

This macro sets the value of the D2FP_RECS_FETCHED_COUNT property of the block.

d2fblks_rel( ctx, obj, val );

This macro sets the value of the D2FP_REL property of the block.

d2fblks_rev_dir( ctx, obj, val );

This macro calls sets the value of the Reverse Direction property of the block.

d2fblks_scrlbr_cnv_nam( ctx, obj, val );

This macro sets the value of the Scroll Bar Canvas property of the block.

d2fblks_scrlbr_cnv_obj( ctx, obj, val );

This macro sets the value of the D2FP_SCRLBR_CNV_OBJ property of the block.

d2fblks_scrlbr_hgt( ctx, obj, val );

This macro sets the value of the Scroll Bar Height property of the block.

d2fblks_srclbr_ornt( ctx, obj, val );

This macro sets the value of the Scroll Bar Orientation property of the block.

d2fblks_scrlbr_tbp_nam( ctx, obj, val );

This macro sets the value of the Scroll Bar Tab Page property of the block.

d2fblks_scrlbr_tbp_obj( ctx, obj, val );

This macro sets the value of the D2FP_SCRLBR_TSP_OBJ property of the block.

d2fblks_scrlbr_wid( ctx, obj, val );

This macro sets the value of the Scroll Bar Width property of the block.

d2fblks_scrlbr_x_pos( ctx, obj, val );

This macro sets the value of the Scroll Bar X Position property of the block.

d2fblks_scrlbr_y_pos( ctx, obj, val );

This macro sets the value of the Scroll Bar Y Position property of the block.

d2fblks_show_scrlbr( ctx, obj, val );

This macro sets the value of the Show Scroll Bar property of the block.

d2fblks_sngl_rec( ctx, obj, val );

This macro sets the value of the Single Record property of the block.

d2fblks_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the block.

d2fblks_trigger( ctx, obj, val );

This macro sets the value of the D2FP_TRIGGER property of the block.

d2fblks_upd_dat_src_arg( ctx, obj, val );

This macro sets the value of the Update Data Source Argument property of the block.

d2fblks_upd_dat_src_col( ctx, obj, val );

This macro sets the value of the Update Data Source Column property of the block.

d2fblks_updt_allowed( ctx, obj, val );

This macro sets the value of the Update Allowed property of the block.

d2fblks_updt_changed_cols( ctx, obj, val );

This macro sets the value of the Update Changed Columns Only property of the block.

d2fblks_updt_proc_name( ctx, obj, val );

This macro sets the value of the Update Procedure Name property of the block.

d2fblks_vat_nam( ctx, obj, val );

This macro sets the value of the Visual Attribute Group property of the block.

d2fblks_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_VAT_OBJ property of the block.

d2fblks_where_clause( ctx, obj, val );

This macro sets the value of the WHERE Clause property of the block.

d2fblks_white_on_black( ctx, obj, val );

This macro sets the value of the White on Black property of the block.


Canvas object macros

  Related Topics

This section describes the macros of the Form Builder Open API Canvas object.

d2fcnvg_back_color( ctx, obj, val );

This macro returns the value of the Background Color property of the canvas as type text.

d2fcnvg_bevel( ctx, obj, val );

This macro returns the value of the Bevel property of the canvas as type number.

d2fcnvg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the canvas as a type dvoid pointer.

d2fcnvg_cnv_typ( ctx, obj, val );

This macro returns the value of the Canvas Type property of the canvas as type number.

d2fcnvg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the canvas as type text.

d2fcnvg_fill_pat( ctx, obj, val );

This macro returns the value of the Fill Pattern property of the canvas as type text.

d2fcnvg_font_nam( ctx, obj, val );

This macro returns the value of the Font Name property of the canvas as type text.

d2fcnvg_font_siz( ctx, obj, val );

This macro returns the value of the Font Size property of the canvas as type number.

d2fcnvg_font_spcing( ctx, obj, val );

This macro returns the value of the Font Spacing property of the canvas as type number.

d2fcnvg_font_sty( ctx, obj, val );

This macro returns the value of the Font Style property of the canvas as type number.

d2fcnvg_font_wght( ctx, obj, val );

This macro returns the value of the Font Weight property of the canvas as type number.

d2fcnvg_fore_color( ctx, obj, val );

This macro returns the value of the Foreground Color property of the canvas as type text.

d2fcnvg_graphic( ctx, obj, val );

This macro returns the value of the D2FP_GRAPHIC property of the canvas as type object.

d2fcnvg_height( ctx, obj, val );

This macro returns the value of the Width/Height property of the canvas as type number.

d2fcnvg_lang_dir( ctx, obj, val );

This macro returns the value of the Language Direction property of the canvas as type number.

d2fcnvg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the canvas as type object.

d2fcnvg_name( ctx, obj, val );

This macro returns the value of the Name property of the canvas as type text.

d2fcnvg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the canvas as type object.

d2fcnvg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the canvas as type object.

d2fcnvg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the canvas as type text.

d2fcnvg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the canvas as type text.

d2fcnvg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the canvas as type number.

d2fcnvg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYPE property of the canvas as type number.

d2fcnvg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the canvas as type text.

d2fcnvg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAME property of the canvas as type text.

d2fcnvg_popup_mnu_nam( ctx, obj, val );

This macro returns the value of the Popup Menu property of the canvas as type text.

d2fcnvg_popup_mnu_obj( ctx, obj, val );

This macro returns the value of the D2FP_POPUP_MNU_OBJ property of the canvas as type text.

d2fcnvg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the canvas as type object.

d2fcnvg_raise_on_ent( ctx, obj, val );

This macro returns the value of the Raise On Entry property of the canvas as type boolean.

d2fcnvg_show_horz_scrlbr( ctx, obj, val );

This macro returns the value of the Show Horizontal Scroll Bar property of the canvas as type boolean.

d2fcnvg_show_vert_scrlbr( ctx, obj, val );

This macro returns the value of the Show Vertical Scroll Bar property of the canvas as type boolean.

d2fcnvg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the canvas as type object.

d2fcnvg_tab_att_edge( ctx, obj, val );

This macro returns the value of the Tab Attachment Edge property of the canvas as type number.

d2fcnvg_tab_page( ctx, obj, val );

This macro returns the value of the Tab Page property of the canvas as type object.

d2fcnvg_tab_style( ctx, obj, val );

This macro returns the value of the Tab Style property of the canvas as type number.

d2fcnvg_vat_nam( ctx, obj, val );

This macro returns the value of the Visual Attribute Group property of the canvas as type text.

d2fcnvg_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_VAT_OBJ property of the canvas as type object.

d2fcnvg_visible( ctx, obj, val );

This macro returns the value of the Visible property of the canvas as type boolean.

d2fcnvg_vprt_hgt( ctx, obj, val );

This macro returns the value of the Viewport Height property of the canvas as type number.

d2fcnvg_vprt_wid( ctx, obj, val );

This macro returns the value of the Viewport Width property of the canvas as type number.

d2fcnvg_vprt_x_pos( ctx, obj, val );

This macro returns the value of the Viewport X Position property of the canvas as type number.

d2fcnvg_vprt_x_pos_on_cnv( ctx, obj, val );

This macro returns the value of the Viewport X Position On Canvas property of the canvas as type number.

d2fcnvg_vprt_y_pos( ctx, obj, val );

This macro returns the value of the Viewport Y Position property of the canvas as type number.

d2fcnvg_vprt_y_pos_on_cnv( ctx, obj, val );

This macro returns the value of the Viewport Y Position On Canvas property of the canvas as type number.

d2fcnvg_white_on_black( ctx, obj, val );

This macro returns the value of the White on Black property of the canvas as type boolean.

d2fcnvg_width( ctx, obj, val );

This macro returns the value of the Width/Height property of the canvas as type number.

d2fcnvg_wnd_nam( ctx, obj, val );

This macro returns the value of the Window property of the canvas as type text.

d2fcnvg_wnd_obj( ctx, obj, val );

This macro returns the value of the D2FP_WND_OBJ property of the canvas as type object.

d2fcnvs_back_color( ctx, obj, val );

This macro sets the value of the Background Color property of the canvas.

d2fcnvs_bevel( ctx, obj, val );

This macro sets the value of the Bevel property of the canvas.

d2fcnvs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the canvas.

d2fcnvs_cnv_typ( ctx, obj, val );

This macro sets the value of the Canvas Type property of the canvas.

d2fcnvs_comment( ctx, obj, val );

This macro sets the value of the Comments property of the canvas.

d2fcnvs_fill_pat( ctx, obj, val );

This macro sets the value of the Fill Pattern property of the canvas.

d2fcnvs_font_nam( ctx, obj, val );

This macro sets the value of the Font Name property of the canvas.

d2fcnvs_font_siz( ctx, obj, val );

This macro sets the value of the Font Size property of the canvas.

d2fcnvs_font_spcing( ctx, obj, val );

This macro sets the value of the Font Spacing property of the canvas.

d2fcnvs_font_sty( ctx, obj, val );

This macro sets the value of the Font Style property of the canvas.

d2fcnvs_font_wght( ctx, obj, val );

This macro sets the value of the Font Weight property of the canvas.

d2fcnvs_fore_color( ctx, obj, val );

This macro sets the value of the Foreground Color property of the canvas.

d2fcnvs_graphic( ctx, obj, val );

This macro sets the value of the D2FP_GRAPHIC property of the canvas.

d2fcnvs_height( ctx, obj, val );

This macro sets the value of the Width/Height property of the canvas.

d2fcnvs_lang_dir( ctx, obj, val );

This macro sets the value of the Language Direction property of the canvas.

d2fcnvs_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the canvas.

d2fcnvs_name( ctx, obj, val );

This macro sets the value of the Name property of the canvas.

d2fcnvs_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the canvas.

d2fcnvs_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the canvas.

d2fcnvs_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the canvas.

d2fcnvs_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the canvas.

d2fcnvs_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the canvas.

d2fcnvs_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYPE property of the canvas.

d2fcnvs_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the canvas.

d2fcnvs_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAME property of the canvas.

d2fcnvs_popup_mnu_nam( ctx, obj, val );

This macro sets the value of the Popup Menu property of the canvas.

d2fcnvs_popup_mnu_obj( ctx, obj, val );

This macro sets the value of the D2FP_POPUP_MNU_OBJ property of the canvas.

d2fcnvs_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the canvas.

d2fcnvs_raise_on_ent( ctx, obj, val );

This macro sets the value of the Raise On Entry property of the canvas.

d2fcnvs_show_horz_scrlbr( ctx, obj, val );

This macro sets the value of the Show Horizontal Scroll Bar property of the canvas.

d2fcnvs_show_vert_scrlbr( ctx, obj, val );

This macro sets the value of the Show Vertical Scroll Bar property of the canvas.

d2fcnvs_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the canvas.

d2fcnvs_tab_att_edge( ctx, obj, val );

This macro sets the value of the Tab Attachment Edge property of the canvas.

d2fcnvs_tab_page( ctx, obj, val );

This macro sets the value of the Tab Page property of the canvas.

d2fcnvs_tab_style( ctx, obj, val );

This macro sets the value of the Tab Style property of the canvas.

d2fcnvs_vat_nam( ctx, obj, val );

This macro sets the value of the Visual Attribute Group property of the canvas.

d2fcnvs_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_VAT_OBJ property of the canvas.

d2fcnvs_visible( ctx, obj, val );

This macro sets the value of the Visible property of the canvas.

d2fcnvs_vprt_hgt( ctx, obj, val );

This macro sets the value of the Viewport Height property of the canvas.

d2fcnvs_vprt_wid( ctx, obj, val );

This macro sets the value of the Viewport Width property of the canvas.

d2fcnvs_vprt_x_pos( ctx, obj, val );

This macro sets the value of the Viewport X Position property of the canvas.

d2fcnvs_vprt_x_pos_on_cnv( ctx, obj, val );

This macro sets the value of the Viewport X Position On Canvas property of the canvas.

d2fcnvs_vprt_y_pos( ctx, obj, val );

This macro sets the value of the Viewport Y Position property of the canvas.

d2fcnvs_vprt_y_pos_on_cnv( ctx, obj, val );

This macro sets the value of the Viewport Y Position On Canvas property of the canvas.

d2fcnvs_white_on_black( ctx, obj, val );

This macro sets the value of the White on Black property of the canvas.

d2fcnvs_width( ctx, obj, val );

This macro sets the value of the Width/Height property of the canvas.

d2fcnvs_wnd_nam( ctx, obj, val );

This macro sets the value of the Window property of the canvas.

d2fcnvs_wnd_obj( ctx, obj, val );

This macro sets the value of the D2FP_WND_OBJ property of the canvas.


Datasource argument object macros

  Related Topics

This section describes the macros of the Form Builder Open API Data Source Argument object.

d2fdsag_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the data source argument object as a type dvoid pointer.

d2fdsag_dsa_mode( ctx, obj, val );

This macro returns the value of the D2FP_DSA_MODE property of the data source argument object as type number.

d2fdsag_dsa_nam( ctx, obj, val );

This macro returns the value of the D2FP_DSA_NAM property of the data source argument object as type text.

d2fdsag_dsa_typ( ctx, obj, val );

This macro returns the value of the D2FP_DSA_TYP property of the data source argument object as type number.

d2fdsag_dsa_typ_nam( ctx, obj, val );

This macro returns the value of the D2FP_DSA_TYP_NAM property of the data source argument object as type text.

d2fdsag_dsa_val( ctx, obj, val );

This macro returns the value of the D2FP_DSA_VAL property of the data source argument object as type text.

d2fdsag_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the data source argument object as type object.

d2fdsag_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the data source argument object as type object.

d2fdsas_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the data source argument object.

d2fdsas_dsa_mode( ctx, obj, val );

This macro sets the value of the D2FP_DSA_MODE property of the data source argument object.

d2fdsas_dsa_nam( ctx, obj, val );

This macro sets the value of the D2FP_DSA_NAM property of the data source argument object.

d2fdsas_dsa_typ( ctx, obj, val );

This macro sets the value of the D2FP_DSA_TYP property of the data source argument object.

d2fdsas_dsa_typ_nam( ctx, obj, val );

This macro sets the value of the D2FP_DSA_TYP_NAM property of the data source argument object.

d2fdsas_dsa_val( ctx, obj, val );

This macro sets the value of the D2FP_DSA_VAL property of the data source argument object.


Datasource column object macros

  Related Topics

This section describes the macros of the Form Builder Open API Data Source Column object.

d2fdscg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the data source column object as a type dvoid pointer.

d2fdscg_dsc_len( ctx, obj, val );

This macro returns the value of the D2FP_DSC_LEN property of the data source column object as a type number.

d2fdscg_dsc_mandatory( ctx, obj, val );

This macro returns the value of the D2FP_DSC_MANDATORY property of the data source column object as a type boolean.

d2fdscg_dsc_nam( ctx, obj, val );

This macro returns the value of the D2FP_DSC_NAM property of the data source column object as a type text.

d2fdscg_dsc_precision( ctx, obj, val );

This macro returns the value of the D2FP_DSC_PRECISION property of the data source column object as a type number.

d2fdscg_dsc_scale( ctx, obj, val );

This macro returns the value of the D2FP_DSC_SCALE property of the data source column object as a type number.

d2fdscg_dsc_typ( ctx, obj, val );

This macro returns the value of the D2FP_DSC_TYP property of the data source column object as a type number.

d2fdscg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the data source column object as a type object.

d2fdscg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the data source column object as a type object.

d2fdscs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the data source column object.

d2fdscs_dsc_len( ctx, obj, val );

This macro sets the value of the D2FP_DSC_LEN property of the data source column object.

d2fdscs_dsc_mandatory( ctx, obj, val );

This macro sets the value of the D2FP_DSC_MANDATORY property of the data source column object.

d2fdscs_dsc_nam( ctx, obj, val );

This macro sets the value of the D2FP_DSC_NAM property of the data source column object.

d2fdscs_dsc_precision( ctx, obj, val );

This macro sets the value of the D2FP_DSC_PRECISION property of the data source column object.

d2fdscs_dsc_scale( ctx, obj, val );

This macro sets the value of the D2FP_DSC_SCALE property of the data source column object.

d2fdscs_dsc_typ( ctx, obj, val );

This macro sets the value of the D2FP_DSC_TYP property of the data source column object.


Editor object macros

  Related Topics

This section describes the macros of the Form Builder Open API Editor object.

d2fedtg_back_color( ctx, obj, val );

This macro returns the value of the Background Color property of the editor object as type text.

d2fedtg_btm_ttl( ctx, obj, val );

This macro returns the value of the Bottom Title property of the editor object as type text.

d2fedtg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the editor object as a type dvoid pointer.

d2fedtg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the editor object as type text.

d2fedtg_fill_pat( ctx, obj, val );

This macro returns the value of the Fill Pattern property of the editor object as type text.

d2fedtg_font_nam( ctx, obj, val );

This macro returns the value of the Font Name property of the editor object as type text.

d2fedtg_font_siz( ctx, obj, val );

This macro returns the value of the Font Size property of the editor object as type number.

d2fedtg_font_spcing( ctx, obj, val );

This macro returns the value of the Font Spacing property of the editor object as type number.

d2fedtg_font_sty( ctx, obj, val );

This macro returns the value of the Font Style property of the editor object as type number.

d2fedtg_font_wght( ctx, obj, val );

This macro returns the value of the Font Weight property of the editor object as type number.

d2fedtg_fore_color( ctx, obj, val );

This macro returns the value of the Foreground Color property of the editor object as type text.

d2fedtg_height( ctx, obj, val );

This macro returns the value of the Height property of the editor object as type number.

d2fedtg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the editor object as type object.

d2fedtg_name( ctx, obj, val );

This macro returns the value of the Name property of the editor object as type text.

d2fedtg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the editor object as type object.

d2fedtg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the editor object as type object.

d2fedtg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the editor object as type text.

d2fedtg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the editor object as type text.

d2fedtg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the editor object as type number.

d2fedtg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the editor object as type number.

d2fedtg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the editor object as type text.

d2fedtg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the editor object as type text.

d2fedtg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the editor object as type object.

d2fedtg_show_horz_scrlbr( ctx, obj, val );

This macro returns the value of the Show Horizontal Scroll Bar property of the editor object as type boolean.

d2fedtg_show_vert_scrlbr( ctx, obj, val );

This macro returns the value of the Show Vertical Scroll Bar property of the editor object as type boolean.

d2fedtg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the editor object as type object.

d2fedtg_title( ctx, obj, val );

This macro returns the value of the Title property of the editor object as type text.

d2fedtg_vat_nam( ctx, obj, val );

This macro returns the value of the Visual Attribute Group property of the editor object as type text.

d2fedtg_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_VAT_OBJ property of the editor object as type object.

d2fedtg_white_on_black( ctx, obj, val );

This macro returns the value of the White on Black property of the editor object as type boolean.

d2fedtg_width( ctx, obj, val );

This macro returns the value of the Width property of the editor object as type number.

d2fedtg_wrap_sty( ctx, obj, val );

This macro returns the value of the Wrap Style property of the editor object as type number.

d2fedtg_x_pos( ctx, obj, val );

This macro returns the value of the X Position/Y Position property of the editor object as type number.

d2fedtg_y_pos( ctx, obj, val );

This macro returns the value of the X Position/Y Position property of the editor object as type number.

d2fedts_back_color( ctx, obj, val );

This macro sets the value of the Background Color property of the editor object.

d2fedts_btm_ttl( ctx, obj, val );

This macro sets the value of the Bottom Title property of the editor object.

d2fedts_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the editor object.

d2fedts_comment( ctx, obj, val );

This macro sets the value of the Comments property of the editor object.

d2fedts_fill_pat( ctx, obj, val );

This macro sets the value of the Fill Pattern property of the editor object.

d2fedts_font_nam( ctx, obj, val );

This macro sets the value of the Font Name property of the editor object.

d2fedts_font_siz( ctx, obj, val );

This macro sets the value of the Font Size property of the editor object.

d2fedts_font_spcing( ctx, obj, val );

This macro sets the value of the Font Spacing property of the editor object.

d2fedts_font_sty( ctx, obj, val );

This macro sets the value of the Font Style property of the editor object.

d2fedts_font_wght( ctx, obj, val );

This macro sets the value of the Font Weight property of the editor object.

d2fedts_fore_color( ctx, obj, val );

This macro sets the value of the Foreground Color property of the editor object.

d2fedts_height( ctx, obj, val );

This macro sets the value of the Height property of the editor object.

d2fedts_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the editor object.

d2fedts_name( ctx, obj, val );

This macro sets the value of the Name property of the editor object.

d2fedts_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the editor object.

d2fedts_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the editor object.

d2fedts_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the editor object.

d2fedts_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the editor object.

d2fedts_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the editor object.

d2fedts_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the editor object.

d2fedts_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the editor object.

d2fedts_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the editor object.

d2fedts_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the editor object.

d2fedts_show_horz_scrlbr( ctx, obj, val );

This macro sets the value of the Show Horizontal Scroll Bar property of the editor object.

d2fedts_show_vert_scrlbr( ctx, obj, val );

This macro sets the value of the Show Vertical Scroll Bar property of the editor object.

d2fedts_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the editor object.

d2fedts_title( ctx, obj, val );

This macro sets the value of the Title property of the editor object.

d2fedts_vat_nam( ctx, obj, val );

This macro sets the value of the Visual Attribute Group property of the editor object.

d2fedts_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_VAT_OBJ property of the editor object.

d2fedts_white_on_black( ctx, obj, val );

This macro sets the value of the White on Black property of the editor object.

d2fedts_width( ctx, obj, val );

This macro sets the value of the Width property of the editor object.

d2fedts_wrap_sty( ctx, obj, val );

This macro sets the value of the Wrap Style property of the editor object.

d2fedts_x_pos( ctx, obj, val );

This macro sets the value of the X Position/Y Position property of the editor object.

d2fedts_y_pos( ctx, obj, val );

This macro sets the value of the X Position/Y Position property of the editor object.


Form module object macros

  Related Topics

This section describes the macros of the Form Builder Open API Form Module object.

d2ffmdg_alert( ctx, obj, val );

This macro returns the value of the D2FP_ALERT property of the form module object as type object.

d2ffmdg_att_lib( ctx, obj, val );

This macro returns the value of the D2FP_ATT_LIB property of the form module object as type object.

d2ffmdg_block( ctx, obj, val );

This macro returns the value of the D2FP_BLOCK property of the form module object as type object.

d2ffmdg_canvas( ctx, obj, val );

This macro returns the value of the D2FP_CANVAS property of the form module object as type object.

d2ffmdg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the form module object as a type dvoid  pointer.

d2ffmdg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the form module object as type text.

d2ffmdg_console_win( ctx, obj, val );

This macro returns the value of the Console Window property of the form module object as type text.

d2ffmdg_crsr_mode( ctx, obj, val );

This macro returns the value of the Cursor Mode property of the form module object as type number.

d2ffmdg_defer_req_enf( ctx, obj, val );

This macro returns the value of the D2FP_DEFER_REQ_ENF property of the form module object as type boolean.

d2ffmdg_editor( ctx, obj, val );

This macro returns the value of the Editor property of the form module object as type object.

d2ffmdg_form_param( ctx, obj, val );

This macro returns the value of the D2FP_FORM_PARAM property of the form module object as type object.

d2ffmdg_frst_navigation_blk_nam( ctx, obj, val );

This macro returns the value of the First navigation Block property of the form module object as type text.

d2ffmdg_frst_navigation_blk_obj( ctx, obj, val );

This macro returns the value of the D2FP_FRST_NAVIGATION_BLK_OBJ property of the form module object as type object.

d2ffmdg_horz_tlbr_cnv( ctx, obj, val );

This macro returns the value of the Horizontal Toolbar Canvas property of the form module object as type text.

d2ffmdg_inhrt_sty( ctx, obj, val );

This macro returns the value of the D2FP_INHRT_STY property of the form module object as type number.

d2ffmdg_init_mnu( ctx, obj, val );

This macro returns the value of the Initial Menu property of the form module object as type text.

d2ffmdg_interaction_mode( ctx, obj, val );

This macro returns the value of the Interaction Mode property of the form module object as type number.

d2ffmdg_isolation_mode( ctx, obj, val );

This macro returns the value of the Isolation Mode property of the form module object as type number.

d2ffmdg_lang_dir( ctx, obj, val );

This macro returns the value of the Language Direction property of the form module object as type number.

d2ffmdg_lov( ctx, obj, val );

This macro returns the value of the List of Values property of the form module object as type object.

d2ffmdg_max_qry_time( ctx, obj, val );

This macro returns the value of the Maximum Query Time property of the form module object as type number.

d2ffmdg_max_recs_fetched( ctx, obj, val );

This macro returns the value of the Maximum Records Fetched property of the form module object as type number.

d2ffmdg_menu( ctx, obj, val );

This macro returns the value of the D2FP_MENU property of the form module object as type object.

d2ffmdg_mnu_mod( ctx, obj, val );

This macro returns the value of the Menu Module property of the form module object.

d2ffmdg_mnu_role( ctx, obj, val );

This macro returns the value of the Menu Module Roles property of the form module object as type text.

d2ffmdg_mnu_src( ctx, obj, val );

This macro returns the value of the Menu Source property of the form module object as type text.

d2ffmdg_mnu_sty( ctx, obj, val );

This macro returns the value of the Menu Style property of the form module object as type number.

d2ffmdg_mouse_navigation_lmt( ctx, obj, val );

This macro returns the value of the Mouse Navigation Limit property of the form module object as type number.

d2ffmdg_name( ctx, obj, val );

This macro returns the value of the Name property of the form module object as type text.

d2ffmdg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the form module object as type object.

d2ffmdg_obj_grp( ctx, obj, val );

This macro returns the value of the D2FP_OBJ_GRP property of the form module object as type object.

d2ffmdg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the form module object as type object.

d2ffmdg_prog_unit( ctx, obj, val );

This macro returns the value of the D2FP_PROG_UNIT property of the form module object as type object.

d2ffmdg_prop_class( ctx, obj, val );

This macro returns the value of the Property Class property of the form module object as type object.

d2ffmdg_rec_grp( ctx, obj, val );

This macro returns the value of the Record Group property of the form module object as type object.

d2ffmdg_rec_vat_grp_nam( ctx, obj, val );

This macro returns the value of the Current Record Visual Attribute Group property of the form module object as type text.

d2ffmdg_rec_vat_grp_obj( ctx, obj, val );

This macro returns the value of the D2FP_REC_VAT_GRP_OBJ property of the form module object as type object.

d2ffmdg_report( ctx, obj, val );

This macro returns the value of the D2FP_REPORT property of the form module object as type object.

d2ffmdg_runtime_comp( ctx, obj, val );

This macro returns the value of the D2FP_RUNTIME_COMP property of the form module object as type number.

d2ffmdg_svpnt_mode( ctx, obj, val );

This macro returns the value of the Savepoint Mode property of the form module object as type boolean.

d2ffmdg_title( ctx, obj, val );

This macro returns the value of the Title property of the form module object as type text.

d2ffmdg_trigger( ctx, obj, val );

This macro returns the value of the D2FP_TRIGGER property of the form module object as type object.

d2ffmdg_use_3D_cntrls( ctx, obj, val );

This macro returns the value of the Use 3D Controls property of the form module object as type boolean.

d2ffmdg_validation_unit( ctx, obj, val );

This macro returns the value of the Validation Unit property of the form module object as type number.

d2ffmdg_vert_tlbr_cnv( ctx, obj, val );

This macro returns the value of the Vertical Toolbar Canvas property of the form module object as type text.

d2ffmdg_vis_attr( ctx, obj, val );

This macro returns the value of the D2FP_VIS_ATTR property of the form module object as type object.

d2ffmdg_window( ctx, obj, val );

This macro returns the value of the Window property of the form module object as type object.

d2ffmds_alert( ctx, obj, val );

This macro sets the value of the D2FP_ALERT property of the form module object.

d2ffmds_att_lib( ctx, obj, val );

This macro sets the value of the D2FP_ATT_LIB property of the form module object.

d2ffmds_block( ctx, obj, val );

This macro sets the value of the D2FP_BLOCK property of the form module object.

d2ffmds_canvas( ctx, obj, val );

This macro sets the value of the D2FP_CANVAS property of the form module object.

d2ffmds_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the form module object.

d2ffmds_comment( ctx, obj, val );

This macro sets the value of the Comments property of the form module object.

d2ffmds_console_win( ctx, obj, val );

This macro sets the value of the Console Window property of the form module object.

d2ffmds_crsr_mode( ctx, obj, val );

This macro sets the value of the Cursor Mode property of the form module object.

d2ffmds_defer_req_enf( ctx, obj, val );

This macro sets the value of the D2FP_DEFER_REQ_ENF property of the form module object.

d2ffmds_editor( ctx, obj, val );

This macro sets the value of the Editor property of the form module object.

d2ffmds_form_param( ctx, obj, val );

This macro sets the value of the D2FP_FORM_PARAM property of the form module object.

d2ffmds_frst_navigation_blk_nam( ctx, obj, val );

This macro sets the value of the First navigation Block property of the form module object.

d2ffmds_frst_navigation_blk_obj( ctx, obj, val );

This macro sets the value of the D2FP_FRST_NAVIGATION_BLK_OBJ property of the form module object.

d2ffmds_horz_tlbr_cnv( ctx, obj, val );

This macro sets the value of the Horizontal Toolbar Canvas property of the form module object.

d2ffmds_inhrt_sty( ctx, obj, val );

This macro sets the value of the D2FP_INHRT_STY property of the form module object.

d2ffmds_init_mnu( ctx, obj, val );

This macro sets the value of the Initial Menu property of the form module object.

d2ffmds_interaction_mode( ctx, obj, val );

This macro sets the value of the Interaction Mode property of the form module object.

d2ffmds_isolation_mode( ctx, obj, val );

This macro sets the value of the Isolation Mode property of the form module object.

d2ffmds_lang_dir( ctx, obj, val );

This macro sets the value of the Language Direction property of the form module object.

d2ffmds_lov( ctx, obj, val );

This macro sets the value of the List of Values property of the form module object.

d2ffmds_max_qry_time( ctx, obj, val );

This macro sets the value of the Maximum Query Time property of the form module object.

d2ffmds_max_recs_fetched( ctx, obj, val );

This macro sets the value of the Maximum Records Fetched property of the form module object.

d2ffmds_menu( ctx, obj, val );

This macro sets the value of the D2FP_MENU property of the form module object.

d2ffmds_mnu_mod( ctx, obj, val );

This macro sets the value of the Menu Module property of the form module object.

d2ffmds_mnu_role( ctx, obj, val );

This macro sets the value of the Menu Module Roles property of the form module object.

d2ffmds_mnu_src( ctx, obj, val );

This macro sets the value of the Menu Source property of the form module object.

d2ffmds_mnu_sty( ctx, obj, val );

This macro sets the value of the Menu Style property of the form module object.

d2ffmds_mouse_navigation_lmt( ctx, obj, val );

This macro sets the value of the Mouse Navigation Limit property of the form module object.

d2ffmds_name( ctx, obj, val );

This macro sets the value of the Name property of the form module object.

d2ffmds_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the form module object.

d2ffmds_obj_grp( ctx, obj, val );

This macro sets the value of the D2FP_OBJ_GRP property of the form module object.

d2ffmds_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the form module object.

d2ffmds_prog_unit( ctx, obj, val );

This macro sets the value of the D2FP_PROG_UNIT property of the form module object.

d2ffmds_prop_class( ctx, obj, val );

This macro sets the value of the Property Class property of the form module object.

d2ffmds_rec_grp( ctx, obj, val );

This macro sets the value of the Record Group property of the form module object.

d2ffmds_rec_vat_grp_nam( ctx, obj, val );

This macro sets the value of the Current Record Visual Attribute Group property of the form module object.

d2ffmds_rec_vat_grp_obj( ctx, obj, val );

This macro sets the value of the D2FP_REC_VAT_GRP_OBJ property of the form module object.

d2ffmds_report( ctx, obj, val );

This macro sets the value of the D2FP_REPORT property of the form module object.

d2ffmds_runtime_comp( ctx, obj, val );

This macro sets the value of the D2FP_RUNTIME_COMP property of the form module object.

d2ffmds_svpnt_mode( ctx, obj, val );

This macro sets the value of the Savepoint Mode property of the form module object.

d2ffmds_title( ctx, obj, val );

This macro sets the value of the Title property of the form module object.

d2ffmds_trigger( ctx, obj, val );

This macro sets the value of the D2FP_TRIGGER property of the form module object.

d2ffmds_use_3D_cntrls( ctx, obj, val );

This macro sets the value of the Use 3D Controls property of the form module object.

d2ffmds_validation_unit( ctx, obj, val );

This macro sets the value of the Validation Unit property of the form module object.

d2ffmds_vert_tlbr_cnv( ctx, obj, val );

This macro sets the value of the Vertical Toolbar Canvas property of the form module object.


Form parameter object macros

  Related Topics

This section describes the macros of the Form Builder Open API Form Parameter object.

d2ffpmg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the form parameter object as a type dvoid pointer.

d2ffpmg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the form parameter object as type text.

d2ffpmg_max_len( ctx, obj, val );

This macro returns the value of the Maximum Length property of the form parameter object as type number.

d2ffpmg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the form parameter object as type object.

d2ffpmg_name( ctx, obj, val );

This macro returns the value of the Name property of the form parameter object as type text.

d2ffpmg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the form parameter object as type object.

d2ffpmg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the form parameter object as type object.

d2ffpmg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the form parameter object as type text.

d2ffpmg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the form parameter object as type text.

d2ffpmg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the form parameter object as type number.

d2ffpmg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the form parameter object as type number.

d2ffpmg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the form parameter object as type text.

d2ffpmg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the form parameter object as type text.

d2ffpmg_param_dat_typ( ctx, obj, val );

This macro returns the value of the Parameter Data Type property of the form parameter object as type number.

d2ffpmg_param_init_val( ctx, obj, val );

This macro returns the value of the Parameter Initial Value property of the form parameter object as type text.

d2ffpmg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the form parameter object as type object.

d2ffpmg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the form parameter object as type object.

d2ffpms_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the form parameter object.

d2ffpms_comment( ctx, obj, val );

This macro sets the value of the Comments property of the form parameter object.

d2ffpms_max_len( ctx, obj, val );

This macro sets the value of the Maximum Length property of the form parameter object.

d2ffpms_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the form parameter object.

d2ffpms_name( ctx, obj, val );

This macro sets the value of the Name property of the form parameter object.

d2ffpms_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the form parameter object.

d2ffpms_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the form parameter object.

d2ffpms_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the form parameter object.

d2ffpms_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the form parameter object.

d2ffpms_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the form parameter object.

d2ffpms_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the form parameter object.

d2ffpms_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the form parameter object.

d2ffpms_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the form parameter object.

d2ffpms_param_dat_typ( ctx, obj, val );

This macro sets the value of the Parameter Data Type property of the form parameter object.

d2ffpms_param_init_val( ctx, obj, val );

This macro sets the value of the Parameter Initial Value property of the form parameter object.


Graphics object macros

  Related Topics

This section describes the macros of the Form Builder Open API Graphics object.

d2fgrag_allow_expansion( ctx, obj, val );

This macro returns the value of the Allow Expansion property of the graphics object as type boolean.

d2fgrag_allow_mlt_lin_prmpts( ctx, obj, val );

This macro returns the value of the Allow Multi-Line Prompts property of the graphics object as type boolean.

d2fgrag_allow_strt_att_prmpts( ctx, obj, val );

This macro returns the value of the Allow Start-Attached Prompts property of the graphics object as type boolean.

d2fgrag_allow_top_att_prmpts( ctx, obj, val );

This macro returns the value of the Allow Top-Attached Prompts property of the graphics object as type boolean.

d2fgrag_arrow_sty( ctx, obj, val );

This macro returns the value of the Line Arrow Style property of the graphics object as type number.

d2fgrag_back_color( ctx, obj, val );

This macro returns the value of the Background Color property of the graphics object as type text.

d2fgrag_bevel( ctx, obj, val );

This macro returns the value of the Bevel property of the graphics object as type number.

d2fgrag_bounding_bx_scalable( ctx, obj, val );

This macro returns the value of the Bounding Box Scaleable property of the graphics object as type boolean.

d2fgrag_cap_sty( ctx, obj, val );

This macro returns the value of the Cap Style property of the graphics object as type number.

d2fgrag_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the graphics object as a type dvoid pointer..

d2fgrag_clip_hgt( ctx, obj, val );

This macro returns the value of the Height of Clipping Rectangle property of the graphics object as type number.

d2fgrag_clip_wid( ctx, obj, val );

This macro returns the value of the Width of Clipping Rectangle property of the graphics object as type number.

d2fgrag_clip_x_pos( ctx, obj, val );

This macro returns the value of the X-origin of Clipping Rectangle property of the graphics object as type number.

d2fgrag_clip_y_pos( ctx, obj, val );

This macro returns the value of the Y-origin of Clipping Rectangle property of the graphics object as type number.

d2fgrag_closed( ctx, obj, val );

This macro returns the value of the Polygon Flag/Arc Closure property of the graphics object as type boolean.

d2fgrag_corner_radius_x( ctx, obj, val );

This macro returns the value of the X-origin of Radius for Corner of Rounded Rectangle property of the graphics object as type number.

d2fgrag_corner_radius( ctx, obj, val );

This macro returns the value of the Y-origin of the Radius for Corner of Rounder Rectangle property of the graphics object as type number.

d2fgrag_cstm_spcing( ctx, obj, val );

This macro returns the value of the Custom Spacing for Text Object property of the graphics object as type number.

d2fgrag_dash_sty( ctx, obj, val );

This macro returns the value of the Dash Style for Objects Edge property of the graphics object as type number.

d2fgrag_disp_qlty( ctx, obj, val );

This macro returns the value of the Display Quality property of the graphics object as type number.

d2fgrag_dist_btwn_recs( ctx, obj, val );

This macro returns the value of the Distance Between Records property of the graphics object as type number.

d2fgrag_dither( ctx, obj, val );

This macro returns the value of the Graphics Dithers Image property of the graphics object as type boolean.

d2fgrag_edge_back_color( ctx, obj, val );

This macro returns the value of the Object Edge Background Color property of the graphics object as type text.

d2fgrag_edge_fore_color( ctx, obj, val );

This macro returns the value of the Object Edge Foreground Color property of the graphics object as type text.

d2fgrag_edge_pat( ctx, obj, val );

This macro returns the value of the D2FP_EDGE_PAT property of the graphics object as type text.

d2fgrag_fill_pat( ctx, obj, val );

This macro returns the value of the Fill Pattern property of the graphics object as type text.

d2fgrag_fixed_bounding_bx( ctx, obj, val );

This macro returns the value of the D2FP_FIXED_BOUNDING_BX property of the graphics object as type boolean.

d2fgrag_font_scaleable( ctx, obj, val );

This macro returns the value of the Point Size Scales with Object property of the graphics object as type boolean.

d2fgrag_fore_color( ctx, obj, val );

This macro returns the value of the Foreground Color property of the graphics object as type text.

d2fgrag_frame_align( ctx, obj, val );

This macro returns the value of the Frame Alignment property of the graphics object as type number.

d2fgrag_frame_ttl( ctx, obj, val );

This macro returns the value of the Frame Title property of the graphics object as type text.

d2fgrag_frame_ttl_align( ctx, obj, val );

This macro returns the value of the Frame Title Alignment property of the graphics object as type number.

d2fgrag_frame_ttl_back_color( ctx, obj, val );

This macro returns the value of the Frame Title Background Color property of the graphics object as type text.

d2fgrag_frame_ttl_fill_pat( ctx, obj, val );

This macro returns the value of the Frame Title Fill Pattern property of the graphics object as type text.

d2fgrag_frame_ttl_font_nam( ctx, obj, val );

This macro returns the value of the Frame Title Font Name property of the graphics object as type text.

d2fgrag_frame_ttl_font_siz( ctx, obj, val );

This macro returns the value of the Frame Title Font Size property of the graphics object as type number.

d2fgrag_frame_ttl_font_spcing( ctx, obj, val );

This macro returns the value of the Frame Title Font Spacing property of the graphics object as type number.

d2fgrag_frame_ttl_font_sty( ctx, obj, val );

This macro returns the value of the Frame Title Font Style property of the graphics object as type number.

d2fgrag_frame_ttl_font_weight( ctx, obj, val );

This macro returns the value of the Frame Title Font Weight property of the graphics object as type number.

d2fgrag_fram_ttl_fore_color( ctx, obj, val );

This macro returns the value of the Frame Title Foreground Color property of the graphics object as type text.

d2fgrag_frame_ttl_ofst( ctx, obj, val );

This macro returns the value of the Frame Title Offset property of the graphics object as type number.

d2fgrag_frame_ttl_spcing( ctx, obj, val );

This macro returns the value of the Frame Title Spacing property of the graphics object as type number.

d2fgrag_frame_ttl_vat_nam( ctx, obj, val );

This macro returns the value of the Frame Title Visual Attribute property of the graphics object as type text.

d2fgrag_frame_ttl_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_FRAME_TTL_VAT_OBJ property of the graphics object as type object.

d2fgrag_gra_font_nam( ctx, obj, val );

This macro returns the value of the Graphics Font Name property of the graphics object as type text.

d2fgrag_gra_font_siz( ctx, obj, val );

This macro returns the value of the Graphics Font Size property of the graphics object as type number.

d2fgrag_gra_font_sty( ctx, obj, val );

This macro returns the value of the Graphics Font Style property of the graphics object as type number.

d2fgrag_gra_text( ctx, obj, val );

This macro returns the value of the Graphics Text property of the graphics object as type text.

d2fgrag_graphic( ctx, obj, val );

This macro returns the value of the D2FP_GRAPHIC property of the graphics object as type object.

d2fgrag_graphics_typ( ctx, obj, val );

This macro returns the value of the Graphics Object Type property of the graphics object as type number.

d2fgrag_height( ctx, obj, val );

This macro returns the value of the Width/Height property of the graphics object as type number.

d2fgrag_horz_jst( ctx, obj, val );

This macro returns the value of the Horizontal Justification of Text Object property of the graphics object as type number.

d2fgrag_horz_margn( ctx, obj, val );

This macro returns the value of the Horizontal Margin property of the graphics object as type number.

d2fgrag_horz_obj_ofst( ctx, obj, val );

This macro returns the value of the Horizontal Object Offset property of the graphics object as type number.

d2fgrag_horz_orgn( ctx, obj, val );

This macro returns the value of the Horizontal Position Relative to Origin property of the graphics object as type number.

d2fgrag_internal_end_angle( ctx, obj, val );

This macro returns the value of the D2FP_INTERNAL_END_ANGLE property of the graphics object as type number.

d2fgrag_internal_lin_wid( ctx, obj, val );

This macro returns the value of the D2FP_INTERNAL_END_WID property of the graphics object as type number.

d2fgrag_internal_rotation_angle( ctx, obj, val );

This macro returns the value of the D2FP_INTERNAL_ROTATION_ANGLE property of the graphics object as type number.

d2fgrag_internal_strt_angle( ctx, obj, val );

This macro returns the value of the D2FP_INTERNAL_STRT_ANGLE property of the graphics object as type number.

d2fgrag_join_sty( ctx, obj, val );

This macro returns the value of the Join Style of Objects Edge property of the graphics object as type number.

d2fgrag_lang_dir( ctx, obj, val );

This macro returns the value of the Language Direction property of the graphics object as type number.

d2fgrag_laayout_data_blk_nam( ctx, obj, val );

This macro returns the value of the Layout Data Block property of the graphics object as type text.

d2fgrag_layout_sty( ctx, obj, val );

This macro returns the value of the Layout Style property of the graphics object as type number.

d2fgrag_lin_spcing( ctx, obj, val );

This macro returns the value of the Line Spacing property of the graphics object as type number.

d2fgrag_max_objs( ctx, obj, val );

This macro returns the value of the Maximum Objects Per Line property of the graphics object as type number.

d2fgrag_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the graphics object as type object.

d2fgrag_name( ctx, obj, val );

This macro returns the value of the Name property of the graphics object as type text.

d2fgrag_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the graphics object as type object.

d2fgrag_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the graphics object as type object.

d2fgrag_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the graphics object as type text.

d2fgrag_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the graphics object as type text.

d2fgrag_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the graphics object as type number.

d2fgrag_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the graphics object as type number.

d2fgrag_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the graphics object as type text.

d2fgrag_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the graphics object as type text.

d2fgrag_point( ctx, obj, val );

This macro returns the value of the Font Point Size property of the graphics object as type object.

d2fgrag_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the graphics object as type object.

d2fgrag_recs_disp_count( ctx, obj, val );

This macro returns the value of the Number of Records Displayed property of the graphics object as type number.

d2fgrag_scrlbr_align( ctx, obj, val );

This macro returns the value of the Scroll Bar Alignment property of the graphics object as type number.

d2fgrag_scrlbr_wid( ctx, obj, val );

This macro returns the value of the Scroll Bar Width property of the graphics object as type number.

d2fgrag_show_scrlbr( ctx, obj, val );

This macro returns the value of the D2FP_SHOW_SCRLBR property of the graphics object as type boolean.

d2fgrag_shrinkwrap( ctx, obj, val );

This macro returns the value of the Shrinkwrap property of the graphics object as type boolean.

d2fgrag_sngl_obj_align( ctx, obj, val );

This macro returns the value of the Single object Align property of the graphics object as type number.

d2fgrag_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the graphics object as type object.

d2fgrag_strt_prmpt_align( ctx, obj, val );

This macro returns the value of the Start Prompt Alignment property of the graphics object as type number.

d2fgrag_strt_prmpt_ofst( ctx, obj, val );

This macro returns the value of the Start Prompt Offset property of the graphics object as type number.

d2fgrag_tbp_nam( ctx, obj, val );

This macro returns the value of the D2FP_TBP_NAM property of the graphics object as type text.

d2fgrag_tbp_obj( ctx, obj, val );

This macro returns the value of the D2FP_TBP_OBJ property of the graphics object as type object.

d2fgrag_top_prmpt_align( ctx, obj, val );

This macro returns the value of the Top Prompt Alignment property of the graphics object as type number.

d2fgrag_top_prmpt_pfst( ctx, obj, val );

This macro returns the value of the Top Prompt Offset property of the graphics object as type number.

d2fgrag_ttl_reading_ordr( ctx, obj, val );

This macro returns the value of the Title Reading property of the graphics object as type number.

d2fgrag_updt_layout( ctx, obj, val );

This macro returns the value of the Update Layout property of the graphics object as type number.

d2fgrag_vert_fill( ctx, obj, val );

This macro returns the value of the Vertical Fill property of the graphics object as type boolean.

d2fgrag_vert_jst( ctx, obj, val );

This macro returns the value of the Vertical Justification property of the graphics object as type number.

d2fgrag_vert_margn( ctx, obj, val );

This macro returns the value of the Vertical Margin property of the graphics object as type number.

d2fgrag_vert_obj_ofst( ctx, obj, val );

This macro returns the value of the Vertical Object Offset property of the graphics object as type number.

d2fgrag_vert_orgn( ctx, obj, val );

This macro returns the value of the Vertical Position Relative to Origin property of the graphics object as type number.

d2fgrag_width( ctx, obj, val );

This macro returns the value of the Width/Height property of the graphics object as type number.

d2fgrag_wrap_txt( ctx, obj, val );

This macro returns the value of the Wrap Text property of the graphics object as type boolean.

d2fgrag_x_pos( ctx, obj, val );

This macro returns the value of the X Position/Y Position property of the graphics object as type number.

d2fgrag_y_pos( ctx, obj, val );

This macro returns the value of the X Position/Y Position property of the graphics object as type number.

d2fgras_allow_expansion( ctx, obj, val );

This macro sets the value of the Allow Expansion property of the graphics object.

d2fgras_allow_mlt_lin_prmpts( ctx, obj, val );

This macro sets the value of the Allow Multi-Line Prompts property of the graphics object.

d2fgras_allow_strt_att_prmpts( ctx, obj, val );

This macro sets the value of the Allow Start-Attached Prompts property of the graphics object.

d2fgras_allow_top_att_prmpts( ctx, obj, val );

This macro sets the value of the Allow Top-Attached Prompts property of the graphics object.

d2fgras_arrow_sty( ctx, obj, val );

This macro sets the value of the Line Arrow Style property of the graphics object.

d2fgras_back_color( ctx, obj, val );

This macro sets the value of the Background Color property of the graphics object.

d2fgras_bevel( ctx, obj, val );

This macro sets the value of the Bevel property of the graphics object.

d2fgras_bounding_bx_scalable( ctx, obj, val );

This macro sets the value of the Bounding Box Scaleable property of the graphics object.

d2fgras_cap_sty( ctx, obj, val );

This macro sets the value of the Cap Style property of the graphics object.

d2fgras_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the graphics object.

d2fgras_clip_hgt( ctx, obj, val );

This macro sets the value of the Height of Clipping Rectangle property of the graphics object.

d2fgras_clip_wid( ctx, obj, val );

This macro sets the value of the Width of Clipping Rectangle property of the graphics object.

d2fgras_clip_x_pos( ctx, obj, val );

This macro sets the value of the X-origin of Clipping Rectangle property of the graphics object.

d2fgras_clip_y_pos( ctx, obj, val );

This macro sets the value of the Y-origin of Clipping Rectangle property of the graphics object.

d2fgras_closed( ctx, obj, val );

This macro sets the value of the Polygon Flag/Arc Closure property of the graphics object.

d2fgras_corner_radius_x( ctx, obj, val );

This macro sets the value of the X-origin of Radius for Corner of Rounded Rectangle property of the graphics object.

d2fgras_corner_radius( ctx, obj, val );

This macro sets the value of the Y-origin of the Radius for Corner of Rounder Rectangle property of the graphics object.

d2fgras_cstm_spcing( ctx, obj, val );

This macro sets the value of the Custom Spacing for Text Object property of the graphics object.

d2fgras_dash_sty( ctx, obj, val );

This macro sets the value of the Dash Style for Objects Edge property of the graphics object.

d2fgras_disp_qlty( ctx, obj, val );

This macro sets the value of the Display Quality property of the graphics object.

d2fgras_dist_btwn_recs( ctx, obj, val );

This macro sets the value of the Distance Between Records property of the graphics object.

d2fgras_dither( ctx, obj, val );

This macro sets the value of the Graphics Dithers Image property of the graphics object.

d2fgras_edge_back_color( ctx, obj, val );

This macro sets the value of the Object Edge Background Color property of the graphics object.

d2fgras_edge_fore_color( ctx, obj, val );

This macro sets the value of the Object Edge Foreground Color property of the graphics object.

d2fgras_edge_pat( ctx, obj, val );

This macro sets the value of the D2FP_EDGE_PAT property of the graphics object.

d2fgras_fill_pat( ctx, obj, val );

This macro sets the value of the Fill Pattern property of the graphics object.

d2fgras_fixed_bounding_bx( ctx, obj, val );

This macro sets the value of the D2FP_FIXED_BOUNDING_BX property of the graphics object.

d2fgras_font_scaleable( ctx, obj, val );

This macro sets the value of the Point Size Scales with Object property of the graphics object.

d2fgras_fore_color( ctx, obj, val );

This macro sets the value of the Foreground Color property of the graphics object.

d2fgras_frame_align( ctx, obj, val );

This macro sets the value of the Frame Alignment property of the graphics object.

d2fgras_frame_ttl( ctx, obj, val );

This macro sets the value of the Frame Title property of the graphics object.

d2fgras_frame_ttl_align( ctx, obj, val );

This macro sets the value of the Frame Title Alignment property of the graphics object.

d2fgras_frame_ttl_back_color( ctx, obj, val );

This macro sets the value of the Frame Title Background Color property of the graphics object.

d2fgras_frame_ttl_fill_pat( ctx, obj, val );

This macro sets the value of the Frame Title Fill Pattern property of the graphics object.

d2fgras_frame_ttl_font_nam( ctx, obj, val );

This macro sets the value of the Frame Title Font Name property of the graphics object.

d2fgras_frame_ttl_font_siz( ctx, obj, val );

This macro sets the value of the Frame Title Font Size property of the graphics object.

d2fgras_frame_ttl_font_spcing( ctx, obj, val );

This macro sets the value of the Frame Title Font Spacing property of the graphics object.

d2fgras_frame_ttl_font_sty( ctx, obj, val );

This macro sets the value of the Frame Title Font Style property of the graphics object.

d2fgras_frame_ttl_font_weight( ctx, obj, val );

This macro sets the value of the Frame Title Font Weight property of the graphics object.

d2fgras_fram_ttl_fore_color( ctx, obj, val );

This macro sets the value of the Frame Title Foreground Color property of the graphics object.

d2fgras_frame_ttl_ofst( ctx, obj, val );

This macro sets the value of the Frame Title Offset property of the graphics object.

d2fgras_frame_ttl_spcing( ctx, obj, val );

This macro sets the value of the Frame Title Spacing property of the graphics object.

d2fgras_frame_ttl_vat_nam( ctx, obj, val );

This macro sets the value of the Frame Title Visual Attribute property of the graphics object.

d2fgras_frame_ttl_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_FRAME_TTL_VAT_OBJ property of the graphics object.

d2fgras_gra_font_nam( ctx, obj, val );

This macro sets the value of the Graphics Font Name property of the graphics object.

d2fgras_gra_font_siz( ctx, obj, val );

This macro sets the value of the Graphics Font Size property of the graphics object.

d2fgras_gra_font_sty( ctx, obj, val );

This macro sets the value of the Graphics Font Style property of the graphics object.

d2fgras_gra_text( ctx, obj, val );

This macro sets the value of the Graphics Text property of the graphics object.

d2fgras_graphic( ctx, obj, val );

This macro sets the value of the D2FP_GRAPHIC property of the graphics object.

d2fgras_graphics_typ( ctx, obj, val );

This macro sets the value of the Graphics Object Type property of the graphics object.

d2fgras_height( ctx, obj, val );

This macro sets the value of the Width/Height property of the graphics object.

d2fgras_horz_jst( ctx, obj, val );

This macro sets the value of the Horizontal Justification of Text Object property of the graphics object.

d2fgras_horz_margn( ctx, obj, val );

This macro sets the value of the Horizontal Margin property of the graphics object.

d2fgras_horz_obj_ofst( ctx, obj, val );

This macro sets the value of the Horizontal Object Offset property of the graphics object.

d2fgras_horz_orgn( ctx, obj, val );

This macro sets the value of the Horizontal Position Relative to Origin property of the graphics object.

d2fgras_internal_end_angle( ctx, obj, val );

This macro sets the value of the D2FP_INTERNAL_END_ANGLE property of the graphics object.

d2fgras_internal_lin_wid( ctx, obj, val );

This macro sets the value of the D2FP_INTERNAL_END_WID property of the graphics object.

d2fgras_internal_rotation_angle( ctx, obj, val );

This macro sets the value of the D2FP_INTERNAL_ROTATION_ANGLE property of the graphics object.

d2fgras_internal_strt_angle( ctx, obj, val );

This macro sets the value of the D2FP_INTERNAL_STRT_ANGLE property of the graphics object.

d2fgras_join_sty( ctx, obj, val );

This macro sets the value of the Join Style of Objects Edge property of the graphics object.

d2fgras_lang_dir( ctx, obj, val );

This macro sets the value of the Language Direction property of the graphics object.

d2fgras_laayout_data_blk_nam( ctx, obj, val );

This macro sets the value of the Layout Data Block property of the graphics object.

d2fgras_layout_sty( ctx, obj, val );

This macro sets the value of the Layout Style property of the graphics object.

d2fgras_lin_spcing( ctx, obj, val );

This macro sets the value of the Line Spacing property of the graphics object.

d2fgras_max_objs( ctx, obj, val );

This macro sets the value of the Maximum Objects Per Line property of the graphics object.

d2fgras_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the graphics object.

d2fgras_name( ctx, obj, val );

This macro sets the value of the Name property of the graphics object.

d2fgras_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the graphics object.

d2fgras_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the graphics object.

d2fgras_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the graphics object.

d2fgras_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the graphics object.

d2fgras_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the graphics object.

d2fgras_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the graphics object.

d2fgras_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the graphics object.

d2fgras_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the graphics object.

d2fgras_point( ctx, obj, val );

This macro sets the value of the Font Point Size property of the graphics object.

d2fgras_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the graphics object.

d2fgras_recs_disp_count( ctx, obj, val );

This macro sets the value of the Number of Records Displayed property of the graphics object.

d2fgras_scrlbr_align( ctx, obj, val );

This macro sets the value of the Scroll Bar Alignment property of the graphics object.

d2fgras_scrlbr_wid( ctx, obj, val );

This macro sets the value of the Scroll Bar Width property of the graphics object.

d2fgras_show_scrlbr( ctx, obj, val );

This macro sets the value of the D2FP_SHOW_SCRLBR property of the graphics object.

d2fgras_shrinkwrap( ctx, obj, val );

This macro sets the value of the Shrinkwrap property of the graphics object.

d2fgras_sngl_obj_align( ctx, obj, val );

This macro sets the value of the Single object Align property of the graphics object.

d2fgras_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the graphics object.

d2fgras_strt_prmpt_align( ctx, obj, val );

This macro sets the value of the Start Prompt Alignment property of the graphics object.

d2fgras_strt_prmpt_ofst( ctx, obj, val );

This macro sets the value of the Start Prompt Offset property of the graphics object.

d2fgras_tbp_nam( ctx, obj, val );

This macro sets the value of the D2FP_TBP_NAM property of the graphics object.

d2fgras_tbp_obj( ctx, obj, val );

This macro sets the value of the D2FP_TBP_OBJ property of the graphics object.

d2fgras_top_prmpt_align( ctx, obj, val );

This macro sets the value of the Top Prompt Alignment property of the graphics object.

d2fgras_top_prmpt_pfst( ctx, obj, val );

This macro sets the value of the Top Prompt Offset property of the graphics object.

d2fgras_ttl_reading_ordr( ctx, obj, val );

This macro sets the value of the Title Reading property of the graphics object.

d2fgras_updt_layout( ctx, obj, val );

This macro sets the value of the Update Layout property of the graphics object.

d2fgras_vert_fill( ctx, obj, val );

This macro sets the value of the Vertical Fill property of the graphics object.

d2fgras_vert_jst( ctx, obj, val );

This macro sets the value of the Vertical Justification property of the graphics object.

d2fgras_vert_margn( ctx, obj, val );

This macro sets the value of the Vertical Margin property of the graphics object.

d2fgras_vert_obj_ofst( ctx, obj, val );

This macro sets the value of the Vertical Object Offset property of the graphics object.

d2fgras_vert_orgn( ctx, obj, val );

This macro sets the value of the Vertical Position Relative to Origin property of the graphics object.

d2fgras_width( ctx, obj, val );

This macro sets the value of the Width/Height property of the graphics object.

d2fgras_wrap_txt( ctx, obj, val );

This macro sets the value of the Wrap Text property of the graphics object.

d2fgras_x_pos( ctx, obj, val );

This macro sets the value of the X Position/Y Position property of the graphics object.

d2fgras_y_pos( ctx, obj, val );

This macro sets the value of the X Position/Y Position property of the graphics object.


Item object macros

  Related Topics

This section describes the macros of the Form Builder Open API Item object.

d2fitmg_access_key( ctx, obj, val );

This macro returns the value of the Access Key property of the item object as type text.

d2fitmg_activex_class( ctx, obj, val );

This macro returns the value of the D2FP_ACTIVEX_CLASS property of the item object as type text.

d2fitmg_activex_val_prop( ctx, obj, val );

This macro returns the value of the D2FP_ACTIVEX_VAL_PROP property of the item object as type text.

d2fitmg_audio_chnnls( ctx, obj, val );

This macro returns the value of the Audio Channels property of the item object as type number.

d2fitmg_auto_hint( ctx, obj, val );

This macro returns the value of the Display Hint Automatically property of the item object as type boolean.

d2fitmg_auto_skip( ctx, obj, val );

This macro returns the value of the Auto Skip property of the item object as type boolean.

d2fitmg_back_color( ctx, obj, val );

This macro returns the value of the Background Color property of the item object as type text.

d2fitmg_bevel( ctx, obj, val );

This macro returns the value of the Bevel property of the item object as type number.

d2fitmg_calc_mode( ctx, obj, val );

This macro returns the value of the Calculation Mode property of the item object as type number.

d2fitmg_case_insensitive_qry( ctx, obj, val );

This macro returns the value of the Case Insensitive Query property of the item object as type boolean.

d2fitmg_case_rstrction( ctx, obj, val );

This macro returns the value of the Case Restriction property of the item object as type number.

d2fitmg_chk_bx_other_vals( ctx, obj, val );

This macro returns the value of the Check Box Mapping of Other Values property of the item object.

d2fitmg_chked_val( ctx, obj, val );

This macro returns the value of the Checked property of the item object as type text.

d2fitmg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the item object as a type dvoid pointer.

d2fitmg_cmprssion_qlty( ctx, obj, val );

This macro returns the value of the D2FP_CMPRSSION_QLTY property of the item object as type number.

d2fitmg_cnv_nam( ctx, obj, val );

This macro returns the value of the Canvas Key property of the item object as type text.

d2fitmg_cnv_obj( ctx, obj, val );

This macro returns the value of the D2FP_CNV_OBJ property of the item object as type object.

d2fitmg_col_nam( ctx, obj, val );

This macro returns the value of the Column Name property of the item object as type text.

d2fitmg_comm_mode( ctx, obj, val );

This macro returns the value of the Communication Mode property of the item object as type number.

d2fitmg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the item object as type text.

d2fitmg_compress( ctx, obj, val );

This macro returns the value of the Compress property of the item object as type number.

d2fitmg_conceal_data( ctx, obj, val );

This macro returns the value of the Conceal Data property of the item object as type boolean.

d2fitmg_copy_val_from_itm( ctx, obj, val );

This macro returns the value of the Copy Data From Item property of the item object as type text.

d2fitmg_dat_src_blk( ctx, obj, val );

This macro returns the value of the Data Source Block property of the item object as type text.

d2fitmg_dat_src_x_axs( ctx, obj, val );

This macro returns the value of the Data Source X Axis property of the item object as type text.

d2fitmg_dat_src_y_axs( ctx, obj, val );

This macro returns the value of the Data Source Y Axis property of the item object as type text.

d2fitmg_dat_typ( ctx, obj, val );

This macro returns the value of the Data Type property of the item object as type number.

d2fitmg_db_itm( ctx, obj, val );

This macro returns the value of the Database Item property of the item object as type boolean.

d2fitmg_dflt_btn( ctx, obj, val );

This macro returns the value of the Default Button property of the item object as type boolean.

d2fitmg_disp_qlty( ctx, obj, val );

This macro returns the value of the Display Quality property of the item object as type number.

d2fitmg_dist_btwn_recs( ctx, obj, val );

This macro returns the value of the Distance Between Records property of the item object as type number.

d2fitmg_edt_nam( ctx, obj, val );

This macro returns the value of the Editor property of the item object as type text.

d2fitmg_edt_obj( ctx, obj, val );

This macro returns the value of the D2FP_EDT_OBJ property of the item object as type object.

d2fitmg_edt_x_pos( ctx, obj, val );

This macro returns the value of the Editor X Position, Editor Y Position property of the item object as type number.

d2fitmg_edt_y_pos( ctx, obj, val );

This macro returns the value of the Editor X Position, Editor Y Position property of the item object as type number.

d2fitmg_enabled( ctx, obj, val );

This macro returns the value of the Enabled property of the item object as type boolean.

d2fitmg_exec_mode( ctx, obj, val );

This macro returns the value of the Execution Mode property of the item object as type number.

d2fitmg_fill_pat( ctx, obj, val );

This macro returns the value of the Fill Pattern property of the item object as type text.

d2fitmg_fixed_len( ctx, obj, val );

This macro returns the value of the Fixed Length property of the item object as type boolean.

d2fitmg_flnam( ctx, obj, val );

This macro returns the value of the File Name property of the item object as type text.

d2fitmg_fmt_msk( ctx, obj, val );

This macro returns the value of the Format Mask property of the item object as type text.

d2fitmg_font_nam( ctx, obj, val );

This macro returns the value of the Font Name property of the item object as type text.

d2fitmg_font_siz( ctx, obj, val );

This macro returns the value of the Font Size property of the item object as type number.

d2fitmg_font_spcing( ctx, obj, val );

This macro returns the value of the Font Spacing property of the item object as type number.

d2fitmg_font_sty( ctx, obj, val );

This macro returns the value of the Font Style property of the item object as type number.

d2fitmg_font_wgth( ctx, obj, val );

This macro returns the value of the Font Weight property of the item object as type number.

d2fitmg_fore_color( ctx, obj, val );

This macro returns the value of the Foreground Color property of the item object as type text.

d2fitmg_formula( ctx, obj, val );

This macro returns the value of the Formula property of the item object as type text.

d2fitmg_height( ctx, obj, val );

This macro returns the value of the Width/Height property of the item object as type number.

d2fitmg_highest_allowed_val( ctx, obj, val );

This macro returns the value of the Highest Allowed Value/Lowest Allowed Value property of the item object as type text.

d2fitmg_hint( ctx, obj, val );

This macro returns the value of the Hint property of the item object as type text.

d2fitmg_icon_flnam( ctx, obj, val );

This macro returns the value of the Icon Filename property of the item object as type text.

d2fitmg_iconic( ctx, obj, val );

This macro returns the value of the Iconic property of the item object as type boolean.

d2fitmg_img_dpth( ctx, obj, val );

This macro returns the value of the Image Depth property of the item object as type number.

d2fitmg_img_fmt( ctx, obj, val );

This macro returns the value of the Image Format property of the item object as type number.

d2fitmg_init_kbrd_dir( ctx, obj, val );

This macro returns the value of the Initial Keyboard Direction property of the item object as type number.

d2fitmg_init_val( ctx, obj, val );

This macro returns the value of the Initial Value property of the item object as type text.

d2fitmg_insrt_allowed( ctx, obj, val );

This macro returns the value of the Insert Allowed property of the item object as type boolean.

d2fitmg_itm_typ( ctx, obj, val );

This macro returns the value of the Item Type property of the item object as type number.

d2fitmg_itms_disp( ctx, obj, val );

This macro returns the value of the Number of Items Displayed property of the item object as type number.

d2fitmg_justification( ctx, obj, val );

This macro returns the value of the Justification property of the item object as type number.

d2fitmg_kbrd_navigable( ctx, obj, val );

This macro returns the value of the Keyboard Navigable property of the item object as type boolean.

d2fitmg_kbrd_state( ctx, obj, val );

This macro returns the value of the D2FP_KBRD_STATE property of the item object as type number.

d2fitmg_keep_crsr_pos( ctx, obj, val );

This macro returns the value of the Keep Cursor Position property of the item object as type boolean.

d2fitmg_label( ctx, obj, val );

This macro returns the value of the Label property of the item object as type text.

d2fitmg_lang_dir( ctx, obj, val );

This macro returns the value of the Language Direction property of the item object as type number.

d2fitmg_lock_rec( ctx, obj, val );

This macro returns the value of the Lock Record property of the item object as type boolean.

d2fitmg_lov_nam( ctx, obj, val );

This macro returns the value of the D2FP_LOV_NAM property of the item object as type text.

d2fitmg_lov_obj( ctx, obj, val );

This macro returns the value of the D2FP_LOV_OBJ property of the item object as type object.

d2fitmg_lov_x_pos( ctx, obj, val );

This macro returns the value of the List X Position property of the item object as type number.

d2fitmg_lov_y_pos( ctx, obj, val );

This macro returns the value of the List Y Position property of the item object as type number.

d2fitmg_lowest_allowed_val( ctx, obj, val );

This macro returns the value of the Highest Allowed Value/Lowest Allowed Value property of the item object as type text.

d2fitmg_lst_element_cnt( ctx, obj, val );

This macro returns the value of the List Element Count property of the item object as type number.

d2fitmg_lst_sty( ctx, obj, val );

This macro returns the value of the List Style property of the item object as type number.

d2fitmg_max_len( ctx, obj, val );

This macro returns the value of the Maximum Length property of the item object as type number.

d2fitmg_mlt_lin( ctx, obj, val );

This macro returns the value of the Multi-line property of the item object as type boolean.

d2fitmg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the item object as type object.

d2fitmg_mouse_navigate( ctx, obj, val );

This macro returns the value of the Muse Navigate property of the item object as type boolean.

d2fitmg_name( ctx, obj, val );

This macro returns the value of the Name property of the item object as type text.

d2fitmg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the item object as type object.

d2fitmg_nxt_navigation_itm_nam( ctx, obj, val );

This macro returns the value of the D2FP_NAVIGATION_ITM_NAM property of the item object as type text.

d2fitmg_nxt_navigation_itm_obj( ctx, obj, val );

This macro returns the value of the D2FP_NAVIGATION_ITM_OBJ property of the item object as type object.

d2fitmg_ole_act_sty( ctx, obj, val );

This macro returns the value of the OLE Activation Style property of the item object as type number.

d2fitmg_ole_class( ctx, obj, val );

This macro returns the value of the OLE Class property of the item object as type text.

d2fitmg_ole_in_place_act( ctx, obj, val );

This macro returns the value of the OLE In-place Activation property of the item object as type boolean.

d2fitmg_ole_insd_out_support( ctx, obj, val );

This macro returns the value of the OLE Inside-out Support property of the item object as type boolean.

d2fitmg_ole_popup_mnu_itms( ctx, obj, val );

This macro returns the value of the OLE Popup Menu Items property of the item object as type number.

d2fitmg_ole_resiz_sty( ctx, obj, val );

This macro returns the value of the OLE Resize Style property of the item object as type number.

d2fitmg_ole_show_popup_menu( ctx, obj, val );

This macro returns the value of the OLE Show Popup Menu property of the item object as type boolean.

d2fitmg_ole_show_tnnt_typ( ctx, obj, val );

This macro returns the value of the Show OLE Tenant Type property of the item object as type boolean.

d2fitmg_ole_tnnt_aspct( ctx, obj, val );

This macro returns the value of the OLE Tenant Aspect property of the item object as type number.

d2fitmg_ole_tnnt_typ( ctx, obj, val );

This macro returns the value of the OLE Tenant Types property of the item object as type number.

d2fitmg_other_vals( ctx, obj, val );

This macro returns the value of the Mapping of Other Values property of the item object as type text.

d2fitmg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the item object as type object.

d2fitmg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the item object as type text.

d2fitmg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the item object as type text.

d2fitmg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_STR property of the item object as type number.

d2fitmg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the item object as type number.

d2fitmg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the item object as type text.

d2fitmg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the item object as type text.

d2fitmg_popup_mnu_nam( ctx, obj, val );

This macro returns the value of the Popup Menu property of the item object as type text.

d2fitmg_popup_mnu_obj( ctx, obj, val );

This macro returns the value of the D2FP_POPUP_MNU_OBJ property of the item object as type text.

d2fitmg_popup_va_obj( ctx, obj, val );

This macro returns the value of the D2FP_POPUP_VA_OBJ property of the item object as type object.

d2fitmg_prev_navigation_itm_nam( ctx, obj, val );

This macro returns the value of the Previous Navigation Item Name property of the item object as type text.

d2fitmg_prev_navigation_itm_obj( ctx, obj, val );

This macro returns the value of the D2FP_PREV_NAVIGATION_ITM_OBJ property of the item object as type object.

d2fitmg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the item object as type object.

d2fitmg_prmpt( ctx, obj, val );

This macro returns the value of the Prompt property of the item object as type text.

d2fitmg_prmpt_align( ctx, obj, val );

This macro returns the value of the Prompt Alignment property of the item object as type number.

d2fitmg_prmpt_align_ofst( ctx, obj, val );

This macro returns the value of the Prompt Alignment Offset property of the item object as type number.

d2fitmg_prmpt_att_edge( ctx, obj, val );

This macro returns the value of the Prompt Attachment Edge property of the item object as type number.

d2fitmg_prmpt_att_ofst( ctx, obj, val );

This macro returns the value of the Prompt Attachment Offset property of the item object as type number.

d2fitmg_prmpt_back_color( ctx, obj, val );

This macro returns the value of the Prompt Background Color property of the item object as type text.

d2fitmg_prmpt_disp_sty( ctx, obj, val );

This macro returns the value of the Prompt Display Style property of the item object as type number.

d2fitmg_prmpt_fill_pat( ctx, obj, val );

This macro returns the value of the Prompt Fill Pattern property of the item object as type text.

d2fitmg_prmpt_font_nam( ctx, obj, val );

This macro returns the value of the Prompt Font Name property of the item object as type text.

d2fitmg_prmpt_font_siz( ctx, obj, val );

This macro returns the value of the Prompt Font Size property of the item object as type number.

d2fitmg_prmpt_font_spcing( ctx, obj, val );

This macro returns the value of the Prompt Font Spacing property of the item object as type number.

d2fitmg_prmpt_font_sty( ctx, obj, val );

This macro returns the value of the Prompt Font Style property of the item object as type number.

d2fitmg_prmpt_font_wght( ctx, obj, val );

This macro returns the value of the Prompt Font Weight property of the item object as type number.

d2fitmg_prmpt_fore_color( ctx, obj, val );

This macro returns the value of the Prompt Foreground Color property of the item object as type text.

d2fitmg_prmpt_jst( ctx, obj, val );

This macro returns the value of the Prompt Justification property of the item object as type number.

d2fitmg_prmpt_reading_ordr( ctx, obj, val );

This macro returns the value of the Prompt Reading Order property of the item object as type number.

d2fitmg_prmpt_vat_nam( ctx, obj, val );

This macro returns the value of the Prompt Visual Attribute Group property of the item object as type text.

d2fitmg_prmpt_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_VAT_OBJ property of the item object as type object.

d2fitmg_prmry_key( ctx, obj, val );

This macro returns the value of the Primary Key property of the item object as type boolean.

d2fitmg_qry_allowed( ctx, obj, val );

This macro returns the value of the Query Allowed property of the item object as type boolean.

d2fitmg_qry_len( ctx, obj, val );

This macro returns the value of the Query Length property of the item object as type number.

d2fitmg_qry_only( ctx, obj, val );

This macro returns the value of the Query Only property of the item object as type boolean.

d2fitmg_rad_but( ctx, obj, val );

This macro returns the value of the D2FP_RAD_BUT property of the item object as type object.

d2fitmg_reading_ordr( ctx, obj, val );

This macro returns the value of the Reading Order property of the item object as type number.

d2fitmg_rec_vat_grp_nam( ctx, obj, val );

This macro returns the value of the Current Record Visual Attribute Group property of the item object as type text.

d2fitmg_rec_vat_grp_obj( ctx, obj, val );

This macro returns the value of the D2FP_REC_VAT_GRP_OBJ property of the item object as type object.

d2fitmg_rendered( ctx, obj, val );

This macro returns the value of the Rendered property of the item object as type boolean.

d2fitmg_required( ctx, obj, val );

This macro returns the value of the Required property of the item object as type boolean.

d2fitmg_show_fast_fwd( ctx, obj, val );

This macro returns the value of the Show Fast Forward Button property of the item object as type boolean.

d2fitmg_show_horz_scrlbr( ctx, obj, val );

This macro returns the value of the Show Horizontal Scrollbar property of the item object as type boolean.

d2fitmg_show_palette( ctx, obj, val );

This macro returns the value of the Show Palette property of the item object as type boolean.

d2fitmg_show_play( ctx, obj, val );

This macro returns the value of the Show Play Button property of the item object as type boolean.

d2fitmg_show_rec( ctx, obj, val );

This macro returns the value of the Show Record Button property of the item object as type boolean.

d2fitmg_show_rewind( ctx, obj, val );

This macro returns the value of the Show Rewind Button property of the item object as type boolean.

d2fitmg_show_slider( ctx, obj, val );

This macro returns the value of the Show Slider Button property of the item object as type boolean.

d2fitmg_show_time( ctx, obj, val );

This macro returns the value of the Show Time Indicator property of the item object as type boolean.

d2fitmg_show_vert_scrlbr( ctx, obj, val );

This macro returns the value of the Show Vertical Scrollbar property of the item object as type boolean.

d2fitmg_show_volume( ctx, obj, val );

This macro returns the value of the Show Volume Control property of the item object as type boolean.

d2fitmg_sizing_sty( ctx, obj, val );

This macro returns the value of the Sizing Style property of the item object as type number.

d2fitmg_snd_fmt( ctx, obj, val );

This macro returns the value of the Sound Format property of the item object as type number.

d2fitmg_snd_qlty( ctx, obj, val );

This macro returns the value of the Sound Quality property of the item object as type number.

d2fitmg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the item object as type object.

d2fitmg_summ_blk_nam( ctx, obj, val );

This macro returns the value of the Summarized Block property of the item object as type text.

d2fitmg_summ_func( ctx, obj, val );

This macro returns the value of the Summarized Function property of the item object as type number.

d2fitmg_summ_itm_nam( ctx, obj, val );

This macro returns the value of the Summarized Item property of the item object as type text.

d2fitmg_sync_itm_nam( ctx, obj, val );

This macro returns the value of the Synchronize with Item property of the item object as type text.

d2fitmg_sync_itm_obj( ctx, obj, val );

This macro returns the value of the D2FP_SYNC_ITM_OBJ property of the item object as type object.

d2fitmg_tbp_nam( ctx, obj, val );

This macro returns the value of the D2FP_TBP_NAM property of the item object as type text.

d2fitmg_tbp_obj( ctx, obj, val );

This macro returns the value of the D2FP_TBP_OBJ property of the item object as type object.

d2fitmg_tooltip( ctx, obj, val );

This macro returns the value of the Tooltip property of the item object as type text.

d2fitmg_tooltip_vat_grp( ctx, obj, val );

This macro returns the value of the Tooltip Visual Attribute Group property of the item object as type text.

d2fitmg_trigger( ctx, obj, val );

This macro returns the value of the D2FP_TRIGGER property of the item object as type object.

d2fitmg_unchked_val( ctx, obj, val );

This macro returns the value of the Value When Unchecked property of the item object as type text.

d2fitmg_updt_allowed( ctx, obj, val );

This macro returns the value of the Update Allowed property of the item object as type boolean.

d2fitmg_updt_commit( ctx, obj, val );

This macro returns the value of the Update Commit property of the item object as type boolean.

d2fitmg_updt_if_null( ctx, obj, val );

This macro returns the value of the Update Only if NULL  property of the item object as type boolean.

d2fitmg_updt_qry( ctx, obj, val );

This macro returns the value of the Update Query property of the item object as type boolean.

d2fitmg_validate_from_lst( ctx, obj, val );

This macro returns the value of the Validate From List property of the item object as type boolean.

d2fitmg_vat_nam( ctx, obj, val );

This macro returns the value of the Visual Attribute Group property of the item object as type text.

d2fitmg_val_obj( ctx, obj, val );

This macro returns the value of the D2FP_VAT_GRP property of the item object as type object.

d2fitmg_visible( ctx, obj, val );

This macro returns the value of the Visible property of the item object as type boolean.

d2fitmg_while_on_black( ctx, obj, val );

This macro returns the value of the White on Black property of the item object as type boolean.

d2fitmg_width( ctx, obj, val );

This macro returns the value of the Width/Height property of the item object as type number.

d2fitmg_wrap_sty( ctx, obj, val );

This macro returns the value of the Wrap Style property of the item object as type number.

d2fitmg_x_pos( ctx, obj, val );

This macro returns the value of the X Position/Y Position property of the item object as type number.

d2fitmg_y_pos( ctx, obj, val );

This macro returns the value of the X Position/Y Position property of the item object as type number.

d2fitms_access_key( ctx, obj, val );

This macro sets the value of the Access Key property of the item object.

d2fitms_activex_class( ctx, obj, val );

This macro sets the value of the D2FP_ACTIVEX_CLASS property of the item object.

d2fitms_activex_val_prop( ctx, obj, val );

This macro sets the value of the D2FP_ACTIVEX_VAL_PROP property of the item object.

d2fitms_audio_chnnls( ctx, obj, val );

This macro sets the value of the Audio Channels property of the item object.

d2fitms_auto_hint( ctx, obj, val );

This macro sets the value of the Display Hint Automatically property of the item object.

d2fitms_auto_skip( ctx, obj, val );

This macro sets the value of the Auto Skip property of the item object.

d2fitms_back_color( ctx, obj, val );

This macro sets the value of the Background Color property of the item object.

d2fitms_bevel( ctx, obj, val );

This macro sets the value of the Bevel property of the item object.

d2fitms_calc_mode( ctx, obj, val );

This macro sets the value of the Calculation Mode property of the item object.

d2fitms_case_insensitive_qry( ctx, obj, val );

This macro sets the value of the Case Insensitive Query property of the item object.

d2fitms_case_rstrction( ctx, obj, val );

This macro sets the value of the Case Restriction property of the item object.

d2fitms_chk_bx_other_vals( ctx, obj, val );

This macro sets the value of the Check Box Mapping of Other Values property of the item object.

d2fitms_chked_val( ctx, obj, val );

This macro sets the value of the Checked property of the item object.

d2fitms_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the item object.

d2fitms_cmprssion_qlty( ctx, obj, val );

This macro sets the value of the D2FP_CMPRSSION_QLTY property of the item object.

d2fitms_cnv_nam( ctx, obj, val );

This macro sets the value of the Canvas Key property of the item object.

d2fitms_cnv_obj( ctx, obj, val );

This macro sets the value of the D2FP_CNV_OBJ property of the item object.

d2fitms_col_nam( ctx, obj, val );

This macro sets the value of the Column Name property of the item object.

d2fitms_comm_mode( ctx, obj, val );

This macro sets the value of the Communication Mode property of the item object.

d2fitms_comment( ctx, obj, val );

This macro sets the value of the Comments property of the item object.

d2fitms_compress( ctx, obj, val );

This macro sets the value of the Compress property of the item object.

d2fitms_conceal_data( ctx, obj, val );

This macro sets the value of the Conceal Data property of the item object.

d2fitms_copy_val_from_itm( ctx, obj, val );

This macro sets the value of the Copy Data From Item property of the item object.

d2fitms_dat_src_blk( ctx, obj, val );

This macro sets the value of the Data Source Block property of the item object.

d2fitms_dat_src_x_axs( ctx, obj, val );

This macro sets the value of the Data Source X Axis property of the item object.

d2fitms_dat_src_y_axs( ctx, obj, val );

This macro sets the value of the Data Source Y Axis property of the item object.

d2fitms_dat_typ( ctx, obj, val );

This macro sets the value of the Data Type property of the item object.

d2fitms_db_itm( ctx, obj, val );

This macro sets the value of the Database Item property of the item object.

d2fitms_dflt_btn( ctx, obj, val );

This macro sets the value of the Default Button property of the item object.

d2fitms_disp_qlty( ctx, obj, val );

This macro sets the value of the Display Quality property of the item object.

d2fitms_dist_btwn_recs( ctx, obj, val );

This macro sets the value of the Distance Between Records property of the item object.

d2fitms_edt_nam( ctx, obj, val );

This macro sets the value of the Editor property of the item object.

d2fitms_edt_obj( ctx, obj, val );

This macro sets the value of the D2FP_EDT_OBJ property of the item object.

d2fitms_edt_x_pos( ctx, obj, val );

This macro sets the value of the Editor X Position, Editor Y Position property of the item object.

d2fitms_edt_y_pos( ctx, obj, val );

This macro sets the value of the Editor X Position, Editor Y Position property of the item object.

d2fitms_enabled( ctx, obj, val );

This macro sets the value of the Enabled property of the item object.

d2fitms_exec_mode( ctx, obj, val );

This macro sets the value of the Execution Mode property of the item object.

d2fitms_fill_pat( ctx, obj, val );

This macro sets the value of the Fill Pattern property of the item object.

d2fitms_fixed_len( ctx, obj, val );

This macro sets the value of the Fixed Length property of the item object.

d2fitms_flnam( ctx, obj, val );

This macro sets the value of the File Name property of the item object.

d2fitms_fmt_msk( ctx, obj, val );

This macro sets the value of the Format Mask property of the item object.

d2fitms_font_nam( ctx, obj, val );

This macro sets the value of the Font Name property of the item object.

d2fitms_font_siz( ctx, obj, val );

This macro sets the value of the Font Size property of the item object.

d2fitms_font_spcing( ctx, obj, val );

This macro sets the value of the Font Spacing property of the item object.

d2fitms_font_sty( ctx, obj, val );

This macro sets the value of the Font Style property of the item object.

d2fitms_font_wgth( ctx, obj, val );

This macro sets the value of the Font Weight property of the item object.

d2fitms_fore_color( ctx, obj, val );

This macro sets the value of the Foreground Color property of the item object.

d2fitms_formula( ctx, obj, val );

This macro sets the value of the Formula property of the item object.

d2fitms_height( ctx, obj, val );

This macro sets the value of the Width/Height property of the item object.

d2fitms_highest_allowed_val( ctx, obj, val );

This macro sets the value of the Highest Allowed Value/Lowest Allowed Value property of the item object.

d2fitms_hint( ctx, obj, val );

This macro sets the value of the Hint property of the item object.

d2fitms_icon_flnam( ctx, obj, val );

This macro sets the value of the Icon Filename property of the item object.

d2fitms_iconic( ctx, obj, val );

This macro sets the value of the Iconic property of the item object.

d2fitms_img_dpth( ctx, obj, val );

This macro sets the value of the Image Depth property of the item object.

d2fitms_img_fmt( ctx, obj, val );

This macro sets the value of the Image Format property of the item object.

d2fitms_init_kbrd_dir( ctx, obj, val );

This macro sets the value of the Initial Keyboard Direction property of the item object.

d2fitms_init_val( ctx, obj, val );

This macro sets the value of the Initial Value property of the item object.

d2fitms_insrt_allowed( ctx, obj, val );

This macro sets the value of the Insert Allowed property of the item object.

d2fitms_itm_typ( ctx, obj, val );

This macro sets the value of the Item Type property of the item object.

d2fitms_itms_disp( ctx, obj, val );

This macro sets the value of the Number of Items Displayed property of the item object.

d2fitms_justification( ctx, obj, val );

This macro sets the value of the Justification property of the item object.

d2fitms_kbrd_navigable( ctx, obj, val );

This macro sets the value of the Keyboard Navigable property of the item object.

d2fitms_kbrd_state( ctx, obj, val );

This macro sets the value of the D2FP_KBRD_STATE property of the item object.

d2fitms_keep_crsr_pos( ctx, obj, val );

This macro sets the value of the Keep Cursor Position property of the item object.

d2fitms_label( ctx, obj, val );

This macro sets the value of the Label property of the item object.

d2fitms_lang_dir( ctx, obj, val );

This macro sets the value of the Language Direction property of the item object.

d2fitms_lock_rec( ctx, obj, val );

This macro sets the value of the Lock Record property of the item object.

d2fitms_lov_nam( ctx, obj, val );

This macro sets the value of the D2FP_LOV_NAM property of the item object.

d2fitms_lov_obj( ctx, obj, val );

This macro sets the value of the D2FP_LOV_OBJ property of the item object.

d2fitms_lov_x_pos( ctx, obj, val );

This macro sets the value of the List X Position property of the item object.

d2fitms_lov_y_pos( ctx, obj, val );

This macro sets the value of the List Y Position property of the item object.

d2fitms_lowest_allowed_val( ctx, obj, val );

This macro sets the value of the Highest Allowed Value/Lowest Allowed Value property of the item object.

d2fitms_lst_element_cnt( ctx, obj, val );

This macro sets the value of the List Element Count property of the item object.

d2fitms_lst_sty( ctx, obj, val );

This macro sets the value of the List Style property of the item object.

d2fitms_max_len( ctx, obj, val );

This macro sets the value of the Maximum Length property of the item object.

d2fitms_mlt_lin( ctx, obj, val );

This macro sets the value of the Multi-line property of the item object.

d2fitms_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the item object.

d2fitms_mouse_navigate( ctx, obj, val );

This macro sets the value of the Muse Navigate property of the item object.

d2fitms_name( ctx, obj, val );

This macro sets the value of the Name property of the item object.

d2fitms_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the item object.

d2fitms_nxt_navigation_itm_nam( ctx, obj, val );

This macro sets the value of the D2FP_NAVIGATION_ITM_NAM property of the item object.

d2fitms_nxt_navigation_itm_obj( ctx, obj, val );

This macro sets the value of the D2FP_NAVIGATION_ITM_OBJ property of the item object.

d2fitms_ole_act_sty( ctx, obj, val );

This macro sets the value of the OLE Activation Style property of the item object.

d2fitms_ole_class( ctx, obj, val );

This macro sets the value of the OLE Class property of the item object.

d2fitms_ole_in_place_act( ctx, obj, val );

This macro sets the value of the OLE In-place Activation property of the item object.

d2fitms_ole_insd_out_support( ctx, obj, val );

This macro sets the value of the OLE Inside-out Support property of the item object.

d2fitms_ole_popup_mnu_itms( ctx, obj, val );

This macro sets the value of the OLE Popup Menu Items property of the item object.

d2fitms_ole_resiz_sty( ctx, obj, val );

This macro sets the value of the OLE Resize Style property of the item object.

d2fitms_ole_show_popup_menu( ctx, obj, val );

This macro sets the value of the OLE Show Popup Menu property of the item object.

d2fitms_ole_show_tnnt_typ( ctx, obj, val );

This macro sets the value of the Show OLE Tenant Type property of the item object.

d2fitms_ole_tnnt_aspct( ctx, obj, val );

This macro sets the value of the OLE Tenant Aspect property of the item object.

d2fitms_ole_tnnt_typ( ctx, obj, val );

This macro sets the value of the OLE Tenant Types property of the item object.

d2fitms_other_vals( ctx, obj, val );

This macro sets the value of the Mapping of Other Values property of the item object.

d2fitms_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the item object.

d2fitms_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the item object.

d2fitms_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the item object.

d2fitms_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_STR property of the item object.

d2fitms_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the item object.

d2fitms_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the item object.

d2fitms_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the item object.

d2fitms_popup_mnu_nam( ctx, obj, val );

This macro sets the value of the Popup Menu property of the item object.

d2fitms_popup_mnu_obj( ctx, obj, val );

This macro sets the value of the D2FP_POPUP_MNU_OBJ property of the item object.

d2fitms_popup_va_obj( ctx, obj, val );

This macro sets the value of the D2FP_POPUP_VA_OBJ property of the item object.

d2fitms_prev_navigation_itm_nam( ctx, obj, val );

This macro sets the value of the Previous Navigation Item Name property of the item object.

d2fitms_prev_navigation_itm_obj( ctx, obj, val );

This macro sets the value of the D2FP_PREV_NAVIGATION_ITM_OBJ property of the item object.

d2fitms_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the item object.

d2fitms_prmpt( ctx, obj, val );

This macro sets the value of the Prompt property of the item object.

d2fitms_prmpt_align( ctx, obj, val );

This macro sets the value of the Prompt Alignment property of the item object.

d2fitms_prmpt_align_ofst( ctx, obj, val );

This macro sets the value of the Prompt Alignment Offset property of the item object.

d2fitms_prmpt_att_edge( ctx, obj, val );

This macro sets the value of the Prompt Attachment Edge property of the item object.

d2fitms_prmpt_att_ofst( ctx, obj, val );

This macro sets the value of the Prompt Attachment Offset property of the item object.

d2fitms_prmpt_back_color( ctx, obj, val );

This macro sets the value of the Prompt Background Color property of the item object.

d2fitms_prmpt_disp_sty( ctx, obj, val );

This macro sets the value of the Prompt Display Style property of the item object.

d2fitms_prmpt_fill_pat( ctx, obj, val );

This macro sets the value of the Prompt Fill Pattern property of the item object.

d2fitms_prmpt_font_nam( ctx, obj, val );

This macro sets the value of the Prompt Font Name property of the item object.

d2fitms_prmpt_font_siz( ctx, obj, val );

This macro sets the value of the Prompt Font Size property of the item object.

d2fitms_prmpt_font_spcing( ctx, obj, val );

This macro sets the value of the Prompt Font Spacing property of the item object.

d2fitms_prmpt_font_sty( ctx, obj, val );

This macro sets the value of the Prompt Font Style property of the item object.

d2fitms_prmpt_font_wght( ctx, obj, val );

This macro sets the value of the Prompt Font Weight property of the item object.

d2fitms_prmpt_fore_color( ctx, obj, val );

This macro sets the value of the Prompt Foreground Color property of the item object.

d2fitms_prmpt_jst( ctx, obj, val );

This macro sets the value of the Prompt Justification property of the item object.

d2fitms_prmpt_reading_ordr( ctx, obj, val );

This macro sets the value of the Prompt Reading Order property of the item object.

d2fitms_prmpt_vat_nam( ctx, obj, val );

This macro sets the value of the Prompt Visual Attribute Group property of the item object.

d2fitms_prmpt_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_PRMPT_VAT_OBJ property of the item object.

d2fitms_prmry_key( ctx, obj, val );

This macro sets the value of the Primary Key property of the item object.

d2fitms_qry_allowed( ctx, obj, val );

This macro sets the value of the Query Allowed property of the item object.

d2fitms_qry_len( ctx, obj, val );

This macro sets the value of the Query Length property of the item object.

d2fitms_qry_only( ctx, obj, val );

This macro sets the value of the Query Only property of the item object.

d2fitms_rad_but( ctx, obj, val );

This macro sets the value of the D2FP_RAD_BUT property of the item object.

d2fitms_reading_ordr( ctx, obj, val );

This macro sets the value of the Reading Order property of the item object.

d2fitms_rec_vat_grp_nam( ctx, obj, val );

This macro sets the value of the Current Record Visual Attribute Group property of the item object.

d2fitms_rec_vat_grp_obj( ctx, obj, val );

This macro sets the value of the D2FP_REC_VAT_GRP_OBJ property of the item object.

d2fitms_rendered( ctx, obj, val );

This macro sets the value of the Rendered property of the item object.

d2fitms_required( ctx, obj, val );

This macro sets the value of the Required property of the item object.

d2fitms_show_fast_fwd( ctx, obj, val );

This macro sets the value of the Show Fast Forward Button property of the item object.

d2fitms_show_horz_scrlbr( ctx, obj, val );

This macro sets the value of the Show Horizontal Scrollbar property of the item object.

d2fitms_show_palette( ctx, obj, val );

This macro sets the value of the Show Palette property of the item object.

d2fitms_show_play( ctx, obj, val );

This macro sets the value of the Show Play Button property of the item object.

d2fitms_show_rec( ctx, obj, val );

This macro sets the value of the Show Record Button property of the item object.

d2fitms_show_rewind( ctx, obj, val );

This macro sets the value of the Show Rewind Button property of the item object.

d2fitms_show_slider( ctx, obj, val );

This macro sets the value of the Show Slider Button property of the item object.

d2fitms_show_time( ctx, obj, val );

This macro sets the value of the Show Time Indicator property of the item object.

d2fitms_show_vert_scrlbr( ctx, obj, val );

This macro sets the value of the Show Vertical Scrollbar property of the item object.

d2fitms_show_volume( ctx, obj, val );

This macro sets the value of the Show Volume Control property of the item object.

d2fitms_sizing_sty( ctx, obj, val );

This macro sets the value of the Sizing Style property of the item object.

d2fitms_snd_fmt( ctx, obj, val );

This macro sets the value of the Sound Format property of the item object.

d2fitms_snd_qlty( ctx, obj, val );

This macro sets the value of the Sound Quality property of the item object.

d2fitms_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the item object.

d2fitms_summ_blk_nam( ctx, obj, val );

This macro sets the value of the Summarized Block property of the item object.

d2fitms_summ_func( ctx, obj, val );

This macro sets the value of the Summarized Function property of the item object.

d2fitms_summ_itm_nam( ctx, obj, val );

This macro sets the value of the Summarized Item property of the item object.

d2fitms_sync_itm_nam( ctx, obj, val );

This macro sets the value of the Synchronize with Item property of the item object.

d2fitms_sync_itm_obj( ctx, obj, val );

This macro sets the value of the D2FP_SYNC_ITM_OBJ property of the item object.

d2fitms_tbp_nam( ctx, obj, val );

This macro sets the value of the D2FP_TBP_NAM property of the item object.

d2fitms_tbp_obj( ctx, obj, val );

This macro sets the value of the D2FP_TBP_OBJ property of the item object.

d2fitms_tooltip( ctx, obj, val );

This macro sets the value of the Tooltip property of the item object.

d2fitms_tooltip_vat_grp( ctx, obj, val );

This macro sets the value of the Tooltip Visual Attribute Group property of the item object.

d2fitms_trigger( ctx, obj, val );

This macro sets the value of the D2FP_TRIGGER property of the item object.

d2fitms_unchked_val( ctx, obj, val );

This macro sets the value of the Value When Unchecked property of the item object.

d2fitms_updt_allowed( ctx, obj, val );

This macro sets the value of the Update Allowed property of the item object.

d2fitms_updt_commit( ctx, obj, val );

This macro sets the value of the Update Commit property of the item object.

d2fitms_updt_if_null( ctx, obj, val );

This macro sets the value of the Update Only if NULL  property of the item object.

d2fitms_updt_qry( ctx, obj, val );

This macro sets the value of the Update Query property of the item object.

d2fitms_validate_from_lst( ctx, obj, val );

This macro sets the value of the Validate From List property of the item object.

d2fitms_vat_nam( ctx, obj, val );

This macro sets the value of the Visual Attribute Group property of the item object.

d2fitms_val_obj( ctx, obj, val );

This macro sets the value of the D2FP_VAT_GRP property of the item object.

d2fitms_visible( ctx, obj, val );

This macro sets the value of the Visible property of the item object.

d2fitms_while_on_black( ctx, obj, val );

This macro sets the value of the White on Black property of the item object.

d2fitms_width( ctx, obj, val );

This macro sets the value of the Width/Height property of the item object.

d2fitms_wrap_sty( ctx, obj, val );

This macro sets the value of the Wrap Style property of the item object.

d2fitms_x_pos( ctx, obj, val );

This macro sets the value of the X Position/Y Position property of the item object.

d2fitms_y_pos( ctx, obj, val );

This macro sets the value of the X Position/Y Position property of the item object.


LOV column mapping object macros

  Related Topics

This section describes the macros of the Form Builder Open API LOV Column Mapping object.

d2flcmg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the LOV column mapping object as a type dvoid pointer.

d2flcmg_disp_wid( ctx, obj, val );

This macro returns the value of the Display Width property of the LOV column mapping object as type number.

d2flcmg_name( ctx, obj, val );

This macro returns the value of the Name property of the LOV column mapping object as type text.

d2flcmg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the LOV column mapping object as type object.

d2flcmg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the LOV column mapping object as type object.

d2flcmg_rtrn_itm( ctx, obj, val );

This macro returns the value of the Return LOV column mapping property of the LOV column mapping object as type text.

d2flcmg_title( ctx, obj, val );

This macro returns the value of the Title property of the LOV column mapping object as type text.

d2flcms_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the LOV column mapping object.

d2flcms_disp_wid( ctx, obj, val );

This macro sets the value of the Display Width property of the LOV column mapping object.

d2flcms_name( ctx, obj, val );

This macro sets the value of the Name property of the LOV column mapping object.

d2flcms_rtrn_itm( ctx, obj, val );

This macro sets the value of the Return LOV column mapping property of the LOV column mapping object.

d2flcms_title( ctx, obj, val );

This macro sets the value of the Title property of the LOV column mapping object.


List of values (LOV) object macros

  Related Topics

This section describes the macros of the Form Builder Open API List of Values (LOV) object.

d2flovg_auto_col_wid( ctx, obj, val );

This macro returns the value of the Automatic Column Width property of the list of values object as type boolean.

d2flovg_auto_disp( ctx, obj, val );

This macro returns the value of the Automatic Display property of the list of values object as type boolean.

d2flovg_auto_pos( ctx, obj, val );

This macro returns the value of the Automatic Position property of the list of values object as type boolean.

d2flovg_auto_rfrsh( ctx, obj, val );

This macro returns the value of the Automatic Refresh property of the list of values object as type boolean.

d2flovg_auto_skip( ctx, obj, val );

This macro returns the value of the Automatic Skip property of the list of values object as type boolean.

d2flovg_auto_slct( ctx, obj, val );

This macro returns the value of the Automatic Select property of the list of values object as type boolean.

d2flovg_back_color( ctx, obj, val );

This macro returns the value of the Background Color property of the list of values object as type text.

d2flovg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the list of values object as a type dvoid pointer.

d2flovg_col_map( ctx, obj, val );

This macro returns the value of the Column Mapping Properties property of the list of values object as type object.

d2flovg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the list of values object as type text.

d2flovg_fill_pat( ctx, obj, val );

This macro returns the value of the Fill Pattern property of the list of values object as type text.

d2flovg_fltr_before_disp( ctx, obj, val );

This macro returns the value of the Filter Before Display property of the list of values object as type boolean.

d2flovg_font_nam( ctx, obj, val );

This macro returns the value of the Font Name property of the list of values object as type text.

d2flovg_font_siz( ctx, obj, val );

This macro returns the value of the Font Size property of the list of values object as type number.

d2flovg_font_spcing( ctx, obj, val );

This macro returns the value of the Font Spacing property of the list of values object as type number.

d2flovg_font_sty( ctx, obj, val );

This macro returns the value of the Font Style property of the list of values object as type number.

d2flovg_font_wght( ctx, obj, val );

This macro returns the value of the Font Weight property of the list of values object as type number.

d2flovg_fore_color( ctx, obj, val );

This macro returns the value of the Foreground Color property of the list of values object as type text.

d2flovg_height( ctx, obj, val );

This macro returns the value of the Width/Height property of the list of values object as type number.

d2flovg_lang_dir( ctx, obj, val );

This macro returns the value of the Language Direction property of the list of values object as type number.

d2flovg_lst_typ( ctx, obj, val );

This macro returns the value of the List Type property of the list of values object as type number.

d2flovg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the list of values object as type object.

d2flovg_name( ctx, obj, val );

This macro returns the value of the Name property of the list of values object as type text.

d2flovg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the list of values object as type object.

d2flovg_old_lov_txt( ctx, obj, val );

This macro returns the value of the Old LOV Text property of the list of values object as type text.

d2flovg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the list of values object as type object.

d2flovg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the list of values object as type text.

d2flovg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the list of values object as type text.

d2flovg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the list of values object as type number.

d2flovg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the list of values object as type number.

d2flovg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the list of values object as type text.

d2flovg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the list of values object as type text.

d2flovg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the list of values object as type object.

d2flovg_rec_grp_nam( ctx, obj, val );

This macro returns the value of the Record Group property of the list of values object as type text.

d2flovg_rec_grp_obj( ctx, obj, val );

This macro returns the value of the D2FP_REC_GRP_OBJ property of the list of values object as type object.

d2flovg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the list of values object as type object.

d2flovg_title( ctx, obj, val );

This macro returns the value of the Title property of the list of values object as type text.

d2flovg_vat_nam( ctx, obj, val );

This macro returns the value of the Visual Attribute Group property of the list of values object as type text.

d2flovg_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_VAT_OBJ property of the list of values object as type object.

d2flovg_white_on_black( ctx, obj, val );

This macro returns the value of the White on Black property of the list of values object as type boolean.

d2flovg_width( ctx, obj, val );

This macro returns the value of the Width/Height property of the list of values object as type number.

d2flovg_x_pos( ctx, obj, val );

This macro returns the value of the X Position/Y Position property of the list of values object as type number.

d2flovg_y_pos( ctx, obj, val );

This macro returns the value of the X Position/Y Position property of the list of values object as type number.

d2flovs_auto_col_wid( ctx, obj, val );

This macro sets the value of the Automatic Column Width property of the list of values object.

d2flovs_auto_disp( ctx, obj, val );

This macro sets the value of the Automatic Display property of the list of values object.

d2flovs_auto_pos( ctx, obj, val );

This macro sets the value of the Automatic Position property of the list of values object.

d2flovs_auto_rfrsh( ctx, obj, val );

This macro sets the value of the Automatic Refresh property of the list of values object.

d2flovs_auto_skip( ctx, obj, val );

This macro sets the value of the Automatic Skip property of the list of values object.

d2flovs_auto_slct( ctx, obj, val );

This macro sets the value of the Automatic Select property of the list of values object.

d2flovs_back_color( ctx, obj, val );

This macro sets the value of the Background Color property of the list of values object.

d2flovs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the list of values object.

d2flovs_col_map( ctx, obj, val );

This macro sets the value of the Column Mapping Properties property of the list of values object.

d2flovs_comment( ctx, obj, val );

This macro sets the value of the Comments property of the list of values object.

d2flovs_fill_pat( ctx, obj, val );

This macro sets the value of the Fill Pattern property of the list of values object.

d2flovs_fltr_before_disp( ctx, obj, val );

This macro sets the value of the Filter Before Display property of the list of values object.

d2flovs_font_nam( ctx, obj, val );

This macro sets the value of the Font Name property of the list of values object.

d2flovs_font_siz( ctx, obj, val );

This macro sets the value of the Font Size property of the list of values object.

d2flovs_font_spcing( ctx, obj, val );

This macro sets the value of the Font Spacing property of the list of values object.

d2flovs_font_sty( ctx, obj, val );

This macro sets the value of the Font Style property of the list of values object.

d2flovs_font_wght( ctx, obj, val );

This macro sets the value of the Font Weight property of the list of values object.

d2flovs_fore_color( ctx, obj, val );

This macro sets the value of the Foreground Color property of the list of values object.

d2flovs_height( ctx, obj, val );

This macro sets the value of the Width/Height property of the list of values object.

d2flovs_lang_dir( ctx, obj, val );

This macro sets the value of the Language Direction property of the list of values object.

d2flovs_lst_typ( ctx, obj, val );

This macro sets the value of the List Type property of the list of values object.

d2flovs_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the list of values object.

d2flovs_name( ctx, obj, val );

This macro sets the value of the Name property of the list of values object.

d2flovs_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the list of values object.

d2flovs_old_lov_txt( ctx, obj, val );

This macro sets the value of the Old LOV Text property of the list of values object.

d2flovs_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the list of values object.

d2flovs_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the list of values object.

d2flovs_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the list of values object.

d2flovs_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the list of values object.

d2flovs_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the list of values object.

d2flovs_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the list of values object.

d2flovs_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the list of values object.

d2flovs_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the list of values object.

d2flovs_rec_grp_nam( ctx, obj, val );

This macro sets the value of the Record Group property of the list of values object.

d2flovs_rec_grp_obj( ctx, obj, val );

This macro sets the value of the D2FP_REC_GRP_OBJ property of the list of values object.

d2flovs_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the list of values object.

d2flovs_title( ctx, obj, val );

This macro sets the value of the Title property of the list of values object.

d2flovs_vat_nam( ctx, obj, val );

This macro sets the value of the Visual Attribute Group property of the list of values object.

d2flovs_xxx( ctx, obj, val );

This macro sets the value of the XXX property of the list of values object.

d2flovs_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_VAT_OBJ property of the list of values object.

d2flovs_white_on_black( ctx, obj, val );

This macro sets the value of the White on Black property of the list of values object.

d2flovs_width( ctx, obj, val );

This macro sets the value of the Width/Height property of the list of values object.

d2flovs_x_pos( ctx, obj, val );

This macro sets the value of the X Position/Y Position property of the list of values object.

d2flovs_y_pos( ctx, obj, val );

This macro sets the value of the X Position/Y Position property of the list of values object.


Menu object macros

  Related Topics

This section describes the macros of the Form Builder Open API Menu object.

d2fmnug_btm_ttl( ctx, obj, val );

This macro returns the value of the Bottom Title property of the menu object as type text.

d2fmnug_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the menu object as a type dvoid pointer.

d2fmnug_comment( ctx, obj, val );

This macro returns the value of the Comments property of the menu object as type text.

d2fmnug_mnu_itm( ctx, obj, val );

This macro returns the value of the Menu Item Type property of the menu object as type object.

d2fmnug_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the menu object as type object.

d2fmnug_name( ctx, obj, val );

This macro returns the value of the Name property of the menu object as type text.

d2fmnug_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the menu object as type object.

d2fmnug_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the menu object as type object.

d2fmnug_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the menu object as type text.

d2fmnug_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the menu object as type text.

d2fmnug_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the menu object as type number.

d2fmnug_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the menu object as type number.

d2fmnug_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the menu object as type text.

d2fmnug_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the menu object as type text.

d2fmnug_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the menu object as type object.

d2fmnug_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the menu object as type object.

d2fmnug_sub_ttl( ctx, obj, val );

This macro returns the value of the Subtitle property of the menu object as type text.

d2fmnug_tear_off_mnu( ctx, obj, val );

This macro returns the value of the Tear-off Menu property of the menu object as type boolean.

d2fmnug_title( ctx, obj, val );

This macro returns the value of the Title property of the menu object as type text.

d2fmnus_btm_ttl( ctx, obj, val );

This macro sets the value of the Bottom Title property of the menu object.

d2fmnus_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the menu object.

d2fmnus_comment( ctx, obj, val );

This macro sets the value of the Comments property of the menu object.

d2fmnus_mnu_itm( ctx, obj, val );

This macro sets the value of the Menu Item Type property of the menu object.

d2fmnus_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the menu object.

d2fmnus_name( ctx, obj, val );

This macro sets the value of the Name property of the menu object.

d2fmnus_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the menu object.

d2fmnus_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the menu object.

d2fmnus_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the menu object.

d2fmnus_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the menu object.

d2fmnus_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the menu object.

d2fmnus_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the menu object.

d2fmnus_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the menu object.

d2fmnus_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the menu object.

d2fmnus_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the menu object.

d2fmnus_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the menu object.

d2fmnus_sub_ttl( ctx, obj, val );

This macro sets the value of the Subtitle property of the menu object.

d2fmnus_tear_off_mnu( ctx, obj, val );

This macro sets the value of the Tear-off Menu property of the menu object.

d2fmnus_title( ctx, obj, val );

This macro sets the value of the Title property of the menu object.


Menu module object macros

  Related Topics

This section describes the macros of the Form Builder Open API Menu Module object.

d2fmmdg_att_lib( ctx, obj, val );

This macro returns the value of the D2FP_ATT_LIB property of the menu module object as type object.

d2fmmdg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the menu module object as a type dvoid pointer.

d2fmmdg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the menu module object as type text.

d2fmmdg_inhrt_sty( ctx, obj, val );

This macro returns the value of the D2FP_INHRT_STY property of the menu module object as type number.

d2fmmdg_main_mnu( ctx, obj, val );

This macro returns the value of the Main Menu property of the menu module object as type text.

d2fmmdg_menu( ctx, obj, val );

This macro returns the value of the D2FP_MENU property of the menu module object as type object.

d2fmmdg_mnu_description( ctx, obj, val );

This macro returns the value of the Menu Description property of the menu module object as type text.

d2fmmdg_mnu_drctry( ctx, obj, val );

This macro returns the value of the Menu Directory property of the menu module object as type text.

d2fmmdg_mnu_flnam( ctx, obj, val );

This macro returns the value of the Menu Filename property of the menu module object as type text.

d2fmmdg_mnu_param( ctx, obj, val );

This macro returns the value of the D2FP_MNU_PARAM property of the menu module object as type object.

d2fmmdg_name( ctx, obj, val );

This macro returns the value of the Name property of the menu module object as type text.

d2fmmdg_mnu_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the menu module object as type object.

d2fmmdg_obj_grp( ctx, obj, val );

This macro returns the value of the D2FP_OBJ_GRP property of the menu module object as type object.

d2fmmdg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the menu module object as type text.

d2fmmdg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the menu module object as type text.

d2fmmdg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the menu module object as type number.

d2fmmdg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the menu module object as type number.

d2fmmdg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the menu module object as type text.

d2fmmdg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the menu module object as type text.

d2fmmdg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the menu module object as type object.

d2fmmdg_prog_unit( ctx, obj, val );

This macro returns the value of the D2FP_PROG_UNIT property of the menu module object as type object.

d2fmmdg_prop_class( ctx, obj, val );

This macro returns the value of the Property Class property of the menu module object as type object.

d2fmmdg_role_count( ctx, obj, val );

This macro returns the value of the D2FP_ROLE_COUNT property of the menu module object as type number.

d2fmmdg_share_lib( ctx, obj, val );

This macro returns the value of the Share Library with Form property of the menu module object as type boolean.

d2fmmdg_short_nam( ctx, obj, val );

This macro returns the value of the Short name property of the menu module object as type text.

d2fmmdg_strtup_code( ctx, obj, val );

This macro returns the value of the Startup Code property of the menu module object as type text.

d2fmmdg_use_security( ctx, obj, val );

This macro returns the value of the Use Security property of the menu module object as type boolean.

d2fmmdg_vis_attr( ctx, obj, val );

This macro returns the value of the D2FP_VIS_ATTR property of the menu module object as type object.

d2fmmds_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the menu module object.

d2fmmds_comment( ctx, obj, val );

This macro sets the value of the Comments property of the menu module object.

d2fmmds_inhrt_sty( ctx, obj, val );

This macro sets the value of the D2FP_INHRT_STY property of the menu module object.

d2fmmds_main_mnu( ctx, obj, val );

This macro sets the value of the Main Menu property of the menu module object.

d2fmmds_menu( ctx, obj, val );

This macro sets the value of the D2FP_MENU property of the menu module object.

d2fmmds_mnu_description( ctx, obj, val );

This macro sets the value of the Menu Description property of the menu module object.

d2fmmds_mnu_drctry( ctx, obj, val );

This macro sets the value of the Menu Directory property of the menu module object.

d2fmmds_mnu_flnam( ctx, obj, val );

This macro sets the value of the Menu Filename property of the menu module object.

d2fmmds_mnu_param( ctx, obj, val );

This macro sets the value of the D2FP_MNU_PARAM property of the menu module object.

d2fmmds_name( ctx, obj, val );

This macro sets the value of the Name property of the menu module object.

d2fmmds_mnu_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the menu module object.

d2fmmds_obj_grp( ctx, obj, val );

This macro sets the value of the D2FP_OBJ_GRP property of the menu module object.

d2fmmds_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the menu module object.

d2fmmds_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the menu module object.

d2fmmds_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the menu module object.

d2fmmds_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the menu module object.

d2fmmds_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the menu module object.

d2fmmds_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the menu module object.

d2fmmds_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the menu module object.

d2fmmds_prog_unit( ctx, obj, val );

This macro sets the value of the D2FP_PROG_UNIT property of the menu module object.

d2fmmds_prop_class( ctx, obj, val );

This macro sets the value of the Property Class property of the menu module object.

d2fmmds_role_count( ctx, obj, val );

This macro sets the value of the D2FP_ROLE_COUNT property of the menu module object.

d2fmmds_share_lib( ctx, obj, val );

This macro sets the value of the Share Library with Form property of the menu module object.

d2fmmds_short_nam( ctx, obj, val );

This macro sets the value of the Short name property of the menu module object.

d2fmmds_strtup_code( ctx, obj, val );

This macro sets the value of the Startup Code property of the menu module object.

d2fmmds_use_security( ctx, obj, val );

This macro sets the value of the Use Security property of the menu module object.


Menu item object macros

  Related Topics

This section describes the macros of the Form Builder Open API Menu Item object.

d2fmnig_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the menu item object as a type dvoid pointer.

d2fmnig_com_txt( ctx, obj, val );

This macro returns the value of the Command Text property of the menu item object as type text.

d2fmnig_com_typ( ctx, obj, val );

This macro returns the value of the Command Type property of the menu item object as type number.

d2fmnig_comment( ctx, obj, val );

This macro returns the value of the Comments property of the menu item object as type text.

d2fmnig_disp_no_priv( ctx, obj, val );

This macro returns the value of the Display without Privileges property of the menu item object as type boolean.

d2fmnig_enabled( ctx, obj, val );

This macro returns the value of the Enabled property of the menu item object as type boolean.

d2fmnig_font_nam( ctx, obj, val );

This macro returns the value of the Font Name property of the menu item object as type text.

d2fmnig_font_siz( ctx, obj, val );

This macro returns the value of the Font Size property of the menu item object as type number.

d2fmnig_font_spcing( ctx, obj, val );

This macro returns the value of the Font Spacing property of the menu item object as type number.

d2fmnig_font_sty( ctx, obj, val );

This macro returns the value of the Font Style property of the menu item object as type number.

d2fmnig_font_wght( ctx, obj, val );

This macro returns the value of the Font Weight property of the menu item object as type number.

d2fmnig_hint( ctx, obj, val );

This macro returns the value of the Hint property of the menu item object as type text.

d2fmnig_hlp_description( ctx, obj, val );

This macro returns the value of the Help property of the menu item object as type text.

d2fmnig_icon_flnam( ctx, obj, val );

This macro returns the value of the Icon Filename property of the menu item object as type text.

d2fmnig_icon_in_mnu( ctx, obj, val );

This macro returns the value of the Iconic property of the menu item object as type boolean.

d2fmnig_kdrd_acc( ctx, obj, val );

This macro returns the value of the Keyboard Accelerator property of the menu item object as type text.

d2fmnig_label( ctx, obj, val );

This macro returns the value of the Label property of the menu item object as type text.

d2fmnig_magic_itm( ctx, obj, val );

This macro returns the value of the Magic Item property of the menu item object as type number.

d2fmnig_mnu_itm_code( ctx, obj, val );

This macro returns the value of the D2FP_MNU_ITM_CODE property of the menu item object as type text.

d2fmnig_mnu_itm_rad_grp( ctx, obj, val );

This macro returns the value of the Menu Item Radio Group property of the menu item object as type text.

d2fmnig_mnu_itm_typ( ctx, obj, val );

This macro returns the value of the Menu Item Type property of the menu item object as type number.

d2fmnig_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the menu item object as type object.

d2fmnig_name( ctx, obj, val );

This macro returns the value of the Name property of the menu item object as type text.

d2fmnig_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the menu item object as type object.

d2fmnig_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the menu item object as type object.

d2fmnig_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the menu item object as type text.

d2fmnig_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the menu item object as type text.

d2fmnig_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the menu item object as type number.

d2fmnig_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the menu item object as type number.

d2fmnig_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the menu item object as type text.

d2fmnig_par_num( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NUM property of the menu item object as type text.

d2fmnig_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the menu item object as type object.

d2fmnig_role_count( ctx, obj, val );

This macro returns the value of the D2FP_ROLE_COUNT property of the menu item object as type number.

d2fmnig_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the menu item object as type object.

d2fmnig_sub_mnu_nam( ctx, obj, val );

This macro returns the value of the D2FP_SUB_MNU_NAM property of the menu item object as type text.

d2fmnig_sub_mnu_obj( ctx, obj, val );

This macro returns the value of the D2FP_SUB_MNU_OBJ property of the menu item object as type object.

d2fmnig_vat_nam( ctx, obj, val );

This macro returns the value of the Visual Attribute Group property of the menu item object as type text.

d2fmnig_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_VAT_OBJ property of the menu item object as type object.

d2fmnig_visible( ctx, obj, val );

This macro returns the value of the Visible property of the menu item object as type boolean.

d2fmnig_vsbl_in_horz_mnu_tlbr( ctx, obj, val );

This macro returns the value of the Visible in Horizontal/Vertical Menu Toolbar property of the menu item object as type boolean.

d2fmnig_vsbl_in_menu( ctx, obj, val );

This macro returns the value of the Visible in Menu property of the menu item object as type boolean.

d2fmnig_vsbl_in_vert_mnu_tlbr( ctx, obj, val );

This macro returns the value of the Visible in Horizontal/Vertical Menu Toolbar property of the menu item object as type boolean.

d2fmnis_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the menu item object.

d2fmnis_com_txt( ctx, obj, val );

This macro sets the value of the Command Text property of the menu item object.

d2fmnis_com_typ( ctx, obj, val );

This macro sets the value of the Command Type property of the menu item object.

d2fmnis_comment( ctx, obj, val );

This macro sets the value of the Comments property of the menu item object.

d2fmnis_disp_no_priv( ctx, obj, val );

This macro sets the value of the Display without Privileges property of the menu item object.

d2fmnis_enabled( ctx, obj, val );

This macro sets the value of the Enabled property of the menu item object.

d2fmnis_font_nam( ctx, obj, val );

This macro sets the value of the Font Name property of the menu item object.

d2fmnis_font_siz( ctx, obj, val );

This macro sets the value of the Font Size property of the menu item object.

d2fmnis_font_spcing( ctx, obj, val );

This macro sets the value of the Font Spacing property of the menu item object.

d2fmnis_font_sty( ctx, obj, val );

This macro sets the value of the Font Style property of the menu item object.

d2fmnis_font_wght( ctx, obj, val );

This macro sets the value of the Font Weight property of the menu item object.

d2fmnis_hint( ctx, obj, val );

This macro sets the value of the Hint property of the menu item object.

d2fmnis_hlp_description( ctx, obj, val );

This macro sets the value of the Help property of the menu item object.

d2fmnis_icon_flnam( ctx, obj, val );

This macro sets the value of the Icon Filename property of the menu item object.

d2fmnis_icon_in_mnu( ctx, obj, val );

This macro sets the value of the Iconic property of the menu item object.

d2fmnis_kdrd_acc( ctx, obj, val );

This macro sets the value of the Keyboard Accelerator property of the menu item object.

d2fmnis_label( ctx, obj, val );

This macro sets the value of the Label property of the menu item object.

d2fmnis_magic_itm( ctx, obj, val );

This macro sets the value of the Magic Item property of the menu item object.

d2fmnis_mnu_itm_code( ctx, obj, val );

This macro sets the value of the D2FP_MNU_ITM_CODE property of the menu item object.

d2fmnis_mnu_itm_rad_grp( ctx, obj, val );

This macro sets the value of the Menu Item Radio Group property of the menu item object.

d2fmnis_mnu_itm_typ( ctx, obj, val );

This macro sets the value of the Menu Item Type property of the menu item object.

d2fmnis_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the menu item object.

d2fmnis_name( ctx, obj, val );

This macro sets the value of the Name property of the menu item object.

d2fmnis_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the menu item object.

d2fmnis_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the menu item object.

d2fmnis_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the menu item object.

d2fmnis_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the menu item object.

d2fmnis_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the menu item object.

d2fmnis_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the menu item object.

d2fmnis_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the menu item object.

d2fmnis_par_num( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NUM property of the menu item object.

d2fmnis_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the menu item object.

d2fmnis_role_count( ctx, obj, val );

This macro sets the value of the D2FP_ROLE_COUNT property of the menu item object.

d2fmnis_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the menu item object.

d2fmnis_sub_mnu_nam( ctx, obj, val );

This macro sets the value of the D2FP_SUB_MNU_NAM property of the menu item object.

d2fmnis_sub_mnu_obj( ctx, obj, val );

This macro sets the value of the D2FP_SUB_MNU_OBJ property of the menu item object.

d2fmnis_vat_nam( ctx, obj, val );

This macro sets the value of the Visual Attribute Group property of the menu item object.

d2fmnis_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_VAT_OBJ property of the menu item object.

d2fmnis_visible( ctx, obj, val );

This macro sets the value of the Visible property of the menu item object.

d2fmnis_vsbl_in_horz_mnu_tlbr( ctx, obj, val );

This macro sets the value of the Visible in Horizontal/Vertical Menu Toolbar property of the menu item object.

d2fmnis_vsbl_in_menu( ctx, obj, val );

This macro sets the value of the Visible in Menu property of the menu item object.

d2fmnis_vsbl_in_vert_mnu_tlbr( ctx, obj, val );

This macro sets the value of the Visible in Horizontal/Vertical Menu Toolbar property of the menu item object.


Menu parameter object macros

  Related Topics

This section describes the macros of the Form Builder Open API Menu Parameter object.

d2fmpmg_assoc_menus_count( ctx, obj, val );

This macro returns the value of the D2FP_ASSOC_MENUS_COUNT property of the menu parameter object as type number.

d2fmpmg_assoc_mnus( ctx, obj, val );

This macro returns the value of the Associated Menus property of the menu parameter object as type object.

d2fmpmg_case_rstrction( ctx, obj, val );

This macro returns the value of the Case Restriction property of the menu parameter object as type number.

d2fmpmg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the menu parameter object as a type dvoid pointer.

d2fmpmg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the menu parameter object as type text.

d2fmpmg_conceal_data( ctx, obj, val );

This macro returns the value of the Conceal Data property of the menu parameter object as type boolean.

d2fmpmg_fixed_len( ctx, obj, val );

This macro returns the value of the Fixed Length property of the menu parameter object as type boolean.

d2fmpmg_hint( ctx, obj, val );

This macro returns the value of the Hint property of the menu parameter object as type text.

d2fmpmg_label( ctx, obj, val );

This macro returns the value of the Label property of the menu parameter object as type text.

d2fmpmg_max_len( ctx, obj, val );

This macro returns the value of the Maximum Length property of the menu parameter object as type number.

d2fmpmg_mnu_param_init_val( ctx, obj, val );

This macro returns the value of the Menu parameter Initial Value property of the menu parameter object as type text.

d2fmpmg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the menu parameter object as type object.

d2fmpmg_name( ctx, obj, val );

This macro returns the value of the Name property of the menu parameter object as type text.

d2fmpmg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the menu parameter object as type object.

d2fmpmg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the menu parameter object as type object.

d2fmpmg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the menu parameter object as type text.

d2fmpmg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the menu parameter object as type text.

d2fmpmg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the menu parameter object as type number.

d2fmpmg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the menu parameter object as type number.

d2fmpmg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the menu parameter object as type text.

d2fmpmg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the menu parameter object as type text.

d2fmpmg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the menu parameter object as type object.

d2fmpmg_required( ctx, obj, val );

This macro returns the value of the D2FP_REQUIRED property of the menu parameter object as type boolean.

d2fmpmg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the menu parameter object as type object.

d2fmpms_assoc_mnus( ctx, obj, val );

This macro sets the value of the Associated Menus property of the menu parameter object.

d2fmpms_case_rstrction( ctx, obj, val );

This macro sets the value of the Case Restriction property of the menu parameter object.

d2fmpms_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the menu parameter object.

d2fmpms_comment( ctx, obj, val );

This macro sets the value of the Comments property of the menu parameter object.

d2fmpms_conceal_data( ctx, obj, val );

This macro sets the value of the Conceal Data property of the menu parameter object.

d2fmpms_fixed_len( ctx, obj, val );

This macro sets the value of the Fixed Length property of the menu parameter object.

d2fmpms_hint( ctx, obj, val );

This macro sets the value of the Hint property of the menu parameter object.

d2fmpms_label( ctx, obj, val );

This macro sets the value of the Label property of the menu parameter object.

d2fmpms_max_len( ctx, obj, val );

This macro sets the value of the Maximum Length property of the menu parameter object.

d2fmpms_mnu_param_init_val( ctx, obj, val );

This macro sets the value of the Menu parameter Initial Value property of the menu parameter object.

d2fmpms_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the menu parameter object.

d2fmpms_name( ctx, obj, val );

This macro sets the value of the Name property of the menu parameter object.

d2fmpms_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the menu parameter object.

d2fmpms_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the menu parameter object.

d2fmpms_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the menu parameter object.

d2fmpms_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the menu parameter object.

d2fmpms_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the menu parameter object.

d2fmpms_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the menu parameter object.

d2fmpms_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the menu parameter object.

d2fmpms_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the menu parameter object.

d2fmpms_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the menu parameter object.

d2fmpms_required( ctx, obj, val );

This macro sets the value of the D2FP_REQUIRED property of the menu parameter object.


Object (generic object) macros

  Related Topics

This section describes the macros of the Form Builder Open API Object (generic object).

d2fobg_access_key( ctx, obj, val );

This macro returns the value of the Access Key property of the object as type text.

d2fobg_activex_class( ctx, obj, val );

This macro returns the value of the D2FP_ACTIVEX_CLASS property of the object as type text.

d2fobg_acitvex_val_prop( ctx, obj, val );

This macro returns the value of the D2FP_ACTIVEX_VAL_PROP property of the object as type text.

d2fobg_alert( ctx, obj, val );

This macro returns the value of the D2FP_ALERT property of the object as type object.

d2fobg_allow_expansion( ctx, obj, val );

This macro returns the value of the Allow Expansion property of the object as type boolean.

d2fobg_allow_mlt_lin_prmpts( ctx, obj, val );

This macro returns the value of the Allow Multi-line Prompts property of the object as type boolean.

d2fobg_allow_strt_att_prmpts( ctx, obj, val );

This macro returns the value of the Allow Start-attached Prompts property of the object as type boolean.

d2fobg_allow_top_att_prpmts( ctx, obj, val );

This macro returns the value of the Allow Top-attached Prompts property of the object as type boolean.

d2fobg_alt_msg( ctx, obj, val );

This macro returns the value of the Message property of the object as type text.

d2fobg_alt_sty( ctx, obj, val );

This macro returns the value of the Alert Style property of the object as type number.

d2fobg_arrow_sty( ctx, obj, val );

This macro returns the value of the Line Arrow Style property of the object as type number.

d2fobg_menus_count( ctx, obj, val );

This macro returns the value of the D2FP_MENUS_COUNT property of the object as type number.

d2fobg_assoc_mnus( ctx, obj, val );

This macro returns the value of the Associated Menus property of the object as type object.

d2fobg_att_lib( ctx, obj, val );

This macro returns the value of the D2FP_ATT_LIB property of the object as type object.

d2fobg_audio_chnnls( ctx, obj, val );

This macro returns the value of the Audio Channels property of the object as type number.

d2fobg_auto_col_wid( ctx, obj, val );

This macro returns the value of the Automatic Column Width property of the object as type boolean.

d2fobg_auto_disp( ctx, obj, val );

This macro returns the value of the Automatic Display property of the object as type boolean.

d2fobg_auto_hint( ctx, obj, val );

This macro returns the value of the Display Hint Automatically property of the object as type boolean.

d2fobg_auto_pos( ctx, obj, val );

This macro returns the value of the Automatic Position property of the object as type boolean.

d2fobg_auto_qry( ctx, obj, val );

This macro returns the value of the Automatic Query property of the object as type boolean.

d2fobg_auto_rfrsh( ctx, obj, val );

This macro returns the value of the Automatic Refresh property of the object as type boolean.

d2fobg_auto_skp( ctx, obj, val );

This macro returns the value of the Automatic Skip property of the object as type boolean.

d2fobg_auto_slct( ctx, obj, val );

This macro returns the value of the Automatic Select property of the object as type boolean.

d2fobg_back_color( ctx, obj, val );

This macro returns the value of the Background Color property of the object as type text.

d2fobg_xxx( ctx, obj, val );

This macro returns the value of the XXX property of the object as type number.

d2fobg_bevel( ctx, obj, val );

This macro returns the value of the Bevel property of the object as type number.

d2fobg_blk_description( ctx, obj, val );

This macro returns the value of the D2FP_BLK_DESCRIPTION property of the object as type text.

d2fobg_block( ctx, obj, val );

This macro returns the value of the D2FP_BLOCK property of the object as type object.

d2fobg_bounding_bx_scalable( ctx, obj, val );

This macro returns the value of the D2FP_BOUNDING_BX_SCALABLE property of the object as type boolean

d2fobg_btm_ttl( ctx, obj, val );

This macro returns the value of the D2FP_BTM_TTL property of the object as type text

d2fobg_btn_1_lbl( ctx, obj, val );

This macro returns the value of the Button 1 Label property of the object as type text

d2fobg_btn_2_lbl( ctx, obj, val );

This macro returns the value of the Button 2 Label property of the object as type text

d2fobg_btn_3_lbl( ctx, obj, val );

This macro returns the value of the Button 3 Label property of the object as type text

d2fobg_calc_mode( ctx, obj, val );

This macro returns the value of the Calculation Mode property of the object as type number

d2fobg_canvas( ctx, obj, val );

This macro returns the value of the D2FP_CANVAS property of the object as type object

d2fobg_cap_sty( ctx, obj, val );

This macro returns the value of the Object Edge Cap Style property of the object as type number

d2fobg_case_insensitive_qry( ctx, obj, val );

This macro returns the value of the Case Insensitive Query property of the object as type boolean.

d2fobg_case_restriction( ctx, obj, val );

This macro returns the value of the Case Restriction property of the object as type number

d2fobg_chk_bx_other_vals( ctx, obj, val );

This macro returns the value of the Check Box Mapping of Other Values property of the object as type number

d2fobg_chked_val( ctx, obj, val );

This macro returns the value of the Checked property of the object as type text

d2fobg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the object as a type dvoid pointer.

d2fobg_clip_hgt( ctx, obj, val );

This macro returns the value of the Height of Clipping Rectangle property of the object as type number.

d2fobg_clip_wid( ctx, obj, val );

This macro returns the value of the Width of Clipping Rectangle property of the object as type number.

d2fobg_clip_x_pos( ctx, obj, val );

This macro returns the value of the X-origin of Clipping Rectangle property of the object as type number.

d2fobg_clip_y_pos( ctx, obj, val );

This macro returns the value of the Y-origin of Clipping Rectangle property of the object as type number.

d2fobg_closed( ctx, obj, val );

This macro returns the value of the Polygon Flag/Arc Closure property of the object as type boolean.

d2fobg_cls_allowed( ctx, obj, val );

This macro returns the value of the Close Allowed property of the object as type boolean.

d2fobg_cmprssion_qlty( ctx, obj, val );

This macro returns the value of the D2FP_CMPRSSION_QLTY property of the object as type number.

d2fobg_cnv_nam( ctx, obj, val );

This macro returns the value of the Canvas property of the object as type text.

d2fobg_cnv_obj( ctx, obj, val );

This macro returns the value of the D2FP_CNV_OBJ property of the object as type object.

d2fobg_cnv_typ( ctx, obj, val );

This macro returns the value of the Canvas Type property of the object as type number.

d2fobg_col_dat_typ( ctx, obj, val );

This macro returns the value of the D2FP_COL_DAT_TYP property of the object as type number.

d2fobg_col_map( ctx, obj, val );

This macro returns the value of the Column Mapping Properties property of the object as type object.

d2fobg_col_nam( ctx, obj, val );

This macro returns the value of the Column Name property of the object as type text.

d2fobg_col_spec( ctx, obj, val );

This macro returns the value of the Column Specifications property of the object as type object.

d2fobg_col_vals_count( ctx, obj, val );

This macro returns the value of the D2FP_COL_VALS_COUNT property of the object as type number.

d2fobg_com_txt( ctx, obj, val );

This macro returns the value of the Command Text property of the object as type text.

d2fobg_com_typ( ctx, obj, val );

This macro returns the value of the D2FP_COM_TYP property of the object as type number.

d2fobg_comm_mode( ctx, obj, val );

This macro returns the value of the Communication Mode property of the object as type number.

d2fobg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the object as type text.

d2fobg_compress( ctx, obj, val );

This macro returns the value of the Compress property of the object as type number.

d2fobg_conceal_data( ctx, obj, val );

This macro returns the value of the Conceal Data property of the object as type boolean.

d2fobg_console_win( ctx, obj, val );

This macro returns the value of the Console Window property of the object as type text.

d2fobg_copy_val_from_itm( ctx, obj, val );

This macro returns the value of the Copy Value From Item property of the object as type text.

d2fobg_corner_radius_x( ctx, obj, val );

This macro returns the value of the X-origin of Radius for Corner of Rounded Rectangle property of the object as type number.

d2fobg_corner_radius_y( ctx, obj, val );

This macro returns the value of the Y-origin of Radius for Corner of Rounded Rectangle property of the object as type number.

d2fobg_crsr_mode( ctx, obj, val );

This macro returns the value of the Cursor Mode property of the object as type number.

d2fobg_cstm_spcing( ctx, obj, val );

This macro returns the value of the Custom Spacing for Text Object property of the object as type number.

d2fobg_dash_sty( ctx, obj, val );

This macro returns the value of the Dash Style for Object Edge property of the object as type number.

d2fobg_dat_src_blk( ctx, obj, val );

This macro returns the value of the Data Source Block property of the object as type text.

d2fobg_dat_src_x_axs( ctx, obj, val );

This macro returns the value of the Data Source X Axis property of the object as type text.

d2fobg_dat_src_y_axs( ctx, obj, val );

This macro returns the value of the X-origin of Data Source Y Axis property of the object as type text.

d2fobg_dat_typ( ctx, obj, val );

This macro returns the value of the Data Type property of the object as type number.

d2fobg_db_blk( ctx, obj, val );

This macro returns the value of the Database Block property of the object as type boolean.

d2fobg_db_itm( ctx, obj, val );

This macro returns the value of the Database Item property of the object as type boolean.

d2fobg_defer_req_enf( ctx, obj, val );

This macro returns the value of the D2FP_DEFER_REQ_ENF property of the object as type boolean.

d2fobg_deferred( ctx, obj, val );

This macro returns the value of the Deferred property of the object as type boolean.

d2fobg_del_allowed( ctx, obj, val );

This macro returns the value of the Delete Allowed property of the object as type boolean.

d2fobg_del_proc_nam( ctx, obj, val );

This macro returns the value of the Delete Procedure Name property of the object as type text.

d2fobg_del_rec( ctx, obj, val );

This macro returns the value of the Delete Record Behavior property of the object as type number.

d2fobg_detail_blk( ctx, obj, val );

This macro returns the value of the Detail Block property of the object as type text.

d2fobg_dflt_alt_btn( ctx, obj, val );

This macro returns the value of the Default Alert Button property of the object as type number.

d2fobg_dflt_btn( ctx, obj, val );

This macro returns the value of the Default Button property of the object as type boolean.

d2fobg_disp_in_kbrd_hlp( ctx, obj, val );

This macro returns the value of the Display in Keyboard Help property of the object as type boolean.

d2fobg_disp_no_priv( ctx, obj, val );

This macro returns the value of the Display without Privilege property of the object as type boolean.

d2fobg_disp_qlty( ctx, obj, val );

This macro returns the value of the Display Quality property of the object as type number.

d2fobg_disp_wid( ctx, obj, val );

This macro returns the value of the Display Width property of the object as type number.

d2fobg_dist_bwwn_recs( ctx, obj, val );

This macro returns the value of the Distance Between Records property of the object as type number.

d2fobg_dither( ctx, obj, val );

This macro returns the value of the Graphics Dither Image property of the object as type boolean.

d2fobg_dml_ary_siz( ctx, obj, val );

This macro returns the value of the DML Array Size property of the object as type number.

d2fobg_dml_dat_nam( ctx, obj, val );

This macro returns the value of the DML Data Target Name property of the object as type text.

d2fobg_dml_dat_typ( ctx, obj, val );

This macro returns the value of the DML Data Target Type property of the object as type number.

d2fobg_dsa_mode( ctx, obj, val );

This macro returns the value of the D2FP_DSA_MODE property of the object as type number.

d2fobg_dsa_nam( ctx, obj, val );

This macro returns the value of the D2FP_DSA_NAM property of the object as type text.

d2fobg_dsa_typ( ctx, obj, val );

This macro returns the value of the D2FP_DSA_TYPE property of the object as type number.

d2fobg_dsa_typ_nam( ctx, obj, val );

This macro returns the value of the D2FP_DSA_TYP_NAM property of the object as type text.

d2fobg_dsa_val( ctx, obj, val );

This macro returns the value of the D2FP_DSA_VAL property of the object as type text.

d2fobg_dsc_len( ctx, obj, val );

This macro returns the value of the D2FP_DSC_LEN property of the object as type number.

d2fobg_dsc_mandatory( ctx, obj, val );

This macro returns the value of the D2FP_DSC_MANDATORY property of the object as type boolean.

d2fobg_dsc_nam( ctx, obj, val );

This macro returns the value of the D2FP_DSC_NAM property of the object as type text.

d2fobg_dsc_precision( ctx, obj, val );

This macro returns the value of the D2FP_DSC_PRECISION property of the object as type number.

d2fobg_dsc_scale( ctx, obj, val );

This macro returns the value of the D2FP_DSC_SCALE property of the object as type number.

d2fobg_dsc_typ( ctx, obj, val );

This macro returns the value of the D2FP_DSC_TYP property of the object as type number.

d2fobg_edge_back_color( ctx, obj, val );

This macro returns the value of the Object Edge Background Color property of the object as type text.

d2fobg_edge_fore_color( ctx, obj, val );

This macro returns the value of the Object Edge Foreground Color property of the object as type text.

d2fobg_editor( ctx, obj, val );

This macro returns the value of the Editor property of the object as type object.

d2fobg_edt_nam( ctx, obj, val );

This macro returns the value of the Editor Name property of the object as type text.

d2fobg_edt_obj( ctx, obj, val );

This macro returns the value of the D2FP_EDT_OBJ property of the object as type object.

d2fobg_edt_x_pos( ctx, obj, val );

This macro returns the value of the Editor X Position/Editor Y Position property of the object as type number.

d2fobg_edt_y_pos( ctx, obj, val );

This macro returns the value of the Editor X Position/Editor Y Position property of the object as type number.

d2fobg_enabled( ctx, obj, val );

This macro returns the value of the Enabled property of the object as type boolean.

d2fobg_enfrc_col_security( ctx, obj, val );

This macro returns the value of the Enforce Column Security property of the object as type boolean.

d2fobg_enfrc_prmry_key( ctx, obj, val );

This macro returns the value of the Enforce Primary Key property of the object as type boolean.

d2fobg_exec_hierarchy( ctx, obj, val );

This macro returns the value of the Executive Style property of the object as type number.

d2fobg_exec_mode( ctx, obj, val );

This macro returns the value of the Executive Mode property of the object as type number.

d2fobg_fill_pat( ctx, obj, val );

This macro returns the value of the Fill Pattern property of the object as type text.

d2fobg_fire_in_qry( ctx, obj, val );

This macro returns the value of the Fire in Enter-query Mode property of the object as type boolean.

d2fobg_fixed_bounding_bx( ctx, obj, val );

This macro returns the value of the Fixed Size of Object Bounding Box property of the object as type boolean.

d2fobg_fixed_len( ctx, obj, val );

This macro returns the value of the Fixed Length property of the object as type boolean.

d2fobg_flnam( ctx, obj, val );

This macro returns the value of the File Name property of the object as type text.

d2fobg_fltr_before_disp( ctx, obj, val );

This macro returns the value of the Filter Before Display property of the object as type boolean.

d2fobg_fmt_msk( ctx, obj, val );

This macro returns the value of the Format Mask property of the object as type text.

d2fobg_font_nam( ctx, obj, val );

This macro returns the value of the Font Name property of the object as type text.

d2fobg_font_scaleable( ctx, obj, val );

This macro returns the value of the Point Size Scales with Object property of the object as type boolean.

d2fobg_font_siz( ctx, obj, val );

This macro returns the value of the Font Size property of the object as type number.

d2fobg_font_spcing( ctx, obj, val );

This macro returns the value of the Font Spacing property of the object as type number.

d2fobg_font_sty( ctx, obj, val );

This macro returns the value of the Font Style property of the object as type number.

d2fobg_font_wght( ctx, obj, val );

This macro returns the value of the XXX property of the object as type number.

d2fobg_fore_color( ctx, obj, val );

This macro returns the value of the Font Color property of the object as type text.

d2fobg_form_param( ctx, obj, val );

This macro returns the value of the D2FP_FORM_PARAM property of the object as type object.

d2fobg_formula( ctx, obj, val );

This macro returns the value of the Formula property of the object as type text.

d2fobg_frame_align( ctx, obj, val );

This macro returns the value of the Frame Alignment property of the object as type number.

d2fobg_frame_ttl( ctx, obj, val );

This macro returns the value of the Frame Title property of the object as type text.

d2fobg_frame_ttl_align( ctx, obj, val );

This macro returns the value of the Frame Title Alignment property of the object as type number.

d2fobg_frame_ttl_back_color( ctx, obj, val );

This macro returns the value of the Frame Title Background Color property of the object as type text.

d2fobg_frame_ttl_fill_pat( ctx, obj, val );

This macro returns the value of the Frame Title Fill Pattern property of the object as type text.

d2fobg_frame_ttl_font_nam( ctx, obj, val );

This macro returns the value of the Frame Title Font Name property of the object as type text.

d2fobg_frame_ttl_font_siz( ctx, obj, val );

This macro returns the value of the Frame Title Font Size property of the object as type number.

d2fobg_frame_ttl_font_spcing( ctx, obj, val );

This macro returns the value of the Frame Title Font Spacing property of the object as type number.

d2fobg_frame_ttl_font_sty( ctx, obj, val );

This macro returns the value of the Frame Title Font Style property of the object as type number.

d2fobg_frame_ttl_font_wght( ctx, obj, val );

This macro returns the value of the Frame Title Font Weight property of the object as type number.

d2fobg_frame_ttl_fore_color( ctx, obj, val );

This macro returns the value of the Frame Title Foreground Color property of the object as type text.

d2fobg_frame_ttl_ofst( ctx, obj, val );

This macro returns the value of the Frame Title Offset property of the object as type number.

d2fobg_frame_ttl_spcing( ctx, obj, val );

This macro returns the value of the Frame Title Spacing property of the object as type number.

d2fobg_frame_ttl_vat_nam( ctx, obj, val );

This macro returns the value of the Frame Title Visual Attribute Group property of the object as type text.

d2fobg_frame_ttl_val_obj( ctx, obj, val );

This macro returns the value of the D2FP_FRAME_TTL_VAL_OBJ property of the object as type object.

d2fobg_frst_navigation_blk_nam( ctx, obj, val );

This macro returns the value of the First Navigation Block property of the object as type text.

d2fobg_frst_navigation_blk_obj( ctx, obj, val );

This macro returns the value of the D2FP_FRST_NAVIGATION_BLK_OBJ property of the object as type object.

d2fobg_gra_font_nam( ctx, obj, val );

This macro returns the value of the Graphics Font Name property of the object as type text.

d2fobg_gra_font_siz( ctx, obj, val );

This macro returns the value of the Graphics Font Size property of the object as type number.

d2fobg_gra_font_sty( ctx, obj, val );

This macro returns the value of the Graphics Font Style property of the object as type number.

d2fobg_gra_text( ctx, obj, val );

This macro returns the value of the Graphics Text property of the object as type text.

d2fobg_graphic( ctx, obj, val );

This macro returns the value of the D2FP_GRAPHIC property of the object as type object.

d2fobg_graphics_typ( ctx, obj, val );

This macro returns the value of the Graphics Object Type property of the object as type number.

d2fobg_height( ctx, obj, val );

This macro returns the value of the Width/Height property of the object as type number.

d2fobg_hide_on_exit( ctx, obj, val );

This macro returns the value of the Hide on Exit property of the object as type number.

d2fobg_highest_allowed_val( ctx, obj, val );

This macro returns the value of the Highest Allowed Value/Lowest Allowed Value property of the object as type text.

d2fobg_hint( ctx, obj, val );

This macro returns the value of the Hint property of the object as type text.

d2fobg_hlp_description( ctx, obj, val );

This macro returns the value of the Help property of the object as type text.

d2fobg_horz_jst( ctx, obj, val );

This macro returns the value of the Horizontal Justification of Text Object property of the object as type number.

d2fobg_horz_margn( ctx, obj, val );

This macro returns the value of the Horizontal Margin property of the object as type number.

d2fobg_horz_obj_ofst( ctx, obj, val );

This macro returns the value of the Horizontal Object Offset property of the object as type number.

d2fobg_horz_orgn( ctx, obj, val );

This macro returns the value of the Horizontal Position Relative to Origin property of the object as type number.

d2fobg_horz_tlbr_cnv( ctx, obj, val );

This macro returns the value of the Horizontal Toolbar Canvas property of the object as type text.

d2fobg_htb_cnv_name( ctx, obj, val );

This macro returns the value of the D2FP_HTB_CNV_NAME property of the object as type text.

d2fobg_icon_flnam( ctx, obj, val );

This macro returns the value of the Icon Filename property of the object as type text.

d2fobg_icon_in_mnu( ctx, obj, val );

This macro returns the value of the D2FO_ICON_IN_MNU property of the object as type boolean.

d2fobg_iconic( ctx, obj, val );

This macro returns the value of the Iconic property of the object as type boolean.

d2fobg_img_dpth( ctx, obj, val );

This macro returns the value of the Image Depth property of the object as type number.

d2fobg_img_fmt( ctx, obj, val );

This macro returns the value of the Image Format property of the object as type number.

d2fobg_inhrt_mnu( ctx, obj, val );

This macro returns the value of the Inherit Menu property of the object as type boolean.

d2fobg_inhrt_sty( ctx, obj, val );

This macro returns the value of the Inherit Style property of the object as type number.

d2fobg_init_kgrd_dir( ctx, obj, val );

This macro returns the value of the Initial Keyboard Direction property of the object as type number.

d2fobg_init_menu( ctx, obj, val );

This macro returns the value of the Initial Menu property of the object as type text.

d2fobg_init_val( ctx, obj, val );

This macro returns the value of the Initial Value property of the object as type text.

d2fobg_insrt_allowed( ctx, obj, val );

This macro returns the value of the Insert Allowed property of the object as type boolean.

d2fobg_insrt_proc_nam( ctx, obj, val );

This macro returns the value of the Insert Procedure Name property of the object as type text.

d2fobg_interaction_mode( ctx, obj, val );

This macro returns the value of the Interaction Mode property of the object as type number.

d2fobg_internal_end_angle( ctx, obj, val );

This macro returns the value of the D2FP_INTERNAL_END_ANGLE property of the object as type number.

d2fobg_internal_lin_wid( ctx, obj, val );

This macro returns the value of the D2FP_INTERNAL_LIN_WID property of the object as type number.

d2fobg_internal_rotation_angle( ctx, obj, val );

This macro returns the value of the D2FP_INTERNAL_ROTATION_ANGLE property of the object as type number.

d2fobg_internal_strt_angle( ctx, obj, val );

This macro returns the value of the D2FP_INTERNAL_STRT_ANGLE property of the object as type number.

d2fobg_isolation_mode( ctx, obj, val );

This macro returns the value of the Isolation Mode property of the object as type number.

d2fobg_item( ctx, obj, val );

This macro returns the value of the D2FP_ITEM property of the object as type object.

d2fobg_itm_typ( ctx, obj, val );

This macro returns the value of the Item Type property of the object as type number.

d2fobg_itms_disp( ctx, obj, val );

This macro returns the value of the Number of Items Displayed property of the object as type number.

d2fobg_join_cond( ctx, obj, val );

This macro returns the value of the Join Condition property of the object as type text.

d2fobg_join_sty( ctx, obj, val );

This macro returns the value of the Join Style of Objects Edge property of the object as type number.

d2fobg_justification( ctx, obj, val );

This macro returns the value of the Justification property of the object as type number.

d2fobg_kbrd_acc( ctx, obj, val );

This macro returns the value of the Keyboard Accelerator property of the object as type text.

d2fobg_kbrd_hlp_txt( ctx, obj, val );

This macro returns the value of the Keyboard Help Description property of the object as type text.

d2fobg_kbrd_navigable( ctx, obj, val );

This macro returns the value of the Keyboard Navigable property of the object as type boolean.

d2fobg_kbrd_state( ctx, obj, val );

This macro returns the value of the Keyboard State property of the object as type number.

d2fobg_keep_crsr_pos( ctx, obj, val );

This macro returns the value of the Keep Cursor Position property of the object as type boolean.

d2fobg_key_mode( ctx, obj, val );

This macro returns the value of the Key Mode property of the object as type number.

d2fobg_label( ctx, obj, val );

This macro returns the value of the Label property of the object as type text.

d2fobg_lang_dir( ctx, obj, val );

This macro returns the value of the Language Direction property of the object as type number.

d2fobg_layout_data_blk_nam( ctx, obj, val );

This macro returns the value of the Layout Data Block property of the object as type text.

d2fobg_layout_sty( ctx, obj, val );

This macro returns the value of the Layout Style property of the object as type number.

d2fobg_lib_loc( ctx, obj, val );

This macro returns the value of the PL/SQL Library Location property of the object as type text.

d2fobg_lib_src( ctx, obj, val );

This macro returns the value of the PL/SQL Library Source property of the object as type number.

d2fobg_lin_spcing( ctx, obj, val );

This macro returns the value of the Line Spacing property of the object as type number.

d2fobg_lock_mode( ctx, obj, val );

This macro returns the value of the Locking Mode property of the object as type number.

d2fobg_lock_proc_nam( ctx, obj, val );

This macro returns the value of the Lock Procedure Name property of the object as type text.

d2fobg_lock_rec( ctx, obj, val );

This macro returns the value of the Lock Record property of the object as type boolean.

d2fobg_lov( ctx, obj, val );

This macro returns the value of the List of Values property of the object as type object.

d2fobg_lov_nam( ctx, obj, val );

This macro returns the value of the D2FP_LOV_NAM property of the object as type text.

d2fobg_lov_obj( ctx, obj, val );

This macro returns the value of the D2FP_LOV_OBJ property of the object as type object.

d2fobg_lov_x_pos( ctx, obj, val );

This macro returns the value of the List X Position property of the object as type number.

d2fobg_lov_y_pos( ctx, obj, val );

This macro returns the value of the List Y Position property of the object as type number.

d2fobg_lowest_allowed_val( ctx, obj, val );

This macro returns the value of the Highest Allowed Value/Lowest Allowed Value property of the object as type text.

d2fobg_lst_element_count( ctx, obj, val );

This macro returns the value of the List Element Count property of the object as type number.

d2fobg_lst_in_blk_mnu( ctx, obj, val );

This macro returns the value of the Listed in Block Menu property of the object as type boolean.

d2fobg_lst_sty( ctx, obj, val );

This macro returns the value of the List Style property of the object as type number.

d2fobg_lst_typ( ctx, obj, val );

This macro returns the value of the List Type property of the object as type number.

d2fobg_magic_itm( ctx, obj, val );

This macro returns the value of the Magic Item property of the object as type number.

d2fobg_main_mnu( ctx, obj, val );

This macro returns the value of the Main Menu property of the object as type text.

d2fobg_max_len( ctx, obj, val );

This macro returns the value of the Maximum Length property of the object as type number.

d2fobg_max_objs( ctx, obj, val );

This macro returns the value of the Maximum Objects Per Line property of the object as type number.

d2fobg_max_qry_time( ctx, obj, val );

This macro returns the value of the Maximum Query Time property of the object as type number.

d2fobg_max_recs_fetched( ctx, obj, val );

This macro returns the value of the Maximum Records Fetched property of the object as type number.

d2fobg_maximize_allowed( ctx, obj, val );

This macro returns the value of the Maximize Allowed property of the object as type boolean.

d2fobg_menu( ctx, obj, val );

This macro returns the value of the D2FP_MENU property of the object as type object.

d2fobg_minimize_allowed( ctx, obj, val );

This macro returns the value of the Minimized Allowed property of the object as type boolean.

d2fobg_minimize_ttl( ctx, obj, val );

This macro returns the value of the Minimize Title property of the object as type text.

d2fobg_mlt_lin( ctx, obj, val );

This macro returns the value of the Multi-line property of the object as type boolean.

d2fobg_mnu_description( ctx, obj, val );

This macro returns the value of the Menu Description property of the object as type text.

d2fobg_mnu_drctry( ctx, obj, val );

This macro returns the value of the Menu Directory property of the object as type text.

d2fobg_mnu_flnam( ctx, obj, val );

This macro returns the value of the Menu Filename property of the object as type text.

d2fobg_mnu_itm( ctx, obj, val );

This macro returns the value of the Menu Item Type property of the object as type object.

d2fobg_mnu_itm_code( ctx, obj, val );

This macro returns the value of the D2FP_MNU_ITM_CODE property of the object as type text.

d2fobg_mnu_itm_rad_grp( ctx, obj, val );

This macro returns the value of the Menu Item Radio Group property of the object as type text.

d2fobg_mnu_itm_typ( ctx, obj, val );

This macro returns the value of the Menu Item Type property of the object as type number.

d2fobg_mnu_mod( ctx, obj, val );

This macro returns the value of the Menu Module property of the object as type text.

d2fobg_mnu_param( ctx, obj, val );

This macro returns the value of the D2FP_MNU_PARAM property of the object as type object.

d2fobg_mnu_param_init_val( ctx, obj, val );

This macro returns the value of the Menu Parameter Initial Value property of the object as type text.

d2fobg_mnu_role( ctx, obj, val );

This macro returns the value of the Menu Module Role property of the object as type text.

d2fobg_mnu_src( ctx, obj, val );

This macro returns the value of the Menu Source property of the object as type number.

d2fobg_mnu_sty( ctx, obj, val );

This macro returns the value of the Menu Style property of the object as type number.

d2fobg_modal( ctx, obj, val );

This macro returns the value of the Modal property of the object as type boolean.

d2fobg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the object as type object.

d2fobg_mouse_navigate( ctx, obj, val );

This macro returns the value of the Mouse Navigate property of the object as type boolean.

d2fobg_mouse_navigation_lmt( ctx, obj, val );

This macro returns the value of the Mouse Navigation Limit property of the object as type number.

d2fobg_mv_allowed( ctx, obj, val );

This macro returns the value of the Move Allowed property of the object as type boolean.

d2fobg_name( ctx, obj, val );

This macro returns the value of the Name property of the object as type text.

d2fobg_navigation_sty( ctx, obj, val );

This macro returns the value of the Navigation Style property of the object as type number.

d2fobg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the object as type object.

d2fobg_nxt_navigation_blk_nam( ctx, obj, val );

This macro returns the value of the D2FP_NXT_NAVIGATION_BLK_NAM property of the object as type text.

d2fobg_nxt_navigation_blk_obj( ctx, obj, val );

This macro returns the value of the D2FP_NXT_NAVIGATION_BLK_OBJ property of the object as type object.

d2fobg_nxt_navigation_itm_nam( ctx, obj, val );

This macro returns the value of the D2FP_NXT_NAVIGATION_ITM_NAM property of the object as type text.

d2fobg_nxt_navigation_itm_obj( ctx, obj, val );

This macro returns the value of the D2FP_NXT_NAVIGATION_ITM_OBJ property of the object as type object.

d2fobg_obj_grp( ctx, obj, val );

This macro returns the value of the D2FP_OBJ_GRP property of the object as type object.

d2fobg_obj_grp_child_real_obj( ctx, obj, val );

This macro returns the value of the D2FP_OBJ_GRP_CHILD_REAL_OBJ property of the object as type object.

d2fobg_og_child( ctx, obj, val );

This macro returns the value of the D2FP_OG_CHILD property of the object as type object.

d2fobg_old_lov_txt( ctx, obj, val );

This macro returns the value of the Old LOV Text property of the object as type text.

d2fobg_ole_act_sty( ctx, obj, val );

This macro returns the value of the LOE Activation Style property of the object as type number.

d2fobg_ole_class( ctx, obj, val );

This macro returns the value of the OLE Class property of the object as type text.

d2fobg_ole_in_place_act( ctx, obj, val );

This macro returns the value of the OLE In-place Activation property of the object as type boolean.

d2fobg_ole_insd_out_support( ctx, obj, val );

This macro returns the value of the OLE Inside-out Support property of the object as type boolean.

d2fobg_ole_popup_mnu_itms( ctx, obj, val );

This macro returns the value of the OLE Popup Menu Items property of the object as type number.

d2fobg_ole_resiz_sty( ctx, obj, val );

This macro returns the value of the OLE Resize Style property of the object as type number.

d2fobg_ole_show_popup_mnu( ctx, obj, val );

This macro returns the value of the OLE Show Popup Menu property of the object as type boolean.

d2fobg_ole_show_tnnt_typ( ctx, obj, val );

This macro returns the value of the Show OLE Tenant Type property of the object as type boolean.

d2fobg_ole_tnnt_aspct( ctx, obj, val );

This macro returns the value of the OLE Tenant Aspect property of the object as type number.

d2fobg_ole_tnnt_typ( ctx, obj, val );

This macro returns the value of the OLE Tenant Types property of the object as type number.

d2fobg_opt_hint( ctx, obj, val );

This macro returns the value of the Optimizer Hint property of the object as type text.

d2fobg_ordr_by_clause( ctx, obj, val );

This macro returns the value of the Order By Clause property of the object as type text.

d2fobg_other_vals( ctx, obj, val );

This macro returns the value of the Mapping of Other Values property of the object as type text.

d2fobg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the object as type object.

d2fobg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the object as type text.

d2fobg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the object as type text.

d2fobg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the object as type number.

d2fobg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the object as type number.

d2fobg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the object as type text.

d2fobg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the object as type text.

d2fobg_param_dat_typ( ctx, obj, val );

This macro returns the value of the Parameter Data Type property of the object as type number.

d2fobg_param_init_val( ctx, obj, val );

This macro returns the value of the Parameter Initial Value property of the object as type text.

d2fobg_pgu_txt( ctx, obj, val );

This macro returns the value of the D2FP_PGU_TEXT property of the object as type text.

d2fobg_popup_mnu_nam( ctx, obj, val );

This macro returns the value of the D2FP_POPUP_MNU_NAM property of the object as type text.

d2fobg_popup_mnu_obj( ctx, obj, val );

This macro returns the value of the D2FP_POPUP_MNU_OBJ property of the object as type text.

d2fobg_popup_va_obj( ctx, obj, val );

This macro returns the value of the D2FP_POPUP_VA_OBJ property of the object as type object.

d2fobg_precomp_summ( ctx, obj, val );

This macro returns the value of the D2FP_PRECOMP_SUMM property of the object as type boolean.

d2fobg_prev_navigation_blk_nam( ctx, obj, val );

This macro returns the value of the Previous Navigation Block property of the object as type text.

d2fobg_prev_navigation_blk_obj( ctx, obj, val );

This macro returns the value of the D2FP_PREV_NAVIGATION_BLK_OBJ property of the object as type object.

d2fobg_prev_navigation_itm_nam( ctx, obj, val );

This macro returns the value of the Previous Navigation Item Name property of the object as type text.

d2fobg_prev_navigation_itm_obj( ctx, obj, val );

This macro returns the value of the D2FP_PREV_NAVIGATION_ITM_OBJ property of the object as type object.

d2fobg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the object as type object.

d2fobg_prmpt( ctx, obj, val );

This macro returns the value of the Prompt property of the object as type text.

d2fobg_prmpt_align( ctx, obj, val );

This macro returns the value of the Prompt Alignment property of the object as type number.

d2fobg_prmpt_align_ofst( ctx, obj, val );

This macro returns the value of the Prompt Alignment Offset property of the object as type number.

d2fobg_prmpt_att_edge( ctx, obj, val );

This macro returns the value of the Prompt Attachment Edge property of the object as type number.

d2fobg_prmpt_att_ofst( ctx, obj, val );

This macro returns the value of the Prompt Attachment Offset property of the object as type number.

d2fobg_prmpt_back_color( ctx, obj, val );

This macro returns the value of the Prompt Background Color property of the object as type text.

d2fobg_prmpt_disp_sty( ctx, obj, val );

This macro returns the value of the Prompt Display Style property of the object as type number.

d2fobg_prmpt_fill_pat( ctx, obj, val );

This macro returns the value of the Prompt Fill Pattern property of the object as type text.

d2fobg_prmpt_font_nam( ctx, obj, val );

This macro returns the value of the Prompt Font Name property of the object as type text.

d2fobg_prmpt_font_siz( ctx, obj, val );

This macro returns the value of the Prompt Font Size property of the object as type number.

d2fobg_prmpt_font_spcing( ctx, obj, val );

This macro returns the value of the Prompt Font Spacing property of the object as type number.

d2fobg_prompt_font_sty( ctx, obj, val );

This macro returns the value of the Prompt Font Style property of the object as type number.

d2fobg_prmpt_font_wght( ctx, obj, val );

This macro returns the value of the Prompt Font Weight property of the object as type number.

d2fobg_prmpt_fore_color( ctx, obj, val );

This macro returns the value of the Prompt Foreground Color property of the object as type text.

d2fobg_prmpt_jst( ctx, obj, val );

This macro returns the value of the Prompt Justification property of the object as type number.

d2fobg_prmpt_reading_ordr( ctx, obj, val );

This macro returns the value of the Prompt Reading Order property of the object as type number.

d2fobg_prmpt_vat_nam( ctx, obj, val );

This macro returns the value of the Prompt Visual Attribute Group property of the object as type text.

d2fobg_prmpt_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_VAT_OBJ property of the object as type object.

d2fobg_prmry_cnv( ctx, obj, val );

This macro returns the value of the Primary Canvas property of the object as type text.

d2fobg_prmry_key( ctx, obj, val );

This macro returns the value of the Primary Key property of the object as type boolean.

d2fobg_prog_unit( ctx, obj, val );

This macro returns the value of the D2FP_PROG_UNIT property of the object as type object.

d2fobg_prop_class( ctx, obj, val );

This macro returns the value of the Property Class property of the object as type object.

d2fobg_prvnt_mstrless_ops( ctx, obj, val );

This macro returns the value of the Prevent Masterless Operations property of the object as type boolean.

d2fobg_qry_all_recs( ctx, obj, val );

This macro returns the value of the Query All Records property of the object as type boolean.

d2fobg_qry_allowed( ctx, obj, val );

This macro returns the value of the Query Allowed property of the object as type boolean.

d2fobg_qry_dat_src_nam( ctx, obj, val );

This macro returns the value of the Query Data Source Name property of the object as type text.

d2fobg_qry_dat_src_type( ctx, obj, val );

This macro returns the value of the Query Data Source Type property of the object as type number.

d2fobg_qry_len( ctx, obj, val );

This macro returns the value of the Query Length property of the object as type number.

d2fobg_qry_only( ctx, obj, val );

This macro returns the value of the Query Only property of the object as type boolean.

d2fobg_rad_but( ctx, obj, val );

This macro returns the value of the D2FP_RAD_BUT property of the object as type object.

d2fobg_raise_on_entry( ctx, obj, val );

This macro returns the value of the Raise On Entry property of the object as type boolean.

d2fobg_rdb_val( ctx, obj, val );

This macro returns the value of the Radio Button Value property of the object as type text.

d2fobg_reading_ordr( ctx, obj, val );

This macro returns the value of the Reading Order property of the object as type number.

d2fobg_rec_grp( ctx, obj, val );

This macro returns the value of the Record Group property of the object as type object.

d2fobg_rec_grp_fetch_siz( ctx, obj, val );

This macro returns the value of the D2FP_REC_GRP_FETCH_SIZ property of the object as type number.

d2fobg_rec_grp_nam( ctx, obj, val );

This macro returns the value of the Record Group property of the object as type text.

d2fobg_rec_grp_obj( ctx, obj, val );

This macro returns the value of the D2FP_REC_GRP_OBJ property of the object as type object.

d2fobg_rec_grp_qry( ctx, obj, val );

This macro returns the value of the Record Group Query property of the object as type text.

d2fobg_rec_grp_typ( ctx, obj, val );

This macro returns the value of the Record Group Type property of the object as type number.

d2fobg_rec_ornt( ctx, obj, val );

This macro returns the value of the Record Orientation property of the object as type number.

d2fobg_rec_vat_grp_nam( ctx, obj, val );

This macro returns the value of the Current Record Visual Attribute Group property of the object as type text.

d2fobg_rec_vat_grp_obj( ctx, obj, val );

This macro returns the value of the D2FP_REC_VAT_GRP_OBJ property of the object as type object.

d2fobg_recs_buffered_count( ctx, obj, val );

This macro returns the value of the Number of Records Buffered property of the object as type number.

d2fobg_recs_disp_count( ctx, obj, val );

This macro returns the value of the Number of Records Displayed property of the object as type number.

d2fobg_recs_fetched_count( ctx, obj, val );

This macro returns the value of the Records to Fetch property of the object as type number.

d2fobg_rel( ctx, obj, val );

This macro returns the value of the D2FP_REL property of the object as type object.

d2fobg_rendered( ctx, obj, val );

This macro returns the value of the Rendered property of the object as type boolean.

d2fobg_report( ctx, obj, val );

This macro returns the value of the D2FP_REPORT property of the object as type object.

d2fobg_required( ctx, obj, val );

This macro returns the value of the Required property of the object as type boolean.

d2fobg_resize_allowed( ctx, obj, val );

This macro returns the value of the Resize Allowed property of the object as type boolean.

d2fobg_rev_dir( ctx, obj, val );

This macro returns the value of the Reverse Direction property of the object as type boolean.

d2fobg_rpt_destination_fmt( ctx, obj, val );

This macro returns the value of the Report Destination Format property of the object as type text.

d2fobg_rpt_destination_nam( ctx, obj, val );

This macro returns the value of the Report Destination Name property of the object as type text.

d2fobg_rpt_destination_typ( ctx, obj, val );

This macro returns the value of the Report Destination Type property of the object as type number.

d2fobg_rpt_params( ctx, obj, val );

This macro returns the value of the Other Reports Parameters property of the object as type text.

d2fobg_rpt_srvr( ctx, obj, val );

This macro returns the value of the Report Server property of the object as type text.

d2fobg_rtrn_itm( ctx, obj, val );

This macro returns the value of the Return Item property of the object as type text.

d2fobg_runtime_comp( ctx, obj, val );

This macro returns the value of the D2FP_RUNTIME_COMP property of the object as type number.

d2fobg_scrlbr_align( ctx, obj, val );

This macro returns the value of the Scroll Bar Alignment property of the object as type number.

d2fobg_scrlbr_cnv_nam( ctx, obj, val );

This macro returns the value of the Scroll Bar Canvas property of the object as type text.

d2fobg_scrlbr_cnv_obj( ctx, obj, val );

This macro returns the value of the D2FP_SCRLBR_CNV_OBJ property of the object as type object.

d2fobg_scrlbr_hgt( ctx, obj, val );

This macro returns the value of the Scroll Bar Height property of the object as type number.

d2fobg_scrlbr_ornt( ctx, obj, val );

This macro returns the value of the Scroll Bar Orientation property of the object as type number.

d2fobg_scrlbr_tbp_nam( ctx, obj, val );

This macro returns the value of the Scroll Bar Tab Page property of the object as type text.

d2fobg_scrlbr_tbp_obj( ctx, obj, val );

This macro returns the value of the D2FP_SCRLBR_TBP_OBJ property of the object as type object.

d2fobg_scrlbr_wid( ctx, obj, val );

This macro returns the value of the Scroll Bar Width property of the object as type number.

d2fobg_scrlbr_x_pos( ctx, obj, val );

This macro returns the value of the Scroll Bar X Position property of the object as type number.

d2fobg_scrlbr_y_pos( ctx, obj, val );

This macro returns the value of the Scroll Bar Y Position property of the object as type number.

d2fobg_share_lib( ctx, obj, val );

This macro returns the value of the Share Library with Form property of the object as type boolean.

d2fobg_short_nam( ctx, obj, val );

This macro returns the value of the Short Name property of the object as type text.

d2fobg_show_fast_fwd( ctx, obj, val );

This macro returns the value of the Show Fast Forward Button property of the object as type boolean.

d2fobg_show_horz_scrlbr( ctx, obj, val );

This macro returns the value of the Show Horizontal Scrollbar property of the object as type boolean.

d2fobg_show_palette( ctx, obj, val );

This macro returns the value of the Show Palette property of the object as type boolean.

d2fobg_show_play( ctx, obj, val );

This macro returns the value of the Show Play Button property of the object as type boolean.

d2fobg_show_rec( ctx, obj, val );

This macro returns the value of the Show Record Button property of the object as type boolean.

d2fobg_show_rewind( ctx, obj, val );

This macro returns the value of the Show Rewind Button property of the object as type boolean.

d2fobg_show_scrlbr( ctx, obj, val );

This macro returns the value of the Show Scrollbar property of the object as type boolean.

d2fobg_show_slider( ctx, obj, val );

This macro returns the value of the Show Slider property of the object as type boolean.

d2fobg_show_time( ctx, obj, val );

This macro returns the value of the Show Time Indicator property of the object as type boolean.

d2fobg_show_vert_scrlbr( ctx, obj, val );

This macro returns the value of the Show Vertical Scrollbar property of the object as type boolean.

d2fobg_show_volumn( ctx, obj, val );

This macro returns the value of the Show Volume Control property of the object as type boolean.

d2fobg_shrinkwrap( ctx, obj, val );

This macro returns the value of the Shrinkwrap property of the object as type boolean.

d2fobg_sizing_sty( ctx, obj, val );

This macro returns the value of the Sizing Style property of the object as type number.

d2fobg_snd_fmt( ctx, obj, val );

This macro returns the value of the Sound Format property of the object as type number.

d2fobg_snd_qlty( ctx, obj, val );

This macro returns the value of the Sound Quality property of the object as type number.

d2fobg_sngl_obj_align( ctx, obj, val );

This macro returns the value of the Single Object Align property of the object as type number.

d2fobg_sngl_rec( ctx, obj, val );

This macro returns the value of the Single Record property of the object as type boolean.

d2fobg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the object as type object.

d2fobg_strt_prmpt_align( ctx, obj, val );

This macro returns the value of the Start Prompt Alignment property of the object as type number.

d2fobg_strt_prmpt_ofst( ctx, obj, val );

This macro returns the value of the Start Prompt Offset property of the object as type number.

d2fobg_strtup_code( ctx, obj, val );

This macro returns the value of the Startup Code property of the object as type text.

d2fobg_sub_mnu_nam( ctx, obj, val );

This macro returns the value of the D2FP_SUB_MNU_NAM property of the object as type text.

d2fobg_sub_mnu_obj( ctx, obj, val );

This macro returns the value of the D2FP_SUB_MNU_OBJ property of the object as type object.

d2fobg_sub_ttl( ctx, obj, val );

This macro returns the value of the Subtitle property of the object as type text.

d2fobg_summ_blk_nam( ctx, obj, val );

This macro returns the value of the Summarized Block property of the object as type text.

d2fobg_summ_func( ctx, obj, val );

This macro returns the value of the Summarized Function property of the object as type number.

d2fobg_summ_itm_nam( ctx, obj, val );

This macro returns the value of the Summarized Item property of the object as type text.

d2fobg_svpnt_mode( ctx, obj, val );

This macro returns the value of the Savepoint Mode property of the object as type boolean.

d2fobg_sync_itm_nam( ctx, obj, val );

This macro returns the value of the Synchronize with Item property of the object as type text.

d2fobg_sync_itm_obj( ctx, obj, val );

This macro returns the value of the d2FP_SYNC_ITM_OBJ property of the object as type object.

d2fobg_tab_att_edge( ctx, obj, val );

This macro returns the value of the Tab Attachment Edge property of the object as type number.

d2fobg_tab_page( ctx, obj, val );

This macro returns the value of the Tab Page property of the object as type object.

d2fobg_tab_sty( ctx, obj, val );

This macro returns the value of the Tab Style property of the object as type number.

d2fobg_tbp_nam( ctx, obj, val );

This macro returns the value of the D2FP_TBP_NAM property of the object as type text.

d2fobg_tbp_obj( ctx, obj, val );

This macro returns the value of the D2FP_TBP_OBJ property of the object as type object.

d2fobg_tear_off_mnu( ctx, obj, val );

This macro returns the value of the Tear-off Menu property of the object as type boolean.

d2fobg_title( ctx, obj, val );

This macro returns the value of the Title property of the object as type text.

d2fobg_tooltip( ctx, obj, val );

This macro returns the value of the Tooltip property of the object as type text.

d2fobg_tooltip_vat_grp, val );

This macro returns the value of the Tooltip Visual Attribute Group object as type text.

d2fobg_top_prmpt_align( ctx, obj, val );

This macro returns the value of the Top Prompt Alignment property of the object as type number.

d2fobg_top_prmpt_ofst( ctx, obj, val );

This macro returns the value of the Top Prompt Offset property of the object as type number.

d2fobg_trg_sty( ctx, obj, val );

This macro returns the value of the Trigger Style property of the object as type number.

d2fobg_trg_txt( ctx, obj, val );

This macro returns the value of the Trigger Text property of the object as type text.

d2fobg_trg_typ( ctx, obj, val );

This macro returns the value of the Trigger Type property of the object as type number.

d2fobg_trigger( ctx, obj, val );

This macro returns the value of the D2FP_TRIGGER property of the object as type object.

d2fobg_ttl_reading_ordr( ctx, obj, val );

This macro returns the value of the Title Reading Order property of the object as type number.

d2fobg_unchked_val( ctx, obj, val );

This macro returns the value of the Value When Unchecked property of the object as type text.

d2fobg_updt_allowed( ctx, obj, val );

This macro returns the value of the Update Allowed property of the object as type boolean.

d2fobg_updt_changed_cols( ctx, obj, val );

This macro returns the value of the Update Changed Columns Only property of the object as type boolean.

d2fobg_updt_commit( ctx, obj, val );

This macro returns the value of the Update Commit property of the object as type boolean.

d2fobg_updt_if_null( ctx, obj, val );

This macro returns the value of the Update Only if NULL property of the object as type boolean.

d2fobg_updt_layout( ctx, obj, val );

This macro returns the value of the Update Layout property of the object as type number.

d2fobg_updt_proc_nam( ctx, obj, val );

This macro returns the value of the Update Procedure Name property of the object as type text.

d2fobg_updt_qry( ctx, obj, val );

This macro returns the value of the Update Query property of the object as type boolean.

d2fobg_use_3D_cntrls( ctx, obj, val );

This macro returns the value of the Use 3D Controls property of the object as type boolean.

d2fobg_use_security( ctx, obj, val );

This macro returns the value of the Use Security property of the object as type boolean.

d2fobg_validate_from_list( ctx, obj, val );

This macro returns the value of the Validate From List property of the object as type boolean.

d2fobg_validation unit( ctx, obj, val );

This macro returns the value of the Validation Unit property of the object as type number.

d2fobg_vat_nam( ctx, obj, val );

This macro returns the value of the Visual Attribute Group property of the object as type text.

d2fobg_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_VAT_OBJ property of the object as type object.

d2fobg_vat_typ( ctx, obj, val );

This macro returns the value of the D2FP_VAT_TYPE property of the object as type number.

d2fobg_vert_fill( ctx, obj, val );

This macro returns the value of the Vertical Fill property of the object as type boolean.

d2fobg_vert_jst( ctx, obj, val );

This macro returns the value of the Vertical Justification property of the object as type number.

d2fobg_vert_margn( ctx, obj, val );

This macro returns the value of the Vertical Margin property of the object as type number.

d2fobg_vert_obj_ofst( ctx, obj, val );

This macro returns the value of the Vertical Object Offset property of the object as type number.

d2fobg_vert_orgn( ctx, obj, val );

This macro returns the value of the Vertical Position Relative to Origin property of the object as type number.

d2fobg_vert_tlbr_cnv( ctx, obj, val );

This macro returns the value of the Vertical Toolbar Canvas property of the object as type text.

d2fobg_vis_attr( ctx, obj, val );

This macro returns the value of the D2FP_VIS_ATTR property of the object as type object.

d2fobg_visible( ctx, obj, val );

This macro returns the value of the Visible property of the object as type boolean.

d2fobg_vprt_hgt( ctx, obj, val );

This macro returns the value of the Viewport Height property of the object as type number.

d2fobg_vrpt_wid( ctx, obj, val );

This macro returns the value of the Viewport Width property of the object as type number.

d2fobg_vprt_x_pos( ctx, obj, val );

This macro returns the value of the Viewport X Position property of the object as type number.

d2fobg_vrpt_x_pos_on_cnv( ctx, obj, val );

This macro returns the value of the Viewport X Position on Canvas property of the object as type number.

d2fobg_vrpt_y_pos( ctx, obj, val );

This macro returns the value of the Viewport Y Position property of the object as type number.

d2fobg_vrpt_y_pos_on_cnv( ctx, obj, val );

This macro returns the value of the Viewport Y Position on Canvas property of the object as number.

d2fobg_vsbl_in_horz_mnu_tlbr( ctx, obj, val );

This macro returns the value of the Visible in Horizontal/Vertical Menu Toolbar property of the object as type boolean.

d2fobg_vsbl_in_menu( ctx, obj, val );

This macro returns the value of the Visible in Menu property of the object as type boolean.

d2fobg_vsbl_in_vert_mnu_tlbr( ctx, obj, val );

This macro returns the value of the XXX property of the object as type boolean.

d2fobg_vtb_cnv_name( ctx, obj, val );

This macro returns the value of the Vertical Toolbar Canvas property of the object as type text.

d2fobg_where_clause( ctx, obj, val );

This macro returns the value of the Where Clause property of the object as type text.

d2fobg_white_on_black( ctx, obj, val );

This macro returns the value of the White on Black property of the object as type boolean.

d2fobg_width( ctx, obj, val );

This macro returns the value of the Width/Height property of the object as type number.

d2fobg_win_sty( ctx, obj, val );

This macro returns the value of the Window Style property of the object as type number.

d2fobg_window( ctx, obj, val );

This macro returns the value of the Window property of the object as type object.

d2fobg_wnd_nam( ctx, obj, val );

This macro returns the value of the D2FP_WND_NAM property of the object as type text.

d2fobg_wnd_obj( ctx, obj, val );

This macro returns the value of the D2FP_WND_OBJ property of the object as type object.

d2fobg_wrap_sty( ctx, obj, val );

This macro returns the value of the Wrap Style property of the object as type number.

d2fobg_wrap_txt( ctx, obj, val );

This macro returns the value of the Wrap Text property of the object as type boolean.

d2fobg_x_pos( ctx, obj, val );

This macro returns the value of the D2FP_X_POSITION property of the object as type number.

d2fobg_y_pos( ctx, obj, val );

This macro returns the value of the D2FP_Y _POSITION property of the object as type number.

d2fobs_access_key( ctx, obj, val );

This macro sets the value of the Access Key property of the object.

d2fobs_activex_class( ctx, obj, val );

This macro sets the value of the D2FP_ACTIVEX_CLASS property of the object.

d2fobs_acitvex_val_prop( ctx, obj, val );

This macro sets the value of the D2FP_ACTIVEX_VAL_PROP property of the object.

d2fobs_alert( ctx, obj, val );

This macro sets the value of the D2FP_ALERT property of the object.

d2fobs_allow_expansion( ctx, obj, val );

This macro sets the value of the Allow Expansion property of the object.

d2fobs_allow_mlt_lin_prmpts( ctx, obj, val );

This macro sets the value of the Allow Multi-line Prompts property of the object.

d2fobs_allow_strt_att_prmpts( ctx, obj, val );

This macro sets the value of the Allow Start-attached Prompts property of the object.

d2fobs_allow_top_att_prpmts( ctx, obj, val );

This macro sets the value of the Allow Top-attached Prompts property of the object.

d2fobs_alt_msg( ctx, obj, val );

This macro sets the value of the Message property of the object.

d2fobs_alt_sty( ctx, obj, val );

This macro sets the value of the Alert Style property of the object.

d2fobs_arrow_sty( ctx, obj, val );

This macro sets the value of the Line Arrow Style property of the object.

d2fobs_menus_count( ctx, obj, val );

This macro sets the value of the D2FP_MENUS_COUNT property of the object.

d2fobs_assoc_mnus( ctx, obj, val );

This macro sets the value of the Associated Menus property of the object.

d2fobs_att_lib( ctx, obj, val );

This macro sets the value of the D2FP_ATT_LIB property of the object.

d2fobs_audio_chnnls( ctx, obj, val );

This macro sets the value of the Audio Channels property of the object.

d2fobs_auto_col_wid( ctx, obj, val );

This macro sets the value of the Automatic Column Width property of the object.

d2fobs_auto_disp( ctx, obj, val );

This macro sets the value of the Automatic Display property of the object.

d2fobs_auto_hint( ctx, obj, val );

This macro sets the value of the Display Hint Automatically property of the object.

d2fobs_auto_pos( ctx, obj, val );

This macro sets the value of the Automatic Position property of the object.

d2fobs_auto_qry( ctx, obj, val );

This macro sets the value of the Automatic Query property of the object.

d2fobs_auto_rfrsh( ctx, obj, val );

This macro sets the value of the Automatic Refresh property of the object.

d2fobs_auto_skp( ctx, obj, val );

This macro sets the value of the Automatic Skip property of the object.

d2fobs_auto_slct( ctx, obj, val );

This macro sets the value of the Automatic Select property of the object.

d2fobs_back_color( ctx, obj, val );

This macro sets the value of the Background Color property of the object.

d2fobs_xxx( ctx, obj, val );

This macro sets the value of the XXX property of the object.

d2fobs_bevel( ctx, obj, val );

This macro sets the value of the Bevel property of the object.

d2fobs_blk_description( ctx, obj, val );

This macro sets the value of the D2FP_BLK_DESCRIPTION property of the object.

d2fobs_block( ctx, obj, val );

This macro sets the value of the D2FP_BLOCK property of the object.

d2fobs_bounding_bx_scalable( ctx, obj, val );

This macro sets the value of the D2FP_BOUNDING_BX_SCALABLE property of the object.

d2fobs_btm_ttl( ctx, obj, val );

This macro sets the value of the D2FP_BTM_TTL property of the object.

d2fobs_btn_1_lbl( ctx, obj, val );

This macro sets the value of the Button 1 Label property of the object.

d2fobs_btn_2_lbl( ctx, obj, val );

This macro sets the value of the Button 2 Label property of the object.

d2fobs_btn_3_lbl( ctx, obj, val );

This macro sets the value of the Button 3 Label property of the object.

d2fobs_calc_mode( ctx, obj, val );

This macro sets the value of the Calculation Mode property of the object.

d2fobs_canvas( ctx, obj, val );

This macro sets the value of the D2FP_CANVAS property of the object.

d2fobs_cap_sty( ctx, obj, val );

This macro sets the value of the Object Edge Cap Style property of the object.

d2fobs_case_insensitive_qry( ctx, obj, val );

This macro sets the value of the Case Insensitive Query property of the object.

d2fobs_case_restriction( ctx, obj, val );

This macro sets the value of the Case Restriction property of the object.

d2fobs_chk_bx_other_vals( ctx, obj, val );

This macro sets the value of the Check Box Mapping of Other Values property of the object.

d2fobs_chked_val( ctx, obj, val );

This macro sets the value of the Checked property of the object.

d2fobs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the object.

d2fobs_clip_hgt( ctx, obj, val );

This macro sets the value of the Height of Clipping Rectangle property of the object.

d2fobs_clip_wid( ctx, obj, val );

This macro sets the value of the Width of Clipping Rectangle property of the object.

d2fobs_clip_x_pos( ctx, obj, val );

This macro sets the value of the X-origin of Clipping Rectangle property of the object.

d2fobs_clip_y_pos( ctx, obj, val );

This macro sets the value of the Y-origin of Clipping Rectangle property of the object.

d2fobs_closed( ctx, obj, val );

This macro sets the value of the Polygon Flag/Arc Closure property of the object.

d2fobs_cls_allowed( ctx, obj, val );

This macro sets the value of the Close Allowed property of the object.

d2fobs_cmprssion_qlty( ctx, obj, val );

This macro sets the value of the D2FP_CMPRSSION_QLTY property of the object.

d2fobs_cnv_nam( ctx, obj, val );

This macro sets the value of the Canvas property of the object.

d2fobs_cnv_obj( ctx, obj, val );

This macro sets the value of the D2FP_CNV_OBJ property of the object.

d2fobs_cnv_typ( ctx, obj, val );

This macro sets the value of the Canvas Type property of the object.

d2fobs_col_dat_typ( ctx, obj, val );

This macro sets the value of the D2FP_COL_DAT_TYP property of the object.

d2fobs_col_map( ctx, obj, val );

This macro sets the value of the Column Mapping Properties property of the object.

d2fobs_col_nam( ctx, obj, val );

This macro sets the value of the Column Name property of the object.

d2fobs_col_spec( ctx, obj, val );

This macro sets the value of the Column Specifications property of the object.

d2fobs_col_vals_count( ctx, obj, val );

This macro sets the value of the D2FP_COL_VALS_COUNT property of the object.

d2fobs_com_txtctx, obj, val );

This macro sets the value of the Command Text property of the object.

d2fobs_xxx( ctx, obj, val );

This macro sets the value of the XXX property of the object.

d2fobs_comm_mode( ctx, obj, val );

This macro sets the value of the Communication Mode property of the object.

d2fobs_comment( ctx, obj, val );

This macro sets the value of the Comments property of the object.

d2fobs_compress( ctx, obj, val );

This macro sets the value of the Compress property of the object.

d2fobs_conceal_data( ctx, obj, val );

This macro sets the value of the Conceal Data property of the object.

d2fobs_console_win( ctx, obj, val );

This macro sets the value of the Console Window property of the object.

d2fobs_copy_val_from_itm( ctx, obj, val );

This macro sets the value of the Copy Value From Item property of the object.

d2fobs_corner_radius_x( ctx, obj, val );

This macro sets the value of the X-origin of Radius for Corner of Rounded Rectangle property of the object.

d2fobs_corner_radius_y( ctx, obj, val );

This macro sets the value of the Y-origin of Radius for Corner of Rounded Rectangle property of the object.

d2fobs_crsr_mode( ctx, obj, val );

This macro sets the value of the Cursor Mode property of the object.

d2fobs_cstm_spcing( ctx, obj, val );

This macro sets the value of the Custom Spacing for Text Object property of the object.

d2fobs_dash_sty( ctx, obj, val );

This macro sets the value of the Dash Style for Object Edge property of the object.

d2fobs_dat_src_blk( ctx, obj, val );

This macro sets the value of the Data Source Block property of the object.

d2fobs_dat_src_x_axs( ctx, obj, val );

This macro sets the value of the Data Source X Axis property of the object.

d2fobs_dat_src_y_axs( ctx, obj, val );

This macro sets the value of the X-origin of Data Source Y Axis property of the object.

d2fobs_dat_typ( ctx, obj, val );

This macro sets the value of the Data Type property of the object.

d2fobs_db_blk( ctx, obj, val );

This macro sets the value of the Database Block property of the object.

d2fobs_db_itm( ctx, obj, val );

This macro sets the value of the Database Item property of the object.

d2fobs_defer_req_enf( ctx, obj, val );

This macro sets the value of the D2FP_DEFER_REQ_ENF property of the object.

d2fobs_deferred( ctx, obj, val );

This macro sets the value of the Deferred property of the object.

d2fobs_del_allowed( ctx, obj, val );

This macro sets the value of the Delete Allowed property of the object.

d2fobs_del_proc_nam( ctx, obj, val );

This macro sets the value of the Delete Procedure Name property of the object.

d2fobs_del_rec( ctx, obj, val );

This macro sets the value of the Delete Record Behavior property of the object.

d2fobs_detail_blk( ctx, obj, val );

This macro sets the value of the Detail Block property of the object.

d2fobs_dflt_alt_btn( ctx, obj, val );

This macro sets the value of the Default Alert Button property of the object.

d2fobs_dflt_btn( ctx, obj, val );

This macro sets the value of the Default Button property of the object.

d2fobs_disp_in_kbrd_hlp( ctx, obj, val );

This macro sets the value of the Display in Keyboard Help property of the object.

d2fobs_xxxdisp_no_priv ctx, obj, val );

This macro sets the value of the Display without Privilege property of the object.

d2fobs_disp_qlty( ctx, obj, val );

This macro sets the value of the Display Quality property of the object.

d2fobs_disp_wid( ctx, obj, val );

This macro sets the value of the Display Width property of the object.

d2fobs_dist_bwwn_recs( ctx, obj, val );

This macro sets the value of the Distance Between Records property of the object.

d2fobs_dither( ctx, obj, val );

This macro sets the value of the Graphics Dither Image property of the object.

d2fobs_dml_ary_siz( ctx, obj, val );

This macro sets the value of the DML Array Size property of the object.

d2fobs_dml_dat_nam( ctx, obj, val );

This macro sets the value of the DML Data Target Name property of the object.

d2fobs_dml_dat_typ( ctx, obj, val );

This macro sets the value of the DML Data Target Type property of the object.

d2fobs_dsa_mode( ctx, obj, val );

This macro sets the value of the D2FP_DSA_MODE property of the object.

d2fobs_dsa_nam( ctx, obj, val );

This macro sets the value of the D2FP_DSA_NAM property of the object.

d2fobs_dsa_typ( ctx, obj, val );

This macro sets the value of the D2FP_DSA_TYPE property of the object.

d2fobs_dsa_typ_nam( ctx, obj, val );

This macro sets the value of the D2FP_DSA_TYP_NAM property of the object.

d2fobs_dsa_val( ctx, obj, val );

This macro sets the value of the D2FP_DSA_VAL property of the object.

d2fobs_dsc_len( ctx, obj, val );

This macro sets the value of the D2FP_DSC_LEN property of the object.

d2fobs_dsc_mandatory( ctx, obj, val );

This macro sets the value of the D2FP_DSC_MANDATORY property of the object.

d2fobs_dsc_nam( ctx, obj, val );

This macro sets the value of the D2FP_DSC_NAM property of the object.

d2fobs_dsc_precision( ctx, obj, val );

This macro sets the value of the D2FP_DSC_PRECISION property of the object.

d2fobs_dsc_scale( ctx, obj, val );

This macro sets the value of the D2FP_DSC_SCALE property of the object.

d2fobs_dsc_typ( ctx, obj, val );

This macro sets the value of the D2FP_DSC_TYP property of the object.

d2fobs_edge_back_color( ctx, obj, val );

This macro sets the value of the Object Edge Background Color property of the object.

d2fobs_edge_fore_color( ctx, obj, val );

This macro sets the value of the Object Edge Foreground Color property of the object.

d2fobs_editor( ctx, obj, val );

This macro sets the value of the Editor property of the object.

d2fobs_edt_nam( ctx, obj, val );

This macro sets the value of the Editor Name property of the object.

d2fobs_edt_obj( ctx, obj, val );

This macro sets the value of the D2FP_EDT_OBJ property of the object.

d2fobs_edt_x_pos( ctx, obj, val );

This macro sets the value of the Editor X Position/Editor Y Position property of the object.

d2fobs_edt_y_pos( ctx, obj, val );

This macro sets the value of the Editor X Position/Editor Y Position property of the object.

d2fobs_enabled( ctx, obj, val );

This macro sets the value of the Enabled property of the object.

d2fobs_enfrc_col_security( ctx, obj, val );

This macro sets the value of the Enforce Column Security property of the object.

d2fobs_enfrc_prmry_key( ctx, obj, val );

This macro sets the value of the Enforce Primary Key property of the object.

d2fobs_exec_hierarchy( ctx, obj, val );

This macro sets the value of the Executive Style property of the object.

d2fobs_exec_mode( ctx, obj, val );

This macro sets the value of the Executive Mode property of the object.

d2fobs_fill_pat( ctx, obj, val );

This macro sets the value of the Fill Pattern property of the object.

d2fobs_fire_in_qry( ctx, obj, val );

This macro sets the value of the Fire in Enter-query Mode property of the object.

d2fobs_fixed_bounding_bx( ctx, obj, val );

This macro sets the value of the Fixed Size of Object Bounding Box property of the object.

d2fobs_fixed_len( ctx, obj, val );

This macro sets the value of the Fixed Length property of the object.

d2fobs_flnam( ctx, obj, val );

This macro sets the value of the File Name property of the object.

d2fobs_fltr_before_disp( ctx, obj, val );

This macro sets the value of the Filter Before Display property of the object.

d2fobs_fmt_msk( ctx, obj, val );

This macro sets the value of the Format Mask property of the object.

d2fobs_font_nam( ctx, obj, val );

This macro sets the value of the Font Name property of the object.

d2fobs_font_scaleable( ctx, obj, val );

This macro sets the value of the Point Size Scales with Object property of the object.

d2fobs_font_siz( ctx, obj, val );

This macro sets the value of the Font Size property of the object.

d2fobs_font_spcing( ctx, obj, val );

This macro sets the value of the Font Spacing property of the object.

d2fobs_font_sty( ctx, obj, val );

This macro sets the value of the Font Style property of the object.

d2fobs_font_wght( ctx, obj, val );

This macro sets the value of the XXX property of the object.

d2fobs_font_color( ctx, obj, val );

This macro sets the value of the Font Color property of the object.

d2fobs_form_param( ctx, obj, val );

This macro sets the value of the D2FP_FORM_PARAM property of the object.

d2fobs_formula( ctx, obj, val );

This macro sets the value of the Formula property of the object.

d2fobs_frame_align( ctx, obj, val );

This macro sets the value of the Frame Alignment property of the object.

d2fobs_frame_ttl( ctx, obj, val );

This macro sets the value of the Frame Title property of the object.

d2fobs_frame_ttl_align( ctx, obj, val );

This macro sets the value of the Frame Title Alignment property of the object.

d2fobs_frame_ttl_back_color( ctx, obj, val );

This macro sets the value of the Frame Title Background Color property of the object.

d2fobs_frame_ttl_fill_pat( ctx, obj, val );

This macro sets the value of the Frame Title Fill Pattern property of the object.

d2fobs_frame_ttl_font_nam( ctx, obj, val );

This macro sets the value of the Frame Title Font Name property of the object.

d2fobs_frame_ttl_font_siz( ctx, obj, val );

This macro sets the value of the Frame Title Font Size property of the object.

d2fobs_frame_ttl_font_spcing( ctx, obj, val );

This macro sets the value of the Frame Title Font Spacing property of the object.

d2fobs_frame_ttl_font_sty( ctx, obj, val );

This macro sets the value of the Frame Title Font Style property of the object.

d2fobs_frame_ttl_font_wght( ctx, obj, val );

This macro sets the value of the Frame Title Font Weight property of the object.

d2fobs_frame_ttl_fore_color( ctx, obj, val );

This macro sets the value of the Frame Title Foreground Color property of the object.

d2fobs_frame_ttl_ofst( ctx, obj, val );

This macro sets the value of the Frame Title Offset property of the object.

d2fobs_frame_ttl_spcing( ctx, obj, val );

This macro sets the value of the Frame Title Spacing property of the object.

d2fobs_frame_ttl_vat_nam( ctx, obj, val );

This macro sets the value of the Frame Title Visual Attribute Group property of the object.

d2fobs_frame_ttl_val_obj( ctx, obj, val );

This macro sets the value of the D2FP_FRAME_TTL_VAL_OBJ property of the object.

d2fobs_frst_navigation_blk_nam( ctx, obj, val );

This macro sets the value of the First Navigation Block property of the object.

d2fobs_frst_navigation_blk_obj( ctx, obj, val );

This macro sets the value of the D2FP_FRST_NAVIGATION_BLK_OBJ property of the object.

d2fobs_gra_font_nam( ctx, obj, val );

This macro sets the value of the Graphics Font Name property of the object.

d2fobs_gra_font_siz( ctx, obj, val );

This macro sets the value of the Graphics Font Size property of the object.

d2fobs_gra_font_sty( ctx, obj, val );

This macro sets the value of the Graphics Font Style property of the object.

d2fobs_gra_text( ctx, obj, val );

This macro sets the value of the Graphics Text property of the object.

d2fobs_graphic( ctx, obj, val );

This macro sets the value of the D2FP_GRAPHIC property of the object.

d2fobs_graphics_typ( ctx, obj, val );

This macro sets the value of the Graphics Object Type property of the object.

d2fobs_height( ctx, obj, val );

This macro sets the value of the Width/Height property of the object.

d2fobs_hide_on_exit( ctx, obj, val );

This macro sets the value of the Hide on Exit property of the object.

d2fobs_highest_allowed_val( ctx, obj, val );

This macro sets the value of the Highest Allowed Value/Lowest Allowed Value property of the object.

d2fobs_hint( ctx, obj, val );

This macro sets the value of the Hint property of the object.

d2fobs_hlp_description( ctx, obj, val );

This macro sets the value of the Help property of the object.

d2fobs_horz_jst( ctx, obj, val );

This macro sets the value of the Horizontal Justification of Text Object property of the object.

d2fobs_horz_margn( ctx, obj, val );

This macro sets the value of the Horizontal Margin property of the object.

d2fobs_horz_obj_ofst( ctx, obj, val );

This macro sets the value of the Horizontal Object Offset property of the object.

d2fobs_horz_orgn( ctx, obj, val );

This macro sets the value of the Horizontal Position Relative to Origin property of the object.

d2fobs_horz_tlbr_cnv( ctx, obj, val );

This macro sets the value of the Horizontal Toolbar Canvas property of the object.

d2fobs_htb_cnv_name( ctx, obj, val );

This macro sets the value of the D2FP_HTB_CNV_NAME property of the object.

d2fobs_icon_flnam( ctx, obj, val );

This macro sets the value of the Icon Filename property of the object.

d2fobs_icon_in_mnu( ctx, obj, val );

This macro sets the value of the D2FO_ICON_IN_MNU property of the object.

d2fobs_iconic( ctx, obj, val );

This macro sets the value of the Iconic property of the object.

d2fobs_img_dpth( ctx, obj, val );

This macro sets the value of the Image Depth property of the object.

d2fobs_img_fmt( ctx, obj, val );

This macro sets the value of the Image Format property of the object.

d2fobs_inhrt_mnu( ctx, obj, val );

This macro sets the value of the Inherit Menu property of the object.

d2fobs_inhrt_sty( ctx, obj, val );

This macro sets the value of the Inherit Style property of the object.

d2fobs_init_kgrd_dir( ctx, obj, val );

This macro sets the value of the Initial Keyboard Direction property of the object.

d2fobs_init_menu( ctx, obj, val );

This macro sets the value of the Initial Menu property of the object.

d2fobs_init_val( ctx, obj, val );

This macro sets the value of the Initial Value property of the object.

d2fobs_insrt_allowed( ctx, obj, val );

This macro sets the value of the Insert Allowed property of the object.

d2fobs_insrt_proc_nam( ctx, obj, val );

This macro sets the value of the Insert Procedure Name property of the object.

d2fobs_interaction_mode( ctx, obj, val );

This macro sets the value of the Interaction Mode property of the object.

d2fobs_internal_end_angle( ctx, obj, val );

This macro sets the value of the D2FP_INTERNAL_END_ANGLE property of the object.

d2fobs_internal_lin_wid( ctx, obj, val );

This macro sets the value of the D2FP_INTERNAL_LIN_WID property of the object.

d2fobs_internal_rotation_angle( ctx, obj, val );

This macro sets the value of the D2FP_INTERNAL_ROTATION_ANGLE property of the object.

d2fobs_internal_strt_angle( ctx, obj, val );

This macro sets the value of the D2FP_INTERNAL_STRT_ANGLE property of the object.

d2fobs_isolation_mode( ctx, obj, val );

This macro sets the value of the Isolation Mode property of the object.

d2fobs_item( ctx, obj, val );

This macro sets the value of the D2FP_ITEM property of the object.

d2fobs_itm_typ( ctx, obj, val );

This macro sets the value of the Item Type property of the object.

d2fobs_itms_disp( ctx, obj, val );

This macro sets the value of the Number of Items Displayed property of the object.

d2fobs_join_cond( ctx, obj, val );

This macro sets the value of the Join Condition property of the object.

d2fobs_join_sty( ctx, obj, val );

This macro sets the value of the Join Style of Objects Edge property of the object.

d2fobs_justification( ctx, obj, val );

This macro sets the value of the Justification property of the object.

d2fobs_kbrd_acc( ctx, obj, val );

This macro sets the value of the Keyboard Accelerator property of the object.

d2fobs_kbrd_hlp_txt( ctx, obj, val );

This macro sets the value of the Keyboard Help Description property of the object.

d2fobs_kbrd_navigable( ctx, obj, val );

This macro sets the value of the Keyboard Navigable property of the object.

d2fobs_kbrd_state( ctx, obj, val );

This macro sets the value of the Keyboard State property of the object.

d2fobs_keep_crsr_pos( ctx, obj, val );

This macro sets the value of the Keep Cursor Position property of the object.

d2fobs_key_mode( ctx, obj, val );

This macro sets the value of the Key Mode property of the object.

d2fobs_label( ctx, obj, val );

This macro sets the value of the Label property of the object.

d2fobs_lang_dir( ctx, obj, val );

This macro sets the value of the Language Direction property of the object.

d2fobs_layout_data_blk_nam( ctx, obj, val );

This macro sets the value of the Layout Data Block property of the object.

d2fobs_layout_sty( ctx, obj, val );

This macro sets the value of the Layout Style property of the object.

d2fobs_lib_loc( ctx, obj, val );

This macro sets the value of the PL/SQL Library Location property of the object.

d2fobs_lib_src( ctx, obj, val );

This macro sets the value of the PL/SQL Library Source property of the object.

d2fobs_lin_spcing( ctx, obj, val );

This macro sets the value of the Line Spacing property of the object.

d2fobs_lock_mode( ctx, obj, val );

This macro sets the value of the Locking Mode property of the object.

d2fobs_lock_proc_nam( ctx, obj, val );

This macro sets the value of the Lock Procedure Name property of the object.

d2fobs_lock_rec( ctx, obj, val );

This macro sets the value of the Lock Record property of the object.

d2fobs_lov( ctx, obj, val );

This macro sets the value of the List of Values property of the object.

d2fobs_lov_nam( ctx, obj, val );

This macro sets the value of the D2FP_LOV_NAM property of the object.

d2fobs_lov_obj( ctx, obj, val );

This macro sets the value of the D2FP_LOV_OBJ property of the object.

d2fobs_lov_x_pos( ctx, obj, val );

This macro sets the value of the List X Position property of the object.

d2fobs_lov_y_pos( ctx, obj, val );

This macro sets the value of the List Y Position property of the object.

d2fobs_lowest_allowed_val( ctx, obj, val );

This macro sets the value of the Highest Allowed Value/Lowest Allowed Value property of the object.

d2fobs_lst_element_count( ctx, obj, val );

This macro sets the value of the List Element Count property of the object.

d2fobs_lst_in_blk_mnu( ctx, obj, val );

This macro sets the value of the Listed in Block Menu property of the object.

d2fobs_lst_sty( ctx, obj, val );

This macro sets the value of the List Style property of the object.

d2fobs_lst_typ( ctx, obj, val );

This macro sets the value of the List Type property of the object.

d2fobs_magic_itm( ctx, obj, val );

This macro sets the value of the Magic Item property of the object.

d2fobs_main_mnu( ctx, obj, val );

This macro sets the value of the Main Menu property of the object.

d2fobs_max_len( ctx, obj, val );

This macro sets the value of the Maximum Length property of the object.

d2fobs_max_objs( ctx, obj, val );

This macro sets the value of the Maximum Objects Per Line property of the object.

d2fobs_max_qry_time( ctx, obj, val );

This macro sets the value of the Maximum Query Time property of the object.

d2fobs_max_recs_fetched( ctx, obj, val );

This macro sets the value of the Maximum Records Fetched property of the object.

d2fobs_maximize_allowed( ctx, obj, val );

This macro sets the value of the Maximize Allowed property of the object.

d2fobs_menu( ctx, obj, val );

This macro sets the value of the D2FP_MENU property of the object.

d2fobs_minimize_allowed( ctx, obj, val );

This macro sets the value of the Minimized Allowed property of the object.

d2fobs_minimize_ttl( ctx, obj, val );

This macro sets the value of the Minimize Title property of the object.

d2fobs_mlt_lin( ctx, obj, val );

This macro sets the value of the Multi-line property of the object.

d2fobs_mnu_description( ctx, obj, val );

This macro sets the value of the Menu Description property of the object.

d2fobs_mnu_drctry( ctx, obj, val );

This macro sets the value of the Menu Directory property of the object.

d2fobs_mnu_flnam( ctx, obj, val );

This macro sets the value of the Menu Filename property of the object.

d2fobs_mnu_itm( ctx, obj, val );

This macro sets the value of the Menu Item Type property of the object.

d2fobs_mnu_itm_code( ctx, obj, val );

This macro sets the value of the D2FP_MNU_ITM_CODE property of the object.

d2fobs_mnu_itm_rad_grp( ctx, obj, val );

This macro sets the value of the Menu Item Radio Group property of the object.

d2fobs_mnu_itm_typ( ctx, obj, val );

This macro sets the value of the Menu Item Type property of the object.

d2fobs_mnu_mod( ctx, obj, val );

This macro sets the value of the Menu Module property of the object.

d2fobs_mnu_param( ctx, obj, val );

This macro sets the value of the D2FP_MNU_PARAM property of the object.

d2fobs_mnu_param_init_val( ctx, obj, val );

This macro sets the value of the Menu Parameter Initial Value property of the object.

d2fobs_mnu_role( ctx, obj, val );

This macro sets the value of the Menu Module Role property of the object.

d2fobs_mnu_src( ctx, obj, val );

This macro sets the value of the Menu Source property of the object.

d2fobs_mnu_sty( ctx, obj, val );

This macro sets the value of the Menu Style property of the object.

d2fobs_modal( ctx, obj, val );

This macro sets the value of the Modal property of the object.

d2fobs_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the object.

d2fobs_mouse_navigate( ctx, obj, val );

This macro sets the value of the Mouse Navigate property of the object.

d2fobs_mouse_navigation_lmt( ctx, obj, val );

This macro sets the value of the Mouse Navigation Limit property of the object.

d2fobs_mv_allowed( ctx, obj, val );

This macro sets the value of the Move Allowed property of the object.

d2fobs_name( ctx, obj, val );

This macro sets the value of the Name property of the object.

d2fobs_navigation_sty( ctx, obj, val );

This macro sets the value of the Navigation Style property of the object.

d2fobs_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the object.

d2fobs_nxt_navigation_blk_nam( ctx, obj, val );

This macro sets the value of the D2FP_NXT_NAVIGATION_BLK_NAM property of the object.

d2fobs_nxt_navigation_blk_obj( ctx, obj, val );

This macro sets the value of the D2FP_NXT_NAVIGATION_BLK_OBJ property of the object.

d2fobs_nxt_navigation_itm_nam( ctx, obj, val );

This macro sets the value of the D2FP_NXT_NAVIGATION_ITM_NAM property of the object.

d2fobs_nxt_navigation_itm_obj( ctx, obj, val );

This macro sets the value of the D2FP_NXT_NAVIGATION_ITM_OBJ property of the object.

d2fobs_obj_grp( ctx, obj, val );

This macro sets the value of the D2FP_OBJ_GRP property of the object.

d2fobs_obj_grp_child_real_obj( ctx, obj, val );

This macro sets the value of the D2FP_OBJ_GRP_CHILD_REAL_OBJ property of the object.

d2fobs_og_child( ctx, obj, val );

This macro sets the value of the D2FP_OG_CHILD property of the object.

d2fobs_old_lov_txt( ctx, obj, val );

This macro sets the value of the Old LOV Text property of the object.

d2fobs_ole_act_sty( ctx, obj, val );

This macro sets the value of the LOE Activation Style property of the object.

d2fobs_ole_class( ctx, obj, val );

This macro sets the value of the OLE Class property of the object.

d2fobs_ole_in_place_act( ctx, obj, val );

This macro sets the value of the OLE In-place Activation property of the object.

d2fobs_ole_insd_out_support( ctx, obj, val );

This macro sets the value of the OLE Inside-out Support property of the object.

d2fobs_ole_popup_mnu_itms( ctx, obj, val );

This macro sets the value of the OLE Popup Menu Items property of the object.

d2fobs_ole_resiz_sty( ctx, obj, val );

This macro sets the value of the OLE Resize Style property of the object.

d2fobs_ole_show_popup_mnu( ctx, obj, val );

This macro sets the value of the OLE Show Popup Menu property of the object.

d2fobs_ole_show_tnnt_typ( ctx, obj, val );

This macro sets the value of the Show OLE Tenant Type property of the object.

d2fobs_ole_tnnt_aspct( ctx, obj, val );

This macro sets the value of the OLE Tenant Aspect property of the object.

d2fobs_ole_tnnt_typ( ctx, obj, val );

This macro sets the value of the OLE Tenant Types property of the object.

d2fobs_opt_hint( ctx, obj, val );

This macro sets the value of the Optimizer Hint property of the object.

d2fobs_ordr_by_clause( ctx, obj, val );

This macro sets the value of the Order By Clause property of the object.

d2fobs_other_vals( ctx, obj, val );

This macro sets the value of the Mapping of Other Values property of the object.

d2fobs_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the object.

d2fobs_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the object.

d2fobs_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the object.

d2fobs_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the object.

d2fobs_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the object.

d2fobs_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the object.

d2fobs_par_num( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NUM property of the object.

d2fobs_param_dat_typ( ctx, obj, val );

This macro sets the value of the Parameter Data Type property of the object.

d2fobs_param_init_val( ctx, obj, val );

This macro sets the value of the Parameter Initial Value property of the object.

d2fobs_pgu_txt( ctx, obj, val );

This macro sets the value of the D2FP_PGU_TEXT property of the object.

d2fobs_popup_mnu_nam( ctx, obj, val );

This macro sets the value of the D2FP_POPUP_MNU_NAM property of the object.

d2fobs_popup_mnu_obj( ctx, obj, val );

This macro sets the value of the D2FP_POPUP_MNU_OBJ property of the object.

d2fobs_popup_va_obj( ctx, obj, val );

This macro sets the value of the D2FP_POPUP_VA_OBJ property of the object.

d2fobs_precomp_summ( ctx, obj, val );

This macro sets the value of the D2FP_PRECOMP_SUMM property of the object.

d2fobs_prev_navigation_blk_nam( ctx, obj, val );

This macro sets the value of the Previous Navigation Block property of the object.

d2fobs_prev_navigation_blk_obj( ctx, obj, val );

This macro sets the value of the D2FP_PREV_NAVIGATION_BLK_OBJ property of the object.

d2fobs_prev_navigation_itm_nam( ctx, obj, val );

This macro sets the value of the Previous Navigation Item Name property of the object.

d2fobs_prev_navigation_itm_obj( ctx, obj, val );

This macro sets the value of the D2FP_PREV_NAVIGATION_ITM_OBJ property of the object.

d2fobs_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the object.

d2fobs_prmpt( ctx, obj, val );

This macro sets the value of the Prompt property of the object.

d2fobs_prmpt_align( ctx, obj, val );

This macro sets the value of the Prompt Alignment property of the object.

d2fobs_prmpt_align_ofst( ctx, obj, val );

This macro sets the value of the Prompt Alignment Offset property of the object.

d2fobs_prmpt_att_edge( ctx, obj, val );

This macro sets the value of the Prompt Attachment Edge property of the object.

d2fobs_prmpt_att_ofst( ctx, obj, val );

This macro sets the value of the Prompt Attachment Offset property of the object.

d2fobs_prmpt_back_color( ctx, obj, val );

This macro sets the value of the Prompt Background Color property of the object.

d2fobs_prmpt_disp_sty( ctx, obj, val );

This macro sets the value of the Prompt Display Style property of the object.

d2fobs_prmpt_fill_pat( ctx, obj, val );

This macro sets the value of the Prompt Fill Pattern property of the object.

d2fobs_prmpt_font_nam( ctx, obj, val );

This macro sets the value of the Prompt Font Name property of the object.

d2fobs_prmpt_font_siz( ctx, obj, val );

This macro sets the value of the Prompt Font Size property of the object.

d2fobs_prmpt_font_spcing( ctx, obj, val );

This macro sets the value of the Prompt Font Spacing property of the object.

d2fobs_prompt_font_sty( ctx, obj, val );

This macro sets the value of the Prompt Font Style property of the object.

d2fobs_prmpt_font_wght( ctx, obj, val );

This macro sets the value of the Prompt Font Weight property of the object.

d2fobs_prmpt_fore_color( ctx, obj, val );

This macro sets the value of the Prompt Foreground Color property of the object.

d2fobs_prmpt_jst( ctx, obj, val );

This macro sets the value of the Prompt Justification property of the object.

d2fobs_prmpt_reading_ordr( ctx, obj, val );

This macro sets the value of the Prompt Reading Order property of the object.

d2fobs_prmpt_vat_nam( ctx, obj, val );

This macro sets the value of the Prompt Visual Attribute Group property of the object.

d2fobs_prmpt_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_PRMPT_VAT_OBJ property of the object.

d2fobs_prmry_cnv( ctx, obj, val );

This macro sets the value of the Primary Canvas property of the object.

d2fobs_prmry_key( ctx, obj, val );

This macro sets the value of the Primary Key property of the object.

d2fobs_prog_unit( ctx, obj, val );

This macro sets the value of the D2FP_PROG_UNIT property of the object.

d2fobs_prop_class( ctx, obj, val );

This macro sets the value of the Property Class property of the object.

d2fobs_prvnt_mstrless_ops( ctx, obj, val );

This macro sets the value of the Prevent Masterless Operations property of the object.

d2fobs_qry_all_recs( ctx, obj, val );

This macro sets the value of the Query All Records property of the object.

d2fobs_qry_allowed( ctx, obj, val );

This macro sets the value of the Query Allowed property of the object.

d2fobs_qry_dat_src_nam( ctx, obj, val );

This macro sets the value of the Query Data Source Name property of the object.

d2fobs_qry_dat_src_type( ctx, obj, val );

This macro sets the value of the Query Data Source Type property of the object.

d2fobs_qry_len( ctx, obj, val );

This macro sets the value of the Query Length property of the object.

d2fobs_qry_only( ctx, obj, val );

This macro sets the value of the Query Only property of the object.

d2fobs_rad_but( ctx, obj, val );

This macro sets the value of the D2FP_RAD_BUT property of the object.

d2fobs_raise_on_entry( ctx, obj, val );

This macro sets the value of the Raise On Entry property of the object.

d2fobs_rdb_val( ctx, obj, val );

This macro sets the value of the Radio Button Value property of the object.

d2fobs_reading_ordr( ctx, obj, val );

This macro sets the value of the Reading Order property of the object.

d2fobs_rec_grp( ctx, obj, val );

This macro sets the value of the Record Group property of the object.

d2fobs_rec_grp_fetch_siz( ctx, obj, val );

This macro sets the value of the D2FP_REC_GRP_FETCH_SIZ property of the object.

d2fobs_rec_grp_nam( ctx, obj, val );

This macro sets the value of the Record Group property of the object.

d2fobs_rec_grp_obj( ctx, obj, val );

This macro sets the value of the D2FP_REC_GRP_OBJ property of the object.

d2fobs_rec_grp_qry( ctx, obj, val );

This macro sets the value of the Record Group Query property of the object.

d2fobs_rec_grp_typ( ctx, obj, val );

This macro sets the value of the Record Group Type property of the object.

d2fobs_rec_ornt( ctx, obj, val );

This macro sets the value of the Record Orientation property of the object.

d2fobs_rec_vat_grp_nam( ctx, obj, val );

This macro sets the value of the Current Record Visual Attribute Group property of the object.

d2fobs_rec_vat_grp_obj( ctx, obj, val );

This macro sets the value of the D2FP_REC_VAT_GRP_OBJ property of the object.

d2fobs_recs_buffered_count( ctx, obj, val );

This macro sets the value of the Number of Records Buffered property of the object.

d2fobs_recs_disp_count( ctx, obj, val );

This macro sets the value of the Number of Records Displayed property of the object.

d2fobs_recs_fetched_count( ctx, obj, val );

This macro sets the value of the Records to Fetch property of the object.

d2fobs_rel( ctx, obj, val );

This macro sets the value of the D2FP_REL property of the object.

d2fobs_rendered( ctx, obj, val );

This macro sets the value of the Rendered property of the object.

d2fobs_report( ctx, obj, val );

This macro sets the value of the D2FP_REPORT property of the object.

d2fobs_required( ctx, obj, val );

This macro sets the value of the Required property of the object.

d2fobs_resize_allowed( ctx, obj, val );

This macro sets the value of the Resize Allowed property of the object.

d2fobs_rev_dir( ctx, obj, val );

This macro sets the value of the Reverse Direction property of the object.

d2fobs_rpt_destination_fmt( ctx, obj, val );

This macro sets the value of the Report Destination Format property of the object.

d2fobs_rpt_destination_nam( ctx, obj, val );

This macro sets the value of the Report Destination Name property of the object.

d2fobs_rpt_destination_typ( ctx, obj, val );

This macro sets the value of the Report Destination Type property of the object.

d2fobs_rpt_params( ctx, obj, val );

This macro sets the value of the Other Reports Parameters property of the object.

d2fobs_rpt_srvr( ctx, obj, val );

This macro sets the value of the Report Server property of the object.

d2fobs_rtrn_itm( ctx, obj, val );

This macro sets the value of the Return Item property of the object.

d2fobs_runtime_comp( ctx, obj, val );

This macro sets the value of the D2FP_RUNTIME_COMP property of the object.

d2fobs_scrlbr_align( ctx, obj, val );

This macro sets the value of the Scroll Bar Alignment property of the object.

d2fobs_scrlbr_cnv_nam( ctx, obj, val );

This macro sets the value of the Scroll Bar Canvas property of the object.

d2fobs_scrlbr_cnv_obj( ctx, obj, val );

This macro sets the value of the D2FP_SCRLBR_CNV_OBJ property of the object.

d2fobs_scrlbr_hgt( ctx, obj, val );

This macro sets the value of the Scroll Bar Height property of the object.

d2fobs_scrlbr_ornt( ctx, obj, val );

This macro sets the value of the Scroll Bar Orientation property of the object.

d2fobs_scrlbr_tbp_nam( ctx, obj, val );

This macro sets the value of the Scroll Bar Tab Page property of the object.

d2fobs_scrlbr_tbp_obj( ctx, obj, val );

This macro sets the value of the D2FP_SCRLBR_TBP_OBJ property of the object.

d2fobs_scrlbr_wid( ctx, obj, val );

This macro sets the value of the Scroll Bar Width property of the object.

d2fobs_scrlbr_x_pos( ctx, obj, val );

This macro sets the value of the Scroll Bar X Position property of the object.

d2fobs_scrlbr_y_pos( ctx, obj, val );

This macro sets the value of the Scroll Bar Y Position property of the object.

d2fobs_share_lib( ctx, obj, val );

This macro sets the value of the Share Library with Form property of the object.

d2fobs_short_nam( ctx, obj, val );

This macro sets the value of the Short Name property of the object.

d2fobs_show_fast_fwd( ctx, obj, val );

This macro sets the value of the Show Fast Forward Button property of the object.

d2fobs_show_horz_scrlbr( ctx, obj, val );

This macro sets the value of the Show Horizontal Scrollbar property of the object.

d2fobs_show_palette( ctx, obj, val );

This macro sets the value of the Show Palette property of the object.

d2fobs_show_play( ctx, obj, val );

This macro sets the value of the Show Play Button property of the object.

d2fobs_show_rec( ctx, obj, val );

This macro sets the value of the Show Record Button property of the object.

d2fobs_show_rewind( ctx, obj, val );

This macro sets the value of the Show Rewind Button property of the object.

d2fobs_show_scrlbr( ctx, obj, val );

This macro sets the value of the Show Scrollbar property of the object.

d2fobs_show_slider( ctx, obj, val );

This macro sets the value of the Show Slider property of the object.

d2fobs_show_time( ctx, obj, val );

This macro sets the value of the Show Time Indicator property of the object.

d2fobs_show_vert_scrlbr( ctx, obj, val );

This macro sets the value of the Show Vertical Scrollbar property of the object.

d2fobs_show_volumn( ctx, obj, val );

This macro sets the value of the Show Volume Control property of the object.

d2fobs_shrinkwrap( ctx, obj, val );

This macro sets the value of the Shrinkwrap property of the object.

d2fobs_sizing_sty( ctx, obj, val );

This macro sets the value of the Sizing Style property of the object.

d2fobs_snd_fmt( ctx, obj, val );

This macro sets the value of the Sound Format property of the object.

d2fobs_snd_qlty( ctx, obj, val );

This macro sets the value of the Sound Quality property of the object.

d2fobs_sngl_obj_align( ctx, obj, val );

This macro sets the value of the Single Object Align property of the object.

d2fobs_sngl_rec( ctx, obj, val );

This macro sets the value of the Single Record property of the object.

d2fobs_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the object.

d2fobs_strt_prmpt_align( ctx, obj, val );

This macro sets the value of the Start Prompt Alignment property of the object.

d2fobs_strt_prmpt_ofst( ctx, obj, val );

This macro sets the value of the Start Prompt Offset property of the object.

d2fobs_strtup_code( ctx, obj, val );

This macro sets the value of the Startup Code property of the object.

d2fobs_sub_mnu_nam( ctx, obj, val );

This macro sets the value of the D2FP_SUB_MNU_NAM property of the object.

d2fobs_sub_mnu_obj( ctx, obj, val );

This macro sets the value of the D2FP_SUB_MNU_OBJ property of the object.

d2fobs_sub_ttl( ctx, obj, val );

This macro sets the value of the Subtitle property of the object.

d2fobs_summ_blk_nam( ctx, obj, val );

This macro sets the value of the Summarized Block property of the object.

d2fobs_summ_func( ctx, obj, val );

This macro sets the value of the Summarized Function property of the object.

d2fobs_summ_itm_nam( ctx, obj, val );

This macro sets the value of the Summarized Item property of the object.

d2fobs_svpnt_mode( ctx, obj, val );

This macro sets the value of the Savepoint Mode property of the object.

d2fobs_sync_itm_nam( ctx, obj, val );

This macro sets the value of the Synchronize with Item property of the object.

d2fobs_sync_itm_obj( ctx, obj, val );

This macro sets the value of the d2FP_SYNC_ITM_OBJ property of the object.

d2fobs_tab_att_edge( ctx, obj, val );

This macro sets the value of the Tab Attachment Edge property of the object.

d2fobs_tab_page( ctx, obj, val );

This macro sets the value of the Tab Page property of the object.

d2fobs_tab_sty( ctx, obj, val );

This macro sets the value of the Tab Style property of the object.

d2fobs_tbp_nam( ctx, obj, val );

This macro sets the value of the D2FP_TBP_NAM property of the object.

d2fobs_tbp_obj( ctx, obj, val );

This macro sets the value of the D2FP_TBP_OBJ property of the object.

d2fobs_tear_off_mnu( ctx, obj, val );

This macro sets the value of the Tear-off Menu property of the object.

d2fobs_title( ctx, obj, val );

This macro sets the value of the Title property of the object.

d2fobs_tooltip( ctx, obj, val );

This macro sets the value of the Tooltip property of the object.

d2fobs_tooltip_vat_grp, val );

This macro sets the value of the Tooltip Visual Attribute Group object.

d2fobs_top_prmpt_align( ctx, obj, val );

This macro sets the value of the Top Prompt Alignment property of the object.

d2fobs_top_prmpt_ofst( ctx, obj, val );

This macro sets the value of the Top Prompt Offset property of the object.

d2fobs_trg_sty( ctx, obj, val );

This macro sets the value of the Trigger Style property of the object.

d2fobs_trg_txt( ctx, obj, val );

This macro sets the value of the Trigger Text property of the object.

d2fobs_trg_typ( ctx, obj, val );

This macro sets the value of the Trigger Type property of the object.

d2fobs_trigger( ctx, obj, val );

This macro sets the value of the D2FP_TRIGGER property of the object.

d2fobs_ttl_reading_ordr( ctx, obj, val );

This macro sets the value of the Title Reading Order property of the object.

d2fobs_unchked_val( ctx, obj, val );

This macro sets the value of the Value When Unchecked property of the object.

d2fobs_updt_allowed( ctx, obj, val );

This macro sets the value of the Update Allowed property of the object.

d2fobs_updt_changed_cols( ctx, obj, val );

This macro sets the value of the Update Changed Columns Only property of the object.

d2fobs_updt_commit( ctx, obj, val );

This macro sets the value of the Update Commit property of the object.

d2fobs_updt_if_null( ctx, obj, val );

This macro sets the value of the Update Only if NULL property of the object.

d2fobs_updt_layout( ctx, obj, val );

This macro sets the value of the Update Layout property of the object.

d2fobs_updt_proc_nam( ctx, obj, val );

This macro sets the value of the Update Procedure Name property of the object.

d2fobs_updt_qry( ctx, obj, val );

This macro sets the value of the Update Query property of the object.

d2fobs_use_3D_cntrls( ctx, obj, val );

This macro sets the value of the Use 3D Controls property of the object.

d2fobs_use_security( ctx, obj, val );

This macro sets the value of the Use Security property of the object.

d2fobs_validate_from_list( ctx, obj, val );

This macro sets the value of the Validate From List property of the object.

d2fobs_validation unit( ctx, obj, val );

This macro sets the value of the Validation Unit property of the object.

d2fobs_vat_nam( ctx, obj, val );

This macro sets the value of the Visual Attribute Group property of the object.

d2fobs_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_VAT_OBJ property of the object.

d2fobs_vat_typ( ctx, obj, val );

This macro sets the value of the D2FP_VAT_TYPE property of the object.

d2fobs_vert_fill( ctx, obj, val );

This macro sets the value of the Vertical Fill property of the object.

d2fobs_vert_jst( ctx, obj, val );

This macro sets the value of the Vertical Justification property of the object.

d2fobs_vert_margn( ctx, obj, val );

This macro sets the value of the Vertical Margin property of the object.

d2fobs_vert_obj_ofst( ctx, obj, val );

This macro sets the value of the Vertical Object Offset property of the object.

d2fobs_vert_orgn( ctx, obj, val );

This macro sets the value of the Vertical Position Relative to Origin property of the object.

d2fobs_vert_tlbr_cnv( ctx, obj, val );

This macro sets the value of the Vertical Toolbar Canvas property of the object.

d2fobs_vis_attr( ctx, obj, val );

This macro sets the value of the D2FP_VIS_ATTR property of the object.

d2fobs_visible( ctx, obj, val );

This macro sets the value of the Visible property of the object.

d2fobs_vprt_hgt( ctx, obj, val );

This macro sets the value of the Viewport Height property of the object.

d2fobs_vrpt_wid( ctx, obj, val );

This macro sets the value of the Viewport Width property of the object.

d2fobs_vprt_x_pos( ctx, obj, val );

This macro sets the value of the Viewport X Position property of the object.

d2fobs_vrpt_x_pos_on_cnv( ctx, obj, val );

This macro sets the value of the Viewport X Position on Canvas property of the object.

d2fobs_vrpt_y_pos( ctx, obj, val );

This macro sets the value of the Viewport Y Position property of the object.

d2fobs_vrpt_y_pos_on_cnv( ctx, obj, val );

This macro sets the value of the Viewport Y Position on Canvas property of the object.

d2fobs_vsbl_in_horz_mnu_tlbr( ctx, obj, val );

This macro sets the value of the Visible in Horizontal/Vertical Menu Toolbar property of the object.

d2fobs_vsbl_in_menu( ctx, obj, val );

This macro sets the value of the Visible in Menu property of the object.

d2fobs_vsbl_in_vert_mnu_tlbr( ctx, obj, val );

This macro sets the value of the XXX property of the object.

d2fobs_vtb_cnv_name( ctx, obj, val );

This macro sets the value of the Vertical Toolbar Canvas property of the object.

d2fobs_where_clause( ctx, obj, val );

This macro sets the value of the Where Clause property of the object.

d2fobs_white_on_black( ctx, obj, val );

This macro sets the value of the White on Black property of the object.

d2fobs_width( ctx, obj, val );

This macro sets the value of the Width/Height property of the object.

d2fobs_win_sty( ctx, obj, val );

This macro sets the value of the Window Style property of the object.

d2fobs_window( ctx, obj, val );

This macro sets the value of the Window property of the object.

d2fobs_wnd_nam( ctx, obj, val );

This macro sets the value of the D2FP_WND_NAM property of the object.

d2fobs_wnd_obj( ctx, obj, val );

This macro sets the value of the D2FP_WND_OBJ property of the object.

d2fobs_wrap_sty( ctx, obj, val );

This macro sets the value of the Wrap Style property of the object.

d2fobs_wrap_txt( ctx, obj, val );

This macro sets the value of the Wrap Text property of the object.

d2fobs_x_pos( ctx, obj, val );

This macro sets the value of the D2FP_X_POSITION property of the object.

d2fobs_y_pos( ctx, obj, val );

This macro sets the value of the D2FP_Y _POSITION property of the object.


Object group object macros

  Related Topics

This section describes the macros of the Form Builder Open API Object Group object.

d2fobgg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the object group object as a type dvoid pointer.

d2fobgg_comment( ctx, obj, val );

This macro returns the value of the D2FP_COMMENT property of the object group object as type text.

d2fobgg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the object group object as type object.

d2fobgg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the object group object as type text.

d2fobgg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the object group object as type object.

d2fobgg_og_child( ctx, obj, val );

This macro returns the value of the D2FP_OG_CHILD property of the object group object as type object.

d2fobgg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the object group object as type object.

d2fobgg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the object group object as type text.

d2fobgg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the object group object as type text.

d2fobgg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the object group object as type number.

d2fobgg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the object group object as type number.

d2fobgg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the object group object as type text.

d2fobgg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the object group object as type text.

d2fobgg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the object group object as type object.

d2fobgg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the object group object as type object.

d2fobgs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the object group object.

d2fobgs_comment( ctx, obj, val );

This macro sets the value of the D2FP_COMMENT property of the object group object.

d2fobgs_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the object group object.

d2fobgs_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the object group object.

d2fobgs_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the object group object.

d2fobgs_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the object group object.

d2fobgs_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the object group object.

d2fobgs_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the object group object.

d2fobgs_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the object group object.


Object group child object macros

  Related Topics

This section describes the macros of the Form Builder Open API Object Group Child object.

d2fogcg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the object group child object as a type dvoid pointer.

d2fogcg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the object group child object as type text.

d2fogcg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the object group child object as type object.

d2fogcg_obj_grp_child_real_obj( ctx, obj, val );

This macro returns the value of the D2FP_OBJ_GRP_CHILD_REAL_OBJ property of the object group child object as type object.

d2fogcg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the object group child object as type object.

d2fogcg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the object group child object as type object.

d2fogcs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the object group child object.

d2fogcs_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the object group child object.

d2fogcs_obj_grp_child_real_obj( ctx, obj, val );

This macro sets the value of the D2FP_ OBJ_GRP_CHILD_REAL_OBJ property of the object group child object.


Object library object macros

  Related Topics

This section describes the macros of the Form Builder Open API Object Library object.

d2folbg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the object library object as a type dvoid pointer.

d2folbg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the object library object as type text.

d2folbg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the object library object as type object.

d2folbg_obj_count( ctx, obj, val );

This macro returns the value of the D2FP_OBJ_COUNT property of the object library object as type number.

d2folbg_obj_lib_tab( ctx, obj, val );

This macro returns the value of the D2FP_OBJ_LIB_TAB property of the object library object as type object.

d2folbg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the object library object as type object.

d2folbs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the object library object.

d2folbs_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the object library object.


Program unit object macros

  Related Topics

This section describes the macros of the Form Builder Open API Program Unit object.

d2fpgug_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the program unit object as a type dvoid pointer.

d2fpgug_comment( ctx, obj, val );

This macro returns the value of the Comments property of the program unit object as type text.

d2fpgug_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the program unit object as type object.

d2fpgug_name( ctx, obj, val );

This macro returns the value of the Name property of the program unit object as type text.

d2fpgug_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the program unit object as type object.

d2fpgug_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the program unit object as type object.

d2fpgug_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the program unit object as type text.

d2fpgug_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the program unit object as type text.

d2fpgug_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the program unit object as type number.

d2fpgug_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the program unit object as type number.

d2fpgug_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the program unit object as type text.

d2fpgug_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the program unit object as type text.

d2fpgug_pgu_txt( ctx, obj, val );

This macro returns the value of the D2FP_PGU_TXT property of the program unit object as type text.

d2fpgug_pgu_typ( ctx, obj, val );

This macro returns the value of the D2FP_PGU_TYP property of the program unit object as type number.

d2fpgug_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the program unit object as type object.

d2fpgug_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the program unit object as type object.

d2fpgus_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the program unit object.

d2fpgus_comment( ctx, obj, val );

This macro sets the value of the Comments property of the program unit object.

d2fpgus_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the program unit object.

d2fpgus_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the program unit object.

d2fpgus_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the program unit object.

d2fpgus_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the program unit object.

d2fpgus_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the program unit object.

d2fpgus_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the program unit object.

d2fpgus_pgu_txt( ctx, obj, val );

This macro sets the value of the D2FP_PGU_TXT property of the program unit object.


Property class object macros

  Related Topics

This section describes the macros of the Form Builder Open API Property Class object.

d2fppcg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the property class object as a type dvoid pointer.

d2fppcg_comment( ctx, obj, val );

This macro returns the value of the D2FP_COMMENT property of the property class object as type text.

d2fppcg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the property class object as type object.

d2fppcg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the property class object as type text.

d2fppcg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the property class object as type object.

d2fppcg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the property class object as type object.

d2fppcg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the property class object as type text.

d2fppcg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the property class object as type text.

d2fppcg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the property class object as type number.

d2fppcg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the property class object as type number.

d2fppcg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the property class object as type text.

d2fppcg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the property class object as type text.

d2fppcg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the property class object as type object.

d2fppcg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the property class object as type object.

d2fppcg_trigger( ctx, obj, val );

This macro returns the value of the D2FP_TRIGGER property of the property class object as type object.

d2fppcs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the property class object.

d2fppcs_comment( ctx, obj, val );

This macro sets the value of the D2FP_COMMENT property of the property class object.

d2fppcs_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the property class object.

d2fppcs_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the property class object.

d2fppcs_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the property class object.

d2fppcs_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the property class object.

d2fppcs_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the property class object.

d2fppcs_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the property class object.

d2fppcs_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the property class object.


Radio button object macros

  Related Topics

This section describes the macros of the Form Builder Open API Radio Button object.

d2frdbg_access_key( ctx, obj, val );

This macro returns the value of the Access Key property of the radio button object as type text.

d2frdbg_back_color( ctx, obj, val );

This macro returns the value of the Background Color property of the radio button object as type text.

d2frdbg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the radio button object as a type dvoid pointer.

d2frdbg_comment( ctx, obj, val );

This macro returns the value of the Comments property of the radio button object as type text.

d2frdbg_dist_btwn_recs( ctx, obj, val );

This macro returns the value of the Distance Between Records property of the radio button object as type number.

d2frdbg_enabled( ctx, obj, val );

This macro returns the value of the Enabled property of the radio button object as type boolean.

d2frdbg_fill_pat( ctx, obj, val );

This macro returns the value of the Fill Pattern property of the radio button object as type text.

d2frdbg_font_nam( ctx, obj, val );

This macro returns the value of the Font Name property of the radio button object as type text.

d2frdbg_font_siz( ctx, obj, val );

This macro returns the value of the Font Size property of the radio button object as type number.

d2frdbg_font_spcing( ctx, obj, val );

This macro returns the value of the Font Spacing property of the radio button object as type number.

d2frdbg_font_sty( ctx, obj, val );

This macro returns the value of the Font Style property of the radio button object as type number.

d2frdbg_font_weight( ctx, obj, val );

This macro returns the value of the Font Weight property of the radio button object as type number.

d2frdbg_fore_color( ctx, obj, val );

This macro returns the value of the Foreground Color property of the radio button object as type text.

d2frdbg_height( ctx, obj, val );

This macro returns the value of the Width/Height property of the radio button object as type number.

d2frdbg_label( ctx, obj, val );

This macro returns the value of the Label property of the radio button object as type text.

d2frdbg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the radio button object as type object.

d2frdbg_name( ctx, obj, val );

This macro returns the value of the Name property of the radio button object as type text.

d2frdbg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the radio button object as type object.

d2frdbg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the radio button object as type object.

d2frdbg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the radio button object as type text.

d2frdbg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the radio button object as type text.

d2frdbg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the radio button object as type number.

d2frdbg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the radio button object as type number.

d2frdbg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the radio button object as type text.

d2frdbg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the radio button object as type text.

d2frdbg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the radio button object as type object.

d2frdbg_prmpt( ctx, obj, val );

This macro returns the value of the Prompt property of the radio button object as type text.

d2frdbg_prmpt_align( ctx, obj, val );

This macro returns the value of the Prompt Alignment property of the radio button object as type number.

d2frdbg_prmpt_align_ofst( ctx, obj, val );

This macro returns the value of the Prompt Alignment Offset property of the radio button object as type number.

d2frdbg_prmpt_att_edge( ctx, obj, val );

This macro returns the value of the Prompt Attachment Edge property of the radio button object as type number.

d2frdbg_prmpt_att_ofst( ctx, obj, val );

This macro returns the value of the Prompt Attachment Offset property of the radio button object as type number.

d2frdbg_prmpt_back_color( ctx, obj, val );

This macro returns the value of the Prompt Background Color property of the radio button object as type text.

d2frdbg_prmpt_disp_sty( ctx, obj, val );

This macro returns the value of the Prompt Display Style property of the radio button object as type number.

d2frdbg_prmpt_fill_pat( ctx, obj, val );

This macro returns the value of the Prompt Fill Pattern property of the radio button object as type text.

d2frdbg_prmpt_font_nam( ctx, obj, val );

This macro returns the value of the Prompt Font Name property of the radio button object as type text.

d2frdbg_prmpt_font_siz( ctx, obj, val );

This macro returns the value of the Prompt Font Size property of the radio button object as type number.

d2frdbg_prmpt_font_spcing( ctx, obj, val );

This macro returns the value of the Prompt Font Spacing property of the radio button object as type number.

d2frdbg_prmpt_font_sty( ctx, obj, val );

This macro returns the value of the Prompt Font Style property of the radio button object as type number.

d2frdbg_prmpt_font_wght( ctx, obj, val );

This macro returns the value of the Prompt Font Weight property of the radio button object as type number.

d2frdbg_prmpt_fore_color( ctx, obj, val );

This macro returns the value of the Prompt Foreground Color property of the radio button object as type text.

d2frdbg_prmpt_jst( ctx, obj, val );

This macro returns the value of the Prompt Justification property of the radio button object as type number.

d2frdbg_prmpt_reading_ordr( ctx, obj, val );

This macro returns the value of the Prompt Reading Order property of the radio button object as type number.

d2frdbg_prmpt_vat_nam( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_VAT_NAM property of the radio button object as type text.

d2frdbg_prmpt_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_VAT_OBJ property of the radio button object as type object.

d2frdbg_rdb_val( ctx, obj, val );

This macro returns the value of the Radio Button Value property of the radio button object as type text.

d2frdbg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the radio button object as type object.

d2frdbg_vat_nam( ctx, obj, val );

This macro returns the value of the Visual Attribute Group property of the radio button object as type text.

d2frdbg_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_VAT_OBJ property of the radio button object as type object.

d2frdbg_visible( ctx, obj, val );

This macro returns the value of the Visible property of the radio button object as type boolean.

d2frdbg_white_on_black( ctx, obj, val );

This macro returns the value of the White on Black property of the radio button object as type boolean.

d2frdbg_width( ctx, obj, val );

This macro returns the value of the Width/Height property of the radio button object as type number.

d2frdbg_x_pos( ctx, obj, val );

This macro returns the value of the X Position/Y Position property of the radio button object as type number.

d2frdbg_y_pos( ctx, obj, val );

This macro returns the value of the X Position/Y Position property of the radio button object as type number.

d2frdbs_access_key( ctx, obj, val );

This macro sets the value of the Access Key property of the radio button object.

d2frdbs_back_color( ctx, obj, val );

This macro sets the value of the Background Color property of the radio button object.

d2frdbs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the radio button object.

d2frdbs_comment( ctx, obj, val );

This macro sets the value of the Comments property of the radio button object.

d2frdbs_dist_btwn_recs( ctx, obj, val );

This macro sets the value of the Distance Between Records property of the radio button object.

d2frdbs_enabled( ctx, obj, val );

This macro sets the value of the Enabled property of the radio button object.

d2frdbs_fill_pat( ctx, obj, val );

This macro sets the value of the Fill Pattern property of the radio button object.

d2frdbs_font_nam( ctx, obj, val );

This macro sets the value of the Font Name property of the radio button object.

d2frdbs_font_siz( ctx, obj, val );

This macro sets the value of the Font Size property of the radio button object.

d2frdbs_font_spcing( ctx, obj, val );

This macro sets the value of the Font Spacing property of the radio button object.

d2frdbs_font_sty( ctx, obj, val );

This macro sets the value of the Font Style property of the radio button object.

d2frdbs_font_weight( ctx, obj, val );

This macro sets the value of the Font Weight property of the radio button object.

d2frdbs_fore_color( ctx, obj, val );

This macro sets the value of the Foreground Color property of the radio button object.

d2frdbs_height( ctx, obj, val );

This macro sets the value of the Width/Height property of the radio button object.

d2frdbs_label( ctx, obj, val );

This macro sets the value of the Label property of the radio button object.

d2frdbs_module( ctx, obj, val );

This macro sets the value of the D2FP_MODULE property of the radio button object.

d2frdbs_name( ctx, obj, val );

This macro sets the value of the Name property of the radio button object.

d2frdbs_next( ctx, obj, val );

This macro sets the value of the D2FP_NEXT property of the radio button object.

d2frdbs_owner( ctx, obj, val );

This macro sets the value of the D2FP_OWNER property of the radio button object.

d2frdbs_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the radio button object.

d2frdbs_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the radio button object.

d2frdbs_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the radio button object.

d2frdbs_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the radio button object.

d2frdbs_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the radio button object.

d2frdbs_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the radio button object.

d2frdbs_previous( ctx, obj, val );

This macro sets the value of the D2FP_PREVIOUS property of the radio button object.

d2frdbs_prmpt( ctx, obj, val );

This macro sets the value of the Prompt property of the radio button object.

d2frdbs_prmpt_align( ctx, obj, val );

This macro sets the value of the Prompt Alignment property of the radio button object.

d2frdbs_prmpt_align_ofst( ctx, obj, val );

This macro sets the value of the Prompt Alignment Offset property of the radio button object.

d2frdbs_prmpt_att_edge( ctx, obj, val );

This macro sets the value of the Prompt Attachment Edge property of the radio button object.

d2frdbs_prmpt_att_ofst( ctx, obj, val );

This macro sets the value of the Prompt Attachment Offset property of the radio button object.

d2frdbs_prmpt_back_color( ctx, obj, val );

This macro sets the value of the Prompt Background Color property of the radio button object.

d2frdbs_prmpt_disp_sty( ctx, obj, val );

This macro sets the value of the Prompt Display Style property of the radio button object.

d2frdbs_prmpt_fill_pat( ctx, obj, val );

This macro sets the value of the Prompt Fill Pattern property of the radio button object.

d2frdbs_prmpt_font_nam( ctx, obj, val );

This macro sets the value of the Prompt Font Name property of the radio button object.

d2frdbs_prmpt_font_siz( ctx, obj, val );

This macro sets the value of the Prompt Font Size property of the radio button object.

d2frdbs_prmpt_font_spcing( ctx, obj, val );

This macro sets the value of the Prompt Font Spacing property of the radio button object.

d2frdbs_prmpt_font_sty( ctx, obj, val );

This macro sets the value of the Prompt Font Style property of the radio button object.

d2frdbs_prmpt_font_wght( ctx, obj, val );

This macro sets the value of the Prompt Font Weight property of the radio button object.

d2frdbs_prmpt_fore_color( ctx, obj, val );

This macro sets the value of the Prompt Foreground Color property of the radio button object.

d2frdbs_prmpt_jst( ctx, obj, val );

This macro sets the value of the Prompt Justification property of the radio button object.

d2frdbs_prmpt_reading_ordr( ctx, obj, val );

This macro sets the value of the Prompt Reading Order property of the radio button object.

d2frdbs_prmpt_vat_nam( ctx, obj, val );

This macro sets the value of the D2FP_PRMPT_VAT_NAM property of the radio button object.

d2frdbs_prmpt_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_PRMPT_VAT_OBJ property of the radio button object.

d2frdbs_rdb_val( ctx, obj, val );

This macro sets the value of the Radio Button Value property of the radio button object.

d2frdbs_source( ctx, obj, val );

This macro sets the value of the D2FP_SOURCE property of the radio button object.

d2frdbs_vat_nam( ctx, obj, val );

This macro sets the value of the Visual Attribute Group property of the radio button object.

d2frdbs_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_VAT_OBJ property of the radio button object.

d2frdbs_visible( ctx, obj, val );

This macro sets the value of the Visible property of the radio button object.

d2frdbs_white_on_black( ctx, obj, val );

This macro sets the value of the White on Black property of the radio button object.

d2frdbs_width( ctx, obj, val );

This macro sets the value of the Width/Height property of the radio button object.

d2frdbs_x_pos( ctx, obj, val );

This macro sets the value of the X Position/Y Position property of the radio button object.

d2frdbs_y_pos( ctx, obj, val );

This macro sets the value of the X Position/Y Position property of the radio button object.


Record group object macros

  Related Topics

This section describes the macros of the Form Builder Open API Record Group object.

d2frcgg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the record group object as a type dvoid pointer.

d2frcgg_col_spec( ctx, obj, val );

This macro returns the value of the D2FP_COL_SPEC property of the record group object as type object.

d2frcgg_comment( ctx, obj, val );

This macro returns the value of the D2FP_COMMENT property of the record group object as type text.

d2frcgg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the record group object as type object.

d2frcgg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the record group object as type text.

d2frcgg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the record group object as type object.

d2frcgg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the record group object as type object.

d2frcgg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the record group object as type text.

d2frcgg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the record group object as type text.

d2frcgg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the record group object as type number.

d2frcgg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the record group object as type number.

d2frcgg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the record group object as type text.

d2frcgg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the record group object as type text.

d2frcgg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the record group object as type object.

d2frcgg_rec_grp_fetch_siz( ctx, obj, val );

This macro returns the value of the D2FP_REC_GRP_FETCH_SIZ property of the record group object as type number.

d2frcgg_rec_grp_qry( ctx, obj, val );

This macro returns the value of the D2FP_REC_GRP_QRY property of the record group object as type text.

d2frcgg_rec_grp_typ( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the record group object as type number.

d2frcgg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the record group object as type object.

d2frcgs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the record group object.

d2frcgs_comment( ctx, obj, val );

This macro sets the value of the D2FP_COMMENT property of the record group object.

d2frcgs_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the record group object.

d2frcgs_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the record group object.

d2frcgs_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the record group object.

d2frcgs_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the record group object.

d2frcgs_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the record group object.

d2frcgs_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the record group object.

d2frcgs_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the record group object.

d2frcgs_rec_grp_fetch_siz( ctx, obj, val );

This macro sets the value of the D2FP_REC_GRP_FETCH_SIZ property of the record group object.

d2frcgs_rec_grp_qry( ctx, obj, val );

This macro sets the value of the D2FP_REC_GRP_QRY property of the record group object.

d2frcgs_rec_grp_typ( ctx, obj, val );

This macro sets the value of the D2FP_REC_GRP_TYP property of the record group object.


Record group column specification object macros

  Related Topics

This section describes the macros of the Form Builder Open API Record Group Column Specification object.

d2frcsg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the record group column specification object as a type dvoid pointer.

d2frcsg_col_dat_typ( ctx, obj, val );

This macro returns the value of the D2FP_COL_DAT_TYP property of the record group column specification object as type number.

d2frcsg_col_vals_count( ctx, obj, val );

This macro returns the value of the D2FP_COL_VALS_COUNT property of the record group column specification object as type number.

d2frcsg_max_len( ctx, obj, val );

This macro returns the value of the D2FP_MAX_LEN property of the record group column specification object as type number.

d2frcsg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the record group column specification object as type text.

d2frcsg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the record group column specification object as type object.

d2frcsg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the record group column specification object as type object.

d2frcss_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the record group column specification object.

d2frcss_col_dat_typ( ctx, obj, val );

This macro sets the value of the D2FP_COL_DAT_TYP property of the record group column specification object.

d2frcss_max_len( ctx, obj, val );

This macro sets the value of the D2FP_MAX_LEN property of the record group column specification object.

d2frcss_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the record group column specification object.


Relation object macros

  Related Topics

This section describes the macros of the Form Builder Open API Relation object.

d2frelg_auto_qry( ctx, obj, val );

This macro returns the value of the D2FP_AUTO_QRY property of the relation object as type boolean.

d2frelg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the relation object as a type dvoid pointer.

d2frelg_comment( ctx, obj, val );

This macro returns the value of the D2FP_COMMENT property of the relation object as type text.

d2frelg_deferred( ctx, obj, val );

This macro returns the value of the D2FP_DEFERRED property of the relation object as type boolean.

d2frelg_del_rec( ctx, obj, val );

This macro returns the value of the D2FP_DEL_REC property of the relation object as type number.

d2frelg_detail_blk( ctx, obj, val );

This macro returns the value of the D2FP_DETAIL_BLK property of the relation object as type text.

d2frelg_join_cond( ctx, obj, val );

This macro returns the value of the D2FP_JOIN_COND property of the relation object as type text.

d2frelg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the relation object as type object.

d2frelg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the relation object as type text.

d2frelg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the relation object as type object.

d2frelg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the relation object as type object.

d2frelg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the relation object as type object.

d2frelg_prvnt_mstrless_ops( ctx, obj, val );

This macro returns the value of the D2FP_PRVNT_MSTRLESS_OPS property of the relation object as type boolean.

d2frelg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the relation object as type object.

d2frels_auto_qry( ctx, obj, val );

This macro sets the value of the D2FP_AUTO_QRY property of the relation object.

d2frels_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the relation object.

d2frels_comment( ctx, obj, val );

This macro sets the value of the D2FP_COMMENT property of the relation object.

d2frels_deferred( ctx, obj, val );

This macro sets the value of the D2FP_DEFERRED property of the relation object.

d2frels_del_rec( ctx, obj, val );

This macro sets the value of the D2FP_DEL_REC property of the relation object.

d2frels_detail_blk( ctx, obj, val );

This macro sets the value of the D2FP_DETAIL_BLK property of the relation object.

d2frels_join_cond( ctx, obj, val );

This macro sets the value of the D2FP_JOIN_COND property of the relation object.

d2frels_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the relation object.

d2frels_prvnt_mstrless_ops( ctx, obj, val );

This macro sets the value of the D2FP_PRVNT_MSTRLESS_OPS property of the relation object.


Report object macros

  Related Topics

This section describes the macros of the Form Builder Open API Report object.

d2frptg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the report object as a type dvoid pointer.

d2frptg_comm_mode( ctx, obj, val );

This macro returns the value of the D2FP_COMM_MODE property of the report object as type number.

d2frptg_comment( ctx, obj, val );

This macro returns the value of the D2FP_COMMENT property of the report object as type text.

d2frptg_dat_src_blk( ctx, obj, val );

This macro returns the value of the D2FP_DAT_SRC_BLK property of the report object as type text.

d2frptg_exec_mode( ctx, obj, val );

This macro returns the value of the D2FP_EXEC_MODE property of the report object as type number.

d2frptg_flnam( ctx, obj, val );

This macro returns the value of the D2FP_FLNAM property of the report object as type text.

d2frptg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the report object as type object.

d2frptg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the report object as type text.

d2frptg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the report object as type object.

d2frptg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the report object as type object.

d2frptg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the report object as type object.

d2frptg_rpt_destination_fmt( ctx, obj, val );

This macro returns the value of the D2FP_RPT_DESTINATION_FMT property of the report object as type text.

d2frptg_rpt_destination_nam( ctx, obj, val );

This macro returns the value of the D2FP_ RPT_DESTINATION_NAM property of the report object as type text.

d2frptg_rpt_destination_typ( ctx, obj, val );

This macro returns the value of the D2FP_ RPT_DESTINATION_TYP property of the report object as type number.

d2frptg_rpt_params( ctx, obj, val );

This macro returns the value of the D2FP_RPT_PARAMS property of the report object as type text.

d2frptg_rpt_srvr( ctx, obj, val );

This macro returns the value of the D2FP_RPT_SRVR property of the report object as type text.

d2frptg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the report object as type object.

d2frpts_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the report object.

d2frpts_comm_mode( ctx, obj, val );

This macro sets the value of the D2FP_COMM_MODE property of the report object.

d2frpts_comment( ctx, obj, val );

This macro sets the value of the D2FP_COMMENT property of the report object.

d2frpts_dat_src_blk( ctx, obj, val );

This macro sets the value of the D2FP_DAT_SRC_BLK property of the report object.

d2frpts_exec_mode( ctx, obj, val );

This macro sets the value of the D2FP_EXEC_MODE property of the report object.

d2frpts_flnam( ctx, obj, val );

This macro sets the value of the D2FP_FLNAM property of the report object.

d2frpts_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the report object.

d2frpts_rpt_destination_fmt( ctx, obj, val );

This macro sets the value of the D2FP_RPT_DESTINATION_FMT property of the report object.

d2frpts_rpt_destination_nam( ctx, obj, val );

This macro sets the value of the D2FP_RPT_DESTINATION_NAM property of the report object.

d2frpts_rpt_destination_typ( ctx, obj, val );

This macro sets the value of the D2FP_RPT_DESTINATION_TYP property of the report object.

d2frpts_rpt_params( ctx, obj, val );

This macro sets the value of the D2FP_RPT_PARAMS property of the report object.

d2frpts_rpt_srvr( ctx, obj, val );

This macro sets the value of the D2FP_RPT_SRVR property of the report object.


Tab page object macros

  Related Topics

This section describes the macros of the Form Builder Open API Tab Page object.

d2ftbpg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the tab page object as a type dvoid pointer.

d2ftbpg_comment( ctx, obj, val );

This macro returns the value of the D2FP_COMMENT property of the tab page object as type text.

d2ftbpg_enabled( ctx, obj, val );

This macro returns the value of the D2FP_ENABLED property of the tab page object as type boolean.

d2ftbpg_graphic( ctx, obj, val );

This macro returns the value of the D2FP_GRAPHIC property of the tab page object as type object.

d2ftbpg_label( ctx, obj, val );

This macro returns the value of the D2FP_LABEL property of the tab page object as type text.

d2ftbpg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the tab page object as type object.

d2ftbpg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the tab page object as type text.

d2ftbpg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the tab page object as type object.

d2ftbpg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the tab page object as type object.

d2ftbpg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the tab page object as type object.

d2ftbpg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the tab page object as type object.

d2ftbpg_visible( ctx, obj, val );

This macro returns the value of the D2FP_VISIBLE property of the tab page boolean.

d2ftbps_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the tab page object.

d2ftbps_comment( ctx, obj, val );

This macro sets the value of the D2FP_COMMENT property of the tab page object.

d2ftbps_enabled( ctx, obj, val );

This macro sets the value of the D2FP_ENABLED property of the tab page object.

d2ftbps_label( ctx, obj, val );

This macro sets the value of the D2FP_LABEL property of the tab page object.

d2ftbps_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the tab page object.

d2ftbps_visible( ctx, obj, val );

This macro sets the value of the D2FP_VISIBLE property of the tab page object.


Trigger object macros

  Related Topics

This section describes the macros of the Form Builder Open API Trigger object.

d2ftrgg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the trigger object as a type dvoid pointer.

d2ftrgg_comment( ctx, obj, val );

This macro returns the value of the D2FP_COMMENT property of the trigger object as type text.

d2ftrgg_disp_in_kbrd_hlp( ctx, obj, val );

This macro returns the value of the D2FP_DISP_IN_KBRD_HLP property of the trigger object as type boolean.

d2ftrgg_exec_hierarchy( ctx, obj, val );

This macro returns the value of the D2FP_EXEC_HIERARCHY property of the trigger object as type number.

d2ftrgg_fire_in_qry( ctx, obj, val );

This macro returns the value of the D2FP_FIRE_IN_QRY property of the trigger object as type boolean.

d2ftrgg_kbrd_hlp_txt( ctx, obj, val );

This macro returns the value of the D2FP_KBRD_HLP_TXT property of the trigger object as type text.

d2ftrgg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the trigger object as type object.

d2ftrgg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the trigger object as type text.

d2ftrgg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the trigger object as type object.

d2ftrgg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the trigger object as type object.

d2ftrgg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the trigger object as type text.

d2ftrgg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the trigger object as type text.

d2ftrgg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the trigger object as type number.

d2ftrgg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAT_MODTYP property of the trigger object as type number.

d2ftrgg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the trigger object as type text.

d2ftrgg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the trigger object as type text.

d2ftrgg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the trigger object as type object.

d2ftrgg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the trigger object as type object.

d2ftrgg_trg_sty( ctx, obj, val );

This macro returns the value of the D2FP_TRG_STY property of the trigger object as type number.

d2ftrgg_trg_txt( ctx, obj, val );

This macro returns the value of the D2FP_TRG_TXT property of the trigger object as type text.

d2ftrgg_trg_typ( ctx, obj, val );

This macro returns the value of the D2FP_TRG_TYP property of the trigger object as type number.

d2ftrgs_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the trigger object.

d2ftrgs_comment( ctx, obj, val );

This macro sets the value of the D2FP_COMMENT property of the trigger object.

d2ftrgs_disp_in_kbrd_hlp( ctx, obj, val );

This macro sets the value of the D2FP_DISP_IN_KBRD_HLP property of the trigger object.

d2ftrgs_exec_hierarchy( ctx, obj, val );

This macro sets the value of the D2FP_EXEC_HIERARCHY property of the trigger object.

d2ftrgs_fire_in_qry( ctx, obj, val );

This macro sets the value of the D2FP_FIRE_IN_QRY property of the trigger object.

d2ftrgs_kbrd_hlp_txt( ctx, obj, val );

This macro sets the value of the D2FP_KBRD_HLP_TXT property of the trigger object.

d2ftrgs_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the trigger object.

d2ftrgs_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the trigger object.

d2ftrgs_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the trigger object.

d2ftrgs_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the trigger object.

d2ftrgs_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the trigger object.

d2ftrgs_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the trigger object.

d2ftrgs_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the trigger object.

d2ftrgs_trg_sty( ctx, obj, val );

This macro sets the value of the D2FP_TRG_STY property of the trigger object.

d2ftrgs_trg_txt( ctx, obj, val );

This macro sets the value of the D2FP_TRG_TXT property of the trigger object.

d2ftrgs_trg_typ( ctx, obj, val );

This macro sets the value of the D2FP_TRG_TYP property of the trigger object.


Visual attribute object macros

  Related Topics

This section describes the macros of the Form Builder Open API Visual Attribute object.

d2fvatg_back_color( ctx, obj, val );

This macro returns the value of the D2FP_BACK_COLOR property of the visual attribute object as type text.

d2fvatg_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the visual attribute object as a type dvoid pointer.

d2fvatg_comment( ctx, obj, val );

This macro returns the value of the D2FP_COMMENT property of the visual attribute object as type text.

d2fvatg_fill_pat( ctx, obj, val );

This macro returns the value of the D2FP_FILL_PAT property of the visual attribute object as type text.

d2fvatg_font_nam( ctx, obj, val );

This macro returns the value of the D2FP_FONT_NAM property of the visual attribute object as type text.

d2fvatg_font_siz( ctx, obj, val );

This macro returns the value of the D2FP_FONT_SIZ property of the visual attribute object as type number.

d2fvatg_font_spcing( ctx, obj, val );

This macro returns the value of the D2FP_FONT_SPCING property of the visual attribute object as type number.

d2fvatg_font_sty( ctx, obj, val );

This macro returns the value of the D2FP_FONT_STY property of the visual attribute object as type number.

d2fvatg_font_wgth( ctx, obj, val );

This macro returns the value of the D2FP_FONT_WGHT property of the visual attribute object as type number.

d2fvatg_fore_color( ctx, obj, val );

This macro returns the value of the D2FP_FORE_COLOR property of the visual attribute object as type text.

d2fvatg_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the visual attribute object as type object.

d2fvatg_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the visual attribute object as type text.

d2fvatg_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the visual attribute object as type object.

d2fvatg_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the visual attribute object as type object.

d2fvatg_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the visual attribute object as type text.

d2fvatg_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the visual attribute object as type text.

d2fvatg_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the visual attribute object as type number.

d2fvatg_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the visual attribute object as type number.

d2fvatg_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the visual attribute object as type text.

d2fvatg_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the visual attribute object as type text.

d2fvatg_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the visual attribute object as type object.

d2fvatg_prmpt_back_color( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_BACK_COLOR property of the visual attribute object as type text.

d2fvatg_prmpt_fill_pat( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_FILL_PAT property of the visual attribute object as type text.

d2fvatg_prmpt_font_nam( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_FONT_NAM property of the visual attribute object as type text.

d2fvatg_prmpt_font_siz( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_FONT_SIZ property of the visual attribute object as type number.

d2fvatg_prmpt_font_spcing( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_FONT_SPCING property of the visual attribute object as type number.

d2fvatg_prmpt_font_sty( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_FONT_STY property of the visual attribute object as type number.

d2fvatg_prmpt_font_wght( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_FONT_WGHT property of the visual attribute object as type number.

d2fvatg_prmpt_fore_color( ctx, obj, val );

This macro returns the value of the D2FP_PRMPT_FORE_COLOR property of the visual attribute object as type text.

d2fvatg_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the visual attribute object as type object.

d2fvatg_vat_typ( ctx, obj, val );

This macro returns the value of the D2FP_VAT_TYP property of the visual attribute object as type number.

d2fvatg_white_on_black( ctx, obj, val );

This macro returns the value of the D2FP_WHITE_ON_BLACK property of the visual attribute object as type boolean.

d2fvats_back_color( ctx, obj, val );

This macro sets the value of the D2FP_BACK_COLOR property of the visual attribute object.

d2fvats_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the visual attribute object.

d2fvats_comment( ctx, obj, val );

This macro sets the value of the D2FP_COMMENT property of the visual attribute object.

d2fvats_fill_pat( ctx, obj, val );

This macro sets the value of the D2FP_FILL_PAT property of the visual attribute object.

d2fvats_font_nam( ctx, obj, val );

This macro sets the value of the D2FP_FONT_NAM property of the visual attribute object.

d2fvats_font_siz( ctx, obj, val );

This macro sets the value of the D2FP_FONT_SIZ property of the visual attribute object.

d2fvats_font_spcing( ctx, obj, val );

This macro sets the value of the D2FP_FONT_SPCING property of the visual attribute object.

d2fvats_font_sty( ctx, obj, val );

This macro sets the value of the D2FP_FONT_STY property of the visual attribute object.

d2fvats_font_wght( ctx, obj, val );

This macro sets the value of the D2FP_FONT_WGHT property of the visual attribute object.

d2fvats_fore_color( ctx, obj, val );

This macro sets the value of the D2FP_FORE_COLOR property of the visual attribute object.

d2fvats_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the visual attribute object.

d2fvats_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the visual attribute object.

d2fvats_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the visual attribute object.

d2fvats_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the visual attribute object.

d2fvats_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the visual attribute object.

d2fvats_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the visual attribute object.

d2fvats_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the visual attribute object.

d2fvats_prmpt_back_color( ctx, obj, val );

This macro sets the value of the D2FP_PROMPT_BACK_COLOR property of the visual attribute object.

d2fvats_prmpt_fill_pat( ctx, obj, val );

This macro sets the value of the D2FP_PROMPT_FILL_PAT property of the visual attribute object.

d2fvats_prmpt_font_nam( ctx, obj, val );

This macro sets the value of the D2FP_PROMPT_FONT_NAM property of the visual attribute object.

d2fvats_prmpt_font_siz( ctx, obj, val );

This macro sets the value of the D2FP_PROMPT_FONT_SIZ property of the visual attribute object.

d2fvats_prmpt_font_spcing( ctx, obj, val );

This macro sets the value of the D2FP_PROMPT_FONT_SPCING property of the visual attribute object.

d2fvats_prmpt_font_sty( ctx, obj, val );

This macro sets the value of the D2FP_PROMPT_FONT_STY property of the visual attribute object.

d2fvats_prmpt_font_wght( ctx, obj, val );

This macro sets the value of the D2FP_PROMPT_FONT_WGHT property of the visual attribute object.

d2fvats_prmpt_fore_color( ctx, obj, val );

This macro sets the value of the D2FP_PROMPT_FORE_COLOR property of the visual attribute object.

d2fvats_vat_typ( ctx, obj, val );

This macro sets the value of the D2FP_VAT_TYP property of the visual attribute object.

d2fvats_white_on_black( ctx, obj, val );

This macro sets the value of the D2FP_WHITE_ON_BLACK property of the visual attribute object.


Window object macros

  Related Topics

This section describes the macros of the Form Builder Open API Window object.

d2fwing_back_color( ctx, obj, val );

This macro returns the value of the D2FP_BACK_COLOR property of the window object as type text.

d2fwing_bevel( ctx, obj, val );

This macro returns the value of the D2FP_BEVEL property of the window object as type number.

d2fwing_client_info( ctx, obj, val );

This macro returns the value of the D2FP_CLIENT_INFO property of the window object as a type dvoid pointer.

d2fwing_cls_allowed( ctx, obj, val );

This macro returns the value of the D2FP_CLS_ALLOWED property of the window object as type boolean.

d2fwing_comment( ctx, obj, val );

This macro returns the value of the D2FP_COMMENT property of the window object as type text.

d2fwing_fill_pat( ctx, obj, val );

This macro returns the value of the D2FP_FILL_PAT property of the window object as type text.

d2fwing_font_nam( ctx, obj, val );

This macro returns the value of the D2FP_FONT_NAM property of the window object as type text.

d2fwing_font_siz( ctx, obj, val );

This macro returns the value of the D2FP_FONT_SIZ property of the window object as type number.

d2fwing_font_spcing( ctx, obj, val );

This macro returns the value of the D2FP_FONT_SPCING property of the window object as type number.

d2fwing_font_sty( ctx, obj, val );

This macro returns the value of the D2FP_FONT_STY property of the window object as type number.

d2fwing_font_wgth( ctx, obj, val );

This macro returns the value of the D2FP_FONT_WGHT property of the window object as type number.

d2fwing_fore_color( ctx, obj, val );

This macro returns the value of the D2FP_FORE_COLOR property of the window object as type text.

d2fwing_height( ctx, obj, val );

This macro returns the value of the D2FP_HEIGHT property of the window object as type number.

d2fwing_hide_on_exit( ctx, obj, val );

This macro returns the value of the D2FP_HIDE_ON_EXIT property of the window object as type boolean.

d2fwing_htb_cnv_name( ctx, obj, val );

This macro returns the value of the D2FP_HTB_CNV_NAME property of the window object as type text.

d2fwing_icon_flnam( ctx, obj, val );

This macro returns the value of the D2FP_ICON_FLNAM property of the window object as type text.

d2fwing_inhrt_mnu( ctx, obj, val );

This macro returns the value of the D2FP_INHRT_MNU property of the window object as type boolean.

d2fwing_lang_dir( ctx, obj, val );

This macro returns the value of the D2FP_LANG_DIR property of the window object as type number.

d2fwing_maximize_allowed( ctx, obj, val );

This macro returns the value of the D2FP_MAXIMIZE_ALLOWED property of the window object as type boolean.

d2fwing_minimize_allowed( ctx, obj, val );

This macro returns the value of the D2FP_MINIMIZE_ALLOWED property of the window object as type boolean.

d2fwing_minimize_ttl( ctx, obj, val );

This macro returns the value of the D2FP_MINIMIZE_TTL property of the window object as type text.

d2fwing_modal( ctx, obj, val );

This macro returns the value of the D2FP_MODAL property of the window object as type boolean.

d2fwing_module( ctx, obj, val );

This macro returns the value of the D2FP_MODULE property of the window object as type object.

d2fwing_mv_allowed( ctx, obj, val );

This macro returns the value of the D2FP_MV_ALLOWED property of the window object as type boolean.

d2fwing_name( ctx, obj, val );

This macro returns the value of the D2FP_NAME property of the window object as type text.

d2fwing_next( ctx, obj, val );

This macro returns the value of the D2FP_NEXT property of the window object as type object.

d2fwing_owner( ctx, obj, val );

This macro returns the value of the D2FP_OWNER property of the window object as type object.

d2fwing_par_flnam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLNAM property of the window object as type text.

d2fwing_par_flpath( ctx, obj, val );

This macro returns the value of the D2FP_PAR_FLPATH property of the window object as type text.

d2fwing_par_modstr( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODSTR property of the window object as type number.

d2fwing_par_modtyp( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODTYP property of the window object as type number.

d2fwing_par_module( ctx, obj, val );

This macro returns the value of the D2FP_PAR_MODULE property of the window object as type text.

d2fwing_par_nam( ctx, obj, val );

This macro returns the value of the D2FP_PAR_NAM property of the window object as type text.

d2fwing_previous( ctx, obj, val );

This macro returns the value of the D2FP_PREVIOUS property of the window object as type object.

d2fwing_prmry_cnv( ctx, obj, val );

This macro returns the value of the D2FP_PRMRY_CNV property of the window object as type text.

d2fwing_resize_allowed( ctx, obj, val );

This macro returns the value of the D2FP_RESIZE_ALLOWED property of the window object as type boolean.

d2fwing_show_horz_scrlbr( ctx, obj, val );

This macro returns the value of the D2FP_SHOW_HORZ_SCRLBR property of the window object as type boolean.

d2fwing_show_vert_scrlbr( ctx, obj, val );

This macro returns the value of the D2FP_SHOW_VERT_SCRLBR property of the window object as type boolean.

d2fwing_source( ctx, obj, val );

This macro returns the value of the D2FP_SOURCE property of the window object as type object.

d2fwing_title( ctx, obj, val );

This macro returns the value of the D2FP_TITLE property of the window object as type text.

d2fwing_vat_nam( ctx, obj, val );

This macro returns the value of the D2FP_VAT_NAM property of the window object as type text.

d2fwing_vat_obj( ctx, obj, val );

This macro returns the value of the D2FP_VAT_OBJ property of the window object as type object.

d2fwing_vtb_cnv_name( ctx, obj, val );

This macro returns the value of the D2FP_VTB_CNV_NAME property of the window object as type text.

d2fwing_white_on_black( ctx, obj, val );

This macro returns the value of the D2FP_WHITE_ON_BLACK property of the window object as type boolean.

d2fwing_width( ctx, obj, val );

This macro returns the value of the D2FP_WIDTH property of the window object as type number.

d2fwing_win_sty( ctx, obj, val );

This macro returns the value of the D2FP_WIN_STY property of the window object as type number.

d2fwing_x_pos( ctx, obj, val );

This macro returns the value of the D2FP_X_POS property of the window object as type number.

d2fwing_y_pos( ctx, obj, val );

This macro returns the value of the D2FP_Y_POS property of the window object as type number.

d2fwins_back_color ( ctx, obj, val );

This macro sets the value of the D2FP_BACK_COLOR property of the window object.

d2fwins_bevel( ctx, obj, val );

This macro sets the value of the D2FP_BEVEL property of the window object.

d2fwins_client_info( ctx, obj, val );

This macro sets the value of the D2FP_CLIENT_INFO property of the window object.

d2fwins_cls_allowed( ctx, obj, val );

This macro sets the value of the D2FP_CLS_ALLOWED property of the window object.

d2fwins_comment( ctx, obj, val );

This macro sets the value of the D2FP_COMMENT property of the window object.

d2fwins_fill_pat( ctx, obj, val );

This macro sets the value of the D2FP_FILL_PAT property of the window object.

d2fwins_font_nam( ctx, obj, val );

This macro sets the value of the D2FP_FONT_NAM property of the window object.

d2fwins_font_siz( ctx, obj, val );

This macro sets the value of the D2FP_FONT_SIZ property of the window object.

d2fwins_font_spcing( ctx, obj, val );

This macro sets the value of the D2FP_FONT_SPCING property of the window object.

d2fwins_font_sty( ctx, obj, val );

This macro sets the value of the D2FP_FONT_STY property of the window object.

d2fwins_font_wght( ctx, obj, val );

This macro sets the value of the D2FP_FONT_WGHT property of the window object.

d2fwins_fore_color( ctx, obj, val );

This macro sets the value of the D2FP_FORE_COLOR property of the window object.

d2fwins_height( ctx, obj, val );

This macro sets the value of the D2FP_HEIGHT property of the window object.

d2fwins_hide_on_exit( ctx, obj, val );

This macro sets the value of the D2FP_HIDE_ON_EXIT property of the window object.

d2fwins_htb_cnv_name( ctx, obj, val );

This macro sets the value of the D2FP_HTB_CNV_NAME property of the window object.

d2fwins_icon_flname( ctx, obj, val );

This macro sets the value of the D2FP_ICON_FLNAME property of the window object.

d2fwins_inhrt_mnu( ctx, obj, val );

This macro sets the value of the D2FP_INHRT_MNU property of the window object.

d2fwins_lang_dir( ctx, obj, val );

This macro sets the value of the D2FP_LANG_DIR property of the window object.

d2fwins_maximize_allowed( ctx, obj, val );

This macro sets the value of the D2FP_MAXIMIZE_ALLOWED property of the window object.

d2fwins_minimize_allowed( ctx, obj, val );

This macro sets the value of the D2FP_MINIMIZE_ALLOWED property of the window object.

d2fwins_minimize_ttl( ctx, obj, val );

This macro sets the value of the D2FP_MINIMIZE_TTL property of the window object.

d2fwins_modal( ctx, obj, val );

This macro sets the value of the D2FP_MODAL property of the window object.

d2fwins_mv_allowed( ctx, obj, val );

This macro sets the value of the D2FP_MV_ALLOWED property of the window object.

d2fwins_name( ctx, obj, val );

This macro sets the value of the D2FP_NAME property of the window object.

d2fwins_par_flnam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLNAM property of the window object.

d2fwins_par_flpath( ctx, obj, val );

This macro sets the value of the D2FP_PAR_FLPATH property of the window object.

d2fwins_par_modstr( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODSTR property of the window object.

d2fwins_par_modtyp( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODTYP property of the window object.

d2fwins_par_module( ctx, obj, val );

This macro sets the value of the D2FP_PAR_MODULE property of the window object.

d2fwins_par_nam( ctx, obj, val );

This macro sets the value of the D2FP_PAR_NAM property of the window object.

d2fwins_prmry_cnv( ctx, obj, val );

This macro sets the value of the D2FP_PRMRY_CNV property of the window object.

d2fwins_resize_allowed( ctx, obj, val );

This macro sets the value of the D2FP_RESIZE_ALLOWED property of the window object.

d2fwins_show_horz_scrlbr( ctx, obj, val );

This macro sets the value of the D2FP_SHOW_HORZ_SCRLBR property of the window object.

d2fwins_show_vert_scrlbr( ctx, obj, val );

This macro sets the value of the D2FP_SHOW_VERT_SCRLBR property of the window object.

d2fwins_title( ctx, obj, val );

This macro sets the value of the D2FP_TITLE property of the window object.

d2fwins_vat_nam( ctx, obj, val );

This macro sets the value of the D2FP_VAT_NAM property of the window object.

d2fwins_vat_obj( ctx, obj, val );

This macro sets the value of the D2FP_VAT_OBJ property of the window object.

d2fwins_vtb_cnv_name( ctx, obj, val );

This macro sets the value of the D2FP_VTB_CNV_NAME property of the window object.

d2fwins_white_on_black( ctx, obj, val );

This macro sets the value of the D2FP_WHITE_ON_BLACK property of the window object.

d2fwins_width( ctx, obj, val );

This macro sets the value of the D2FP_WIDTH property of the window object.

d2fwins_win_sty( ctx, obj, val );

This macro sets the value of the D2FP_WIN_STY property of the window object.

d2fwins_x_pos( ctx, obj, val );

This macro sets the value of the D2FP_X_POS property of the window object.

d2fwins_y_pos( ctx, obj, val );

This macro sets the value of the D2FP_Y_POS property of the window object.


Creating modules using the Open API

 Examples	     Related Topics

To create a basic Form Builder module:

1	Include the appropriate C header files in your C source code.

2	Make calls to the desired Open API functions in your C source code.

A	Initialize the context structure.

B	Make "create" or "load" function calls to create a new form module, menu module, or object library, or open an existing one.

C	Make the necessary Open Forms API function calls to perform the desired operations, including connecting to an existing database, if required.

D	Generate an .FMX or .MMX compiled form using the appropriate "CompileFile()" function.

E	Make the required function calls to save the associated module (for example, d2ffmdsv_Save() for a form module, d2fmmdsv_Save() for a menu module, or d2folbsv_Save() for an object library).

F	Finally, call the context destroy function, d2fctxde_Destroy(), to destroy the Open Forms API context. Note that this function call must be your final one.

3	Link your source files against the Open API library (f60d2f32.lib).

4	Compile the files to create an executable.

5	Run the executable to create a Form Builder module.


Creating modules using the Open API examples

Example

/*

This example creates a master-detail form based on the dept and emp database tables owned by the user scott.  The master contains the following fields: empno, ename, job, sal, and deptno.  The detail contains the following fields deptno, dname, and loc.  The join condition is deptno.
*/
#include<stdio.h>
#include<string.h>
#include<windows.h>
#include<d2fctx.h>
#include<d2ffmd.h>
#include<d2ffpr.h>
#include<d2fob.h>
#include<d2fcnv.h>
#include<d2ftrg.h>
#include<d2blk.h>
#include<d2fitm.h>
#include<d2fwin.h>
#include<d2frel.h>

#define D2FS_SUCCESS 0
#define FAIL 1
#define BUFSIZE 128
#define WBP_TXT "null;\n"

int WINAPI WinMain(HANDLE hInstance,
                   HANDLE hPrevInstance,
                   LPSTR lpszCommandLine,
                   int cmdShow)
{
d2fctx  *pd2fctx;
d2ffmd  *pd2ffmd;
d2fcnv  *pd2fcnv;
d2fwin  *pd2fwin;

d2fblk  *pempblk;
d2fblk  *pdeptblk;
d2frel  *pd2frel;

d2fitm  *pEempnoitm;
d2fitm  *pEenameitm;
d2fitm  *pEjobitm;
d2fitm  *pEsalitm;

d2fitm  *pEdeptnoitm;
d2fitm  *pDdeptnoitm;
d2fitm  *pDdnameitm;
d2fitm  *pDlocitm;

text  *name = (text *)0;
text  *form_name = (text *)0;
d2fctxa  d2fctx_attr;
d2fstatus retval;
char buf[BUFSIZE];

/* Get form name */
strncpy(buf, "empdept", BUFSIZE);
form_name = (text*)strtok(buf, ".");

/* Initialize the attribute mask */
d2fctx_attr.mask_d2fctxa = 0;

/* for MS Windows-only attributes */
d2fctx_attr.d2fihnd_d2fctxa = hInstance;
d2fctx_attr.d2fphnd_d2fctxa = hPrevInstance;
d2fctx_attr.d2fcmsh_d2fctxa = cmdShow;

/* Create the API context */
status = d2fctxcr_Create(&pd2fctx, &d2fctx_attr);

/* Create the context */
d2fctxcn_Connect(pd2fctx, (text*)"scott/tiger@test");

/* Create the form */
d2ffmdcr_Create(pd2fctx, &pd2ffmd, form_name);

/* Create a window */
d2fwincr_Create(pd2fctx,pd2ffmd,&pd2fwin,(text*)"MYWIN");

/*** Create Canvas and set canvas-related properties ***/
/* Create a canvas */
d2fcnvcr_Create(pd2fctx, pd2ffmd, &pd2fcnv, (text*)"MYCANVAS");

/* Set viewport width */
d2fcnvs_vprt_wid(pd2fctx, pd2fcnv, 512);

/* Set viewport height */
d2fcnvs_vprt_hgt(pd2fctx, pd2fcnv, 403);

/* Set window */
dwfcnvs_wnd_obj(pd2fctx, pd2fcnv, pd2fwin);

/* Set viewport X-position */
d2fcnvs_vprt_x_pos(pd2fctx, pd2fcnv, 0);

/* Set viewport Y-position */
d2fcnvs_vprt_y_pos(pd2fctx, pd2fcnv, 0);

/* Set width */
d2fcnvs_width(pd2fctx, pd2fcnv, 538)

/* Set height */
d2fcnvs_height(pd2fctx, pd2fcnv, 403)

/*** Create Emp block and set block-related properties ***/
/* Create block */
d2fblkcr_Create(pd2fctx, pd2ffmd, &pempblk, (text*)"EMP");

/* Set to database block */
d2fblks_db_blk(pd2fctx, pempblk, TRUE);

/* Set query data source to Table */
d2fblks_qry_dat_src_typ(pd2fctx, pempblk, D2FC_QRDA_TABLE);

/* Set query data source name to EMP table */
d2fblks_qry_dat_src_nam(pd2fctx, pempblk, "EMP");

/* Set DML data source type to Table */
d2fblks_dml_dat_typ(Pd2fctx, pempblk, D2FC_DMDA_TABLE);

/* Set DML data source name to EMP table */
d2fblks_dml_dat_nam(pd2fctx, pempblk, (text*)"EMP");

/*** Create Dept block and set block-related properties ***/
/* Create block */
d2fblkcr_Create(pd2fctx, pd2ffmd, &pdeptblk, (text*)"DEPT");

/* Set to database block */
d2fblks_db_blk(pd2fctx, pdeptblk, TRUE);

/* Set query data source to Table */
d2fblks_qry_dat_src_typ(pd2fctx, pdeptblk, D2FC_QRDA_TABLE);

/* Set query data source name to EMP table */
d2fblks_qry_dat_src_nam(pd2fctx, pdeptblk, "DEPT");

/* Set DML data source type to Table */
d2fblks_dml_dat_typ(Pd2fctx, pdeptblk, D2FC_DMDA_TABLE);

/* Set DML data source name to EMP table */
d2fblks_dml_dat_nam(pd2fctx, pdeptblk, (text*)"DEPT");

/*** Create empno item and item-related properties ***/
/* Create item */
d2fitmcr_Create(pd2fctx, pempblk, &pEempnoitm, (text*)"EMPNO");

/* Set item type */
d2fitms_itm_type(pd2fctx, pEempnoitm, D2FC_ITTY_TI);

/* Set Enable property */
d2fitms_enabled(pd2fctx, pEempnoitm, TRUE);

/* Set item (keyboard) navigable property */
d2fitms_kbrd_navigable(pd2fctx, pEempnoitm, TRUE);

/* Set item Data Type property */
d2fitms_dat_typ(pd2fctx, pEempnoitm, D2FC_DATY_NUMBER);

/* Set item Max Length property */
d2fitms_max_len(pd2fctx, pEempnoitm, 6);

/* Set item Required property */
d2fitms_required(pd2fctx, pEempnoitm, TRUE);

/* Set Distance Between Records property */
d2fitms_dist_btwn_recs(pd2fctx, pEempnoitm, 0);

/* Set Database block(Database Item) property */
d2fitms_db_itm(pd2fctx, pEempnoitm, TRUE);

/* Set Query Allowed */
d2fitms_qry_allowed(pd2fctx, pEempnoitm, TRUE);

/* Set Query Length */
d2fitms_qry_len(pd2fctx, pEempnoitm, 6);

/* Set Update Allowed */
d2fitms_updt_allowed(pd2fctx, pEempnoitm, TRUE);

/* Set Item Displayed (Visible) */
d2fitms_visible(pd2fctx, pEempnoitm, TRUE);

/* Set Item Canvas property */
d2fitms_cnv_obj(pd2fctx, pEempnoitm, pd2fcnv);

/* Set Item X-position */
d2fitms_x_pos(pd2fctx, pEempnoitm, 32);

/* Set Item Y-position */
d2fitms_y_pos(pd2fctx, pEempnoitm, 50);

/* Set Item Width */
d2fitms_width(pd2fctx, pEempnoitm, 51);

/* Set Item Height */
d2fitms_height(pd2fctx, pEempnoitm, 17);

/* Set Item Bevel */
d2fitms_bevel(pd2fctx, pEempnoitm, D2FC_BEST_LOWERED);

/* Set item Hint */
d2fitms_hint(pd2fctx, PEempnoitm, (text*)"Enter value for :EMPNO");

/*** Create Ename item and item-related properties ***/
/* Create item */
d2fitmcr_Create(pd2fctx, pempblk, &pEenameitm, (text*)"ENAME");

/* Set item type */
d2fitms_itm_type(pd2fctx, pEenameitm, D2FC_ITTY_TI);

/* Set Enable property */
d2fitms_enabled(pd2fctx, pEenameitm, TRUE);

/* Set item (keyboard) navigable property */
d2fitms_kbrd_navigable(pd2fctx, pEenameitm, TRUE);

/* Set item Data Type property */
d2fitms_dat_typ(pd2fctx, pEenameitm, D2FC_DATY_CHAR);

/* Set item Max Length property */
d2fitms_max_len(pd2fctx, pEenameitm, 10);

/* Set Distance Between Records property */
d2fitms_dist_btwn_recs(pd2fctx, pEenameitm, 0);

/* Set Database block(Database Item) property */
d2fitms_db_itm(pd2fctx, pEenameitm, TRUE);

/* Set Query Allowed */
d2fitms_qry_allowed(pd2fctx, pEenameitm, TRUE);

/* Set Query Length */
d2fitms_qry_len(pd2fctx, pEenameitm, 10);

/* Set Update Allowed */
d2fitms_updt_allowed(pd2fctx, pEenameitm, TRUE);

/* Set Item Displayed (Visible) */
d2fitms_visible(pd2fctx, pEenameitm, TRUE);

/* Set Item Canvas property */
d2fitms_cnv_obj(pd2fctx, pEenameitm, pd2fcnv);

/* Set Item X-position */
d2fitms_x_pos(pd2fctx, pEenameitm, 83);

/* Set Item Y-position */
d2fitms_y_pos(pd2fctx, pEenameitm, 50);

/* Set Item Width */
d2fitms_width(pd2fctx, pEenameitm, 77);

/* Set Item Height */
d2fitms_height(pd2fctx, pEenameitm, 17);

/* Set Item Bevel */
d2fitms_bevel(pd2fctx, pEenameitm, D2FC_BEST_LOWERED);

/* Set item Hint */
d2fitms_hint(pd2fctx, PEenameitm, (text*)"Enter value for :ENAME");

/*** Create JOB item and item-related properties ***/
/* Create item */
d2fitmcr_Create(pd2fctx, pempblk, &pEjobitm, (text*)"JOB");

/* Set item type */
d2fitms_itm_type(pd2fctx, pEjobitm, D2FC_ITTY_TI);

/* Set Enable property */
d2fitms_enabled(pd2fctx, pEjobitm, TRUE);

/* Set item (keyboard) navigable property */
d2fitms_kbrd_navigable(pd2fctx, pEjobitm, TRUE);

/* Set item Data Type property */
d2fitms_dat_typ(pd2fctx, pEjobitm, D2FC_DATY_CHAR);

/* Set item Max Length property */
d2fitms_max_len(pd2fctx, pEjobitm, 9);

/* Set Distance Between Records property */
d2fitms_dist_btwn_recs(pd2fctx, pEjobitm, 0);

/* Set Database block(Database Item) property */
d2fitms_db_itm(pd2fctx, pEjobitm, TRUE);

/* Set Query Allowed */
d2fitms_qry_allowed(pd2fctx, pEjobitm, TRUE);

/* Set Query Length */
d2fitms_qry_len(pd2fctx, pEjobitm, 9);

/* Set Update Allowed */
d2fitms_updt_allowed(pd2fctx, pEjobitm, TRUE);

/* Set Item Displayed (Visible) */
d2fitms_visible(pd2fctx, pEjobitm, TRUE);

/* Set Item Canvas property */
d2fitms_cnv_obj(pd2fctx, pEjobitm, pd2fcnv);

/* Set Item X-position */
d2fitms_x_pos(pd2fctx, pEjobitm, 160);

/* Set Item Y-position */
d2fitms_y_pos(pd2fctx, pEjobitm, 50);

/* Set Item Width */
d2fitms_width(pd2fctx, pEjobitm, 70);

/* Set Item Height */
d2fitms_height(pd2fctx, pEjobitm, 17);

/* Set Item Bevel */
d2fitms_bevel(pd2fctx, pEjobitm, D2FC_BEST_LOWERED);

/* Set item Hint */
d2fitms_hint(pd2fctx, PEjobitm, (text*)"Enter value for :JOB");

/*** Create SALARY item and item-related properties ***/
/* Create item */
d2fitmcr_Create(pd2fctx, pempblk, &pEsalitm, (text*)"SAL");

/* Set item type */
d2fitms_itm_type(pd2fctx, pEsalitm, D2FC_ITTY_TI);

/* Set Enable property */
d2fitms_enabled(pd2fctx, pEsalitm, TRUE);

/* Set item (keyboard) navigable property */
d2fitms_kbrd_navigable(pd2fctx, pEsalitm, TRUE);

/* Set item Data Type property */
d2fitms_dat_typ(pd2fctx, pEsalitm, D2FC_DATY_NUMBER);

/* Set item Max Length property */
d2fitms_max_len(pd2fctx, pEsalitm, 9);

/* Set Distance Between Records property */
d2fitms_dist_btwn_recs(pd2fctx, pEsalitm, 0);

/* Set Database block(Database Item) property */
d2fitms_db_itm(pd2fctx, pEsalitm, TRUE);

/* Set Query Allowed */
d2fitms_qry_allowed(pd2fctx, pEsalitm, TRUE);

/* Set Query Length */
d2fitms_qry_len(pd2fctx, pEsalitm, 9);

/* Set Update Allowed */
d2fitms_updt_allowed(pd2fctx, pEsalitm, TRUE);

/* Set Item Displayed (Visible) */
d2fitms_visible(pd2fctx, pEsalitm, TRUE);

/* Set Item Canvas property */
d2fitms_cnv_obj(pd2fctx, pEsalitm, pd2fcnv);

/* Set Item X-position */
d2fitms_x_pos(pd2fctx, pEsalitm, 352);

/* Set Item Y-position */
d2fitms_y_pos(pd2fctx, pEsalitm, 50);

/* Set Item Width */
d2fitms_width(pd2fctx, pEsalitm, 70);

/* Set Item Height */
d2fitms_height(pd2fctx, pEsalitm, 17);

/* Set Item Bevel */
d2fitms_bevel(pd2fctx, pEsalitm, D2FC_BEST_LOWERED);

/* Set item Hint */
d2fitms_hint(pd2fctx, PEsalitm, (text*)"Enter value for :SAL");

/*** Create DEPTNO item and item-related properties ***/
/* Create item */
d2fitmcr_Create(pd2fctx, pempblk, &pEdeptnoitm, (text*)"DEPTNO");

/* Set item type */
d2fitms_itm_type(pd2fctx, pEdeptnoitm, D2FC_ITTY_TI);

/* Set Enable property */
d2fitms_enabled(pd2fctx, pEdeptnoitm, TRUE);

/* Set item (keyboard) navigable property */
d2fitms_kbrd_navigable(pd2fctx, pEdeptnoitm, TRUE);

/* Set item Data Type property */
d2fitms_dat_typ(pd2fctx, pEdeptnoitm, D2FC_DATY_NUMBER);

/* Set item Max Length property */
d2fitms_max_len(pd2fctx, pEdeptnoitm, 4);

/*Set item Required property */
d2fitms_required(pd2fctx, pEdeptnoitm, TRUE);

/* Set Distance Between Records property */
d2fitms_dist_btwn_recs(pd2fctx, pEdeptnoitm, 0);

/* Set Database block(Database Item) property */
d2fitms_db_itm(pd2fctx, pEdeptnoitm, TRUE);

/* Set Query Allowed */
d2fitms_qry_allowed(pd2fctx, pEdeptnoitm, TRUE);

/* Set Query Length */
d2fitms_qry_len(pd2fctx, pEdeptnoitm, 4);

/* Set Update Allowed */
d2fitms_updt_allowed(pd2fctx, pEdeptnoitm, TRUE);

/* Set Item Displayed (Visible) */
d2fitms_visible(pd2fctx, pEdeptnoitm, TRUE);

/* Set Item Canvas property */
d2fitms_cnv_obj(pd2fctx, pEdeptnoitm, pd2fcnv);

/* Set Item X-position */
d2fitms_x_pos(pd2fctx, pEdeptnoitm, 493);

/* Set Item Y-position */
d2fitms_y_pos(pd2fctx, pEdeptnoitm, 50);

/* Set Item Width */
d2fitms_width(pd2fctx, pEdeptnoitm, 30);

/* Set Item Height */
d2fitms_height(pd2fctx, pEdeptnoitm, 17);

/* Set Item Bevel */
d2fitms_bevel(pd2fctx, pEdeptnoitm, D2FC_BEST_LOWERED);

/* Set item Hint */
d2fitms_hint(pd2fctx, PEdeptnoitm, (text*)"Enter value for :DEPTNO");

/*** Create DEPTNO item and item-related properties ***/
/* Create item */
d2fitmcr_Create(pd2fctx, pdeptblk, &pDdeptnoitm, (text*)"DEPTNO");

/* Set item type */
d2fitms_itm_type(pd2fctx, pDdeptnoitm, D2FC_ITTY_TI);

/* Set Enable property */
d2fitms_enabled(pd2fctx, pDdeptnoitm, TRUE);

/* Set item (keyboard) navigable property */
d2fitms_kbrd_navigable(pd2fctx, pDdeptnoitm, TRUE);

/* Set item Data Type property */
d2fitms_dat_typ(pd2fctx, pDdeptnoitm, D2FC_DATY_NUMBER);

/* Set item Max Length property */
d2fitms_max_len(pd2fctx, pDdeptnoitm, 4);

/*Set item Required property */
d2fitms_required(pd2fctx, pDdeptnoitm, TRUE);

/* Set Distance Between Records property */
d2fitms_dist_btwn_recs(pd2fctx, pDdeptnoitm, 0);

/* Set Database block(Database Item) property */
d2fitms_db_itm(pd2fctx, pDdeptnoitm, TRUE);

/* Set Query Allowed */
d2fitms_qry_allowed(pd2fctx, pDdeptnoitm, TRUE);

/* Set Query Length */
d2fitms_qry_len(pd2fctx, pDdeptnoitm, 4);

/* Set Update Allowed */
d2fitms_updt_allowed(pd2fctx, pDdeptnoitm, TRUE);

/* Set Item Displayed (Visible) */
d2fitms_visible(pd2fctx, pDdeptnoitm, TRUE);

/* Set Item Canvas property */
d2fitms_cnv_obj(pd2fctx, pDdeptnoitm, pd2fcnv);

/* Set Item X-position */
d2fitms_x_pos(pd2fctx, pDdeptnoitm, 32);

/* Set Item Y-position */
d2fitms_y_pos(pd2fctx, pDdeptnoitm, 151);

/* Set Item Width */
d2fitms_width(pd2fctx, pDdeptnoitm, 38);

/* Set Item Height */
d2fitms_height(pd2fctx, pDdeptnoitm, 17);

/* Set Item Bevel */
d2fitms_bevel(pd2fctx, pDdeptnoitm, D2FC_BEST_LOWERED);

/* Set item Hint */
d2fitms_hint(pd2fctx, PDdeptnoitm, (text*)"Enter value for :DEPTNO");

/*** Create DNAME item and item-related properties ***/
/* Create item */
d2fitmcr_Create(pd2fctx, pdeptblk, &pDdnameitm, (text*)"DNAME");

/* Set item type */
d2fitms_itm_type(pd2fctx, pDdnameitm, D2FC_ITTY_TI);

/* Set Enable property */
d2fitms_enabled(pd2fctx, pDdnameitm, TRUE);

/* Set item (keyboard) navigable property */
d2fitms_kbrd_navigable(pd2fctx, pDdnameitm, TRUE);

/* Set item Data Type property */
d2fitms_dat_typ(pd2fctx, pDdnameitm, D2FC_DATY_CHAR);

/* Set item Max Length property */
d2fitms_max_len(pd2fctx, pDdnameitm, 14);

/* Set Distance Between Records property */
d2fitms_dist_btwn_recs(pd2fctx, pDdnameitm, 0);

/* Set Database block(Database Item) property */
d2fitms_db_itm(pd2fctx, pDdnameitm, TRUE);

/* Set Query Allowed */
d2fitms_qry_allowed(pd2fctx, pDdnameitm, TRUE);

/* Set Query Length */
d2fitms_qry_len(pd2fctx, pDdnameitm, 14);

/* Set Update Allowed */
d2fitms_updt_allowed(pd2fctx, pDdnameitm, TRUE);

/* Set Item Displayed (Visible) */
d2fitms_visible(pd2fctx, pDdnameitm, TRUE);

/* Set Item Canvas property */
d2fitms_cnv_obj(pd2fctx, pDdnameitm, pd2fcnv);

/* Set Item X-position */
d2fitms_x_pos(pd2fctx, pDdnameitm, 70);

/* Set Item Y-position */
d2fitms_y_pos(pd2fctx, pDdnameitm, 151);

/* Set Item Width */
d2fitms_width(pd2fctx, pDdnameitm, 102);

/* Set Item Height */
d2fitms_height(pd2fctx, pDdnameitm, 17);

/* Set Item Bevel */
d2fitms_bevel(pd2fctx, pDdnameitm, D2FC_BEST_LOWERED);

/* Set item Hint */
d2fitms_hint(pd2fctx, PDdnameitm, (text*)"Enter value for :DNAME");

/*** Create LOC item and item-related properties ***/
/* Create item */
d2fitmcr_Create(pd2fctx, pdeptblk, &pDlocitm, (text*)"LOC");

/* Set item type */
d2fitms_itm_type(pd2fctx, pDlocitm, D2FC_ITTY_TI);

/* Set Enable property */
d2fitms_enabled(pd2fctx, pDlocitm, TRUE);

/* Set item (keyboard) navigable property */
d2fitms_kbrd_navigable(pd2fctx, pDlocitm, TRUE);

/* Set item Data Type property */
d2fitms_dat_typ(pd2fctx, pDlocitm, D2FC_DATY_CHAR);

/* Set item Max Length property */
d2fitms_max_len(pd2fctx, pDlocitm, 13);

/* Set Distance Between Records property */
d2fitms_dist_btwn_recs(pd2fctx, pDlocitm, 0);

/* Set Database block(Database Item) property */
d2fitms_db_itm(pd2fctx, pDlocitm, TRUE);

/* Set Query Allowed */
d2fitms_qry_allowed(pd2fctx, pDlocitm, TRUE);

/* Set Query Length */
d2fitms_qry_len(pd2fctx, pDlocitm, 13);

/* Set Update Allowed */
d2fitms_updt_allowed(pd2fctx, pDlocitm, TRUE);

/* Set Item Displayed (Visible) */
d2fitms_visible(pd2fctx, pDlocitm, TRUE);

/* Set Item Canvas property */
d2fitms_cnv_obj(pd2fctx, pDlocitm, pd2fcnv);

/* Set Item X-position */
d2fitms_x_pos(pd2fctx, pDlocitm, 173);

/* Set Item Y-position */
d2fitms_y_pos(pd2fctx, pDlocitm, 151);

/* Set Item Width */
d2fitms_width(pd2fctx, pDlocitm, 96);

/* Set Item Height */
d2fitms_height(pd2fctx, pDlocitm, 17);

/* Set Item Bevel */
d2fitms_bevel(pd2fctx, pDlocitm, D2FC_BEST_LOWERED);

/* Set item Hint */
d2fitms_hint(pd2fctx, PDlocitm, (text*)"Enter value for :LOC");

/*** Create Relations and relations-related properties ***/
/* Create Relation */
d2frelcr_Create(pd2fctx, (d2fob *)pdeptblk, &pd2frel, (text*)"DEPT_EMP");

/* Set Relation Detail block */
d2frels_detail_blk(pd2fctx, pd2frel, (text *)"EMP");

/* Set Master Deletes property */
d2frels_del_rec([pd2fctx, pd2frel, D2FC_DERE_NON_ISOLATED);

/* Set Deferred property */
d2frels_deferred(pd2ctx, pd2frel, FALSE);

/* Set Auto Query property */
d2frels_auto_qry(pd2ctx, pd2frel, FALSE);

/* Set Prevent Masterless property */
d2frels_prvnt_mstrless_ops(pd2ctx, pd2frel, FALSE);

/* Set Join Condition property */
d2frels_join_cond(pd2ctx, pd2frel, (text*)"DEPTNO");

/* Instantiate Relation: creates master-detail triggers */
d2frelup_Update(pd2fctx, pd2frel);

/* Save Form */
d2ffmdsv_Save(pd2fctx, pd2ffmd, (text*)0, FALSE, TRUE);

/* Compile Form */
d2ffmdcf_CompileFile(pd2fctx, pd2ffmd);

/* Destroy Context */
d2fctxde_Destroy(pd2fctx);
}


Modifying modules using the Open API

 Examples	     Related Topics

To modify a basic Form Builder module:

1	Include the appropriate C header files in your C source code.

2	Make calls to the desired APIs in your C source code.

A	Initialize the context structure.

B	Make "load" function calls to open an existing form module, menu module, or object library.

C	Make the necessary Open Forms API function calls to perform the desired operations, including connecting to an existing database, if required.

D	Generate an .FMX or .MMX compiled form using the appropriate "CompileFile()" function.

E	Make the required function calls to save the associated module (for example, d2ffmdsv_Save() for a form module, d2fmmdsv_Save() for a menu module, or d2folbsv_Save() for an object library).

F	Finally, call the context destroy function, d2fctxde_Destroy(), to destroy the Open Forms API context. Note that this function call must be your final one.

3	Link your source files against the Open API library (ifd2f60.lib).

4	Compile the files to create an executable (.EXE file).

5	Run the executable to modify one or more Form modules (.FMB).


Modifying modules using the Open API examples

Example

/*

This example determines if the Form Builder object is a subclassed object and returns the file path of the parent to NULL if the object is subclassed. This sample only processes the following object types:  form level triggers, alerts, blocks, items, item level triggers, radio buttons, and block level triggers.  Use a similar method to process other object types.
*/
#include <stdio.h>
#include <string.h>
#include <windows.h>

#include <d2ferr.h>
#include <d2fctx.h>
#include <d2ffmd.h>
#include <d2fblk.h>
#include <d2fitm.h>
#include <d2falt.h>
#include <d2ftrg.h>
#include <d2frdb.h>

#define BUFSIZE 128

int WINAPI WinMain(HANDLE hInstance,
                   HANDLE hPrevInstance,
                   LPSTR lpszCommandLine,
                   int cmdShow)
{
    d2fctx*   pd2fctx;
    d2ffmd*   pd2ffmd;
    d2fblk*   pd2fblk;
    d2fitm*   pd2fitm;
    d2fctxa   d2fctx_attr;
    d2fstatus status;
    d2falt*   pd2falt;
    d2ftrg*   pd2ftrg;
    d2frdb*   pd2frdb;

    int counter;

    char buf[BUFSIZE];
    char* form_name=(char*)0;

    /* Get the form name from the command line */
    strncpy(buf, lpszCommandLine, BUFSIZE);
    form_name = strtok(buf, ".");

    /* Initialize the attribute mask */
    d2fctx_attr.mask_d2fctxa = 0;

    /* Create the API context */
    status = d2fctxcr_Create(&pd2fctx, &d2fctx_attr);

    /* Load the form */
    status = d2ffmdld_Load(pd2fctx, &pd2ffmd, form_name, FALSE) ;

    if (status == D2FS_SUCCESS)
    {
      /*** Process Form Level Trigger Objects ***/
      for(status = d2ffmdg_trigger(pd2fctx,pd2ffmd,&pd2ftrg);
          pd2ftrg != NULL;
          status = d2ftrgg_next(pd2fctx,pd2ftrg,&pd2ftrg))
      {
        if (d2ftrgis_IsSubclassed(pd2fctx,pd2ftrg) == D2FS_YES)
            d2ftrgs_par_flpath(pd2fctx,pd2ftrg,NULL);
      }

      /*** Process Alert Objects ***/
      for(status = d2ffmdg_alert(pd2fctx,pd2ffmd,&pd2falt);
          pd2falt != NULL;
          status = d2faltg_next(pd2fctx,pd2falt,&pd2falt))
      {
        if (d2faltis_IsSubclassed(pd2fctx,pd2falt) == D2FS_YES)
            d2falts_par_flpath(pd2fctx,pd2falt,NULL);
      }

      /*** Process Block Objects ***/
      for(status = d2ffmdg_block(pd2fctx,pd2ffmd,&pd2fblk);
          pd2fblk != NULL;
          status = d2fblkg_next(pd2fctx,pd2fblk,&pd2fblk))
      {
        if (d2fblkis_IsSubclassed(pd2fctx,pd2fblk) == D2FS_YES)
           d2fblks_par_flpath(pd2fctx,pd2fblk,NULL);
      }

      /* Process Item Objects */
      for(status = d2fblkg_item(pd2fctx,pd2fblk,&pd2fitm);
          pd2fitm != NULL;
          status = d2fitmg_next(pd2fctx,pd2fitm,&pd2fitm))
      {
        if (d2fitmis_IsSubclassed(pd2fctx,pd2fitm) == D2FS_YES)
           d2fitms_par_flpath(pd2fctx,pd2fitm,NULL);

        /* Process Item Level Trigger Objects */
         for(status = d2fitmg_trigger(pd2fctx,pd2fitm,&pd2ftrg);
             pd2ftrg != NULL;
             status = d2ftrgg_next(pd2fctx,pd2ftrg,&pd2ftrg))
         {
             if (d2ftrgis_IsSubclassed(pd2fctx,pd2ftrg)==D2FS_YES)
             {
               d2ftrgs_par_flpath(pd2fctx,pd2ftrg,NULL);
               printf("item trigger is Subclassed\n"
             }
             else if  (d2ftrgis_IsSubclassed(pd2fctx,
                                            pd2ftrg)==D2FS_NO)
             printf("item trigger is NOT Subclassed\n");
         }

      /* Process Radio Button Objects *
        for(status = d2fitmg_rad_but(pd2fctx,pd2fitm,&pd2frdb);
            pd2frdb != NULL;
            status = d2frdbs_next(pd2fctx,pd2frdb,&pd2frdb))
        {
            if (d2frdbis_IsSubclassed(pd2fctx,pd2frdb)==D2FS_YES
            {
              d2frdbs_par_flpath(pd2fctx,pd2frdb,NULL);
              printf("radio button is Subclassed\n");
            }
            else if (d2frdbis_IsSubclassed(pd2fctx,
                                         pd2frdb)==D2FS_NO)
            printf("radio button is NOT Subclassed\n");
       }
      }

      /* Process Block Level Trigger Objects */
      for(status = d2fblkg_trigger(pd2fctx,pd2fblk,&pd2ftrg);
          pd2ftrg != NULL;
          status = d2ftrgg_next(pd2fctx,pd2ftrg,&pd2ftrg))
      {
          if (d2ftrgis_IsSubclassed(pd2fctx,pd2ftrg) == D2FS_YES)
          {
            d2ftrgs_par_flpath(pd2fctx,pd2ftrg,NULL);
            printf("block trigger is Subclassed\n");
          }
          else if (d2ftrgis_IsSubclassed(pd2fctx,
                                          pd2ftrg)==D2FS_NO)
          printf("block trigger is NOT Subclassed\n");
      }

     /* Save out the form */
     d2ffmdsv_Save(pd2fctx, pd2ffmd, (text *)0, FALSE) ;

     /* Generate the forms executable (fmx) */
     d2ffmdcf_CompileFile(pd2fctx, pd2ffmd ) ;

     /* Destroy the API Context */
     d2fctxde_Destroy(pd2fctx) ;

    }
}


Open API examples

This section includes several examples that describe how to use the Open API.

Modifying modules using the Open API:

/*

This example determines if the Form Builder object is a subclassed object and returns the file path of the parent to NULL if the object is subclassed. This sample only processes the following object types:  form level triggers, alerts, blocks, items, item level triggers, radio buttons, and block level triggers.  Use a similar method to process other object types.

*/

#include <stdio.h>

#include <string.h>

#include <windows.h>

#include <d2ferr.h>

#include <d2fctx.h>

#include <d2ffmd.h>

#include <d2fblk.h>

#include <d2fitm.h>

#include <d2falt.h>

#include <d2ftrg.h>

#include <d2frdb.h>

#define BUFSIZE 128

int WINAPI WinMain(HANDLE hInstance,

                   HANDLE hPrevInstance,

                   LPSTR lpszCommandLine,

                   int cmdShow)

{

    d2fctx*   pd2fctx;

    d2ffmd*   pd2ffmd;

    d2fblk*   pd2fblk;

    d2fitm*   pd2fitm;

    d2fctxa   d2fctx_attr;

    d2fstatus status;

    d2falt*   pd2falt;

    d2ftrg*   pd2ftrg;

    d2frdb*   pd2frdb;

    int counter;

    char buf[BUFSIZE];

    char* form_name=(char*)0;

    /* Get the form name from the command line */

    strncpy(buf, lpszCommandLine, BUFSIZE);

    form_name = strtok(buf, ".");

    /* Initialize the attribute mask */

    d2fctx_attr.mask_d2fctxa = 0;

    /* for MS Windows-only attributes */

    d2fctx_attr.d2fihnd_d2fctxa = hInstance;

    d2fctx_attr.d2fphnd_d2fctxa = hPrevInstance;

    d2fctx_attr.d2fcmsh_d2fctxa = cmdShow;

    /* Create the API context */

    status = d2fctxcr_Create(&pd2fctx, &d2fctx_attr);

    /* Load the form */

    status = d2ffmdld_Load(pd2fctx, &pd2ffmd, form_name, FALSE) ;

    if (status == D2FS_D2FS_SUCCESS)

    {

      /*** Process Form Level Trigger Objects ***/

      for(status = d2ffmdg_trigger(pd2fctx,pd2ffmd,&pd2ftrg);

          pd2ftrg != NULL;

          status = d2ftrgg_next(pd2fctx,pd2ftrg,&pd2ftrg))

      {

        if (d2ftrgis_IsSubclassed(pd2fctx,pd2ftrg) == D2FS_YES)

            d2ftrgs_par_flpath(pd2fctx,pd2ftrg,NULL);

      }

      /*** Process Alert Objects ***/

      for(status = d2ffmdg_alert(pd2fctx,pd2ffmd,&pd2falt);

          pd2falt != NULL;

          status = d2faltg_next(pd2fctx,pd2falt,&pd2falt))

      {

        if (d2faltis_IsSubclassed(pd2fctx,pd2falt) == D2FS_YES)

            d2falts_par_flpath(pd2fctx,pd2falt,NULL);

      }

      /*** Process Block Objects ***/

      for(status = d2ffmdg_block(pd2fctx,pd2ffmd,&pd2fblk);

          pd2fblk != NULL;

          status = d2fblkg_next(pd2fctx,pd2fblk,&pd2fblk))

      {

        if (d2fblkis_IsSubclassed(pd2fctx,pd2fblk) == D2FS_YES)

           d2fblks_par_flpath(pd2fctx,pd2fblk,NULL);

      }

      /* Process Item Objects */

      for(status = d2fblkg_item(pd2fctx,pd2fblk,&pd2fitm);

          pd2fitm != NULL;

          status = d2fitmg_next(pd2fctx,pd2fitm,&pd2fitm))

      {

        if (d2fitmis_IsSubclassed(pd2fctx,pd2fitm) == D2FS_YES)

           d2fitms_par_flpath(pd2fctx,pd2fitm,NULL);

        /* Process Item Level Trigger Objects */

         for(status = d2fitmg_trigger(pd2fctx,pd2fitm,&pd2ftrg);

             pd2ftrg != NULL;

             status = d2ftrgg_next(pd2fctx,pd2ftrg,&pd2ftrg))

         {

             if (d2ftrgis_IsSubclassed(pd2fctx,pd2ftrg)==D2FS_YES)

             {

               d2ftrgs_par_flpath(pd2fctx,pd2ftrg,NULL);

               printf("item trigger is Subclassed\n"

             }

             else if  (d2ftrgis_IsSubclassed(pd2fctx,

                                            pd2ftrg)==D2FS_NO)

             printf("item trigger is NOT Subclassed\n");

         }

      /* Process Radio Button Objects *

        for(status = d2fitmg_rad_but(pd2fctx,pd2fitm,&pd2frdb);

            pd2frdb != NULL;

            status = d2frdbs_next(pd2fctx,pd2frdb,&pd2frdb))

        {

            if (d2frdbis_IsSubclassed(pd2fctx,pd2frdb)==D2FS_YES

            {

              d2frdbs_par_flpath(pd2fctx,pd2frdb,NULL);

              printf("radio button is Subclassed\n");

            }

            else if (d2frdbis_IsSubclassed(pd2fctx,

                                         pd2frdb)==D2FS_NO)

            printf("radio button is NOT Subclassed\n");

       }

      }

      /* Process Block Level Trigger Objects */

      for(status = d2fblkg_trigger(pd2fctx,pd2fblk,&pd2ftrg);

          pd2ftrg != NULL;

          status = d2ftrgg_next(pd2fctx,pd2ftrg,&pd2ftrg))

      {

          if (d2ftrgis_IsSubclassed(pd2fctx,pd2ftrg) == D2FS_YES)

          {

            d2ftrgs_par_flpath(pd2fctx,pd2ftrg,NULL);

            printf("block trigger is Subclassed\n");

          }

          else if (d2ftrgis_IsSubclassed(pd2fctx,

                                          pd2ftrg)==D2FS_NO)

          printf("block trigger is NOT Subclassed\n");

      }

     /* Save out the form */

     d2ffmdsv_Save(pd2fctx, pd2ffmd, (text *)0, FALSE) ;

     /* Generate the forms executable (fmx) */

     d2ffmdcf_CompileFile(pd2fctx, pd2ffmd ) ;

     /* Destroy the API Context */

     d2fctxde_Destroy(pd2fctx) ;

    }

}

Creating modules using the Open API:

/*

This example creates a master-detail form based on the dept and emp database tables owned by the user scott.  The master contains the following fields: empno, ename, job, sal, and deptno.  The detail contains the following fields deptno, dname, and loc.  The join condition is deptno.

*/

#include<stdio.h>

#include<string.h>

#include<windows.h>

#include<d2fctx.h>

#include<d2ffmd.h>

#include<d2ffpr.h>

#include<d2fob.h>

#include<d2fcnv.h>

#include<d2ftrg.h>

#include<d2blk.h>

#include<d2fitm.h>

#include<d2fwin.h>

#include<d2frel.h>

#define D2FS_SUCCESS 0

#define FAIL 1

#define BUFSIZE 128

#define WBP_TXT "null;\n"

int WINAPI WinMain(HANDLE hInstance,

                   HANDLE hPrevInstance,

                   LPSTR lpszCommandLine,

                   int cmdShow)

{

d2fctx  *pd2fctx;

d2ffmd  *pd2ffmd;

d2fcnv  *pd2fcnv;

d2fwin  *pd2fwin;

d2fblk  *pempblk;

d2fblk  *pdeptblk;

d2frel  *pd2frel;

d2fitm  *pEempnoitm;

d2fitm  *pEenameitm;

d2fitm  *pEjobitm;

d2fitm  *pEsalitm;

d2fitm  *pEdeptnoitm;

d2fitm  *pDdeptnoitm;

d2fitm  *pDdnameitm;

d2fitm  *pDlocitm;

text  *name = (text *)0;

text  *form_name = (text *)0;

d2fctxa  d2fctx_attr;

d2fstatus retval;

char buf[BUFSIZE];

/* Get form name */

strncpy(buf, "empdept", BUFSIZE);

form_name = (text*)strtok(buf, ".");

/* Initialize the attribute mask */

d2fctx_attr.mask_d2fctxa = 0;

/* for MS Windows-only attributes */

d2fctx_attr.d2fihnd_d2fctxa = hInstance;

d2fctx_attr.d2fphnd_d2fctxa = hPrevInstance;

d2fctx_attr.d2fcmsh_d2fctxa = cmdShow;

/* Create the API context */

status = d2fctxcr_Create(&pd2fctx, &d2fctx_attr);

/* Create the context */

d2fctxcn_Connect(pd2fctx, (text*)"scott/tiger@test");

/* Create the form */

d2ffmdcr_Create(pd2fctx, &pd2ffmd, form_name);

/* Create a window */

d2fwincr_Create(pd2fctx,pd2ffmd,&pd2fwin,(text*)"MYWIN");

/*** Create Canvas and set canvas-related properties ***/

/* Create a canvas */

d2fcnvcr_Create(pd2fctx, pd2ffmd, &pd2fcnv, (text*)"MYCANVAS");

/* Set viewport width */

d2fcnvs_vprt_wid(pd2fctx, pd2fcnv, 512);

/* Set viewport height */

d2fcnvs_vprt_hgt(pd2fctx, pd2fcnv, 403);

/* Set window */

dwfcnvs_wnd_obj(pd2fctx, pd2fcnv, pd2fwin);

/* Set viewport X-position */

d2fcnvs_vprt_x_pos(pd2fctx, pd2fcnv, 0);

/* Set viewport Y-position */

d2fcnvs_vprt_y_pos(pd2fctx, pd2fcnv, 0);

/* Set width */

d2fcnvs_width(pd2fctx, pd2fcnv, 538)

/* Set height */

d2fcnvs_height(pd2fctx, pd2fcnv, 403)

/*** Create Emp block and set block-related properties ***/

/* Create block */

d2fblkcr_Create(pd2fctx, pd2ffmd, &pempblk, (text*)"EMP");

/* Set to database block */

d2fblks_db_blk(pd2fctx, pempblk, TRUE);

/* Set query data source to Table */

d2fblks_qry_dat_src_typ(pd2fctx, pempblk, D2FC_QRDA_TABLE);

/* Set query data source name to EMP table */

d2fblks_qry_dat_src_nam(pd2fctx, pempblk, "EMP");

/* Set DML data source type to Table */

d2fblks_dml_dat_typ(Pd2fctx, pempblk, D2FC_DMDA_TABLE);

/* Set DML data source name to EMP table */

d2fblks_dml_dat_nam(pd2fctx, pempblk, (text*)"EMP");

/*** Create Dept block and set block-related properties ***/

/* Create block */

d2fblkcr_Create(pd2fctx, pd2ffmd, &pdeptblk, (text*)"DEPT");

/* Set to database block */

d2fblks_db_blk(pd2fctx, pdeptblk, TRUE);

/* Set query data source to Table */

d2fblks_qry_dat_src_typ(pd2fctx, pdeptblk, D2FC_QRDA_TABLE);

/* Set query data source name to EMP table */

d2fblks_qry_dat_src_nam(pd2fctx, pdeptblk, "DEPT");

/* Set DML data source type to Table */

d2fblks_dml_dat_typ(Pd2fctx, pdeptblk, D2FC_DMDA_TABLE);

/* Set DML data source name to EMP table */

d2fblks_dml_dat_nam(pd2fctx, pdeptblk, (text*)"DEPT");

/*** Create empno item and item-related properties ***/

/* Create item */

d2fitmcr_Create(pd2fctx, pempblk, &pEempnoitm, (text*)"EMPNO");

/* Set item type */

d2fitms_itm_type(pd2fctx, pEempnoitm, D2FC_ITTY_TI);

/* Set Enable property */

d2fitms_enabled(pd2fctx, pEempnoitm, TRUE);

/* Set item (keyboard) navigable property */

d2fitms_kbrd_navigable(pd2fctx, pEempnoitm, TRUE);

/* Set item Data Type property */

d2fitms_dat_typ(pd2fctx, pEempnoitm, D2FC_DATY_NUMBER);

/* Set item Max Length property */

d2fitms_max_len(pd2fctx, pEempnoitm, 6);

/* Set item Required property */

d2fitms_required(pd2fctx, pEempnoitm, TRUE);

/* Set Distance Between Records property */

d2fitms_dist_btwn_recs(pd2fctx, pEempnoitm, 0);

/* Set Database block(Database Item) property */

d2fitms_db_itm(pd2fctx, pEempnoitm, TRUE);

/* Set Query Allowed */

d2fitms_qry_allowed(pd2fctx, pEempnoitm, TRUE);

/* Set Query Length */

d2fitms_qry_len(pd2fctx, pEempnoitm, 6);

/* Set Update Allowed */

d2fitms_updt_allowed(pd2fctx, pEempnoitm, TRUE);

/* Set Item Displayed (Visible) */

d2fitms_visible(pd2fctx, pEempnoitm, TRUE);

/* Set Item Canvas property */

d2fitms_cnv_obj(pd2fctx, pEempnoitm, pd2fcnv);

/* Set Item X-position */

d2fitms_x_pos(pd2fctx, pEempnoitm, 32);

/* Set Item Y-position */

d2fitms_y_pos(pd2fctx, pEempnoitm, 50);

/* Set Item Width */

d2fitms_width(pd2fctx, pEempnoitm, 51);

/* Set Item Height */

d2fitms_height(pd2fctx, pEempnoitm, 17);

/* Set Item Bevel */

d2fitms_bevel(pd2fctx, pEempnoitm, D2FC_BEST_LOWERED);

/* Set item Hint */

d2fitms_hint(pd2fctx, PEempnoitm, (text*)"Enter value for :EMPNO");

/*** Create Ename item and item-related properties ***/

/* Create item */

d2fitmcr_Create(pd2fctx, pempblk, &pEenameitm, (text*)"ENAME");

/* Set item type */

d2fitms_itm_type(pd2fctx, pEenameitm, D2FC_ITTY_TI);

/* Set Enable property */

d2fitms_enabled(pd2fctx, pEenameitm, TRUE);

/* Set item (keyboard) navigable property */

d2fitms_kbrd_navigable(pd2fctx, pEenameitm, TRUE);

/* Set item Data Type property */

d2fitms_dat_typ(pd2fctx, pEenameitm, D2FC_DATY_CHAR);

/* Set item Max Length property */

d2fitms_max_len(pd2fctx, pEenameitm, 10);

/* Set Distance Between Records property */

d2fitms_dist_btwn_recs(pd2fctx, pEenameitm, 0);

/* Set Database block(Database Item) property */

d2fitms_db_itm(pd2fctx, pEenameitm, TRUE);

/* Set Query Allowed */

d2fitms_qry_allowed(pd2fctx, pEenameitm, TRUE);

/* Set Query Length */

d2fitms_qry_len(pd2fctx, pEenameitm, 10);

/* Set Update Allowed */

d2fitms_updt_allowed(pd2fctx, pEenameitm, TRUE);

/* Set Item Displayed (Visible) */

d2fitms_visible(pd2fctx, pEenameitm, TRUE);

/* Set Item Canvas property */

d2fitms_cnv_obj(pd2fctx, pEenameitm, pd2fcnv);

/* Set Item X-position */

d2fitms_x_pos(pd2fctx, pEenameitm, 83);

/* Set Item Y-position */

d2fitms_y_pos(pd2fctx, pEenameitm, 50);

/* Set Item Width */

d2fitms_width(pd2fctx, pEenameitm, 77);

/* Set Item Height */

d2fitms_height(pd2fctx, pEenameitm, 17);

/* Set Item Bevel */

d2fitms_bevel(pd2fctx, pEenameitm, D2FC_BEST_LOWERED);

/* Set item Hint */

d2fitms_hint(pd2fctx, PEenameitm, (text*)"Enter value for :ENAME");

/*** Create JOB item and item-related properties ***/

/* Create item */

d2fitmcr_Create(pd2fctx, pempblk, &pEjobitm, (text*)"JOB");

/* Set item type */

d2fitms_itm_type(pd2fctx, pEjobitm, D2FC_ITTY_TI);

/* Set Enable property */

d2fitms_enabled(pd2fctx, pEjobitm, TRUE);

/* Set item (keyboard) navigable property */

d2fitms_kbrd_navigable(pd2fctx, pEjobitm, TRUE);

/* Set item Data Type property */

d2fitms_dat_typ(pd2fctx, pEjobitm, D2FC_DATY_CHAR);

/* Set item Max Length property */

d2fitms_max_len(pd2fctx, pEjobitm, 9);

/* Set Distance Between Records property */

d2fitms_dist_btwn_recs(pd2fctx, pEjobitm, 0);

/* Set Database block(Database Item) property */

d2fitms_db_itm(pd2fctx, pEjobitm, TRUE);

/* Set Query Allowed */

d2fitms_qry_allowed(pd2fctx, pEjobitm, TRUE);

/* Set Query Length */

d2fitms_qry_len(pd2fctx, pEjobitm, 9);

/* Set Update Allowed */

d2fitms_updt_allowed(pd2fctx, pEjobitm, TRUE);

/* Set Item Displayed (Visible) */

d2fitms_visible(pd2fctx, pEjobitm, TRUE);

/* Set Item Canvas property */

d2fitms_cnv_obj(pd2fctx, pEjobitm, pd2fcnv);

/* Set Item X-position */

d2fitms_x_pos(pd2fctx, pEjobitm, 160);

/* Set Item Y-position */

d2fitms_y_pos(pd2fctx, pEjobitm, 50);

/* Set Item Width */

d2fitms_width(pd2fctx, pEjobitm, 70);

/* Set Item Height */

d2fitms_height(pd2fctx, pEjobitm, 17);

/* Set Item Bevel */

d2fitms_bevel(pd2fctx, pEjobitm, D2FC_BEST_LOWERED);

/* Set item Hint */

d2fitms_hint(pd2fctx, PEjobitm, (text*)"Enter value for :JOB");

/*** Create SALARY item and item-related properties ***/

/* Create item */

d2fitmcr_Create(pd2fctx, pempblk, &pEsalitm, (text*)"SAL");

/* Set item type */

d2fitms_itm_type(pd2fctx, pEsalitm, D2FC_ITTY_TI);

/* Set Enable property */

d2fitms_enabled(pd2fctx, pEsalitm, TRUE);

/* Set item (keyboard) navigable property */

d2fitms_kbrd_navigable(pd2fctx, pEsalitm, TRUE);

/* Set item Data Type property */

d2fitms_dat_typ(pd2fctx, pEsalitm, D2FC_DATY_NUMBER);

/* Set item Max Length property */

d2fitms_max_len(pd2fctx, pEsalitm, 9);

/* Set Distance Between Records property */

d2fitms_dist_btwn_recs(pd2fctx, pEsalitm, 0);

/* Set Database block(Database Item) property */

d2fitms_db_itm(pd2fctx, pEsalitm, TRUE);

/* Set Query Allowed */

d2fitms_qry_allowed(pd2fctx, pEsalitm, TRUE);

/* Set Query Length */

d2fitms_qry_len(pd2fctx, pEsalitm, 9);

/* Set Update Allowed */

d2fitms_updt_allowed(pd2fctx, pEsalitm, TRUE);

/* Set Item Displayed (Visible) */

d2fitms_visible(pd2fctx, pEsalitm, TRUE);

/* Set Item Canvas property */

d2fitms_cnv_obj(pd2fctx, pEsalitm, pd2fcnv);

/* Set Item X-position */

d2fitms_x_pos(pd2fctx, pEsalitm, 352);

/* Set Item Y-position */

d2fitms_y_pos(pd2fctx, pEsalitm, 50);

/* Set Item Width */

d2fitms_width(pd2fctx, pEsalitm, 70);

/* Set Item Height */

d2fitms_height(pd2fctx, pEsalitm, 17);

/* Set Item Bevel */

d2fitms_bevel(pd2fctx, pEsalitm, D2FC_BEST_LOWERED);

/* Set item Hint */

d2fitms_hint(pd2fctx, PEsalitm, (text*)"Enter value for :SAL");

/*** Create DEPTNO item and item-related properties ***/

/* Create item */

d2fitmcr_Create(pd2fctx, pempblk, &pEdeptnoitm, (text*)"DEPTNO");

/* Set item type */

d2fitms_itm_type(pd2fctx, pEdeptnoitm, D2FC_ITTY_TI);

/* Set Enable property */

d2fitms_enabled(pd2fctx, pEdeptnoitm, TRUE);

/* Set item (keyboard) navigable property */

d2fitms_kbrd_navigable(pd2fctx, pEdeptnoitm, TRUE);

/* Set item Data Type property */

d2fitms_dat_typ(pd2fctx, pEdeptnoitm, D2FC_DATY_NUMBER);

/* Set item Max Length property */

d2fitms_max_len(pd2fctx, pEdeptnoitm, 4);

/*Set item Required property */

d2fitms_required(pd2fctx, pEdeptnoitm, TRUE);

/* Set Distance Between Records property */

d2fitms_dist_btwn_recs(pd2fctx, pEdeptnoitm, 0);

/* Set Database block(Database Item) property */

d2fitms_db_itm(pd2fctx, pEdeptnoitm, TRUE);

/* Set Query Allowed */

d2fitms_qry_allowed(pd2fctx, pEdeptnoitm, TRUE);

/* Set Query Length */

d2fitms_qry_len(pd2fctx, pEdeptnoitm, 4);

/* Set Update Allowed */

d2fitms_updt_allowed(pd2fctx, pEdeptnoitm, TRUE);

/* Set Item Displayed (Visible) */

d2fitms_visible(pd2fctx, pEdeptnoitm, TRUE);

/* Set Item Canvas property */

d2fitms_cnv_obj(pd2fctx, pEdeptnoitm, pd2fcnv);

/* Set Item X-position */

d2fitms_x_pos(pd2fctx, pEdeptnoitm, 493);

/* Set Item Y-position */

d2fitms_y_pos(pd2fctx, pEdeptnoitm, 50);

/* Set Item Width */

d2fitms_width(pd2fctx, pEdeptnoitm, 30);

/* Set Item Height */

d2fitms_height(pd2fctx, pEdeptnoitm, 17);

/* Set Item Bevel */

d2fitms_bevel(pd2fctx, pEdeptnoitm, D2FC_BEST_LOWERED);

/* Set item Hint */

d2fitms_hint(pd2fctx, PEdeptnoitm, (text*)"Enter value for :DEPTNO");

/*** Create DEPTNO item and item-related properties ***/

/* Create item */

d2fitmcr_Create(pd2fctx, pdeptblk, &pDdeptnoitm, (text*)"DEPTNO");

/* Set item type */

d2fitms_itm_type(pd2fctx, pDdeptnoitm, D2FC_ITTY_TI);

/* Set Enable property */

d2fitms_enabled(pd2fctx, pDdeptnoitm, TRUE);

/* Set item (keyboard) navigable property */

d2fitms_kbrd_navigable(pd2fctx, pDdeptnoitm, TRUE);

/* Set item Data Type property */

d2fitms_dat_typ(pd2fctx, pDdeptnoitm, D2FC_DATY_NUMBER);

/* Set item Max Length property */

d2fitms_max_len(pd2fctx, pDdeptnoitm, 4);

/*Set item Required property */

d2fitms_required(pd2fctx, pDdeptnoitm, TRUE);

/* Set Distance Between Records property */

d2fitms_dist_btwn_recs(pd2fctx, pDdeptnoitm, 0);

/* Set Database block(Database Item) property */

d2fitms_db_itm(pd2fctx, pDdeptnoitm, TRUE);

/* Set Query Allowed */

d2fitms_qry_allowed(pd2fctx, pDdeptnoitm, TRUE);

/* Set Query Length */

d2fitms_qry_len(pd2fctx, pDdeptnoitm, 4);

/* Set Update Allowed */

d2fitms_updt_allowed(pd2fctx, pDdeptnoitm, TRUE);

/* Set Item Displayed (Visible) */

d2fitms_visible(pd2fctx, pDdeptnoitm, TRUE);

/* Set Item Canvas property */

d2fitms_cnv_obj(pd2fctx, pDdeptnoitm, pd2fcnv);

/* Set Item X-position */

d2fitms_x_pos(pd2fctx, pDdeptnoitm, 32);

/* Set Item Y-position */

d2fitms_y_pos(pd2fctx, pDdeptnoitm, 151);

/* Set Item Width */

d2fitms_width(pd2fctx, pDdeptnoitm, 38);

/* Set Item Height */

d2fitms_height(pd2fctx, pDdeptnoitm, 17);

/* Set Item Bevel */

d2fitms_bevel(pd2fctx, pDdeptnoitm, D2FC_BEST_LOWERED);

/* Set item Hint */

d2fitms_hint(pd2fctx, PDdeptnoitm, (text*)"Enter value for :DEPTNO");

/*** Create DNAME item and item-related properties ***/

/* Create item */

d2fitmcr_Create(pd2fctx, pdeptblk, &pDdnameitm, (text*)"DNAME");

/* Set item type */

d2fitms_itm_type(pd2fctx, pDdnameitm, D2FC_ITTY_TI);

/* Set Enable property */

d2fitms_enabled(pd2fctx, pDdnameitm, TRUE);

/* Set item (keyboard) navigable property */

d2fitms_kbrd_navigable(pd2fctx, pDdnameitm, TRUE);

/* Set item Data Type property */

d2fitms_dat_typ(pd2fctx, pDdnameitm, D2FC_DATY_CHAR);

/* Set item Max Length property */

d2fitms_max_len(pd2fctx, pDdnameitm, 14);

/* Set Distance Between Records property */

d2fitms_dist_btwn_recs(pd2fctx, pDdnameitm, 0);

/* Set Database block(Database Item) property */

d2fitms_db_itm(pd2fctx, pDdnameitm, TRUE);

/* Set Query Allowed */

d2fitms_qry_allowed(pd2fctx, pDdnameitm, TRUE);

/* Set Query Length */

d2fitms_qry_len(pd2fctx, pDdnameitm, 14);

/* Set Update Allowed */

d2fitms_updt_allowed(pd2fctx, pDdnameitm, TRUE);

/* Set Item Displayed (Visible) */

d2fitms_visible(pd2fctx, pDdnameitm, TRUE);

/* Set Item Canvas property */

d2fitms_cnv_obj(pd2fctx, pDdnameitm, pd2fcnv);

/* Set Item X-position */

d2fitms_x_pos(pd2fctx, pDdnameitm, 70);

/* Set Item Y-position */

d2fitms_y_pos(pd2fctx, pDdnameitm, 151);

/* Set Item Width */

d2fitms_width(pd2fctx, pDdnameitm, 102);

/* Set Item Height */

d2fitms_height(pd2fctx, pDdnameitm, 17);

/* Set Item Bevel */

d2fitms_bevel(pd2fctx, pDdnameitm, D2FC_BEST_LOWERED);

/* Set item Hint */

d2fitms_hint(pd2fctx, PDdnameitm, (text*)"Enter value for :DNAME");

/*** Create LOC item and item-related properties ***/

/* Create item */

d2fitmcr_Create(pd2fctx, pdeptblk, &pDlocitm, (text*)"LOC");

/* Set item type */

d2fitms_itm_type(pd2fctx, pDlocitm, D2FC_ITTY_TI);

/* Set Enable property */

d2fitms_enabled(pd2fctx, pDlocitm, TRUE);

/* Set item (keyboard) navigable property */

d2fitms_kbrd_navigable(pd2fctx, pDlocitm, TRUE);

/* Set item Data Type property */

d2fitms_dat_typ(pd2fctx, pDlocitm, D2FC_DATY_CHAR);

/* Set item Max Length property */

d2fitms_max_len(pd2fctx, pDlocitm, 13);

/* Set Distance Between Records property */

d2fitms_dist_btwn_recs(pd2fctx, pDlocitm, 0);

/* Set Database block(Database Item) property */

d2fitms_db_itm(pd2fctx, pDlocitm, TRUE);

/* Set Query Allowed */

d2fitms_qry_allowed(pd2fctx, pDlocitm, TRUE);

/* Set Query Length */

d2fitms_qry_len(pd2fctx, pDlocitm, 13);

/* Set Update Allowed */

d2fitms_updt_allowed(pd2fctx, pDlocitm, TRUE);

/* Set Item Displayed (Visible) */

d2fitms_visible(pd2fctx, pDlocitm, TRUE);

/* Set Item Canvas property */

d2fitms_cnv_obj(pd2fctx, pDlocitm, pd2fcnv);

/* Set Item X-position */

d2fitms_x_pos(pd2fctx, pDlocitm, 173);

/* Set Item Y-position */

d2fitms_y_pos(pd2fctx, pDlocitm, 151);

/* Set Item Width */

d2fitms_width(pd2fctx, pDlocitm, 96);

/* Set Item Height */

d2fitms_height(pd2fctx, pDlocitm, 17);

/* Set Item Bevel */

d2fitms_bevel(pd2fctx, pDlocitm, D2FC_BEST_LOWERED);

/* Set item Hint */

d2fitms_hint(pd2fctx, PDlocitm, (text*)"Enter value for :LOC");

/*** Create Relations and relations-related properties ***/

/* Create Relation */

d2frelcr_Create(pd2fctx, (d2fob *)pdeptblk, &pd2frel, (text*)"DEPT_EMP");

/* Set Relation Detail block */

d2frels_detail_blk(pd2fctx, pd2frel, (text *)"EMP");

/* Set Master Deletes property */

d2frels_del_rec([pd2fctx, pd2frel, D2FC_DERE_NON_ISOLATED);

/* Set Deferred property */

d2frels_deferred(pd2ctx, pd2frel, FALSE);

/* Set Auto Query property */

d2frels_auto_qry(pd2ctx, pd2frel, FALSE);

/* Set Prevent Masterless property */

d2frels_prvnt_mstrless_ops(pd2ctx, pd2frel, FALSE);

/* Set Join Condition property */

d2frels_join_cond(pd2ctx, pd2frel, (text*)"DEPTNO");

/* Instantiate Relation: creates master-detail triggers */

d2frelup_Update(pd2fctx, pd2frel);

/* Save Form */

d2ffmdsv_Save(pd2fctx, pd2ffmd, (text*)0, FALSE, TRUE);

/* Compile Form */

d2ffmdcf_CompileFile(pd2fctx, pd2ffmd);

/* Destroy Context */

d2fctxde_Destroy(pd2fctx);

}


About Form Builder Components

  Related Topics

Form Builder consists of the following programs, or components, which you can execute independently from the command line or by clicking on an icon:

Form Builder	Form Builder is the design component you use to create, compile, and run Form Builder applications.  Using Form Builder, you can create three types of modules:  forms, menus, and libraries.
Forms Runtime	Form operators use Forms Runtime to run the completed application.  As an application designer, you can also use Forms Runtime to test and debug forms during the design stage.  Forms Runtime reads the machine-readable file created by the Form Compiler, and executes the form.
Web Previewer	Application developers use the Web Previewer to test forms locally as though they were being run from Forms Server in a browser or in the Appletviewer.  Like Forms Runtime, the Web Previewer reads the machine-readable file created by the Form Compiler, and executes the form.
Form Compiler	Most often, you use the Form Compiler to create a machine-readable file that Forms Runtime can execute.  Form Compiler also allows you to convert various representations of a form.  Using Form Compiler, you can:  • Convert files between binary, text, and database module storage formats.  • Insert module definitions into database tables.  • Delete module definitions from the database.  • Recompile application modules when porting to different platforms.  • Upgrade applications created with previous versions of Form Builder,  SQL*Forms, and SQL*Menu.


Starting Form Builder Components

  Related Topics

Some platforms support icons, and some support command lines. You can start the Form Builder, Form Compiler, Web Previewer, or Forms Runtime components in one of two ways, depending on your computer platform:

icon	You will see a different icon for each component: Form Builder, Forms Runtime, and Forms Compiler.  To launch a component, double-click it.
command line	When you start a component by entering a command on the command line, you can indicate the options you want to use for this session by entering keyword parameters on the command line.
For more information on starting Form Builder components, refer to the Form Builder documentation for your operating system.


Starting Form Builder Components from the Command Line

  Related Topics	 Examples

To start any Form Builder component from the command line, enter this statement at the system prompt:

component_name [module_name] [userid/password] [parameters]

where:

component_name	Specifies the Form Builder component you want to use:

•	Form Builder - ifbld60

•	Forms Runtime - ifrun60

•	Web Previewer - ifweb60

•	Form Compiler - ifcmp60


Starting Form Builder Components examples

ifrun60	Starts the Forms Runtime component on Microsoft Windows, with no calls to the user exit interface.

To indicate that foreign functions accessible through the user exit interface have been linked into the executable, add an x to component_name.

For more information on valid component names, refer to the Form Builder documentation for your operating system.

module_name	Specifies the module you want to load: a form, menu, or library name.  If you omit the module name, Form Builder displays a dialog allowing you to choose the module to open.

userid/password	Specifies your ORACLE username and password.

parameters	Specifies any optional command line parameters you want to activate for this session.  Optional parameters are entered in this format:keyword1=value1 keyword2=value2...

ifrun60 custform scott/tiger statistics=yes

Note:  The examples assume that you're running Form Builder on Microsoft Windows, with no calls to the user exit interface, so the Forms Runtime component name is shown as "ifrun60."  You should substitute the correct value of component_name for your platform and application.

Keyword Usage

There are three categories of parameters in Form Builder:

•	MODULE and USERID

•	options (command line parameters for setting options)

•	form parameters

The first two parameters, MODULE and USERID, are unique because you can use either positional or keyword notation to enter them.  Use keyword notation to enter optional parameters, on the command line.  (Many optional parameters can also be set using dialogs.)  Form parameters are optional input variables that are defined at design time for a specific form.

MODULE and USERID

If you enter the first two parameters, MODULE and USERID,  in the specified order, you may omit the keywords and enter only values, as shown in the following example:

ifrun60 custform scott/tiger

Invalid Example:

ifrun60 scott/tiger

This sequence is invalid because the value for username/password is out of sequence, so it must be preceded by the USERID keyword.  To use positional notation instead of keywords would require inserting the value of the MODULE parameter immediately after the component name, as in the previous example.

Valid Examples:

ifrun60 module=custform userid=scott/tiger
ifrun60 userid=scott/tiger
ifrun60

If you indicate only the module name, Form Builder will prompt you for module name and username/password.

Options

Use keyword notation for setting options on the command line. For information on options, see:

•	Setting Forms Runtime Options

•	Setting Form Compiler Options

•	Setting Form Builder Options

The following syntax rules apply to all keyword parameters, including options and form parameters:

•	No spaces should be placed before or after the equal sign of an argument.

•	Separate arguments with one or more spaces; do not use commas to separate arguments.

Invalid Example:

ifrun60 custform scott/tiger statistics = yes
ifrun60 custform scott/tiger statistics=yes,debug=yes

Valid Examples:

ifrun60 custform scott/tiger statistics=yes
ifrun60 custform scott/tiger statistics=yes debug=yes

Form Parameters

Form parameters are variables that you define at design time.  Form parameters provide a simple mechanism for defining and setting the value of inputs that are required by a form at startup.  Operators can specify values for form parameters by entering them on the command line using standard command line syntax.

The default value for a form parameter is taken from the Default Value field of the Properties window.  The operator can override the default value when starting Forms Runtime by specifying a new value for the form parameter on the command line.

In the following example, myname_param is a user-defined form parameter that was defined in Form Builder.

Note:  If a form parameter value includes a space or punctuation, enclose the value in double quotes.

Example

ifrun60 empform scott/tiger myname_param="Msr. Dubois"

Displaying Hint Text on Command Line Options

To receive help on syntax and parameters, type the component name followed by "help=yes" at the system prompt.

Example

ifrun60 help=yes


Logging in to the Database
Logging on to the Database

 Examples

To explicitly log on to the database, use the USERID command line keyword or, in Form Builder, choose File [image] Connect.

USERID

USERID is your ORACLE username and password with an optional SQL*Net connect string.   The maximum length for the connect string is 255 characters.

To log on, use one of the following forms:

username/password
username/password@node

Expired password

The Oracle8 database server offers a password expiration feature that database administrators can employ to force users to update their password on a regular basis.

If your password has expired, Forms will offer you an opportunity to enter a new password when you log on.  (You can also use the Forms startup dialog box to change your password before it expires.)


Logging in to the Database examples
Logging on to the Database examples

You might specify the following command to run the ORDER_ENTRY form on the default database of the LONDON node:

ifrun60 order_entry scott/tiger@D:london

For information on SQL*Net, refer to the SQL*Net User's Guide.  For help with your ORACLE username, see your Database Administrator.


Forms Runtime Options

Forms Runtime options specify Form Builder default behavior during a Forms Runtime session. You can set Forms Runtime options in two ways:

•	Set options in the Forms Runtime Options dialog box.

•	Pass parameters to Form Builder on the command line when you invoke Forms Runtime.

In addition, you can set Forms Runtime options to specify the defaults for forms you run from Form Builder in the Preferences dialog box.  To display the Preferences dialog box, choose Tools [image] Preferences.

Note:  Forms Runtime preferences set in Form Builder apply only to forms run from within Form Builder.

Options may also be set for the Web Previewer in the serverargs parameter of a base HTML file.  You can specify this HTML filename in the Runtime tab of the Preferences dialog box, or on the command line.  For details on creating a base HTML file see the section on "Configuring the Forms Server" in Deploying Forms Applications to the Web.

The following chart lists the Forms Runtime options from the Options window and their corresponding keyword parameters.

If you enter these keyword parameters as command line options, you can enter more than one at a time, in any order:

ifrun60 module=myform userid=scott/tiger debug=YES statistics=YES

Option Name	Keyword Parameter	Default
Oracle terminal resource file	Term
Run in debug mode	Debug	No
Debug messages	Debug_Messages *	No
Write input keystrokes to file	Keyout
Read input keystrokes from file	Keyin
Write output to file	Output_File
Write output to display	Interactive	Yes
Array processing	Array	Yes
Buffer records to temporary file	Buffer_Records	No
Display screen to specify logon	Logon_Screen	No
Display block menu on startup	Block_Menu	No
Optimize V2-style trigger step SQL processing	OptimizeSQL	Yes
Optimize transaction mode processing	OptimizeTP	Yes
Run in quiet mode	Quiet	No
Show statistics	Statistics	No
Run in query only mode	Query_Only	No
Show help information	Help	No
Window state	Window_State	NORMAL
Collect PECS data?	PECS	OFF
Options screen	Options_Screen *	No
Use SDI mode	USESDI	No
Path for HTML file (Web Runtime only)	HTML
 * Use from command line only; not available from the Forms Runtime Options dialog box.


Array (Forms Runtime)

 Examples	 All Options

Description

Use array processing during a Forms Runtime session.

When you suppress array processing, Forms requests that the database only returns a single row of query results at a time from server to client.  Similarly, Forms requests that the database only send a single row at a time from the client to the server for an INSERT, UPDATE, or DELETE when array processing is suppressed.

Suppressing array processing usually results in the first retrieved record displaying faster than it would if you fetched a number of records with array processing.  However, the total time required to fetch and display a number of records is shorter with array processing because network overhead can be reduced.

Option Name  Array Processing

Default YES


Array (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger array=NO


Block_Menu (Forms Runtime)

 Examples	 All Options

Description

Automatically displays the block menu as the first screen (after the login screen, if it displays) instead of the form.

Preference Name  Display Block Menu

Default NO


Block_Menu (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger block_menu=YES


Buffer_Records (Forms Runtime)

 Examples	 All Options

Description

Sets the number of records buffered in memory to the minimum allowable number of rows displayed plus 3 (for each block).  If a block retrieves any records by a query beyond this minimum, Form Builder buffers these additional records to a temporary file on disk.

Setting this option saves Forms Runtime memory, but may slow down processing because of disk I/O.

Buffer_Records=NO tells Form Builder to set the minimum to the number specified using the Buffered property from each block.

Option Name  Buffer Records to Temporary File

Default NO


Buffer_Records (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger buffer_records=YES


Debug (Forms Runtime)

 Examples	 All Options

Description

Invokes the debug mode for the Forms Runtime session.   Debug mode invokes break processing if the BREAK built-in is used in any trigger or if you use the Help [image] Debug command from the Form Builder menu.

To invoke debug mode on non-Windows platforms, you must use the debug runform executable:

ifdbg60 module=myform userid=scott/tiger debug=YES

Option Name  Run in Debug Mode

Default NO


Debug (Forms Runtime) examples

ifdbg60 module=myform userid=scott/tiger debug=YES


Debug_Messages (Forms Runtime)

 Examples	 All Options

Description

Debug_Messages displays ongoing messages about trigger execution while the form runs.

Default NO


Debug_Messages (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger debug_messages=YES


Help (Forms Runtime)

 Examples	 All Options

Description

Invokes the Form Builder help screen.

Option Name  Show Help Information

Default NO


Help (Forms Runtime) examples

ifrun60 help=YES


Interactive (Forms Runtime)

 Examples	 All Options

Description

Interactive specifies that, when you are using a keyscript file as input,  Form Builder will display the output on the terminal screen (i.e., run interactively) as well as print the output to a file. Use Interactive=NO to suppress screen output when running forms in batch mode.

This parameter applies to character-mode terminals only.

Note: You must use the Keyin and Output_File parameters whenever you use Interactive.  The Keyin file specifies the input, or keyscript, file; Output_File specifies the output, or display log, file.

Option Name  Write Output to Display

Default YES


Interactive (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger keyin=myfile.key

output_file=mydisplay.out interactive=NO


Keyin (Forms Runtime)

 Examples	 All Options

Description

Allows you to read a keyscript file into a form as input.  The keyscript file starts, executes, and ends the Forms Runtime session.

The file name specified is the input, or keyscript, file.

By default, Form Builder performs all actions on the terminal screen. If you want to suppress screen output, specify Interactive=NO and use  Output_File to specify the output file.

This parameter applies to character-mode terminals only.

Option Name  Read Input Keystrokes from File


Keyin (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger keyin=myfile.key


Keyout (Forms Runtime)

 Examples	 All Options

Description

Captures in a keyscript file the keystrokes involved during the Forms Runtime session.  The keyscript file includes the keystrokes involved in navigating within a form, invoking functions, and performing transactions.

The file name specifies the output, or keyscript, file.

This parameter applies to character-mode terminals only.

Option Name  Write Input Keystrokes to File


Keyout (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger keyout=newfile.key


Logon_Screen (Forms Runtime)

 Examples	 All Options

Description

Forces the logon screen to display if you have not entered the password.  Do not specify a username and password when you use Logon_Screen (Form Builder will ignore it if you do).

Use Logon_Screen when you do not want to type your password on the command line (where it is visible).

Option Name  Display Screen to Specify Logon

Default NO


Logon_Screen (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger logon_screen=YES


Optimize SQL Processing (Forms Runtime)

 Examples	 All Options

Description

Specifies that Form Builder is to optimize SQL statement processing in V2-style triggers by sharing database cursors.

By default, Form Builder assigns a separate database cursor for each SQL statement that a form executes explicitly in a V2 trigger.  This behavior enhances processing  because the statements in each cursor need to be parsed only the first time they are executed in a Forms Runtime session¾not every time.

When you specify OptimizeSQL=NO, Form Builder assigns a single cursor for all SQL statements in V2 triggers.  These statements share, or reuse, that cursor.  This behavior saves memory, but slows processing because the SQL statements must be parsed every time they are executed.

You can fine-tune this behavior through the New Cursor Area trigger step characteristic.  If a trigger step that contains a SQL statement has this characteristic turned on, Form Builder assigns a separate cursor to the statement, in effect overriding the OptimizeSQL parameter for that statement.

Note:  OptimizeSQL has no effect on statements in PL/SQL triggers.

Option Name  Optimize V2-Style Trigger Step SQL Processing   optimizesql

Default YES


Optimize SQL Processing (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger optimizesql=NO


Optimize Transaction Mode Processing (Forms Runtime) preference
Optimize Transaction Mode Processing (Forms Runtime)

 Examples	   Restrictions	 All Options

Description

Optimizes transaction mode processing.

By default, Form Builder assigns a separate database cursor for each SQL statement that a form executes implicitly as part of posting or querying data.  This behavior enhances processing because the statements in each cursor are parsed only the first time they are executed in a Forms Runtime session, not every time.

Note that the cursors that are assigned to query SELECT statements must be parsed every time they are executed.  This exception exists because queries can vary from execution to execution.

When you specify OptimizeTP=NO, Form Builder assigns a separate cursor only for each query SELECT statement.  All other implicit SQL statements share, or reuse, cursors.  This behavior saves memory but slows processing because all INSERT, UPDATE, DELETE, and SELECT FOR UPDATE statements must be parsed every time they are executed.

Option Name  Optimize Transaction Mode Processing   optimizetp

Default YES


Optimize Transaction Mode Processing (Forms Runtime) restrictions

The OptimizeTP parameter has no effect if you replace standard Form Builder processing with On-Insert, On-Update, and On-Delete triggers because these triggers replace the implicit issuance of INSERT, UPDATE, and DELETE statements.


Optimize Transaction Mode Processing (Forms Runtime) examples
Optimize Transaction Mode Processing (Forms Runtime) example

ifrun60 module=myform userid=scott/tiger optimizetp=NO


Options_Screen (Forms Runtime)

 Examples	 All Options

Description

Displays the Options window.

This parameter applies on GUI displays only.

Default  NO


Options_Screen (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger options_screen=YES


Output_File (Forms Runtime)

 Examples	 All Options

Description

Captures the terminal output for a form in a display log file, as well as displaying it on the screen.  If you want to suppress screen output, use Interactive=NO and then specify an Output_File.

This parameter applies to character-mode terminals only.

Note:  You must use the Keyin parameter whenever you use Output_File.  The Keyin file specifies the input, or keyscript, file;  Output_File specifies the output, or display log, file.

Option Name  Write Output to File


Output_File (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger keyin=myfile.key output_file=mydisplay.out


PECS (Forms Runtime)

 Examples	 All Options

Description

Runs a form with Performance Event Collection Services (PECS) enabled.

PECS is a performance measurement tool you can use to perform the following tasks:

•	Measure resource usage (CPU time per event or transactions processed per hour) of Form Builder or application-specific events

•	Locate performance problems (elapsed time per event)

•	Measure object coverage (whether a specific object, such as a trigger, alert, or window, is visited during test execution)

•	Measure line-by-line coverage (for PL/SQL code in triggers and procedures)

The PECS option can be set to ON, OFF, or FULL:

•	For object coverage, set PECS=ON

•	For object coverage and line coverage:

•	Compile with Debug=ON

•	Run with PECS=FULL

•	The default is PECS=OFF

To use PECS on non-Windows platforms, you must use the debug runform executable:

ifdbg60 module=myform userid=scott/tiger PECS=ON

Default:   OFF


PECS (Forms Runtime) examples

ifdbg60 module=myform userid=scott/tiger PECS=ON


Query_Only (Forms Runtime)

 Examples	 All Options

Description

Invokes the form in query-only mode.  Setting this option to On is equivalent to using the CALL_FORM(query_only) built-in.

Preference Name  Query Only Mode

Default NO


Query_Only (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger query_only=YES


Quiet (Forms Runtime)

 Examples	 All Options

Description

Invokes the quiet mode for the Forms Runtime session.  In quiet mode, messages do not produce an audible beep.  You can explicitly ring the bell from a trigger by way of a call to the BELL built-in.  The default of quiet=NO means that the bell rings.  To turn off the bell, set quiet=YES.

Option Name  Run in Quiet Mode

Default NO


Quiet (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger quiet=YES


Statistics (Forms Runtime)

 Examples	 All Options

Description

Displays a message at the end of the session that states the maximum number of simultaneous cursors that were used during the session.  This message appears on the terminal screen, not on the message line.

This option also issues the following command to the database:

ALTER SESSION SET SQL_TRACE TRUE

This command enables the SQL trace facility for the current session, displaying the trace file directory on the server.  For more information on this facility¾which gathers database performance information¾refer to the Oracle RDBMS Performance Tuning Guide.

If you are running a form within Form Builder and you want to use this feature, activate the Statistics Forms Runtime option.

Option Name  Show Statistics

Default NO


Statistics (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger statistics=YES


Term (Forms Runtime)

 Examples	 All Options

Description

Specifies a mapping other than the default mapping for the current device and product:

resfile	The file name specified is the name of your Oracle Terminal resource file.  If you do not specify resfile, Form Builder defaults to a file name that is platform-specific, but begins with "FMR" on most platforms.  For example, the Microsoft Windows default file is FMRUSW.

mymapping	The mapping name specified is the mapping you want to use for this Form Builder session.

Note:  You or the DBA define mappings with Oracle Terminal.  For more information on resource files, refer to the Form Builder documentation for your operating system.

When running forms on the web use only the resfile argument to specify the full path of the resource file to be used.

Option Name  Oracle Terminal Resource File


Term (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger@<alias> term=resfile:mymapping

When running a form on the web use:

serverargs="myform.fmx scott/tiger@<alias> term=c:\formdir\resfile.res"


Window_State (Forms Runtime)

 Examples	   Restrictions	 All Options

Description

Sets the size of the MDI application window at the beginning of Forms Runtime.

When set to MAXIMIZE, the MDI application window is maximized at the beginning of a Forms Runtime session.  When set to MINIMIZE, the MDI application window is minimized at the beginning of a Forms Runtime session.  The NORMAL setting starts up an MDI application window that is normal size.

Option Name  Window State

Default NORMAL


Window_State (Forms Runtime) restrictions

Valid only on Microsoft Windows.  Not supported for forms running from the web.


Window_State (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger window_state=MAXIMIZE


Setting Form Compiler Options

 All Options

Form Compiler options specify Form Builder default behavior during a Form Compiler session. Some of these options apply to file generation during development, for running and testing forms; other options apply only when you are converting files from earlier versions to Version 6.0.

You can set Form Compiler options in two ways:

•	Set options in the "Form Compiler Options" dialog box.

•	Pass parameters to Form Builder on the command line when you invoke Form Compiler.

The following chart lists the Form Compiler options from the "Form Compiler Options" window and their corresponding keyword parameters.  For information on a specific Form Compiler option, see the corresponding parameter in the alphabetical list that follows the chart.

In the alphabetical list of Form Compiler parameters, the following information is shown for each parameter:

•	example, showing the parameter set to a value other than its default

•	relevant module type: Form, Menu, Library, or All

•	description

•	default

If you enter these keyword parameters as command line options, you can enter more than one at a time, in any order:

ifcmp60 module=myform userid=scott/tiger batch=YES statistics=YES

Option Name	Keyword Parameter
File	Module
Userid/Password	Userid
Module type is Form, Menu, or Library	Module_Type
Module access is File or Database	Module_Access
Compile in Debug mode	Debug
Show statistics	Statistics
Logon to the database	Logon
Write output to file	Output_File
Write script file	Script
Delete module from database	Delete
Insert module into database	Insert
Extract module from database into file	Extract
Upgrade 3.0 Form or 5.0 Menu to 4.5 Module	Upgrade
Upgrade SQL*Menu 5.0 table privileges	Upgrade_Roles
Version to upgrade	Version
CRT file to use when upgrading	CRT_File
Compile a runform/runmenu file when upgrading	Build
Add key-up and down triggers when upgrading	Add_Triggers
Add NOFAIL to exemacro steps when upgrading	Nofail
Show help information	Help
Options_Screen	Options_Screen*
Batch	Batch*

*Use from command line only; not available from the Form Compiler Options dialog.


Add_Triggers (Form Compiler)

 Examples	 All Options

Description

Indicates whether to add key-up and key-down triggers when upgrading from Forms 2.0 or 2.3 to 4.0 wherever KEY-PRVREC and KEY-NXTREC triggers existed.

Module:  Form

Default NO


Add_Triggers (Forms Compiler) examples
Add_Triggers (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger upgrade=yes version=23 add_triggers=YES


Batch (Form Compiler)

 Examples	 All Options

Description

Suppresses interactive messages; use when performing a batch generation.

Module:  Form

Default NO


Batch (Forms Compiler) examples
Batch (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger batch=YES


Build (Form Compiler)

 Examples	 All Options

Description

Use the Build option in conjunction with Upgrade.  Form Builder creates two files when you specify upgrade=YES and omit build, thus accepting the default of build=YES:

•	an upgraded binary design module (.FMB or .MMB file)

•	an upgraded Forms Runtime executable module (.FMX or .MMX file)

If you do not want to automatically create the Forms Runtime module, specify build=NO.

Module:  Form, Menu

Default YES


Build (Forms Compiler) examples
Build (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger upgrade=YES build=NO


Compile_All (Form Compiler)

 Examples	 All Options

Description

Compiles the program units within the specified module.

Note: The output file will be placed in the current directory unless you specify a different location using Output_File.

Module:  Form, Menu, Library

Default NO


Compile_All (Forms Compiler) examples
Compile_All (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger compile_all=YES


CRT_File (Form Compiler)

 Examples	 All Options

Description

Indicates CRT file to use when upgrading from SQL*Forms Version 2.0 or 2.3.

Module:  Form


CRT_File (Forms Compiler) examples
CRT_File (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger upgrade=yes version=20 crt_file=myfile.crt


Debug (Form Compiler)

 Examples	 All Options

Description

Creates a debug-capable form.

The debug Form Compiler option creates entries in your .FMX file used by the runtime source-level debugger, so set debug=yes for Form Compiler whenever you plan to set debug=yes for runtime.

Option Name  Compile in Debug Mode

Default NO


Debug (Forms Compiler) examples
Debug (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger debug=yes


Delete (Form Compiler)

 Examples	 All Options

Description

Deletes the module directly from the database.

Module:  All

Default NO


Delete (Forms Compiler) examples
Delete (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger delete=YES


Extract (Form Compiler)

 Examples	 All Options

Description

Extracts the module from the database into a file with the same module name.

Module:  All

Default NO


Extract (Forms Compiler) examples
Extract (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger extract=YES


Help (Form Compiler)

 Examples	 All Options

Description

Invokes the Form Builder help screen.

Module:  All

Default NO


Help (Forms Compiler) examples
Help (Form Compiler) examples

ifcmp60 help=YES


Insert (Form Compiler)

 Examples	 All Options

Description

Inserts a module directly into the database from the Form Compiler command line.

Module:  All

Default NO

Usage Notes

The Insert option does not work in combination with the Upgrade option.


Insert (Forms Compiler) examples
Insert (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger insert=YES


Logon (Form Compiler)

 Examples	 All Options

Description

Specifies whether Form Compiler should log on to the database.  If the module contains any PL/SQL code with table references, a connection will be required for generation.

Module:  Form

Default YES


Logon (Forms Compiler) examples
Logon (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger logon=NO


Module_Access (Form Compiler)

 Examples	 All Options

Description

Specifies whether you want to open and save modules to the file system or to the database.

Module:  All

Default FILE


Module_Access (Forms Compiler) examples
Module_Access (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger module_access=database


Module_Type (Form Compiler)

 Examples	 All Options

Description

Specifies module type for current module.  By specifying Module_Type, you can have form, menu and library modules with the same name.

Module:  All

Default FORM


Module_Type (Forms Compiler) examples
Module_Type (Form Compiler) examples

ifcmp60 module=orders userid=scott/tiger module_type=menu


Nofail (Form Compiler)

 Examples	 All Options

Description

Indicates whether to add the NOFAIL keyword to exemacro steps when upgrading from Forms 2.0 only.

Module:  Form

Default NO


Nofail (Forms Compiler) examples
Nofail (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger upgrade=yes version=20 nofail=YES


Options_Screen (Form Compiler)

 Examples	 All Options

Description

Invokes the Options window.

This parameter applies to GUI displays only.

Module:  All

Default NO


Options_Screen (Forms Compiler) examples
Options_Screen (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger options_screen=YES


Output_File (Form Compiler)

 Examples	 All Options

Description

Specifies the file name for the generated file.

When used with upgrade=yes, output_file specifies:

•	the complete name of the upgraded binary design module(.FMB,.MMB, or .PLL file)

Note:  To specify the name of the generated library file, you must use Strip_Source in conjunction with Output_File.

•	the root name (without extension) of the upgraded Forms Runtime executable module (.FMX or .MMX file)

When used with upgrade=yes and build=no, the file extension is ignored.

Module:  All


Output_File (Forms Compiler) examples
Output_File (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger upgrade=yes output_file=myform.fmb


Parse (Form Compiler)

 Examples	 All Options

Description

Converts the text file format of a module (.FMT, .MMT, .PLD) to a binary format (.FMB, .MMB, .PLL).

This operation can also be done from within Form Builder by using the Convert command.

Module:  All

Default NO


Parse (Forms Compiler) examples
Parse (Form Compiler) examples

ifcmp60 module=myform parse=YES


Script (Form Compiler)

 Examples	 All Options

Description

Converts a binary file format (.FMB, .MMB, or .PLL) to a text format (.FMT, .MMT, or .PLD).

This operation can also be done within Form Builder by using the Convert command.

Module:  All

Default NO


Script (Forms Compiler) examples
Script (Form Compiler) examples

ifcmp60 module=myform script=YES


Statistics (Form Compiler)

 Examples	 All Options

Description

Displays a message at the end of the session listing the number of various objects in the compiled form:

•	Object Statistics: The number of alerts, editors, lists of values, procedures, record groups, canvases, visual attributes, windows, and total number of objects.

•	Trigger Statistics: The number of form triggers, block triggers, item triggers, and total number of triggers.

•	Block Statistics: The number of blocks with Array Fetch ON, the average array fetch size, and the total number of blocks.

•	Item Statistics: The number of buttons, check boxes, display items, image items, list items, radio groups, text items, user areas, and total number of items.

Module:  Form

Default NO


Statistics (Forms Compiler) examples
Statistics (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger statistics=YES


Strip_Source (Form Compiler) option
Strip_Source (Form Compiler)

 Examples	 All Options

Description

Removes the source code from the library file and generates a library file that only contains pcode.  The resulting file can be used for final deployment, but cannot be subsequently edited in Form Builder.

When you use Strip_Source, you must specify an output file by using the Output_File (Forms Runtime) parameter.

Module:  Library

Default NO


Strip_Source (Forms Compiler) examples
Strip_Source (Form Compiler) examples

ifcmp60 module=old_lib.pll userid=scott/tiger strip_source=YES output_file=new_lib.pll


Upgrade (Forms Compiler)
Upgrade (Form Compiler)

 Examples	 All Options

Description

Upgrades modules from SQL*Forms 2.0, 2.3, or 3.0 to Form Builder 4.5, or from SQL*Menu 5.0 to an Form Builder 4.5 menu module:

•	To upgrade from SQL*Forms 3.0 or SQL*Menu 5.0 to Form Builder 4.5, specify upgrade=yes and omit version.

•	To upgrade from SQL*Forms 2.0, specify  upgrade=yes and version=20.

•	To upgrade from SQL*Forms 2.3, specify upgrade=yes and  version=23.

Module:  Form, Menu

Default NO

Usage Notes

The Upgrade option does not work in combination with the Insert option.


Upgrade (Forms Compiler) examples
Upgrade (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger upgrade=YES


Upgrade_Roles (Form Compiler)

 Examples	 All Options

Description

Upgrades SQL*Menu 5.0 table privileges to Oracle8 database roles.

Note:  Menu roles are independent of any specific menu application (no module name is specified).  You cannot specify upgrade=yes and upgrade_roles=yes in one run.

Module:  none

Default NO


Upgrade_Roles (Forms Compiler) examples
Upgrade_Roles (Form Compiler) examples

ifcmp60 userid=system/manager upgrade_roles=YES


Version (Form Compiler)

 Examples	 All Options

Description

Indicates version from which to upgrade.  Use in conjunction with upgrade=yes to upgrade from version 2.3 (version=23) or version 2.0 (version=20).

To upgrade from version 3.0, specify upgrade=yes and omit the version parameter.

Module:  Form

Default version=30


Version (Forms Compiler) examples
Version (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger upgrade=yes version=23


Widen_Fields (Form Compiler)

 Examples	 All Options

Description

Use the Widen_Fields option in conjunction with Upgrade. When upgrading to Version 4.5, the bevels on each field can cause the loss of up to one character per field.  Specify this option when upgrading to automatically add one character to the Display Width of each field.  Note:  This has no effect on the maximum allowable data length.

This option is most useful for upgrading Form Builder 3.0 character-mode applications with a large number of 1-6 character fields. The effects of the Widen_Fields option will depend on your interface design, and should be tested carefully.  Effects can include:

•	Text items may overlap boilerplate text if space between fields is limited.

•	If two fields are currently flush against each other, the Widen_Fields option will cause the fields to overlap.

Module:  Form

Default NO


Widen_Fields (Forms Compiler) examples
Widen_Fields (Form Compiler) examples

ifcmp60 module=myform userid=scott/tiger upgrade=yes widen_fields=YES


Setting Form Builder Preferences

 Examples	 All Options

Form Builder preferences specify Form Builder session default behavior.  Choose Tools [image] Preferences in Form Builder to invoke the Preferences dialog box.  To set options, click on the check boxes or fill in file names for the options you choose.

The Preferences dialog box includes both Form Builder and Forms Runtime preferences.

Form Builder Preferences

You can set the following design options to specify the defaults for the current Form Builder session:

•	Save Before Building

•	Build Before Running

•	Suppress Hints

•	Run Module Asynchronously

•	Use System Editor

•	Module Access (File, Database, File/Database)

•	Module Filter (Forms, Menus, Libraries, All)

•	Printer

•	Color Palette

•	Color Mode

For information on a specific design option, see the alphabetical list that follows.

Runtime Options

You can set the following Runtime options to specify the defaults for forms that you run from Form Builder:

•	Buffer Records in File

•	Debug Mode

•	Array Processing

•	Optimize SQL Processing

•	Optimize Transaction Mode Processing

•	Statistics

•	Display Block Menu

•	Query Only Mode

•	Quiet Mode

Runtime options are listed earlier in this chapter.

Keyword Parameters

In addition to the options listed in the Options dialog, you can set these keyword parameters on the Form Builder command line:

•	Module_Type

•	Module_Access

•	Help


Setting Form Builder Options
Setting Form Builder Options examples

ifbld60 module=orders userid=scott/tiger module_type=menu


Color Mode

 All Options

Determines how an Form Builder color palette will be loaded on your system.  Each time you load, open, or create a form, Form Builder loads the Form Builder color palette into your current system color table. Because this system color table can handle only a limited number of colors at once, Form Builder may not be able to accurately modify multiple forms simultaneously if they use different color palettes.  For this reason, use the Read Only - Shared option except when you are actively modifying the Form Builder color palette.

Color Mode options:

Editable	Select Editable mode only when you want to change the Form Builder color palette.  Once you have changed the color palette, return to Read Only - Shared mode.  In Editable mode, each color has its own unique entry in the current system color table, and if there is no more room in the table,  the color palette may refuse to load.

To change the Form Builder color palette:

•	Change Color Mode to Editable and save your options (Tools -> Preferences, General tab, Color Mode).

•	Restart Form Builder.

•	Use Formet -> Layout Options -> Color Palette to make changes to the color palette (only when the Layout Editor is open).

•	Use File -> Export -> Color Palette to save the Form Builder color palette to a file (only when the Layout Editor is open).

•	Change your options to use the new color file (Tools -> Preferences, General tab, Color Palette).

•	Change Color Mode back to Read Only - Shared and save your options.

•	Restart Form Builder.

Read Only-Shared	In Read Only - Shared mode, Form Builder maps duplicate colors to the same entry in the current system color table before appending new entries from your Form Builder color palette.  Read Only - Shared will help you avoid the color flicker that can result when you switch between Form Builder color palettes and is the recommended setting for Color Mode unless you are modifying the palette.

Read Only-Private	This option is provided for consistency with Graphics Builder, and is not relevant for Form Builder.  In Form Builder, it maps to Read Only - Shared.

Default Read Only - Shared


Color Palette

 All Options

Description

Specifies the name of the Form Builder color palette that is automatically loaded when you create a new form.  If this field is left blank, the Form Builder default color palette is loaded.

For more information about color palettes, refer to About Color Palettes.


Build Before Running

 All Options

Description

Determines whether Form Builder automatically compiles the active module before running a form.  When Build Before Running is checked, Form Builder does the following when you issue the Program [image] Run Form command to run a specified form:

•	builds the active form, menu, or library module to create an executable runfile having the same name as the module

•	runs the .FMX file (form runfile) you specify in the Run dialog box.

This option lets you avoid issuing separate Compile and Run commands each time you modify and then run a form.  However, this option does not save the module.  You must issue the File [image] Save command to save the module, or check the Save Before Building preference.

Also, when the Build Before Running option is checked, Form Builder does not automatically compile any menu or library modules attached to that form.  You must compile menu and library modules separately before running a form that references them.

Default:  Off


Help (Form Builder)

 Examples	 All Options

Description

Invokes the Form Builder help screen.

Module:  All

Default NO


Help (Form Builder) examples

ifbld60 help=YES


HTML File Name

 Related Topics	 All Options

Description

Specifies the HTML file to be used to run the form using the Web Previewer.

When you preview a form in the Web Previewer, a container HTML file is created dynamically with the runtime options specified by preferences or by default.  This file is sent to the Web Previewer to execute your form.  Enter the path and filename of a custom HTML file to supersede the one Form Builder creates.

For more information on creating a base HTML file see the section on "Configuring the Forms Server" in Deploying Forms Applications to the Web


Access preference (Form Builder)

 Examples	 All Options

Description

Specifies whether to open and save modules to the file system or to the database.

This option can be set on the command line using the Module_Access parameter or within the Form Builder Access tab of the Preferences dialog box.

The command line parameter establishes access on a one-time basis for the current Form Builder session.  On the command line, the Module_Access option can be set to file or database.

To set this option for future Form Builder sessions, use the Access preference (Tools [image] Preferences Access tab) to change your Preferences file.

In the Module Access option, you can specify one of the following storage preferences for opening and saving modules:

File	Modules are loaded from and saved to the file system.
Database	Modules are loaded from and saved to the database.
Ask	Modules can be loaded from and saved to either the file system or the database.  Form Builder will prompt for the location of the file each time you perform these operations.
Module:  All

Default FILE


Access preference (Form Builder) examples

ifbld60 module=myform userid=scott/tiger module_access=database


Module_Type (Form Builder)

 Examples	 All Options

Description

Specifies module type for current module.  By specifying Module_Type, you can have form, menu and library modules with the same name.

Module:  All

Default FORM


Module_Type (Form Builder) examples

ifbld60 module=orders userid=scott/tiger module_type=menu


Printer

The name of the default printer.  This name is operating-system dependent.

For more information about printers, refer to the Form Builder documentation for your operating system.


Run Modules Asynchronously

 All Options

Determines whether forms that you run from Form Builder are executed synchronously or asynchronously with respect to Form Builder itself:

•	When Run Modules Asynchronously is Off, forms you run from Form Builder are synchronous.  That is, you cannot work in Form Builder until you exit the form.

•	When Run Modules Asynchronously is On, forms you run from Form Builder are asynchronous, so you can move back and forth between Form Builder and Forms Runtime.

When you run a form synchronously, Form Builder notifies you of any Forms Runtime startup errors that occur by displaying an alert in Form Builder.  When you run a form asynchronously, no such communication between Forms Runtime and Form Builder occurs, and Forms Runtime startup errors are not reported in Form Builder.

Default  Off


Save Before Building

Determines whether Form Builder saves the current module automatically before it is built either when you choose File [image] Administration [image] Compile File or when the form is built before running when the Build Before Running preference is checked.

Default    Off


Subclassing Path

 All Options

Description

Specifies whether to save the path of an original object with the subclassed object.

Specify one of the following preferences for saving the path of original objects with subclassed objects:

Remove	The path will be removed from the filename of the original object referenced in the subclassed object.

Keep	The subclassed object will reference the original object according to the full path.

Ask	Each time you subclass an object Form Builder will display a dialog box prompting whether to remove or keep the path.

Default ASK

Notes

A subclassed object inherits property values from the original object and references the original object by the file name of the form in which it is saved.  The full path name of the form may be saved with the subclassed object or only the filename.  When the form containing the subclassed object is opened, Form Builder looks for the file specified for the subclassed object.  If the filename is specified without the path, Form Builder looks in the current directory in which Form Builder was started.


Suppress Hints

 All Options

Determines whether hints are suppressed from the message line as you work in Form Builder.

Default   Off


Term (Form Builder)

 Examples	 All Options

Description

Specifies a mapping other than the default mapping for the current device and product:

resfile	The file name specified is the name of your Oracle Terminal resource file.  If you do not specify resfile, Form Builder defaults to a file name that is platform-specific, but begins with "FMR"  on most platforms.  For example, the Microsoft Windows default file is FMRUSW.

mymapping	The mapping name specified is the mapping you want to use for this Form Builder session.

For more information on resource files, refer to the Form Builder documentation for your operating system.

Note:  You or the DBA define mappings with Oracle Terminal.


Term (Form Builder) examples

ifbld60 module=myform userid=scott/tiger term=resfile:mymapping


USESDI (Forms Runtime)
USESDI (Forms Runtime and Web Forms Runtime)

 Examples	 All Options

Description

Use single document interface (SDI) system of window management during a Forms Runtime or Web Forms Runtime session.

There is no multiple document interface (MDI) root window.  MDI toolbars exist in parent windows and menus will be attached to each window.

Calls to the FORMS_MDI_WINDOW constant returns NULL as the MDI window handle when usesdi=YES.

Option Name  None

Default YES

Usage Notes:

SDI Forms are not native windows and you cannot navigate to the SDI window by using certain native OS methods to access windows, such as Alt-TAB on Microsoft Windows.


USESDI (Forms Runtime) examples

ifrun60 module=myform userid=scott/tiger usesdi=YES


Use System Editor

 All Options

Determines which editor Form Builder uses when you invoke an editor from a multi-line text item.  When Use System Editor is unchecked, Form Builder displays the default editor.   When Use System Editor is checked, Form Builder displays the default system editor defined on your system.

Note:  If Use System Editor is checked and you are using an editor with a native document format, you must save the document as ASCII text (with line breaks), instead of saving the document in that editor's format.

For more information about defining the default system editors, refer to the Form Builder documentation for your operating system.

Default   Off


User Preference File

 All Options

Although the Preferences dialog box is the most convenient way to set preferences, you can also set them directly in the preference file (usually called PREFS.ORA).

The preference file that enforces Form Builder options is automatically updated every time you change your preferences.  Form Builder reads the updated preference file when you start Form Builder.  This file contains keywords and settings that allow you to preset each of the Form Builder and Forms Runtime options.

You can use any of the Form Builder or Forms Runtime keyword parameters listed in this chapter in a user preference file.  For example, to ensure that any form that you run from Form Builder runs in quiet mode, you would include the following line in the user preference file:

FORMS.QUIET=ON

The preference file also allows you to preset a mapping for Form Builder.  On most platforms, the preference file must be named PREFS.ORA and must reside in the login directory.

If you start Form Builder with a command line parameter that specifies a preference setting or mapping, the command line parameter overrides the setting in the preference file.  Also, if a line in the preference file contains an error, Form Builder ignores that line when it reads the file.

Syntax for Options

To preset a Form Builder or Forms Runtime option, include the appropriate keyword and setting in the preference file, just as you would on the command line.  Use the following syntax:

KEYWORD = {ON | OFF | STRING}

For a list of keywords and appropriate values, save your preferences, then examine the current contents of your PREFS.ORA file.


Welcome Dialog

 All Options

Description

Determines whether the welcome screen is displayed when Form Builder is started.

When checked, the welcome screen will be displayed when Form Builder is started.   When unchecked, Form Builder starts with a new, blank module called module1.

Default ON


Welcome Pages

 All Options

Description

Determines whether the welcome page for a specific wizard is displayed when the wizard is invoked.

When checked, the welcome page will be displayed when the wizard is started.   When unchecked, the wizard does not display the welcome page.

Applies to

Data Block Wizard

LOV Wizard

Layout Wizard

Chart Wizard

Default  ON


Foreign Function Interface


About foreign functions

  Related Topics

Foreign functions are subprograms written in a 3GL programming language for customizing Form Builder applications.  Foreign functions can interact with Oracle databases, and Form Builder variables and items.  Although it is possible to access Form Builder variables and items, you cannot call Form Builder built-in subprograms from a foreign function.

Foreign functions can be used to perform the following tasks:

•	Replace default Form Builder processing when running against a non-Oracle data source using transactional triggers.

•	Perform complex data manipulation.

•	Pass data to Form Builder from operating system text files.

•	Manipulate LONG RAW data.

•	Pass entire PL/SQL blocks for processing by the server.

•	Control real time devices, such as a printer or a robot.

Note: You should not perform host language screen I/O from a foreign function.  This restriction exists because the runtime routines that a host language uses to perform screen I/O conflict with the routines that Form Builder uses to perform screen I/O.  However, you can perform host language file I/O from a foreign function.

Foreign functions that can be invoked from a PL/SQL interface must be contained in a dynamic library.

Initializing a foreign function identifies the location of a dynamic library and dissects the foreign function prototype.  The initialization process provides a one-to-one match between foreign function host language data types and PL/SQL data types.  Initialize a foreign function in a PL/SQL package body.


About the PL/SQL interface

  Related Topics

In Form Builder, you can invoke a foreign function from a PL/SQL interface using PL/SQL language conventions.

A PL/SQL package encapsulates the components that are used in creating a PL/SQL interface to a foreign function.  You can include PL/SQL interfaces to multiple foreign functions in a single PL/SQL package.  For each PL/SQL interface to a foreign function, you must follow the procedure of initializing the foreign function, associating a PL/SQL subprogram with the foreign function, and mimicking the foreign function prototype in PL/SQL.  Alternatively, you can opt to include a PL/SQL interface to a single foreign function in a PL/SQL package.

Foreign functions invoked from a PL/SQL interface must be contained in a dynamic library.  Examples of dynamic libraries include dynamic link libraries on Microsoft Windows, and shared libraries on UNIX systems.  The procedure for creating a dynamic library depends on your operating system.  For more information on creating dynamic libraries in your environment, refer to the documentation for your operating system.

Creating a PL/SQL interface to foreign functions requires the use of the ORA_FFI built-in package (Oracle Foreign Function Interface).  The ORA_FFI package consists of a group of PL/SQL built-in subprograms for creating a  PL/SQL interface to foreign functions.  For more details on the ORA_FFI package, refer to the Oracle Procedure Builder Developer's Guide.

By associating a PL/SQL subprogram with a foreign function, you can invoke the foreign function each time you call the associated PL/SQL subprogram.  Associating a foreign function with a PL/SQL subprogram is necessary because Form Builder uses PL/SQL constructs.  The associated PL/SQL subprogram specifies the memory location of the foreign function code to be executed.

Once you have associated a PL/SQL subprogram with a foreign function, Form Builder invokes the foreign function whenever you call the PL/SQL subprogram.  The associated subprogram requires the first parameter to be a foreign function handle, a parameter type that does not have a host language equivalent in the foreign function prototype.

To provide a PL/SQL interface that has a one-to-one correspondence between the parameter and return data types of the foreign function, you must mimic the prototype of the foreign function using PL/SQL; this is the PL/SQL interface that is made public.

Note:  An alternative approach for invoking a foreign function is from a user exit interface.  Using a user exit interface to invoke foreign functions occasionally requires relinking Form Builder Runform.  Because invoking foreign functions from a user exit interface can require relinking Form Builder Runform, using a PL/SQL interface provides a looser bind than that of a user exit interface.


Types of foreign functions

  Related Topics

You can develop the following types of foreign functions:

•	Oracle Precompiler foreign functions

•	OCI (ORACLE Call Interface) foreign functions

•	non-ORACLE foreign functions

You can also develop foreign functions that combine both the ORACLE Precompiler interface and the OCI.

Oracle Precompiler Foreign Functions  An Oracle Precompiler foreign function incorporates the Oracle Precompiler interface.  This interface allows you to write a subprogram in one of the following supported host languages with embedded SQL commands:

•	Ada

•	C

•	COBOL

•	FORTRAN

•	Pascal

•	PL/I

Note:  Not all operating systems support all of the listed languages.  For more information on supported languages, refer to the Form Builder documentation for your operating system.

With embedded SQL commands, an Oracle Precompiler foreign function can access Oracle databases as well as Form Builder variables and items.  You can access Form Builder variables and items by using a set of Oracle Precompiler statements that provide this capability.

Because of the capability to access both Oracle databases and Form Builder variables and items, most of your foreign functions will be Oracle Precompiler foreign functions.  For more information on the Oracle Precompiler interface, refer to the Programmer's Guide to the Oracle Precompilers.

Oracle Call Interface(OCI) Foreign Functions  An OCI foreign function incorporates the Oracle Call Interface.  This interface allows you to write a subprogram that contains calls to Oracle databases.  A foreign function that incorporates only the OCI (and not the Oracle Precompiler interface) cannot access Form Builder variables and items. For more information on the OCI, refer to the Oracle Call Interface Programmer's Guide Documentation Set.

Non-Oracle Foreign Functions  A non-Oracle foreign function does not incorporate either the Oracle Precompiler interface or the OCI.  For example, a non-Oracle foreign function might be written entirely in the C language.  A non-Oracle foreign function cannot access Oracle databases, or Form Builder variables and items.


Precompiler statements

  Related Topics

All Oracle Precompiler foreign functions can use host language statements to perform procedural operations.  Precompiler foreign functions can also use the following types of statements to perform additional functions such as accessing the database and manipulating Form Builder variables and items.

Statement	Use
EXEC SQL	Performs SQL commands.
EXEC TOOLS GET	Retrieves values from Form Builder to a foreign function.
EXEC TOOLS SET	Sends values from a foreign function to Form Builder.
EXEC TOOLS MESSAGE	Passes a message from a foreign function to display in Form Builder.
EXEC TOOLS GET CONTEXT	Obtains context information previously saved in a foreign function.
EXEC TOOLS SET CONTEXT	Saves context information from one foreign function for use in subsequent foreign function invocations.
EXEC ORACLE	Executes Oracle Precompiler options.

An Oracle Precompiler foreign function source file includes host programming language statements and Oracle Precompiler statements with embedded SQL statements.  Precompiling an Oracle Precompiler foreign function replaces the embedded SQL statements with equivalent host programming language statements.  After precompiling, you have a source file that you can compile with a host language compiler. For more information on a specific precompiler, refer to the appropriate precompiler documentation for your environment.


Creating a PL/SQL interface to foreign functions

 Examples	  Related Topics

To create a PL/SQL interface to a foreign function:

1	Initialize the foreign function.

2	Associate a PL/SQL subprogram with the foreign function.

3	Mimick the foreign function prototype with PL/SQL.


Initializing a foreign function

 Examples	  Next Step	  Related Topics

To initialize a foreign function:

1	Use ORA_FFI.LOAD_LIBRARY to obtain a library handle to the dynamic library containing the foreign function.  You must provide the name and location of the dynamic library.

2	Use ORA_FFI.REGISTER_FUNCTION to obtain a function handle to the foreign function.  You must provide the library handle and name of the foreign function.

3	Use ORA_FFI.REGISTER_PARAMETER to register the foreign function parameter types.  For each parameter, provide the function handle to identify the foreign function and a corresponding PL/SQL equivalent parameter type.  You must register parameters in the order they appear in the foreign function prototype.

4	Use ORA_FFI.REGISTER_RETURN to register the foreign function return type.  You must provide the function handle to identify the foreign function and a corresponding PL/SQL equivalent return type.


Initializing a foreign function example

Here is an example of initializing a foreign function:

PACKAGE BODY calc IS
BEGIN
/*
This example shows how to initialize the foreign function
int ADD(int X, int Y) that is contained in the dynamic
library CALC.DLL;
*/
lh_calc := ora_ffi.load_library('c:\mathlib\', 'calc.dll');
fh_add := ora_ffi.register_function(lh_calc,'add',
ora_ffi.C_STD);
ora_ffi.register_return(fh_add,ORA_FFI.C_INT);
ora_ffi.register_parameter(fh_add,ORA_FFI.C_INT);
ora_ffi.register_parameter(fh_add,ORA_FFI.C_INT);
END;


Associating a PL/SQL subprogram with a foreign function

 Examples	  Next Step

To associate a PL/SQL subprogram with a foreign function:

1	Obtain a function handle using ORA_FFI.FIND_FUNCTION or ORA_FFI.REGISTER_FUNCTION.

2	In the declaration section of the body of your PL/SQL package, define a PL/SQL subprogram that accepts a parameter of type ORA_FFI.FUNCHANDLETYPE as the first parameter followed by PL/SQL data type equivalents for all other foreign function parameters.

3	Include a PRAGMA interface in the PL/SQL subprogram.

The PRAGMA statement invokes the foreign function by passing control to the memory location in Form Builder that can communicate with dynamic libraries.


Associating a PL/SQL subprogram with a foreign function example

Here is an example of associating a subprogram with a foreign function:

PACKAGE BODY calc IS
/*
This example shows how to associate a PL/SQL subprogram with
 	the given function prototype, int ADD(int X, int Y);
*/

FUNCTION ff_ADD(ff_handle ORA_FFI.FUNCHANDLETYPE,
 X IN BINARY_INTEGER,
 Y IN BINARY_INTEGER);
RETURN BINARY_INTEGER;
PRAGMA interface(C, ff_ADD, 11265);

BEGIN
...
END;


Mimicking a foreign function prototype with PL/SQL

 Examples	  Related Topics

To mimic a foreign function prototype with PL/SQL:

1	In the declaration section of the body of your PL/SQL package, define a PL/SQL subprogram that accepts and returns PL/SQL data type equivalents of the foreign function parameters; this is the subprogram that mimics the foreign function prototype.

2	From the body of the mimicking subprogram, call the PL/SQL subprogram associated with the foreign function.

3	Enter a PL/SQL subprogram prototype in the specification of your PL/SQL package.


Mimicking a foreign function prototype with PL/SQL example

Here is an example of mimicking a foreign function definition:

PACKAGE calc IS
FUNCTION ADD(X IN BINARY_INTEGER, Y IN BINARY_INTEGER)
RETURN BINARY_INTEGER;
END;

PACKAGE BODY calc IS
/*
Given the foreign function prototype, int ADD(int X, int y),
and the associated PL/SQL subprogram,
FUNCTION ff_ADD(ff_handle,X,Y),
this example shows how to mimic the foreign function
definition in PL/SQL.
*/

FUNCTION ADD(X IN BINARY_INTEGER, Y IN BINARY_INTEGER)
RETURN BINARY_INTEGER IS
BEGIN
RETURN(ff_ADD(ff_ADD_HANDLE,X,Y));
END;

BEGIN
...
END;


Invoking a foreign function from a PL/SQL interface

  Related Topics

After defining a PL/SQL interface to a foreign function, you can invoke the foreign function using PL/SQL from Form Builder.  To invoke the foreign function from PL/SQL, specify the PL/SQL package name followed by a dot and the PL/SQL function name. This example shows how to invoke the foreign functions Get_Image and Show_Image from the ImageLib PL/SQL package.

PROCEDURE display_image(keywrd IN OUT VARCHAR2) IS
img_ptr	ORA_FFI.POINTERTYPE;
BEGIN
img_ptr := ImageLib.Get_Image(keywrd);
ImageLib.Show_Image(img_ptr,2);
END;

Invoking a foreign function from a PL/SQL interface passes process control to the foreign function.  Upon completion of the foreign function, process control is returned to Form Builder.


Passing parameter values to a foreign function using PL/SQL

 Examples	  Related Topics

Passing parameter values, such as Form Builder variables and items, to a foreign function that is invoked from a PL/SQL interface is similar to passing parameters to any PL/SQL subprogram.  Be sure to register the parameter values when you create the PL/SQL interface.

After assigning a Form Builder variable or item value to a PL/SQL variable, pass the PL/SQL variable as a parameter value in the PL/SQL interface of the foreign function.  The PL/SQL variable that is passed as a parameter must be a valid PL/SQL data type; it must also be the appropriate parameter type as defined in the PL/SQL interface.


Passing parameter values to a foreign function using PL/SQL example

/*
The variables X_Val and Y_Val contain values obtained from
Form Builder and are used as parameter values in the ADD
foreign function.
*/
DECLARE
X_Val 	BINARY_INTEGER := :addblk.Xitm;
Y_Val	BINARY_INTEGER := :addblk.Yitm;
sum	BINARY_INTEGER;

BEGIN
sum := ADD(X_Val, Y_Val);
END;


Returning values from a foreign function using PL/SQL

 Examples	  Related Topics

Returning a value from a foreign function to a Form Builder variable or item is similar to returning a value from any PL/SQL function.  Be sure to register the return value when you create the PL/SQL interface.

You obtain a return value from a foreign function by assigning the return value to a Form Builder variable or item.  Make sure that the Form Builder variable or item is the same data type as the return value from the foreign function.


Returning a value from a foreign function using PL/SQL example

/*
The BINARY_INTEGER that the ADD foreign function returns is
assigned to the item sum_itm of the block addblk.
*/
BEGIN
addblk.sum_itm:= ADD(X_Val, Y_Val);
END;


Simplifying complex parameter data types

  Related Topics

The ORA_FFI package only supports simple PL/SQL parameter and return data types that correspond to the C programming language.  When complex parameter and return data types are used in foreign function prototypes, you must simplify or substitute the parameter and return type.  If simplification is not possible, use a user exit interface instead.

For example, there is no PL/SQL equivalent to a C language structure data type.  You can simplify the structure data type by creating a foreign function that builds the structure.  You cannot create a PL/SQL interface to a foreign function without simplifying the complex parameter type.

MainStruct is an example of a complex parameter type:

Foreign_Func(MainStruct a, int b, char c)
{
/* process MainStruct */
...
}

To simplify the the MainStruct parameter, consider the following approach:

New_Foreign_Func(int x, float y, char* z, int b, char c)
{
 struct MainStruct
{
int x;
float y;
char* z;
}
/* process MainStruct */
...
}


Creating a PL/SQL interface on Microsoft Windows example

  Related Topics

Although creating a PL/SQL interface is similar on most platforms, this topic describes aspects of Form Builder that is specific to its use in Microsoft Windows.

This example invokes Windows Profile String functions from a PL/SQL interface.  The PL/SQL package OraWinProfile contains the PL/SQL interface to the Windows Profile String functions.

This is the PL/SQL package specification:

PACKAGE OraWinProfile IS
/*
Function WritePrivateString calls the Windows
WritePrivateProfileString function
*/
FUNCTION WritePrivateString(pSection IN VARCHAR2,
     pEntry IN VARCHAR2,
     pString IN VARCHAR2,
     pFilename IN VARCHAR2)
RETURN BOOLEAN;

/*
Function GetPrivateString calls the Windows
GetPrivateProfileString function
*/
FUNCTION GetPrivateString(pSection IN VARCHAR2,
   pEntry IN VARCHAR2,
   pDefault IN VARCHAR2,
   pReturnBuffer IN OUT VARCHAR2,
   pReturnBufferN IN BINARY_INTEGER,
   pFilename IN VARCHAR2)
RETURN BINARY_INTEGER;
END OraWinProfile;

This is the PL/SQL package body:

PACKAGE BODY OraWindProfile IS
lh_window	ora_ffi.libHandleType;
lh_forms	ora_ffi.libHandleType;
fh_wpps	ora_ffi.funcHandleType;
fh_gpps	ora_ffi.funcHandleType;

/*
icd_wpps function acts as the interface to the
WritePrivateString function in Windows
*/
FUNCTION icd_wpps(funcHandle IN ora_ffi.funcHandleType,
   pSection IN OUT VARCHAR2,
   pEntry IN OUT VARCHAR2,
   pString IN OUT VARCHAR2,
   pFilename IN OUT VARCHAR2)
RETURN BINARY_INTEGER;
PRAGMA interface(c,icd_wpps,11265);

/*
icd_gpps function acts as the interface to the
GetPrivateString function in windows
*/
FUNCTION icd_gpps(funcHandle IN ora_ffi.funcHandleType,
   pSection IN OUT VARCHAR2,
   pEntry IN OUT VARCHAR2,
   pDefault IN OUT VARCHAR2,
   pReturnBuffer IN OUT VARCHAR2,
   pRetrunBufferN IN BINARY_INTEGER,
   pFilename IN OUT VARCHAR2)
RETURN BINARY_INTEGER;
PRAGMA(c,icd_gpps,11265);

FUNCTION WritePrivateString(pSection IN VARCHAR2,
     pEntry IN VARCHAR2,
     pString IN VARCHAR2,
     pFilename IN VARCHAR2)
RETURN BOOLEAN IS
/* WritePrivateString calls the Windows function */
/* Make copies of in out arguments */
lSection VARCHAR2(1024) := pSection;
lEntry VARCHAR(1024) := pEntry;
lString VARCHAR2(1024) := pString;
lFilename VARCHAR(1024) := pFilename;

BEGIN
/*
validate arguments--although NULL is a valid argument
for Windows functions, we are going to prohibit this
case because of the format of the string that is
returned
*/
IF (lSection is NULL) OR (lEntry is NULL) OR
   (lString is NULL) OR (lFilename is NULL) THEN
    RAISE VALUE_ERROR;
END IF;
RETURN(icd_wpps(fh_wpps,lSection,lEntry,lString,
lFilename)<>0);
END WritePrivateString;

FUNCTION GetPrivateString(pSection IN VARCHAR2,
   pEntry IN VARCHAR2,
   pDefault IN VARCHAR2,
   pReturnBuffer IN OUT VARCHAR2,
   pReturnBufferN IN BINARY_INTEGER,
   pFilename IN VARCHAR2)
RETURN BINARY_INTEGER IS
/* GetPrivateString calls the Windows function */
/* Make copies of in out arguments */
lSection VARCHAR2(1024) := pSection;
lEntry VARCHAR(1024) := pEntry;
lDefault VARCHAR2(1024) := pDefault;
lFilename VARCHAR(1024) := pFilename;

BEGIN
/*
validate arguments--although NULL is a valid argument for
Windows functions, we are going to prohibit this case
because of the format of the string that is returned
*/
IF (lSection is NULL) OR (lEntry is NULL) OR
   (lDefault is NULL) OR (lFilename is NULL) OR
 	   (pReturnBufferN <= 0) THEN
    RAISE VALUE_ERROR;
END IF;
/* Pad the buffer with spaces */
pReturnBuffer := rpad(' ', pReturnBufferN);
RETURN(icd_gpps(fh_gpps,lSection,lEntry,lDefault,
pReturnBuffer,pReturnBufferN,lFilename));
END GetPrivateString;

BEGIN
/* Declare a library handle to the Windows 386 Kernel */
lh_windows := ora_ffi.load_library(NULL,'krnl386.exe');

/*
Register the components of WritePrivateString
 This is function prototype for WritePrivateProfileString:
 BOOL WritePrivateProfileString(LPCSTR lpszSection,
    LPCSTR lpszEntry,
    LPCSTR lpszString,
    LPCSTR lpszFilename)
*/
fh_wpps := ora_ffi.register_function(lh_windows,
'WritePrivateProfileString',
 ora_ffi.PASCAL_STD);

ora_ffi.register_return(fh_wpps,ORA_FFI.C_SHORT);
ora_ffi.register_parameter(fh_wpps,ORA_FFI.C_CHAR_PTR);
ora_ffi.register_parameter(fh_wpps,ORA_FFI.C_CHAR_PTR);
ora_ffi.register_parameter(fh_wpps,ORA_FFI.C_CHAR_PTR);
ora_ffi.register_parameter(fh_wpps,ORA_FFI.C_CHAR_PTR);

/*
Register the components of GetPrivateString
This is function prototype for GetPrivateProfileString:
int GetPrivateProfileString(LPCSTR lpszSection,
 LPCSTR lpszEntry,
 LPCSTR lpszDefault,
 LPCSTR lpszReturnBuffer,
 int cbReturnBuffer,
 LPCSTR lpszFilename)
*/
fh_gpps := ora_ffi.register_function(lh_windows,
      'GetPrivateProfileString',
       ora_ffi.PASCAL_STD);
ora_ffi.register_return(fh_gpps,ORA_FFI.C_INT);
ora_ffi.register_parameter(fh_wpps,ORA_FFI.C_CHAR_PTR);
ora_ffi.register_parameter(fh_wpps,ORA_FFI.C_CHAR_PTR);
ora_ffi.register_parameter(fh_wpps,ORA_FFI.C_CHAR_PTR);
ora_ffi.register_parameter(fh_wpps,ORA_FFI.C_CHAR_PTR);
ora_ffi.register_parameter(fh_wpps,ORA_FFI.C_INT);
ora_ffi.register_parameter(fh_wpps,ORA_FFI.C_CHAR_PTR);
END OraWinProfile;

Here is an example of how to invoke the WritePrivateProfileString and the GetPrivateProfileString functions from a PL/SQL interface in Form Builder:

DECLARE
tmpb BOOLEAN;
tmpn NUMBER;
buffer VARCHAR(1024) := '';
buffern BINARY_INTEGER := 1024;
BEGIN
tmpb := OraWinProfile.WritePrivateString('Section',
    'Entry',
    'string1',
    'PROFILE.INI');
tmpn := OraWinProfile.GetPrivateString('Section',
  'Entry',
  'Bad Entry',
   buffer,
   buffern,
  'PROFILE.INI');
   MESSAGE(buffer);
END;

You invoke the WritePrivateString and GetPrivateString functions from the OraWinProfile package. After executing the example PL/SQL code, the following two lines are appended to the PROFILE.INI file.

[Section]
Entry=String1

The identical results would have been obtained if the Windows Profile String functions, WritePrivateString and GetPrivateString,  were called from outside Form Builder.  From this example, you can see how a variety of foreign functions can be invoked in Form Builder from a PL/SQL interface.


Accessing the Microsoft Windows SDK from a PL/SQL interface

  Related Topics

Many functions from the Microsoft Windows Software Developer's Kit (SDK) are accessible from a PL/SQL interface.  Creating a PL/SQL interface to a Microsoft Windows SDK function is similar to creating a PL/SQL interface to any foreign function.

The parameters and return types of the Microsoft Windows SDK function must be data types that have a PL/SQL equivalent; they cannot be complex data types that cannot be simplified. For more information on simplifying complex data types, refer to Invoking a Foreign Function from a PL/SQL Interface.

A foreign function with complex parameters and return data types that cannot be simplified can only be invoked from a user exit interface.  An example of a complex parameter data type that cannot be simplified is a window handle, a parameter data type recognized by many Microsoft Windows SDK functions.  A window handle is a unique internal character constant that is used to refer to interface objects.

In instances where the Microsoft Windows SDK function requires a window handle, you cannot invoke the function from a PL/SQL interface.  Instead, you should use a user exit interface and the Window_Handle property to provide the necessary parameters.  Window_Handle is a property of Form Builder items and windows.

In cases where the Microsoft Windows SDK function call is typical of a C language function call without complex data types, you can invoke the function from a PL/SQL interface.  Treat the Microsoft Windows SDK function like any other foreign function: during initialization, load the library and register the function name, return type, and parameters.  After the creation of a PL/SQL interface to the Microsoft Windows SDK function, invoke the Windows SDK function from Form Builder using PL/SQL.


Foreign function examples

This section includes several examples that demonstrate how to use foreign functions.

1	Creating a PL/SQL interface on Microsoft Windows

2	Using ORA_FFI to open the File Open dialog on Windows

3	Using ORA_FFI to call Unix(SUN) executables with a STDIN/STDOUT type interface


Using ORA_FFI to open the File Open dialog on Windows example

PACKAGE OraDlg IS

FUNCTION OraMultiFileDlg

(Title IN  VARCHAR2,

Filter IN  VARCHAR2,

Dir IN  VARCHAR2,

FileString IN OUT VARCHAR2)

RETURN PLS_INTEGER;

FUNCTION OraSingleFileDlg

(Title IN  VARCHAR2,

Filter IN  VARCHAR2,

Dir IN  VARCHAR2,

FileString IN OUT VARCHAR2)

RETURN PLS_INTEGER;

END OraDlg;

PACKAGE BODY OraDlg IS

     	lh_ORADLG ora_ffi.libHandleType;

fh_OraMultiFileDlg ora_ffi.funcHandleType;

fh_OraSingleFileDlg ora_ffi.funcHandleType;

FUNCTION i_OraMultiFileDlg

(funcHandle IN ora_ffi.funcHandleType,

Title IN OUT VARCHAR2,

Filter IN OUT VARCHAR2,

Dir IN OUT VARCHAR2,

FileString IN OUT VARCHAR2)

RETURN PLS_INTEGER;

PRAGMA INTERFACE(C,i_OraMultiFileDlg,11265);

FUNCTION OraMultiFileDlg

(Title IN  VARCHAR2,

Filter IN  VARCHAR2,

Dir IN  VARCHAR2,

FileString IN OUT VARCHAR2)

RETURN PLS_INTEGER IS

Title_l VARCHAR2(128)  :=  RPAD(SUBSTR(NVL(Title,'Open'),1,128),128,CHR(0));

Filter_l VARCHAR2(128)  :=  RPAD(SUBSTR(NVL

(Filter,'All Files (*.*)|*.*|'),1,128),128,CHR(0));

Dir_l VARCHAR2(256)  :=  RPAD(SUBSTR(NVL(Dir,' '),1,256),256,CHR(0));

FileString_l VARCHAR2(2000)  :=  RPAD(SUBSTR(NVL(FileString,' '),1,2000),2000,CHR(0));

rc PLS_INTEGER;

BEGIN

     rc  := i_OraMultiFileDlg(fh_OraMultiFileDlg,

Title_l,

Filter_l,

Dir_l,

FileString_l);

     FileString := FileString_l;

RETURN (rc);

END ;

FUNCTION i_OraSingleFileDlg

(funcHandle IN ora_ffi.funcHandleType,

Title IN OUT VARCHAR2,

Filter IN OUT VARCHAR2,

Dir IN OUT VARCHAR2,

FileString IN OUT VARCHAR2)

RETURN PLS_INTEGER;

PRAGMA INTERFACE(C,i_OraSingleFileDlg,11265);

FUNCTION OraSingleFileDlg

(Title IN  VARCHAR2,

Filter IN  VARCHAR2,

Dir IN  VARCHAR2,

FileString IN OUT VARCHAR2)

RETURN PLS_INTEGER IS

Title_l VARCHAR2(128)  :=  RPAD(SUBSTR(NVL(Title,'Open'),1,128),128,CHR(0));

Filter_l VARCHAR2(128)  :=  RPAD(SUBSTR(NVL

(Filter,'All Files (*.*)|*.*|'),1,128),128,CHR(0));

Dir_l VARCHAR2(256)  :=  RPAD(SUBSTR(NVL(Dir,' '),1,256),256,CHR(0));

FileString_l VARCHAR2(2000)  :=  RPAD(SUBSTR(NVL(FileString,' '),1,2000),2000,CHR(0));

rc PLS_INTEGER;

BEGIN

     rc  := i_OraSingleFileDlg(fh_OraSingleFileDlg,

Title_l,

Filter_l,

Dir_l,

FileString_l);

     FileString := FileString_l;

RETURN (rc);

END ;

BEGIN

     BEGIN

     lh_ORADLG := ora_ffi.find_library('ORADLG.DLL');

     EXCEPTION WHEN ora_ffi.FFI_ERROR THEN

     lh_ORADLG := ora_ffi.load_library(NULL,'ORADLG.DLL');

     END ;

     fh_OraMultiFileDlg := ora_ffi.register_function

(lh_ORADLG,'OraMultiFileDlg',ora_ffi.PASCAL_STD);

     ora_ffi.register_parameter(fh_OraMultiFileDlg,ORA_FFI.C_CHAR_PTR);

     ora_ffi.register_parameter(fh_OraMultiFileDlg,ORA_FFI.C_CHAR_PTR);

     ora_ffi.register_parameter(fh_OraMultiFileDlg,ORA_FFI.C_CHAR_PTR);

     ora_ffi.register_parameter(fh_OraMultiFileDlg,ORA_FFI.C_CHAR_PTR);

     ora_ffi.register_return(fh_OraMultiFileDlg,ORA_FFI.C_LONG);

     fh_OraSingleFileDlg := ora_ffi.register_function

(lh_ORADLG,'OraSingleFileDlg',ora_ffi.PASCAL_STD);

     ora_ffi.register_parameter(fh_OraSingleFileDlg,ORA_FFI.C_CHAR_PTR);

     ora_ffi.register_parameter(fh_OraSingleFileDlg,ORA_FFI.C_CHAR_PTR);

     ora_ffi.register_parameter(fh_OraSingleFileDlg,ORA_FFI.C_CHAR_PTR);

     ora_ffi.register_parameter(fh_OraSingleFileDlg,ORA_FFI.C_CHAR_PTR);

     ora_ffi.register_return(fh_OraSingleFileDlg,ORA_FFI.C_LONG);

END OraDlg;


Using ORA_FFI to call Unix(SUN) executables with a STDIN/STDOUT type interface example

/* Copyright (c) 1997 by Oracle Corporation */

/*

   NAME

     ora_pipe_io_spec.sql - Specification for access to Unix Pipe mechanism

   DESCRIPTION

     Demonstration of how to use the ORA_FFI Package to provide access to the

     Unix Pipe C functions.

   PUBLIC FUNCTION(S)

     popen    - Open the Pipe command

     get_line - Get a line of Text from a Pipe

     put_line - Put a line of Text into a Pipe

     pclose   - Close the Pipe

     is_open  - Determine whether the Pipe descriptor is open.

   NOTES

     In Order to use these routines you could write  the following

     PL/SQL Code:

        -- Example of Calls to ora_pipe_io functions

        DECLARE

            stream ora_pipe_io.PIPE;

            buffer VARCHAR2(240);

        BEGIN

            stream := ora_pipe_io.popen('ls -l', ora_pipe_io.READ_MODE);

            loop

                exit when not ora_pipe_io.get_line(stream, buffer, 240);

                :directory.file := buffer;

                down;

            end loop;

            ora_pipe_io.pclose(stream);

        END;

   MODIFIED   (MM/DD/YY)

    smclark    08/05/94 -  Creation

*/

PACKAGE ora_pipe_io is

    /*

    ** Arguments to popen.

    */

    READ_MODE constant VARCHAR2(1) := 'r';

    WRITE_MODE constant VARCHAR2(1) := 'w';

    /* ------------- TYPE PIPE ----------- */

    /*

    ** Public Type PIPE - Handle to a Un*x pipe

    **

    ** Do not modify the private members of this type

    */

    TYPE PIPE is RECORD

        (file_handle ORA_FFI.POINTERTYPE,

         is_open boolean,

         read_write_mode VARCHAR2(1));

    /* ------------ FUNCTION POPEN ----------- */

    /*

    ** Function POPEN -- Open a Un*x pipe command

    **

    ** Given a Unix command to execute and a Pipe read/write mode in which

    ** to execute the instruction this Function will execute the Command

    ** and return a handle, of type PIPE, to the resulting Input/Output

    ** stream.

    **

    ** The command to be executed is limited to 1024 characters.

    */

    FUNCTION popen(command in VARCHAR2,

                   ctype in VARCHAR2)

    RETURN PIPE;

    /* ------------ PROCEDURE PCLOSE ----------- */

    /*

    ** Procedure PCLOSE -- Close a pipe

    **

    ** Close a previously opened pipe.

    **

    ** Raises a VALUE_ERROR exception if incorrect arguments are passed.

    */

    PROCEDURE pclose(stream in out PIPE);

    /* ------------ FUNCTION GET_LINE ----------- */

    /*

    ** Function GET_LINE

    ** -- Get a line of text into a buffer from the read mode pipe.

    **

    ** Get a line of text from a previously opened pipe.

    **

    ** Raises a VALUE_ERROR exception if incorrect arguments are passed.

    ** For example

    ** if you pass a pipe which has never been opened (using popen)

    */

    FUNCTION get_line(stream in out PIPE,

                      s in out VARCHAR2,

                      n in PLS_INTEGER)

    RETURN BOOLEAN;

    /* ------------ PROCEDURE PUT_LINE ----------- */

    /*

    ** Procedure PUT_LINE -- Put a line of text into a a write mode pipe.

    **

    ** Put a line of text into a previously opened pipe.

    **

    ** Raises a VALUE_ERROR exception if incorrect arguments are passed.

    ** For example

    ** if you pass a pipe which has never been opened (using popen)

    **

    ** The Internal buffer for the string to write is limited to 2048 bytes

    */

    PROCEDURE put_line(stream in out PIPE,

                       s in VARCHAR2);

    /* ------------ FUNCTION IS_OPEN ----------- */

    /*

    ** Function IS_OPEN -- Determines whether a pipe is open.

    **

    ** Returns TRUE if the pipe is open, FALSE if the pipe is closed.

    */

    FUNCTION is_open(stream in PIPE)

    RETURN BOOLEAN;

END;

/*    ora_pipe_io_body.sql - Body of Package for access to Unix Pipe mechanism

   DESCRIPTION

     Demonstration of how to use the ORA_FFI Package to provide access to the

     Unix Pipe C functions.

   PUBLIC FUNCTION(S)

     popen    - Open the Pipe command

     get_line - Get a line of Text from a Pipe

     put_line - Put a line of Text into a Pipe

     pclose   - Close the Pipe

     is_open  - Determine whether the Pipe descriptor is open.

   PRIVATE FUNCTION(S)

     icd_popen, icd_fgets, icd_fputs, icd_pclose

   NOTES

   MODIFIED   (MM/DD/YY)

    smclark    11/02/94 -  Modified for production release changes to ORA_FFI.

    smclark    08/05/94 -  Creation

*/

 PACKAGE BODY ora_pipe_io is

    lh_libc   ora_ffi.libHandleType;

    fh_popen  ora_ffi.funcHandleType;

    fh_pclose ora_ffi.funcHandleType;

    fh_fgets  ora_ffi.funcHandleType;

    fh_fputs  ora_ffi.funcHandleType;

    /* ------------ FUNCTION ICD_POPEN ----------- */

    /*

    ** Function ICD_POPEN -- Interface routine to C function popen

    **

    ** This function acts as the interface to the popen function in

    ** libc.

    */

    FUNCTION icd_popen(funcHandle in ora_ffi.funcHandleType,

                       command in out VARCHAR2,

                       ctype in out VARCHAR2)

    return ORA_FFI.POINTERTYPE;

    pragma interface(c, icd_popen, 11265);

    /* ------------ PROCEDURE ICD_PCLOSE ----------- */

    /*

    ** Function ICD_PCLOSE -- Interface routine to C function pclose

    **

    ** This function acts as the interface to the pclose function in

    ** libc.

    */

    PROCEDURE icd_pclose(funcHandle in ora_ffi.funcHandleType,

                         stream in out ORA_FFI.POINTERTYPE);

    pragma interface(c, icd_pclose, 11265);

    /* ------------ FUNCTION ICD_FGETS ----------- */

    /*

    ** Function ICD_FGETS -- Interface routine to C function fgets

    **

    ** This function acts as the interface to the fgets function in

    ** libc.

    */

    FUNCTION icd_fgets(funcHandle in ora_ffi.funcHandleType,

                       s in out VARCHAR2, n in PLS_INTEGER,

                       stream in out ORA_FFI.POINTERTYPE)

    RETURN ORA_FFI.POINTERTYPE;

    pragma interface(c, icd_fgets, 11265);

    /* ------------ FUNCTION ICD_FPUTS ----------- */

    /*

    ** Function ICD_FPUTS -- Interface routine to C function fputs

    **

    ** This function acts as the interface to the fputs function in

    ** libc.

    */

    PROCEDURE icd_fputs(funcHandle in ora_ffi.funcHandleType,

                        s in out VARCHAR2,

                        stream in out ORA_FFI.POINTERTYPE);

    pragma interface(c, icd_fputs, 11265);

    /* ------------ FUNCTION POPEN ----------- */

    /*

    ** Function POPEN -- Open a Un*x pipe command

    */

    FUNCTION popen(command in VARCHAR2,

                   ctype in VARCHAR2)

    RETURN PIPE is

        /*

        ** Take a copy of the arguments because we need to pass them

        ** IN OUT to icd_popen, but we really don't want people to have

        ** to call our routines in the same way.

        */

        cmd varchar2(1024) := command;

        cmode varchar2(1) := ctype;

        stream PIPE;

    BEGIN

        if (cmode not in (READ_MODE, WRITE_MODE))

           or (cmode is NULL)

           or (cmd is NULL)

        then

            raise VALUE_ERROR;

        end if;

        stream.file_handle := icd_popen(fh_popen, cmd, cmode);

        stream.is_open := TRUE;

        stream.read_write_mode := ctype;

        return(stream);

    END popen;

    /* ------------ PROCEDURE PCLOSE ----------- */

    /*

    ** Procedure PCLOSE -- Close a pipe

    */

    PROCEDURE pclose(stream in out PIPE) is

    BEGIN

        icd_pclose(fh_pclose, stream.file_handle);

        stream.is_open := FALSE;

    END pclose;

    /* ------------ FUNCTION GET_LINE ----------- */

    /*

    ** Function GET_LINE -- Get a line of text into a buffer

    ** from the read mode pipe.

    */

    FUNCTION get_line(stream in out PIPE,

                      s in out VARCHAR2, n in PLS_INTEGER)

    RETURN BOOLEAN is

        buffer ORA_FFI.POINTERTYPE;

    BEGIN

        if (n <= 0)

           or (stream.is_open = FALSE)

           or (stream.is_open is NULL)

           or (stream.read_write_mode <> READ_MODE)

        then

            raise VALUE_ERROR;

        end if;

        /*

        ** Initialise the Buffer area to reserve the correct amount of space.

        */

        s := rpad(' ', n);

        buffer := icd_fgets(fh_fgets, s, n, stream.file_handle);

        /*

        ** Determine whether a NULL pointer was returned.

        */

        return (ora_ffi.is_null_ptr(buffer) = FALSE);

    END get_line;

    /* ------------ PROCEDURE PUT_LINE ----------- */

    /*

    ** Procedure PUT_LINE -- Put a line of text into a a write mode pipe.

    */

    PROCEDURE put_line(stream in out PIPE,

                       s in VARCHAR2) is

        buffer varchar2(2048) := s;

    BEGIN

        if (stream.is_open = FALSE)

           or (stream.is_open is NULL)

           or (stream.read_write_mode <> WRITE_MODE)

        then

            raise VALUE_ERROR;

        end if;

        icd_fputs(fh_fputs, buffer, stream.file_handle);

        buffer := chr(10);

        icd_fputs(fh_fputs, buffer, stream.file_handle);

    END put_line;

    /* ------------ FUNCTION IS_OPEN ----------- */

    /*

    ** Function IS_OPEN -- Determines whether a pipe is open.

    */

    FUNCTION is_open(stream in PIPE)

    RETURN BOOLEAN is

    BEGIN

        return(stream.is_open);

    END is_open;

BEGIN

    /*

    ** Declare a library handle as libc.  (Internal so NULL,NULL)

    */

    lh_libc := ora_ffi.load_library(NULL, NULL);

    if ora_ffi.is_null_ptr(lh_libc) then

        raise VALUE_ERROR;

    end if;

    /*

    ** Register the popen function, it's return type and arguments.

    */

    fh_popen := ora_ffi.register_function(lh_libc, 'popen');

    if ora_ffi.is_null_ptr(fh_popen) then

        raise VALUE_ERROR;

    end if;

    ora_ffi.register_return(fh_popen, ORA_FFI.C_DVOID_PTR);

    ora_ffi.register_parameter(fh_popen, ORA_FFI.C_CHAR_PTR);

    ora_ffi.register_parameter(fh_popen, ORA_FFI.C_CHAR_PTR);

    /*

    ** Register the pclose function, it's return type and arguments.

    */

    fh_pclose := ora_ffi.register_function(lh_libc, 'pclose');

    if ora_ffi.is_null_ptr(fh_pclose) then

        raise VALUE_ERROR;

    end if;

    ora_ffi.register_return(fh_pclose, ORA_FFI.C_VOID);

    ora_ffi.register_parameter(fh_pclose, ORA_FFI.C_DVOID_PTR);

    /*

    ** Register the fgets function, it's return type and arguments.

    */

    fh_fgets := ora_ffi.register_function(lh_libc, 'fgets');

    if ora_ffi.is_null_ptr(fh_fgets) then

        raise VALUE_ERROR;

    end if;

    ora_ffi.register_return(fh_fgets, ORA_FFI.C_DVOID_PTR);

    ora_ffi.register_parameter(fh_fgets, ORA_FFI.C_CHAR_PTR);

    ora_ffi.register_parameter(fh_fgets, ORA_FFI.C_INT);

    ora_ffi.register_parameter(fh_fgets, ORA_FFI.C_DVOID_PTR);

    /*

    ** Register the fputs function, it's return type and arguments.

    */

    fh_fputs := ora_ffi.register_function(lh_libc, 'fputs');

    if ora_ffi.is_null_ptr(fh_fputs) then

        raise VALUE_ERROR;

    end if;

    ora_ffi.register_return(fh_fputs, ORA_FFI.C_VOID);

    ora_ffi.register_parameter(fh_fputs, ORA_FFI.C_CHAR_PTR);

    ora_ffi.register_parameter(fh_fputs, ORA_FFI.C_DVOID_PTR);

END ora_pipe_io;


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.


About Form Builder resource files

  Related Topics

Resources are collections of related data. An application built with Oracle Terminal support includes resources that describe its behavior and appearance. Specifically, Form Builder resource files define design time and runtime logical attributes and key bindings for Form Builder.

Using Oracle Terminal to edit the Form Builder resource file for your platform, you can:

•	associate a key sequence with an application function by defining a key binding

•	associate a key sequence with a Form Builder key trigger by defining a key binding

•	modify the visual appearance (face, pattern, color, etc.) of a Form Builder-specific element

Note:  Resource file names are platform-specific. On Microsoft Windows, the look and feel of a Form Builder application is defined by the resource file, FMRUSW.RES.


About using Oracle Terminal to re-map Form Builder key mappings

  Related Topics

Resource files associate application functions with specific keys, using what are known as key bindings.

A key binding connects a key to an application function. When you bind a key to a function, the program performs that function when you type that keystroke.

By defining key bindings, you can integrate a variety of keyboards to make an application feel similar on each of them.

In some instances, you may want to define your own key mapping for a specific Form Builder function. For example, on Microsoft Windows, the default key mapping for [Show Keys] is Control+F1. Using Oracle Terminal, you could re-map the [Show Keys] function to Control+F2 or to some other desired key mapping.

When you create a Key-Fn or Key-Other Triggers, you must use Oracle Terminal to associate a key with your Key-Fn or Key-Other function. Creating a key binding for your trigger allows it to fire when the operator presses the key sequence associated with your trigger.

The key bindings that you create using Oracle Terminal automatically appear in the Show Keys window when the operator invokes the Show Keys function.

Note:  Key bindings must be unique.  When you define a key binding, verify it against each bind category to ensure uniqueness.

In addition, there are functions which have multiple key bindings.

For example, [Accept] is mapped to both F10 and the Return key, depending on the context. As a result, in order to consistently bind a sequence of keys with a function, you must modify the key binding for each instance.

On some platforms not all keys are able to be re-mapped. For example, on Microsoft Windows, because keys are defined in the Windows keyboard device driver, certain keys cannot be re-mapped by Oracle Terminal. Key combinations integral to Windows, such as Alt-F4 (Close Window) and F1 (Help) cannot be re-mapped. As a general rule, keys which are part of the “extended” keyboard also cannot be re-mapped. These keys include the number pad, gray arrow and editing keys, Print Screen, Scroll Lock, and Pause.

Oracle supports remapping only those keys from F0 to F9.


Remapping a Form Builder key binding
Re-mapping a Form Builder key binding

  Related Topics

To re-map a Form Builder key binding:

1	Start Oracle Terminal.

2	Open the appropriate Form Builder resource file (on Microsoft Windows, open FMRUSW.RES).

Note: Before modifying a Form Builder resource file, you should create a backup copy.

3	Choose Functions [image] Edit Keys.

The Key Binding Editor appears and lists Form Builder key bindings by category.

4	Double-click on a category and modify the desired "Action" and "Binding."

For example, to modify the key mapping for [Show Keys], double-click on "windows-sqlforms," specify the desired key binding for Show Keys, then click OK.

5	Choose File [image] Save to save your modifications.

6	Choose Functions [image] Generate to generate your modifications and to create a new resource file, which incorporates the changes you made to the key binding.

An alert appears, informing you that your resource file has been successfully generated. Accept the alert.

7	Choose File [image] Save to save your changes to the new resource file.

8	Run Form Builder to use your new key binding.


Creating a key binding for a key trigger

  Related Topics

To create a key binding for a key trigger:

1	In Form Builder, create your Key-Fn or Key-Other trigger.

2	Using Oracle Terminal, open the appropriate Form Builder resource file (on Microsoft Windows, open FMRUSW.RES).

3	Choose Functions [image] Edit Keys to invoke the Key Binding Editor.

4	In the Key Binding Editor, double-click on windows-sqlforms to invoke the Key Binding Definition window.

5	Click on the Insert Row button and then enter the action that corresponds to your Key-Fn or Key-Other trigger. (The chart below applies only to Microsoft Windows.)

Key-Fn Trigger	MicrosoftW Action	MicrosoftW Code
KEY-F0	User Defined Key 0	82
KEY-F1	User Defined Key 1	83
KEY-F2	User Defined Key 2	84
KEY-F3	User Defined Key 3	85
KEY-F4	User Defined Key 4	86
KEY-F5	User Defined Key 5	87
KEY-F6	User Defined Key 6	88
KEY-F7	User Defined Key 7	89
KEY-F8	User Defined Key 8	90
KEY-F9	User Defined Key 9	91
For example, if you created a KEY-F3 trigger, enter:

 User Defined Key 3

into the Action field.

6	Specify a key binding for your Key-Fn trigger, then click OK.

For example, you could enter:

Action	Binding
User Defined Key 3	Control+F2
7	Click Product Actions to invoke the Product Actions Editor.

8	Double-click on the sqlforms category.

9	Click on the Insert Row button, enter the Action, Code, and Description for your Key-Fn trigger, then click OK.

For example, if you create a KEY-F3 trigger that invokes a help system, enter the following on Microsoft Windows:

Action	Code	Description
User Defined Key 3	85	[Help System]
10	Dismiss the Product Action and Key Binding Editors by clicking on OK for each, then choose File [image] Save.

11	Choose Functions [image] Generate  to generate your modifications and to create a new resource file, which incorporates the additions you made.

12	Choose File [image] Save to save your changes to the new resource file.

13	(Optional)  Within Form Builder, set the Keyboard Help Description property for your key trigger to True if you want the key binding for your trigger to appear in the Show Keys window.


About using Oracle Terminal to modify Form Builder logical attributes

  Related Topics

In addition to setting default and named visual attributes in Form Builder, you can also modify the look (logical attributes) of a Form Builder application by modifying Form Builder resource files.

Form Builder logical attributes are organized into two groups: character-mode (cm_logicals) and GUI (forms_logicals).

Note:  Because of the limited number of GUI logical attributes that can be defined using Oracle Terminal, you should use Form Builder to create named visual attributes for the desired GUI elements rather than using Oracle Terminal to modify a Form Builder resource file.

About Attribute Precedence

When you edit Form Builder resource files, you specify font and color attributes for character-mode or GUI logical attributes, such as field-current, field-non-current, pushbuttoncurrent, field-queryable, etc.

In addition to modifying Form Builder resource files, there are several other methods for setting display attributes for Form Builder objects. You can:

•	accept Form Builder default attributes

•	define custom visual attributes

•	define logical attributes using Oracle Terminal

•	define display attributes using your window manager

In many cases, depending on the method chosen, you can create an attribute that overrides an attribute defined at a higher level.

When defining object attributes, consider the following rules regarding attribute precedence:

1	Window manager (lowest level)

Window manager definitions take precedence over Oracle Terminal definitions, visual attributes defined in Form Builder, local environment variable definitions (registry, CONFIG.ORA, etc.), and default Form Builder attributes.

For example, on Microsoft Windows, color attributes for buttons are handled exclusively by Windows. Any color attributes that you create and apply to buttons in Form Builder have no effect on buttons.

To change the color attributes of a button in a Microsoft Windows environment, use the MicrosoftW Control Panel facility.

2	Oracle Terminal definitions

Oracle Terminal definitions take precedence over visual attributes defined in Form Builder, local environment variable definitions, and default Form Builder attributes.

For example, assume that you create a custom visual attribute for the text items in your form so that text items appear gray. Assume also that you use Oracle Terminal to define all queryable items as cyan. When you run your form, all text items appear gray, but when you invoke Enter Query mode, text items appear cyan.

In this example, the Oracle Terminal definition takes precedence and overrides the higher level attribute (the custom visual attribute created at design time).

3	Visual attributes created within Form Builder

Form Builder-created visual attributes take precedence over local environment variable definitions (registry, CONFIG.ORA, etc.) and default Form Builder attributes.

For example, assume that you create and apply a named visual attribute to the text items in your form. Assume also that you define the FORMS60_DEFAULTFONT local environment variable in the registry (or in CONFIG.INI) so that item labels are displayed with 10 point Courier.

At runtime, your named visual attribute takes precedence, and Form Builder displays all text items according to the properties defined by your named visual attribute.

4	Local environment variable definitions

Local environment variable definitions (registry, CONFIG.ORA, etc.) take precedence over default Form Builder attributes.

For example, if you edit your registry file and define the default font (FORMS60_DEFAULTFONT) as 10 point Courier,  Form Builder displays item labels as 10 point Courier.

In this example, the default font in the registry takes precedence and overrides the default font attributes for items.

5	Form Builder default attributes (highest level)

Form Builder applies default attributes to every object. At runtime, Form Builder looks up the specific color, pattern, and font characteristics for a particular object and then displays it with its default attributes.


Modifying Form Builder logical attributes

  Related Topics

To modify a Form Builder logical attribute:

1	Start Oracle Terminal.

2	Using Oracle Terminal, open the appropriate Form Builder resource file (on Microsoft Windows, open FMRUSW.RES).

3	Choose Functions [image] Edit Attributes.

4	Select cm_logicals or form_logicals from the Attribute List drop-down list.


About edit attribute node options

The Edit Attribute Node window offers the following options to define the font and color elements of a logical attribute.

Font Attributes

Font Attributes include:

•	Face

•	Size

•	Style

•	Weight

•	Width

At runtime, Form Builder passes these settings to the window manager. If the font that you specify is unavailable in the runtime operating system, Form Builder uses the font that most nearly matches the characteristics of the font specified.

Color and Fill Pattern Atributes

You can set the following color and pattern attributes in a custom or named visual attribute definition:

Foreground and Background Color  Color is applied to objects in a foreground layer and a background layer. You specify the color of each layer by setting the Foreground Color and Background Color attributes.

Pattern  You can set the Pattern attribute to any of the predefined patterns available on your system. Patterns are identified by name. For example, the pattern named thinline45 is a pattern of thin, diagonal lines on a solid background.

How Fill Pattern Affects Color Attributes

Form Builder renders the selected pattern in the foreground and background colors applied to an object, as shown in the Fill Pattern Palette after you select foreground and background colors.

•	When the current pattern is Solid (the black square in the pattern palette), the object displays in the color specified by the Foreground Color attribute.

•	When the current pattern is Transparent (the white square in the Layout Editor pattern palette), the object displays in the color specified by the Background Color attribute.

•	When the current pattern is None, the object is transparent, and neither the foreground color or background color is applied (whatever is behind the object shows through).

Note:  The None pattern cannot be selected in the Fill Pattern Palette, only types in the Property Palette, and is not valid for items. For best results, use the Transparent pattern for items (the solid white square in the Layout Editor pattern palette).


About Form Builder character mode logical attributes
About Form Builder character-mode logical attributes

Use Oracle Terminal to change the defaults for Form Builder-specific visual attributes for character-mode terminals, which are listed below.

Attribute Name	Context Where Attribute Is Used
ToolkitDisabled	Generic attribute
ToolkitEnabled	Generic attribute
ToolkitCurrent	Generic attribute
ToolkitDisabledMnemonic	Generic attribute
ToolkitEnabledMnemonic	Generic attribute
ToolkitCurrentMnemonic	Generic attribute
NormalAttribute	Normal background for windows
Normal	Text item
Bold	Bold for all items (including check boxes)
Bold-text	Boilerplate
Bold-inverse	Inverse bold for all items
Underline	Underline for all items
Boilerplate	Constant text
WindowTitleCurrent	Title of active window
Menu	Selected menu
Sub-menu	Selected submenu
Full-screen-title	Screen title
Menu-title	Current menu title
Menu-subtitle	Current menu subtitle
Menu-bottom-title	Current title at bottom of menu
MenuItemEnable	Enabled, non-current menu item
MenuItemDisabled	Disabled menu item
MenuItemSelect	Current menu item
MenuItemEnableMnemonic	Mnemonic of an enabled menu item
MenuItemDisableMnemonic	Mnemonic of a disabled menu item
MenuItemSelectMnemonic	Mnemonic of the current menu item
TextControlCurrent	Current field or text editor
Field-current	Color for current text item
TextControlNonCurrent	Disabled or non-current field or text editor
Field-non-current	Color for text item that is not currently selected
TextControlSelect	Selected text in an enabled field or text editor
Field-selected-current	Currently selected text item
Field-selected-non-current	Text item that is not currently selected
Field-queryable	Field that operator can query
PushButtonDefault	Default or current button
PushButtonNonDefault	Button that is not default
Button-non-current	Non-current button
Button-current	Current button
Alert	Alert text
AlertIcon	Icon in an alert window
AlertMessage	Message text in an alert window
AlertBackground	Alert background
Listtitle	List of Values (LOV) title
ListItemSelect	Selected item in a text list
ListItemNonSelect	Unselected item in a text list
ListPrefix	List prefix
ScrollThumb	"Elevator box" on scroll bar


About Form Builder GUI logical attributes

Use Oracle Terminal to change the GUI defaults for Form Builder-specific visual attributes, which are listed below.

Attribute Name	Context Where Attribute Is Used
TextControlFailValidation	Text item that fails validation
ItemQueryDisabled	Text item that is explicitly disabled by the operator, so it cannot be included as query criteria
Status-Message	Message appearing on status bar
Status-Hint	Hint appearing on status bar
Status-Empty	Status bar with no text
Status-Items	Indicators (lamps) on status bar
Scroll-bar-fill, Inverse, Inverse-underline, Bold-underline, Bold-inverse-underline	These logical attributes are not unique to Form Builder. As a result, these logical attributes can be overridden by the visual attributes defined by the window manager.


Defining Parameters


About Form Parameters

Parameters provide a simple mechanism for defining and setting the values of inputs that are required by a form at startup.  Form parameters are variables of type CHAR, NUMBER, or DATE that you define at design time.

You can pass parameter values to a form when an application executes the CALL_FORM, NEW_FORM, OPEN_FORM, or RUN_PRODUCT built-in subprograms.

Operators can specify values for form parameters at form startup by entering them on the command line, using standard command line syntax.

A parameter value entered on the command line overrides the default value that was specified for the parameter at design time.

In the following example, MODULE, USERID, and DEBUG are pre-defined command line parameters; CITY is a user-defined form parameter that was defined in the trade form at design time:

ifrun60 MODULE=trade USERID=scott/tiger debug=YES city="BOGOTA"

Note:  A parameter must have been defined at design time before you can specify a value for it at form startup.  That is, the form must be expecting the parameter value it receives at startup, either through the command line or by way of a parameter list.  If you attempt to pass a value for a parameter that does not exist in the form, an error occurs.

The following sections explain how to create parameters in a form at design time, how to set and reference parameter values programmatically, and how to create parameter lists to pass parameter values to called forms at runtime.


Creating a Parameter

  Related Topics

When you create a parameter, you specify its name, datatype, length, and default value.

To create a parameter:

1	In the Object Navigator, create a parameter.

To create a parameter, select the Parameters node in the Object Navigator and then choose Navigator [image] Create.

2	In the Property Palette, set the desired parameter properties:

Parameter Data Type	Set to CHAR, NUMBER, or DATE.
Parameter Initial Value	The default value of the parameter.  Must be compatible with the parameter data type and length.
Length	The maximum number of characters the parameter can store.  Length is only valid for CHAR parameters, which can be up to 64K.  NUMBER parameters default to 23 bytes and DATE parameters default to 7 bytes.
Name	The internal name of the parameter.


Referencing Parameters

In PL/SQL, you can reference and set the values of form parameters using bind variable syntax.

To reference a parameter:

Preface the parameter name with the reserved word PARAMETER, as shown in the following examples:

:PARAMETER.parameter_name := 'TOKYO';

Or

:block.item := :PARAMETER.parameter_name;


About indirectly referencing parameters

  Related Topics

You cannot use bind variable syntax to refer directly to a parameter in a trigger, user-named routine, menu command, or stored procedure that is not declared in the same module as the parameter itself.

To indirectly reference a parameter:

Use the NAME_IN and COPY built-ins to indirectly set and reference the parameter's value:

Name_In('PARAMETER.my_param')
Copy('SAN JUAN', 'PARAMETER.my_param')

Note:  When you reference parameters indirectly, the parameter names are enclosed in single quotes, but are not preceded with a colon.


About referencing parameters when you set object properties

You can reference form parameters in the following object properties:

•	WHERE and ORDER BY clauses for a data block (specified in the Property Palette when you select the desired block in the Object Navigator or programmatically by way of SET_BLOCK_PROPERTY)

•	Return Item property for a list of values (specified in the LOV Column Mapping dialog)

•	Initial Value property for an item (specified in the Property Palette when you select the desired item in the Object Navigator)

•	Lowest Allowed Value and Highest Allowed Value properties for a text item (specified in the Property Palette when you select the desired text item)


Creating and Passing Parameter Lists

Parameters are passed to called forms by means of a parameter list.  A parameter list is a named programmatic construct that is simply a list of parameter names (called keys) and their values.

You can pass parameter values to forms invoked by the built-in subprograms CALL_FORM, OPEN_FORM, and NEW_FORM.  In addition, you can pass parameter values to other Oracle tools with the RUN_PRODUCT procedure.

A parameter you include in a parameter list can be either a text parameter or a data parameter.  The parameter type determines how its value is interpreted.

Text Parameters	The value of a text parameter being passed to a called product is a CHAR string that can represent the following:

•	a user-defined form parameter defined in a form invoked by the CALL_FORM, OPEN_FORM, or NEW_FORM built-in subprograms

•	a command line or user-defined parameter for a product invoked with the RUN_PRODUCT built-in subprogram

Data Parameters	The value of a data parameter being passed to a called product is always the name of a record group defined in the current form.  (A record group is a data structure that stores records derived from a query or through programmatic assignment.) Data parameters are used to pass data to products invoked with the RUN_PRODUCT built-in subprogram.  You cannot pass data parameters to forms.

The following table shows the structure of a parameter list that contains four parameters:

Key	Paramtype	Value
CITY	Text_Parameter	'BOGOTA'
CATEGORY	Text_Parameter	'EXPORTS'
MULTIPLIER	Text_Parameter	'.0275'
NEW_DATA	Data_Parameter	'RECORD_GROUP8'


Creating a Parameter List

You can use the following built-in subprograms to create and manipulate a parameter list:

•	ADD_PARAMETER

•	CREATE_PARAMETER_LIST

•	DELETE_PARAMETER

•	DESTROY_PARAMETER_LIST

•	GET_PARAMETER_ATTR

•	GET_PARAMETER_LIST

•	SET_PARAMETER_ATTR

Tip:  Keep in mind the following when you create parameter lists:

•	CREATE_PARAMETER_LIST is a function whose return value is the ID of the list being created.  You must assign the ID to a variable that you declared as type PARAMLIST (an Form Builder data type).

•	A call to CREATE_PARAMETER_LIST creates a parameter list that does not yet contain any parameters.  To add parameters to the list, execute the ADD_PARAMETER procedure.

•	GET_PARAMETER_ATTR and SET_PARAMETER_ATTR can be used to get and set the type and value of a parameter that has been added to a parameter list with the ADD_PARAMETER built-in.  Do not use these built-ins to get or set the value of a form parameter that was defined at design time; instead, refer to the parameter using bind variable syntax or indirect reference.

•	GET_PARAMETER_LIST is a function that returns the ParamList ID of an indicated parameter list, similar to the FIND-* functions available for other object types.

The following example creates a parameter list, adds two parameters to it, and then passes the list to a form by way of the CALL_FORM procedure:

/*
** Declare a variable of type ParamList to store
** the parameter list ID
*/
DECLARE
   list_id   ParamList;
BEGIN
/*
** Create a parameter list named "input_params"
*/
   list_id := Create_Parameter_List('input_params');

/*
** Add two parameters to the list to pass values for each
** user-defined parameters defined in the target form; for each
** parameter, specify its key, type (text or data), and value
*/
   Add_Parameter(list_id, 'CITY',TEXT_PARAMETER,'BOGOTA');
   Add_Parameter(list_id, 'CATEGORY',TEXT_PARAMETER,'EXPORTS');

/*
** Now call the form, referencing the parameter list ID
** in the last argument to the CALL_FORM procedure
*/
   Open_Form('trade',ACTIVATE,NO_SESSION,list_id);
END;

The Default Parameter List

Each form includes a built-in parameter list named Default.  The Default parameter list contains all of the form parameters that were defined in the form at design time.  For example, if you define parameters p1, p2, and p3 in Form A at design time, they  are automatically included in the Default parameter list for Form A.

The Default parameter list can be passed to a called form by including it in the argument list of the OPEN_FORM, CALL_FORM, or NEW_FORM built-in procedures.

DECLARE
    the_list PARAMLIST:= Get_Parameter_List('default');
BEGIN
    Open_Form('form_B',ACTIVATE, NO_SESSION,'default');
END;


Passing a Parameter List

To pass one or more parameters to a called form, the calling form must perform the following steps in a trigger or user-named routine:

•	execute the CREATE_PARAMETER_LIST  built-in subprogram to programmatically create a parameter list

•	execute the ADD_PARAMETER  built-in subprogram to add one or more parameters to the parameter list

•	execute the DELETE_PARAMETER  built-in subprogram to delete one or more parameters in the parameter list

•	execute the CALL_FORM, NEW_FORM, OPEN_FORM, or RUN_PRODUCT built-in subprogram and include the name or ID of the parameter list to be passed to the called form


Specifying Parameter Attributes

  Related Topics

When you use ADD_PARAMETER to add a parameter to a parameter list, you must specify three parameter attributes:

Key	The name of the parameter.

Paramtype	The parameter type, either DATA_PARAMETER or TEXT_PARAMETER.

Value	The parameter value.  For a TEXT_PARAMETER, the value is any CHAR value.  For a DATA_PARAMETER, the value is always the CHAR name of a record group defined in the current form.


About PECS

As a Form Builder developer or a system administrator, you may have questions about the performance of both Form Builder and your own applications. Form Builder' Performance Event Collection Services (PECS) will help you answer questions such as these:

•	How much elapsed time does it take to use LOVs on three fields in my form?

•	How long does it take to execute these triggers?

•	How many invoices per hour can we produce?

•	Have I tested all the triggers in my form?

•	Have I tested all the lines of my PL/SQL code?

The PECS System

The PECS system consists of three main parts:

•	PECS built-ins, used to define application-specific events

•	PECS Assistant, an Form Builder application you can use to load and view PECS data

•	PECS reports, which let you view the results of your tests on line or print out hard copy

PECS Measurements

PECS is a low-overhead performance measurement tool you can use to perform the following tasks:

•	Measure resource usage for Form Builder events

The simplest way to use PECS is to measure only Form Builder events.  If you only want to measure Form Builder events, you do not need to add PECS built-ins to your PL/SQL code because Form Builder includes pre-defined PECS events to measure the performance of objects such as triggers, windows, canvases, LOVs, and alerts.

•	Measure resource usage for application-specific events (CPU time and elapsed time)

If you add calls to PECS built-ins to your PL/SQL code, you can measure the performance of application-specific events, as well as Form Builder events.

•	Locate performance problems

•	Measure coverage

When you're testing an Form Builder application, you may be interested in what kind of coverage your test cases provide.  The PECS Object Coverage Report gives you information about the coverage provided by your current test suite.

The PECS Line Coverage Report provides information about coverage of PL/SQL code.


Collecting performance data on Form Builder events

Because Form Builder includes pre-defined PECS events, you can measure both performance and coverage without making any changes in your application.  PECS measures:

•	The performance of the entire application,  triggers, and LOVs

•	The coverage of procedures, windows, canvases, editors, and alerts, and line-by-line coverage for PL/SQL code

The process has three steps:

1	Run your application with PECS on to collect performance data in a .DAT file, using the following command:

ifrun60 module=myform userid=scott/tiger pecs=on

Or, at the Runform Preferences dialog "Collect PECS data?" option, select ON.

Running Form Builder with PECS creates a PECS binary file with a default name of the module name with a .DAT extension:

myform.dat

The data is written to a file rather than directly to the database.

2	Load data from the .DAT file and your form into the database.

Use the PECS Assistant to load both your form and the PECS binary (.DAT) file into the database.

For information about the PECS Assistant, see "Using the PECS Assistant" later in this chapter.

3	Analyze the data.

Once the PECS database file is created, review the results:

•	Use the PECS Assistant Data or Summary windows to view the results on line, or

•	Run the Performance, Object Coverage, or Line Coverage Reports and view the results on line or print out hard copy

Although you don't need to use the PECS built-ins to collect performance data on Form Builder events, you can use the built-ins to  limit the focus of your PECS experiments.  For example, if you are only  interested in LOV events, you can use the PECS.DISABLE_CLASS built-in to turn off all events except the LOV events.


About collecting performance data on application-specific events

 Examples

To use PECS to measure application-specific events, first define the events you want to measure by adding PECS built-ins to your PL/SQL code.  (For best results, define only a few most important events.)

Using PECS to collect performance data on application-specific events is a five-stage process:

•	Group application-specific events.

•	Define the events you want to measure, using PECS built-ins.

•	Run your application with PECS.

•	Load the form and the PECS data from the file into the database.

•	Analyze the data.

Group Application-Specific Events

Application-specific events are the business transactions that you define:  for example, in a banking application, you might define Deposit, Withdrawal, and Transfer events.

You can group like events into classes in order to create reports that display your test results meaningfully.  In a banking application, you might create two classes:

•	A Banking class, composed of three events:

•	Deposit event

•	Withdraw event

•	Transfer event

•	A Customer class, composed of three events:

•	AddCustomer event

•	DeleteCustomer event

•	ChangeCustomer event

Define PECS Events

Once you've chosen the set of events you want to measure, you'll prepare your application to use PECS by adding PECS built-ins to your PL/SQL code:

•	Start PECS:

•	At design time, by adding the PECS.COLLECTOR built-in to your application (to collect data on  application-specific events only), or

•	At runtime, by invoking PECS from the command line (to collect data on Form Builder events, as well as on application-specific events)

•	Add any classes and events you need with the PECS.ADD_CLASS and PECS.ADD_EVENT built-ins

•	Enable the class or specific event you want to measure using the PECS.ENABLE_CLASS built-in

•	Define the events you want to measure:

•	Bracket them with the PECS.START_EVENT and PECS.END_EVENT built-ins, or

•	Mark them with PECS.POINT_EVENT

To invoke PECS from the command line, set PECS=ON for object coverage and PECS=FULL for object and line coverage.

Note:  You can use PECS built-ins wherever you can use other Form Builder built-ins:  triggers, user-named routines, menu PL/SQL commands, and stored procedures.  While you can't directly measure the duration of a PL/SQL procedure, you can define a trigger that calls the procedure and then measure the duration of that trigger.

Run Application with PECS

Once you have added PECS built-ins to your application, when you run the form PECS automatically creates a binary file containing the test data:

•	If you started PECS from the command line, the name of the PECS binary file defaults to the form name with a .DAT extension:  myform.dat.

•	If you started PECS by adding the PECS.COLLECTOR built-in to your application,  the name of the PECS binary file defaults to the name of the first class you specified with the PECS.ADD_CLASS built-in:  banking.dat.

Load the Form and the PECS Data into the Database

Use the PECS Assistant application to load both your form and the PECS binary file into the database.  For more information, see "Using the PECS Assistant" later in this chapter.

Note:  Unless you want coverage statistics, PECS does not require that you store your form in the database. However, PECS depends on some of the tables that are created automatically by the Form Builder 5.0 table scripts that are run during installation when you choose the "Create database tables" option.  If you did not choose that option, you or your DBA must logon as SYSTEM and run those SQL scripts, which are  found in the Form Builder SQL directory.

Analyze the Data

Once the PECS .DAT file has been loaded into the database, you can review the results using the PECS Assistant:

•	Use the Data or Summary windows to view the results on line,  or

•	Run the Performance, Object Coverage, or Line Coverage Reports and view the results on line or print out hard copy

Next Step

Once you've analyzed the data,  you may decide to proceed in any of several directions:

•	If you are debugging, you may want to change the application and run the same tests again.

•	If you are testing performance, you may want to create multiple runs of the same test, average the statistics, and compare results with previous tests.

•	If you are testing coverage, you may want to change the test to add test cases to cover more conditions, then re-run the test and compare results with earlier tests.


Collecting performance data on application-specific events examples

Assume that you've decided to measure both internal Form Builder events and three application-specific events: Deposit, Withdrawal, and Transfer.  This example illustrates adding the PECS built-ins to define these events to PECS.

(Because you want to measure both types of events, you could have started PECS on the command line, but this example includes starting PECS with the PECS.COLLECTOR built-in for  purposes of demonstration.)

PACKAGE globals IS
/* We will create a package of global variables instead of     */
/* local variables because the pecs.event and pecs.class types */
/* may be spread across various procedures, triggers, and      */
/* even forms.                                                 */

/*                                                             */
/*   Add the classes.                                          */
/*                                                             */
banking PECS.class  := PECS.Add_Class('Banking');
myform  PECS.class  := PECS.Add_Class(PECS.FORMS);
/*                                                            */
/*   Add the events for the class 'Banking'.                  */
/*   No need to add events for the class 'Form'               */
/*   because they are pre-defined internal events.            */
withdraw pecs.event  := PECS.Add_Event(banking,'Withdraw');
deposit pecs.event   := PECS.Add_Event(banking,'Deposit');
transfer pecs.event  := PECS.Add_Event(banking,'Transfer');

END globals;

/*   Trigger: When-New-Form-Instance                        */
/*   Enable PECS                                            */

BEGIN
PECS.Collector(COLLECT_ON);

/*                                                          */
/*   Enable the classes                                     */
/*                                                          */

PECS.Enable_Class(GLOBALS.banking);
/*                                                          */
/* After the forms class has been enabled,                  */
/* internal forms events will be measured.                  */
/* NOTE: This line is not needed if you use the             */
/*       PECS=on command line option.                      */

PECS.Enable_Class(GLOBALS.myform);
END;

PROCEDURE do_withdraw

/*                                                          */
/*   This is the code that does the Withdraw Event.         */
/*                                                          */

DECLARE
withdraw_handle number;

BEGIN

/*                                                          */
/*   Start the Withdraw event               .               */
/*                                                          */

withdraw_handle := PECS.Start_Event(GLOBALS.withdraw,
'Withdrawing cash');

.
.   /do the withdraw/
.

PECS.End_Event(GLOBALS.withdraw,withdraw_handle);
END;


Collecting object coverage data

When you're testing an Form Builder application, you can  also use PECS as a quality assurance tool. The PECS Object Coverage Report lets you evaluate the percentage of coverage provided by your current set of test cases.

When you run PECS to collect information on Form Builder events, either separately or in conjunction with collecting information on application-specific events, you can run the Object Coverage Report as well as the Performance Report.

By examining the Object Coverage Report, you can see whether your current set of test cases exercises all of the Form Builder objects in your application. For example, you can check whether each trigger, procedure, alert, window, and canvas are visited during execution of your current set of test cases, and find any areas where you may need to construct new test cases for increased coverage.

Note:  If you want coverage statistics, you must store your form in the database.


Collecting line coverage data

In addition to testing for simple coverage of test cases, you can also test for line-by-line coverage of PL/SQL code in triggers and procedures.  The PECS Line Coverage Report lets you evaluate the percentage of PL/SQL line coverage provided by your current set of test cases.

To obtain line coverage data:

•	Compile the form with debug=ON.

•	Run with PECS=FULL.

•	In the PECS Assistant, select the Line Coverage check box.

•	Select the Line Coverage Report.

Note:  To collect line coverage data, you must use the PECS command line option (PECS=FULL)  rather than invoking PECS with the PECS.ENABLE_CLASS built-in.


Using the PECS assistant

 Examples

The PECS Assistant application provides the following functions:

To do this:	Use this window:
Load PECS data into tables	Load
Display data	Data, Summary
Display information about classes and experiments	Class, Experiment
About the PECS Hierarchy

The PECS Assistant asks you to specify names of occurrences, events, classes, runs, and experiments.

These terms are used in the PECS hierarchy as follows:

This group:	Consists of:
Experiment	One or more test runs.  Experiments own runs.
Run	One pass through your application from start to finish.  A single .DAT file maps to a single run of an experiment.
Class	A group of related events.  Classes own events.
Event	An application-specific or form-specific transaction with a defined start and end.
Occurrence	One example of a given event.
Steps for Using the PECS Assistant

Once you've run a form with PECS enabled, you're ready to use the PECS Assistant application:

1	At the system prompt, enter this command to run the PECS Assistant: ifrun60 module=pecs

The PECS Assistant displays the Main window. You can navigate to other windows using the buttons or the commands on the Windows menu.

2	Click Load.

The PECS Assistant displays the Load window.

3	Fill in the "PECS Data" section to select the experiment you want to load into the database.

If the file does not exist, an Open error message is displayed.

Note:  Fill in the "Connect String" section only if you want to use a connect string that differs from the one you used to start the form.  For more information, press Help.

4	Check the appropriate check boxes.

The "Load PECS data in the database" and "Summarize data" check boxes are checked, as default.

If you want to include line coverage data, check the "Prepare for Line Coverage" check box.

Note:  Preparing for line coverage is a time-consuming task, so the "busy" cursor will be displayed for a while.

If you want to delete the detailed data once the summary files are created, check the "Delete details after summary" check box.

5	Click Start.

PECS displays confirmation messages for each check box you've selected.

Once you've accepted each confirmation, PECS processes the data, displaying status messages in the "Status" area during processing, and prepares the results for you to examine.

6	To view the results, choose Navigation [image] Experiment or Navigation [image] Class.

7	From the Experiment or Class window, query to select the experiment or class you want to review.

PECS displays the results of your query.

8	Highlight the specific experiment or class.

9	Click Zoom In.

PECS displays the Summary window, showing the summarized version of the data.  The Summary window displays the information in a format similar to the PECS reports.

10	Click Zoom In again to examine the detailed results of a PECS experiment.

PECS displays the detailed results in the Data window.

PECS Reports

To run the PECS reports, choose the Reports menu:

•	Choose the Performance Report to show elapsed time and CPU time.

•	Choose the Object Coverage Report to show that certain events or occurrences have been reached.

•	Choose the Line Coverage Report to show coverage of your PL/SQL code.

By default, the Performance Report displays data in the sequence of columns as displayed in the Data or Summary screen.  To change the sequence in the report, change the Order By clause in the Data or Summary Performance Report window.

PECS Maintenance

To review data about classes and experiments you defined, return to the Main window and click Class or Exp (Experiment):

•	Use the Class window to view data about the classes and events you defined using the PECS built-ins.

You can perform minimal maintenance on classes using this window.  For instance, you can change class names and add version information.

•	Use the Experiment window to view data about the experiments and runs you defined using PECS built-ins.

You can perform minimal maintenance on experiments using this window.  For instance, you can change experiment names  and add comment information.  (You specified the experiment name earlier, in the Load window or on the command line using the -n option.)

Using .DAT files

PECS allows you to load multiple previously-created .DAT files in order to re-run experiments or to average the performance statistics.  For example, for Form A, you might use .DAT files in a sequence like this:

•	Experiment #1, Run #1:  Produces the original A.DAT file.  You evaluate the coverage results of Run #1, and decide to add more test cases to improve the coverage.

•	Experiment #1, Run #2:  Produces a new A.DAT file.

•	When you also load the results of Run #2 to the database,  check Summarize on the Load window to summarize the data from all runs of this experiment.

Using PECSLOAD

You can also access the PECS system directly from the command line, without using the PECS Assistant.  Invoke the PECSLOAD utility from the command line to load the PECS binary file into the database.   During PECSLOAD, both classes and events will also be saved to the database, if they are not already there.

Location of the PECS Data File

When you use the PECSLOAD command, PECS must first locate where the binary (.DAT) file was saved. The PECS data file is usually saved in a temporary directory set by an environment variable, as shown below:

Environment	PECS Default Directory/Environment Variable
Microsoft Windows	TMP
UNIX	FORMS_PECS
VMS	SYS$SCRATCH
If the environment variable is not set, PECS uses the current working directory.

If you issue the PECSLOAD command and receive an error message similar to "Error opening file," probably PECS is searching for the data file and cannot find it.  In this case, re-issue the PECSLOAD command and provide the full pathname in place of the module name.

PECS Database Tables

You may want to consult the PECS database tables to perform data manipulation or obtain specific PECS information, such as an experiment name or number.  PECS uses the following database tables:

•	PECS_run

•	PECS_experiment

•	PECS_class

•	PECS_class_events

•	PECS_data

•	PECS_summary

•	PECS_plsql

Use SQL commands to obtain a list of columns in each table.


Using the PECS assistant examples

Example 1 Using PECSLOAD with an experiment name:

PECSLOAD -f mymod.dat -n my_experiment scott/tiger

Example 2 Using PECSLOAD with an experiment number:

PECSLOAD -f mymod.dat -e 3 scott/tiger


About PECS built-ins

The PECS built-ins allow you to define application-specific events to the PECS system:

To do this:	Use this PECS built-in:
Start and stop PECS	PECS.COLLECTOR
Register classes and events	PECS.ADD_CLASSPECS.ADD_EVENT
Enable and disable classes	PECS.ENABLE_CLASSPECS.DISABLE_CLASS
Define event instances	PECS.START_EVENTPECS.END_EVENTPECS.POINT_EVENT


PECS.ADD_CLASS

 Examples

Syntax

PECS.ADD_CLASS(class_name);

PECS.ADD_CLASS(class_type);

Built-in Type  unrestricted procedure

Returns  PECS.CLASS

Description

PECS.ADD_CLASS creates the class, or group of events, in PECS,  and returns the ID for this class.  Use this class ID to identify the class in future calls to PECS.  The datatype of the class ID is PECS.CLASS.

Parameters

class_type	Specifies the type of class to add.  Valid numeric constant for this parameter:

PECS.FORMS   Specifies Form Builder.

class_name	Specifies the name of the class to add.  Specify the CHAR class name for application-specific classes that do not use one of the class types listed above.

Usage Notes

If you started PECS by adding the PECS.COLLECTOR built-in to your application,  the name of the PECS binary file defaults to the name of the first class you specified with the PECS.ADD_CLASS built-in:  banking.dat.  (If you started PECS from the command line, the name of the PECS binary file defaults to the form name with the .DAT extension: myform.dat.)


PECS.ADD_CLASS examples

/*

/*   This will add the class FORMS                           */
/*                                                           */
forms_class pecs.class := PECS.Add_Class(pecs.FORMS);

/*                                                           */
/*   This will add the class 'Banking'                       */
/*                                                           */
banking_class pecs.class := PECS.Add_Class('Banking');


PECS.ADD_EVENT

 Examples

Syntax

PECS.ADD_EVENT(class_id, event_type);

PECS.ADD_EVENT(class_id, event_description);

Built-in Type  unrestricted procedure

Returns  PECS.EVENT

Description

PECS.ADD_EVENT adds an event to a specified class.

For an Form Builder event, specify the event type from the list of Form Builder event types.  For an application-specific event, specify the event using event_description, which must be unique among events in the class.

Parameters

class_id	Specifies the ID of this class.  The class ID is created with a call to PECS.ADD_CLASS, and is of datatype PECS.CLASS.

event_type	For Form Builder events, specifies the event type. Valid numeric constants for this parameter are PECS.LINE, PECS.FORMS_TRIGGER,  PECS.FORMS_LOV, PECS.FORMS_20TRIGGER (Form Builder V2-style trigger event), PECS.FORMS_PROCEDURE, PECS.FORMS_ALERT, PECS.FORMS_CANVAS, PECS.FORMS_WINDOW, PECS.FORMS_EDITOR.

For application-specific events, specify the event_type from the PECS_EVENTS table, or use the event_description parameter.

event_descriptio	For application-specific events, specifies the event.  The description is limited to 32 datatype CHAR characters.


PECS.ADD_EVENT examples

/*

/*   This will add the class 'Banking'                       */
/*                                                           */

banking_class pecs.class := PECS.Add_Class('Banking');

/*                                                           */
/*   This will add the event Withdraw.                       */
/*   banking_class was previously defined by PECS.ADD_CLASS  */

withdraw pecs.event := PECS.Add_Event(banking_class, 'Withdraw');


PECS.COLLECTOR

 Examples

Syntax

PECS.COLLECTOR(collector_status);

Built-in Type   unrestricted procedure

Description

Use PECS.COLLECTOR to turn PECS on or off. This built-in allows you to start PECS later, if you haven't invoked PECS from the command line.  PECS.COLLECTOR needs to be called only once per session.

Parameters

collector_status	A NUMBER parameter that specifies whether PECS is on or off:

PECS.COLLECT_ON     Turns the collector on.

PECS.COLLECT_OFF    Turns the collector off.

Usage Notes

•	You don't need to use PECS.COLLECTOR if you turned PECS on using the command line option pecs=on.

•	Although you can toggle the status of PECS.COLLECTOR, doing this may produce mismatched events.  For example, if PECS is turned off after a trigger event has started, there may be no corresponding end event.  During the loading of the .DAT file, PECS will detect this and issue a warning saying that a start event is missing an end event, or vice versa.


PECS.COLLECTOR examples

PECS.COLLECTOR(pecs.collect_on);


PECS.DISABLE_CLASS

 Examples

Syntax

PECS.DISABLE_CLASS(class_id);

PECS.DISABLE_CLASS(class_id, event_type);
PECS.DISABLE_CLASS(class_id, event_id);

Built-in Type  unrestricted procedure

Description

To disable all of the events associated with a class, specify only the class_id:

PECS.DISABLE_CLASS(class_id);

To disable only a specific event, supply the class_id and the event_type or event_id:

PECS.DISABLE_CLASS(class_id, event_type);
PECS.DISABLE_CLASS(class_id, event_id);

Parameters

class_id	Specifies the ID of this class.  The class ID is created with a call to PECS.ADD_CLASS, and is of datatype PECS.CLASS.

event_type	For Form Builder events, specifies the event type. Valid numeric constants for this parameter are PECS.LINE, PECS.FORMS_TRIGGER,  PECS.FORMS_LOV, PECS.FORMS_20TRIGGER (Form Builder V2-style trigger event), PECS.FORMS_PROCEDURE, PECS.FORMS_ALERT, PECS.FORMS_CANVAS, PECS.FORMS_WINDOW, PECS.FORMS_EDITOR.

event_id	Specifies the ID of this event name.  The event ID is created with a call to PECS.ADD_EVENT, and is of datatype PECS.EVENT.


PECS.DISABLE_CLASS examples

/*   Disable the internal Form Builder LOV event.            */

PECS.Disable_Class(forms_class, PECS.FORMS_LOV);

/*  Disable the Withdraw event for Banking_class.            */
/*  Banking_class was previously defined with PECS.ADD_CLASS */
/*  Withdraw was previously defined with PECS.ADD_EVENT      */

PECS.Disable_Class(banking_class, withdraw);


PECS.ENABLE_CLASS

 Examples

Syntax

PECS.ENABLE_CLASS(class_id);

PECS.ENABLE_CLASS(class_id, event_type);
PECS.ENABLE_CLASS(class_id, event_id);

Built-in Type  unrestricted procedure

Description

To enable all of the events associated with a class, specify only the class_id:

PECS.ENABLE_CLASS(class_id);

To enable only a specific event, supply the class_id and the event_type or event_id:

PECS.ENABLE_CLASS(class_id, event_type);
PECS.ENABLE_CLASS(class_id, event_id);

Parameters

class_id	Specifies the ID of this class.  The class ID is created with a call to PECS.ADD_CLASS, and is of datatype PECS.CLASS.

event_type	For Form Builder events, specifies the event type. Valid numeric constants for this parameter are PECS.LINE, PECS.FORMS_TRIGGER,  PECS.FORMS_LOV, PECS.FORMS_20TRIGGER (Form Builder V2-style trigger event), PECS.FORMS_PROCEDURE, PECS.FORMS_ALERT, PECS.FORMS_CANVAS, PECS.FORMS_WINDOW, PECS.FORMS_EDITOR.

event_id	Specifies the ID of this event name.  The event ID is created with a call to PECS.ADD_EVENT, and is of datatype PECS.EVENT.


PECS.ENABLE_CLASS examples

/*  Enable the internal Form Builder LOV event.            */

PECS.Enable_Class(forms_class);

/*  Enable the Withdraw event for Banking_class.              */
/*  Banking_class was previously defined with PECS.ADD_CLASS  */
/*  Withdraw was previously defined with PECS.ADD_EVENT       */

PECS.Enable_Class(banking_class, withdraw);


PECS.END_EVENT

 Examples

Syntax

PECS.END_EVENT(event_id, event_handle);

Built-in Type   unrestricted procedure

Description

Marks the end of a PECS event.

Parameters

event_id	Specifies the ID of this event name.  The event ID is created with a call to PECS.ADD_EVENT, and is of datatype PECS.EVENT.

event_handle	Specifies handle of this event occurrence.  The event handle is created with a call to PECS.START_EVENT, and is of datatype NUMBER.


PECS.END_EVENT examples

/*  Measure the performance of the Withdraw event            */

/*  Banking_class was previously defined with PECS.ADD_CLASS */
/*                                                           */

withdraw_handle := PECS.Start_Event(withdraw, 'Withdrawing Cash');
.
.   /do the withdraw/
.
PECS.End_Event(withdraw, withdraw_handle);


PECS.POINT_EVENT

 Examples

Syntax

PECS.POINT_EVENT(event_id, event_comment);

Built-in Type   unrestricted procedure

Description

Use PECS.POINT_EVENT to determine whether an event was reached during code execution.

Parameters

event_id	Specifies the ID of this event name.  The event ID is created with a call to PECS.ADD_EVENT, and is of datatype PECS.EVENT.

event_comment	A CHAR comment to identify the event.

Usage Notes

•	Use PECS.POINT_EVENT when you need to know only that a given application-specific event occurred, rather than its duration.

•	You can use PECS.POINT_EVENT to gather coverage data for specific parts of your application where you insert PECS point events.


PECS.POINT_EVENT examples

/*   Start the Withdraw event               .          */

/*                                                     */
...

...
IF (do_withdraw = TRUE) then
...
message('Success collecting data for event Withdraw');
PECS.Point_Event(GLOBALS.withdraw,'Withdraw Success');
ELSE
...
 message('Error collecting data for event Withdraw');
PECS.Point_Event(GLOBALS.withdraw,'Withdraw Error');
END IF;


PECS.START_EVENT

 Examples

Syntax

PECS.START_EVENT(event_id,event_ comment);

Built-in Type   unrestricted procedure

Returns  NUMBER

Description

Marks the beginning of a PECS event.  PECS.START_EVENT returns a unique identifier for this occurrence of this particular event, which is needed to end the event.

Parameters

event_id	Specifies the event ID.  Datatype is PECS.EVENT.

event_comment	A CHAR comment to identify the event.

Usage Notes

PECS.START_EVENT returns an identifier, or handle, to the event that must be used with PECS.END_EVENT to mark the end of the event.


PECS.START_EVENT examples

/*  Measure the performance of the Withdraw event            */

/*  Banking_class was previously defined with PECS.ADD_EVENT */
/*                                                           */
withdraw_handle := PECS.Start_Event(withdraw, 'Withdrawing Cash');
.
.   /do the withdraw/
.
PECS.End_Event(withdraw, withdraw_handle);


About PL/SQL in Form Builder

PL/SQL is Oracle's procedural extension to the SQL database language.  It combines the data manipulation and transaction processing capabilities of SQL with constructs typically found in procedural programming languages such as variable and constant declarations, assignment, looping, and conditional branching.

You can use PL/SQL to enhance and modify the default functionality that is built in to every Form Builder application. To do so, you need to be familiar with PL/SQL concepts and syntax.  The PL/SQL language is documented in PL/SQL User's Guide and Reference.

You use the integrated PL/SQL Editor for writing PL/SQL code in Form Builder.  In the Builder, you write PL/SQL code when you do the following:

•	create a trigger

•	write a user-named subprogram

•	write a PL/SQL package

•	create a PL/SQL-type menu item

•	define menu startup code


About Form Builder built-in subprograms

  Related Topics

Built-in subprograms are packaged procedures and functions that are  available within Form Builder.  A procedure is usually a complete statement used to perform an action; a function is an expression of a specific data type that is part of a statement used to compute a value.

Each built-in subprogram is a group of program instructions that executes some application function.  Built-in subprograms can be called from triggers, menu item commands, and user-named subprograms, but cannot be edited or modified in any way.


Calling Form Builder built-in procedures

To call a procedure, type the procedure name and any required parameters as a statement in a PL/SQL block.  A call to a built-in procedure is a complete statement, and must be terminated with a semicolon.

Go_Item('customer.cust_id');

The GO_ITEM procedure moves the input focus to the item named in its parameter list; in this case, the cust_id text item in the customer block.


Calling Form Builder built-in functions

 Examples

When you call a function, you need to consider the data type of the function's return value.  Functions can be combined with constants, variables, and logical operators to form an expression.  Because they return a single value, functions can be used in the same way as local variables or constants of the same type.


Calling Form Builder built-in functions examples

Example 1

DECLARE
item_required	VARCHAR2 (5);
BEGIN
item_required := Get_Item_Property('customer.custid',REQUIRED);
END;

The built-in function GET_ITEM_PROPERTY is called to get the current setting of the Required property for the custid item in the customer block.  Because the return type of the GET_ITEM_PROPERTY function is CHAR, the variable to which the return value is assigned must either be of type CHAR or VARCHAR2.

Example 2

:control.item_A := Message_Text;

The MESSAGE_TEXT function returns a CHAR value that is assigned to  item_A in the control block.  item_A must be the same type as the return value of the MESSAGE_TEXT function.

Example 3:

Go_Item(Get_Block_Property('customer',LAST_ITEM));

The GET_BLOCK_PROPERTY function is used to get the name of the last item in the customer block. The GET_BLOCK_PROPERTY function is nested as a parameter to the GO_ITEM procedure, and its return value is the target item for the GO_ITEM operation.

Example  4:

IF Show_LOV('customer_list') THEN
Message('Good Selection.');
ELSE
Message('No Customer was Selected.');
END IF;

A function that has a BOOLEAN return type evaluates to either TRUE or FALSE, and so can be used as an expression in a conditional statement.

The function SHOW_LOV first displays the list of values named customer_list, then waits for operator input; if the operator selects a record from the LOV, the function returns TRUE; if the operator dismisses the LOV by choosing Cancel, it returns FALSE.

Note:  Functions cannot be used in DML statements.  You can achieve the same result by assigning the return value of the function to a local variable, and then referencing the variable in the DML statement.


Passing parameter values to subprograms

Parameters provide information to a subprogram that it needs to execute successfully.  In a function or procedure call, parameters are listed after the name of the function or procedure, enclosed in parentheses.

The specification for a function or procedure defines each of the parameters it requires.  The parameter names in a function or procedure declaration are referred to as formal parameters.  In the following procedure syntax example,  the formal parameters include window_name, width, and height:

Resize_Window (window_name, width, height);

The values of formal parameters are provided by actual parameters.

When you call the RESIZE_WINDOW procedure, you supply values for the formal parameters by referencing a specific window and specifying the desired width and height values.  The values you enter in the list of parameters are actual parameters.  In the following procedure call, my_window, 50, and 35 are actual parameters:

Resize_Window('my_window',50,35);

Note:  To specify a single quote character as a literal character, prefix each single quote in the string with an additional single quote.  For example, the actual parameter '''50'' PIXELS' is interpreted by the calling subprogram as '50' PIXELS.


Understanding parameter data types

Formal parameters, like variables, are of a specific data type.  In the following syntax example, the data type appears after each formal parameter name:

Show_Window(window_name IN CHAR,
 x IN NUMBER,
 y IN NUMBER);
 Return BOOLEAN

You can see from this example that the function SHOW_WINDOW takes parameters of type CHAR, and NUMBER.  CHAR and NUMBER are native PL/SQL types.

In a call to a built-in subprogram, an actual parameter can be any expression that evaluates to a value of the same type as the formal parameter to which it corresponds.  This means that an actual parameter can be a local or global variable, a function, or any combination of variables, constants, and operators that evaluates to a value of the appropriate type.


Using built-in constants as actual parameters

  Related Topics

There are predefined constants that you can use for many built-in subprograms.  Look at the syntax for the EXIT_FORM built-in procedure shown below.  EXIT_FORM has two optional parameters, commit_mode and rollback_mode, that prescribe how Form Builder should exit the current form:

Exit_Form(commit_mode, rollback_mode);

The commit_mode and rollback_mode parameters are of type NUMBER.  When you call EXIT_FORM, you can use predefined numeric constants for these parameters.  Valid constants for the commit_mode parameter include ASK_COMMIT, DO_COMMIT, NO_COMMIT, and NO_VALIDATE.  Valid constants for the rollback_mode parameter include NO_ROLLBACK and TO_SAVEPOINT.

Constants for built-in subprograms are predefined literals that are declared by  Form Builder as type NUMBER at startup.  The actual numeric value of each constant is stored internally, and is not externalized.

When you use constants as actual parameters, enter them exactly as they appear in the syntax, and do not enclose them in quotes:

Exit_Form(DO_COMMIT,NO_ROLLBACK);

Because built-in constants are of type NUMBER, they can be assigned to NUMBER variables. However, constants cannot appear on the left side of an expression.


Using default parameter values

  Related Topics

Some parameters for built-in functions and procedures have predefined default values.  If you do not provide an actual parameter for a formal parameter,  Form Builder uses the default value defined for that parameter.  Consider the procedure CALL_FORM, which invokes a new form module while keeping the current form module active.  The following example shows the syntax for the CALL_FORM procedure:

Open_Form(form_name,activate_mode,session_mode);

The default parameter values defined for the activate_mode and session_mode parameters are the constants ACTIVATE  and NO_SESSION, respectively.

When you invoke OPEN_FORM without parameters,  Form Builder uses the default parameters implicitly:

Open_Form('order_entry');

It is always acceptable to enter the default parameter values if you want to do so for the sake of clarity.  The following procedure calls are equivalent; the first requires fewer keystrokes, but the second is more descriptive:

Open_Form('order_entry');
Open_Form('order_entry',ACTIVATE,NO_SESSION);


Using positional and named notation parameters

You can use either positional or named notation to pass parameters to a subprogram.  When positional notation is used, the compiler looks at the relative positions of the actual parameters to determine the formal parameters to which they correspond.

The following example shows the syntax for a user-named procedure called update_inventory:

PROCEDURE update_inventory (warehouse CHAR,product NUMBER);

To call this procedure using positional notation, you must enter the actual parameters in the same order that the corresponding formal parameters appear in the specification:

update_inventory('chicago',10557);

When you write parameters using named notation, the correspondence between a formal and actual parameter is stated explicitly in the parameter list itself, and you can pass parameters in any order.  Thus, the following procedure calls are logically equivalent:

update_inventory(warehouse => 'chicago',product => 10557);
update_inventory(product => 10557, warehouse =>'chicago');

You can mix positional and named notation, provided that the parameters being passed by position precede those being passed by name in the parameter list:

update_inventory('chicago', product => 10557);

For most built-in subprograms, using positional notation is preferable to named notation because it requires fewer keystrokes.  However, named notation can be especially useful when calling built-in subprograms that have two or more optional parameters.  With named notation, you need only supply values for the optional parameters you want to pass, and can leave the others unspecified.


Referencing Form Builder objects by name

To reference a Form Builder object by name in a PL/SQL statement, enclose the object name in single quotes:

'form_module_name'
'block_name'
'window_name'

For example, when you call the procedure RESIZE_WINDOW, you must pass the name of the window to be resized as the first parameter. The window name must be enclosed in single quotes:

Resize_Window('status_window',50,35);

To reference an item by name, include the name of the block to which the item belongs to form a fully-qualified name:

'block_name.item_name'

For instance, when you call the GO_ITEM built-in procedure to move the input focus to a different item, you pass GO_ITEM the name of the target item:

Go_Item('customer.cust_id');

To reference a specific column in a record group:

'record_group_name.column_name'

To reference an item that was a component of a column object or a REF column, include the column name as well as the block name.  For object components, the connector between column name and item name is an underscore:

'blockname.columnname_itemname'


Referencing Form Builder item values

The following types of items store values:

•	check boxes

•	display items

•	list items

•	radio groups

•	text items

•	OLE container

•	VBX control

To reference the value stored in an item, put a colon in front of the fully-qualified item name.  Do not use quotes around an item name when you reference its value:

:block_name.item_name

This syntax is similar to that used when referencing global variables in  Form Builder.  In fact, item values can be used in PL/SQL statements just like local or global variables.  This means that you can do all of the following:

Assign the value of an expression to an item:

:ord.total := price * .85;

Assign the value of one item to another item:

:ord.comment := :control.textfield;

Select database values into items:

SELECT phone INTO :info.tel_no FROM warehouse
WHERE id = :info.warehouse_id;


Referencing Form Builder objects by internal ID

Form Builder assigns an ID to each object that you create.  An object's ID is an internal handle whose actual value is never externalized.

You can get the ID of an object by calling the built-in FIND_ function appropriate for that object class.  The FIND_ functions take a fully-qualified object name as a parameter.

In the following example, the FIND_WINDOW function is used to assign the ID of the window named my_window to the variable id_var:

DECLARE
id_var	WINDOW;
BEGIN
id_var := Find_Window('my_window');
END;

Once an object ID has been assigned to a variable, you can use that variable to reference the object, rather than referring to the object by name.

For example, the syntax for the procedure RESIZE_WINDOW indicates that you can call this procedure with either a window name or window id:

Resize_Window(window_name CHAR,width NUMBER,height NUMBER);
Resize_Window(window_id WINDOW,width NUMBER,height NUMBER);

Thus, the following calls are logically equivalent:

Resize_Window('my_window',50,35);
Resize_Window(id_var,50,35);

A FIND_ function can also be used as an actual parameter in a procedure or function call:

Resize_Window((FIND_WINDOW('my_window'),50,35);

Mixing Names and IDs in Parameter Lists  You can mix object IDs and object names in the same parameter list, provided that each actual parameter refers to a distinct object:

Replace_Content_View(canvas_id,'window_name');

You cannot, however, use an object ID and an object name to form a fully-qualified object name:

/*  invalid procedure call:   */
Set_Group_Char_Cell(group_id.'column_name',1,'in_stock');

Object ID Types  The return values of the FIND_ functions, that is, the object IDs themselves, are of a specific datatype.  In the syntax example for the RESIZE_WINDOW procedure, you saw that the formal parameter window_id was declared as type WINDOW.  The types for object IDs are predefined in Form Builder. There is a different type for each object class.

Form Builder Datatypes

The following table shows the FIND_ function and return type for each object:

Object	Function	Return Type
Alert	FIND_ALERT	ALERT
Block	FIND_BLOCK	BLOCK
Canvas	FIND_CANVAS	CANVAS
Record Group Column	FIND_COLUMN	GROUPCOLUMN
Editor	FIND_EDITOR	EDITOR
Form	FIND_FORM	FORMMODULE
Record Group	FIND_GROUP	RECORDGROUP
Item	FIND_ITEM	ITEM
List of Values	FIND_LOV	LOV
Menu Item	FIND_MENU_ITEM	MENUITEM
Parameter List	GET_PARAMETER_LIST	PARAMLIST
Relation	FIND_RELATION	RELATION
Report	FIND_REPORT_OBJECT	REPORT
Tab Page	FIND_TAB_PAGE	TAB_PAGE
Timer	FIND_TIMER	TIMER
Tree Node	FIND_TREE_NODE	NODE
View	FIND_VIEW	VIEWPORT
Window	FIND_WINDOW	WINDOW

Declaring Variables for Object IDs  Before you can assign an object ID to a local variable, you must declare the variable to be of the same type as the object ID:

DECLARE
id_var	  WINDOW;
BEGIN
id_var := Find_Window('my_window');
IF Get_Window_Property(id_var, HEIGHT) < 25 THEN
Resize_Window (id_var, 50, 35);
END IF;
END;

Why Use Object IDs?  There are two reasons to use object IDs in your PL/SQL code:

•	Using object IDs improves performance

•	Using object IDs makes code more generic and easier to maintain

Each time you reference an object by name in a PL/SQL statement,  Form Builder does the necessary processing to look up the object's ID internally.  If you refer to an object by name more than once in the same trigger,  Form Builder looks up the object's ID each time.  The following trigger code references the object my_record_group three times:

DECLARE
dummy_var	NUMBER;
count	NUMBER;
BEGIN
dummy_var := Populate_Group('my_record_group');
count := Get_Group_Row_Count('my_record_group');
IF count > 20 THEN
Delete_Group_Row('my_record_group', ALL_ROWS);
END IF;
END;

In contrast, if you refer to an object by its ID,  Form Builder looks up the object only once--when you call the initial FIND_ function to get the ID:

DECLARE
dummy_var	NUMBER;
count	NUMBER;
group	RECORDGROUP := Find_Group('my_record_group');
BEGIN
dummy_var := Populate_Group(group);
count := Get_Group_Row_Count(group);
IF count > 20 THEN
Delete_Group_Row(group, ALL_ROWS);
END IF;
END;

Besides improving performance, using object IDs results in code that is easier to maintain and can be reused in other places.  When you need to change the name of an object or want to reuse the same code to operate on a different object, you need only make the change in the parameter list of the initial FIND_ function, rather than in each statement that references that object.


Referencing Form Builder items indirectly

  Related Topics

You can reference items indirectly with the NAME_IN and COPY built-in subprograms.

The NAME_IN function returns the contents of an indicated variable or item.  Use the NAME_IN function to get the value of an item without referring to the item directly.

The following statements are equivalent:

IF :emp.ename = 'smith' -- direct reference
IF NAME_IN('emp.ename') = 'smith' -- indirect reference

The return value is always a character string.  To use NAME_IN for a DATE or NUMBER item, convert the string to the desired data type with the appropriate conversion function:

date_var := TO_DATE(Name_In('order.date_item'));
num_var := TO_NUMBER(Name_In('order.number_item'));

Notes on NAME_IN:

•	The NAME_IN function cannot return the contents of a global or local variable.

•	In PL/SQL triggers that will be executed in enter-query mode, you must use NAME_IN rather than normal bind-variable notation to access values in the data-block.  (This is because the end-user might  type relational operators into the item, producing a value which is not in a form that can be processed by PL/SQL.)

The COPY Procedure  The COPY procedure assigns an indicated value to an indicated variable or item.  Unlike standard PL/SQL assignment, however, using the COPY procedure allows you to indirectly reference the item whose value is being set:

:emp.ename := 'smith';	-- direct reference
Copy('smith','emp.ename');	-- indirect reference

COPY can be used with the NAME_IN function to assign a value to an item whose name is stored in a reference variable or item:

/* put value 'smith' in item whose name is stored in ref_item */
Copy('smith',Name_In('control.ref_item'));

Why Use Indirect Reference  Referencing items indirectly allows you to write more generic, reusable code.  By using variables in place of actual item names, you can write a subprogram that can operate on any item whose name has been assigned to the indicated variable.

Also, using indirect reference is mandatory when you refer to the value of a form bind variable (item, parameter, global variable) in PL/SQL that you write in a library or a menu module.  Because libraries, menus, and forms are separate application modules, you cannot refer directly to the value of a form item in a menu-item command or library procedure.


About local variables

A local variable is a PL/SQL variable whose value is only accessible within the trigger or user-named subprogram in which the variable is declared.   Form Builder supports standard PL/SQL variable declaration and assignment for local variables.


About global variables

A global variable is a Form Builder variable whose value is accessible to triggers and subprograms in any module that is active during the current session.  A global variable stores a character string of up to 255 characters in length.

Global variables are not formally declared the way PL/SQL local variables are.  Rather, you initialize a global variable the first time you assign a value to it:

:GLOBAL.my_var := TO_CHAR(:order.total * .85);

To reference a global variable, prefix the variable name with the word GLOBAL and a colon.  The following example shows a global variable passed as an actual parameter to a procedure call:

calculate_discount(TO_NUMBER(:GLOBAL.my_var));

Referencing a global variable that has not been initialized through assignment causes a runtime error.

To destroy a global variable and release its memory, use the ERASE built-in procedure:

Erase('GLOBAL.my_var');


Initializing Global Variables with Default Value

You can use the DEFAULT_VALUE built-in procedure to assign a value to a variable whose value is NULL.  If the value of the indicated variable is not NULL, DEFAULT_VALUE does nothing.  If the variable to which the value is being assigned is an undefined global variable,  Form Builder creates the variable.

The following example creates a global variable named country and initializes it to the value FRANCE:

Default_Value('FRANCE','GLOBAL.country');


Using NULL-canvas items as variables

  Related Topics

A NULL-Canvas item is an item that has its Canvas property left unspecified, and so is not assigned to a canvas.  A NULL-canvas item is never displayed at runtime, and operators cannot see the item or interact with it.

You can use a NULL-canvas item for temporary storage of data values, much like a global variable.  For example, you can define an item of type NUMBER in a control block, and then reference its value in triggers and user-named subprograms:

IF :control.count > 200 THEN
...

Any type of item that can store values can be used as a NULL-canvas item variable.  Display items are a good choice because they use less memory than other types of items.

Consider the following factors when deciding whether to use a global or NULL-canvas item as a variable:

•	Items can be defined as CHAR, NUMBER, or DATE data types; global variables store only character strings, and using conversion functions like TO_DATE and TO_NUMBER requires additional processing.

•	Items can be dimensioned by setting their Maximum Length property; global variables are always 255 bytes.

•	Global variables are visible across multiple modules during a runtime session; NULL-canvas items are not.

•	The CLEAR_FORM operation sets the value of a NULL-canvas item in the current form to NULL; the value of a global variable is not affected by CLEAR_FORM.

•	Both items and global variables can be referenced in the default WHERE clause for a data block and record group SQL statements.


Accessing Form Builder system variables

  Related Topics

Form Builder provides built-in system variables that keep track of runtime status conditions during a Form Builder Runform session.  You can read the values of these variables in any form trigger or user-named subprogram.  Here is an example of checking the value of the system variable System.Mode:

IF :System.Mode = 'ENTER-QUERY' THEN
IF NOT Show_Lov('dept_lov') then
RAISE Form_Trigger_Failure;
END IF;


About user-named subprograms

A user-named subprogram is a named PL/SQL function or procedure that you write in a form, menu, or library module.  Although triggers are the primary way to add programmatic control to an Form Builder application, user-named subprograms supplement triggers by allowing you to reuse code without having to enter it in multiple triggers.

Unlike triggers, which execute in response to application events, a user-named subprogram must be called explicitly within your application.  A user-named subprogram that you define in a form module can be called from any trigger in that module.

Just as built-in subprograms save you the trouble of writing code for common functions like navigation and database interaction, user-named subprograms provide a way to reuse application-specific code that you write yourself.

If you find yourself writing the same lines of code in more than one trigger or menu item command, you should consider writing a user-named subprogram instead.

In most applications, operators can perform the same operation in more than one way, and from more than one window or menu.  For example, an order-entry application might allow an operator to calculate an order total by pressing a key, clicking a button, or selecting a menu item from a menu.  Without a user-named subprogram, you would need to write the same calculation formula in a Key trigger, a When-Button-Pressed trigger, and a menu-item command.

A better way is to write the calculation formula once in a user-named subprogram.  You can give the subprogram a meaningful name, say, calculate_totals,  and then call it by name from any trigger or menu item in which the formula is required.

Like built-in subprograms, user-named subprograms can take parameters.  When you declare the parameters for a subprogram, you specify their data type, mode, and default value, if any.  By using parameters to pass actual values, you can create more generic subprograms that use values that are supplied programmatically at runtime.


Creating a user-named subprogram

User-named subprograms are named objects that you define in form, menu, or library modules.

To create a user-named subprogram:

1	In the Object Navigator, select the desired Program Units node and then choose Navigator [image] Create.

The New Program Unit dialog appears.

For information on PL/SQL Editor commands, refer to Chapter 2, "Working with the Design Tools."

2	Specify the Name of the program unit to create and then specify the program unit Type (either Procedure, Function, Package Spec, or Package Body).

3	Enter, edit, and compile the procedure or function you are defining.

Enter a complete procedure or function definition using standard PL/SQL structure and syntax.

4	Choose Compile to compile your program unit.

Note:  Form Builder will apply your changes automatically when you close the editor even if you have not successfully compiled the program unit.

Form Builder displays each program unit name with an annotation that indicates its type (procedure body, package specification, and so on).  For example, a procedure body would be annotated as shown here:

calculate_totals (Procedure Body)

And a package specification would appear as follows:

Error_Handlers (Package Specification)


Procedure Syntax

The procedure specification begins with the keyword PROCEDURE and ends with the procedure name or with the list of formal parameters.  The procedure body begins with the keyword IS and ends with the keyword END followed by the optional procedure name.

Syntax

PROCEDURE procedure_name [argument list] IS
   [local variable declaration]
BEGIN
   statements
   [EXCEPTION exception_handlers]
END;

where:

procedure_name	Is the unique, user-defined name of the procedure.  This name must adhere to ORACLE naming conventions.  For more information, refer to your SQL Language Reference Manual.

argument_list	Is ({var_name [mode] type [:= value]}[,...])

where:

var_name	Is the unique name of a local variable.

mode	Is {IN|OUT|IN OUT}.

type	Is any acceptable PL/SQL type.

value	Is a PL/SQL expression.

local_variable_  declaration	Is {var_name type [:= value]}(,...]

statements	Are the executable PL/SQL statements.

exception_handler	Refer to your PL/SQL User's Guide and Reference.


Function Syntax

Every function must execute a RETURN statement.  The RETURN statement sets the return value of the function and immediately returns control to the trigger, user-named subprogram, or menu item command that called the function.

Syntax

FUNCTION function_name [argument list] RETURN [type] IS
   [local variable declaration]
BEGIN
   statements
   RETURN (result);
   [EXCEPTION exception_handlers]
   RETURN (result);
END;

where:

function_name	Is the unique, user-defined name of the function.  This name must adhere to ORACLE naming conventions.

argument_list	Is ({var_name [mode] type [:= value]}[,...])

where:

var_name	Is the unique name of a local variable.

mode	Is {IN|OUT|IN OUT}.

type	Is {BOOLEAN|VARCHAR2|NUMBER| DATE|Form Builder Object Type}.

value	Is a PL/SQL expression.

local_variable_  declaration	Is {var_name type [:= value]}(,...]

statements	Are the executable PL/SQL statements.

exception_handler	Refer to your PL/SQL User's Guide and Reference.

result	Is the expression indicating the value of the function.  The value of the expression must be compatible with the type specified in the function specification.

Procedure Example:

The following procedure processes an order by decrementing the inventory available for a particular product.  To call this procedure, you pass in the product ID, the number of units being ordered, and  the warehouse that should fill the order:

PROCEDURE do_order (units_ordered IN NUMBER,
   prod_id IN NUMBER,
   warehouse IN NUMBER) IS
   units_in_stock	NUMBER;
BEGIN
   SELECT amount_in_stock INTO units_in_stock FROM inventory
     WHERE product_id = prod_id
     AND warehouse_id = warehouse;
   IF units_in_stock >= units_ordered THEN
     UPDATE inventory
     SET amount_in_stock = units_in_stock - units_ordered
       WHERE product_id = prod_id;
   ELSE
     Message('Insufficient stock on hand.');
     Raise Form_Trigger_Failure;
   END IF;
END;

You could use this procedure in a trigger as follows:

do_order (:order.units, :order.prod_id, :warehouse.id);

In this example, the values of the three formal parameters are the current values of items in the form, specified with standard bind variable syntax:

:block_name.item_name

Function Example:

The following function returns the number of product units in stock at a particular warehouse. When you call this function, you pass in a product ID and warehouse ID:

FUNCTION get_inventory (product NUMBER, warehouse NUMBER)
   RETURN NUMBER IS
   amount NUMBER;
BEGIN
   SELECT amount_in_stock INTO amount FROM inventory
   WHERE product_id = product and warehouse_id = warehouse;
   RETURN amount;
EXCEPTION
   WHEN OTHERS THEN
     Message('Invalid product name or warehouse ID.');
     RETURN (-1);
END;

You could use this function in a trigger as follows:

DECLARE
   inv	NUMBER;
   amount_required	NUMBER := :order_block.order_item;
BEGIN
   inv := Get_inventory (:product.id, :warehouse.id);
   IF inv < 0 THEN
   . . . -- handle the error here
   ELSE IF inv >= amount_required THEN
   ... -- process the order here
   END IF;
END;


Calling user-named subprograms

Calling user-named procedures and functions is similar to calling built-in procedures and functions; you can use both named and positional association to pass parameters.  You can reference form objects in user-named subprograms just as you would in the parameter list of a built-in subprogram.

When you compile a form or menu module to create a runtime file, Form Builder must be able to find any subprograms called by that module.  The module in which a subprogram is defined determines where that subprogram can be called.

When you develop an application that includes more than one module, keep in mind the following scoping rules:

•	a user-named subprogram defined in a form module can be called only from triggers and other user-named subprograms in that same module

•	a user-named subprogram defined in a menu module can be called only from menu item commands and startup code in that same module

•	a user-named subprogram defined in a library module can be called from any trigger or menu item command, provided that the library is attached to the form or menu module

You can create a library of user-named subprograms by writing procedures and functions directly in a library module or by copying subprograms from other modules into a library.  For information on libraries, see Chapter 20, "Working with Libraries."


Defining parameters

Using parameters is optional.  Subprograms that do not take parameters are written without parentheses.  If you declare a parameter, you must indicate its data type and mode in the formal parameter list.

Parameter Data Types  In a function, parameters can be declared as type VARCHAR2, DATE, NUMBER, or BOOLEAN, or any of the Form Builder object types.  In a procedure, parameters can be of any valid PL/SQL type.  When you create a function or procedure, enter the data type after the name of each formal parameter:

PROCEDURE display_overdue_shipments (dept_id NUMBER);
FUNCTION credit_ok (customer VARCHAR2) RETURN BOOLEAN;

Parameter Modes  The mode of a parameter can be either IN (the default), OUT, or IN OUT.  An IN parameter passes a value to a subprogram.  The subprogram can read the value of the IN parameter, but cannot write its value.  An actual IN parameter can be a constant, literal, initialized variable, or expression.

An OUT parameter returns a value from a subprogram.  An actual OUT parameter can only be a local variable (not a bind variable), and the subprogram must assign a value to the variable.  If it does not, the predefined PL/SQL exception NO_DATA_FOUND is raised.

An IN OUT parameter passes a value to a subprogram and returns a value from the subprogram.  An actual IN OUT parameter can be a local variable or a bind variable.  A subprogram can write the value of an IN OUT parameter, but is not required to do so.

Both functions and procedures can take OUT and IN OUT parameters.  A procedure that returns a value by way of an OUT or IN OUT parameter works much like a function, and can be used to accomplish anything that a function would normally be used for.

If you do not explicitly indicate the mode of a formal parameter in the procedure or function specification, the parameter is declared as an IN parameter.  Thus, the following procedure specifications are equivalent:

PROCEDURE calculate_discount(multiplier NUMBER);
PROCEDURE calculate_discount(multiplier IN NUMBER);

You can explicitly state the mode of a parameter by entering IN, OUT, or IN OUT after the formal parameter name in the subprogram specification.

Note:  When you call a subprogram that takes an IN OUT or OUT parameter, be aware that a value is always assigned to the actual parameter, even if the subprogram itself does not explicitly write the value of the parameter.

For example, if you reference a text item as an actual parameter for a formal IN OUT parameter, the value of the text item is updated when the subprogram executes, even if the subprogram itself does not do an explicit assignment statement.  This can cause the record status to become CHANGED, and the record to be marked for update or insert.

Assigning Default Values to IN Parameters  You can assign a default value to a formal IN parameter when you declare the parameter.  Many of the Form Builder built-in subprograms use this technique.  When you call these subprograms, you do not have to enter an actual parameter for the default formal parameter unless you want to override the parameter's default value.

To assign a default value to a formal parameter, use the PL/SQL assignment operator in the formal parameter list.  The value you assign must be a constant or expression of the same data type as the formal parameter:

PROCEDURE calculate_discount(multiplier IN NUMBER := 15);

When you call this procedure, you can omit the multiplier parameter if you want the procedure to execute with the default value (15):

calculate_discount;

Or, you can override the default value by providing an actual parameter:

calculate_discount(10);

Note that when using positional notation, only trailing parameters can have default values.


About PL/SQL packages

A package is a PL/SQL construct that groups logically related types, objects, procedures, and functions.  Packages usually have two parts, a specification and a body, although sometimes the body is unnecessary.

The specification is the interface to the package; it declares the types, variables, constants, exceptions, cursors, and subprograms (procedures and functions) available for use.  The body fully defines cursors and subprograms, and so implements the specification.

Form Builder provides several predefined packages that you can use, or you can define your own packages in form, menu, or library modules.  You can also define packages in the Oracle Server, and then reference their contents from client-side applications. For information on using stored procedures with Form Builder, see About stored programs .

The syntax for a package is similar to that for a procedure:

PACKAGE name IS  -- specification
-- public type and object declarations
-- subprogram specifications
END [name];
PACKAGE BODY name IS  --body (hidden part)
-- private type and object declarations
-- subprogram bodies
[BEGIN
-- initialization statements]
END [name];

The specification holds public declarations, which are visible to your application.  The body holds implementation details and private declarations, which are hidden from your application.

Only subprograms and cursors have an underlying implementation or definition.  So, if a specification declares only types, constants, variables, and exceptions, the package body is unnecessary.

Only the declarations in the package specification are visible and accessible to your application.  Implementation details in the package body are hidden and inaccessible.  You can code and compile the specification separately. Once the specification has been compiled, you can successfully compile any triggers or user-named subprograms that reference the specification.  You need not define the package body fully until you are ready to complete the application.

Note:  If you later change a package, then any forms or menus that call the package may need to be recompiled as well.


Creating PL/SQL packages

 Examples

You can create a package by organizing your procedures and functions to form a suitcase of PL/SQL objects.

Packages can contain variables that are persistent for a user's entire session (akin to a server-side GLOBAL variable and just as useful), as well as cursors that may remain open across calls to functions and procedures in the package.

See the PL/SQL User's Guide and Reference for more information on packages.

Note: The first time a package is called (by any user on the instance) the entire package is loaded into the Oracle SGA to make subsequent invocation of any procedures or functions it contains very fast.

Restrictions  Form Builder provides direct support for invoking stored procedures and functions, but not for directly referencing package variables or package cursors. To manipulate package variables and package cursors within the code on the server side, you must design a function or procedure. The available data types are:

•	VARCHAR2--maximum of VARCHAR2(2000)

•	NUMBER

•	DATE

•	BOOLEAN

If you use these data types to write functions or procedures, values of package variables and fetched cursor data can be returned to the Form Builder caller via parameters or a function return value.

Form Builder requires that both Package Specification and Body be valid in order to compile an Form Builder PL/SQL block that makes reference to the package.


Creating PL/SQL packages examples

CREATE OR REPLACE PACKAGE LIB_HR AS

    -- Retrieve Social Security Number for an Employee
    FUNCTION get_ssn(theEmpNo NUMBER) RETURN NUMBER;
   -- Hire a new Employee and return his/her Employee Number
  FUNCTION hire_employee(theName VARCHAR2,
                  theDept NUMBER,
                  theSal  NUMBER,
                  theDate DATE,
                  theSSN  NUMBER) RETURN NUMBER;

   -- Terminate an existing Employee
   PROCEDURE fire_employee(theEmpno NUMBER,
                  theReason VARCHAR2);

   -- Set Signing Bonus Variable
   PROCEDURE set_bonus(newValue NUMBER);

   END LIB_HR;

CREATE OR REPLACE PACKAGE BODY LIB_HR AS
   -- Package Variables --
   signingBonus NUMBER := 1000;

   -- Package Cursor --
   CURSOR next_empid
      IS SELECT empid_sequence.NEXTVAL
         FROM dual;

   -- Retrieve Social Security Number for an Employee
   FUNCTION get_ssn(theEmpNo NUMBER) RETURN NUMBER IS
      tmpSSN NUMBER;
   BEGIN
      SELECT ssn
         INTO tmpSSN
         FROM emp
         WHERE empno = theEmpNo;
         RETURN(tmpSSN);
   EXCEPTION
      WHEN NO_DATA_FOUND THEN
         RETURN(-1);
    END;

   -- Hire a new Employee and return Employee Number
   FUNCTION hire_employee(theName VARCHAR2,
                  theDept NUMBER,
                  theSal  NUMBER,
                  theDate DATE,
                  theSSN  NUMBER) RETURN NUMBER IS
      tmpEmpNo NUMBER;
   BEGIN
      IF (NOT next_empid%ISOPEN) THEN
         OPEN next_empid;
      END IF;
      FETCH next_empid INTO tmpEmpNo;
      -- We don't have to CLOSE the cursor because it will
      -- remain open between calls

      INSERT INTO EMP(empno, ename, deptno, sal,
                       hiredate, ssn, bonus)
      VALUES(tmpEmpNo, theName, theDept, theSal,
         theDate, theSSN, signingBonus);
      RETURN(tmpEmpNo);
   EXCEPTION
      WHEN OTHERS THEN
      RETURN(-1);
   END;
   -- Terminate an existing Employee
   PROCEDURE fire_employee(theEmpno NUMBER,
                     theReason VARCHAR2) IS
   BEGIN
      DELETE FROM emp
         WHERE empno = theEmpno;
      INSERT INTO terminations(empno, reason)
         VALUES(theEmpno, theReason);
   END;

   -- Set Signing Bonus Variable
   PROCEDURE set_bonus(newValue NUMBER) IS
   BEGIN
      signingBonus := newValue;
   END;

END LIB_HR;


Referencing PL/SQL package contents

You can refer to the contents of a package using standard PL/SQL dot notation:

package_name.object_name
package_name.program_unit_name

For example, to call the procedure arrange_windows defined in the package win_manage, you would write the following in a trigger or user-named subprogram:

win_manage.arrange_windows

The same scoping rules apply to packages that apply to user-named subprograms.


About Form Builder packages

  Related Topics

Form Builder provides the following predefined packages:

Standard Extensions	The STANDARD Extensions package contains Form Builder built-in procedures and functions.

TOOL_ENV	The TOOL_ENV package allows you to interact with Oracle environment variables.

ORA_NLS	The ORA_NLS package enables you to extract high-level information about your current language environment.

TOOL_RES	The TOOL_RES package allows you to extract string resources from a resource file.

ORA_FFI	The ORA_FFI package allows you to access foreign (3GL) functions.

ORA_DE	The ORA_DE is an internal package.  Do not use this package.

STPROC	The STPROC is an internal package.  Do not use this package.

TEXT_IO	The TEXT_IO package allows you to read and write information to a file in the file system.

PECS	The PECS package allows you to evaluate form performance.

FORMS_OLE	The FORMS_OLE package contains Form Builder OLE functions and procedures.

VBX	The VBX package contains Form Builder VBX functions and procedures.

Standard	The Standard package contains PL/SQL procedures and functions.

Note:  PL/SQL also offers  some supplied packages, and those procedures can be called from within PL/SQL code in a Forms application.  However, any such procedure with a name beginning DBMS_ is available only on the server (not on the client).


Query processing

Each data block has an associated data source. Action by the application or by the end user can cause Form Builder to issue a query to the data source. The following paragraphs describe the way Form Builder constructs and processes queries.

Properties of the data block and of its base table items define the SQL SELECT statement that Form Builder executes in the absence of additional commands. Form Builder sets most of these properties automatically. The application designer can set the following properties:

•	WHERE Clause.

•	ORDER BY Clause.

•	Copy Value from Item.

The application can also use built-ins to set properties at runtime.

At runtime, end users can initiate queries by a two-step process:

1	Place the form into Enter Query mode and enter query-by-example conditions in fields. This creates an example record. By typing a colon in a field, the end user can cause Form Builder to open the Query Where dialog box, allowing the end user to specify conditions that are too complex to specify by entering values into fields. This can include specifying an ORDER BY clause.

2	Direct Form Builder to execute the query using the example record.

The application can modify the example record that the end user creates, or it can create an example record without end user action. Form Builder combines the example record with the previously established block properties to produce the query it issues to the database.

Form Builder performs the following steps to create a SELECT statement to issue to the database:

1	Build a SELECT statement using column names that correspond to the base table items in the block.

2	Add a WHERE clause built by ANDing the WHERE Clause block property with additional WHERE conditions derived from the example record. For example, if the end user types the value 10 into the DEPTNO field, Form Builder adds the additional condition DEPTNO=10 to the WHERE clause. If any of the base table items in the block has a non-null value for its Copy Value from Item property, Form Builder incorporates this into the WHERE clause.

3	Add an ORDER BY clause by taking the ORDER BY clause from the example record. If the example record does not contain an ORDER BY clause, use the contents of the ORDER BY Clause block property.

Form Builder reinitializes the example record whenever a program statement, menu selection, or function key causes Form Builder to execute any of the ENTER_QUERY, EXECUTE_QUERY, or COUNT_QUERY built-ins or to enter one of the corresponding interactive modes.

Designers can assign values to items in a PRE-QUERY trigger. Note that changes made to the SELECT statement by a PRE-QUERY trigger override values entered by an end user in Enter Query mode. This functionality allows the designer to screen illegal queries.

Query Where dialog box  End users can invoke the Query Where dialog box by entering a colon in a field in Enter Query mode. This allows them to supply values for the WHERE clause by entering query conditions, using pattern matching and relational operators.

Processing in Enter Query mode

When a form is in Enter Query mode, Form Builder modifies its processing rules as follows:

•	It does not perform validation.

•	It uses standard function key definitions (not those defined in key triggers).

•	It disables the following function keys:

Block Menu	Next Block
Clear Form/Rollback	Next Record
Commit	Next Set of Records
Down	Previous Block
Duplicate Item	Previous Record
Duplicate Record	Scroll Down
Insert Record	Scroll Up
Lock Record	Up


Initialization

Form Builder initializes a form by creating a null record in each block of the form. Each item of a null record is null. Form builder replaces the null record with an initialized record the first time it enters the block. At that time it gives initial values to some items. An item's Initial Value property specifies the item's initial value.

Note: If a trigger assigns a value to an item in a null record, the record is no longer null. Form Builder never assigns an initial value to any item in the record. For example, a PRE-FORM trigger fires while the form contains only null records. If it assigns a value to an item, it must ensure that all other items of the record receive appropriate initial values.

Special considerations apply to certain types of items.

Check boxes

The initial value determines whether the check box is initially checked or unchecked. You must specify a valid initial value unless one of the following is true:

•	The item's Mapping of Other Values property is set to Checked or Unchecked.

•	The value associated with Checked or Unchecked is Null.

Note: A check box in a null record appears unchecked.

List items

You must specify a valid initial value unless one of the following is true:

•	The item's Mapping of Other Values property has a non-null value.

•	The value associated with one of the list elements is Null.

Note: A list item in a null record appears blank.

Radio groups

You must specify a valid initial value unless one of the following is true:

•	The item's Mapping of Other Values property has a non-null value.

•	The value associated with one of the radio buttons in the group is Null.

Note: A radio group in a null record appears with no radio button selected.

Synchronized items

If items, say B and C, have their Synchronize with Item properties set to the name of another item, say A, then A, B, and C form a set of synchronized items. A is the master item of the set, and B and C are subordinate items. Synchronized items were called mirror items in earlier versions of Form Builder.

The items of a synchronized set share a common data value, but can have different item properties. Form Builder takes data-specific properties and triggers from the master item and ignores those properties and triggers for the subordinate items.

Form Builder initializes synchronized items from the master item's Initial Value property. Form Builder also uses the master item's ON-SEQUENCE-NUMBER trigger.

If the designer specifies an Initial Value property or an ON-SEQUENCE-NUMBER trigger for a subordinate item, Form Builder ignores them and issues a warning.

Form Builder ignores an item's Initial Value property if all of the following are true for the item (or an item synchronized with it):

•	The item is a check box, poplist (drop-down list), Tlist (Text list), or radio group.

•	The item has no element corresponding to the specified initial value.

•	The item's Mapping of Other Values property has a null value.


Validation

Form Builder validates an item by ensuring that the item conforms to the rules that pertain to it. Triggers can implement additional validation.

Validation unit

A form's Validation Unit property controls the granularity of validation in the form. The validation unit can be an item, record, block, or form. Most Form Builder applications validate at the item level.

When validation occurs

Form Builder performs validation when

•	Form Builder navigates out of the validation unit. This occurs when the end user presses certain function keys or clicks the mouse outside the validation unit, or a trigger executes certain built-ins.

•	A trigger invokes the ENTER built-in, or the end user presses  [Enter].

•	A trigger invokes the COMMIT_FORM built-in, or the end user presses [Commit]. In this case Form Builder validates the form regardless of the validation unit.

•	A trigger invokes the VALIDATE built-in.

Form Builder does not perform validation in Enter Query mode. This allows the end user to enter query criteria that Form Builder would find invalid.

How validation proceeds

Internally, Form Builder maintains a status for each item, record, block, and form. For purposes of validation, each potential validation unit has a validation status with one of two values:

•	Valid

•	Unvalidated

The Valid status means that Form Builder does not need to examine the validation unit. The Unvalidated status, a combination of states known internally as New and Changed, means that Form Builder needs to validate the items in the validation unit. The distinction between New and Changed appears only rarely in the validation process (see the note in the Record entry in the table that follows).

A third state occurs if validation fails, but in that case Form Builder does not proceed until the situation is corrected, so the failed status does not enter into the validation process.

Form Builder validates a validation unit according to one of the following processes:

Item	If the item's status is Valid, the process stops. If the status is Unvalidated, Form Builder performs standard validation checks, then fires the WHEN-VALIDATE-ITEM trigger.  (See, however, the Defer Required Enforcement property.)
Record	If the record's status is Valid, the process stops. If the status is Unvalidated, Form Builder validates each item in the record, then fires the WHEN-VALIDATE-RECORD trigger. Note:  if the validation is as a result of a call to the VALIDATE trigger and the record's internal status is New, the process stops.
Block	Form Builder validates all records in the block.
Form	Form Builder validates all blocks in the form.
Item validation status

Unvalidated  Form Builder sets the status of an item to Unvalidated when any of the following occurs:

•	Form Builder creates a record.

•	The end user types a value into the item, or a trigger causes a value to be stored into the item.

Note: Form Builder sets the status of the item to Unvalidated even if the new value is the same as the old value. For example, if an item with Valid status has the value 10 and the end user types 10 into the item, Forms Builder sets the status of the item to Unvalidated.

•	When Form Builder duplicates a record (in response to the  DUPLICATE_RECORD built-in or the [Duplicate Record] key), any item that has Unvalidated status in the original has Unvalidated status in the duplicate.

Valid  Form Builder sets the status of an item to Valid in the following cases:

•	When Form Builder successfully validates an item, it sets the item's status to Valid, even if validation changes the item's value (through a WHEN-VALIDATE-ITEM, WHEN-VALIDATE-RECORD, or POST-CHANGE trigger). Form Builder does not re-validate the changed value.

Caution: This behavior avoids validation loops, but a trigger error can cause Form Builder to commit an invalid value to the database.

•	When Form Builder fetches records from the database, it sets their status to Valid, even if a Post-Change trigger that fires during the fetch changes item values.

•	When Form Builder successfully commits data to the database, it sets the status of all items in the form to Valid. Form Builder does not validate changes caused by triggers that fire during the commit transaction.

Note: See Changing Data During Commit Processing for exceptions to this rule.

•	When Form Builder duplicates a record (in response to the  DUPLICATE_RECORD built-in or the [Duplicate Record] key), any item that has Valid status in the original has Valid status in the duplicate.

Record validation status

Each record has a validation status of Unvalidated or Valid.

Note: a record's validation status is not equivalent to the value of the SYSTEM.RECORD_STATUS system variable.

Unvalidated  Form Builder sets the status of a record to Unvalidated in the following cases:

•	When Form Builder creates a record, it sets its status to Unvalidated.

•	When Form Builder sets the status of an item in the record to Unvalidated, it sets the status of the record to Unvalidated.

•	When Form Builder duplicates a record (in response to the  DUPLICATE_RECORD built-in or the [Duplicate Record] key), it sets the status of the duplicate record to Unvalidated.

Valid  Form Builder sets the status of a record to Valid in the following cases:

•	When Form Builder validates a record, it validates each item that does not already have a status of Valid. If all items have Valid status at the completion of this process, and if the WHEN-VALIDATE-RECORD trigger, if any, returns without raising the Form_Trigger_Failure exception, Form Builder sets the status of the record to Valid.

•	Form Builder sets to Valid the status of records fetched from the database.

•	When Form Builder successfully commits data to the database, it sets the status of each record in the form to Valid. Form Builder does not validate changes caused by triggers that fire during the commit transaction.

Note: See Changing Data During Commit Processing for exceptions to this rule.

•	When Form Builder (in response to the DUPLICATE_RECORD built-in or the [Duplicate Record] key) duplicates a record that has Valid status, it sets the status of the duplicate record to Valid.

Standard validation checks

Form Builder uses the requirements specified in the Data and List of Values (LOV) sections of the property palette to validate an item.

Validation sequence for text items

For text items, Form Builder performs one of the following sequences of validation steps, depending on whether the item’s value is null or not-null. If the text item fails a validation step, Form Builder notes the failure and omits the subsequent validation steps.

When the item’s value is null:

1	If the item's Required property has a setting of Yes, the item fails validation -- unless item-level validation is occurring and one of the following is true:

•	The form’s Defer Required Enforcement property has the setting Yes or 4.5.  (For a discussion of validation behavior in these cases, see Defer Required Enforcement property.)

•	The item instance does not allow end-user update.

Under either of the above exceptional conditions, Form Builder defers validating the null item until record-level validation.  (Note that if the item instance does not allow end-user update, validation is deferred even if Defer Required Enforcement is set to No.)

2	If the item's Required property has a setting of No, then the WHEN-VALIDATE-ITEM trigger is fired. If the trigger raises the Form_Trigger_Failure exception, the item fails this validation step.

When the item’s value is not null:

1	Check data type. If the value does not match the item's data type, the item fails this validation step.

Form Builder tries to convert a user-entered value to the item's data type.

If the item has a format mask, Form Builder uses it. If the item has no format mask and its data type is DATE or DATETIME, Form Builder uses the input format mask derived at Form Builder startup.

If the item has no format mask and is of data type NUMBER or ALPHA, Form Builder checks for a valid numeric or alphabetic text string.

2	Check length. If the value does not match the item's Fixed Length property, the item fails this validation step.

3	Check range. If the value does not match the item's Lowest Allowed Value and Highest Allowed Value properties, the item fails this validation step.

4	If the item's Use LOV for Validation property has the value Yes, verify that the value appears in the item's list of values.

5	Fire the POST-CHANGE trigger. If the trigger raises the Form_Trigger_Failure exception, the item fails this validation step.

6	Fire the WHEN-VALIDATE-ITEM trigger. If the trigger raises the Form_Trigger_Failure exception, the item fails this validation step.

Validation sequence for non-text items

If the item's Item Type property does not have the value Text Item, Form Builder follows the above sequence, but omits steps 3 through 5. It also omits step 2 unless the Item Type property has the value List Item and the List Style property has the value Combo Box.

Validation of synchronized items

If items, say B and C, have their Synchronize with Item properties set to the name of another item, say A, then A, B, and C form a set of synchronized items. A is the master item of the set, and B and C are subordinate items. Synchronized items were called mirror items in earlier versions of Form Builder.

The items of a synchronized set share a common data value, but can have different item properties. Form Builder takes data-specific properties and triggers from the master item and ignores those properties and triggers for the subordinate items.

When validating the value assigned to a synchronized set of items, Form Builder uses the following data-specific properties and triggers from the master item:

•	Required property

•	Highest Allowed Value property

•	Lowest Allowed Value property

•	Initial Value

•	POST-CHANGE trigger

•	WHEN-VALIDATE-ITEM trigger

If the subordinate item has values for these properties or specifications for these triggers, Form Builder ignores them and issues a warning.

Form Builder takes the remaining validation properties from the item through which the data value is set—either programmatically or by end user action. In particular, Form Builder uses the Fixed Length and Validate from List properties of that item.

The SYSTEM.TRIGGER_ITEM variable contains the name of the item through which the data value was set. This allows code in the POST-CHANGE or WHEN-VALIDATE-ITEM trigger to refer to properties of that item, even though these triggers are defined for the master item.

Form Builder considers a value that has not been set programmatically or by the end user to have been set by the master item, because that is the source Form Builder uses for the initial value.

During record-level validation, Form Builder validates the item through which the data value was set. If validation fails, Form Builder gives focus to that item, unless the item instance does not allow end user input. In that case, Form Builder tries to give focus to another item of the synchronized set that does allow end user input. If it fails to find one, it tries to give focus to an item of the set for which the Enabled property has the value Yes.


Commit processing

Commit processing is the way Form Builder attempts to make the data in the database identical to the data in the form. Form Builder's normal cycle of operation is:

1	Read records from the database.

2	Allow the end user to make tentative insertions, updates, and deletions. The tentative changes appear only in the form. The database remains unchanged.

3	Post changes to the database. Form Builder does all of its remaining processing and sends the data to the database. After posting the data, Form Builder can only roll back the changes (via the [Clear Form] function key or CLEAR_FORM built-in) or commit them.

4	Form Builder commits the posted changes. They become permanent changes to the database.

The term commit processing refers to steps 3 and 4 of the above cycle. Normally these steps occur together. In response to the [Commit] key or invocation of the COMMIT_FORM built-in, Form Builder firsts posts, then commits the data to the database.

Posting can occur separately before committing. End users cannot issue posting commands, but triggers can invoke the POST built-in.

Note: Form Builder does not support a commit that does not include the normal Form Builder commit processing.  For example, Form Builder does not support a commit issued from an Oracle Precompiler user exit or from a stored procedure.

Processing inserts, updates, and deletes

Posting consists of sending tentative changes from the form to the database. These are records that have been marked for insertion, update, or deletion since the last post. During posting, Form Builder processes inserts, updates, and deletes for all blocks in a form. Form Builder has a standard way to process these changes. Triggers provide a flexible mechanism for altering the standard behavior.

Insert  An insert is the pending insertion of a row in the database. Each insert has an associated SQL statement, which Form Builder executes when it posts the insert. The statement has the following form:

INSERT INTO table [(column, column, . . .)]
  VALUES (value, value, . . .);

table	The name of the base table for the current  block.
column	A column corresponding to a base table item. If an item is a derived column, it does not appear in the column clause.
value	The value to insert into the corresponding column.
Update  An update is the pending update of an existing row in the database. Each update has an associated SQL statement, which Form Builder executes when it posts the update. The statement has the following form:

UPDATE table
  SET (column=value, column=value, . . .)
  WHERE ROWID=rowid_value;

table	The name of the base table for the current  block.
column	A column corresponding to a base table item. If an item is a derived column, it does not appear in the column clause.
value	The value to update the corresponding column.
rowid_value	The ROWID value for the row Form Builder is updating.
Note:

•	The WHERE clause specifies only a ROWID value. This identifies the unique row that the database should update. Form Builder uses the ROWID construct only when the block's Key Mode property has the value Unique_Key (the default).

•	If an end user does not have update privileges for a column, and the block's Enforce Column Security property has the value Yes, Form Builder does not include the column in the UPDATE statement. Different end users can have different UPDATE statements, depending on their privileges, but the statement remains unchanged during an end user's Form Builder session.

Delete  A delete is the pending deletion of a row in the database. Each delete has an associated SQL statement, which Form Builder executes when it posts the delete. The statement has the following form:

DELETE FROM table WHERE ROWID=rowid_value;

table	The name of the base table for the current  block.
rowid_value	The ROWID value for the row Form Builder is deleting.
Note:  The WHERE clause specifies only a ROWID value. This identifies the unique row  that the database should delete. Form Builder does not use the ROWID value for non-Oracle data sources.

Caution: If a commit fails, the ROWID value may not have a null value. Use record status rather than the ROWID value to test for success or failure of the commit.

When commit processing occurs

Form Builder performs commit processing when

•	a trigger or the [Commit] key invokes the COMMIT_FORM built-in.

•	database items in the current block have changed since the last commit, and a trigger invokes the CLEAR_BLOCK  built-in (with the DO_COMMIT argument).

•	database items in the form have changed since the last commit, and a trigger invokes the CLEAR_FORM built-in (with the DO_COMMIT argument).

•	an end user answers Yes to the alert that asks

  Do you want to commit the changes you have made?

The alert appears as a result of any of the following:

•	database items in the current block have changed since the last commit, and any of the following events occurs:

CLEAR_BLOCK (with the ASK_COMMIT argument or with no argument)

COUNT_QUERY

ENTER_QUERY

EXECUTE_QUERY

NEW_FORM

•	database items in any block of the form have changed since the last commit, and any of the following events occurs:

CLEAR_FORM (with the ASK_COMMIT argument or with no argument)

Leave the Form

Note:  When a PL/SQL block issues a database commit from within Form Builder (via the SQL COMMIT statement), Form Builder commit processing occurs  as if the COMMIT_FORM built-in had been invoked.

Changing data during commit processing

Commit processing performs validation and can fire triggers. As a result, a commit event can change database items. For some triggers Form Builder attempts to commit those changes to the database during the current commit event.

Caution: Form Builder can commit unvalidated database changes made by the PRE-DELETE, PRE-INSERT, and PRE-UPDATE triggers.

For example, assume that a PRE-INSERT trigger selects a value into a base table item.

•	If Form Builder has not already processed the affected record's updates, it commits the changes during the current commit event without validating them.

•	If Form Builder has already processed the affected record's updates, it does not commit the changes, but it marks the records as having come from the database. Subsequently attempting to update the record before it is committed causes an error.

Caution: Form Builder can commit unvalidated database changes made by the POST-COMMIT, POST-DELETE, POST-INSERT, and POST-UPDATE triggers.

For example, assume that a POST-INSERT trigger selects a value into a base table item.

•	If the affected record is in a block that the commit has processed or is processing, Form Builder does not commit the changes during the current commit event. If the commit succeeds, Form Builder marks all items and records as Valid. This results in an error during subsequent processing.

•	If the affected record is in a block that the commit has not yet processed, Form Builder validates the changes and commits them during the current commit event.

Replacing standard commit processing

The ON-INSERT, ON-UPDATE, and ON-DELETE triggers replace standard commit processing.


Locking

  Related Topics

Oracle databases allow many end users to examine and modify data concurrently. Locks are the mechanism Oracle uses to keep concurrent modifications from interfering with each other. Locking tables and rows helps to maintain the consistency and integrity of the data. The Oracle Server Concepts Manual contains a complete explanation of Oracle locking methods and lock types.

Form Builder normally handles locking automatically, but designers and end users can exercise control over when and how it locks resources.

When an end user updates a row, Form Builder locks the row to prevent other users from updating the same row until the first user commits or rolls back changes. Unless the block's Locking Mode property has the value Delayed, Form Builder automatically tries to obtain exclusive row locks in response to end user events and trigger and transaction processing.

An exclusive row lock

•	prevents other users from updating or deleting the row or acquiring locks on that row.

•	allows other users to query the row.

Locks caused by end users  When an end user changes the value of a base table item or explicitly requests a lock on a record, Form Builder tries to place an exclusive lock on the corresponding row in the database. The exclusive row lock statement has the following form:

SELECT <all base table items in block>
  FROM <base table for the block>
  WHERE ROWID = <the unique row ID for the row to be locked>
  FOR UPDATE OF <all base table items in block>

The use of SELECT FOR UPDATE ensures that the data the end user changes while working in the form is identical to the corresponding data in the database.

Locks caused by triggers  When a trigger makes a change to a table through a Data Manipulation  Language (DML) command, the database tries to place an exclusive lock on the affected row. Form Builder does not manage locks caused by DML statements.

Form Builder tries to place an exclusive lock on the row corresponding to a fetched record when a trigger uses either of the following built-ins:

•	DELETE_RECORD

•	LOCK_RECORD

In general, any action (built-in invocation, PL/SLQ assignment, update operation) that modifies a value in a queried record causes Form Builder to request an exclusive lock.

Implicit and explicit row locking

There are two kinds of locking: implicit and explicit. They accomplish identical functions but happen at different times.

Implicit locking  All Form Builder applications use implicit locking, which means that end users never have to lock rows explicitly. Form Builder tries to place an exclusive lock on a row at a time determined by the block's Locking Mode property. This property takes one of three values: Automatic, Immediate, or Delayed.

For Oracle databases, Automatic and Immediate mean the same thing: Form Builder tries to place an exclusive lock on a row as soon as the end user begins to enter a change into an item in the corresponding record. The Automatic value directs Form Builder to detect and adjust to the database's capabilities -- with no need for changes to properties or trigger code.

If the block's Locking Mode property has the value Delayed, Form Builder does not lock rows until it is time to commit changes. At that time Form Builder looks for differences between the current values in the database and those returned by its original query. If it finds differences, it warns the end user and does not commit the changes.

Note:  When validating at the item level, Form Builder does not allow the change if it cannot acquire the lock. Otherwise Form Builder allows the change and tries to place an exclusive lock on the row during record validation.

Explicit locking  An end user or a trigger can explicitly ask Form Builder to lock a specific row immediately. From the default menu the end user selects Record [image] Lock to do this. A trigger requests a lock explicitly by invoking the LOCK_RECORD built-in. An ON-LOCK trigger must do this to obtain a lock explicitly, because its action replaces Form Builder's standard locking procedure.

Failing to obtain a lock

Form Builder tries to obtain a lock a fixed number of times, then asks whether it should retry. The end user can choose whether to keep waiting for the lock or to terminate the locking procedure.

If a user has a table exclusively locked, other users can query records from the table, but cannot update or delete those rows. This condition persists, without notice, until the resource becomes available. For this reason Oracle recommends minimizing the use of exclusive table locks.

When locks are released

The database releases locks when

•	the form commits successfully.

•	the form aborts.

•	Form Builder performs a full Form Builder rollback (not a rollback to a savepoint).

•	Form Builder disconnects from the database.

Form Builder maintains locks when it rolls back to a savepoint, as might happen after an unsuccessful commit. This allows the end user to make necessary changes and commit again.

Note:

•	If a trigger explicitly locks rows via the FOR_UPDATE  argument, it must query those rows again after a commit to obtain new locks.

•	Clearing a record or block does not release locks on the corresponding rows.

•	If you use a ROLLBACK or COMMIT statement in a trigger or a form-level procedure, Form Builder releases all locks. Form Builder interprets a ROLLBACK statement as a CLEAR_FORM built-in with no arguments. It interprets a COMMIT statement as a COMMIT_FORM built-in.

Replacing standard locking

The ON-LOCK trigger fires whenever Form Builder would normally try to obtain a lock. The code of the On-Lock trigger completely replaces Form Builder's standard locking procedure. Therefore, an ON-LOCK trigger usually includes a call to the LOCK_RECORD built-in.


What are properties?

 All Properties

Each object in a Form Builder application possesses characteristics known as properties.  An object's properties determine its appearance and functionality.


About setting and modifying properties

  Related Topics

Each property description includes a Set  heading that describes how you can set the property;  either declaratively in Form Builder (using the Property Palette), programmatically at runtime, or both.

Setting Properties Programmatically

To dynamically modify object properties programmatically, use the following Form Builder built-ins subprograms:

•	SET_APPLICATION_PROPERTY

•	SET_BLOCK_PROPERTY

•	SET_CANVAS_PROPERTY

•	SET_FORM_PROPERTY

•	SET_ITEM_PROPERTY

•	SET_ITEM_INSTANCE_PROPERTY

•	SET_LOV_PROPERTY

•	SET_MENU_ITEM_PROPERTY

•	SET_PARAMETER_ATTR

•	SET_RADIO_BUTTON_PROPERTY

•	SET_RECORD_PROPERTY

•	SET_RELATION_PROPERTY

•	SET_REPORT_OBJECT_PROPERTY

•	SET_TAB_PAGE_PROPERTY

•	SET_VIEW_PROPERTY

•	SET_WINDOW_PROPERTY

You can programmatically determine the settings of most properties by using the set of corresponding built-ins to get properties (e.g., GET_ITEM_PROPERTY).


Reading property descriptions

Description

The property descriptions follow a general pattern.  The property name is printed in a bold typeface and is followed by a brief description.

The headings in the following table are included for those properties to which they apply.

Heading	Description
Applies to	The object class or classes for which this property is meaningful.
Set	Where you can set the property:  in Form Builder (using the Property Palette), programmatically at runtime, or both.
Refer to Built-in	Built-in(s) you can use to set the property, if you can set the property programmatically.
Default	The default value of the property.
Required/Optional	Whether the property is required or optional.
Restrictions:	Any restrictions potentially affecting usage of the property.
Usage Notes	Any particular usage considerations you should keep in mind when using the property.


About Control property

 All Properties

Description

For ActiveX (OCX) control items in the layout editor. Provides a link to an about screen describing the current OCX control.

Applies to  ActiveX items

Set  Form Builder

Required/Optional  optional


Access Key property

 Restrictions	 All Properties

Description

Specifies the character that will be used as the access key, allowing the operator to select or execute an item by pressing a key combination, such as Alt-C.

The access key character is displayed with an underscore in the item label.

For example, assume that Push_Button1's label is "Commit" and the access key is defined as "c".  When the operator presses Alt-C (on Microsoft Windows), Form Builder executes the "Commit" command.

Applies to  button, radio button, and check box

Set  Form Builder

Default

No

Required/Optional  Optional

Usage Notes

•	When the operator initiates an action via an access key, any triggers associated with the action fire.  For example, assume that  Push_Button1 has an access key assigned to it.  Assume also that there is a When-Button-Pressed trigger associated with Push_Button1.  When the operator presses the access key, the When-Button-Pressed trigger fires for Push_Button1.


Access Key restrictions property
Access Key restrictions

•	Buttons with the Iconic property set to Yes cannot have an access key.


Alert Style property

 All Properties

Description

Specifies the alert style: caution, warning, or informational.  On GUI platforms, the alert style determines which bitmap icon is displayed in the alert.

Applies to  alert

Set  Form Builder

Default

warning


Alias property

 All Properties

Description

Establishes an alias for the table that the data block is associated with.

Applies to  table/columns associated with a data block

Set  Form Builder

Default

The Data Block wizard sets the Alias property to the first letter of the table name.  (For example, a table named DEPT would have a default alias of D.)

Required/Optional  required for Oracle8 tables that contain column objects or REFs

Usage Notes

For Oracle8 tables, SELECT statements that include column objects or REF columns must identify both the table name and its alias, and must qualify the column name by using that alias as a prefix.

For example:

     CREATE TYPE ADDRESS_TYPE AS OBJECT

                 (STREET   VARCHAR2(30),

                  CITY     VARCHAR2(30),

                  STATE    VARCHAR2(2));

      CREATE TABLE EMP

                  (EMPNO     NUMBER,

                   ADDRESS   ADDRESS_TYPE);

If the alias for this EMP table were E, then a SELECT statement would need to be qualified as follows:

      SELECT EMPNO, E.ADDRESS.CITY FROM EMP E;

In this case, the alias is E.  The column object ADDRESS.CITY is qualified with that alias, and the alias is also given after the table name.  (The column EMPNO, which is a normal relational column, requires no such qualification.)

In most situations, Form Builder will handle this alias naming for you.  It will establish an alias name at design-time, and then automatically use the qualified name at runtime when it fetches the data from the Oracle8 Server.  You only need to concern yourself with this alias naming if you are doing such things as coding a block WHERE clause.


Allow Expansion property

 All Properties

Description

Specifies whether Form Builder can automatically expand a frame when the contents of the frame extend beyond the frame's borders.

Applies to  frame

Set  Form Builder

Default

Yes

Required/Optional  required


Allow Empty Branches property

 All Properties

Description

Specifies whether branch nodes may exist with no children. If set to FALSE, branch nodes with no children will be converted to leaf nodes. If set to TRUE, an empty branch will be displayed as a collapsed node.

Applies to  hierarchical tree

Set Form Builder, programmatically

Default

False

Required/Optional  required


Allow Multi-Line Prompts property

 All Properties

Description

Specifies whether Form Builder can conserve space within a frame by splitting a prompt into multiple lines.  Prompts can only span two lines.

Applies to  frame

Set  Form Builder

Default

Yes

Required/Optional  required


Allow Start-Attached Prompts property

 All Properties

Description

Specifies whether space usage can be optimized when arranging items in tablular-style frames.

By default, this property is set to No, and prompts are attached to the item's top edge.  Setting Allow Start-Attached Prompts to Yes allows you to attach prompts to the item's start edge if there is enough space.

Applies to  frame

Set  Form Builder

Default

No

Required/Optional  required


Allow Top-Attached Prompts property

 All Properties

Description

Specifies whether space usage can be optimized when arranging items in form-style frames.

By default, this property is set to No, and prompts are attached to the item's start edge.  Setting Allow Top-Attached Prompts to Yes allows you to attach prompts to the item's top edge if there is enough space.

Applies to  frame

Set  Form Builder

Default

No

Required/Optional  required


Application Instance property

 Restrictions

Description

Specifies a reference to an instance of an application on the Microsoft Windows platform.  Other platforms always return the NULL value.

Applies to  form, block, or item

Refer to Built-in

GET_APPLICATION_PROPERTY

Default

NULL

Usage Notes

Specify the APPLICATION_INSTANCE property in GET_APPLICATION_PROPERTY to obtain the pointer value of an instance handle.  To use the instance handle when calling the Windows API, this pointer value must be converted with TO_PLS_INTEGER.


Application Instance restrictions property
Application Instance restrictions

Valid only on Microsoft Windows (Returns NULL on other platforms).


Arrow Style property

 All Properties

Description

Specifies the arrow style of the line as None, Start, End, Both ends, Middle to Start, or Middle to End.

Applies to  graphic line

Set  Form Builder

Default

None

Required/Optional  required


Associated Menus property

 Restrictions	    Related Topics	   All Properties

Description

Indicates the name of the individual menu in the module with which the parameter is associated.  When the operator navigates to a menu that has an associated parameter, Form Builder prompts the operator to enter a value in the Enter Parameter Values dialog box.

Applies to  menu parameter

Set  Form Builder

Required/Optional  optional


Associated Menus restrictions property
Associated Menus restrictions

Applies only to full-screen menus.


Audio Channels property

 All Properties

Description

Specifies the number of channels with which the sound item will be stored in the database:  either Automatic, Mono, or Stereo.

When you use the or WRITE_SOUND_FILE built-in subprogram to write sound data to the filesystem, use the channels parameter to control the number of channels with which the sound data will be written to the filesystem.

Applies to  sound item

Set  Form Builder, programmatically

Refer to Built-in

•	WRITE_SOUND_FILE

Default

Automatic

Required/Optional  required


Automatic Column Width property

  Related Topics	   All Properties

Description

Specifies whether LOV column width is set automatically.

•	When Automatic Column Width is set to Yes, the width of each column is set automatically to the greater of the two following settings:

•	the width specified by the Display Width property

or

•	the width necessary to display the column's title as specified in the Column Title property.

•	When Automatic Column Width is set to No, the width of each column is set to the value specified by the Display Width property.

Applies to  LOV

Set  Form Builder

Default

No


Automatic Display property

 All Properties

Description

Specifies whether Form Builder displays the LOV automatically when the operator or the application navigates into a text item to which the LOV is attached.

Applies to  LOV

Set  Form Builder

Default

No


Automatic Position property

 All Properties

Description

Specifies whether Form Builder automatically positions the LOV near the field from which it was invoked.

Applies to  LOV

Set  Form Builder

Default

No


Automatic Query property

 All Properties

Description

See Coordination.


Automatic Refresh property

 Restrictions	   All Properties

Description

Determines whether Form Builder re-executes the query to populate an LOV that is based on a query record group.  By default, Form Builder executes the query to populate an LOV's underlying record group whenever the LOV is invoked; that is, whenever the LOV is displayed, or whenever Form Builder validates a text item that has the Use LOV for Validation property set to Yes.

•	When Automatic Refresh is set to Yes (the default), Form Builder executes the query each time the LOV is invoked.  This behavior ensures that the LOV's underlying record group contains the most recent database values.

•	When Automatic Refresh is set to No, Form Builder executes the query only if the LOV's underlying record group is not flagged as having been populated by a query that occurred because this or any other LOV was invoked.  (Remember that more than one LOV can be based on the same record group.)  If the LOV's underlying record group has already been populated as a result of an LOV displaying, Form Builder does not re-execute the query, but instead displays the LOV using the records currently stored in the record group.

The Automatic Refresh property also determines how long records retrieved by the query remain stored in the underlying record group:

•	When Automatic Refresh is set to Yes, records returned by the query are stored in the underlying record group only as long as the LOV is needed.  Once the operator dismisses the LOV, or validation is completed, the record cache is destroyed.

•	When Automatic Refresh is set to No, records from the initial query remain stored in the LOV's underlying record group until they are removed or replaced.  You can manipulate these records programmatically.  For example, you can explicitly replace the records in an LOV's underlying record group by calling the POPULATE_GROUP built-in.  Other record group built-ins allow you to get and set the values of cells in a record group.

Applies to LOV

Set  Form Builder, programmatically

Refer to Built-in

•	GET_LOV_PROPERTY

•	SET_LOV_PROPERTY

Default

Yes

Usage Notes

•	When multiple LOVs are based on the same record group, it is usually appropriate to use the same Automatic Refresh setting for each one.  This is not, however, a strict requirement;  the following scenario describes refresh behavior when one LOV has Automatic Refresh set to Yes and another has Automatic Refresh set to No.

LOV1 and LOV2 are based on the same record group; LOV1 has Automatic Refresh set to Yes, LOV2 has Automatic Refresh set to No.  When LOV1 is invoked, Form Builder executes the query to populate the underlying record group.  When the operator dismisses LOV1, Form Builder destroys the record cache, and clears the record group.

When LOV2 is subsequently invoked, Form Builder again executes the query to populate the record group, even though LOV2 has Automatic Refresh set to No.  Because LOV2's underlying record group was cleared when LOV1 was dismissed, Form Builder does not consider it to have been queried by an LOV invocation, and so re-executes the query.

If, on the other hand, both LOV1 and LOV2 had Automatic Refresh set to No, Form Builder would execute the query when LOV1 was invoked, but would not re-execute the query for LOV2.  This is true even if the initial query returned no rows.

•	When Automatic Refresh is set to No, you can programmatically replace the rows that were returned by the initial query with POPULATE_GROUP.  Form Builder ignores this operation when deciding whether to re-execute the query.  (Form Builder looks only at the internal flag that indicates whether a query has occurred, not at the actual rows returned by that query.)


Automatic Refresh restrictions property
Automatic Refresh restrictions

Valid only for an LOV based on a query record group, rather than a static or non-query record group.


Automatic Select property

 All Properties

Description

Specifies what happens when an LOV has been invoked and the user reduces the list to a single choice when using auto-reduction or searching:

•	When Automatic Confirm is set to Yes, the LOV is dismissed automatically and column values from the single row are assigned to their corresponding return items.

•	When Automatic Confirm is set to No, the LOV remains displayed, giving the operator the option to explicitly select the remaining choice or dismiss the LOV.

Applies to  LOV

Set  Form Builder

Default

No


Automatic Skip properties

 All Properties

Automatic Skip (Item) property

Automatic Skip (LOV) property


Automatic Skip (Item) property

 Restrictions	    Related Topics	   All Properties

Description

Moves the cursor to the next navigable item when adding or changing data in the last character of the current item.  The last character is defined by the Maximum Length property.

Applies to  text item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Usage Notes

Combine the Automatic Skip property with the Fixed Length property to move the cursor to the next applicable text item when an operator enters the last required character.


Automatic Skip (Item) restrictions property
Automatic Skip (Item) restrictions

•	Valid only for single-line text items.

•	The Key-NXT-ITEM trigger does not fire when the cursor moves as a result of this property.  This behavior is consistent with the fact that the operator did not press [Next Item].


Automatic Skip (LOV) property

 Restrictions	   All Properties

Description

Moves the cursor to the next navigable item when the operator makes a selection from an LOV to a text item.  When Automatic Skip is set to No, the focus remains in the text item after the operator makes a selection from the LOV.

Applies to  LOV

Set  Form Builder, programmatically

Refer to Built-in

SET_ITEM_PROPERTY

Default

No


Automatic Skip (LOV) restrictions property
Automatic Skip (LOV) restrictions

•	The Key-NXT-ITEM trigger does not fire when the cursor moves as a result of this property.  This behavior is consistent with the fact that the operator did not press [Next Item].


Background_Color property

  Related Topics	   All Properties

Description

Specifies the color of the object’s background region.

Applies to  item, tab page, canvas, window, radio button

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY


Bevel property

 Restrictions	   All Properties

Description

Specifies the appearance of the object border, either RAISED, LOWERED, INSET, OUTSET, or NONE. Can also be set programmatically at the item instance level to indicate the property is unspecified at this level. That is, if you set this property programmatically at the item instance level using SET_ITEM_INSTANCE_PROPERTY, the border bevel is determined by the item-level value specified at design-time or by SET_ITEM_PROPERTY at runtime.

Applies to  chart item, image item, custom item, stacked canvases, text items (Microsoft Windows only)

Set  Form Builder, programmatically [BORDER_BEVEL]

Refer to Built-in

•	GET_ITEM_INSTANCE_PROPERTY

•	GET_ITEM_PROPERTY

•	SET_ITEM_INSTANCE_PROPERTY

•	SET_ITEM_PROPERTY

Default

LOWERED

Usage Notes

•	To create a scrolling window, the Bevel property should be set to RAISED or LOWERED.


Bevel restrictions property
Bevel restrictions

•	On window managers that do not support beveling, the RAISED, LOWERED, and NONE options are equivalent, and simply specify that the item should have a border.

•	If the item's Bevel property is set to None in Form Builder, you cannot set BORDER_BEVEL programmatically.

•	You cannot programmatically set BORDER_BEVEL to NONE.


Block Description property

 All Properties

Description

See Listed in Block Menu/Block Description.


Bottom Title properties

 All Properties

Bottom Title (Editor) property


Bottom Title (Editor) property

 All Properties

Description

Specifies a title of up to 72 characters to appear at the bottom of the editor window.

Applies to  editor

Set  Form Builder

Required/Optional  optional


Bounding Box Scalable property

 All Properties

Description

Specifies whether the text object's bounding box should be scaled when the text object is scaled.

Applies to  graphic text

Set  Form Builder

Default

Yes

Required/Optional  required


Builtin_Date_Format property

 All Properties

Description

This property establishes the format mask used in converting a date value to or from a string that is not potentially visible to the end user.  This format mask is most commonly used when executing a built-in subprogram.

Applies to application (global value)

Set  programmatically

Refer to Built-in

•	GET_APPLICATION_PROPERTY built-in

•	SET_APPLICATION_PROPERTY built-in

Required/Optional  optional.  However, it is STRONGLY RECOMMENDED that, for a  new application, you set this property to a format mask containing full century and time information.  It is also recommended that this format mask be the same as the one specified in the PLSQL_DATE_FORMAT property .

Default

As noted above, it is strongly recommended that you explicitly set this value for a new application.  However, if you do not, the default value used will depend on the context.

Forms first determines whether the item is a DATE2, DATE4, or DATETIME object, and then tries a series of format masks accordingly.  (These default masks are used for compatibility with prior releases.)

Object types are determined as shown in the following table:

Date object	Type
Item of datatype DATETIME	DATETIME
Item of datatype DATE:
…having a format mask that contains yyyy,                YYYY, rrrr, or RRRR	DATE4
…having a format mask that does not contain yyyy, YYYY, rrrr, or RRRR	DATE2
…not having a format mask, and its length (Maximum Length) is 10 or more	DATE4
…not having a format mask, and its length (Maximum Length) is 9 or less	DATE2
Parameter (as in :PARAMETER.myparam) of datatype DATE.  (Note that there are no DATETIME parameters, and that a parameter's Maximum Length property applies only to CHAR parameters.)	DATE2
LOV column of datatype DATE.  (Note that there are no DATETIME LOV columns.)	DATE2
Internal value of system variables CURRENT_DATETIME and EFFECTIVE_DATE	DATETIME

After determining the object type of the item to be converted, Forms uses one of the masks listed below.  There are two sets of masks -- one set for YY operations, and another set for RR operations.

For a date-to-string operation, only the first (primary) format mask is used.  For a string-to-date operation, Form Builder first tries the first/primary format mask.  If that conversion is unsuccessful, it tries the other (secondary) masks, in the order shown

For YY:

Object Type	Format Masks Used
DATE2	DD-MON-YY DD-MM-SYYYY HH24:MI:SS
DATE4	DD-MON-YYYY DD-MM-SYYYY HH24:MI:SS
DATETIME	DD-MON-YYYY HH24:MI:SS DD-MON-YYYY HH24:MI DD-MM-SYYYY HH24:MI:SS

For RR:

Object Type	Format Masks Used
DATE2	DD-MON-RR DD-MM-SYYYY HH24:MI:SS
DATE4	DD-MON-RRRR DD-MM-SYYYY HH24:MI:SS
DATETIME	DD-MON-RRRR HH24:MI:SS DD-MON-RRRR HH24:MI DD-MM-SYYYY HH24:MI:SS


Button 1 Label, Button 2 Label, Button 3 Label

  Related Topics	   All Properties

Description

Specifies the text labels for the three available alert buttons.

Applies to  alert

Set  Form Builder, programmatically

Refer to Built-in

SET_ALERT_BUTTON_PROPERTY

Required/Optional  At least one button must have a label.

Default

Button 1 Label: OK, Button 2 Label: Cancel, Button 3 Label: NULL


Calculation Mode property

  Related Topics	   All Properties

Description

Specifies the method of computing the value of a calculated item.  Valid values are:

None	The default.  Indicates the item is not a calculated item.

Formula	Indicates the item's value will be calculated as the result of a user-written formula. You must enter a single PL/SQL expression for an item's formula.  The expression can compute a value, and also can call a Form Builder or user-written subprogram.

Summary	Indicates the item's value will be calculated as the result of a summary operation on a single form item.  You must specify the summary type, and the item to be summarized.

Applies to  item

Set  Form Builder

Required/Optional  optional

Default

None


Calling_Form property

 All Properties

Description

Specifies the name of the calling form, as indicated by the form module Name property.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY

Default

NULL

Usage Notes

Only valid in a called form; that is, a form that was invoked from a calling form by the execution of the CALL_FORM built-in procedure.


Canvas property

 Restrictions	    Related Topics	   All Properties

Description

Specifies the canvas on which you want the item to be displayed.

Applies to  item

Set  Form Builder

Default

The item's current canvas assignment.

Required/Optional  optional

Usage Notes

•	Items are assigned to a specific canvas, which in turn is assigned to a specific window.

•	If you leave the Canvas property blank, the item is a NULL-canvas item; that is, an item that is not assigned to any canvas and so cannot be displayed in the Form Editor or at runtime.

•	If you change the name of a canvas in the Form Builder, Form Builder automatically updates the Canvas property for all items assigned to that canvas.


Canvas restrictions property
Canvas restrictions

The canvas specified must already exist in the form.


Canvas Type property

  Related Topics	   All Properties

Description

Specifies the type of canvas, either Content, Stacked, Vertical Toolbar Canvas, or Horizontal Toolbar Canvas. The type determines how the canvas is displayed in the window to which it is assigned, and determines which properties make sense for the canvas.

Content	The default. Specifies that the canvas should occupy the entire content area of the window to which it is assigned. Most canvases are content canvases.
Stacked	Specifies that the canvas should be displayed in its window at the same time as the window's content canvas. Stacked views are usually displayed programmatically and overlay some portion of the content view displayed in the same window.
Vertical Toolbar Canvas	Specifies that the canvas should be displayed as a vertical toolbar under the menu bar of the window. You can define iconic buttons, pop-lists, and other items on the toolbar as desired.
Horizontal Toolbar Canvas	Specifies that the canvas should be displayed as a horizontal toolbar at the left side of the window to which it is assigned.
Applies to  canvas

Set  Form Builder

Default

Content

Usage Notes

In the Property Palette, the properties listed under the Stacked View heading are valid only for a canvas with the Canvas Type property set to Stacked.


Cap Style property

 All Properties

Description

Specifies the cap style of the graphic object's edge as either Butt, Round, or Projecting.

Applies to  graphic physical

Set  Form Builder

Default

Butt

Required/Optional  required


Case Insensitive Query property

 Restrictions	    Related Topics	   All Properties

Description

Determines whether the operator can perform case-insensitive queries on the text item.

Applies to  text item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Usage Notes

Case-insensitive queries are optimized to take advantage of an index.  For example, assume you perform the following steps:

•	Create an index on the EMP table.

•	Set the Case Insensitive Query property on ENAME to Yes.

•	In Enter Query mode, enter the name 'BLAKE' into :ENAME.

•	Execute the query.

Form Builder constructs the following statement:

SELECT * FROM EMP WHERE UPPER(ENAME) = 'BLAKE' AND
   (ENAME LIKE 'Bl%' OR ENAME LIKE 'bL%' OR
   ENAME LIKE 'BL%' OR ENAME LIKE 'bl%');

The last part of the WHERE clause is performed first, making use of the index.  Once the database finds an entry that begins with bl, it checks the UPPER(ENAME) = 'BLAKE' part of the statement, and makes the exact match.


Case Insensitive Query restrictions property
Case Insensitive Query restrictions

If you set this property to Yes, queries may take longer to execute.


Case Restriction property

 Restrictions	 All Properties

Description

Specifies the case for text entered in the text item or menu substitution parameter. The allowable values for this property are as follows:

Value	Result
MIXED	Text appears as typed.
UPPER	Lower case text converted to upper case as it is typed.
LOWER	Upper case text converted to lower case as it is typed.

 Applies to  text item, menu substitution parameters

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM _PROPERTY


Case Restriction property restrictions
Case Restriction restrictions

•	Values assigned to the text item through triggers are not effected.

•	Case Restriction governs the display of all strings, whether they are entered by an operator or assigned programmatically, because Case Restriction serves as both an input and output format mask enforced by the user interface.

If you programmatically assign string values that conflict with the setting for Case Restriction, you will not see the effect in the text item because its display will be forced to conform to the current setting of Case Restriction.  This also means that if data that violates the Case Restriction setting is queried into or programmatically assigned to an item, then what the end user sees on the screen may differ from the internal value of that text item. For example, if Case Restriction is set to UPPER and the data retrieved from the data source is in mixed case, the form will display it in UPPER, but the actual value of the data will remain mixed case. However, If the data is subsequently modified in that field and the change is committed, the value of the data will change to upper case.


Character Cell WD/HT

  Related Topics	   All Properties

Description

Specifies the width and height of a character cell when the Coordinate System property is set to Real, rather than Character.  The width and height are expressed in the current real units (centimeters, inches, or points) indicated by the Real Unit property setting.

Applies to  form module

Set  Form Builder

Required/Optional  optional

Usage Notes

The character cell size is specified in the Coordinate System dialog in pixels but displayed in the Layout Editor in points.


Chart Type
Chart Type property

 All Properties

Description

Specifies the base chart type.  Available types of charts are Column, Pie, Bar, Table, Line, Scatter, Mixed, High-low, Double-Y, and Gantt.

Applies to  chart item

Set  Form Builder

Default

Column


Chart Subtype
Chart Subtype property

 All Properties

Description

Specifies a variation of the chart type.  Each variation is based on the specified chart type, with various properties set to achieve a different look.

Applies to  chart item

Set  Form Builder

Default

Column


Check Box Mapping of Other Values property

  Related Topics	   All Properties

Description

Specifies how any fetched or assigned value that is not one of the pre-defined "checked" or "unchecked" values should be interpreted.

Applies to  check box

Set  Form Builder

Default

NOT ALLOWED

Usage Notes

The following settings are valid for this property:

Setting	Description
Not Allowed	Any queried record that contains a value other than the user-defined checked and unchecked values is rejected and no error is raised.  Any attempt to assign an other value is disallowed.
Checked	Any value other than the user-defined unchecked value is interpreted as the checked state.
Unchecked	Any value other than the user-defined checked value is interpreted as the unchecked state.


Checked property

 Restrictions	    Related Topics	   All Properties

Description

Specifies the state of a check box- or radio-style menu item, either CHECKED or UNCHECKED.

Applies to  menu item

Set  programmatically

Refer to Built-in

•	GET_MENU_ITEM_PROPERTY

•	SET_MENU_ITEM_PROPERTY

Default

NULL

Required/Optional  optional


Checked restrictions property
Checked restrictions

Valid only for a menu item with the Menu Item Type property set to Check or Radio.


Clip Height property

 All Properties

Description

Specifies the height of a clipped (cropped) image in layout units.  If you specify a value less than the original image height, the image clips from the bottom.

Applies to  graphic image

Set  Form Builder

Default

original image height

Required/Optional  required


Clip Width property

 All Properties

Description

Specifies the width of a clipped (cropped) image in layout units.  If you specify a value less than the original image's width, the image clips from the right.

Applies to  graphic image

Set  Form Builder

Default

original image width

Required/Optional  required


Clip X Position property

 All Properties

Description

Specifies how much (in layout units) to clip off the left side of the image.

Applies to  graphic image

Set  Form Builder

Default

0

Required/Optional  required


Clip Y Position property

 All Properties

Description

Specifies how much (in layout units) to clip off the top of the image.

Applies to  graphic image

Set  Form Builder

Default

0

Required/Optional  required


Close Allowed property

 Restrictions	    Related Topics	   All Properties

Description

Specifies whether the window manager-specific Close command is enabled or disabled for a window. On GUI window managers, the Close command is available on the window's system menu, or by double-clicking the close box in the upper-left corner of the window.

Applies to  window

Set  Form Builder

Default

Yes

Usage Notes

•	Setting Close Allowed to Yes enables the Close command so that the Close Window event can be sent to Form Builder when the operator issues the Close command. However, to actually close the window in response to this event, you must write a When-Window-Closed trigger that explicitly closes the window. You can close a window programmatically by calling HIDE_WINDOW,  SET_WINDOW_PROPERTY, or EXIT_FORM.

•	On Microsoft Windows, if the operator closes the MDI parent window, Form Builder executes DO_KEY('Exit_Form') by default.


Close Allowed restrictions property
Close Allowed restrictions

Cannot be set for a root window. A root window is always closeable.


Closed property

 All Properties

Description

Specifies whether an arc is closed.

Applies to  graphic arc

Set  Form Builder

Default

Yes

Required/Optional  required


Column Mapping Properties property

 All Properties

Description

The Column Mapping Properties group includes Column Name, Column Title, Display Width, and Return Item.

Applies to  LOV

Set  Form Builder

Column Name

Specifies the names of the columns in an LOV.

Required/Optional  At least one column must be defined.

Default

The names of the columns in the underlying record group.

Usage Notes

The column names must adhere to object naming standards.

Column Title

Specifies the title that displays above the column currently selected in the column name list.

Display Width

Specifies the width for the column currently selected in the Column Name list.

Required/Optional  optional

Usage Notes

•	Set the Display Width property to the width in appropriate units (points, pixels, centimeters, inches, or characters as specified by the form's Coordinate System property) that you want Form Builder to reserve for the column in the LOV window. Column value truncation may occur if the Display Width is smaller than the width of the column value.  To avoid this situation, increase the Display Width for the column.

•	To make the column a hidden column, set Display Width to 0.  (You can specify a return item for a hidden column, just as you would for a displayed column.)

•	To add extra space between columns in the LOV window, set the Display Width wider than the column's default width. Note, however, that as an exception to this rule, you cannot increase the width between a NUMBER column and a non-NUMBER column by increasing the display width for the NUMBER column because LOVs display numbers right-justified. For example, assume that your LOV contains 3 columns: column 1 and 3 are type CHAR and column 2 is type NUMBER.  To increase the width between each column, increase the Display Width for columns 1 and 3.

Return Item

Specifies the name of the form item or variable to which Form Builder should assign the column's value whenever the operator selects an LOV record.

Default

NULL

Required/Optional  optional

Usage Notes

The Return Item can be any of the following entries:

•	form item (block_name.item_name)

•	form parameter (PARAMETER.my_parameter)

•	global parameter (GLOBAL.my_global)

Do not put a colon in front of the object name.


Column Name property

  Related Topics	   All Properties

Description

Establishes that an item corresponds to a column in the table associated with the data block.

Applies to  any item except button, chart, VBX (on 16-bit Microsoft Windows 3.x), or ActiveX (on 32-bit Windows) controls

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Default

Yes

Required/Optional  optional

Usage notes

When a selected item is from a column object or REF column in a table, Form Builder creates a compound name for it using dot notation:  ObjectColumnName.AttributeName.

For example, assume dept_type were an object type having attributes of dnum, dname, and dloc, and we had a column object called dept based on dept_type.  If we then selected dname to become an item in the data block, its column name property would become dept.dname.


Column Specifications property

 Restrictions	   All Properties

Description

The Column Specifications group of properties include Column Name, Column Value, Data Type, Length.

Applies to  record group

Set  Form Builder

Column Name

Specifies the names of the columns in a record group.

Required/Optional  At least one column must be defined.

Default

Names of the columns in the underlying record group.

Usage Notes

The column names must adhere to object naming standards.  There can be up to 255 columns in a record group.

Column Value

For a static record group, specifies the row values for the column currently selected in the Column Name list.

Default

NULL

Data Type

Specifies the data type for a given record group column.

Default

CHAR, except when you define a query record group, in which case, the data type of each column defaults to the data type of the corresponding database column.

Restrictions

The data type of a record group column can only be CHAR, NUMBER, or DATE.

Length

Specifies the length, in characters, of the record group column currently  selected in the Column Name list.

Default

For a query record group, the default is the width specified for the column in the database.  For a static record group, the default is 30.

Required/Optional  required


Column Specifications restrictions property
Column Specifications restrictions

•	You cannot reference an uninitialized variable or an item for this property, as that action constitutes a forward reference that Form Builder is unable to validate at design time.

•	The data type of the value must correspond to the data type of its associated column, as indicated in the Column Name property.


Column Title (LOV) property

 All Properties

Description

See Column Mapping Properties.


Column Value (Record Group) property

 All Properties

Description

See Column Specifications.


Command Text property

 Restrictions	    Related Topics	   All Properties

Description

Specifies menu item command text for the current menu item.  Valid values depend on the current setting of the menu item Command Type property.  For instance, when the command type is MENU, valid command text is the name of a submenu in the menu module.  When the command type is PL/SQL, valid command text is any valid PL/SQL statements.

Applies to  menu item

Set  Form Builder

Required/Optional  Required for all command types except NULL.


Command Text restrictions

The value can be up to 240 characters in length.


Command Type property

  Related Topics	   All Properties

Description

Specifies the nature of the menu item command.  This property determines how Form Builder interprets the text in the Command Text property.

Applies to  menu item

Set  Form Builder

Default

NULL

Required/Optional  required

Command Type	Description
Null	Specifies that the menu item does not issue a command.  The NULL command is required for separator menu items and optional for all other types of items.
Menu	Invokes a submenu.  Valid command text is the name of the submenu to be invoked.
PL/SQL	The default command type.  Executes a PL/SQL command. Valid command text is PL/SQL statements, including calls to built-in and user-named subprograms.   Note:  PL/SQL in a menu module cannot refer directly to the values of items, variables, or parameters in a form module.  Instead, use the built-ins NAME_IN and COPY to indirectly reference such values.
Plus*	Avoid. To invoke SQL*Plus, use the PL/SQL command type, and execute the HOST  built-in to launch SQL*Plus. (On Windows platforms, use plus80.exe as the executable name.)
Current Forms*	Avoid.  To invoke Form Builder, use the PL/SQL command type, and execute the HOST or RUN_PRODUCT built-ins to execute a valid Form Builder login.
Macro*	Avoid.  Executes a SQL*Menu macro.
*This command type is included for compatibility with previous versions.  Do not use this command type in new applications.


Comments property

 All Properties

Description

The Comments property specifies general information about any Form Builder object that you create.  Use comments to record information that will be useful to you or to other designers who develop, maintain, and debug your applications.

Applies to  all objects

Set  Form Builder

Required/Optional  optional


Communication Mode properties

 All Properties

Communication Mode (Chart) property

Communication Mode (Report) property


Communication Mode (Chart) property

 All Properties

Description

When calling Graphics Builder from Form Builder to create a chart, specifies the communication mode to be used as either Synchronous or Asynchronous. Synchronous specifies that control returns to the calling application only after the called product has finished. The end user cannot work in the form while the called product is running. Asynchronous specifies that control returns to the calling application immediately, even if the called application has not completed its display.

When data is returned from the called product, such as when updating a chart item, communication mode must be synchronous.

Applies to chart items

Set  Form Builder

Default

Synchronous

Required/Optional  required


Communication Mode (Report) property

 All Properties

Description

For report/form integration, specifies communication mode between the form and the report as either Synchronous or Asynchronous. Synchronous specifies that control returns to the calling application only after the called product has finished. The end user cannot work in the form while the called product is running. Asynchronous specifies that control returns to the calling application immediately, even if the called application has not completed its display.

When data is returned from the called product, communication mode must be synchronous.

Applies to  report integration

Set  Form Builder

Default

Synchronous

Required/Optional  required


Compress property

  Related Topics	   All Properties

Description

Specifies whether a sound object being read into a form from a file should be compressed when converting to the Oracle internal format.

Applies to  sound item

Set  Form Builder, programmatically

Refer to Built-in

•	WRITE_SOUND_FILE

Default

Automatic  (uses the compression setting of the sound data, if any).


Compression Quality property

  Related Topics	   All Properties

Description

Specifies whether an image object being read into a form from a file, or written to a file (with the WRITE_IMAGE_FILE built-in) should be compressed, and if so, to what degree.  Valid values are:

•	None

•	Minimum

•	Low

•	Medium

•	High

•	Maximum

Applies to  image item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

None


Conceal Data property

 Restrictions	   All Properties

Description

Hides characters that the operator types into the text item.  This setting is typically used for password protection.

The following list describes the allowable values for this property:

Yes	Disables the echoing back of data entered by the operator.

No	Enables echoing of data entered by the operator.

Applies to  text item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No


Conceal Data property restrictions
Conceal Data restrictions

Valid only for single-line text items.


Connect_String property

  Related Topics	   All Properties

Description

The Connect String property specifies the form operator's SQL*NET connect string.

If the current operator does not have a SQL*NET connect string, Form Builder returns NULL.

Applies to  application

Refer to Built-in

GET_APPLICATION_PROPERTY


Console Window property

  Related Topics	   All Properties

Description

Specifies the name of the window that should display the Form Builder console.  The console includes the status line and message line, and is displayed at the bottom of the window.

On Microsoft Windows, the console is always displayed on the MDI application window, rather than on any particular window in the form; however, you must still set this property to the name of a form window to indicate that you want the console to be displayed.

If you do not want a form to have a console, set this property to <Null>.

Applies to  form

Set  Form Builder

Default

WINDOW1

Required/Optional  optional


Control Help property

 All Properties

Description

For ActiveX (OCX) control items in the layout editor. Provides a link to the OCX help documentation about the current OCX control.

Applies to ActiveX control

Set  Form Builder

Default

More...

Required/Optional  optional


Control Properties property

 All Properties

Description

Activates the control-specific property sheet for the currently-selected OLE or ActiveX control.  The control must be visible in the Layout Editor in order to view its property sheet.

Applies to  OLE/ ActiveX control

Set  Form Builder


Coordinate System property

  Related Topics	   All Properties

Description

Specifies whether object size and position values should be interpreted as character cell values, or as real units (centimeters, inches, pixels, or points). The following settings are valid for this property:

Character	Sets the coordinate system to a character cell-based measurement.  The actual size and position of objects will depend on the size of a default character on your particular platform.

Real	Sets the coordinate system to the unit of measure specified by the Real Unit property (centimeters, inches, pixels, or points.)

Changing the coordinate system for the form changes the ruler units displayed on Form Editor rulers, but does not change the grid spacing and snap-points settings.

Applies to  form

Set  Form Builder

Default

Centimeter

Usage Notes

The coordinate system you select is enforced at design time and at runtime. For example, if you programmatically move a window with SET_WINDOW_PROPERTY, the position coordinates you pass to the built-in are interpreted in the current form coordinate units.

When you convert from one coordinate system to another, Form Builder automatically converts object size and position values that were specified declaratively at design time.  Loss of precision can occur when you convert to less precise units.

If portability is a concern, setting the Coordinate System to Character provides the most portable unit across platforms, but sets a coarse grid that reduces the ability to fine-tune the layout.  If your application runs in both character-mode and GUI, the decision about which coordinate system to use depends on which interface style you want to optimize.

If you want to optimize for GUIs, the Real setting provides maximum flexibility for proportional fonts, but may require some fine-tuning to avoid overlapping fields on the character-mode side.

If you want to optimize for character-mode, choose the Character setting.  This setting provides less flexibility for the proportional fonts used on GUIs, but lets you line up character cell boundaries exactly.

For this type of application...	Set Coordinate System to...
GUI only	Real: inches, centimeters, or points
Character-mode only	Character
Mixed character-mode and GUI:
Optimize for GUI	Real
Optimize for character-mode	Character


Coordination property

 Restrictions	    Related Topics	   All Properties

Description

Specifies how and when the population phase of block coordination should occur.  Specify the coordination desired by setting the Deferred and Automatic Query properties.  When you set these properties at design time, Form Builder creates or modifies the appropriate master-detail triggers to enforce the coordination setting you choose.

Applies to:

relation

Set:

Form Builder, programmatically

Refer to Built-in

•	GET_RELATION_PROPERTY

•	SET_RELATION_PROPERTY

Default

Immediate coordination (Deferred No, Automatic Query No)

Usage Notes

Whenever the current record in the master block changes at runtime (a coordination-causing event), Form Builder needs to populate the detail block with a new set of records.  You can specify exactly how and when that population should occur by setting this property to one of three valid settings:

Deferred=No,Automatic Query ignored	The default setting.  When a coordination-causing event occurs in the master block, the detail records are fetched immediately.
Deferred=Yes,  Automatic Query=Yes	When a coordination-causing event occurs, Form Builder defers fetching the associated detail records until the operator navigates to the detail block.
Deferred=Yes,  Automatic Query=No	When a coordination-causing event occurs, Form Builder defers fetching the associated detail records until the operator navigates to the detail block and explicitly executes a query.
Deferred=No,Automatic Query=Yes	Not a valid setting.


Coordination restrictions property
Coordination restrictions

The ability to set and get these properties programmatically is included only for applications that require a custom master-detail scheme. For a default master-detail relation created at design time, Form Builder generates the appropriate triggers to enforce coordination, and setting the coordination properties at runtime has no effect on the default trigger text.


Coordination_Status property

 All Properties

Description

For a block that is a detail block in a master-detail block relation, this property specifies the current coordination status of the block with respect to its master block(s).  This property is set to the value COORDINATED when the block is coordinated with all of its master blocks.  When the block is not coordinated with all of its master blocks, Coordination_Status is set to NON_COORDINATED.

Immediately after records are fetched to the detail block, the status of a detail block is COORDINATED.  When a different record becomes the current record in the master block, the status of the detail block again becomes NON_COORDINATED.

Applies to  relation

Set  programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Usage Notes

This property is included for designers who are programmatically enforcing a custom master-detail block coordination scheme.  Its use is not required when you are using Form Builder declarative master-detail coordination.


Copy Value from Item property

  Related Topics	   All Properties

Description

Specifies the source of the value that Form Builder uses to populate the item.  When you define a master-detail relation, Form Builder sets this property automatically on the foreign key item(s) in the detail block.  In such cases, the Copy Value from Item property names the primary key item in the master block whose value gets copied to the foreign key item in the detail block whenever a detail record is created or queried.

Applies to  all items except buttons, chart items, and image items

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Required/Optional  optional

Usage Notes

•	Specify this property in the form <block_name>.<block_item_name>.

•	Setting the Copy Value from Item property does not affect record status at runtime, because the copying occurs during default record processing.

•	To prevent operators from de-enforcing the foreign key relationship, set the Enabled property to No for the foreign key items.

•	To get the Copy Value from Item property programmatically with GET_ITEM_PROPERTY, use the constant ENFORCE_KEY.


Current Record Visual Attribute Group property

 All Properties

Description

Specifies the named visual attribute used when an item is part of the current record.

Applies to  form, block, item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Required/Optional  optional

Usage Notes

This property can be set at the form, block, or item level, or at any combination of levels.  If you specify named visual attributes at each level, the item-level attribute overrides all others, and the block-level overrides the form-level.

Note that if you define a form-level Current Record Visual Attribute, any toolbars in the form will be displayed using that Current Record Visual Attribute. You can avoid this by defining block-level Current Record Visual Attributes for the blocks that need them instead of defining them at the form level. If you wish to retain the form-level Current Record Visual Attribute, you can set the block-level Current Record Visual Attribute for the toolbar to something acceptable.

Current Record Visual Attribute is frequently used at the block level to display the current row in a multi-record block in a special color.  For example, if you define Vis_Att_Blue for the Emp block which displays four detail records, the current record will display as blue, because it contains the item that is part of the current record.

If you define an item-level Current Record Visual Attribute, you can display a pre-determined item in a special color when it is part of the current record, but you cannot dynamically highlight the current item, as the input focus changes.  For example, if you set the Current Record Visual Attribute for EmpNo to Vis_Att_Green, the EmpNo item in the current record would display as green. When the input focus moved to EmpName, EmpNo would still be green and EmpName would not change.


Current_Form property

  Related Topics	   All Properties

Description

Specifies the name of the .FMX file of the form currently being executed.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY

Usage Notes

Get the value of this property to determine the name of the file the current form came from in an application that has multiple called forms.

Current_Form at the application level corresponds to File_Name at the form level.  File_Name is gettable with GET_FORM_PROPERTY.


Current_Form_Name property

  Related Topics	   All Properties

Description

Specifies the name of the current form, as indicated by the form module Name property.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY

Usage Notes

Get the value of this property to determine the name of the current form in an application that has multiple called forms.

Current_Form_Name at the application level corresponds to Form_Name at the form level.  Form_Name is gettable with GET_FORM_PROPERTY.


Current_Record property

 All Properties

Description

Specifies the number of the current record in the block's list of records.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY


Current_Row_Background_Color property

  Related Topics	   All Properties

Description

Specifies the color of the object’s background region.

Applies to  item, block, form

Set  Programmatically

Default

NULL

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY


Current_Row_Fill_Pattern property

  Related Topics	   All Properties

Description

Specifies the pattern to be used for the object’s fill region. Patterns are rendered in the two colors specified by Background_Color and Foreground_Color.

Applies to  item, block, form

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY


Current_Row_Font_Name property

  Related Topics	   All Properties

Description

Specifies the font family, or typeface, to be used for text in the object. The list of fonts available is system-dependent.

Applies to  item, block, form

Set  Programmatically

Default

NULL

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY


Current_Row_Font_Size property

  Related Topics	   All Properties

Description

Specifes the size of the font in points.

Applies to  item, block, form

Set  Programmatically

Default

NULL

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY


Current_Row_Font_Spacing property

  Related Topics	   All Properties

Description

Specifies the width of the font (i.e., the amount of space between characters, or kerning).

Applies to  item, block, form

Set  Programmatically

Default

NULL

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY


Current_Row_Font_Style property

  Related Topics	   All Properties

Description

Specifies the style of the font.

Applies to  item, block, form

Set  Programmatically

Default

NULL

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY


Current_Row_Font_Weight property

  Related Topics	   All Properties

Description

Specifies the weight of the font.

Applies to  item, block, form

Set  Programmatically

Default

NULL

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY


Current_Row_Foreground_Color property

  Related Topics	   All Properties

Description

Specifies the color of the object’s foreground region. For items, defines the color of the text displayed in the item.

Applies to  item, block, form

Set  Programmatically

Default

NULL

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY


Current_Row_White_On_Black property

  Related Topics	   All Properties

Description

Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

Applies to  item, block, form

Set  Programmatically

Default

NULL

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY


Cursor Mode property

 All Properties

Note:

In Release 5.0 and later, cursor mode is handled automatically by Form Builder.  This property is now obsolete, and should not be used.  In particular, cursor mode should never be set to Close.  The following information is provided only for historical and maintenance purposes.

Description

Defines the cursor state across transactions.  The cursor refers to the memory work area in which SQL statements are executed.  For more information on cursors, refer to the ORACLE RDBMS Database Administrator's Guide.  This property is useful for applications running against a non-ORACLE data source.

The following settings are valid for the Cursor_Mode property:

Setting	Description
Open (the default)	Specifies that cursors should remain open across transactions.
Close	Specifies that cursors should be closed when a commit is issued.

Applies to  form

Set   programmatically

Refer to Built-in

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY

Default

OPEN_AT_COMMIT

Usage Notes

•	Because ORACLE allows the database state to be maintained across transactions, Form Builder allows cursors to remain open across COMMIT operations.  This reduces overhead for subsequent execution of the same SQL statement because the cursor does not need to be re-opened and the SQL statement does not always need to be re-parsed.

•	Some non-ORACLE databases do not allow database state to be maintained across transactions.  Therefore, you can specify the CLOSE_AT_COMMIT parameter of the Cursor_Mode option to satisfy those requirements.

•	Closing cursors at commit time and re-opening them at execute time can degrade performance in three areas:

•	during the COMMIT operation

•	during future execution of other SQL statements against the same records

•	during execution of queries

•	Form Builder does not explicitly close cursors following commit processing if you set the property to CLOSE_AT_COMMIT.  This setting is primarily a hint to Form Builder that the cursor state can be undefined after a commit.

Form Builder maintains a transaction ID during all types of transaction processing. For instance, Form Builder increments the transaction ID each time it opens a cursor, performs a commit, or performs a rollback.

When Form Builder attempts to re-execute a cursor, it checks the transaction ID.  If it is not the current transaction ID, then Form Builder opens, parses, and executes a new cursor.  Only the last transaction ID is maintained.

•	If you query, change data, then commit, Form Builder increments the transaction ID.  Subsequent fetches do not re-open and execute the cursor, for the following reasons:

•	Form Builder does not attempt to handle read consistency issues, nor does it handle re-positioning in the cursor.

•	Form Builder expects ORACLE or the connect to return an end-of-fetch error when trying to fetch from an implicitly closed cursor.

On a subsequent execution of the query, Form Builder opens a new cursor.

•	When using this property in conjunction with transactional triggers, you, the designer, must manage your cursors.  For example, you might want to close any open queries on the block whenever you perform a commit.


Cursor_Style property

 All Properties

Description

Specifies the mouse cursor style.  Use this property to dynamically change the shape of the cursor.

The following settings are valid for the Cursor Style property:

Setting	Description

BUSY	Displays a GUI-specific busy symbol.

CROSSHAIR	Displays a GUI-specific crosshair symbol.

DEFAULT	Displays a GUI-specific arrow symbol.

HELP	Displays a GUI-specific help symbol.

INSERTION	Displays a GUI-specific insertion symbol.

Applies to  application

Set  Programmatically

Refer to Built-in

•	GET_APPLICATION_PROPERTY

•	SET_APPLICATION_PROPERTY

Default

Arrow symbol

Usage Notes

When Form Builder is performing a long operation, it displays the "Working" message and replaces any cursor style specified with the BUSY cursor.

For example, if you set the cursor style to "HELP" and the operator executes a large query, the HELP cursor is replaced by the BUSY cursor while the query is being executed.  After Form Builder executes the query, the BUSY cursor reverts to the HELP cursor.

Note, however, if you change the cursor style while Form Builder is displaying the BUSY cursor, the cursor style changes immediately rather than waiting for Form Builder to complete the operation before changing cursor styles.


Custom Spacing property

 All Properties

Description

Specifies the custom spacing for the text object in layout units.

Applies to  graphic text

Set  Form Builder

Default

0

Required/Optional  required


Dash Style property

 All Properties

Description

Specifies the dash style of the graphic object's edge as Solid, Dotted, Dashed, Dash Dot, Double Dot, Long dash, or dash Double Dot.

Applies to  graphic physical

Set  Form Builder

Default

Solid

Required/Optional  required


Data Block Description property

 All Properties

Description

Describes the data block.

Applies to  data block database

Set  Form Builder

Default

Null

Required/Optional  optional


Data Query property

 All Properties

Description

Specifies the query-based data source.

Applies to  hierarchical tree

Set Form Builder, programmatically

Refer to Built-in

ADD_TREE_DATA

Default

NULL

Required/Optional  optional


Data Source Data Block properties

 All Properties

Data Source Data Block (Chart) property

Data Source Data Block (Report) property


Data Source Data Block (Chart) property

  Related Topics	 All Properties

Description

When running Graphics Builder from Form Builder to create a chart, specifies the data block to be used as the source of a chart item.

Applies to chart item

Set  Form Builder

Default

Null

Required/Optional  optional


Data Source Data Block (Report) property

  Related Topics	 All Properties

Description

For report/form integration, specifies the data block to be used as the source of the report as either Null or a block name.

Applies to  report integration

Set  Form Builder

Default

Null

Required/Optional  optional


Data Source X Axis property

  Related Topics	 All Properties

Description

Specifies the data block column to be used as the basis of the X axis of a chart item.

Applies to chart item

Set  Form Builder


Data Source Y Axis property

  Related Topics	 All Properties

Description

Specifies the data block column to be used as the basis of the Y axis of a chart item.

Applies to chart item

Set  Form Builder


Data Type property

  Related Topics	 All Properties

Description

Specifies what kinds of values Form Builder allows as input and how Form Builder displays those values.

Applies to  check box, display item, list item, radio group, text item, custom item, and form parameter (form parameter supports CHAR, DATE, DATETIME, and NUMBER only)

Note:  All data types do not apply to each item type.

Set  Form Builder

Usage Notes

•	In Form Builder 6.0 and later, it is recommended that you use only the standard data types CHAR, DATE, DATETIME, and NUMBER for data.  These data types are based on native ORACLE data types, and offer better performance and application portability.  The other data types are valid only for text items, and are included primarily for compatibility with previous versions.  You can achieve the same formatting characteristics by using a standard data type with an appropriate format mask.

•	The data type of a base table item must be compatible with the data type of the corresponding database column. Use the CHAR data type for items that correspond to ORACLE VARCHAR2 database columns.

•	Do not create items that correspond to database CHAR columns if those items will be used in queries or as the join condition for a master-detail relation; use VARCHAR2 database columns instead.

•	Form Builder will perform the following actions on items, as appropriate:

remove any trailing blanks

change the item to NULL if it consists of all blanks

remove leading zeros if the data type is NUMBER, INT, MONEY, RINT, RMONEY, or RNUMBER (unless the item's format mask permits leading zeros)

•	The form parameter Data Type property supports the data types  CHAR, DATE, and NUMBER.

ALPHA

Contains any combination of letters (upper and/or lower case).

Default	Null
Example	"Employee", "SMITH"
CHAR

Supports VARCHAR2 up to 2000 characters.  Contains any combination of the following characters:

•	Letters (upper and/or lower case)

•	Digits

•	Blank spaces

•	Special characters ($, #, @, and _)

Default	Null
Example	"100 Main Street", "CHAR_EXAMPLE_2"
DATE

Contains a valid date.  You can display a DATE item in any other valid format by changing the item's format mask.

Default	DD-MON-YY
Restrictions	Refers to a DATE column in the database and is processed as a true date, not a character string.
	The DATE data type is not intended to store a time component.
Example	01-JAN-92
DATETIME

Contains a valid date and time.

Default	DD-MON-YY HH24:MI[:SS]
Restrictions	Refers to a DATE column in the database and is processed as a true date, not a character string.
	The DATETIME data type contains a four digit year.  If the year input to a DATETIME data type is two digits, the year is interpreted as 00YY.
Example	31-DEC-88 23:59:59
EDATE

Contains a valid European date.

Default	DD/MM/YY
Restrictions	V3 data type.
	Must refer to a NUMBER column in the database.
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the DATE data type.
	Apply a format mask to produce the European date format.
	Reference a DATE column in the database, rather than a NUMBER column.
Example	23/10/92 (October 23, 1992)
	01/06/93 (June 1, 1993)
INT

Contains any integer (signed or unsigned whole number).

Default	0
Example	1, 100, -1000
JDATE

Contains a valid Julian date.

Default	MM/DD/YY
Restrictions	V3 data type.
	Must refer to a NUMBER column in the database.
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the DATE data type.
	Apply a format mask to produce the Julian date format.
	Reference a DATE column in the database, rather than a NUMBER column.
Example	10/23/92 (October 23, 1992)
	06/01/93 (June 1, 1993)
LONG

Contains any combination of characters.  Stored in ORACLE as variable-length character strings.  Forms allows a LONG field to be up to 65,534 bytes.  However, PL/SQL has a maximum of 32,760 bytes.  If a LONG variable is to be used as a bind variable in a PL/SQL statement, it cannot exceed that 32,760 byte limit.

Default	Null
Restrictions	Not allowed as a reference in the WHERE or ORDER BY clauses of any SELECT statement.
	LONG items are not queryable in Enter Query mode.
MONEY

Contains a signed or unsigned number to represent a sum of money.

Restrictions	V3 data type
	Included for backward compatibility.  Instead, use a format mask with a number to produce the same result.
Example	10.95, 0.99, -15.47
NUMBER

Contains fixed or floating point numbers, in the range of 1.0x10-129 to 9.99x10124, with one or more of the following characteristics:

•	signed

•	unsigned

•	containing a decimal point

•	in regular notation

•	in scientific notation

•	up to 38 digits of precision

NUMBER items refer to NUMBER or FLOAT columns in the database, and Form Builder processes their values as true numbers (not character strings).

Default	0
Restrictions	Commas cannot be entered into a number item (e.g., 99,999).  Use a format mask instead.
Example	-1, 1, 1.01, 10.001, 1.85E3
RINT

Displays integer values as right-justified.

Restrictions	V3 data type
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the NUMBER data type.
	Apply a format mask such as 999 to produce a right-justified number.
RMONEY

Displays MONEY values as right-justified.

Restrictions	V3 data type
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the NUMBER data type
	Apply a format mask such as $999.99 to produce a right-justified number.
RNUMBER

Displays NUMBER values as right-justified.

Restrictions	V3 data type
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the NUMBER data type.
	Apply a format mask such as 999.999 to produce a right-justified number.
TIME

Contains numbers and colons that refer to NUMBER columns in the database.

Default	HH24:MI[:SS]
Restrictions	V3 data type
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the DATETIME data type.
	Apply a format mask to produce only the time.
	Not allowed as a reference to DATE columns in the database.
Example	:10:23:05
	21:07:13


Data Type (Record Group) property

Description

See Column Specifications.


Database Block property

 All Properties

Description

Specifies that the block is based on any of the following block data source types:  table, procedure, transactional trigger, or sub-query.  (Table source includes relational tables, object tables, and relational tables containing column objects or REFs.)  Also specifies that the block is not a control block.  When the Database Block property is set to No, form builder grays-out and ignores the datasource properties for the block.

Applies to  block

Set  Form Builder

Default

Yes

Required/Optional  required


Database_Value property

 All Properties

Description

For a base table item that is part of a database record whose status is QUERY or UPDATE, Database_Value returns the value that was originally fetched from the database. When a fetched value has been updated and then subsequently committed, Database_Value returns the committed value.

For a control item that is part of a database record, Database_Value returns the value that was originally assigned to the item when the record was fetched from the database.

For any item that is part of a non-database record whose status is NEW or INSERT, Database_Value returns the current value of the item.

Note:  You can examine the Database_Value property to determine what the value of an item in a database record was before it was modified by the end user.

Note:  You can examine the SYSTEM.RECORD_STATUS system variable or use the GET_RECORD_PROPERTY built-in to determine if a record has been queried from the database.

Applies to:

all items except buttons, chart items, and image items

Set  not settable

Refer to Built-in:

GET_ITEM_PROPERTY


Datasource property

 All Properties

Description

Specifies the name of the database currently in use.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY

Default

ORACLE

Usage Notes

This property is used in connection with non-Oracle data sources.  It returns the name of the database for connections established by Form Builder, not for connections established by On-Logon triggers. The following settings are valid for this property:

•	ORACLE

•	DB2

•	NULL (Unspecified database, or not logged on)

•	NONSTOP

•	TERADATA

•	NCR/3600

•	NCR/3700

•	SQLSERVER


Date_Format_Compatibility_Mode property

 All Properties

Description

Establishes what date format masks will be used in certain conversion operations.  A setting of 4.5 chooses the types of conversions done in Release 4.5 and earlier.  A setting of 5.0  chooses the types of conversions done in Release 5.0 and later.

The conversion operations and masks affected by this choice are noted in About format masks for dates

Applies to  application

Set  settable from within Form Builder.

Refer to Built-in

GET_APPLICATION_PROPERTY

SET_APPLICATION_PROPERTY

Default

5.0

Required/Optional  required

Usage Notes

If this Date_Format_Compatibility_Mode property is set to 4.5 but the  Runtime_Compatibility_Mode property is set to 5.0, the 5.0 value will override the Date_Format_Compatibility_Mode setting.


Default Alert Button property

 All Properties

Description

Specifies which of three possible alert buttons is to be the default alert button.  The default alert button is normally bordered uniquely or highlighted in some specific manner to visually distinguish it from other buttons.

Applies to  alert

Set  Form Builder

Default

Button 1

Required/Optional  optional


Default Button property

 All Properties

Description

Specifies that the button should be identified as the default button.  At runtime, the end user can invoke the default button by pressing [Select] if focus is within the window that contains the default button.

On some window managers, the default button is bordered or highlighted in a unique fashion to distinguish it from other buttons in the interface.

Applies to  button

Set  Form Builder

Default

No

Required/Optional  optional


Default Font Scaling property

 Restrictions	    Related Topics	 All Properties

Description

Specifies that the font indicated for use in a form defaults to the relative character scale of the display device in use.

Applies to  form module

Set  Form Builder

Default

Yes


Default Font Scaling restrictions

Valid only when the Coordinate System property is set to Character Cell.


Deferred property

 All Properties

Description

See Coordination.


Defer Required Enforcement property

  Related Topics	 All Properties

Description

For an item that has the Required property set to true, it specifies whether Form Builder should defer enforcement of the Required item attribute until the record is validated.

There are three settings for this property:  Yes, 4.5, and No.

Applies to  form

Set  Form Builder, programmatically

Refer to Built-in

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY

Default

No

Usage Notes

This property applies only when item-level validation is in effect. By default, when an item has Required set to true, Form Builder will not allow navigation out of the item until a valid value is entered.  This behavior will be in effect if you set Defer Required Enforcement to No.  (An exception is made when the item instance does not allow end-user update; in this unusual case, a Defer Required Enforcement setting of No is ignored and item-level validation does not take place.)

If you set Defer Required Enforcement to Yes (PROPERTY_TRUE for runtime) or to 4.5 (PROPERTY_4_5 for runtime), you allow the end user to move freely among the items in the record, even if they are null, postponing enforcement of the Required attribute until validation occurs at the record level.

When Defer Required Enforcement is set to Yes, null-valued Required items are not validated when navigated out of. That is, the WHEN-VALIDATE-ITEM trigger (if any) does not fire, and the item's Item Is Valid property is unchanged.  If the item value is still null when record-level validation occurs later, Form Builder will issue an error.

When Defer Required Enforcement is set to 4.5, null-valued Required items are not validated when navigated out of, and the item's Item Is Valid property is unchanged. However, the WHEN-VALIDATE-ITEM trigger (if any) does fire.  If it fails (raises Form_Trigger_Failure), the item is considered to have failed validation and Form Builder will issue an error.  If the trigger ends normally, processing continues normally.  If the item value is still null when record-level validation occurs later, Form Builder will issue an error at that time.

Setting a value of 4.5 for Defer Required Enforcement allows you to code logic in a WHEN-VALIDATE-ITEM trigger that will be executed immediately whenever the end-user changes the item’s value (even to null) and then navigates out.  Such logic might, for example, update the values of other items.  (The name “4.5” for this setting reflects the fact that in Release 4.5, and subsequent releases running in 4.5 mode, the WHEN-VALIDATE-ITEM trigger always fired during item-level validation.)


Delete Allowed property

  Related Topics	 All Properties

Description

Specifies whether records can be deleted from the block.

Applies to  block

Set  Form Builder, programmatically

Default

Yes

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY


Delete Procedure Arguments property

  Related Topics	 All Properties

Description

Specifies the names, datatypes, and values of the arguments that are to be passed to the procedure for deleting data.  The Delete Procedure Arguments property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Delete Procedure Name property

  Related Topics	 All Properties

Description

Specifies the name of the procedure to be used for deleting data.  The Delete Procedure Name property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Delete Procedure Result Set Columns property

  Related Topics	 All Properties

Description

Specifies the names and the datatypes of the result set columns associated with the procedure for deleting data.  The Delete Procedure Result Set Columns property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Delete Record Behavior property

 Restrictions	    Related Topics	 All Properties

Description

(Note :  this property was formerly called the Master Deletes property.)

Specifies how the deletion of a record in the master block should affect records in the detail block:

Setting	Description
Non-Isolated	The default setting.  Prevents the deletion of a master record when associated detail records exist in the database.
Isolated	Allows the master record to be deleted and does not affect associated detail records in the database.
Cascading	Allows the master record to be deleted and automatically deletes any associated detail records in the detail block's base table at commit time.  In a master-detail-detail relation, where relations are  nested, only records in the immediate detail block are deleted (deletions do not cascade to multiple levels of a relation chain automatically).

Applies to  relation

Set  Form Builder, programmatically

Refer to Built-in

•	GET_RELATION_PROPERTY

•	SET_RELATION_PROPERTY

Default

Non-Isolated


Delete Record Behavior restrictions property
Delete Record Behavior restrictions

•	Setting this property at runtime has no effect for a default master-detail relation. At design time, Form Builder creates the appropriate triggers to enforce the relation, and changing the Delete Record Behavior property at runtime does not alter the default trigger text.  The ability to set and get this property programmatically is included only for designers who are coding custom master-detail coordination.


Detail Block property

 Restrictions	 All Properties

Description

Specifies the name of the detail block in a master-detail block relation.

Applies to  relation

Set  Form Builder

Refer to Built-in

GET_RELATION_PROPERTY (Detail_Name)

Default:

NULL

Required/Optional  required


Detail Block restrictions property
Detail Block restrictions

The block specified must exist in the active form.


Detail Reference Item property

 All Properties

Description

Identifies the REF item in the relation's detail data block that forms the link to the master data block.  This property applies only when the Relation Type property is set to REF.

Applies to  Relation

Set  Form Builder

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Null

Usage Notes

This property applies only when the Relation type property is set to REF


Direction property

  Related Topics	 All Properties

Description

Note:  This property is specific to bidirectional National Language Support (NLS) applications.

Specifies the layout direction for bidirectional objects.

For the purposes of this property, assume that Local refers to languages displayed Right-To-Left, and Roman refers to languages displayed Left-To-Right.

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, have both a Direction property and an Initial Keyboard Direction property.)

The form-level Direction property is the highest level setting of the property.  When you accept the Default setting for the form-level Direction property,  the layout direction for the form is inherited from the natural writing direction specified by the NLS language environment variable.

In most cases, leaving all the other Direction properties set to Default will provide the desired functionality--that is, the NLS language environment variable layout direction will ripple down to each subsequent level. You only need to specify the bidirectional properties when you want to override the inherited default values.

This chart summarizes inheritance for the Direction property.

	Default Setting Derives Value From This Object
Form	NLS environment variable
All objects, such as Alert, Block, LOV, Window, and Canvas	Form
All items, such as Text Item, Display Item, Check Box, Button, Radio Group, and List Item	Canvas

 This table summarizes the functions controlled by the Direction property for each object type.  (Text items and display items do not have a Direction property; instead, in the Form Builder, you can specifically set Justification, Reading Order, and Initial Keyboard Direction properties for these items.  However, programmatically, you can get and set the Direction property only for all items, including text items and display items.)

	Layout Direction	Text Reading Order	Text Alignment	Scrollbar Position	Initial Keyboard Direction
Form	X
Alert	X	X			X
Block(for future use)
LOV(for future use)
Window	X(of menu)	X			X
Canvas	X(also point of origin)	X(boilerplate text)		X(and rulers)
Check Box	X	X			X
Button	X	X			X
Radio Group	X	X			X
List Item	X	X	X	X

Note:  The headings listed above represent functions, not properties:  for example, the Direction property for alerts does not set the Initial Keyboard Direction property, it controls the initial keyboard state function.

The allowable values for this property are:

Value	Description
Default	Direction based on the property shown in the table.
Right-To-Left	Direction is right-to-left.
Left-To-Right	Direction is left-to-right.

Applies to  all objects listed in the table

Set  Form Builder, programmatically

Refer to Built-in

•	GET_WINDOW_PROPERTY

•	GET_VIEW_PROPERTY

•	GET_ITEM_PROPERTY

•	SET_FORM_PROPERTY

•	SET_WINDOW_PROPERTY

•	SET_VIEW_PROPERTY

•	SET_ITEM_PROPERTY

General Usage Notes:

•	If you want all items on your form to default to the natural writing direction specified by the language environment variable, set Language Direction at the Form level to Default, and allow all other Direction properties to be Default, as well.

•	In most cases, the Default setting will provide the functionality you need.  Occasionally, however, you  may want to override the default by setting the Direction property for a specific object that needs to be displayed differently from the higher-level Direction property.  For example, you may want to have most items on a canvas inherit their Direction from the canvas Direction property, but in the case of a specific text item, you might set the Direction property to override the default.

•	If you are developing a bilingual application and need to display both Local and Roman menus, create a trigger to display the correct version of the menu based on the USER_NLS_LANG property of the GET_APPLICATION_PROPERTY built-in.

•	Follow these guidelines when choosing a Direction property value:

•	If you are developing a bilingual application and want to display a Local object in Right-To-Left mode and a Roman object in Left-To-Right, use the Default value.

•	If the object is normally composed of Local text, choose the Right-To-Left value.

•	If the object is normally composed of Roman text, choose the Left-To-Right value.

Direction (Alert)

Specifies the layout direction of the alert interface items, including the reading order of the text displayed within the alert window.

Direction (Button)

Specifies the reading order of button text and the initial keyboard state when the button receives input focus.

Direction (Canvas)

Specifies the layout direction of the canvas, including:

•	layout direction used in the Layout Editor

•	point of origin (for Right-to-Left, point of origin is top right corner; for Left-to-Right, point of origin is top left corner)

•	display of rulers and scrollbars

•	reading order of boilerplate text

Canvas Usage Notes:

•	Refer to the Usage Notes for the form-level Direction property to determine which value to choose.

•	To develop an application with blocks laid out in different directions, place each block on a different canvas.   This will provide:

•	automatic layout of blocks in the canvas Direction property

•	boilerplate text reading order will default to the canvas Direction property

•	If a block spans multiple canvases, keep the canvas Direction property the same for all canvases, unless you intend to have part of the block displayed with a different Direction.

•	In the Form Builder, if you change the canvas Direction property while the Layout Editor is open, the change will not take place until you reopen the Layout Editor.

Direction (Check Box)

Specifies the layout direction of a check box, including:

•	the position of the box relative to the text

•	reading order of check box label

•	initial keyboard state when the check box receives input focus

Direction (Form)

Specifies the layout direction of a form.  Setting the form-level Direction property to Default lets the form inherit layout direction from the natural writing direction of the language specified in the NLS  environment variable.

Form Usage Notes:

•	If you are developing a bilingual application that must run in both Right-To-Left and Left-To-Right directions, use the Default value.

•	During testing, set Direction to either Right-To-Left or Left-To-Right, to test your form in Local or Roman direction.  Before generating the final executable, return the setting to Default.

•	If your application must run in one direction only, choose the corresponding value.

Direction (List Item)

Specifies the layout direction of the list items in both popup lists and combo boxes, including:

•	position of the scroll bar

•	alignment of list text

•	reading order of list text

•	initial keyboard state when the list item gains input focus

Direction (Radio Group)

Specifies layout direction of the radio buttons of a group (position of the circle relative to the text), including:

•	reading order of text

•	initial keyboard state when the radio group gains input focus

Direction (Windows)

Specifies layout direction of the window object, including:

•	layout direction of the menu

•	reading order of any text displayed within the window area that is not part of an object that has its own Direction property (for example, the window title)


Display Hint Automatically property

 Restrictions	    Related Topics	 All Properties

Description

Determines when the help text specified by the item property, Hint, is displayed:

•	Set Display Hint Automatically to Yes to have Form Builder display the hint text whenever the input focus enters the item.

•	Set Display Hint Automatically to No to have Form Builder display the hint text only when the input focus is in the item and the end user presses [Help] or selects the Help command on the default menu.

Applies to  all items except chart item, display item, and custom item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Usage Notes

If a trigger causes Form Builder to navigate through several items before stopping at the target item, the help text does not display for the traversed items, but only for the target item.


Display Hint Automatically restrictions property
Display Hint Automatically restrictions

Not applicable when the Hint property is NULL.


Display in Keyboard Help property
Display in 'Keyboard Help'/'Keyboard Text' property

 Restrictions	    Related Topics	 All Properties

Description

Specifies whether a key trigger description is displayed in the runtime Keys help screen. An entry in the Keys screen includes a text description for the key name and the physical keystroke associated with it, for example, Ctrl-S.

Applies to  trigger

Set  Form Builder

Default

No

Usage Notes

•	If you do not want the name or the description to appear in the Show Keys window, set the Display Keyboard Help property to No.  This is the default setting.

•	If you want the name of the key that corresponds to the trigger and its default description to be displayed in the Keys window, set the Display Keyboard Help property to Yes and leave the Keyboard Help Text blank.

•	If you want to replace the default key description, set the Display Keyboard Help property to Yes, then enter the desired description in the Keyboard Help Text property.


Display in Keyboard Help restrictions property
Display in Keyboard Help restrictions

Valid only for key triggers.


Display Quality property

 Restrictions	 All Properties

Description

Determines the level of quality used to display an image item, allowing you to control the tradeoff between image quality and memory/performance.

The following settings are valid for this property:

High	Displays the image with high quality, which requires more resources.

Medium	Displays the image with medium quality.

Low	Displays the image with low quality, which requires fewer resources.

Applies to  image item

Set  Form Builder

Default

High


Display Quality restrictions property
Display Quality restrictions

none


Display Width (LOV) property

 All Properties

Description

See Column Mapping Properties.


Display without Privilege property

 Restrictions	    Related Topics	 All Properties

Description

Determines whether the current menu item is displayed when the current form end user is not a member of a security role that has access privileges to the item:

•	When Display without Privilege is No, Form Builder does not display the item if the end user does not have access to it.

•	When Display without Privilege is Yes, Form Builder displays the item as a disabled (grayed) menu item.  The end user can see the item on the menu, but cannot execute the command associated with the item.

You can only grant access to members of those roles displayed in the roles list.  To add a database role to this list, set the menu module property, Menu Module Roles.  For more information on establishing the roles list and assigning a role access to menu items, see the Form Builder online help system.

Applies to  menu item

Set  Form Builder

Default

No


Display without Privilege restrictions property
Display without Privilege restrictions

Valid only when the name of at least one database role has been specified in the roles list.


Display_Height property

 All Properties

Description

Specifies the height of the display device, in the units specified by the current setting of the Coordinate Units form property.  Use this property to dynamically calculate the optimum display position for windows on the screen.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY


Display_Width property

 All Properties

Description

Specifies the width of the display device, in the units specified by the current setting of the Coordinate Units form property.  Use this property to dynamically calculate the optimum display position for windows on the screen.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY


Displayed property

 Restrictions	   All Properties

Descriptiuon

Enables/unhides or deisbles/hides an item. When an itme is disabled and hidden it is not navigable, queryable, or updateable.

Values: TRUE/FALSE

Applies to: item

Set: programmatically

Usage notes

You should make sure an item is not selected before setting the Displayed property to FALSE. Setting a selected item's Diaplayed property to false will generate an error: FRM-41016.

Refer to Built-in

GET_ITEM_PROPERTY

SET_ITEM_PROPERTY


Displayed property restrictions

You cannot set the Displayed property of an item that is selected or has focus.


Distance Between Records property

  Related Topics	 All Properties

Description

Specifies the amount of space between instances of items in a multi-record block. A multi-record block is a block that has the Number of Records Displayed property set to greater than 1.

Applies to  item

Set  Form Builder

Default

0

Required/Optional  optional

Usage Notes

If you are working in character cell ruler units, the amount of space between item instances must be at least as large as the height of a single cell.

For example, to increase the amount of space between item instances in a 5 record item, you must set the Distance Between Records property to at least 4, one cell for each space between item instances.


Dither property

 All Properties

Description

Specifies the whether the image is dithered when it is displayed.

Applies to  graphic image

Set  Form Builder

Default

No

Required/Optional  required


DML Array Size property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the maximum array size for inserting, updating, and deleting records in the database at one time.

Applies to  block

Set  form builder

Default

1

Usage Notes

A larger size reduces transaction processing time by reducing network traffic to the database, but requires more memory.  The optimal size is the number of records a user modifies in one transaction.


DML Array Size restrictions property
DML Array Size restrictions

•	Minimium number of records is 1; there is no maximum.

•	When the DML Array Size is greater than 1 and Insert Allowed is Yes, you must specify one or more items as a primary key, because you cannot get the ROWID of the records.  ROWID is the default construct ORACLE uses to identify each record.  With single record processing, the ROWID of a record is obtained for future reference (update or delete).  During array processing, the ROWID of each record in the array is not returned, resulting in the need to designate one or more primary key items in the block.  The primary key is used to specify the row to lock, and the ROWID is used for updating and deleting.  BLOCK.ROWID is not available until the record is locked.  You should specify one or more items in the block as the primary key even if the Key Mode value is Unique (the default).

•	When DML Array Size is greater than 1, Update Changed Columns Only is always set to No at runtime, even if Update Changed Columns Only is Yes in the form builder.  Update Changed Columns Only specifies that only columns whose values are actually changed should be included in the UPDATE statement during a COMMIT.

•	If a long raw item (such as an image, sound or OLE item) appears in the block, the DML Array Size is always set to 1 at runtime.


DML Data Target Name property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the name of the block's DML data target.  The DML Data Target Name property is valid only when the DML Data Target Type property is set to Table.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_ITEM_PROPERTY

Default

NULL

Required/Optional  optional


DML Data Target Name restrictions property
DML Data Target Name restrictions

Prior to setting the DML Data Target Name property you must perform a COMMIT_FORM or a CLEAR_FORM.


DML Data Target Type property

  Related Topics	 All Properties

Description

Specifies the block's DML data target type.  A DML data target type can be a Table, Procedure, or Transactional Trigger.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

GET_BLOCK_PROPERTY

Default

Table

Required/Optional  required


DML Returning Value property

 All Properties

Description

Specifies whether Forms should use new or old behavior when updating client-side data with changed values after a database update or insert.  A Yes setting for this property selects new behavior (new as of Release 6).  A No setting selects old behavior (behavior of Release 5 and earlier).

A database update or insert action may initiate server-side triggers that cause alterations or additional changes in the data.  In Release 6, when using an Oracle8 database server, Forms uses the DML Returning clause to immediately bring back any such changes.  When this property is set to Yes, Forms will automatically update the client-side version of the data, and the user will not need to re-query the database to obtain the changed values.

When this property is set to No, Forms will not automatically update the client-side version of the data.  (This is its pre-Release 6 behavior.)  In this case, if the user subsequently tries to update a row whose values were altered on the server side,  the user receives a warning message and is asked to re-query to obtain the latest values.  This No setting is available as a compatibility option.

Applies to  block

Set  Form Builder

Valid values  Yes/No

Default  No

Required/Optional  required

Restrictions

•	Forms uses the DML Returning clause only with an Oracle8 database server.  This property is ignored when using a non-Oracle8 server.

•	Forms uses the Returning clause with Insert and Update statements, but (currently) not with Delete statements.

•	Forms does not use the Returning clause when processing LONGs.

•	The updating of unchanged columns is controlled by the setting of the Update Changed Columns Only property, which in turn is affected by the setting of the DML Array Size property.


Edge Background Color property

 All Properties

Description

Specifies the background color of the graphic object's edge.

Applies to  graphic font & color

Set  Form Builder

Default

Null

Required/Optional  optional


Edge Foreground Color property

 All Properties

Description

Specifies the foreground color of the graphic object's edge.

Applies to  graphic font & color

Set  Form Builder

Default

Null

Required/Optional  optional


Edge Pattern property

 All Properties

Description

Specifies the pattern of the graphic object's edge.

Applies to  graphic font & color

Set  Form Builder

Default

Null

Required/Optional  optional


Editor property

 Restrictions	 All Properties

Description

Specifies that one of the following editors should be used as the default editor for this text item:

•	a user-named editor that you defined in the form or

•	a system editor outside of Form Builder that you specified by setting the SYSTEM_EDITOR environment variable

Applies to  text item

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Default

blank, indicating the default Form Builder editor

Required/Optional  optional

Usage Notes

To specify a system editor:

•	Define the system editor by setting the FORMS60_EDITOR environment variable.

•	Enter the value SYSTEM_EDITOR in the Editor Name field.


Editor restrictions property
Editor restrictions

The editor specified must exist in the active form.


Editor X Position, Editor Y Position

 All Properties

Description

Specifies the horizontal (x) and vertical (y) coordinates of the upper left corner of the editor relative to the upper left corner of the window's content canvas.  When you set the Editor property, you can set the Editor position properties to override the default display coordinates specified for the editor.

Applies to  text item

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Default

0, 0; indicating that Form Builder should use the default editor display coordinates, as specified by the editor Position property.

Required/Optional  optional


Elements in List property

 Restrictions	 All Properties

Description

The Elements in List property group includes the List Item and List Item Value properties.

Applies to  list item

Set  Form Builder

List Item

Specifies the text label for each element in a list item.

Required/Optional  required

List Item Value

Specifies the value associated with a specific element in a list item.

Default

NULL

Required/Optional  required

Usage Notes

When you leave the List Item Value field blank, the value associated with the element is NULL.


Elements in List restrictions property
Elements in List restrictions

•	Must be unique among values associated with element values.


Enabled properties

 All Properties

Enabled (Item) property

Enabled (Menu Item) property

Enabled (Tab Page) property


Enabled (Item) property

  Related Topics	 All Properties

Description

Determines whether end users can use the mouse to manipulate an item.

On most window managers, Enabled set to No grays out the item.

Applies to  all items except buttons, chart items, and display items

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

Default

Yes

Usage Notes

When Enabled is set to Yes, Keyboard Navigable can be set to Yes or No.  When Enabled is No, an item is always non-Keyboard Navigable.   At runtime, when the Enabled property is set to PROPERTY_FALSE, the Keyboard_Navigable property is also set to PROPERTY_FALSE.

Enabled set to No grays out the item.  If you want the item to appear normally so the user can inspect it but without being able to change it, set the following properties:

•	Insert Allowed (Item) to No

•	Update Allowed (Item) to No

•	Enabled to Yes


Enabled (Menu Item) property

 Restrictions	    Related Topics	 All Properties

Description

Specifies whether the menu item should be displayed as an enabled (normal) item or disabled (grayed) item.

Applies to  menu item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_MENU_ITEM_PROPERTY

Default

Yes


Enabled (Menu Item) restrictions property
Enabled (Menu Item) restrictions

You cannot programmatically enable or disable a menu item that is hidden as a result of the following conditions:

•	The menu module Use Security property is Yes.

•	The menu item Display without Privilege property is set to No.

•	The current end user is not a member of a role that has access to the menu item.


Enabled (Tab Page) property

 All Properties

Description

Specifies whether the tab page should be displayed as enabled (normal) or disabled (greyed out).

Applies to  tab page

Set  Form Builder, programmatically

Refer to Built-in

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

Default

Yes


End Angle property

 All Properties

Description

Specifies the ending angle of the arc, using the horizontal axis as an origin.

Applies to  graphic arc

Set  Form Builder

Default

180

Required/Optional  required


Enforce Column Security property

  Related Topics	 All Properties

Description

Specifies when Form Builder should enforce update privileges on a column-by-column basis for the block's base table.  If an end user does not have update privileges on a particular column in the base table, Form Builder makes the corresponding item non-updateable for this end user only, by turning off the Update Allowed item property at form startup.

The following table describes the effects of the allowable values for this property:

State	Effect
Yes	Form Builder enforces the update privileges that are defined in the database for the current end user.
No	Form Builder does not enforce the defined update privileges.

 Applies to  block

Set  Form Builder

Refer to Built-in

GET_BLOCK_PROPERTY

Default

No


Enforce Primary Key (Block) property

 Restrictions	    Related Topics	 All Properties

Description

Indicates that any record inserted or updated in the block must have a unique key in order to avoid committing duplicate rows to the block's base table.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default

No


Enforce Primary Key (Block) restrictions property
Enforce Primary Key (Block) restrictions

•	The Primary Key item property must be set to Yes for one or more items in the block.


Enterable property

  Related Topics	 All Properties

Description

Specifies whether the block is enterable.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY

Usage Notes

•	A block is enterable when its current record contains an item instance whose Keyboard Navigable property has an effective value of true. See the Keyboard Navigable property and SET_ITEM_INSTANCE_PROPERTY built-in for information about effective Keyboard Navigable values.


Error_Date/Datetime_Format property

  Related Topics	 All Properties

Description

Holds the current error date or datetime format mask established by the environment variable FORMSnn_ERROR_DATE_FORMAT or FORMSnn_ERROR_DATETIME_FORMAT.  Forms uses these format masks as defaults in its runtime error processing.

There are two separate properties:  Error_Date_Format and Error_Datetime_Format.

Applies to  application

Set  Not settable from within Form Builder.

Refer to Built-in

GET_APPLICATION_PROPERTY


Execution Mode properties

 All Properties

Execution Mode (Chart) property

Execution Mode (Report) property


Execution Mode (Chart) property

 All Properties

Description

When running Graphics Builder from Form Builder to create a chart, this property specifies the execution mode to be used as either Batch or Runtime. Batch mode executes the report or graphic without user interaction. Runtime mode enables user interaction during the execution.

Applies to  chart items

Set  Form Builder

Default

Batch

Required/Optional  required


Execution Mode (Report) property

 All Properties

Description

For report integration with a form, this property specifies the execution mode of the report as either Batch or Runtime. Batch mode executes the report or graphic without user interaction. Runtime mode enables user interaction during the execution.

Applies to  report Developer integration

Set  Form Builder

Default

Batch

Required/Optional  required


Execution Hierarchy property

 All Properties

Description

Specifies how the current trigger code should execute if there is a trigger with the same name defined at a higher level in the object hierarchy.

The following settings are valid for this property:

Override	Specifies that the current trigger fire instead of any trigger by the same name at any higher scope.  This is known as "override parent" behavior.

Before	Specifies that the current trigger fire before firing the same trigger at the next-higher scope.  This is known as "fire before parent" behavior.

After	Specifies that the current trigger fire after firing the same trigger at the next-higher scope.  This is known as "fire after parent" behavior.

Applies to  trigger

Set  Form Builder

Default

Override


Filename property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the name of the file where the named object is stored.

Applies to  form, report

Set  not settable

Refer to Built-in

GET_FORM_PROPERTY

Required/Optional  optional

Usage Notes

Filename at the form level corresponds to Current_Form at the application level.  Current_Form is gettable with GET_APPLICATION_PROPERTY.


Filename property restrictions

If two or more forms share the same name, Filename supplies the name of the file where the most recently-accessed form is stored.


Fill property

 All Properties

Description

Specifies the fill shape of the arc as either Pie or Chord.  Pie renders the arc from the center point of the circle described by the arc.  Chord renders the arc from a line segment between the arc's two end points.

Applies to  graphic arc

Set  Form Builder

Default

Pie

Required/Optional  required


Fill_Pattern property

  Related Topics	 All Properties

Description

Specifies the pattern to be used for the object’s fill region. Patterns are rendered in the two colors specified by Background_Color and Foreground_Color.

Applies to  item, tab page, canvas, window, radio button

Set Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY


Filter Before Display property

 Restrictions	 All Properties

Description

When Filter Before Display is set to Yes, Form Builder displays a query criteria dialog before displaying the LOV.  End users can enter a value in the query criteria dialog to further restrict the rows that are returned by the default SELECT statement that populates the LOV's underlying record group.  Form Builder uses the value entered in the query criteria dialog to construct a WHERE clause for the SELECT statement. The value is applied to the first column displayed in the LOV. A hidden LOV column is not displayed.

The WHERE clause constructed by Form Builder appends the wildcard symbol to the value entered by the end user.  For example, if the end user enters 7, the WHERE clause reads LIKE '7%' and would return 7, 712, and 7290.

Keep in mind that once the end user enters a value in the query criteria dialog and the LOV is displayed, the LOV effectively contains only those rows that correspond to both the the default SELECT statement and the WHERE clause created by the value in the query criteria dialog. For example, consider an LOV whose default SELECT statement returns the values FOO, FAR, and BAZ. If the end user enters the value F or F% in the query criteria dialog, the resulting LOV contains only the values FOO and FAR. If the user then enters the value B% in the LOV’s selection field, nothing will be returned because BAZ has already been selected against in the query criteria dialog.

Applies to  LOV

Set  Form Builder

Default

No


Filter Before Display restrictions property
Filter Before Display restrictions

•	If the SELECT statement for the LOV's underlying record group joins tables, the name of the first column displayed in the LOV must be unique among all columns in all joined tables.  If it is not, an error occurs when the end user attempts to use the Filter Before Display feature.  For example, when joining the EMP and DEPT tables, the DEPTNO column would not be unique because it occurs in both tables.  An alternative is to create a view in the database, and assign a unique name to the column you want end users to reference in the query criteria dialog.

•	When a long-list LOV is used for item validation, the query criteria dialog is not displayed so that LOV validation is transparent to the forms end user.  Instead, Form Builder uses the current value of the text item to construct the WHERE clause used to reduce the size of the list by applying the wildcard criteria to the first visible column in the LOV.


Fire in Enter-Query Mode

  Related Topics	 All Properties

Description

Specifies that the trigger should fire when the form is in Enter-Query mode, as well as in Normal mode.

Applies to  trigger

Set  Form Builder

Default

no

Usage Notes

Only applicable to the following triggers:

•	Key

•	On-Error

•	On-Message

•	When- triggers, except:

•	When-Database-Record

•	When-Image-Activated

•	When-New-Block-Instance

•	When-New-Form-Instance

•	When-Create-Record

•	When-Remove-Record

•	When-Validate-Record

•	When-Validate-Item


First Navigation Block property

  Related Topics	 All Properties

Description

Specifies the name of the block to which Form Builder should navigate at form startup and after a CLEAR_FORM operation.  By default, the First_Navigation_Block is the first block in the form's commit sequence, as indicated by the sequence of blocks in the Object Navigator.  You can set the First_Navigation_Block property programmatically to specify a different block as the first navigation block.

Applies to  form module

Set  Form Builder, programmatic

Refer to Built-in

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY

Default

The first block in the form; that is, the block that is listed first in the Object Navigator.

Required/Optional  optional

Usage Notes

You can set this property from a When-New-Form-Instance trigger,  which fires at form startup, before Form Builder navigates internally to the first block in the form.


First_Block property

  Related Topics	 All Properties

Description

Specifies the block that is the first block in the form, as indicated by the sequence of blocks in the Object Navigator.  At startup, Form Builder navigates to the first item in the first block.

Applies to  form

Set  not settable

Refer to Built-in

GET_FORM_PROPERTY


First_Detail_Relation property

  Related Topics	 All Properties

Description

Specifies the name of the first master-detail block relation in which the given block is the detail block.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY

Usage Notes

This property is useful when you are writing your own master-detail coordination scheme.  It can be used in conjunction with the Next_Master_Relation and Next_Detail_Relation properties to traverse a list of relations.


First_Item property

  Related Topics	 All Properties

Description

Specifies the item that is the first item in the block, as indicated by the sequence of items in the Object Navigator.  At startup, Form Builder navigates to the first item in the first block.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY


First_Master_Relation property

  Related Topics	 All Properties

Description

Specifies the name of the first master-detail block relation in which the given block is the master block.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY

Usage Notes

This property is useful when you are writing your own master-detail coordination scheme.  It can be used in conjunction with the Next_Master_Relation and Next_Detail_Relation properties to traverse a list of relations.


Fixed Bounding Box property

 All Properties

Description

Specifies whether the text object's bounding box should remain a fixed size.  If this property is set to Yes, the values of the Width and Height properties determine the size of the bounding box.

Applies to  graphic text

Set  Form Builder

Default

No

Required/Optional  required


Fixed Length (Item) property

 Restrictions	    Related Topics	 All Properties

Description

When set to Yes, Fixed Length specifies that the item should be considered valid only when it contains the maximum number of characters allowed.  The maximum number of characters allowed is determined by the Maximum Length property setting.

Applies to  text item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No


Fixed Length (Item) restrictions property
Fixed Length (Item) restrictions

•	The Visible and Enabled properties must be set to Yes.

•	A text item value of the NUMBER data type cannot contain leading zeroes.  Form Builder automatically removes leading zeroes and interprets the text item as "not filled."


Fixed Length (Menu Substitution Parameter) property

  Related Topics	 All Properties

Description

When set to Yes, Fixed Length specifies that the parameter should be considered valid only when it contains the maximum number of characters allowed.  The maximum number of characters allowed is determined by the Maximum Length property setting.

Applies to  menu substitution parameter

Set  Form Builder

Default

No


Flag User Value Too Long property

 All Properties

Description

Specifies how Forms should handle a user-entered value that exceeds the item’s Maximum Length property.

This property applies only in a 3-tier environment in which the middle tier (the Forms server) specifies a multi-byte character set other than UTF8.

Applies to  application

Set  programmatically

Default

Property_False (‘FALSE’)

Refer to Built-in

GET_APPLICATION_PROPERTY

SET_APPLICATION_PROPERTY

Usage Notes

In a 3-tier, non-UTF8 multi-byte character set environment, it is possible for an end user to type more bytes into an item than the item’s Maximum Length property specifies.

When the Flag User Value Too Long property has been set or defaulted to FALSE and this situation arises, then the user’s typed-in value is truncated (on a character boundary) so that its size in bytes does not exceed the item’s Maximum Length.  When item-level validation is performed, the truncated value is validated.  If validation (and any navigational triggers) succeeds, then the end user is allowed to navigate out of the item.  No error or warning message is displayed.

When the Flag User Value Too Long property has been set to TRUE and this situation arises, then the user’s typed-in value is not truncated.  When item-level validation is performed, it will fail (with an error message indicating that truncation would be necessary).  This means that the end user is not allowed to leave the current validation unit (as specified by the current form’s Validation Unit property).


Font_Name property

  Related Topics	 All Properties

Description

Specifies the font family, or typeface, to be used for text in the object. The list of fonts available is system-dependent.

Applies to  item, tab page, canvas, window, radio button

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY


Font_Size property

  Related Topics	 All Properties

Description

Specifes the size of the font in points.

Applies to  item, tab page, canvas, window, radio button

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY


Font_Spacing property

  Related Topics	 All Properties

Description

Specifies the width of the font (i.e., the amount of space between characters, or kerning). Valid values are:

FONT_NORMAL

FONT_ULTRADENSE

FONT_EXTRADENSE

FONT_DENSE

FONT_SEMIDENSE

FONT_SEMIEXPAND

FONT_EXPAND

FONT_EXTRAEXPAND

FONT_ULTRAEXPAND

Applies to  item, tab page, canvas, window, radio button

Set  Programmatically

Default

FONT_NORMAL

Refer to Built-in

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

•	GET_VA_PROPERTY

•	SET_VA_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY


Font_Style property

  Related Topics	 All Properties

Description

Specifies the style of the font. Valid values are:

FONT_PLAIN

FONT_ITALIC

FONT_OBLIQUE

FONT_UNDERLINE

FONT_OUTLINE

FONT_SHADOW

FONT_INVERTED

FONT_OVERSTRIKE

FONT_BLINK

Applies to  item, tab page, canvas, window, radio button

Set  Programmatically

Default

FONT_PLAIN

Refer to Built-in

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

•	GET_VA_PROPERTY

•	SET_VA_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY


Font_Weight property

  Related Topics	 All Properties

Description

Specifies the weight of the font. Valid values are:

FONT_MEDIUM

FONT_ULTRALIGHT

FONT_EXTRALIGHT

FONT_LIGHT

FONT_DEMILIGHT

FONT_DEMIBOLD

FONT_BOLD

FONT_EXTRABOLD

FONT_ULTRABOLD

Applies to  item, tab page, canvas, window, radio button

Set  Programmatically

Default

FONT_MEDIUM

Refer to Built-in

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

•	GET_VA_PROPERTY

•	SET_VA_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY


Foreground_Color property

  Related Topics	 All Properties

Description

Specifies the color of the object’s foreground region. For items, defines the color of the text displayed in the item.

Applies to  item, tab page, canvas, window, radio button

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY


Form Horizontal Toolbar Canvas property

 Restrictions	    Related Topics	 All Properties

Description

On Microsoft Windows, specifies the canvas that should be displayed as a horizontal toolbar on the MDI application window. The canvas specified must have the Canvas Type property set to Horizontal Toolbar.

Applies to  form

Set  Form Builder

Default

Null

Required/Optional  optional


Form Horizontal Toolbar Canvas restrictions property
Form Horizontal Toolbar Canvas restrictions

Valid only on Microsoft Windows. On other platforms, the Form Horizontal Toolbar Canvas property is ignored and the canvas is mapped to the window indicated by its Window property setting.


Form Vertical Toolbar Canvas property

 Restrictions	    Related Topics	 All Properties

Description

On Microsoft Windows, specifies the toolbar canvas that should be displayed as a vertical toolbar on the MDI application window. The canvas specified must have the Canvas Type property set to Vertical Toolbar.

Applies to  form

Set  Form Builder

Default

Null

Required/Optional  optional


Form Vertical Toolbar Canvas restrictions property
Form Vertical Toolbar Canvas restrictions

Valid only on Microsoft Windows. On other platforms, the Form Vertical Toolbar Canvas property is ignored and the toolbar canvas is mapped to the window indicated by its Window property setting.


Format Mask property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the display format and input accepted for data in text items.

Applies to  text item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Required/Optional  optional

Usage Notes

Valid format masks for character strings, numbers and dates are described in the following tables.

Character Strings

The following table describes valid format masks for character strings.

Element	Example	Description
FM	FMXX99	Fill mode:  accept string as typed, do not right justify.  Allows end user input string to be shorter than the format mask.
X	XXXX	Any alphabetic, numeric, or special character.  End user input string must be exact length specified by format mask.
9	9999	Numeric characters only.  End user input string must be exact length specified by format mask.
A	AAAA	Alphabetic characters only.  End user input string must be exact length specified by format mask.
Character String Examples

Format Mask	Description
XXAA	Will accept: --ab, abcd, 11ab; will not accept: --11, ab11, or ab--(must use XX to accept hyphens and other special characters).
XXXX	Will accept any combination of alphabetic, numeric, or special characters: --ab, abcd, 11ab, --11, ab11, or ab--.  Will accept 1234 or abcd; will not accept 123 or abc.  (To accept input string shorter than mask, use FMXXXX.)
FMXX99	Will accept ab12, ab1, ab followed by two spaces; will not accept 12ab or abcd.  (To produce the Form Builder Version 3.0 Alpha datatype, use FMAAAAAA.)
•	To embed additional characters such as a hyphen (-) or a comma (,), surround the character with double-quotes (").

•	Embedded characters are separate from text item values and are not collated along with text item values, even when the end user enters them.

NUMBERS

The following table describes valid format masks for numbers.

Element	Example	Description
9	9999	Number of nines determines display width.  Any leading zeros will be displayed as blanks.
0	0999	Display leading zeros.
0	9990	Display zero value as zero, not blank.
$	$9999	Prefix value with dollar sign.
B	B9999	Display zero value as blank, not "0".
MI	9999MI	Display "-" after a negative value.
PR	9999PR	Display a negative value in <angle brackets>.
comma	9,999	Display a comma in this position.  For correct behavior in multilingual applications, substitute G to return the appropriate group (thousands) separator.
period	99.99	Display a decimal point in this position. For correct behavior in multilingual applications, substitute D to return the appropriate decimal separator.
E	9.999EEEE	Display in scientific notation (format must contain exactly four "E"s).
FM	FM999	Fill mode: accept string as typed, do not right justify.
•	When you mask a number with nines (9), Form Builder adds a space in front of the number to accommodate the plus (+) or minus (-) sign.  However, since the plus sign is not displayed, it appears as if Form Builder adds a space in front of the number.  (The minus sign is displayed.)

•	To embed additional characters such as a hyphen (-) or a comma (,), surround the character with double-quotes (").

•	Embedded characters are separate from text item values and are not collated along with text item values, even when the end user enters them.

NUMBER Examples

Format Mask	Description
FM099"-"99"-"9999	Displays the social security number as formatted, including hyphens, even if end user enters only nine digits.To create a Social Security column, create an 11-character column, set to fixed length, with a format mask of 099"-"99"-"9999.  This mask will accommodate Social Security numbers that begin with zero, accepting 012-34-5678 or 012345678 (both stored as 012345678).
99999PR	Accepts -123; reformats as <123>.
999MI	Accepts -678; reformats as 678-.
9.999EEEE	Displays as 1.00E+20.
How Forms handles length mismatches

If a runtime user enters a numeric string that exceeds the format mask specification, the value will be rejected.  For example:

Format Mask	User enters	Result
99.9	321.0	Invalid
99.9	21.01	Invalid
99.9	21.1	21.1
99.9	01.1	1.1
In contrast, if a numeric value fetched from the database exceeds the format mask specification for its display field, the value is displayed, but truncated, with rounding, to fit the mask.  (The item itself within the Forms application retains its full value.)  For example, if the database held the value 2.0666, and the format mask was 99.9, the value displayed to the user would be 2.1.  However, the value of the item within the form would be the full 2.0666.

Dates

The following table describes valid format masks for dates.

Element	Description
YYYY or SYYYY	4-digit year; "S" prefixes "BC" date with "-".
YYY or YY or Y	Last 3, 2, or 1 digits of year.
Y,YYY	Year with comma in this position.
BC or AD	BC/AD indicator.
B.C. or A.D.	BD/AD indicator with periods.
RR	Defaults to correct century.  Deduces the century from a date entered by comparing the 2 digit year entered with the year and century to which the computer's internal clock is set.   Years 00-49 will be given the 21st century (the year 2000), and years from 50-99 will be given the 20th century (the year 1900).
MM	Month (01-12; JAN = 01).
MONTH	Name of month, padded with blanks to length of 9 characters.
MON	Name of month, 3-letter abbreviation.
DDD	Day of year (1-366).
DD	Day of month (1-31).
D	Day of week (1-7; Sunday=1).
DAY	Name of day, padded with blanks to length of 9 characters.
DY	Name of day, 3-letter abbreviation.
J	Julian day; the number of days since January 1, 4712 BC.
AM or PM	Meridian indicator.
A.M. or P.M.	Meridian indicator with periods.
HH or HH12	Hour of day (1-12).
HH24	Hour of day (0-23).
MI	Minute (0-59).
SS	Second (0-59).
SSSSS	Seconds past midnight (0-86399).
/. , .	Punctuation is reproduced in the result.
"..."	Quoted string is reproduced in the result.
FM	Fill mode: assumes implied characters such as O or space; displays significant characters left justified.  Allows end user input to be shorter than the format mask.  (Use in conjunction with FX to require specific delimiters.)
FX	All date literals must match the format mask exactly, including delimiters.
•	When you prefix a date mask with FX, the end user must enter the date exactly as you define the mask, including the specified delimiters:

Date Examples

Format Mask	Description
FXDD-MON-YY	Will accept 12-JAN-94, but will not accept 12.JAN.94 or 12/JAN/94 because the delimiters do not match the mask. Will not accept 12JAN94 because there are no delimiters.  Will accept 01-JAN-94 but will not accept 1-JAN-94.
FMDD-MON-YY	Will accept 01-JAN-94.  Will also accept the entry of other delimiters, for example 01/JAN/94 and 01 JAN 94.  However, will not accept 01JAN94.  Will accept 1-JAN-94, converting it to 01-JAN-94.
DD-MON-YY	Will accept 12.JAN.94, 12/JAN/94 or 12-JAN-94. Note: Any delimiter characters will be accepted, but if delimiters are omitted by the end user, this mask will interpret date characters as a delimiters.  Will accept 12-JAN94, (but will erroneously interpret as 12-JAN-04); but will not accept 12JAN94, because "AN" is not a valid month name.
•	Use of a format mask only affects how the data looks.  Form Builder stores full precision, regardless of how the data is presented.

•	Embedded characters are separate from text item values and are not collated along with text item values, even when the end user enters them.

•	To embed additional characters such as a hyphen (-) or a comma (,), surround the character with double-quotes (").  Note, however, that double-quotes themselves cannot be used as a character.  In other words, trying to achieve output of DD"MM by specifying a mask of DD"""MM would not work.

Format Mask	Description
FMMONTH" "DD", "YYYY	Displays the text item data in the specified date format: JANUARY 12, 1994, including the appropriate blank spaces and comma.
FMDD-MONTH-YYYY	Displays as 12-JANUARY-1994.
DY-DDD-YYYY	Displays as WED-012-1994.  Note: for input validation including day of the week, a mask that allows specific determination of the day is required, such as this example or DY-DD-MM-YY.
•	When you use day of the week formats, be sure that the data  includes day of the week information.  To avoid illogical masks, display also either the day of the year (1-366) or the month in some format.

Format Mask	Description
DD-MONTH-YYYY	Displays as 12-JANUARY-1994.
DY-DDD-YYYY	Displays as WED-012-1994.
DY-DD-MON-YY	Displays as WED-12-JAN-94.  Be sure to include month.  Avoid masks such as DY-DD-YY, which could generate an error.
NLS Format Masks

The following table describes valid National Language Support (NLS) format masks.

Element	Example	Description
C	C999	Returns the international currency  symbol.
L	L9999	Returns the local currency  symbol.
D	99D99	Returns the decimal separator.
G	9G999	Returns the group (thousands) separator.
comma	9,999	Displays a comma in this position.
period	9.999	Displays a decimal point in this position. Displays a decimal point in this position.
NLS Format Mask Examples

Format Mask	Description
L99G999D99	Displays the local currency symbol, group, and decimal separators:  if NLS_LANG=American, this item displays as $1,600.00; if NLS_LANG=Norwegian, this item displays as Kr.1.600,00.
C99G999D99	Displays the appropriate international currency symbol: if NLS_LANG=American, this item displays as USD1,600.00; if NLS_LANG=French, this item displays as FRF1.600,00.


Format Mask restrictions property
Format Mask restrictions

•	When setting the Maximum Length property for a text item, include space for any embedded characters inserted by the format mask you specify.

•	Format masks can contain a maximum of 30 characters.

•	Form Builder supports only ORACLE format masks that are used for both input and output.  Output-only format masks, such as WW, are not supported.


Form_Name property

  Related Topics	 All Properties

Description

Specifies the name of the form.

Applies to  form

Set  not settable

Refer to Built-in

GET_FORM_PROPERTY

Usage Notes

Form_Name at the form level corresponds to Current_Form_Name at the application level.  Current_Form_Name is gettable with GET_APPLICATION_PROPERTY.


Formula property

 All Properties

Description

Specifies a single PL/SQL expression that determines the value for a formula calculated item.  The expression can reference built-in or user-written subprograms.

Applies to  item

Set  Form Builder

Refer to Built-in

RECALCULATE

Usage Notes

You cannot enter an entire PL/SQL statement as your formula;  accordingly, do not terminate your calculation expression with a semicolon.  Form Builder adds the actual assignment code to the formula internally do not code it yourself.  For example, instead of coding an entire assignment statement, code just the expression

   :emp.sal + :emp.comm

Form Builder will internally convert this into a complete statement, e.g.,

   :emp.gross_comp := (:emp.sal + :emp_comm);

Required/Optional  required if Calculation Mode property is set to Formula


Frame Alignment property

 Show Me	 All Properties

Description

Specifies how objects should be aligned within the width of the frame, either Start, End, Center, Fill, or Column. This property is valid when the Layout Style property is set to Form.

Applies to  frame

Set  Form Builder

Default

Fill

Required/Optional  required


Frame Alignment showme
Frame Alignment


Frame Title property

 All Properties

Description

Specifies the frame's title.

Applies to  frame

Set  Form Builder

Default

blank

Required/Optional  optional


Frame Title Alignment property

 Show Me	 All Properties

Description

Specifies the title alignment for a frame, either Start, End, or Center.

Note: Title alignment is relative to the Direction of the canvas on which the canvas appears.

Applies to  frame

Set  Form Builder

Default

Start

Required/Optional  required


Frame Title Alignment showme
Frame Title Alignment


Frame Title Background Color property

 All Properties

Description

Specifies the color to apply to the frame title background.

Applies to  frame

Set  Form Builder

Default

Defaults to the standard operating system font color (usually white).

Required/Optional  required


Frame Title Font Name property

 All Properties

Description

Specifies the name of the font (typeface) to apply to the frame title.

Applies to  frame

Set  Form Builder

Default

Defaults to the standard operating system font

Required/Optional  required


 Frame Title Font Size property

 All Properties

Description

Specifies the size of the font (typeface) to apply to the frame title.

Applies to  frame

Set  Form Builder

Default

Defaults to the standard operating system font size

Required/Optional  required


 Frame Title Font Spacing property

 All Properties

Description

Specifies the spacing to apply to the frame title text.

Applies to  frame

Set  Form Builder

Default

Defaults to the standard operating system font spacing

Required/Optional  required


Frame Title Font Style property

 All Properties

Description

Specifies the typographic style (for example, Italic) to apply to the frame title text.

Applies to  frame

Set  Form Builder

Default

Defaults to the standard operating system font style

Required/Optional  required


Frame Title Font Weight property

 All Properties

Description

Specifies the typographic weight (for example, Bold) to apply to the frame title text.

Applies to  frame

Set  Form Builder

Default

Defaults to the standard operating system font weight.

Required/Optional  required


Frame Title Foreground Color property

 All Properties

Description

Specifies the color to apply to the frame title text.

Applies to  frame

Set  Form Builder

Default

Defaults to the standard operating system font color (usually black).

Required/Optional  required


Frame Title Offset property

 Show Me	 All Properties

Description

Specifies the distance between the frame and its title.

Applies to  frame

Set  Form Builder

Default

2 char cells (or the equivalent depending on the form coordinate system)

Required/Optional  required


Frame Title Offset showme


Frame Title Reading Order property

 All Properties

Description

Specifies the reading order for frame titles, either Default, Left-to-Right, or Right-to-Left.

Applies to  frame

Set  Form Builder

Default

Default

Required/Optional  required


Frame Title Spacing property

 Show Me	 All Properties

Description

Specifies the amount of space reserved on either side of the frame's title.

Applies to  frame

Set  Form Builder

Default

1 char cell (or the equivalent depending on the form coordinate system)

Required/Optional  required


Frame Title Spacing showme
Frame Title Spacing


Frame Title Visual Attribute Group property

  Related Topics	 All Properties

Description

Specifies how the frame title's individual attribute settings (Font Name, Background Color, Fill Pattern, etc.) are derived. The following settings are valid for this property:

Default	Specifies that the object should be displayed with default color, pattern, and font settings. When Visual Attribute Group is set to Default, the individual attribute settings reflect the current system defaults. The actual settings are determined by a combination of factors, including the type of object, the resource file in use, and the platform.
Named visual attribute	Specifies a named visual attribute that should be applied to the object. Named visual attributes are separate objects that you create in the Object Navigator and then apply to interface objects, much like styles in a word processing program. When Visual Attribute Group is set to a named visual attribute, the individual attribute settings reflect the attribute settings defined for the named visual attribute object. When the current form does not contain any named visual attributes, the poplist for this property will show Default.

Applies to  frame title

Set  Form Builder

Default

Default

Usage Notes

•	Default and named visual attributes can include the following individual attributes, listed in the order they appear in the Property Palette:

Font Name  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

Font Size  The size of the font, specified in points.

Font Style  The style of the font.

Font Spacing  The width of the font, that is, the amount of space between characters (kerning).

Font Weight  The weight of the font.

Foreground Color  The color of the object's foreground region.  For items, the Foreground Color attribute defines the color of text displayed in the item.

Background Color  The color of the object's background region.

Fill Pattern  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

Character Mode Logical Attribute  Specifies the name of a character mode logical attribute defined in an Oracle Terminal resource file that is to be used as the basis of device attributes for a character mode version of your application.

White on Black  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

Not all attributes are valid for each object type. For example, setting font attributes for a window object has no effect. (The font used in a window's title bar is derived from the system.)

•	A new object in a new form has Default visual attributes.  The default settings are defined internally. Override the default font for new items and boilerplate by setting the optional FORMS60_DEFAULTFONT environment variable.  For example, On Microsoft Windows, set this variable in the ORACLE.INI file, as follows: FORMS60_DEFAULTFONT="COURIER.10". The default font specified determines the font used for new boilerplate text generated by the New Block window, and for any items that have Visual Attribute Group set to Default.

•	When you create an item in the Layout Editor, its initial visual attribute settings are determined by the current Layout Editor settings for fonts, colors, and patterns, as indicated by the Font dialog and Color and Pattern palettes.

•	On Microsoft Windows, the colors of buttons, window title bars, and window borders are controlled by the Windows Control Panel color settings specified for these elements. You cannot override these colors in Form Builder.

•	When the Use 3D Controls form property is set to Yes on Microsoft Windows (the default), items are rendered with shading that provides a sculpted, three-dimensional look.  A side effect of setting this property is that any canvases that have Visual Attribute Group set to Default derive their color setting from the Windows Control Panel (gray for most color schemes). You can override this setting by explicitly applying named visual attributes to the canvas.

•	An item that has Visual Attribute Group set to Default, or that has individual attribute settings left unspecified, inherits those settings from the canvas to which it is assigned. Similarly, a canvas that has Visual Attribute Group set to Default, or that has individual attribute settings left unspecified, inherits those settings from the window in which it is displayed. For example, if you set a window's Background Color to CYAN, and then leave Background Color unspecified for the canvas assigned to the window, at runtime, that canvas will inherit the CYAN background from its window. Visual attribute settings derived through window canvas or canvas item inheritance are apparent only at runtime, not at design time.

•	You can apply property classes to objects to specify visual attribute settings. A property class can contain either the Visual Attribute Group property, or one or more of the individual attribute properties. (If a property class contains both Visual Attribute Group and individual attributes, the Visual Attribute Group property takes precedence.)

•	If you apply both a named visual attribute and a property class that contains visual attribute settings to the same object, the named visual attribute settings take precedence, and the property class visual attribute settings are ignored.

•	Logical attribute definitions defined in the resource file take precedence over visual attributes specified in the Form Builder, local environment variable definitions, and default Form Builder attributes. To edit the resource file, use the Oracle Terminal utility.


Graphics Type property

 All Properties

Description

A read-only property that specifies the type of the graphic object. Possible values include: Arc, Chart, Group, Image, Line, Polygon, Rectangle, Rounded Rectangle, Symbol, and Text.  (Same possible values as Graphics Builder property Object Type.)

Applies to  graphics general

Set  Form Builder

Default

the type

Required/Optional  required


Group_Name property

 All Properties

Description

Specifies the name of the record group on which an LOV is based.

Applies to  LOV

Set  programmatically

Refer to Built-in

•	GET_LOV_PROPERTY

•	SET_LOV_PROPERTY

Default

Name of the underlying record group.

Usage Notes

Set Group_Name to replace the LOV's current record group with another record group at runtime. The column names and types in the new record group must match the column names and types in the record group you are replacing.


Help property

 Restrictions	    Related Topics	 All Properties

Description

On character mode platform specifies help text for the menu item. Help text is displayed in a window when the end user presses [Help] while the menu item is selected.

Applies to  menu item

Set  Form Builder

Required/Optional  optional


Help restrictions property
Help restrictions

Applies to character mode applications only.


Hide on Exit property

 Restrictions	  Related Topics	 All Properties

Description

For a modeless window, determines whether Form Builder hides the window automatically when the end user navigates to an item in another window.

Applies to  window

Set  Form Builder, programmatically

Refer to Built-in

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY

Default

No


Hide on Exit restrictions property
Hide on Exit restrictions

•	Cannot be set for a root window: a root window always remains visible when the end user navigates to an item in another window.


Highest Allowed Value/Lowest Allowed Value
Highest Allowed Value/Lowest Allowed Value property

  Related Topics	 All Properties

Description

Determines the maximum value or minimum value, inclusive, that Form Builder allows in the text item.

Applies to  text item

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Required/Optional  optional

Usage Notes

•	The following values are valid for range settings:

•	any valid constant

•	form item (:block_name.item_name)

•	global variable (:GLOBAL.my_global)

•	form parameter (:PARAMETER.my_param)

•	Form Builder evaluates the values in items by data type, as follows:

ALPHA	alphabetical according to your system's collating sequence

CHAR	alphabetical according to your system's collating sequence

DATE	chronological

DATETIME	chronological

INT	numerical ascending

NUMBER	numerical ascending

•	For all items, you can enter dates in either:

•	the default format for your NLS_LANG setting or

•	the format you specified as a format mask

•	For compatibility with prior releases, a reference to a form item or to a sequence may be specified with a leading ampersand (&) instead of a leading colon (:).

•	To specify a raw value that begins with a leading ampersand (‘&’) or a leading colon (‘:’), specify two of them (that is, ‘&&’ or ‘::’).  (This is a change in Forms behavior, beginning with Release 6.5.)


Hint properties

 All Properties

Hint (Item) property

Hint (Menu Item) property

Hint (Menu Substitution Parameter) property


Hint (Item) property

  Related Topics	 All Properties

Description

Specifies item-specific help text that can be displayed on the message line of the root window at runtime.  Hint text is available when the input focus is in the item.

Applies to  all items except chart items, display items, and custom items

Set  Form Builder

Refer to Built-in

•	GET_ITEM_PROPERTY (HINT_TEXT)

Default

"Enter value for: <item name>"	For an item that was created by using the Data Block Wizard
NULL	For all other items
Required/Optional  optional

Usage Notes

Leave the Hint property NULL if you do not want the item to have hint text.


Hint (Menu Item) property

 Restrictions	    Related Topics	 All Properties

Description

For a character mode application, specifies hint text for a menu item.  In pull-down and bar menu display styles, hint text is displayed on the message line when the input focus is in the menu item.

In full-screen display style, hint text, if specified, is displayed as the item descriptor, and the menu item name is ignored. (When no hint text is specified, Form Builder displays the item name as the descriptor.)

Applies to  menu item

Set  Form Builder

Required/Optional  optional


Hint (Menu Item) restrictions property
Hint (Menu Item) restrictions

•	Applies to character mode applications only.


Hint (Menu Substitution Parameter) property

  Related Topics	 All Properties

Description

Specifies a description or instruction to appear on the message line when the end user enters a value for the menu substitution parameter.

Applies to  menu substitution parameter

Set  Form Builder

Required/Optional  optional


Horizontal Justification property

 All Properties

Description

Specifies the horizontal justification of the text object as either Left, Right, Center, Start, or End.

Applies to  graphic text

Set  Form Builder

Default

Start

Required/Optional  required


Horizontal Margin property

 Show Me	 All Properties

Description

Specifies the distance between the frame's borders (left and right) and the objects within the frame.

Applies to  frame

Set  Form Builder

Default

1 char cell (or the equivalent depending on the form coordinate system)

Required/Optional  required


Horizontal Margin showme
Horizontal Margin


Horizontal Object Offset property

 Show Me	 All Properties

Description

Specifies the horizontal distance between the objects within a frame.

Applies to  frame

Set  Form Builder

Default

2 char cells (or the equivalent depending on the form coordinate system)

Required/Optional  required


Horizontal Object Offset showme
Horizontal Object Offset


Horizontal Origin property

 All Properties

Description

Specifies the horizontal position of the text object relative to its origin point as either Left, Right, or Center.

Applies to  graphic text

Set  Form Builder

Default

Left

Required/Optional  required


Horizontal Toolbar Canvas property

  Related Topics	 All Properties

Description

Specifies the canvas that should be displayed as a horizontal toolbar on the window. The canvas specified must be a horizontal toolbar canvas (Canvas Type property set to Horizontal Toolbar) and must be assigned to the current window by setting the Window property.

Applies to  window

Set  Form Builder

Default

Null

Required/Optional  required if you are creating a horizontal toolbar

Usage Notes

•	In the Properties window, the poplist for this property shows only canvases that have the Canvas Type property set to Horizontal Toolbar.

•	At runtime, Form Builder attempts to display the specified horizontal toolbar on the window. However, if more than one toolbar of the same type has been assigned to the same window (by setting the canvas Window property to point to the specified window), Form Builder may display a different toolbar in response to navigation events or programmatic control.

•	On Microsoft Windows, the specified horizontal toolbar canvas will not be displayed on the window if you have specified that it should be displayed on the MDI application window by setting the Form Horizontal Toolbar Canvas form property.


Icon Filename property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the name of the icon resource that you want to represent the iconic button, menu item, or window.

Applies to  button, menu item, window

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_MENU_ITEM_PROPERTY

•	SET_MENU_ITEM_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY

Default

NULL

Required/Optional  optional

Usage Notes

When defining the Icon Filename property, do not include the icon file extension (.ico, .xpm, etc.).  For example, enter my_icon, not my_icon.ico.

The icon filename should not end in any of the following five letters: A, L, M, S, and X. (Neither upper-case nor lower-case are allowed.) These are reserved letters used internally for icon sizing. Unexpected icon placement results may occur if your icon filename ends in any of these letters.

Use the platform-specific environment variable to indicate the directory where icon resources are located.  For example, the Microsoft Windows name for this variable is UI60_ICON.  (For more information on this variable name, refer to the Form Builder documentation for your operating system.)


Icon Filename restrictions property
Icon Filename restrictions

•	For a window, it is only valid when Minimize Allowed property set to Yes.

•	Icon resources must exist in the runtime operating system, and are not incorporated in the form definition.  For this reason, icon resource files are not portable across platforms.


Icon in Menu property

  Related Topics	 All Properties

Description

Specifies whether an icon should be displayed in the menu beside the menu item. If Yes, the Icon Filename property specifies the icon that will be displayed.

Applies to  menu item

Set  Form Builder

Default

No

Required/Optional  optional


Iconic property

 Restrictions	    Related Topics	 All Properties

Description

Specifies that a button is to be an iconic button.

Applies to  button

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Default

No

Required/Optional  optional

Usage Notes

When Iconic is Yes, the button's Icon Filename property specifies the icon resource that Form Builder should display for the button.


Iconic restrictions property
Iconic restrictions

A valid icon resource file name must be supplied.


Image Depth property

  Related Topics	 All Properties

Description

Specifies the image depth setting Form Builder applies to an image being read from or written to a file in the filesystem.  Valid values are:

•	Original

•	Monochrome

•	Gray

•	LUT  (Lookup Table)

•	RGB  (Red, Green, Blue)

Applies to  image item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	WRITE_IMAGE_FILE

Default

Original

Required/Optional  required


Image Format property

  Related Topics	 All Properties

Description

Specifies the format in which an image item will be stored in the database.  Valid values are:

•	BMP

•	CALS

•	GIF

•	JFIF

•	PICT

•	RAS

•	TIFF

•	TPIC

Applies to  image item

Set  Form Builder

Refer to Built-in

•	GET_ITEM_PROPERTY

•	WRITE_IMAGE_FILE

Default

TIFF

Required/Optional  required

Usage Notes

•	The default Oracle image storage format no longer is valid.

•	The value you set for this property will override the original format of an image when the record containing the image item is stored in the database.  For example, if an image item's Image Format property is set to GIF, and a TIFF image is pasted into the image item at runtime, the pasted image will be stored in GIF format when the record is saved to the database.


Implementation Class
Implementation Class property

  Related Topics	 All Properties

Description

Identifies the class name of a container of a JavaBean, or of a custom implementation for a control item type when you want to supply an alternate to the standard Form Builder control.

Applies to

The following control item types:

•	Bean Area

•	Check Box

•	List Item

•	Push Button

•	Radio Group

•	Text Item

Set

Form Builder

Default

None.

Required/Optional

Always required for Bean Area.  This property identifies the class name of the container of the JavaBean you are adding to the application.  (If this property is not supplied, the form’s end user will see an empty square.)

Also required for any other control item type listed above if the form is to use a customized, user-supplied implementation of that control.  This identifies the class name of the alternate control you are supplying.

Set at Runtime

No.

Usage Notes

•	The Implementation Class property is only available for those control item types listed above, not for all control item types.


Include REF Item property

 All Properties

Description

Creates a hidden item called REF for this block.  This item is used internally to coordinate master-detail relationships built on a REF link.  This item also can be used programmatically to access the object Id (OID) of a row in an object table.

Applies to

Blocks based on object tables; master-detail REF links, in particular.

Set  Form Builder

Default

Default is No.  However, when creating a relationship based on a REF pointer, Form Builder sets this property to Yes.

Required/Optional

Required for a master block in a master-detail relationship based on a REF pointer.

Usage Notes

This REF item is used to obtain the object-ids (OIDs) of the rows in an object table.

Each row in an object table is identified by a unique object id (OID).  The OID is a unique identifier for that row.  These OIDs form an implicit column in an object table.

In a REF pointer relationship between two tables, the REF column in the pointing table holds copies of the OID values (addresses) of the pointed-to table.  This forms the link between the two tables.

The Data Block wizard sets this property to Yes and creates this REF item when you  build a master-detail relationship based on a REF pointer.  The item is named REF, and is in the master block.  It is not visible to the end user.  In addition, the wizard sets the Copy_Value_From_Item property in the detail block to access this new REF.  This is how Form Builder coordinates the master-detail relationship at runtime.


Inherit Menu property

 Restrictions	 All Properties

Description

Specifies whether the window should display the current form menu on window managers that support this feature.

Applies to  window

Set  Form Builder

Default

Yes

Required/Optional  optional


Inherit Menu restrictions property
Inherit Menu restrictions

•	Not valid on Microsoft Windows.


Initial Keyboard State property

  Related Topics	 All Properties

Description

Note:  This property is specific to bidirectional National Language Support (NLS) applications.

Initial Keyboard State sets the keyboard to generate either Local or Roman characters when the item receives input focus, so the end user can begin to type immediately, without switching the keyboard state.

Value	Description
Default	Initial keyboard state is based on the value of the Reading Order property.
Local	Initial keyboard state is Local (Right To Left language).
Roman	Initial keyboard state is Roman (Left To Right language).
Applies to  display item, text item

Set  Form Builder

Usage Notes

•	Most of the time, you will use this property only for text items.

•	The end user can override the setting for Initial Keyboard State by pressing the keyboard state toggle key.


Initial Menu property

 Restrictions	 All Properties

Description

Specifies the name of the individual menu in the menu module that Form Builder should use as the main, or top-level, menu for this invocation.  End users cannot navigate above the menu specified as the starting menu.

By default, the starting menu is the menu named in the menu module property, Main Menu.  The Initial Menu property allows you to override the Main Menu property.

Applies to  form module

Set  Form Builder

Default

blank (Form Builder uses the default main menu as the starting menu)

Required/Optional  optional


Initial Menu restrictions property
Initial Menu restrictions

•	The menu specified must exist in the menu module.


Initial Value (Item) property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the default value that Form Builder should assign to the item whenever a record is created.  The default value can be one of the following:

•	raw value (216, 'TOKYO')

•	form item (:block_name.item_name)

•	global variable (:GLOBAL.my_global)

•	form parameter (:PARAMETER.my_param)

•	a sequence (:SEQUENCE.my_seq.NEXTVAL)

Applies to check boxes, display items, list items, radio groups, text items, and user areas

Set  Form Builder

Default

Null

Required/Optional  Optional for all items except radio groups, check boxes, and list items.

For a radio group, a valid Initial Value is required unless

a) 	the radio group specifies Mapping of Other Values or,

b) 	the value associated with one of the radio buttons in the group is NULL.

For a list item, a valid Initial Value is required unless

a) 	the list item specifies Mapping of Other Values or,

b) 	the value associated with one of the list elements is NULL.

For a check box, a valid Initial Value is required unless

a) 	the check box specifies Mapping of Other Values or,

b) 	the value associated with Checked or Unchecked is NULL.

Usage Notes

•	When using the default value to initialize the state of items such as check boxes, radio groups, or list items, keep in mind that the default value does not get assigned until Form Builder creates a record in the block.

•	Subordinate mirror items are initialized from the master mirror item’s Initial Value property. The ON-SEQUENCE-NUMBER trigger is also taken from the master item. If the  subordinate mirror item specifies Initial Value and ON-SEQUENCE-NUMBER, Form Builder ignores them and issues a warning.

•	At runtime, the initial value set by this property will be ignored if all of the following are true for the item (or an item that mirrors it):

•	the item is a poplist, T-list, radio group, or check box

•	there is no element corresponding to the initial value

•	the item does not allow other values

•	For compatibility with prior releases, a reference to a form item or to a sequence may be specified with a leading ampersand (&) instead of a leading colon (:).

•	To specify a raw value that begins with a leading ampersand (‘&’) or a leading colon (‘:’), specify two of them (that is, ‘&&’ or ‘::’).  (This is a change in Forms behavior, beginning with Release 6.5.)


Initial Value (Item) property restrictions

•	For a text item, the value cannot be outside the range defined by the Lowest Allowed Value and Highest Allowed Value properties.

•	For a radio group, the default value must be either the name (not the label) of one of the radio buttons, or the value associated with one of the radio buttons.  Form Builder checks first for a radio button name.

•	For a list item, the default value must be either the name of one of the list elements, or the value associated with one of the list elements.  Form Builder checks first for a list element name.


Insert Allowed (Block) property

  Related Topics	 All Properties

Description

Specifies whether records can be inserted in the block.

Applies to  block

Set  Form Builder , programatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default

Yes


Insert Allowed (Item) property

 Restrictions	    Related Topics	 All Properties

Description

Determines whether an end user can modify the value of an item in a new record (i.e., when the Record_Status is NEW or INSERT).

If you set Insert Allowed to No for an item, the user will not be able to manipulate the item in a new record.  For example, the user will not be able to type into a text item, check a check box, or select a radio button.

Applies to  text item, check box, list item, radio button, image item, custom items

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_INSTANCE_PROPERTY

•	GET_ITEM_PROPERTY

•	SET_ITEM_INSTANCE_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes

Usage Notes

•	Set Insert Allowed to No when you want the user to be able to inspect an item without being able to modify it.  For example, for a system-generated key field, you might set Insert Allowed to No to prevent modification of the key while still displaying it normally (not grayed out).

•	Set the Enabled property to No if you want to prevent an item from responding to mouse events.  Disabled items are grayed out to emphasize the fact that they are not currently applicable, while enabled items with Insert Allowed set to No allow the user to browse an item's value with the mouse or keyboard, but not to modify the item's value.

•	Insert Allowed resembles Update Allowed, which applies to records with a Record_Status of QUERY or CHANGED.  For items in database blocks, Insert Allowed, in combination with Update Allowed, lets you control whether the end user can enter or change the value displayed by an item.  For items in non-database blocks, setting Insert Allowed to No lets you create a display-only item without disabling it.

•	If Enabled or Visible is set to No (or PROPERTY_FALSE for runtime), then the items’ or item instance’s Insert Allowed property is effectively false.

•	Setting INSERT_ALLOWED to Yes (or PROPERTY_TRUE for runtime) has no effect at the item instance level unless it is set consistently at the block and item levels.  For example, your user cannot type data into an item instance if INSERT_ALLOWED is true at the instance level, but not at the item or block levels.


Insert Allowed (Item) restrictions property
Insert Allowed (Item) restrictions

•	If you are using SET_ITEM_PROPERTY to set Insert Allowed to true, then you must set item properties as follows:

•	Enabled to Yes (PROPERTY_TRUE for runtime)

•	Visible to Yes (PROPERTY_TRUE for runtime)

•	When Insert Allowed is specified at multiple levels (item instance, item, and block), the values are ANDed together. This means that setting INSERT_ALLOWED to Yes (PROPERTY_TRUE for runtime) has no effect at the item instance level unless it is set consistently at the block and item levels.  For example, your user cannot type data into an item instance if INSERT_ALLOWED is true at the instance level, but not at the item or block levels.


Insert Procedure Arguments property

  Related Topics	 All Properties

Description

Specifies the names, datatypes, and values of the arguments to pass to the procedure for inserting data into the data block.  The Insert Procedure Arguments property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Insert Procedure Name property

  Related Topics	 All Properties

Description

Specifies the name of the procedure to be used for inserting data into the data block.  The Insert Procedure Name property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Insert Procedure Result Set Columns property

  Related Topics	 All Properties

Description

Specifies the names and datatypes of the result set columns associated with the procedure for inserting data into the data block.  The Insert Procedure Result Set Columns property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Interaction Mode property

 All Properties

Description

Specifies the interaction mode for the form module. Interaction mode dictates how a user can interact with a form during a query. If Interaction Mode is set to Blocking, then users are prevented from resizing or otherwise interacting with the form until the records for a query are fetched from the database. If set to Non-Blocking, then end users can interact with the form while records are being fetched.

Non-blocking interaction mode is useful if you expect the query will be time-consuming and you want the user to be able to interrupt or cancel the query. In this mode, the Forms runtime will display a dialog that allows the user to cancel the query.

You cannot set the interaction mode programmatically, however, you can obtain the interaction mode programmatically using the GET_FORM_PROPERTY built-in.

Applies to  form module

Set  Form Builder

Refer to Built-in

•	GET_FORM_PROPERTY

Default  Blocking

Required/Optional  required


Isolation Mode property

  Related Topics	 All Properties

Description

Specifies whether or not transactions in a session will be serializable.  If Isolation Mode has the value Serializable, the end user sees a consistent view of the database for the entire length of the transaction, regardless of updates committed by other users from other sessions. If the end user queries and changes a row, and a second user updates and commits the same row from another session, the first user sees Oracle error (ORA-08177: Cannot serialize access.).

Applies to  form module

Set  Form Builder

Usage Notes

Serializable mode is best suited for an implementation where few users are performing a limited number of transactions against a large database;  in other words, an implementation where there is a low chance that two concurrent transactions will modify the same row, and where long-running transactions are queries.  For transaction-intensive implementations, leave Isolation Mode set to Read Committed (the default). Serializable mode is best used in conjunction with the block-level property Locking Mode set to Delayed.

Default

Read Committed

Required/Optional  required


Item Roles property

 Restrictions	    Related Topics	 All Properties

Description

Specifies which menu roles have access to a menu item.

Applies to  menu item

Set  Form Builder

Required/Optional  optional

Usage Notes

You can only grant access to members of those roles displayed in the roles list.  To add a role to this list, set the menu module property Module Roles.


Item Roles restrictions property
Item Roles restrictions

Valid only when the name of at least one role has been specified in the menu module roles list.


Item Type property

  Related Topics	 All Properties

Description

Specifies the type of item.  An item can be one of the following types:

•	ActiveX Control (32-bit Windows platforms)

•	Bean Area

•	Chart Item

•	Check Box

•	Display Item

•	Hierarchical Tree

•	Image

•	List Item

•	OLE Container

•	Push Button

•	Radio Group

•	Sound

•	Text  Item

•	User Area

•	VBX Control (Microsoft Windows 3.1 only)

Applies to:  items

Set:  Form Builder

Default:  Text Item

Required/Optional  required


Item_Is_Valid property

 All Properties

Description

Specifies whether an item is marked internally as valid.

Applies to  item

Set  programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

item in a new record: No;  item in a queried record: Yes

Usage Notes

•	Use Item_Is_Valid to check whether the current status of a text item is valid.

•	Set Item_Is_Valid to Yes to instruct Form Builder to treat any current data in an item as valid and skip any subsequent validation.  Set Item_Is_Valid to No to instruct Form Builder to treat any current data in a text item as invalid and subject it to subsequent validation.


Item_Tab_Page property

  Related Topics	 All Properties

Description

Specifies the tab page on which an item is placed.

Applies to  item

Refer to Built-in

•	GET_ITEM_PROPERTY

Default

None


Item_Tab_Page restrictions property
Item_Tab_Page restrictions


Join Condition property

 Examples	   Restrictions	    Related Topics	 All Properties

Description

Defines the relationship that links a record in the detail block with a record in the master block.

Applies to  relation

Set  Form Builder

Required/Optional  required for a relation object

Usage Notes

You can specify a join condition with the following entries:

•	an item name that exists in both the master block and the detail block (block_2.item_3)

•	an equating condition of two item names, where one item exists in the master block and the other item exists in the detail block

•	a combination of item names and equating conditions


Join Condition restrictions property
Join Condition restrictions

•	Maximum length for a join condition is 255 characters.


Join Condition examples property
Join Condition examples

Examples:

To link a detail block to its master block through the ORDID text item that is common to both blocks, define the following join condition:

ORDID

To link the detail block to its master block through a number of text items, define the join condition as follows:

block1.item1 = block2.item1 AND block1.item2 = block2.item2

Keep in mind that the join condition specifies the relationship between the items in each block, not between the columns in the tables on which those blocks are based. Thus, the items specified must actually exist in the form for the join condition to be valid.


Join Style property

 All Properties

Description

Specifies the join style of the graphic object as either Mitre, Bevel, or Round.

Applies to  graphic physical

Set  Form Builder

Default

Mitre

Required/Optional  optional


Justification property

 All Properties

Description

Specifies the text justification within the item. The allowable values for this property are as follows:

Value	Description
Left	Left-justified, regardless of Reading Order property.
Center	Centered, regardless of Reading Order property.
Right	Right-justified, regardless of Reading Order property.
Start	Item text is aligned with the starting edge of the item bounding box.  The starting edge depends on the value of the item's Reading Order property.   Start is evaluated as Right alignment when the reading order is Right To Left, and as Left alignment when the reading order is Left to Right.
End	Item text is aligned with the ending edge of the item bounding box.  The ending edge depends on the value of the item's Reading Order property. End is evaluated as Left alignment when the reading order is Right To Left, and as Right alignment when the reading order is Left to Right.

Applies to  display item, text item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Start

Usage Notes

•	In unidirectional applications (reading order Left to Right), accept the default, Start, in most cases.  For unidirectional applications, Start gives exactly the same results as Left and End gives the same results as Right.

•	In bidirectional applications:

•	If your data must be aligned with the item's Reading Order, choose Start (the default).

•	If your data must be aligned opposite to the item's Reading Order, choose End.

•	Unsupported by some window managers.


Keep Cursor Position property

 Restrictions	 All Properties

Description

Specifies that the cursor position be the same upon re-entering the text item as when last exited.

Applies to  text item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Usage Notes

Use this property if you want to give the end user the flexibility to move the cursor to an item, then back to the partially filled item, and have the cursor reposition itself to the end of the partial text.


Keep Cursor Position restrictions property
Keep Cursor Position restrictions

Unsupported on some window managers.


Key Mode property

 All Properties

Description

Specifies how Form Builder uniquely identifies rows in the database.  This property is included for applications that will run against non-ORACLE data sources.  For applications that will run against ORACLE, use the default setting.

By default, the ORACLE database uses unique ROWID values to identify each row.  Non-ORACLE databases do not include the ROWID construct, but instead rely solely on unique primary key values to identify unique rows.  If you are creating a form to run against a non-ORACLE data source, you must use primary keys, and set the Key Mode block property accordingly.

Value	Description
Automatic (default)	Specifies that Form Builder should use ROWID constructs to identify unique rows in the datasource but only if the datasource supports ROWID.
Non-Updateable	Specifies that Form Builder should not include primary key columns in any UPDATE statements.  Use this setting if your database does not allow primary key values to be updated.
Unique	Instructs Form Builder to use ROWID constructs to identify unique rows in an ORACLE database.
Updateable	Specifies that Form Builder should issue UPDATE statements that include primary key values.  Use this setting if your database allows primary key columns to be updated and you intend for the application to update primary key values.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default

Unique

Usage Notes

When the Key Mode property is set to one of the primary key modes, you must identify the primary key items in your form by setting the Enforce Primary Key block property to Yes for the block, and the Primary Key item property to Yes for at least one item in the block.


Keyboard Accelerator property

 Restrictions	    Related Topics	 All Properties

Description

Specifies a logical function key to be associated with a menu item.  Accelerator keys are named ACCELERATOR1, ACCELERATOR2, and so on, through ACCELERATOR5.  End users can select the menu item by pressing the key or key combination that is mapped to the logical accelerator key.

Applies to  menu item

Set  Form Builder

Required/Optional  optional

Usage Notes

The mappings of logical accelerator keys to physical device keys is defined in the runtime resource file.  You must edit the resource file in Oracle Terminal to change the key mappings.  You can also create additional accelerator keys  in Oracle Terminal (ACCELERATOR6, ACCELERATOR7, and so on), which you can then associate with menu items in a menu module.


Keyboard Accelerator restrictions property
Keyboard Accelerator restrictions

•	Not valid for separator menu items.

•	Key mappings must not interfere with standard Form Builder key mappings.

•	When running with bar-style menus, accelerator keys can be used only for items on the menu that is currently displayed.


Keyboard Help Description property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the key trigger description that is displayed in the runtime Keys help screen if the Display in Keyboard Help property is set to Yes. An entry in the Keys screen includes a text description for the key name and the physical keystroke associated with it, for example, Ctrl-S.

Applies to  trigger

Set  Form Builder

Default

blank

Usage Notes

•	If you do not want the name or the description to appear in the Keys window, set the Display Keyboard Help property to No. This is the default setting.

•	If you want the name of the key that corresponds to the trigger and its default description to be displayed in the Keys window, set the Display Keyboard Help property to Yes and leave the Keyboard Help Description blank.

•	If you want to replace the default key description, set the Display Keyboard Help property to Yes, then enter the desired description in the Keyboard Help Description field.


Keyboard Help Description restrictions property
Keyboard Help Description restrictions

Valid only for key triggers.


Keyboard Navigable property

 Restrictions	    Related Topics	 All Properties

Description

Determines whether the end user or the application can place the input focus in the item during default navigation.  When set to Yes for an item, the item is navigable.  When set to No, Form Builder skips over the item and enters the next navigable item in the default navigation sequence.  The default navigation sequence for items is defined by the order of items in the Object Navigator.

Applies to  all items except chart items and display items

Set  Form Builder, programmatically [NAVIGABLE]

Refer to Built-in

•	GET_ITEM_INSTANCE_PROPERTY

•	GET_ITEM_PROPERTY

•	SET_ITEM_INSTANCE_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes

Usage Notes

•	If Enabled or Visible is set to No (PROPERTY_FALSE for runtime), then the items’ or item instance’s Keyboard  navigable property is effectively false.  At runtime, when the Enabled property is set to PROPERTY_FALSE, the Keyboard_Navigable property is also set to PROPERTY_FALSE.  However, if the Enabled property is subsequently set back to PROPERTY_TRUE, the keyboard Navigable property is NOT set to PROPERTY_TRUE, and must be changed explicitly.

•	When Keyboard Navigable is specified at multiple levels (item instance, item, and block), the values are ANDed together. This means that setting Keyboard Navigable to Yes (or NAVIGABLE to PROPERTY_TRUE for runtime) has no effect at the item instance level unless it is set consistently at the item level.  For example, your user cannot navigate to an item instance if Keyboard Navigable is true at the instance level, but not at the item level.

•	You can use the GO_ITEM built-in procedure to navigate to an item that has its Keyboard Navigable property set to No (PROPERTY_FALSE) for runtime.


Keyboard Navigable property restrictions
Keyboard Navigable restrictions

•	If you are using SET_ITEM_PROPERTY to set NAVIGABLE to true, then you must set item properties as follows:

•	Enabled to Yes (PROPERTY_TRUE for runtime)

•	Visible to Yes (PROPERTY_TRUE for runtime)


Keyboard State property

 All Properties

Description

Specifies supported international keyboard states as Any, Roman Only, or Local Only.

Applies to  item international

Set  Form Builder

Default

Any

Required/Optional  required


Label properties

 All Properties

Label (Item) property

Label (Menu Item) property

Label (Menu Substitution Parameter) property

Label (Tab Page) property


Label (Item) property

 All Properties

Description

Specifies the text label that displays for a button, check box, or radio button in a radio group.

Applies to  button, check box, radio group button

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_ITEM_INSTANCE_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

Default

blank

Required/Optional  optional


Label (Menu Item) property

  Related Topics	 All Properties

Description

Specifies the text label for each menu item.

Applies to  menu item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_MENU_ITEM_PROPERTY

•	SET_MENU_ITEM_PROPERTY

Required/Optional  optional

Usage Notes

Each menu item has both a name and a label. The label, used only in the runtime GUI, may differ from the name, which can be used programmatically.

Unlike the name, which must follow PL/SQL naming conventions, the label can include multiple words and punctuation.  For example,More Info... is an acceptable label, while the corresponding name would be more_info.

When you create a new menu item in the Menu editor, Form Builder gives it a default name, like ITEM2, and a default label, <New Item>.  When you edit the item label in the Menu editor, making it, for instance, "Show Keys," the menu item name remains ITEM2 until you change it in either the Object Navigator or the Properties Palette.


Label (Menu Substitution Parameter) property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the label that will prompt the end user to supply a value for the substitution parameter.

Applies to  menu substitution parameter

Set  Form Builder

Required/Optional  optional


Label (Menu Substitution Parameter) restrictions property
Label (Menu Substitution Parameter) restrictions

none


Label (Tab Page) property

 Restrictions	 All Properties

Description

The label identifying the tab page.  End users click the labelled tab to display the tab pages of a tab canvas.

Applies to  tab page

Set  Form Builder, programmatically

Refer to Built-in

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

Required/Optional  optional


Label (Tab Page) restrictions property
Label (Tab Page) restrictions

none


Last_Block property

  Related Topics	 All Properties

Description

Specifies the name of the block with the highest sequence number in the form, as indicated by the sequence of blocks listed in the Object Navigator.

Applies to  form module

Set  not settable

Refer to Built-in

GET_FORM_PROPERTY


Last_Item property

  Related Topics	 All Properties

Description

Specifies the name of the item with the highest sequence number in the indicated block, as indicated by the sequence of items listed in the Object Navigator.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY


Last_Query property

 All Properties

Description

Specifies the SQL statement for the last query of the specified block.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY


Layout Data Block property

 All Properties

Description

Specifies the name of the data block which the frame is associated with;  the items within this block are arranged within the frame.  A block can only be associated with one frame.  You cannot arrange a block's items within multiple frames.

Applies to  frame

Set  Form Builder

Default

NULL

Required/Optional  required


Layout Style property

 Show Me	 All Properties

Description

Specifies the layout style for the items within the frame.

Form	The default frame style.  When Frame Style is set is to Form, Form Builder arranges the items in a two-column format, with graphic text prompts positioned to the left of each item.

Tabular	When Frame Style is set to Tabular, Form Builder arranges the items next to each other across a single row, with graphic text prompts above each item.

Applies to  frame

Set  Form Builder

Default

Form

Required/Optional  required


Layout Stle showme
Layout Styles


Length (Record Group) property

 All Properties

Description

See Column Specifications.


Line Spacing property

 All Properties

Description

Specifies the line spacing of the text objext as Single, One-and-a-half, Double, Custom.  If Custom is selected, the Custom Spacing property determines the line spacing.

Applies to  graphic text

Set  Form Builder

Default

Single

Required/Optional  required


Line Width property

 All Properties

Description

Specifies the width of the object's edge in points (1/72 inch). (Same as Graphics Builder property Edge Width.)

Applies to  graphic physical

Set  Form Builder

Required/Optional  optional


List Item Value property

 Restrictions	 All Properties

Description

Specifies the value associated with a specific radio.

Applies to  radio button

Set  Form Builder

Default

NULL

Required/Optional  required

Usage Notes

When you leave the List Item Value field blank, the value associated with the radio button is NULL.


List Item Value restrictions property
List Item Value restrictions

•	Must be unique among values associated with radio button.


List of Values property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the list of values (LOV) to attach to the text item. When an LOV is attached to a text item, end users can navigate to the item and press [List of Values] to invoke the LOV.  To alert end users that an LOV is available, Form Builder displays the LOV list lamp on the message line when the input focus is in a text item that has an attached LOV.

Applies to  text item

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Required/Optional  optional


List of Values restrictions property
List of Values restrictions

The LOV must exist in the active form module.


List Style property

 All Properties

Description

Specifies the display style for the list item, either poplist, combo box, or Tlist.  The poplist and combo box styles take up less space than a Tlist, but end users must open the poplist or combo box to see list elements.  A Tlist remains "open," and end users can see more than one value at a time if the list is large enough to display multiple values.

Applies to  list item

Set  Form Builder

Default

Poplist

Usage Notes

The display style you select for the list item has no effect on the data structure of the list item.


List Type property

 Restrictions	 All Properties

Description

Specifies how you intend to reference the record group object on which the LOV will be based.  Every LOV has an associated record group from which it derives its values at runtime.

Applies to:

List of Values (LOV)

Set  Form Builder

Default

Query

Required/Optional  required

Usage Notes

The following settings are valid for this property:

Record Group	Indicates that you intend to base the LOV on an existing record group. When you select this option, you must choose the record group in the Record Group property drop-down list.  The record group you specify can be either a static record group or a query record group, and must already exist in the active form.

Old	This option is included for compatibility with previous versions of Form Builder. It cannot be used in new applications.


List Type restrictions property
List Type restrictions

none


List X Position property

  Related Topics	 All Properties

Description

Specifies the horizontal (X) coordinate of the upper left corner of the LOV relative to the screen.  When you attach an LOV to a text item by setting the List of Values property, you can also set the List X Position and List Y Position properties to override the default display coordinates specified for the LOV.

Applies to  text item

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Default

0; indicating that Form Builder should use the default LOV display horizontal (X) coordinate, as specified by the List X Position property.

Required/Optional  required

Usage Notes

•	If you leave the List X Position property set to 0 and the List Y Position property set to 0, Form Builder displays the LOV at the display coordinates you specified when you created the LOV.  If you specify position coordinates, the coordinates you specify override the LOV's default position coordinates.

•	The List of Values property must be specified.


List Y Position property

  Related Topics	 All Properties

Description

Specifies the vertical (Y) coordinate of the upper left corner of the LOV relative to the screen.  When you attach an LOV to a text item by setting the List of Values property, you can also set the List Y Position and List X Position properties to override the default display coordinates specified for the LOV.

Applies to  text item

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Default

0; indicating that Form Builder should use the default LOV display vertical (Y) coordinate, as specified by the List Y Position property.

Required/Optional  required

Usage Notes

•	If you leave the List X Position property set to 0 and the List Y Position property set to 0, Form Builder displays the LOV at the display coordinates you specified when you created the LOV.  If you specify position coordinates, the coordinates you specify override the LOV's default position coordinates.

•	The List of Values property must be specified.


Listed in Data Block Menu/Data Block Description

 Restrictions

Specifies whether the block should be listed in the block menu and, if so, the description that should be used for the block.

Form Builder has a built-in block menu that allows end users to invoke a list of blocks in the current form by pressing [Block Menu].  When the end user selects a block from the list, Form Builder navigates to the first enterable item in the block.

Applies to  block

Set  Form Builder

Default

Yes.  Block Description:  For a new block, NULL; For an existing block, the block name at the time the block was created.

Required/Optional  optional


Listed in Block Menu/Block Description restrictions

The block does not appear in the Block Menu if you set the Listed in Block Menu property to Yes but leave the Block Description property blank.


Lock Procedure Arguments property

  Related Topics	 All Properties

Description

Specifies the names, datatypes, and values of the arguments that are to be passed to the procedure for locking data.  The Lock Procedure Arguments property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Lock Procedure Name property

  Related Topics	 All Properties

Description

Specifies the name of the procedure to be used for locking data.  The Lock Procedure Name property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Lock Procedure Result Set Columns property

  Related Topics	 All Properties

Description

Specifies the names and datatypes of the result set columns associated with the procedure for locking data.  The Lock Procedure Result Set Columns property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Lock Record property

 Restrictions	 All Properties

Description

Specifies that Form Builder should attempt to lock the row in the database that corresponds to the current record in the block whenever the text item's value is modified, either by the end user or programmatically.

Applies to  text item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Usage Notes

•	Set this property to Yes when the text item is a control item (an item not associated with a base table column), but you still want Form Builder to lock the row in the database that corresponds to the current record in the block.

•	Useful for lookup text items where locking underlying record is required.

•	To set the Lock Record property with SET_ITEM_PROPERTY, use the constant LOCK_RECORD_ON_CHANGE.


Lock Record restrictions property
Lock Record restrictions

Valid only when the item is a control item (Base Table Item property set to No) in a data block.


Locking Mode property

 All Properties

Description

Specifies when Form Builder tries to obtain database locks on rows that correspond to queried records in the form.  The following table describes the allowed settings for the Locking Mode property:

Value	Description
Automatic (default)	Identical to Immediate if the datasource is an Oracle database. For other datasources, Form Builder determines the available locking facilities and behaves as much like Immediate as possible.
Immediate	Form Builder locks the corresponding row as soon as the end user presses a key to enter or edit the value in a text item.
Delayed	Form Builder locks the row only while it posts the transaction to the database, not while the end user is editing the record.  Form Builder prevents the commit action from processing if values of the fields in the block have changed when the user causes a commit action.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default

Automatic

Usage Notes

For most applications use the default setting of Automatic.

The Immediate setting remains for compatibility with existing applications, but there is no reason to use it in new applications.  Use Automatic instead.

The Delayed setting is useful for applications that must minimize the number of locks or the amount of time that rows remain locked.  Use delayed locking if the form's Isolation Mode property has the value Serializable.

The main drawbacks of delayed locking are

•	The changes an end user makes to a block may need to be redone at commit time.

•	Another user's lock can force the first end user to choose between waiting indefinitely or abandoning the changes.


Magic Item property

 Restrictions	    Related Topics	 All Properties

Description

Specifies one of the the following predefined menu items for custom menus:  Cut, Copy, Paste, Clear, Undo, About, Help, Quit, or Window.  Magic menu items are automatically displayed in the native style for the platform on which the form is being executed, with the appropriate accelerator key assigned.

Cut, Copy, Paste, Clear, Window,  and Quit have built-in functionality supplied by Form Builder, while the other magic menu items can have commands associated with them.

Applies to  menu item

Set  Form Builder

Default

Cut

Required/Optional  optional

Usage Notes

The following settings are valid for this property:

Setting	Description
Cut, Copy, Paste, Clear	These items perform the usual text-manipulation operations.  Form Builder supplies their functionality, so the designer may not enter a command for these items.
Undo, About	These items have no native functionality, so the designer must enter a command for these items.  Any type of command can be used for these items, except Menu.
Help	The command for the Help menu item must be Menu.  The designer provides the functionality of items on this submenu.
Quit	Quit also has built-in functionality, so the designer may not assign a command to this item.
Window	The Window magic menu item presents a submenu of all open windows, allowing the user to activate any of them.  If the Window magic menu item has a command that invokes a submenu, that submenu will contain both the list of open widows and the user-defined submenu items, in an order determined by Form Builder.  The command type for a magic Window item is Null or Menu.


Magic Item restrictions property
Magic Item restrictions

•	Any given magic menu item may appear only once in the entire menu  hierarchy for a given menu module.  For example, a menu containing the magic menu item Cut cannot be a submenu of two different options in the menu module.

•	Leave the magic menu item's Icon, Keyboard Accelerator, and Hint properties blank.


Main Menu property

  Related Topics	 All Properties

Description

Specifies the name of the individual menu in the document that is to be the main or starting menu at runtime.

If you are creating a pulldown menu, you will not need to change this property:  it is automatically set to the name of the first menu you create, and updated thereafter if you change the name of that menu.

The Main Menu property is used mostly with full-screen menus, to limit the menus to which end users have access.  End users cannot navigate to any menu that is above the main menu in the menu module hierarchy.

Applies to  menu module

Set  Form Builder

Default

blank

Required/Optional  required

Usage Notes

When you attach the menu module to a form by setting the appropriate properties in the Form Module property sheet, you can specify a different menu in the document to be the main menu by setting the Initial Menu property.


Mapping of Other Values property

  Related Topics	 All Properties

Description

Specifies how any fetched or assigned value that is not one of the pre-defined values associated with a specific list element or radio button should be interpreted.

Applies to  list item, radio group

Set  Form Builder

Default

blank

Required/Optional  optional

Usage Notes

•	Leave this property blank to indicate that other values are not allowed for this item or radio group. Any queried record that contains a value other than the user-defined element value is silently rejected.  Any attempt to assign an other value is disallowed.

•	Any value you specify must evaluate to one of the following references:

•	the value associated with one of the list elements or radio groups

•	the name (not the label) of one of the list elements


Maximize Allowed property

 Restrictions	 All Properties

Description

Specifies that end users can resize the window by using the zooming capabilities provided by the runtime window manager.

Applies to  window

Set  Form Builder

Default

Yes


Maximize Allowed restrictions property
Maximize Allowed restrictions

•	Only valid when Resize Allowed is set to No


Maximum Length property

 All Properties

Description

Specifies the maximum length of the data value that can be stored in the item.

Applies to  all items except buttons, image items, and chart items

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Default

•	For a database item, the length of the corresponding column in the database table. Note: If the item's data type is NUMBER, the maximum length will be set to the defined column length plus two, to allow for the possible use of a minus sign (for negative values) and a decimal separator.

•	For a control item, 30.

•	For a LONG item, 240 bytes.

Required/Optional  required

Usage Notes

1	At runtime, Forms will increase the value of the Maximum Length property if the item’s format mask requires a longer length.  (The format mask may be either an explicit mask specified by the form’s designer for this item, or one of the implicit masks used by Forms in its internal conversion operations.)

2	For CHAR values, the Maximum Length is 2000 characters.

Note:  Bear these considerations in mind if you are writing applications for a multi-byte character set:

•	Form Builder allows end users to enter the full number of single-byte characters, up to the Maximum Length specified.

•	If the end user enters a combination of single-byte and multi-byte characters that produce a string whose total length in bytes exceeds the item's Maximum Length, the string will be truncated to the nearest whole character and a warning will be displayed.  To avoid this situation, consider raising the Maximum Length for the item.  (If Maximum Length exceeds the display width of the item, Form Builder will automatically allow the end user to scroll the contents of the item.)


Maximum Length (Form Parameter) property

 Restrictions	 All Properties

Description

Specifies the maximum length, in characters, of a form parameter of type CHAR.

Applies to  form parameter

Set  Form Builder

Default

For a parameter of type CHAR, 30

Required/Optional  required


Maximum Length (Form Parameter) restrictions property
Maximum Length (Form Parameter) restrictions

•	Maximum length of a CHAR parameter is 2000 bytes.


Maximum Length (Menu Substitution Parameter) property

  Related Topics	 All Properties

Description

Specifies the maximum length, in characters, of a menu substitution parameter.

Applies to  menu substitution parameter

Set  Form Builder

Default

30

Required/Optional  required


Maximum Objects Per Line property

 All Properties

Description

Specifies the maximum number of objects that can appear on each line within a frame.

When the Maximum Number of Frame Objects is set to 0 (the default), there is no maximum--Form Builder arranges the maximum number of objects per line within a frame.

This property is valid when the Frame Style property is set to Form and the Vertical Fill property is set to No.

Applies to  frame

Set  Form Builder

Default

0

Required/Optional  required


Maximum Query Time property

 All Properties

Description

Provides the option to abort a query when the elapsed time of the query exceeds the value of this property.

Applies to  form, block

Set  Form Builder, Programmatically

Refer to Built-in

•	GET_FORM_PROPERTY

•	GET_BLOCK_PROPERTY

Required/Optional  optional

Usage Notes

This property is only useful when the Query All Records property is set to Yes.


Maximum Records Fetched property

 All Properties

Description

Specifies the number of records fetched when running a query before the query is aborted.

Applies to  form, block

Set  Form Builder, Programmatically

Refer to Built-in

•	GET_FORM_PROPERTY

•	GET_BLOCK_PROPERTY

Required/Optional  optional

Usage Notes

Maximum Records Fetched is only useful when the properties Query Allowed and Query All Records are set to Yes.  Set the Maximum Records Fetched property to limit the records returned by a user's query.


Menu Description property

 Restrictions	    Related Topics	 All Properties

Description

For applications running on character mode in the pull-down and bar menu display styles, this property specifies the string that displays on the message line when the end user navigates to the menu.  In full-screen display style, this property specifies the string that identifies the menu module.

Applies to  menu module

Set  Form Builder

Default

The default document name

Required/Optional  optional


Menu Description restrictions property
Menu Description restrictions

•	Applicable for character mode applications only.


Menu Directory property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the directory in which Form Builder should look for the .MMX runtime menu file.  This property is applicable only when you want Form Builder to locate the menu .MMX runfile through database lookup, rather than direct reference.

When using database lookup, the menu module must be stored in the database.  At runtime, Form Builder queries the menu module definition stored in the database to find out the directory and filename of the menu .MMX runfile.  The Menu Directory and Menu Filename menu module properties specify the path where Form Builder should look for the .MMX menu file.

Applies to  menu module

Set  Form Builder

Default

blank

Required/Optional  optional

Usage Notes

If you leave the directory path unspecified, Form Builder first searches the default directory for the file, then searches any predefined search paths.  For more information on search paths, refer to the Form Builder documentation for your platform.


Menu Directory restrictions property
Menu Directory restrictions

Not valid when using direct reference to specify the location of the menu .MMX runfile.  You use direct reference when you attach a menu to a form by setting the Menu Source form module property to Yes.


Menu Filename property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the name of the .MMX runtime menu file that Form Builder should look for at form startup.  This property is applicable only when you want Form Builder to locate the menu runfile through database lookup, rather than direct reference.

To use database lookup, the menu module must be stored in the database.  At runtime, Form Builder queries the menu module definition stored in the database to find out the directory and filename of the menu .MMX runfile.  The Menu Directory and Menu Filename menu module properties specify the path where Form Builder should look for the .MMX menu file.

Applies to  menu module

Set  Form Builder

Default

Module Name property

Required/Optional  required

Usage Notes

If you leave the directory unspecified, Form Builder first searches the default directory for the file, then searches any predefined search paths.  For more information on search paths, refer to the Form Builder documentation for your platform.


Menu Filename restrictions property
Menu Filename restrictions

•	The .MMX file extension is not required.


Menu Item Code property

 All Properties

Description

Contains the PL/SQL commands for a menu item.

Applies to  menu items

Set  Form Builder

Required/Optional  required

Usage Notes

Clicking the More… button opens the PL/SQL Editor for the menu item, allowing you to edit the PL/SQL commands.


Menu Item Radio Group property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the name of the radio group to which the current radio menu item belongs.

Applies to  menu item

Set  Form Builder

Required/Optional  required

Usage Notes

Specify the same Radio Group for all radio items that belong to the same logical set.


Menu Item Radio Group restrictions property
Menu Item Radio Group restrictions

•	Radio items must be adjacent to each other on the same menu.

•	Only one radio group per individual menu is allowed.


Menu Item Type property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the type of menu item: Plain, Check, Magic, Radio, or Separator.  The type determines how the item is displayed and whether the item can have an associated command.

Applies to:

menu items

Set  Form Builder

Default

Plain

Usage Notes

The following menu item types are available:

PlaiDefault.	Standard text menu item.

Check	Indicates a Boolean menu item that is either Yes or No, checked or unchecked.

Whenever the end user selects a Check menu item Form Builder toggles the state of that item and executes the command associated with that menu item, if there is one.

Magic	Indicates one of the the following predefined menu items:  Cut, Copy, Paste, Clear, Undo, About, Help, Quit, and Window.  Magic menu items are automatically displayed in the native style of the platform on which the form is executed, in the position determined by the platform's conventions, with the appropriate accelerator key assigned.  Cut,  Copy, Paste, Clear, Windows, and Quit have built-in functionality supplied by Form Builder, while the other magic menu items require that commands be associated with them.

Radio	Indicates a BOOLEAN menu item that is part of a radio group.  Enter a radio group name in the Radio Group property field. One and only one Radio menu item in a group is selected at any given time.

When the end user selects a Radio menu item,  Form Builder toggles the selection state of the item and executes its command, if there is one.

Separator	A line or other cosmetic item.  You specify a Separator menu item for the purpose of separating other menu items on the menu.  A Separator menu item cannot be selected and therefore it cannot have a command associated with it.

•	You can use GET_MENU_ITEM_PROPERTY and SET_MENU_ITEM_PROPERTY to get and set the state of check and radio menu items.

•	Magic menu items Cut, Copy, Clear, and Paste are automatically enabled and disabled by Form Builder.  You can also use GET_MENU_ITEM_PROPERTY and SET_MENU_ITEM_PROPERTY to get and set the state of magic menu items programmatically, but the result of disabling magic menu items will vary, depending on the behavior of the native platform.


Menu Item Type restrictions property
Menu Item Type restrictions

The top-level menu should only have plain or magic menu items.


Menu Module property

  Related Topics	 All Properties

Description

Specifies the name of the menu to use with this form.  When this property is set to Default, Form Builder runs the form with the default menu that is built in to every form.  When left NULL, Form Builder runs the form without any menu.

When any value other than Default or Null is specified, the Menu Source property determines how the Menu Module property setting is interpreted:

•	When the Menu Source property is Yes, the Menu Module property specifies the name of the menu .MMX runfile that Form Builder should use with this form.

•	When the Menu Source property is No, it specifies the name of the menu module in the database that Form Builder should query at form startup to find out the name of the menu .MMX file to use with this form.

Applies to  form module

Set  Form Builder

Default

Default, indicating that Form Builder should run the form with the default form menu.

Required/Optional  optional


Menu Role property

  Related Topics	 All Properties

Description

Specifies the security role that Form Builder should use to run the menu.  When the Menu Role property is specified, Form Builder runs the indicated menu as if the current end user were a member of the security role specified.

Applies to  form module

Set  Form Builder

Required/Optional  optional

Usage Notes

The Menu Role property is included for backward compatibility only.  Its use is not recommended in current applications.

In previous versions of Form Builder, the Menu Role property allowed designers to test a menu by creating a master role that had access to all of the items in the menu, and then running the menu under that role. You can obtain the same result by setting the menu module property Use Security to No.  When Use Security is No, all end users have access to all menu items, and you do not have to be a member of any particular role to test your application.


Menu Source property

  Related Topics	 All Properties

Description

Menu Source allows you to specify the location of the .MMX runfile when you attach a custom menu to a form module.  Form Builder loads the .MMX file at form startup.

Applies to  form module

Set  Form Builder

Default

Yes

Required/Optional  optional

Usage Notes

Setting the Menu Source property allows you to specify the location of the menu .MMX runfile through either direct reference or through database lookup.  In most cases, you will want to use direct reference to the file system.  Database lookup is included for backward compatibility.

Direct Reference	To refer directly to the .MMX file, set the Menu Source property to Yes, then enter the path/filename of the .MMX file in the Menu Module field.
Database Lookup	To refer to the menu by way of database lookup, set the Menu Source property to No, then enter the name of the menu module stored in the database.  At form startup, Form Builder queries the menu module definition to look up the name of the .MMX runfile it needs. (The Menu Module Menu Filename and Menu Directory define the path to the .MMX file in the file system.) When the form is loaded at runtime, Form Builder locates the .MMX file by querying the database to look up the pointer to the .MMX file defined by the menu module Menu Filename and Menu Directory properties.
The following table compares the property settings and database conditions required when attaching a menu to a form through direct reference to those required for database lookup.

Condition or Property	Direct Reference	Database Lookup
Form Module Property: "Menu Source"	Yes	No
Form Module Property: "Menu Module"	Name of .MMX runfile	Name of .MMB menu design document in database
Menu Module Property: "Menu Directory/Menu Filename"	n/a	Path/filename of .MMX file in file system
Database Connection	Not required	Required at form startup
Location of Menu .MMB at Load Time	n/a	Must be stored in database
The following diagrams compare using direct reference and database lookup when attaching a custom menu to a form.


Menu Style property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the menu display style Form Builder should use to run the custom menu specified by the Menu Module property.  Display style options are pull-down or bar.

Applies to  form module

Set  Form Builder

Default

Pull-down

Required/Optional  optional


Menu Style restrictions property
Menu Style restrictions

Not valid when the Menu Module property is set to DEFAULT.  (The default menu runs only in pull-down display style.)


Message property

 Restrictions	 All Properties

Description

Specifies the message that is to be displayed in an alert.

Applies to  alert

Set  Form Builder, programmatically

Refer to Built-in

SET_ALERT_PROPERTY

Required/Optional  optional


Message restrictions property
Message restrictions

Maximum of 200 characters.  Note, however, that several factors affect the maximum number of characters displayed, including the font chosen and the limitations of the runtime window manager.


Minimize Allowed property

 Restrictions	    Related Topics	 All Properties

Description

Specifies that a window can be iconified on window managers that support this feature.

Applies to  window

Set  Form Builder

Default

Yes

Required/Optional  optional


Minimize Allowed restrictions property
Minimize Allowed restrictions

Cannot be set for a root window: a root window is always iconifiable.


Minimized Title property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the text string that should appear below an iconified window.

Applies to  window

Set  Form Builder

Default

No

Required/Optional  optional


Minimized Title restrictions property
Minimized Title restrictions

Only applicable when the Minimize Allowed property is set to Yes.


Modal property

 Restrictions	    Related Topics	 All Properties

Description

Specifies whether a window is to be modal.  Modal windows require an end user to dismiss the window before any other user interaction can continue.

Applies to  window

Set  Form Builder

Default

No


Modal restrictions property
Modal restrictions

•	When Modal is set to Yes, the following window properties are ignored:

• Close Allowed	• Resize Allowed
• Icon Filename	• Minimized Title
• Minimize Allowed	• Inherit Menu
• Move Allowed	• Maximize Allowed
• Show Vertical/Horizontal Scroll Bar


Module_NLS_Lang property

 All Properties

Description

Specifies the complete current value of the NLS_LANG environment variable defined for the form, for national language support.  MODULE_NLS_LANG is the equivalent of concatenating the following properties:

•	MODULE_NLS_LANGUAGE (language only)

•	MODULE_NLS_TERRITORY (territory only)

•	MODULE_NLS_CHARACTER_SET (character set only)

Applies to  form

Set  Not settable from within Form Builder.  Set at your operating system level.

Refer to Built-in

GET_FORM_PROPERTY

Default

Default is usually "America_American.WE8ISO8859P1," but all the defaults can be port-specific.


Module Roles property

  Related Topics	 All Properties

Description

Specifies which database roles are available for items in this menu module.

Applies to  menu module

Set  Form Builder

Required/Optional  optional

Usage Notes

Use Menu Module Roles to construct the entire list of roles with access to this menu module, then use Menu Item Roles to specify which of these roles should have access to a specific menu item.


Mouse Navigate property

 Restrictions	    Related Topics	 All Properties

Description

Specifies whether Form Builder should perform navigation to the item when the end user activates the item with a mouse.

Applies to  button, check box, list item, radio group

Set  Form Builder

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes

Usage Notes

When Mouse Navigate is No, Form Builder does not perform navigation to the item when the end user activates it with the mouse.  For example, a mouse click in a button or check box is not treated as a navigational event.  Form Builder fires any triggers defined for the button or check box (such as When-Button-Pressed), but the input focus remains in the current item.

When Mouse Navigate is Yes, Form Builder navigates to the item, firing any appropriate navigation and validation triggers on the way.


Mouse Navigate restrictions property
Mouse Navigate restrictions

Applies only in mouse-driven environments.


Mouse Navigation Limit property

 All Properties

Description

Determines how far outside the current item an end user can navigate with the mouse.  Mouse Navigation Limit can be set to the following settings:

Form 	(The default.) Allows end users to navigate to any item in the current form.

Block 	Allows end users to navigate only to items that are within the current block.

Record 	Allows end users to navigate only to items that are within the current record.

Item 	Prevents end users from navigating out of the current item.  This setting prevents end users from navigating with the mouse at all.

Applies to  form

Set  Form Builder

Default

Form


Move Allowed property

 Restrictions	    Related Topics	 All Properties

Description

Specifies whether or not the window can be moved .

Windows can be moved from one location to another on the screen by the end user or programmatically by way of the appropriate built-in subprogram.

Applies to  window

Set  Form Builder

Default

Yes

Required/Optional  optional

Usage Notes

In general, it is recommended that windows always be movable.


Move Allowed restrictions property
Move Allowed restrictions

Cannot be set to NO for a window with the name of ROOT_WINDOW.  Such a window is always movable.


Multi-Line property

 Restrictions	    Related Topics	 All Properties

Description

Determines whether the text item is a single-line or multi-line editing region.

Applies to  text item

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Default

No

Usage Notes

Setting the Multi-line property Yes allows a text item to store multiple lines of text, but it does not automatically make the item large enough to display multiple lines.  It is up to you to set the Width, Height, Font Size, and Maximum Length properties to ensure that the desired number of lines and characters are displayed.

Single-line	Pressing the carriage return key while the input focus is in a single-line text item initiates a [Next Item] function.

Multi-line	Pressing the carriage return key while the input focus is in a multi-line text item starts a new line in the item.


Multi-Line restrictions

Valid only for text items with data type CHAR, ALPHA, or LONG.


Multi-Selection property

 All Properties

Description

Indicates whether multiple nodes may be selected at one time. If set to FALSE, attempting to select a second node will deselect the first node, leaving only the second node selected.

Applies to  hierarchical tree

Set  Form Builder

Default

False

Required/Optional  required


Name property

 Examples	   Restrictions	    Related Topics	 All Properties

Description

Specifies the internal name of the object.  Every object must have a valid name that conforms to Oracle naming conventions.

Applies to  all objects

Set  Form Builder

Default

OBJECT_CLASS_N, where OBJECT_CLASS is the type of object, and N is the next available number in the document; for example, BLOCK5 or EDITOR3.

Required/Optional  required

Usage Notes

For menu items and radio buttons, the Name property has unique characteristics:

•	The Name property specifies an internal handle that does not display at runtime.

•	The Name property is used to refer to the menu item or radio button in PL/SQL code.

•	The Label property specifies the text label that displays for the menu item or current radio button.

For menu substitution parameters, the following restrictions apply:

•	Restricted to a two-character identifier for the substitution parameter.

•	Must be alphanumeric.

•	Must start with an alphabetic character.

•	When referencing the parameter in a menu command line, the parameter must be preceded by an ampersand (&RN)

•	In a PL/SQL reference, the parameter must be preceded by a colon (:SS).


Name restrictions property
Name restrictions

•	Can be up to 30 characters long

•	Must begin with a letter

•	Can contain letters, numbers, and the special characters $, #, @ and _ (underscore)

•	Are not case sensitive

•	Must uniquely identify the object:

•	Item names must be unique among item names in the same block

•	Relation names must be unique among relations that have the same master block

•	Cannot be set for the root window


Name examples property
Name examples

Example

ENAME, ADDRESS1, PHONE_NO1


Navigation Style property

  Related Topics	 All Properties

Description

Determines how a Next Item or Previous Item operation is processed when the input focus is in the last navigable item or first navigable item in the block, respectively.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default

Same Record

Usage Notes

The following settings are valid for this property:

Same Record	The default navigation style.  A Next Item operation from the block's last navigable item moves the input focus to the first navigable item in the block, in that same record.

Change Record	A Next Item operation from the block's last navigable item moves the input focus to the first navigable item in the block, in the next record.  If the current record is the last record in the block and there is no open query, Form Builder creates a new record.  If there is an open query in the block (the block contains queried records), Form Builder retrieves additional records as needed.

Change Block	A Next Item operation from the block's last navigable item moves the input focus to the first navigable item in the first record of the next block.  Similarly, a Previous Item operation from the first navigable item in the block moves the input focus to the last item in the current record of the previous block.  The Next Navigation Block and Previous Navigation Block properties can be set to redefine a block's "next" or "previous" navigation block.


Next Navigation Block property

  Related Topics	 All Properties

Description

Specifies the name of the block that is defined as the"next navigation block" with respect to this block.  By default, this is the block with the next higher sequence number in the form, as indicated by the order of blocks listed in the Object Navigator.  However,  you can set this property to redefine a block's "next" block for navigation purposes.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default

The name of the block with the next higher sequence number, as indicated by the order of blocks listed in the Object Navigator.

Required/Optional  optional

Usage Notes

Setting this property does not change the value of the NextBlock property.


Next Navigation Item property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the name of the item that is defined as the "next navigation item" with respect to this current item.  By default, the next navigation item is the item with the next higher sequence as indicated by the order of items in the Object Navigator.  However, you can set this property to redefine the "next item" for navigation purposes.

Applies to  item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

NULL.  NULL indicates the default sequence, which is the name of the item with the next higher sequence number.


Next Navigation Item restrictions property
Next Navigation Item restrictions

The item specified as Next Navigation Item must be in the same block as the current item.


NextBlock property

  Related Topics	 All Properties

Description

Specifies the name of the block with the next higher sequence number in the form, as indicated by the order of blocks listed in the Object Navigator.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY

Usage Notes

•	You can programmatically visit all of the blocks in a form by using GET_BLOCK_PROPERTY to determine the First_Block and NextBlock values.

•	The value of NextBlock is NULL when there is no block with a higher sequence number than the current block.

•	Setting the Next Navigation Block property has no effect on the value of NextBlock.


NextItem property

  Related Topics	 All Properties

Description

Specifies the name of the item with the next higher sequence number in the block, as indicated by the order of items listed in the Object Navigator.

Applies to  item

Set  not settable

Refer to Built-in

GET_ITEM_PROPERTY


Next_Detail_Relation property

  Related Topics	 All Properties

Description

Returns the name of the relation that has the same detail block as the specified relation.  If no such relation exists, returns NULL.

Applies to  relation

Set  not settable

Refer to Built-in

GET_RELATION_PROPERTY

Usage Notes

Use this property with the FIRST_DETAIL_RELATION property to traverse a list of relations for a given master block.


Next_Master_Relation property

  Related Topics	 All Properties

Description

Returns the name of the next relation that has the same master block as the specified relation.  If no such relation exists, returns NULL.

Applies to  relation

Set  not settable

Refer to Built-in

GET_RELATION_PROPERTY

Usage Notes

Use this property with the FIRST_MASTER_RELATION property to traverse a list of relations for a given master block.


Number of Items Displayed property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the number of item instances displayed for the item when the item is in a multi-record block.

Setting Number of Items Displayed > 0 overrides the Number of Records Displayed block property.

Applies to  item

Set  Form Builder

Default

Zero.  Zero indicates that the item should display the number of instances specified by the Number of Records Displayed block property.

Required/Optional  optional

Usage:

Use Number of Items Displayed to create a single button, chart, OLE item, image, VBX control (in 16-bit Microsoft Windows), or ActiveX control (in 32-bit Windows) as part of a multi-record block.   For instance, if Number of Records Displayed is set to 5 to create a multi-record block and you create a button, by default you will get 5 buttons, one per record.  To get only one button, set Number of Items Displayed to 1.


Number of Items Displayed restrictions property
Number of Items Displayed restrictions

Number of Items Displayed must be <= Number of Records Displayed block property setting.


Number of Records Buffered property

 Restrictions	 All Properties

Description

Specifies the minimum number of records buffered in memory during a query in the block.

Applies to  block

Set  Form Builder

Default

NULL; which indicates the minimum setting allowed (the value set for the Number of Records Displayed property plus a constant of 3).

Required/Optional  optional

Usage Notes

•	Form Builder buffers any additional records beyond the maximum to a temporary file on disk.

•	Improve processing speed by increasing the number of records buffered.

•	Save memory by decreasing the number of records buffered.  This can, however, result in slower disk I/O.

•	If you anticipate that the block may contain a large number of records either as the result of a query or of heavy data entry, consider raising the Number of Records Buffered property to increase performance.

•	Consider lowering the Number of Records Buffered property if you anticipate retrieving large items, such as image items, because of the amount of memory each item buffered may require.


Number of Records Buffered restrictions property
Number of Records Buffered restrictions

•	If you specify a number lower than the minimum, Form Builder returns an error when you attempt to accept the value.


Number of Records Displayed property

 All Properties

Description

Specifies the maximum number of records that the block can display at one time.  The default is 1 record.  Setting Number of Records Displayed greater than 1 creates a multi-record block.

Applies to  block

Set  Form Builder

Refer to Built-in

GET_BLOCK_PROPERTY

Default

1

Required/Optional  required


OLE Activation Style property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the event that will activate the OLE containing item.

Applies to  OLE Container

Set  Form Builder

Default

Double Click

Usage Notes

The following settings are valid for this property:

Double Click	The default OLE activation style.  An OLE object becomes active by double-clicking anywhere on the OLE object.

Focus-i 	Navigating to the OLE object causes the OLE object to become active.

Manual	An OLE object becomes active by selecting Edit or Open from the Object submenu of the OLE popup menu.  The Show OLE Popup Menu property must be set to YES and the Object menu item must be set to displayed and enabled.  The OLE popup menu is accessible when the mouse cursor is on the OLE object and the right mouse button is pressed.

If the Show OLE Popup Menu property is YES and the Object menu item is displayed and enabled, it is also possible to manually activate the OLE object through the OLE popup menu when the OLE Activation Style is Double Click or Focus-in.


OLE Activation Style restrictions property
OLE Activation Style restrictions

Valid only on Microsoft Windows and Macintosh.


OLE Class property

 Restrictions	    Related Topics	 All Properties

Description

Determines what class of OLE objects can reside in an OLE container.  The following settings are valid for this property:

NULL	The default OLE class.  You can insert any kind of OLE object class specified in the registration database in an OLE container.

other than NULL	Only OLE objects from the specified class can be inserted in an OLE container at runtime.  The OLE object classes that are available for selection depend on information contained in the registration database.  The content of the registration database is determined by the OLE server applications installed on your computer.

Applies to  OLE Container

Set  Form Builder

Default

NULL

Usage Notes

You select a specific class if you want to create an application that allows end users to change the current OLE object in the OLE container, but want to restrict the end users to creating OLE objects from a particular class.


OLE Class restrictions property
OLE Class restrictions

Valid only on Microsoft Windows and Macintosh.


OLE In-place Activation

 Restrictions	    Related Topics	 All Properties

Description

Specifies if OLE in-place activation is used for editing embedded OLE objects.  The following settings are valid for this property:

YES	Turns on OLE in-place activation.  OLE in-place activation is used for editing embedded OLE objects; linked objects are activated with external activation.

NO	Turns off OLE in-place activation and turns on external activation.  External Activation is used for editing embedded or linked OLE objects.

Applies to  OLE Container

Set  Form Builder

Default

NO


OLE In-place Activation restrictions

•	Valid only on Microsoft Windows and Macintosh.


OLE Inside-Out Support

 Restrictions	    Related Topics	 All Properties

Description

Specifies if the OLE server of the embedded object allows inside-out object support during in-place activation.  Inside-out activation allows for more than one embedded object to have an active editing window within an OLE container.  The following settings are valid for this property:

YES	Turns on inside-out object support for embedded objects that have the OLE In-place Activation property set to Yes.

NO	Turns off inside-out object support for embedded objects that have the OLE in-place Activation property set to Yes.

Applies to  OLE Container

Set  Form Builder

Default

YES


OLE Inside-Out Support restrictions

•	Valid only on Microsoft Windows and Macintosh.


OLE Popup Menu Items property

 Restrictions	    Related Topics	 All Properties

Description

Determines which OLE popup menu commands are displayed and enabled when the mouse cursor is on the OLE object and and the right mouse button is pressed.  The OLE popup menu commands manipulate OLE objects.  OLE popup menu commands and their actions include:

OLE Popup Menu Command	Action
CUT	Cuts an OLE object and places the content on the clipboard.
COPY	Copies an OLE object and places the content on the clipboard.
PASTE	Pastes the content from the clipboard to an OLE container.
PASTE SPECIAL	Pastes an OLE object from the clipboard to an OLE container in a format other than the original format.
INSERT OBJECT	Inserts an OLE object in an OLE container.
DELETE OBJECT	Deletes an OLE object from an OLE container.
LINKS	Invokes a dialog that has settings to determine how links are updated, edit linked source files, and change links from one source file to another source file.
OBJECT	Depending on the OLE server, it is possible to perform various operations on an OLE object.  Some examples include opening an OLE object, editing an OLE object, and converting an OLE object from one format to another.
Applies to  OLE Container

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Display On and Enable On for all menu commands

Required/Optional  required

Usage Notes

•	In the Form Builder, you can set each OLE popup menu command to exhibit the following characteristics by selecting the appropriate check box:

Display	Specifies whether the selected menu command is displayed.

Enable	Specifies whether a menu command that has  Display On is enabled or disabled.  A disabled item appears dimmed or grayed.

•	In addition to setting OLE popup menu command properties in the Form Builder, you can set and get OLE popup menu command properties programmatically.  To set or get the OLE popup menu commands programmatically, use a programmatic property name that corresponds to a menu command. The following list includes each of the OLE popup menu commands and a corresponding programmatic property name:

Menu Command	Programmatic Property Name
Cut	POPUPMENU_CUT_ITEM
Copy	POPUPMENU_COPY_ITEM
Paste	POPUPMENU_PASTE_ITEM
Paste Special	POPUPMENU_PASTESPEC_ITEM
Insert Object	POPUPMENU_INSOBJ_ITEM
Delete Object	POPUPMENU DELOBJ ITEM
Links	POPUPMENU_LINKS_ITEM
Object	POPUPMENU_OBJECT_ITEM
You can programmatically set the OLE popup menu command properties to any of the following values:

DISPLAYED	Specifies that an OLE popup menu command is displayed and enabled.

ENABLED	Specifies that an OLE popup menu command is displayed and disabled.  A disabled item appears dimmed or grayed.

HIDDEN	Specifies that an OLE popup menu command is not displayed on the OLE popup menu.  A command that is not displayed is not enabled.

•	In addition to the values that you can set programmatically,  you can programmatically get the following values from each of the OLE popup menu commands:

DISPLAYED	Return value when an OLE popup menu command is displayed and enabled.

ENABLED	Return value when an OLE popup menu command is displayed and disabled.  A disabled item appears dimmed or grayed.

HIDDEN	Return value when an OLE popup menu command is not displayed on the OLE popup menu.  A command that is not displayed is not enabled.

UNSUPPORTED	Return value when the OLE popup menu is not supported.  This is the return value for every platform except Microsoft Windows.


OLE Popup Menu Items restrictions property
OLE Popup Menu Items restrictions

Valid only on Microsoft Windows.


OLE Resize Style property

 Restrictions	 All Properties

Description

Determines how an OLE object is displayed in an OLE container.  The following settings are valid for this property:

CLIP	The default OLE resize style.  An OLE object is cropped to fit into an OLE container.

SCALE	An OLE object is scaled to fit into an OLE container.

INITIAL	An OLE container is resized to fit an OLE object at creation time only.

DYNAMIC	An OLE container is resized to fit an OLE object whenever the OLE object size changes.

Applies to  OLE Container

Set  Form Builder

Required/Optional  required

Default

CLIP


OLE Resize Style restrictions property
OLE Resize Style restrictions

Valid only on Microsoft Windows and Macintosh.


OLE Tenant Aspect property

 Restrictions	    Related Topics	 All Properties

Description

Determines how an OLE object appears in an OLE container.

Applies to  OLE Container

Set  Form Builder

Default

CONTENT

Usage Notes

The following settings are valid for this property:

CONTENT	The default OLE tenant aspect.  The content of an OLE object is displayed in an OLE container.  The content of the OLE object depends on the value of the OLE Resize Style property and can either be clipped, scaled, or full size.

ICO	An icon of an OLE object is displayed in an OLE container.  The default icon is one that represents the OLE server application that created the OLE object.  You can choose which icon to use from the insert object dialog.

THUMBNAIL	A reduced view of the OLE object is displayed in an OLE container.

•	An OLE object type is saved to the database in a LONG RAW column.  When the OLE object is queried from the database, make sure that it has the same OLE Tenant Aspect property setting as that of the OLE object saved to the database.  If the OLE Tenant Aspect property of the saved OLE object is different from that of the queried OLE object, the record containing the object is automatically LOCKED.


OLE Tenant Aspect restrictions property
OLE Tenant Aspect restrictions

Valid only on Microsoft Windows.


OLE Tenant Types property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the type of OLE objects that can be tenants of the OLE container.  The following settings are valid for this property:

ANY	The default OLE tenant type.  Any OLE object can be a tenant of the OLE container.

NONE	No object can reside in the OLE container.

STATIC	Only static OLE objects can be a tenant of the OLE container.  A static OLE object is a snapshot image of a linked OLE object that has a broken link to its source.  A static OLE object cannot be modified.

EMBEDDED	Only an embedded OLE object can be a tenant of the OLE container.

LINKED	Only a linked OLE object can be a tenant of the OLE container.

Applies to  OLE Container

Set  Form Builder

Default

ANY


OLE Tenant Types restrictions property
OLE Tenant Types restrictions

Valid only on Microsoft Windows and Macintosh.


Operating_System property

  Related Topics	 All Properties

Description

Specifies the name of the current operating system, such as  Microsoft WINDOWS, WIN32COMMON, UNIX, Sun OS, MACINTOSH, VMS, and HP-UX.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY

Usage Notes

Because the value returned by this property is platform-specific, refer to the Form Builder documentation for your operating system if the platform you are using is not listed above.


Optimizer Hint property

 All Properties

Description

Specifies a hint string that Form Builder passes on to the RDBMS optimizer when constructing queries.  Using the optimizer can improve  the performance of database transactions.

Applies to  block

Set  Designer, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Restrictions:

Valid only for applications running against the Oracle7 Server or Oracle8 Server.

Usage Notes

Consider a form that contains a block named DeptBlock based on the DEPT table. If the end user enters a criteria of " > 25 " for the DEPTNO column and executes the query, the default SELECT statement that Form Builder generates to query the appropriate rows from the database is as follows:

SELECT DEPTNO,DNAME,LOC,ROWID
FROM DEPT
WHERE (DEPTNO > 25)

The designer can use SET_BLOCK_PROPERTY to set the Optimizer Hint property to request that the Oracle7 Server attempt to optimize the SQL statement for best response time:

Set_Block_Property('DeptBlock',OPTIMIZER_HINT,'FIRST_ROWS');
SELECT /*+ FIRST_ROWS */ DEPTNO,DNAME,LOC,ROWID
FROM DEPT
WHERE (DEPTNO > 25)

For more information on how to use this feature with Oracle7, refer to the following sources:

•	Oracle7 Server Application Developer's Guide, Chapter 5, "Tuning SQL Statements"

•	Oracle7 Server Concepts Manual, Chapter 13, "The Optimizer"


Order By property

Description

See WHERE CLAUSE/ORDER BY CLAUSE.


Other Reports Parameters property

 All Properties

Description

A <keyword>=<value> list of parameters to include in the running of the report.  For a list of valid parameters, see the keyword list in the Report Builder online help.

Applies to  Report Builder reports

Set  Form Builder

Default

blank

Required/Optional  optional

Usage Notes:

When passing multi-word parameter values in the where-clause, the entire where-clause should be enclosed in single quotes.  When a name appears in such a multi-word parameter, then two single quotes should also be used to begin and to end that name.  For example, in order to pass the parameter value where ename = ’MILLER’ it is necessary to code this as:

‘where ename = ‘‘MILLER’’’


Output_Date/Datetime_Format property

  Related Topics	 All Properties

Description

Holds the current output date or datetime format mask established by the environment variable FORMSnn_OUTPUT_DATE_FORMAT or FORMSnn_OUTPUT_DATETIME_FORMAT.  Forms uses these format masks as defaults in its runtime output processing.

There are two separate properties:  Output_Date_Format and Output_Datetime_Format.

Applies to  application

Set  Not settable from within Form Builder.

Refer to Built-in

GET_APPLICATION_PROPERTY


Parameter Data Type property

  Related Topics	 All Properties

Description

Specifies what kinds of values Form Builder allows as input and how Form Builder displays those values.

Applies to  check box, display item, list item, radio group, text item, custom item, form parameter

Note:  All data types do not apply to each item type.

Set  Form Builder

Usage Notes

•	It is recommended that you use only the standard data types CHAR, DATE, LONG, and NUMBER.  These data types are based on native ORACLE data types, and offer better performance and application portability.  The other data types are valid only for text items, and are included primarily for compatibility with previous versions.  You can achieve the same formatting characteristics by using a standard data type with an appropriate format mask.

•	The data type of a base table item must be compatible with the data type of the corresponding database column. Use the CHAR data type for items that correspond to ORACLE VARCHAR2 database columns.

•	Do not create items that correspond to database CHAR columns if those items will be used in queries or as the join condition for a master-detail relation; use VARCHAR2 database columns instead.

•	Form Builder will perform the following actions on items, as appropriate:

•	remove any trailing blanks

•	change the item to NULL if it consists of all blanks

•	remove leading zeros if the data type is NUMBER, INT, MONEY, RINT, RMONEY, or RNUMBER (unless the item's format mask permits leading zeros)

•	The form parameter Parameter Data Type property supports the data types  CHAR, DATE, and NUMBER.

ALPHA

Contains any combination of letters (upper and/or lower case).

Default	Blanks
Example	"Employee", "SMITH"
CHAR

Supports VARCHAR2 up to 2000 characters.  Contains any combination of the following characters:

•	Letters (upper and/or lower case)

•	Digits

•	Blank spaces

•	Special characters ($, #, @, and _)

Default	Blanks
Example	"100 Main Street", "CHAR_EXAMPLE_2"
DATE

Contains a valid date.  You can display a DATE item in any other valid format by changing the item's format mask.

Default	DD-MON-YY
Restrictions	Refers to a DATE column in the database and is processed as a true date, not a character string.
The  DATE data type contains a ZERO time component	.
Example	01-JAN-92
DATETIME

Contains a valid date and time.

Default	DD-MON-YY HH24:MI[:SS]
Restrictions	Refers to a DATE column in the database and is processed as a true date, not a character string.
	The DATETIME data type contains a four digit year.  If the year input to a DATETIME data type is two digits, the year is interpreted as 00YY.
Example	31-DEC-88 23:59:59
EDATE

Contains a valid European date.

Default	DD/MM/YY
Restrictions	V3 data type.
	Must refer to a NUMBER column in the database.
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the DATE data type.
	Apply a format mask to produce the European date format.
	Reference a DATE column in the database, rather than a NUMBER column.
Example	23/10/92 (October 23, 1992)
	01/06/93 (June 1, 1993)
INT

Contains any integer (signed or unsigned whole number).

Default	0
Example	1, 100, -1000
JDATE

Contains a valid Julian date.

Default	MM/DD/YY
Restrictions	V3 data type.
	Must refer to a NUMBER column in the database.
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the DATE data type.
	Apply a format mask to produce the Julian date format.
	Reference a DATE column in the database, rather than a NUMBER column.
Example	10/23/92 (October 23, 1992)
	06/01/93 (June 1, 1993)
LONG

Contains any combination of up to 65,534 characters.  Stored in ORACLE as variable-length character strings.

Default	Blanks
Restrictions	Not allowed as a reference in the WHERE or ORDER BY clauses of any SELECT statement.
	LONG items are not queryable in Enter Query mode.
MONEY

Contains a signed or unsigned number to represent a sum of money.

Restrictions	V3 data type
	Included for backward compatibility.  Instead, use a format mask with a number to produce the same result.
Example	10.95, 0.99, -15.47
NUMBER

Contains fixed or floating point numbers, in the range of 1.0x10-129 to 9.99x10124, with one or more of the following characteristics:

•	signed

•	unsigned

•	containing a decimal point

•	in regular notation

•	in scientific notation

•	up to 38 digits of precision

NUMBER items refer to NUMBER columns in the database and Form Builder processes their values as true numbers (not character strings).

Default	0
Restrictions	Commas cannot be entered into a number item (e.g., 99,999).  Use a format mask instead.
Example	-1, 1, 1.01, 10.001, 1.85E3
RINT

Displays integer values as right-justified.

Restrictions	V3 data type
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the NUMBER data type.
	Apply a format mask such as 999 to produce a right-justified number.
RMONEY

Displays MONEY values as right-justified.

Restrictions	V3 data type
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the NUMBER data type
	Apply a format mask such as $999.99 to produce a right-justified number.
RNUMBER

Displays NUMBER values as right-justified.

Restrictions	V3 data type
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the NUMBER data type.
	Apply a format mask such as 999.999 to produce a right-justified number.
TIME

Contains numbers and colons that refer to NUMBER columns in the database.

Default	HH24:MI[:SS]
Restrictions	V3 data type
	Included for backward compatibility.  Instead, follow these recommendations:
	Use the DATETIME data type.
	Apply a format mask to produce only the time.
	Not allowed as a reference to DATE columns in the database.
Example	:10:23:05
	21:07:13


Parameter Initial Value (Form Parameter) property

  Related Topics	 All Properties

Description

Specifies the value that Form Builder assigns the parameter at form startup.

Applies to  Form Parameter

Set  Form Builder

Default

NULL

Required/Optional  optional

Usage Notes

Any valid constant is a valid value for this property.


Menu Parameter Initial Value (Menu Substitution Parameter) property

  Related Topics	 All Properties

Description

Specifies the value that Form Builder assigns the parameter at form startup.

Set  Form Builder

Required/Optional  required


Password property

  Related Topics	 All Properties

Description

Specifies the password of the current end user.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY

Usage Notes

The Password property returns only the password.  If you want a connect string as well, examine the Connect_String property.


PLSQL_Date_Format property

  Related Topics	 All Properties

Description

This property establishes the format mask used in converting date values when executing PL/SQL (for a trigger or called function or procedure) within Forms, in the following cases:

•	evaluating TO_DATE (char_value) or TO_DATE (date_value) with no explicit format mask

•	assigning a CHAR value to a date variable, or vice versa.

Applies to  entire Forms application (global value)

Set  programmatically

Refer to Built-in

•	GET_APPLICATION_PROPERTY built-in

•	SET_APPLICATION_PROPERTY built-in

Required/Optional  optional.  However, it is STRONGLY RECOMMENDED that, for a  new application, you set this property to a format mask containing full century and time information.  It is also recommended that this format mask be the same as the one specified in the Builtin_Date_Format property.

Default

As noted above, it is strongly recommended that you explicitly set this value for a new application.  If you do not, the default value will be DD-MON-YY.  (This value is used for compatibility with Release 4.5 and earlier.)

Compatibility with other Oracle products

In Oracle products other than Form Builder, PL/SQL version 2 does not necessarily use a default date format mask of DD-MON-YY.  Instead, it typically uses a format mask derived from the current NLS environment.  If for some reason you want your Forms application to exhibit the same behavior, you can use the USER_NLS_DATE_FORMAT application property to get the current NLS date format mask, and then assign it to the application's PLSQL_DATE_FORMAT property.


PL/SQL Library Location property

  Related Topics	 All Properties

Description

Shows the location of the attached PL/SQL library.

This property is set when you attach a PL/SQL library to a Forms module.  If you requested that the directory path be retained, this property will be the full pathname of the library.  If you requested that the directory path be removed, this property will be just the library name.

This property is displayed only for your information.  You cannot set or change it through the property palette.

Applies to  PL/SQL libraries

Set  Form Builder

Required/Optional  display only.

Default  none


PL/SQL Library Source property

  Related Topics	 All Properties

Description

This property is set when you attach a PL/SQL library to a Forms module.  It shows the source of this PL/SQL library – either File or Database.

This property is displayed only for your information.  You cannot set or change it through the property palette.

Applies to  PL/SQL libraries

Set  Form Builder

Required/Optional  display only

Default  File


Popup Menu property

 Restrictions	 All Properties

Description

Specifies the popup menu to display for the canvas or item.

Applies to  canvases and items

Set  not settable

Required/Optional  Optional

Default

NULL

Refer to Built-in

•	GET_MENU_ITEM_PROPERTY

•	SET__MENU_ITEM_PROPERTY

Note:  ENABLED, DISABLED, and LABEL are the only properties valid for popup menus.


Popup Menu restrictions property
Popup Menu restrictions

•	The popup menu must be defined within the current form module.

•	You cannot attach a popup menu to individual radio buttons, but you can assign a popup menu to a radio group.


Precompute Summaries property

 Restrictions	    Related Topics	 All Properties

Description

Specifies that the value of any summarized item in a data block is computed before the normal query is issued on the block.  Form Builder issues a special query that selects all records (in the database) of the summarized item and performs the summary operation (sum, count, etc.) over all the records.

Applies to  block

Set  Form Builder

Required/Optional  Required if the block contains summarized items and the block's Query All Records property is set to No.

Default

No

Usage Notes

When an end user executes a query in a block with Precompute Summaries set to Yes, Form Builder fires the Pre-Query trigger (if any) once before it executes the special query.  Form Builder fires the Pre-Select trigger (if any) twice:  once just before executing the special query, and again just before executing the normal query.


Precompute Summaries restrictions property
Precompute Summaries restrictions

•	You cannot set Precompute Summaries to Yes if any of the following are true:  (1) the block contains a summarized control item,  (2) a minimize or maximize operation is performed on a summarized item in the block,  (3) the block's Query Data Source is a stored procedure or transactional triggers (must be a table or sub-query), or  (4) the block contains a checkbox item, list item, or radio group with an empty Other Values property..

•	Read consistency cannot be guaranteed unless  (1) the form is running against an Oracle7.3 database, and  (2) the form-level Isolation Mode property is set to Serializable.


Prevent Masterless Operations property

  Related Topics	 All Properties

Description

Specifies whether end users should be allowed to query or insert records in a block that is a detail block in a master-detail relation.  When set to Yes, Form Builder does not allow records to be inserted in the detail block when there is no master record in the master block, and does not allow querying in the detail block when there is no master record that came from the database.

When Prevent Masterless Operation is Yes, Form Builder displays an appropriate message when end users attempt to insert or query a record:

FRM-41105: Cannot create records without a parent record.
FRM-41106: Cannot query records without a parent record.

Applies to  relation

Set  Form Builder, programmatically

Refer to Built-in

•	GET_RELATION_PROPERTY

•	SET_RELATION_PROPERTY

Default

No


Previous Navigation Block property

  Related Topics	 All Properties

Description

Specifies the name of the block that is defined as the "previous navigation block" with respect to this block.  By default, this is the block with the next lower sequence in the form, as indicated by the order of blocks in the Object Navigator.  However,  you can set this property to redefine a block's "previous" block for navigation purposes.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default

The name of the block with the next lower sequence in the form.

Required/Optional  optional

Usage Notes

Setting this property has no effect on the value of the PreviousBlock property.


Previous Navigation Item property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the name of the item that is defined as the"previous navigation item" with respect to the current item.  By default, this is the item with the next lower sequence in the form, as indicated by the order of items in the Object Navigator.  However, you can set this property to redefine the "previous item" for navigation purposes.

Applies to  item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

NULL.  NULL indicates the default, which is the name of the item with the next lower sequence in the form.

Required/Optional  optional


Previous Navigation Item restrictions property
Previous Navigation Item restrictions

The item specified as Previous Navigation Item must be in the same block as the current item.


PreviousBlock property

  Related Topics	 All Properties

Description

Specifies the name of the block with the next lower sequence in the form, as indicated by the order of blocks in the Object Navigator.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY

Required/Optional  optional

Usage Notes

•	You may use this property with the First_Block or Last_Block form properties to traverse a list of blocks.

•	The value of PreviousBlock is NULL when there is no block with a lower sequence number than the current block.

•	Setting the Previous Navigation Block property has no effect on the value of PreviousBlock.


PreviousItem property

  Related Topics	 All Properties

Description

Specifies the name of the item with the next lower sequence number in the block, as indicated by the order of items in the Object Navigator.

Applies to  item

Set  not settable

Refer to Built-in

GET_ITEM_PROPERTY

Required/Optional  optional


Primary Canvas property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the canvas that is to be the window's primary content view.  At runtime, Form Builder always attempts to display the primary view in the window.  For example, when you display a window for the first time during a session by executing the SHOW_WINDOW built-in procedure, Form Builder displays the window with its primary content view.

If, however, Form Builder needs to display a different content view because of navigation to an item on that view, the primary content view is superseded by the target view.

Applies to  window

Set  Form Builder

Default

 NULL

Required/Optional  Required only for a window that will be shown programmatically, rather than in response to navigation to an item on a canvas assigned to the window.


Primary Canvas restrictions property
Primary Canvas restrictions

The specified view must be a content view (Canvas Type property set to Content), and must be assigned to the indicated window (by setting the Window canvas property).


Primary Key (Item) property

 Restrictions	    Related Topics	 All Properties

Description

Indicates that the item is a base table item in a data block and that it corresponds to a primary key column in the base table.  Form Builder requires values in primary key items to be unique.

Applies to  all items except buttons, chart items, and image items

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Required/Optional  optional


Primary Key (Item) restrictions property
Primary Key (Item) restrictions

The Enforce Primary Key block property must be set to Yes for the item's owning block.


Program Unit Text property

 All Properties

Description

Specifies the PL/SQL code that a program unit contains.   When you click on More… in the Property Palette the Program Unit Editor is invoked.

Applies to  program unit

Set  Form Builder

Required/Optional  required


Prompt property

 All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the text label that displays for an item.

Applies to  item prompt

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

blank

Required/Optional  optional


Prompt Alignment property

 All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies how the prompt is aligned along the item's edge, either Start, End, or Center.

Applies to  item prompt

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Alignment.)

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Start

Required/Optional  required


Prompt Alignment Offset property

 All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the prompt's alignment offset.

Applies to  item prompt

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Alignment_Offset.)

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

blank

Required/Optional  optional


Prompt Attachment Edge property

 All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies which edge the prompt should be attached to, either Start, End, Top, or Bottom.

Applies to  item prompt

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Attachment_Edge.)

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Start

Required/Optional  required


Prompt Attachment Offset property

 All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the distance between the item and its prompt.

Applies to  item prompt

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Attachment_Offset.)

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

blank

Required/Optional  optional


Prompt Background Color property

  Related Topics	All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

The color of the object's or  background region.

Applies to  item prompt, radio button

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Background_Color.)

Default

Unspecified

Required/Optional  optional

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY


Prompt Display Style property

 All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the prompt's display style.

First Record	Form Builder displays a prompt beside the first record.

•	HiddeForm Builder does not display a prompt.

All Records	Form Builder displays a prompt beside each record.

Applies to  item prompt

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Display_Style.)

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

First Record

Required/Optional  required


Prompt Fill Pattern property

  Related Topics	 All Properties	{button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the pattern to be used for the object’s fill region. Patterns are rendered in the two colors specified by Background_Color and Foreground_Color.

Applies to  item, item prompt's, radio button

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Fill_Pattern.)

Default

Unspecified

Required/Optional  optional

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY


Prompt Font Name property

  Related Topics	 All Properties	{button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the font family, or typeface, to be used for text in the object. The list of fonts available is system-dependent.

Applies to  item item prompt, radio button

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Font_Name.)

Default

Unspecified

Required/Optional  optional

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY


Prompt Font Size property

  Related Topics	 All Properties	{button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

The size of the  font, specified in points.

Applies to  item, item prompt, radio button

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Font_Size.)

Default

Unspecified

Required/Optional  optional

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY


Prompt Font Spacing property

  Related Topics	 All Properties	{button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the width of the font (i.e., the amount of space between characters, or kerning).

Applies to  item, item prompt, radio button

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Font_Spacing.)

Default

Unspecified

Required/Optional  optional

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY


Prompt Font Style property

  Related Topics	 All Properties	{button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the style of the font.

Applies to  item, item prompt, radio button

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Font_Style.)

Default

Unspecified

Required/Optional  optional

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY


Prompt Font Weight property

  Related Topics	 All Properties	{button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the weight of the font.

Applies to  item, item prompt, radio button

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Font_Weight.)

Default

Unspecified

Required/Optional  optional

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY


Prompt Foreground Color property

  Related Topics	 All Properties	{button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the color of the object’s foreground region. For items, defines the color of the text displayed in the item.

Applies to  item, item prompt, radio button

Set  Form Builder, programmatically (Note: When you use this property in a PL/SQL program, replace the spaces with underscores: Prompt_Foreground_Color.)

Default

Unspecified

Required/Optional  optional

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY


Prompt Justification property

 All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies justification of the prompt as either Left, Right, Center, Start, or End.

Applies to  item prompt

Set  Form Builder

Default

Start

Required/Optional  required


Prompt Reading Order property

 All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the prompt's reading order, either Default, Left to Right, or Right to Left.

Applies to  item prompt

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Default

Required/Optional  required


Prompt Visual Attribute Group property

 All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies the named visual attribute that should be applied to the prompt at runtime.

Applies to  item prompt

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Default

Required/Optional  required


Prompt_White_On_Black property

  Related Topics	 All Properties {button ,JumpId(>category,Prompt_Properties) Prompt_Properties

Description

Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

Applies to  item, radio button

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY


Property Class property

  Related Topics	 All Properties

Description

Specifies the name of the property class from which the object can inherit property settings.

Applies to  all objects

Set  Form Builder

Default

Null

Required/Optional   optional


Query All Records property

  Related Topics	 All Properties

Description

Specifies whether all the records matching the query criteria should be fetched into the data block when a query is executed.

Yes - Fetches all records from query; equivalent to executing the EXECUTE_QUERY (ALL_RECORDS) built-in.

No - Fetches the number of records specified by the Query Array Size block property.

Applies to  block

Set  Form Builder

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default

No

Required/Optional  Required if a data block contains summarized items, and the block's Precompute Summaries property is set to No.


Query Allowed (Block) property

  Related Topics	 All Properties

Description

Specifies whether Form Builder should allow the end user or the application to execute a query in the block. When Query Allowed is No, Form Builder displays the following message if the end user attempts to query the block:

FRM-40360: Cannot query records here.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default

Yes

Restrictions:

When the Query Allowed block property is Yes, the Query Allowed item property must be set to Yes for at least one item in the block.


Query Allowed (Item) property

 Restrictions	    Related Topics	 All Properties

Description

Determines if the item can be included in a query against the base table of the owning block.

Applies to  all items except buttons, chart items, and image items

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes; however if the item is part of the foreign key in the detail block of a master-detail block relation, Form Builder sets this property to No.

Usage Notes

To set the Query Allowed (Item) property programmatically, use the constant QUERYABLE.


Query Allowed (Item) restrictions property
Query Allowed (Item) restrictions

•	The Visible property must also be set to Yes.

•	Items with the data type LONG cannot be directly queried.


Query Array Size property

 Restrictions	 All Properties

Description

Specifies the maximum number of records that Form Builder should fetch from the database at one time.

Applies to  block

Set  Form Builder

Refer to Built-in

GET_BLOCK_PROPERTY

Default

The number of records the block can display, as indicated by the Number of Records Displayed block property.

Required/Optional  required

Usage Notes

A size of 1 provides the fastest perceived response time, because Form Builder fetches and displays only 1 record at a time.  By contrast, a size of 10 fetches up to 10 records before displaying any of them, however, the larger size reduces overall processing time by making fewer calls to the database for records.


Query Array Size restrictions property
Query Array Size restrictions

•	There is no maximum.


Query Data Source Arguments property

  Related Topics	 All Properties

Description

Specifies the names, datatypes, and values of the arguments that are to be passed to the procedure for querying data.  The Query Procedure Arguments property is valid only when the Query Data Source Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Query Data Source Columns property

  Related Topics	 All Properties

Description

Specifies the names and datatypes of the columns associated with the block's query data source.  The Query Data Source Columns property is valid only when the Query Data Source Type property is set to Table, Sub-query, or Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Query Data Source Name property

 Restrictions	   Related Topics	 All Properties

Description

Specifies the name of the block's query data source.

The Query Data Source Name property is valid only when the Query Data Source Type property is set to Table, Sub-Query, or Procedure.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	 GET_BLOCK_PROPERTY

•	SET_ITEM_PROPERTY

Default

NULL

Required/Optional  optional


Query Data Source Name restrictions property
Query Data Source Name restrictions

Prior to setting the Query Data Source Name property you must perform a COMMIT_FORM or a CLEAR_FORM.


Query Data Source Type property

  Related Topics	 All Properties

Description

Specifies the query data source type for the block.  A query data source type can be a Table, Procedure, Transactional Trigger, or FROM clause query.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

GET_BLOCK_PROPERTY

Default

Table

Required/Optional  required


Query Length property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the number of characters an end user is allowed to enter in the text item when the form is Enter Query mode.

Applies to  text item

Set  Form Builder

Default

The value of the item's Maximum Length property.

Usage Notes

You can make the query length greater than the Maximum Length when you want to allow the end user to enter complex query conditions.  For example, a query length of 5 allows an end user to enter the query condition !=500 in a text item with a Maximum Length of 3.


Query Length restrictions property
Query Length restrictions

•	The maximum query length is 255 characters.


Query Name property

 All Properties

Description

Specifies the name of the query in the report with which to associate the forms block.

Applies to  report integration

Set  Form Builder

Default

blank

Required/Optional  optional


Query Only property

  Related Topics	 All Properties

Description

Specifies that an item can be queried but that it should not be included in any INSERT or UPDATE statement that Form Builder issues for the block at runtime.

Applies to  check box, radio group, list item, image item, text item, custom item (OLE)

Set  programmatically

Default

No

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


Query_Hits property

 Restrictions	 All Properties

Description

Specifies the NUMBER value that indicates the number of records identified by the COUNT_QUERY operation.  If this value is examined while records are being retrieved from a query, QUERY_HITS specifies the number of records that have been retrieved.

This property is included primarily for applications that will run against non-ORACLE data sources.

Applies to  block

Set  programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Usage Notes

This property can be used in several ways:

•	In an application that runs against a non-ORACLE data source, use SET_BLOCK_PROPERTY(QUERY_HITS) in an On-Count trigger to inform Form Builder of the number of records that a query will return.  This allows you to implement count query processing equivalent to Form Builder default Count Query processing.

•	Use GET_BLOCK_PROPERTY(QUERY_HITS) during Count Query processing to examine the number of records a query will potentially retrieve.

•	Use GET_BLOCK_PROPERTY(QUERY_HITS) during fetch processing to examine the number of records that have been retrieved by the query so far and placed on the block's list of records.


Query_Hits restrictions property
Query_Hits restrictions

Set this property greater than or equal to 0.


Query_Options property

 All Properties

Description

Specifies the type of query operation Form Builder would be doing by default if you had not circumvented default processing.  This property is included for applications that will run against non-ORACLE data sources.

Values for this property include:

•	VIEW

•	FOR_UPDATE

•	COUNT_QUERY

•	NULL

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY


 Radio Button Value Property

  Related Topics	 All Properties

Description

Specifies the value associated with a radio button item in a radio group.

Applies to  radio button

Set  Form Builder

Default

blank


Raise on Entry property

 Restrictions	    Related Topics	 All Properties

Description

For a canvas that is displayed in the same window with one or more other canvases, Raise on Entry specifies how Form Builder should display the canvas when the end user or the application navigates to an item on the canvas.

•	When Raise on Entry is No, Form Builder raises the view in front of all other views in the window only if the target item is behind another view.

•	When Raise on Entry is Yes, Form Builder always raises the view to the front of the window when the end user or the application navigates to any item on the view.

Applies to  canvas

Set  Form Builder

Default

No


Raise on Entry restrictions property
Raise on Entry restrictions

Applicable only when more than one canvas is assigned to the same window.


Reading Order property

  Related Topics	 All Properties

Description

Note:  This property is specific to bidirectional National Language Support (NLS) applications.

Specifies the reading order for groups of words (segments) in the same language within a single text item.

Reading Order allows you to control the display of bilingual text items, text items that include segments in both Roman and Local languages.  (The Reading Order property has no effect on text items composed of a single language.)

The allowable values for this property are:

Value	Description
Default	Text item inherits the reading order specified by its canvas Language Direction property setting.
Right-To-Left	Item reading order is right-to-left.
Left-To-Right	Item reading order is left-to-right.

Applies to  display item, text item

Set  Form Builder

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Default

Usage Notes

•	In most cases, you will not need to explicitly set the Reading Order property (the Default setting will provide the functionality you need).  Use the Reading Order property only when you need to override the default reading order for an item.

•	To get or set the Reading Order property programmatically, use the Language Direction property.

•	To display a Local segment in Right-To-Left mode and a Roman segment in Left-To-Right, use the Default value.

•	If your item text is mostly Local, choose the Right-To-Left value.

•	If your item text is mostly Roman, choose the Left-To-Right value.


Real Unit property

 Restrictions	 All Properties

Description

When the Coordinate System property is set to Real, the Real Unit property specifies the real units to be used for specifying size and position coordinates in the form.  Real units can be centimeters, inches, pixels, points, or decipoints.  (A point is 1/72nd of an inch.)

Form Builder interprets all size and position coordinates specified in the form in the real units you specify here.  When you convert from one real unit to another, some loss of precision may occur for existing object size and position values.

Applies to  form module

Set  Form Builder

Default

Centimeter

Required/Optional  optional


Real Unit restrictions property
Real Unit restrictions

Valid only when the coordinate system property is set to Real.


Record Group property

  Related Topics	 All Properties

Description

Specifies the name of the record group from which the LOV or hierarchical tree derives its values.

Applies to:

LOV, hierarchical tree

Set   Form Builder, programmatically

Refer to Built-in

GET_LOV_PROPERTY (GROUP_NAME)

SET_LOV_PROPERTY (GROUP_NAME)

POPULATE_TREE

POPULATE_GROUP_FROM_TREE

Default

Null

Required/Optional  Required for LOV, Optional for hierarchical tree

Usage Notes

An LOV displays the records stored in its underlying record group. Each LOV must be based on a record group. A record group can be populated by a query (query record group) or by fixed values (static record group).


Record Group Fetch Size property

 All Properties

Description

Specifies the size of the record group to be fetched. A larger fetch size reduces the number of fetches required to obtain the record group. For example, a record group of 5000 records will require 500 trips to be fetched if Record Group Fetch Size is set to 10, but only 5 trips if Record Group Fetch Size is set to 1000.

Applies to  record group functional

Set  Form Builder

Default

20

Required/Optional  required

Usage Notes

Only available when Record Group Type is set to Query.


Record Group Query property

 All Properties

Description

Specifies the SELECT statement for query associated with the record group.

Applies to  record group

Set  Form Builder, programmatically

Refer to Built-in

POPULATE_GROUP_WITH_QUERY

Required/Optional  optional


Record Group Type property

 All Properties

Description

Specifies the type of record group, either Static or Query:

Static	Specifies that the record group is constructed of explicitly defined column names and column values.  The values of a static record group are specified at design time and cannot be changed at runtime.

Query	Specifies that the record group is associated with a SELECT statement, and thus can be populated dynamically at runtime. When you select this option, enter the SELECT statement in the multi-line field provided, then choose Apply.

Applies to:

record group

Set  Form Builder

Default

Query


Record Orientation property

 Restrictions	    Related Topics	 All Properties

Description

Determines the orientation of records in the block, either horizontal records or vertical records.  When you set this property, Form Builder adjusts the display position of items in the block accordingly.

Applies to  block

Set  Form Builder

Default

Vertical records

Required/Optional  optional

Usage Notes

You can also set this property when you create a block in the New Block window by setting the Orientation option to either Vertical or Horizontal.


Record Orientation restrictions property
Record Orientation restrictions

Valid only for a multi-record block (Number of Records Displayed property set greater than 1).


Records_to_Fetch property

 Examples	 All Properties

Description

Returns the number of records Form Builder expects an On-Fetch trigger to fetch and create as queried records.

You can programmatically examine the value of Records_To_Fetch when you are using transactional triggers to replace default Form Builder transaction processing when running against a non-ORACLE data source.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY

Usage Notes

Records_To_Fetch is defined only within the scope of an On-Fetch trigger.

The first time the On-Fetch trigger fires, the value of Records_To_Fetch is either the array size (as specified by the Query Array Size block property) or the number of records displayed + 1, whichever is larger.

If the On-Fetch trigger creates this many queried records, the next time the On-Fetch trigger fires, the value of Records_To_Fetch will be the same number.

If, however, the On-Fetch trigger creates fewer records than the value of Records_To_Fetch and returns without raising Form_Trigger_Failure,  Form Builder will fire the On-Fetch trigger again.  Records_To_Fetch  will be the set to its previous value minus the number of queried records created by the previous firing of the On-Fetch trigger.

This behavior continues until one of the following events occurs:

•	The trigger does not create a single queried record (signaling a successful end of fetch).

•	The expected number of queried records gets created.

•	The trigger raises a Form_Trigger_Failure (signaling that the fetch aborted with an error and fetch processing should halt).


Records_to_Fetch examples property
Records_to_Fetch examples

Example

/*

** Call a client-side package function to retrieve
** the proper number of rows from a package cursor.
*/
DECLARE
   j NUMBER := Get_Block_Property(blk_name, RECORDS_TO_FETCH);
   emprow emp%ROWTYPE;
BEGIN
   FOR ctr IN 1..j LOOP
      /* Try to get the next row.*/
      EXIT WHEN NOT MyPackage.Get_Next_Row(emprow);
      Create_Queried_Record;
      :Emp.rowid := emprow.ROWID;
      :Emp.empno := emprow.EMPNO;
      :Emp.ename := emprow.ENAME;
         :
         :
   END LOOP;
END;


Relation Type property

 All Properties

Description

Specifies whether the link between the master block and detail block is a relational join or an object REF pointer.

Applies to  master-detail relations

Set  Form Builder

Default

Join

Usage Notes

Valid values are Join (indicating a relational join) or REF (indicating a REF column in one block pointing to referenced data in the other block).

When the link is via a REF, see also the Detail Reference property.

When the link is via a join, see also the Join Condition property.


Rendered property

 All Properties

Description

Specifies that the item is to be displayed as a rendered object when it does not have focus.

Applies to  text item, display item

Set  Form Builder

Default

Yes

Usage Notes

Use the Rendered property to conserve system resources.  A rendered item does not require system resources until it receives focus.  When a rendered item no longer has focus, the resources required to display it are released.


Report Destination Format property

 All Properties

Description

In bit-mapped environments, this property specifies the printer driver to be used when the Report Destination Type property is File.  In character-mode environments, it specifies the characteristics of the printer named in report Destination name property.

Possible valus are any valid destination format not to exceed 1K in length.  Examples of valid values for this keyword are hpl, hplwide, dec, decwide, decland, dec180, dflt, wide, etc.  Ask your System Administrator for a list of valid destination formats.   In addition, Report Builder supports the following destination formats:

PDF	Means that the report output will be sent to a file that can be read by a PDF viewer.  PDF output is based upon the currently configured printer for your system.  The drivers for the currently selected printer is used to produce the output;  you must have a printer configured for the machine on which you are running the report.
HTML	Means that the report output will be sent to a file that can be read by an HTML 3.0 compliant browser (e.g., Netscape 2.2).
HTMLCSS	Means that the report output sent to a file will include style sheet extensions that can be read by an HTML 3.0 compliant browser that supports cascading style sheets.
HTMLCSSIE	Means that the report output sent to a file will include style sheet extensions that can be read by Microsoft Internet Explorer 3.x.
RTF	Means that the report output will be sent to a file that can be read by standard word processors (such as Microsoft Word).  Note that when you open the file in MS Word, you must choose View [image] Page Layout to view all the graphics and objects in your report.
DELIMITED	Means that the report output will be sent to a file that can be read by standard spreadsheet utilities, such as Microsoft Excel.  Note that you must also specify a DELIMITER.
For more information about this property, see DESFORMAT under the index category Command Line Arguments in the Report Builder online help.

Applies to  report reports

Set  Form Builder

Default

blank

Required/Optional  optional


Report Destination Name property

 All Properties

Description

Name of the file, printer, Interoffice directory, or email user ID (or distribution list) to which the report output will be sent. Possible values are any of the following not to exceed 1K in length:

•	a filename (if Report Destination Type property is File or Localfile)

•	a printer name (if Report Destination Type property is Printer)

•	email name or distribution name list (if Report Destination Type property is Mail).

To send the report output via email, specify the email ID as you do in your email application (any MAPI-compliant application on Windows, such as Oracle InterOffice, or your native mail application on UNIX).  You can specify multiple usernames by enclosing the names in parentheses and separating them by commas (e.g., (name, name, . . .name)). For printer names, you can optionally specify a port. For example:

printer,LPT1:

printer,FILE:

Or, if the Report Destination Type property is Interoffice:

/FOLDERS/directory/reportname

For more information about this property, see DESNAME under the index category Command Line Arguments in the Report Builder online help.

Applies to  report reports

Set  Form Builder

Default

blank

Required/Optional  optional


Report Destination Type property

 All Properties

Description

Destination to which you want the output to be sent. Possible values are Screen, File, Printer, Preview, Mail, and Interoffice. For more information about this property, see DESTYPE under the index category Command Line Arguments in the Report Builder online help.

SCREEN	Screen routes the output to the Previewer for interactive viewing. This value is valid only for when running the report in Runtime mode (not Batch). Font aliasing is not performed.
FILE	File saves the output to a file named in Report Destination Name.
PRINTER	Printer routes the output to the printer named in Report Destination Name.
PREVIEW	Preview routes the output to the Previewer for interactive viewing. However, Preview causes the output to be formatted as Postscript output. The Previewer will use the Report Destination Name property to determine which printer’s fonts to use to display the output. Font aliasing is performed for Preview.
MAIL	Mail routes the output to the mail users specified in Report Destination Name.  You can send mail to any mail system that is MAPI-compliant or has the service provider driver installed.  The report is sent as an attached file.
INTEROFFICE	routes the output to the Oracle InterOffice mail users specified in Report Destination Name.  By specifying this value, you store the report output in InterOffice as a repository.
Applies to  report reports

Set  Form Builder

Default

File

Required/Optional  required


Report Server property

 All Properties

Description

Specifies the Report Server against which you can run your Report.

Applies to  report reports

Set  Form Builder

Required/Optional  optional

Default

blank


Required (Item) property

  Related Topics	 All Properties

Description

When a new record is being entered, specifies that the item is invalid when its value is NULL.

Applies to  list item, text item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_INSTANCE_PROPERTY

•	GET_ITEM_PROPERTY

•	SET_ITEM_INSTANCE_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Usage Notes

When an item has Required set to Yes, and item-level validation is in effect, by default Form Builder will not allow navigation out of the item until a valid value is entered. To allow the end user to move freely among the items in the record, set the Defer Required Enforcement property to Yes.  This will postpone enforcement of the Required attribute from item validation to record validation.

Even when Required is set to Yes, there are circumstances when an item's value could be NULL.  Form Builder checks for required items as part of its validation process:  each item in a new record is subject to validation, but queried data is presumed to be valid and an item is not validated unless it is changed.  For example, if the record already exists and is queried from the database, the item that would be Required could come in as NULL.

Setting a poplist’s or T-list’s Required property may affect the values the list will display:  When selected, an instance of a poplist will display an extra null value if its current value is NULL or if its effective Required property is No (false).  When selecting the current value of an instance of a T-list, it will be unselected (leaving the T-list with no selected value) if its effective Required property is No (false).  But if its effective Required property is Yes (true), selecting a T-list instance’s current value will have no effect. The value will stay selected.


Required (Menu Parameter) property

  Related Topics	 All Properties

Description

Specifies that the end user is required to enter a value for the menu substitution parameter.

Applies to  menu substitution parameter

Set  Form Builder

Default

No


Resize Allowed property

 Restrictions	    Related Topics	 All Properties

Description

Specifies that the window is to be a fixed size and cannot be resized at runtime.  This property is a GUI hint, and may not be supported on all platforms.

Applies to  window

Set  Form Builder

Default

No

Usage Notes

The Resize Allowed property prevents an end user from resizing the window, but it does not prevent you from resizing the window programmatically with RESIZE_WINDOW or SET_WINDOW_PROPERTY.


Resize Allowed restrictions property
Resize Allowed restrictions

•	Resize Allowed is only valid when the Maximize Allowed property is set to No


Return Item (LOV) property

 All Properties

Description

See Column Mapping Properties .


Rotation Angle property

 All Properties

Description

Specifies the graphic 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.

Applies to  graphics physical

Set  Form Builder

Default  0

Required/Optional  required


Runtime Compatibility Mode property

 All Properties

Description

Specifies the Form Builder version with which the current form’s runtime behavior is compatible (either 4.5 or 5.0 +). By default, new forms created with Form Builder 5.0 and later are set to 5.0-compatible. Existing forms that are upgraded from 4.5 are 4.5-compatible. To get these forms to use the new runtime behavior of 5.0 +, set this property to 5.0. The runtime behavior that is affected by this property is primarily validation and initialization. For information about 5.0-and-later runtime behavior, see the Initialization and Validation sections in the Default Processing chapter of the online Form Builder Reference. For information about 4.5 runtime behavior, see the Form Builder 4.5 Runtime Behavior section in the Compatibility with Prior Releases chapter of the online Form Builder Reference.

Applies to  forms compatibility

Set  Form Builder

Default

5.0 for new forms, 4.5 for forms created using Form Builder 4.5.

Required/Optional  required


Savepoint Mode property

 Restrictions	 All Properties

Description

Specifies whether Form Builder should issue savepoints during a session. This property is included primarily for applications that will run against non-ORACLE data sources.  For applications that will run against ORACLE, use the default setting.

The following table describes the settings for this property:

Setting	Description
Yes (the default)	Specifies that Form Builder should issue a savepoint at form startup and at the start of each Post and Commit process.
No	Specifies that Form Builder is to issue no savepoints, and that no rollbacks to savepoints are to be performed.

 Applies to  form module

Set  Form Builder, programmatically

Refer to Built-in

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY

Default

Yes

Required/Optional  optional


Savepoint Mode restrictions property
Savepoint Mode restrictions

When Savepoint Mode is No, Form Builder does not allow a form that has uncommitted changes to invoke another form with the CALL_FORM procedure.


Savepoint_Name property

 All Properties

Description

Specifies the name of the savepoint Form Builder is expecting to be set or rolled back to.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY

Usage Notes

The value of this property should be examined only within an On-Savepoint or On-Rollback trigger:

•	Use Savepoint_Name in an On-Savepoint trigger to determine the savepoint to be set by a call to ISSUE_SAVEPOINT.

•	In an On-Rollback trigger, examine Savepoint_Name to determine the savepoint to which Form Builder should roll back by way of a call to ISSUE_ROLLBACK.  A NULL savepoint name implies that a full rollback is expected.


Scroll Bar Alignment property

 All Properties

Description

Specifies whether the scroll bar is displayed at the start or the end of the frame.

Applies to  frame

Set  Form Builder

Default

End

Required/Optional  optional


Scroll Bar Height property

 All Properties

Description

Specifies the height of the scroll bar.

Applies to  scroll bar

Set  Form Builder

Required/Optional  optional


Scroll Bar Width property

 All Properties

Description

Specifies the width of the scroll bar.

Applies to scroll bar

Set  Form Builder

Required/Optional  optional


Secure (Menu Parameter) property

  Related Topics	 All Properties

Description

Hides characters that the end user enters for the substitution parameter.

Applies to  menu substitution parameter

Set  Form Builder

Default

No

Required/Optional  optional


Share Library with Form property

  Related Topics	 All Properties

Description

Forms that have identical libraries attached can share library package data. (For more information, see the data_mode parameter for the CALL_FORM, OPEN_FORM, and NEW_FORM built-ins, under Related Topics above.) The Share Library with Form property enables menus associated with the forms to share the library package data as well.

Applies to  menus

Set  Form Builder

Default

Yes

Usage Notes

1	If two forms share an object, and both forms are open at design time and you make changes to the object in Form A, those changes will not be seen in Form B until the changes are first saved by Form A, and Form B is then closed and reopened.

2	If you use OPEN_FORM to open a form in a different database session, you cannot share library data with the form or its associated menus. Attempts to share library data by setting the property to Yes will be ignored.


Show Fast Forward Button property

  Related Topics	 All Properties

Description

Determines whether the sound item control will display [image] (both in the Layout Editor and at runtime).

Applies to  Sound item control

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Required/Optional  Required


Show Horizontal Scroll Bar property

 Restrictions	    Related Topics	 All Properties

Description

Determines whether a canvas, secondary window, or image item is displayed with a scroll bar.

Applies to  canvas, window, editor, image item

Set  Form Builder

Default

No

Required/Optional  optional


Show Horizontal Scroll Bar restrictions property
Show Horizontal Scroll Bar restrictions

•	For a window, only valid when the Modal property is set to No.

•	Valid on window managers that support horizontal scroll bars.


Show Lines property

 All Properties

Description

Determines whether a hierarchical tree displays lines leading up to each node.

Applies to  hierarchical tree

Set  Form Builder

Default

True

Required/Optional  required


Show OLE Popup Menu property

  Related Topics	 All Properties

Description

Determines whether the right mouse button displays a popup menu of commands for interacting with the OLE object.  The following settings are valid for this property:

YES	The default OLE popup menu selection.  The OLE popup menu is displayed when the mouse cursor is on the OLE object and the right mouse button is pressed.

NO	The OLE popup menu is not displayed when mouse cursor is on the OLE object and the right mouse button is pressed.

Applies to  OLE Container

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes

Required/Optional  required

Usage Notes

•	In addition to the Form Builder, you can programmatically set and get the OLE popup menu value by using the SHOW_POPUPMENU property.  For the SET_ITEM_PROPERTY built-in, the OLE popup menu is shown when the SHOW_POPUPMENU property is set to PROPERTY_TRUE.  When the SHOW_POPUPMENU property is set to PROPERTY_FALSE, the OLE popup menu is not shown. You can also use the SHOW_POPUPMENU property with the GET_ITEM_PROPERTY built-in to obtain the current OLE popup menu setting.  The GET_ITEM_PROPERTY built-in returns TRUE when the OLE popup menu is shown, and GET_ITEM_PROPERTY returns FALSE when the OLE popup menu is not shown.

•	Valid only on Microsoft Windows and Macintosh.


Show OLE Tenant Type property

 Restrictions	     Related Topics	 All Properties

Description

Determines whether a border defining the OLE object type surrounds the OLE container. The type of border varies according to the object type.

Applies to  OLE Container

Set  Form Builder

Default

Yes


Show OLE Tenant Type restrictions property
Show OLE Tenant Type restrictions

Valid only on Microsoft Windows and Macintosh.


Show Palette property

  Related Topics	 All Properties

Description

Determines whether Form Builder will display an image-manipulation palette adjacent to the associated image item at runtime.  The palette provides three tools that enable end users to manipulate a displayed image:

•	Zoom—click the tool, then repeatedly click the image to incrementally reduce the amount of the source image displayed within the image item's borders.

•	Pan—click the tool and use the grab hand to pan unseen portions of the source image into view (valid only if the source image extends beyond at least one border of the image item).

•	Rotate—click the tool, then repeatedly click the image to rotate it clockwise in 90-degree increments.

Applies to  image item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Required/Optional  Required


Show Play Button property

  Related Topics	 All Properties

Description

Determines whether the sound item control will display [image] (both in the Layout Editor and at runtime).

Applies to  Sound item control

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes

Required/Optional  Required

Usage Notes

•	If you set the Show Play Button property to No when the Show Record Button property already is set to No, Form Builder automatically will display [image] at runtime.


Show Record Button property

  Related Topics	 All Properties

Description

Determines whether the sound item control will display [image] (both in the Layout Editor and at runtime).

Applies to  Sound item control

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Required/Optional  Required

Usage Notes

•	If you set the Show Record Button property to No when the Show Play Button property already is set to No, Form Builder will automatically display [image] at runtime.


Show Rewind Button property

  Related Topics	 All Properties

Description

Determines whether the sound item control will display [image] (both in the Layout Editor and at runtime).

Applies to  Sound item control

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Required/Optional  Required


Show Scroll Bar property

  Related Topics	 All Properties

Description

The Show Scroll Bar option specifies whether Form Builder should create a block scroll bar for the block you are defining. When Show Scroll Bar is set to Yes, Form Builder creates the scroll bar on the canvas specified by the Scroll Bar Canvas property.

When you create a block scroll bar, you can set the properties of the scroll bar object itself, including Scroll Bar Canvas, Scroll Bar Orientation, Scroll Bar X Position, Scroll Bar Y Position, Scroll Bar Width, Scroll Bar Height, Reverse Direction, and Visual Attribute Group.

Applies to  block

Set  Form Builder

Default:

No

Required/Optional  optional

Usage Notes

Setting Reverse Direction to Yes causes Form Builder to fetch the next set of records when the end user scrolls upward.  If the end user scrolls downward, Form Builder displays already fetched records.

Property	Description
Scroll Bar Canvas	Specifies the canvas on which the block's scroll bar should be displayed.  The specified canvas must exist in the form.
Scroll Bar Orientation	Specifies whether the block scroll bar should be displayed horizontally or vertically.
Scroll Bar X Position	Specifies the x position of a block scroll bar measured at the upper left corner of the scrollbar.  The default value is 0.
Scroll Bar Y Position	Specifies the width of a block scroll bar measured at the upper left corner of the scrollbar.   The default value is 0.
Scroll Bar Width	Specifies the width of a block scroll bar.  The default value is 2.
Scroll Bar Height	Specifies the height of a block scroll bar.  The default value is 10.
Reverse Direction	Specifies that the scroll bar scrolls in reverse.  The default value is No.
Visual Attribute Group	Specifies the font, color, and pattern attributes to use for scroll bar.  Refer to the Visual Attribute Group property for more information.  The default setting is determined by the platform and resource file definition.


Show Slider property

  Related Topics	 All Properties

Description

Determines whether the sound item control will display the Slider position control (both in the Layout Editor and at runtime).

Applies to  Sound item control

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes

Required/Optional  Required


Show Symbols property

 All Properties

Description

Indicates whether a hierarchical tree should display + or - symbols in front of each branch node. The + symbol indicates that the node has children but is not expanded. The - symbol indicates that the node is expanded.

Applies to  hierarchical tree

Set  Form Builder

Default

True

Required/Optional  required


Show Time Indicator property

  Related Topics	 All Properties

Description

Determines whether the sound item control will display [image] (both in the Layout Editor and at runtime).

Applies to  Sound item control

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes

Required/Optional  Required


Show Vertical Scroll Bar property

 Restrictions	    Related Topics	 All Properties

Description

Specifies that a vertical scroll bar is to appear on the side of a canvas or window.

Applies to  canvas, window, image item, editor, item

Set  Form Builder

Default

No

Required/Optional  Optional


Show Vertical Scroll Bar restrictions property
Show Vertical Scroll Bar restrictions

•	Valid on window managers that support vertical scroll bars.

•	Not valid for a root window: a root window cannot have scroll bars.

•	Valid on window managers that support vertical scroll bars.

•	For text item, the Multi-Line property must be YES.


Show Volume Control property

  Related Topics	 All Properties

Description

Determines whether the sound item control will display [image] (both in the Layout Editor and at runtime).

Applies to  Sound item control

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes

Required/Optional  Required


Shrinkwrap property

 All Properties

Description

Specifies whether blank space should be automatically removed from the frame.  When Shrinkwrap is set to Yes, Form Builder automatically reduces, or "shrinkwraps", the frame around the items within the frame.

Note: Reisizing a frame has no effect when Shrinkwrap is set to Yes; when you, for example, increase the size of the frame, Form Builder automatically reduces the frame to its shrinwrap size.  If you want to resize a frame, set Shrinkwrap to No.

Applies to  frame

Set  Form Builder

Default

Yes

Required/Optional  Optional


Single Object Alignment property

 All Properties

Description

Specifies the alignment for single line objects when the Frame Alignment property is set to Fill.

Applies to  frame

Set  Form Builder

Default

Start

Required/Optional  Required


Single Record property

  Related Topics	 All Properties

Description

Specifies that the control block always should contain one record.  Note that this differs from the number of records displayed in a block.

Applies to  block

Set  Form Builder

Default

No

Usage Notes

•	Set Single Record to Yes for a control block that contains a summary calculated item, a VBX (on Microsoft Windows 3.x 16-bit) or ActiveX control (on 32-bit Windows).  Conversely, Single Record must be set to No for the block that contains the item whose values are being summarized and displayed in the calculated item.

•	You cannot set Single Record to Yes for a data block.


Size property

 Restrictions	 All Properties

Description

Specifies the width and height of the canvas in the current form coordinate units specified by the Coordinate System form property.

Applies to  canvas

Set  Form Builder, programmatically

Refer to Built-in

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

Size (Item)

Specifies the width and height of the item in the current form coordinate units specified by the Coordinate System form property.

Applies to  item

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

Size (Editor)

Specifies the width and height of the editor in the current form coordinate units specified by the Coordinate System form property.

Applies to  editor

Set  Form Builder, programmatically

Refer to Built-in

•	EDIT_TEXTITEM

•	SHOW_EDITOR

Usage Notes

•	For a text item or display item, the number of characters the item can store is determined by the Max Length property, and is not affected by the size property.

•	In applications that will run on character mode platforms, the height of items that display text labels must be at least 2 character cells for the text to display properly.

Size (LOV)

Specifies the width and height of the LOV in the current form coordinate units specified by the Coordinate System form property.

Specifies the width and height of the LOV, in the current form coordinate units specified by the Coordinate System form property.

Applies to  LOV

Set  Form Builder, programmatically

Refer to Built-in

•	GET_LOV_PROPERTY

•	SET_LOV_PROPERTY

Restrictions

Form Builder will ensure that the minimum width of the LOV is set  wide enough to display the buttons at the bottom of the LOV.  (On platforms that allow LOVs to be resized, you can resize the LOV to a minimum that will not display all the buttons.)

Size (Window)

Specifies the width and height of the window in the current form coordinate units specified by the Coordinate System form property.

Applies to  window

Set  Form Builder, programmatically

Default

80 characters by 24 characters

Refer to Built-in

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY


Size restrictions property
Size restrictions

Form Builder will ensure that the minimum width of the editor is set  wide enough to display the buttons at the bottom of the editor.  (On platforms that allow editors to be resized, you can resize the editor to a minimum that will not display all the buttons.)


Sizing Style property

 All Properties

Description

Determines the display style of an image when the image size does not match the size of the image item.

The following settings are valid for this property:

Crop	Displays only the portion of the full image that fits in the display rectangle.

Adjust	Scales the image to fit within the display rectangle.

Applies to  image item

Set  Form Builder

Default

Crop


Sound Format property

 All Properties

Description

Specifies the format in which the sound item will be stored in the database:  either AU, AIFF, AIFF-C, or WAVE.

When you use the READ_SOUND_FILE or WRITE_SOUND_FILE built-in subprograms to work with sound data read from—or written to—the filesystem, use the file_type parameter to control the sound format of the sound data being read or written.

Applies to  sound item

Set  Form Builder

Refer to Built-in

•	READ_SOUND_FILE

•	WRITE_SOUND_FILE

Default

WAVE

Required/Optional  required


Sound Quality property

 All Properties

Description

Specifies the quality with which the sound item will be stored in the database:  either Automatic, Highest, High, Medium, Low, or Lowest.

When you use the WRITE_SOUND_FILE built-in subprogram to write sound data to the filesystem, use the sound_quality parameter to control the sound format of the sound data being written.

Applies to  sound item

Set  Form Builder

Refer to Built-in

•	WRITE_SOUND_FILE

Default

Automatic

Required/Optional  required


Start Angle property

 All Properties

Description

Specifies the starting angle of the arc, using the horizontal axis as an origin.

Applies to  graphic arc

Set  Form Builder

Default

90

Required/Optional  required


Start Prompt Alignment property

 Show Me	 All Properties

Description

Specifies how the prompt is aligned to the item's horizontal edge, either Start, Center, or End.  This property is valid when the Layout Style property is set to Form.

Applies to  frame

Set  Form Builder

Default

Start

Required/Optional  required


Start Prompt Alignment showme
Start Prompt Alignment


Start Prompt Offset property

 Show Me	 All Properties

Description

Specifies the distance between the prompt and its item when the Start Prompt Alignment property is set to Start.

Applies to  frame

Set  Form Builder

Default

0 (character cell)

Required/Optional  required


Start Prompt Offset showme
Start Prompt Offset


Startup Code property

  Related Topics	 All Properties

Description

Specifies optional PL/SQL code that Form Builder executes when the menu module is loaded in memory at form startup.  Think of startup code as a trigger that fires when the menu module is loaded.

Applies to  menu module

Set  Form Builder

Required/Optional  optional

Usage Notes

Startup code does not execute when Form Builder is returning from a called form.


Status (Block) property

 All Properties

Description

Specifies the current status of an indicated block.  Block status can be New, Changed, or Query.

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY

Usage Notes

You can determine the status of the current block in the form by examining the SYSTEM.BLOCK_STATUS system variable.  Form status can be examined by way of the SYSTEM.FORM_STATUS system variable.


Status (Record) property

 All Properties

Description

Specifies the current status of the indicated record.  Record status can be New, Changed, Query, or Insert.

Applies to  record

Set  programmatically

Refer to Built-in

•	GET_RECORD_PROPERTY

•	SET_RECORD_PROPERTY

Usage Notes

The status property allows you to examine the status of any indicated record.  You can also examine the status of the current record in the form with the SYSTEM.RECORD_STATUS system variable.

In general, any assignment to a database item will change a record's status from QUERY to CHANGED (or  from NEW to INSERT), even if the value being assigned is the same as the previous value.  Passing an item to a procedure as OUT or IN OUT parameter counts as an assignment to it.


Subclass Information property

 All Properties

Description

Specifies the following information about the source object and source module for a referenced objects.

Module	The name of the source module.

Storage	The source module type (Form or Menu) and location (File System or Database)

Name	The name of the source object in the source module. (The name of a reference object can be different than the name of its source object.)

Applies to  any reference object

Set  Form Builder

Required/Optional  optional


Submenu Name property

 All Properties

Description

Specifies the name of the submenu associated with a main menu.  The Command Type property must be set to Menu to invoke the Submenu property.

Applies to  menu items

Set  Form Builder

Required/Optional  required

Default

Null


Summarized Block property

  Related Topics	 All Properties

Description

Specifies a Form Builder block, over which all rows of a summary calculated item is summarized (e.g., summed, averaged, etc.) in order to assign a value to the item.

Applies to  block

Set  Form Builder

Required/Optional  required if the associated item's Calculation Mode property is set to Summary


Summarized Item property

 Restrictions	    Related Topics	 All Properties

Description

Specifies a Form Builder item, the value of which is summarized (e.g., summed, averaged, etc.) in order to assign a value to a summary calculated item.

Applies to  item

Set  Form Builder

Required/Optional  required if the associated item's Calculation Mode property is set to Summary


Summarized Item restrictions property
Summarized Item restrictions

•	The summarized item cannot be a summary item.

•	If the summarized item does not reside in the same block as the summary item, the summary item must reside in a control block with the Single Record property set to Yes.


Summary Function property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the type of computation function Form Builder will perform on the summarized item.

Avg	The average value (arithmetic mean) of the summarized item over all records in the block.

Count	Count of all non-null instances of the summarized item over all records in the block.

Max	Maximum value of the summarized item over all records in the block.

Min	Minimum value of the summarized item over all records in the block.

Stddev	The standard deviation of the summarized item's values over all records in the block.

Sum	Sum of all values of the summarized item over all records in the block.

Variance	The variance of the summarized item's values over all records in the block.  (Variance is defined as the square of the standard deviation.)

Note:  For more information about these arithmetic operations, refer to the Oracle8 Server SQL Language Reference Manual.

Applies to  item

Set  Form Builder

Required/Optional  required (only if associated item's Calculation Mode property is set to Summary)

Default

None


Summary Function restrictions property
Summary Function restrictions

You must set the Parameter Data Type property to Number, unless the item's Summary Type is Max or Min, in which case the datatype must mirror that of its associated summarized item.  For example, a calculated item that displays the most recent (i.e., maximum) date in the HIRE_DATE column must have a datatype of Date.


Synchronize with Item property

 Restrictions	 All Properties

Description

Specifies the name of the item from which the current item should derive its value. Setting this property synchronizes the values of the two items, so that they effectively mirror each other. When the end user or the application changes the value of either item, the value of the other item changes also.

Applies to  all items except OLE containers

Set  Form Builder

Required/Optional  Optional

Default

NULL

Usage Notes

•	In earlier releases, this property was called the Mirror Item property.

•	You can set Synchronize with Item for base table or control blocks.  When Synchronize with Item is specified, the current item's Base Table Item property is ignored, and the item derives its value from the mirror item specified, rather than from a column in the database.

•	If you use the GET_ITEM_PROPERTY built-in to obtain a Base Table Item property, it will obtain the value from the mirror item specified.

•	You can use mirror item to create more than one item in a block that display the same database column value.


Synchronize with Item restrictions property
Synchronize with Item restrictions

•	The maximum number of items in a form that can point to the same mirror item is 100.


Tab Attachment Edge property

 Restrictions	 All Properties

Description

Specifies the location where tabs are attached to a tab canvas.

Applies to  tab canvas

Set  Form Builder

Default

Top

Required/Optional  required


Tab Attachment Edge property, restrictions
Tab Attachment Edge restrictions

Valid only for tab canvas.


Tab Page property

  Related Topics	 All Properties

Description

The name of the tab page on which the item is located.

Applies to  item

Set  Form Builder

Default

none

Refer to Built-in

•	GET_ITEM_PROPERTY  (programmatic property name is Item_Tab_Page)

Required/Optional  required (if the item is located on a tab canvas)


Tab Page X Offset property

 Restrictions	    Related Topics	 All Properties

Description

The distance between the left edge of the tab canvas and the left edge of the tab page.  The value returned depends on the form coordinate system—pixel, centimeter, inch, or point.

Applies to  tab canvas

Refer to Built-in

•	GET_CANVAS_PROPERTY


Tab Page X Offset property restrictions
Tab Page X Offset restrictions

•	you can get the property value, but you cannot set it

•	valid only for tab canvas. 0 is returned for all other canvas types


Tab Page Y Offset property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the distance between the top edge of the tab canvas and the top edge of the tab page.  The value returned depends on the form coordinate system used -- pixel, centimeter, inch, or point.

Applies to  tab canvas

Refer to Built-in

•	GET_CANVAS_PROPERTY


Tab Page Y Offset restrictions property
Tab Page Y Offset restrictions

•	you can get the property value, but you cannot set it

•	valid only for tab canvas. 0 is returned for all other canvas types


Tab Style property

 All Properties

Description

Specifies the shape of the labelled tab(s) on a tab canvas.

Applies to  tab canvas

Set  Form Builder

Default

Chamfered

Required/Optional  required


Tear-Off Menu

 Restrictions	    Related Topics	 All Properties

Description

Defines a menu as a tear-off menu.

Applies to  menu

Set  Form Builder

Default

No


Tear-Off Menu restrictions

Only supported in the pull-down menu style, on window managers that support this feature.


Timer_Name property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the name of the most recently expired timer.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY

Required/Optional  optional


Timer_Name restrictions property
Timer_Name restrictions

Only valid when examined in a When-Timer-Expired trigger.


Title property

 All Properties

Description

Specifies the title to be displayed for the object.

Applies to  alert, form module, LOV,  window

Set  Form Builder

Required/Optional  optional

Title (LOV)

Default

NULL

Required/Optional  optional

Title (Window)

Refer to Built-in

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY

Required/Optional  optional

Usage Notes

•	Length limit of a window title depends on the display driver used.  (For example, for an SVGA 1280 x 1024, running under NT, the limit is 78 characters.)

•	If you do not specify a title for a window that is not a root window, Form Builder uses the window's object name, as indicated by the window Name property.

•	If you do not specify a title for a root window, and the current menu is the Default menu, Form Builder uses the name of the form module for the root window title, as indicated by the form module Name property.  When the current menu is a custom menu running in Pull-down or Bar display style, Form Builder uses the name of the main menu in the module for the root window title, as indicated by the menu module Main property.


Tooltip property

  Related Topics	 All Properties

Description

Specifies the help text that should appear in a small box beneath the item when the mouse enters the item.

Applies to  item

Set  Form Builder, programmtically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

blank

Required/Optional  optional


Tooltip Background Color property

  Related Topics	 All Properties

Description

Specifies the color of the object’s background region.

Applies to  item

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


Tooltip Fill Pattern property

  Related Topics	 All Properties

Description

Specifies the pattern to be used for the object’s fill region. Patterns are rendered in the two colors specified by Background_Color and Foreground_Color.

Applies to  item

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


Tooltip Font Name property

  Related Topics	 All Properties

Description

Specifies the font family, or typeface, to be used for text in the object. The list of fonts available is system-dependent.

Applies to  item

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


Tooltip Font Size property

  Related Topics	 All Properties

Description

Specifes the size of the font in points.

Applies to  item

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


Tooltip Font Spacing property

  Related Topics	 All Properties

Description

Specifies the width of the font (i.e., the amount of space between characters, or kerning).

Applies to  item

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


Tooltip Font Style property

  Related Topics	 All Properties

Description

Specifies the style of the font.

Applies to  item

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


Tooltip Font Weight property

  Related Topics	 All Properties

Description

Specifies the weight of the font.

Applies to  item

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


Tooltip Foreground Color property

  Related Topics	 All Properties

Description

Specifies the color of the object’s foreground region. For items, defines the color of the text displayed in the item.

Applies to  item

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


Tooltip Visual Attribute Group property

 All Properties

Description

Specifies the named visual attribute that should be applied to the tooltip at runtime.

Applies to  item tooltip

Set  Form Builder

Default

Default

Required/Optional  required


Tooltip White on Black property

  Related Topics	 All Properties

Description

Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

Applies to  item

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY


Top Prompt Alignment property

 Show Me	 All Properties

Description

Specifies how the prompt is aligned to the item's top edge, either Start, End, or Center.  This property is valid when the Layout Style property is set to Tabular.

Applies to  frame

Set  Form Builder

Default

Start

Required/Optional  required


Top Prompt Alignment showme
Top Prompt Alignment


Top Prompt Offset property

 Show Me	 All Properties

Description

Specifies the distance between the prompt and its item when the Top Prompt Alignment property is set to Top.

Applies to  frame

Set  Form Builder

Default

0 (character cell)

Required/Optional  required


Top Prompt Offset showme
Top Prompt Offset


Top_Record property

 All Properties

Description

Specifies the record number of the topmost record that is visible in the block.  (Records are numbered in the order they appear on the block's internal list of records.)

Applies to  block

Set  not settable

Refer to Built-in

GET_BLOCK_PROPERTY

Usage Notes

Together, the TOP_RECORD and RECORDS_DISPLAYED properties allow you to determine the number of the bottom record in the display, that is, the record having the highest record number among records that are currently displayed in the block.


Top Title property

 All Properties

Description

Specifies a title of up to 72 characters to appear at the top of the editor window.

Applies to  editor

Set  Form Builder

Required/Optional  optional


Topmost_Tab_Page property

 Restrictions	 All Properties

Description

Specifies the top most tab page in a tab canvas.

Applies to  tab canvas

Set  Form Builder, programmatically

Refer to Built-in

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

Default

First tab page that appears under the Tab Page node.


Topmost_Tab_Page restrictions property
Topmost_Tab_Page restrictions

Valid only for tab canvas.


Transactional Triggers property

 All Properties

Description

Identifies a block as a transactional control block; that is, a non-database block that Form Builder should manage as a transactional block.  This property is included for applications that will run against non-ORACLE data sources, and that will include transactional triggers.  If your application will run against ORACLE, leave this property set to No.

When you create a non-ORACLE data source application, you are essentially simulating the functionality of a data block by creating a transactional control block. Such a block is a control block because its base table is not specified at design time (the Base Table block property is NULL), but it is transactional because there are transactional triggers present that cause it to function as if it were a data block.

For more information, see Form Builder Advanced Techniques, Chapter 4, "Connecting to Non-ORACLE Data Sources."

Applies to  block

Set  Form Builder

Default

No

Usage Notes

•	Transactional Triggers applies only when the Base Table property is NULL.

•	Setting Transactional Triggers to Yes enables the Enforce Primary Key and Enforce Column Security properties.


Trigger Style property

 All Properties

Description

Specifies whether the trigger is a PL/SQL trigger or a V2-style trigger.  Oracle Corporation recommends that you write PL/SQL triggers only.  V2-style trigger support is included only for compatibility with previous versions.

Applies to  trigger

Set  Form Builder

Default

PL/SQL

Usage Notes

Choosing V2-Style Trigger enables the Zoom button, which opens the Trigger Step property sheet.


Trigger Text property

 All Properties

Description

Specifies the PL/SQL code that Form Builder executes when the trigger fires.

Applies to  trigger

Set  Form Builder

Required/Optional  required


Trigger Type property

  Related Topics	 All Properties

Description

Specifies the type of trigger, either built-in or user-named.  User-named triggers are appropriate only in special situations, and are not required for most applications.

Applies to:

trigger

Set  Form Builder

Default

PL/SQL

Required/Optional  required

Usage Notes

Trigger type can be one of the following:

Built-i	Specifies that the trigger is one provided by Form Builder and corresponds to a specific, pre-defined runtime event.

User-named	Specifies that the trigger is not provided by Form Builder.  A user-named trigger can only be executed by a call to the EXECUTE_TRIGGER built-in procedure.


Update Allowed (Block) property

 Restrictions	    Related Topics	 All Properties

Description

Determines whether end users can modify the values of items in the block that have the Update Allowed item property set to Yes. (Setting Update Allowed to No for the block overrides the Update Allowed setting of any items in the block.)

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default

Yes


Update Allowed (Block) property restrictions
Update Allowed (Block) restrictions

When the Update Allowed block property is set to Yes, at least one item in the block must have the Update Allowed item property set to Yes for the block to be updateable.


Update Allowed (Item) property

 Restrictions	    Related Topics	 All Properties

Description

Specifies whether end users should be allowed to change the value of the base table item in a queried record. When Update Allowed is set to No, end users can navigate to the item in a queried record, but if they attempt to change its value, Form Builder displays error FRM-40200: Field is protected against update.

Setting Update Allowed to Yes does not prevent end users from entering values in a NEW (INSERT) record.

Applies to  all items except buttons, chart items, and image items

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_INSTANCE_PROPERTY

•	GET_ITEM_PROPERTY

•	SET_ITEM_INSTANCE_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes

Usage Notes

•	To set the Update Allowed (Item) property programmatically, you can use the constant UPDATE_ALLOWED or UPDATEABLE. The constant UPDATEABLE is for compatibility with prior releases.

•	If Enabled is set to PROPERTY_FALSE at runtime, then the items’ or item instance’s Update Allowed property is also set to PROPERTY_FALSE.

•	When Update Allowed is specified at multiple levels (item instance, item, and block), the values are ANDed together. This means that setting Update Allowed to Yes (PROPERTY_TRUE for runtime) has no effect at the item instance level unless it is set consistently at the block and item levels.  For example, your user cannot update an item instance if Update Allowed is true at the instance level, but not at the item or block levels.


Update Allowed (Item) property restrictions
Update Allowed (Item) restrictions

•	If you are using SET_ITEM_PROPERTY to set UPDATE_ALLOWED to true, then you must set item properties as follows:

•	Enabled to Yes (PROPERTY_TRUE for runtime)

•	Visible to Yes (PROPERTY_TRUE for runtime)

•	Base Table Item to Yes (PROPERTY_TRUE for runtime)

•	Update Only If Null to No (PROPERTY_FALSE for runtime)


Update Changed Columns Only property

 All Properties

Description

When queried records have been marked as updates, specifies that only columns whose values were actually changed should be included in the SQL UPDATE statement that is sent to the database during a COMMIT.  By default, Update Changed Columns Only is set to No, and all columns are included in the UPDATE statement.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Default :

No

Required/Optional  optional

Usage Notes

•	If the DML Array Size property is set to a value greater than 1, this Update Changed Columns Only property will be ignored at runtime.  That is, a DML Array Size greater than 1 causes all columns to be updated – even if Update Changed Columns Only was set to Yes.

•	When Update Changed Columns Only is No, Form Builder can reuse the same SQL statement for multiple updates, without having to reparse each time. Setting Update Changed Columns Only to Yes can degrade performance because the UPDATE statement must be reparsed each time. In general, you should only set Update Changed Columns Only to Yes when you know that operators will seldom update column values that will take a long time to transfer over the network, such as LONGs.

•	Set Update Changed Columns Only to Yes in the following circumstances:

To save on network traffic, if you know an operator will primarily update only one or two columns.

To avoid re-sending large items that are not updated, such as images or LONGs.

To fire database triggers on changed columns only.  For example, if you implement a security scheme with a database trigger that fires when a column has been updated and writes the userid of the person performing the update to a table.


Update_Column property

  Related Topics	 All Properties

Description

When set to Yes, forces Form Builder to treat this item as updated.

If the Update Changed Columns Only block property is set to Yes, setting Update Column to Property_True specifies that the item has been updated and its corresponding column should be included in the UPDATE statement sent to the database.

If the Update Changed Columns Only block property is set to Yes, and Update Column is set to Property_False, the item's column will not be included in the UPDATE statement sent to the database.

If the Updated Changed Columns block property is set to No, the Update Column setting is ignored, and all base table columns are included in the UPDATE statement.

Applies to  item

Set  programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Required/Optional  optional

Usage Notes

The main use for this property is in conjunction with Update Changed Columns Only.  However, whether or not Update Changed Columns Only is set to Yes, you can use this property to check whether a given column was updated.

Note:  Although Update Column affects Record Status, setting this property to Property_Off for all columns will not return Record Status to QUERY.  If you want Record Status to revert to QUERY, you must set it explicitly with SET_RECORD_PROPERTY.


Update Commit property

 All Properties

Description

Specifies whether a chart item is updated to reflect changes made by committing new or updated records to its source block.

Applies to  chart item

Set  Form Builder

Default

Yes

Required/Optional  required


Update Layout property

 All Properties

Description

Specifies when the frame's layout is updated.

Automatically	The layout is updated whenever the frame is moved or resized or whenever any frame layout property is modified.

Manually	The layout is updated whenever the Layout Wizard is used to modify a frame or whenever the user clicks the Update Layout button or menu option.

Locked	The layout is locked and cannnot be updated.

Applies to  frame

Set  Form Builder

Default

Yes

Required/Optional  required


Update Only if NULL property

 Restrictions	    Related Topics	 All Properties

Description

Indicates that operators can modify the value of the item only when the current value of the item is NULL.

Applies to  image items, list items, sound items, text items

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

No

Required/Optional  optional

Usage Notes

To set the Update Only if NULL property programmatically, use the constant UPDATE_NULL.


Update Only if NULL restrictions property
Update Only if NULL restrictions

Item properties must be set as follows:

•	Enabled set to Yes

•	Visible set to Yes

•	Update Allowed set to No


Update_Permission property

  Related Topics	 All Properties

Description

Setting Update_Permission to No performs the following three actions:

•	Sets the Update_If_Null property to No.

•	Sets the Update Allowed property to No.

•	Specifies that this column should not be included in any UPDATE statements issued by Form Builder, by removing that column from the SET clause of the UPDATE statements.

Applies to  all items except buttons and chart items

Set  programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

Default

Yes

Required/Optional  optional

Usage Notes

Update_Permission allows form developers to implement their own security mechanism, overriding the Form Builder default Enforce Column Security property.  This property is included primarily for applications that will run against non-ORACLE data sources.  Use Update_Permission when you want to exclude certain columns from any UPDATE statements:  for example, when using an On-Column-Security trigger to implement a custom security scheme.


Update Procedure Arguments property

  Related Topics	 All Properties

Description

Specifies the names, datatypes, and values of the arguments that are to be passed to the procedure for updating data.  The Update Procedure Arguments property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Update Procedure Name property

  Related Topics	 All Properties

Description

Specifies the name of the procedure to be used for updating data.  The Update Procedure Name property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Update Procedure Result Set Columns property

  Related Topics	 All Properties

Description

Specifies the names and datatypes of the result set columns associated with the procedure for updating data.  The Update Procedure Result Set Columns property is valid only when the DML Data Target Type property is set to Procedure.

Applies to  block

Set  Form Builder

Default

NULL

Required/Optional  optional


Update Query property

 All Properties

Description

Specifies whether a chart item is updated to reflect changes made by querying records in its source block.

Applies to  chart item

Set  Form Builder

Default

Yes

Required/Optional  required


Use Security property

 Restrictions	    Related Topics	 All Properties

Description

Specifies that Form Builder should enforce the security scheme defined for the menu module, using the Menu Module Roles property.

Applies to  menu module

Set  Form Builder

Default

No

Usage Notes

This property can be set to No so that developers can test a menu module without having to be members of any database role.  Use Security can then be set to Yes at production to enforce those roles.


Use Security restrictions property
Use Security restrictions

none


Use 3D Controls property

 Restrictions	    Related Topics	 All Properties

Description

On Microsoft Windows, specifies that Form Builder displays items with a 3-dimensional, beveled look.

When Use 3D Controls is set to Yes, any canvas that has Visual Attribute Group set to Default will automatically be displayed with background color grey.

In addition, when Use 3D Controls is set to Yes, the bevel for each item automatically appears lowered, even if an item-level property is set, for example, to raised.

Applies to  form

Set  Form Builder

Default

For a new form, Yes. For a form upgraded from a previous version of Form Builder, No.


Use 3D Controls restrictions property
Use 3D Controls restrictions

Valid only on Microsoft Windows.


Username property

 All Properties

Description

Specifies the username of the current operator.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY

Usage Notes

May be used with the LOGON built-in in an On-Logon trigger or for connecting to a non-ORACLE data source.

The Username property returns only the username.  If you want a connect string as well, examine the Connect_String property.


User_Date/Datetime_Format property

  Related Topics	 All Properties

Description

Holds the current date or datetime format mask established by the environment variable FORMSnn_USER_DATE_FORMAT or FORMSnn_USER_DATETIME_FORMAT.

There are two separate properties:  User_Date_Format and User_Datetime_Format.

Applies to  application

Set  Not settable from within Form Builder.

Refer to Built-in

GET_APPLICATION_PROPERTY


User_Interface property

 All Properties

Description

Specifies the name of the user interface currently in use.

Applies to  application

Set  not settable

Refer to Built-in

GET_APPLICATION_PROPERTY

Usage Notes

This property returns one of the following values:

•	BLOCKMODE

•	CHARMODE

•	MACINTOSH

•	MOTIF

•	MSWINDOWS

•	MSWINDOWS32

•	PM

•	WIN32COMMON

•	WEB

•	X


User_NLS_Date_Format property

  Related Topics	 All Properties

Description

Obtains the current NLS date format mask.

Applies to  application

Set  Not settable from within Form Builder.

Refer to Built-in

GET_APPLICATION_PROPERTY

Note that this property is read-only.  That is, you cannot specify it in SET_APPLICATION_PROPERTY.

For example, if you wanted to set the PLSQL_DATE_FORMAT property to the current NLS date format mask value, you could code the following in a WHEN-NEW-FORM-INSTANCE trigger in your application:

     SET_APPLICATION_PROPERTY(PLSQL_DATE_FORMAT,
                              GET_APPLICATION_PROPERTY(USER_NLS_DATE_FORMAT));

Default

None.


User_NLS_Lang property

 All Properties

Description

Specifies the complete value of the NLS_LANG environment variable defined for the current Runform session, for national language support.  USER_NLS_LANG is the equivalent of concatenating the following properties:

•	USER_NLS_LANGUAGE (language only)

•	USER_NLS_TERRITORY (territory only)

•	USER_NLS_CHARACTER_SET (character set only)

Applies to  application

Set  Not settable from within Form Builder.  Set at your operating system level.

Refer to Built-in

GET_APPLICATION_PROPERTY

Default

Default is usually "America_American.WE8ISO8859P1," but all the defaults can be port-specific.


Validate from List property

  Related Topics	 All Properties

Description

Specifies whether Form Builder should validate the value of the text item against the values in the attached LOV.

Applies to  text item

Set  Form Builder

Default

No

Required/Optional  optional

Restrictions:

List of Values property must be specified.

Usage Notes

When Validate from List is Yes, Form Builder compares the current value of the text item to the values in the first column displayed in the LOV whenever the validation event occurs:

•	If the value in the text item matches one of the values in the first column of the LOV, validation succeeds, the LOV is not displayed, and processing continues normally.

•	If the value in the text item does not match one of the values in the first column of the LOV, Form Builder displays the LOV and uses the text item value as the search criteria to automatically reduce the list.

For example, if the operator enters the first three digits of a 6-digit product code and then tries to navigate to the next item, Form Builder displays the LOV and auto-reduces the list to display all of the codes that have the same first three digits.

•	If the operator selects a value from the LOV, Form Builder dismisses the LOV and assigns the selected values to their corresponding return items.

When you use an LOV for validation, Form Builder generally marks a text item as Valid if the operator selects a choice from the LOV.  Thus, it is your responsibility to ensure that:

•	the text item to which the LOV is attached is defined as a return item for the first column displayed in the LOV and

•	the values in the LOV are valid

Note, however, that a When-Validate-Item trigger on the item still fires, and any validation checks you perform in the trigger still occur.

Note also that the first column displayed in the LOV may not be the first column in the LOV's underlying record group, as some record group columns may not have been included in the LOV structure, or may be hidden columns.


Validation property

 All Properties

Description

Specifies whether default Form Builder validation processing has been enabled or disabled for a form.

Applies to  form module

Set  programmatically

Refer to Built-in

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY

Default

Yes

Usage Notes

Use this property with caution, because when you set Validation to No all internal form validation will be bypassed and no WHEN-VALIDATE triggers will fire.

You can programmatically set Validation to No for only brief periods of time when you specifically want to avoid all default Form Builder validation behavior.  Once you set Validation to Yes again, any text items left in an unvalidated state will be validated according to normal processing rules.

When Validation is set to No, the Post-Change trigger will fire during query processing but will not fire elsewhere.


Validation Unit property

 All Properties

Description

Specifies the scope of form validation at runtime.  Specifically, the validation unit defines the maximum amount of data that an operator can enter in the form before Form Builder initiates validation.  For most applications, the Validation Unit is Item (default setting on most platforms), which means that Form Builder validates data in an item as soon as the operator attempts to navigate out of the item.

Applies to  form module

Set  Form Builder, programmatically

Refer to Built-in

•	GET_FORM_PROPERTY

•	SET_FORM_PROPERTY

Default

Default

Usage Notes

The following settings are valid for this property:

•	Default

•	Form

•	Block

•	Record

•	Item


Value when Checked property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the value you want the check box to display as the checked state.  For example, Y, 1, MANAGER, or 1992.  When a value that matches the checked value is fetched or assigned to the check box, the check box is displayed checked.  Similarly, when the operator toggles the check box to the checked state, the value of the check box becomes the checked value.

Applies to  check box

Set  Form Builder

Default

NULL

Required/Optional  optional


Value when Checked restrictions property
Value when Checked restrictions

The value must be compatible with the datatype specified by the Parameter Data Type property.


Value when Unchecked property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the value you want the check box to display as the unchecked state.  For example, Y, 1, MANAGER, or 1992.  When a value that matches the unchecked value is fetched or assigned to the check box, the check box is displayed unchecked.  Similarly, when the operator toggles the check box to the unchecked state, the value of the check box becomes the unchecked value.

Applies to  check box

Set  Form Builder

Default

NULL

Required/Optional  Optional; leaving this property blank makes the Unchecked value NULL.


Value when Unchecked restrictions property
Value when Unchecked restrictions

The value must be compatible with the datatype specified by the Parameter Data Type property.


VBX Control File property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the VBX file selection.

Applies to  VBX Control

Set  Form Builder

Default

none

Required/Optional  required

Usage Notes

The selection of a VBX file determines which VBX controls are available for use.  The number and type of VBX files available for selection depends on the third-party VBX controls that are installed on your system.

Because moving a form module with hard-coded paths to another computer system can make the VBX file and location invalid, you  should avoid specifying an absolute path for the VBX Control File property.

For a VBX control file that is not associated with an absolute path, the search criteria is the system default search path.  If all default search paths fail to locate the specified VBX control file, the FORMS60_PATH parameter in the ORACLE.INI file becomes the search criteria for finding the VBX control file.  If all search paths in the FORMS60_PATH parameter fail to locate the VBX control file, a runtime error message informs you that the VBX control cannot be found.


VBX Control File restrictions property
VBX Control File restrictions

Valid only on Microsoft Windows 3.x (16-bit).


VBX Control Name property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the VBX control selection from a VBX file.  Some VBX files contain more than a single VBX control. You must specify which VBX control to use even when a VBX file contains on a single VBX control.

Applies to  VBX Control

Set  Form Builder

Default

none


VBX Control Name restrictions property
VBX Control Name restrictions

Valid only on Microsoft Windows 3.x (16-bit).


VBX Control Value property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the value property of a VBX control.  This property determines the value of the VBX custom item in Form Builder.

Applies to  VBX Control

Set  Form Builder

Refer to Built-in

•	VBX.GET_VALUE_PROPERTY

•	VBX.SET_VALUE_PROPERTY

Default

Most VBX controls have a default value property.  If the default value property exists, it is the default Form Builder VBX Control Value Property.  If the VBX control does not have a default value property, the Form Builder VBX Control Value Property is the VBX property named "value".  If the VBX property "value" does not exist, a default value property is not assigned to the Form Builder VBX Control Value Property.

Required/Optional  required

Usage Notes

The VBX CONTROL VALUE PROPERTY automatically synchronizes itself with a VBX property.  Changes to the VBX property are reflected in the VBX CONTROL VALUE PROPERTY.


VBX Control Value property restrictions property
VBX Control Value restrictions

Valid only on Microsoft Windows 3.x (16-bit).


Vertical Fill property

 All Properties

Description

Specifies whether the Layout Wizard uses the empty space surrounding an object when the Layout Style property is set to Form.

Yes	Specifies that the Layout Wizard should use all available space when arranging frame objects.  Consequently, Form Builder ignores the Maximum Objects Per Line property.

No	Specifies that the Layout Wizard should not use all available space when arranging frame objects.  When objects wrap, they begin on the next frame line.

Applies to  frame

Set  Form Builder

Default

Yes

Required/Optional  required


Vertical Justification property

 All Properties

Description

Specifies the vertical justification of the text object as either Top, Center, or Bottom.

Applies to  graphic text

Set  Form Builder

Default

Top

Required/Optional  required


Vertical Margin property

 Show Me	 All Properties

Description

Specifies the distance between the frame's top and bottom borders and the objects within the frame.

Applies to  frame

Set  Form Builder

Default

1 character cell (or the equivalent based on the form coordinate system)

Required/Optional  required


Vertical Margin showme
Vertical Margin


Vertical Object Offset property

 Show Me	 All Properties

Description

Specifies the vertical distance between the objects within a frame.

Applies to  frame

Set  Form Builder

Default

0

Required/Optional  required


Vertical Object Offset showme
Vertical Object Offset


Vertical Origin property

 All Properties

Description

Specifies the vertical position of the text object relative to its origin point as either Top, Center, or Bottom.

Applies to  graphic text

Set  Form Builder

Default

Top

Required/Optional  required


Vertical Toolbar Canvas property

  Related Topics	 All Properties

Description

Specifies the canvas that should be displayed as a vertical toolbar on the window. The canvas you specify must be a vertical toolbar canvas (Canvas Type property set to Vertical Toolbar) and must be assigned to the current window by setting the Window property.

Applies to  window

Set  Form Builder

Default

Null

Required/Optional  required if you are creating a vertical toolbar

Usage Notes

•	In the Properties window, the poplist for this property shows only canvases that have the Canvas Type property set to Vertical Toolbar.

•	At runtime, Form Builder attempts to display the specified vertical toolbar on the window. However, if more than one toolbar of the same type has been assigned to the same window (by setting the canvas Window property to point to the specified window), Form Builder may display a different toolbar in response to navigation events or programmatic control.

•	On Microsoft Windows, the specified vertical toolbar canvas will not be displayed on the window if you have specified that it should instead be displayed on the MDI application window by setting the Form Vertical Toolbar Canvas form property.


Viewport Height, Viewport Width
Viewport Height, Viewport Width property

 Restrictions	 All Properties

Description

Specifies the width and height of the view for a stacked canvas.  The size and position of the view define the part of the canvas that is actually displayed in the window at runtime.

Note: For a content or toolbar canvas, the view is represented by the window to which the canvas is assigned, and so the Viewport Height and Viewport Width properties do not apply.

Applies to  canvas

Set  Form Builder, programmatically

Refer to Built-in

SET_VIEW_PROPERTY

Default

0,0

Required/Optional  optional


Viewport Height, Viewport Width restrictions

Valid only for a stacked view (Canvas Type property set to Stacked).  For a content view, the viewport size is determined by the runtime size of the window in which the content view is displayed.


Viewport X Position, Viewport Y Position
Viewport X Position, Viewport Y Position property

 Restrictions	    Related Topics	 All Properties

Description

Specifies the x,y coordinates for the stacked canvas's upper left corner relative to the upper left corner of the window's current content view.

Applies to  canvas

Set  Form Builder, programmatically

Refer to Built-in

•	GET_VIEW_PROPERTY

•	SET_VIEW_PROPERTY

Default

0,0

Required/Optional  optional


Viewport X Position, Viewport Y Position restrictions

Not valid for a content canvas view; that is, a canvas view that has the Canvas Type property set to Content.


Viewport X Position on Canvas, Viewport Y Position on Canvas
Viewport X Position on Canvas, Viewport Y Position on Canvas property

  Related Topics	 All Properties

Description

Specifies the location of the view's upper left corner relative to the upper left corner of the canvas.  The size and location of the viewport define the view; that is, the part of the canvas that is actually visible in the window to which the canvas is assigned.

Applies to  canvas

Set  Form Builder, programmatically

Refer to Built-in

•	GET_VIEW_PROPERTY

•	SET_VIEW_PROPERTY

Default

0,0


Visible property

  Related Topics	 All Properties

Description

Indicates whether the object is currently displayed or visible.  Set Visible to Yes or No to show or hide a canvas or window.

Applies to  canvas, window

Set  programmatically

Refer to Built-in

•	GET_VIEW_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_VIEW_PROPERTY

•	SET_WINDOW_PROPERTY

Default

TRUE

Usage Notes

•	You cannot hide the canvas that contains the current item.

•	You can hide a window that contains the current item.

NOTE: In some operating systems, it is possible to hide the only window in the form.

•	When you use GET_WINDOW_PROPERTY to determine window visibility, Form Builder uses the following rules:

•	A window is considered visible if it is displayed, even if it is entirely hidden behind another window.

•	A window that has been iconified (minimized) is reported as visible to the operator because even though it has a minimal representation, it is still mapped to the screen.

•	When you use GET_VIEW_PROPERTY to determine canvas visibility, Form Builder uses the following rules:

•	A view is reported as visible when it is a) in front of all other views in the window or b) only partially obscured by another view.

•	A view is reported as not visible when it is a) a stacked view that is behind the content view in the window or b) completely obscured by a single stacked view. Note that a view is reported as visible even if it is completely obscured by a combination of two or more stacked views.

•	The display state of the window does not affect the setting of the canvas VISIBLE property.  That is, a canvas may be reported visible even if the window in which it is displayed is not currently mapped to the screen.


Visible (Canvas) property

 Restrictions	    Related Topics	 All Properties

Description

Determines whether a stacked canvas is initially shown or hidden in the window to which it is assigned.

Applies to:

stacked canvas

Set:

Form Builder, programmatically

Refer to Built-in

•	GET_VIEW_PROPERTY (VISIBLE)

•	SET_VIEW_PROPERTY (VISIBLE)

Default:

Yes


Visible (Canvas) restrictions property
Visible (Canvas) restrictions

•	A displayed view may not be visible if it is behind the content view or another stacked view assigned to the same window.


Visible (Item) property

 Restrictions	 All Properties

Description

Determines whether an item that is assigned to a canvas is shown or hidden at runtime.

Applies to  all items

Set  Form Builder, programmatically

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

Default

Yes

Usage Notes

•	To set the Visible (Item) property programmatically, you can use the constant VISIBLE or DISPLAYED. The constant DISPLAYED is for compatibility with prior releases.


Visible (Item) property restrictions
Visible (Item) restrictions

When the item is part of the foreign key in a default master-detail relation, the default is No.


Visible (Tab Page) property

 All Properties

Description

Determines whether a tab page is shown or hidden at runtime.

Applies to:

tab page

Applies to:

Form Builder, programmatically

Refer to Built-in

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

Default:

Yes


Visible in Horizontal/Vertical Menu Toolbar
Visible in Horizontal/Vertical Menu Toolbar property

 Restrictions	    Related Topics	 All Properties

Description

Specifies whether the menu item should appear (represented by an icon) on the horizontal or vertical menu toolbar (or both) of a form.

Applies to  menu item

Set  Form Builder

Default

No

Required/Optional  optional


Visible in Horizontal/Vertical Menu Toolbar restrictions

Developers must provide icons to associate with each menu item that appears on a menu toolbar.


Visible in Menu property

 All Properties

Description

Determines whether the menu item is shown or hidden at runtime.

Applies to:

menu item

Set:

Form Builder, programmatically

Refer to Built-in

•	GET_MENU_ITEM_PROPERTY

•	SET_MENU_ITEM_PROPERTY

Default:

Yes


Visual Attribute property

 Restrictions	 All Properties

Description

Specifies the named visual attribute that should be applied to the object at runtime.  A visual attribute defines a collection of font, color, and pattern attributes that determine the appearance of the object.

Applies to  canvas, tab page, item, radio button

Set  programmatically

Refer to Built-in

•	GET_ITEM_INSTANCE_PROPERTY

•	GET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	GET_TAB_PAGE_PROPERTY

•	SET_CANVAS_PROPERTY

•	SET_ITEM_INSTANCE_PROPERTY

•	SET_ITEM_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

•	SET_TAB_PAGE_PROPERTY

Usage Notes

When you execute the appropriate GET_ built-in function to determine the setting of this property at runtime, the return value is one of the following:

•	the name of a named visual attribute

•	the name of a logical attribute defined in the resource file

•	DEFAULT (the item uses the default attributes defined in the resource file)


Visual Attribute property restrictions
Visual Attribute restrictions

The visual attribute must be a named visual attribute defined in the form module or a logical attribute defined in the runtime resource file.


Visual Attribute Group property

  Related Topics	 All Properties

Description

Specifies how the object's individual attribute settings (Font Name, Background Color, Fill Pattern, etc.) are derived. The following settings are valid for this property:

Default	Specifies that the object should be displayed with default color, pattern, and font settings. When Visual Attribute Group is set to Default, the individual attribute settings reflect the current system defaults. The actual settings are determined by a combination of factors, including the type of object, the resource file in use, and the platform.
Named visual attribute	Specifies a named visual attribute that should be applied to the object. Named visual attributes are separate objects that you create in the Object Navigator and then apply to interface objects, much like styles in a word processing program. When Visual Attribute Group is set to a named visual attribute, the individual attribute settings reflect the attribute settings defined for the named visual attribute object. When the current form does not contain any named visual attributes, the poplist for this property will show Default.
Applies to  all interface objects

Set  Form Builder

Default

Default

Usage Notes

•	Default and named visual attributes can include the following individual attributes, listed in the order they appear in the Property Palette:

Font Name  The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

Font Size  The size of the font, specified in points.

Font Style  The style of the font.

Font Spacing  The width of the font, that is, the amount of space between characters (kerning).

Font Weight  The weight of the font.

Foreground Color  The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

Background Color  The color of the object's background region.

Fill Pattern  The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

Character Mode Logical Attribute  Specifies the name of a character mode logical attribute defined in an Oracle Terminal resource file that is to be used as the basis of device attributes for a character mode version of your application.

White on Black  Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

Not all attributes are valid for each object type. For example, setting font attributes for a window object has no effect. (The font used in a window's title bar is derived from the system.)

•	A new object in a new form has Default visual attributes. The default settings are defined internally. You can override the default font for new items and boilerplate by setting the optional FORMS60_DEFAULTFONT environment variable. For example, on Microsoft Windows, you can set this variable in the registry, as follows: FORMS60_DEFAULTFONT="COURIER.10". The default font specified determines the font used for new boilerplate text generated by the New Block window, and for any items that have Visual Attribute Group set to Default.

•	When you create an item in the Layout Editor, its initial visual attribute settings are determined by the current Layout Editor settings for fonts, colors, and patterns, as indicated by the Font dialog and Color and Pattern palettes.

•	On Microsoft Windows, the colors of buttons, window title bars, and window borders are controlled by the Windows Control Panel color settings specified for these elements. You cannot override these colors in Form Builder.

•	When the Use 3D Controls form property is set to Yes on Microsoft Windows (the default), items are rendered with shading that provides a sculpted, three-dimensional look.  A side effect of setting this property is that any canvases that have Visual Attribute Group set to Default derive their color setting from the Windows Control Panel (gray for most color schemes). You can override this setting by explicitly applying named visual attributes to the canvas.

•	An item that has Visual Attribute Group set to Default, or that has individual attribute settings left unspecified, inherits those settings from the canvas to which it is assigned. Similarly, a canvas that has Visual Attribute Group set to Default, or that has individual attribute settings left unspecified, inherits those settings from the window in which it is displayed. For example, if you set a window's Background Color to CYAN, and then leave Background Color unspecified for the canvas assigned to the window, at runtime, that canvas will inherit the CYAN background from its window. Visual attribute settings derived through window--canvas or canvas--item inheritance are apparent at design time if the Layout Editor is reopened.

•	You can apply property classes to objects to specify visual attribute settings. A property class can contain either the Visual Attribute Group property, or one or more of the individual attribute properties. (If a property class contains both Visual Attribute Group and individual attributes, the Visual Attribute Group property takes precedence.)

•	If you apply both a named visual attribute and a property class that contains visual attribute settings to the same object, the named visual attribute settings take precedence, and the property class visual attribute settings are ignored.

•	Logical attribute definitions defined in the resource file take precedence over visual attributes specified in the Form Builder, local environment variable definitions, and default Form Builder attributes. To edit the resource file, use the Oracle Terminal utility.


Visual Attribute Type property

 All Properties

Description

Specifies the type of the visual attribute during design time as either Common, Prompt, or Title.

Applies to  visual attribute general

Set  Form Builder

Default  Common

Required/Optional  required


WHERE Clause/ORDER BY Clause

 Examples	   Restrictions	    Related Topics	 All Properties

Description

The default WHERE Clause and default ORDER BY Clause properties specify standard SQL clauses for the default SELECT statement associated with a data block. These clauses are automatically appended to the SELECT statement that Form Builder constructs and issues whenever the operator or the application executes a query in the block.

Applies to  block

Set  Form Builder, programmatically

Refer to Built-in

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

Required/Optional  optional

Usage Notes

1	The reserved words WHERE and ORDER BY are optional.  If you do not include them, Form Builder automatically prefixes the statement with these words.

2	WHERE Clause can reference the following objects:

•	columns in the block's data block table (except LONG columns)

•	form parameters (:PARAMETER.my_parameter)

3	ORDER BY Clause can reference the following objects:

•	columns in the block's data block table (except LONG columns)

4	Embedded comments are not supported in WHERE Clause and ORDER BY Clause.


WHERE Clause/ORDER BY Clause restrictions

•	Maximum length for WHERE Clause is 32,000 bytes.

•	ORDER BY clause cannot reference global variables or form parameters.


WHERE Clause/ORDER BY Clause examples

Example

In the following example from an order tracking system, the WHERE Clause limits the retrieved records to those whose shipdate column is NULL.  The ORDER BY Clause arranges the selected records from the lowest (earliest) date to the highest (latest) date.

WHERE shipdate IS NULL
ORDER BY orderdate

This WHERE Clause/ORDER BY Clause statement specifies the base conditions for record retrieval.  The operator can further restrict the records retrieved by placing the form in Enter Query mode and entering ad hoc query conditions.


White on Black property

  Related Topics	 All Properties

Description

Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

Applies to  item, tab page, canvas, window, radio button

Set  Programmatically

Default

Unspecified

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

•	GET_TAB_PAGE_PROPERTY

•	SET_TAB_PAGE_PROPERTY

•	GET_CANVAS_PROPERTY

•	SET_CANVAS_PROPERTY

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY


Width/Height (WD, HT)

 All Properties

Description

See Size


Window property

  Related Topics	 All Properties

Description

Specifies the window in which the canvas will be displayed at runtime.

Applies to  canvas

Set  Form Builder

Refer to Built-in

GET_VIEW_PROPERTY

Default

ROOT_WINDOW, if there is a root window in the form, else the first window listed under the Windows node in the Object Navigator.

Required/Optional  required for the canvas to be displayed at runtime


Window_Handle property

 Restrictions	 All Properties

Description

On Microsoft Windows, a window handle is a unique internal character constant that can be used to refer to objects. It is possible to obtain a window handle for any item or window.

Applies to  form, block, item

Refer to Built-in

•	GET_ITEM_PROPERTY

•	GET_WINDOW_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

Default

NULL

Usage Notes

•	Specify the name of the item and the WINDOW_HANDLE property in GET_ITEM_PROPERTY to obtain the window handle to an item.

•	Specify the name of the window and the WINDOW_HANDLE property in GET_WINDOW_PROPERTY to obtain the window handle to a window.  If the name of the window of GET_WINDOW_PROPERTY is FORMS_MDI_WINDOW, the return value is a handle to the MDI client window. The handle to a MDI client window is used to create child MDI windows and controls.

•	Specify the item name or item id of the radio group, the name of the radio button, and the WINDOW_HANDLE property in GET_RADIO_BUTTON_PROPERTY to obtain a window handle to a radio button.

•	To obtain a window handle to a radio group, use the name of the radio group as the item name in GET_ITEM_PROPERTY.  A window handle to the button that is in focus is returned.  If no button is in focus, the window handle to the button that is selected is returned.  If neither a focused or selected button exists, the window handle to the first button is returned.


Window_Handle restrictions property
Window_Handle restrictions

Valid only on Microsoft Windows. (Returns NULL on other platforms.)


Window_State property

 Restrictions	 All Properties

Description

Specifies the current display state of the window:

NORMAL	Specifies that the window should be displayed normally, according to its current Width, Height, X Position, and Y Position property settings.

MINIMIZE	Specifies that the window should be minimized, or iconified so that it is visible on the desktop s a bitmap graphic.

MAXIMIZE	Specifies that the window should be enlarged to fill the screen according to the display style of the window manager.

Applies to  window

Set  Programmatically

Refer to Built-in

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY

Default

NORMAL

Usage Notes

The minimize and maximize display states are managed by the window manager and do not affect the window's current width and height settings, as defined by the Width and Height properties. Thus, if a window display state is currently minimized or maximized, any call to SET_WINDOW_PROPERTY or RESIZE_WINDOW that changes the Width or Height properties will be applied, but will not become apparent to the operator until the window is returned to the Normal state.

Similarly, GET_WINDOW_PROPERTY always returns the window's current Width and Height property settings, even if the window is currently in the minimized or maximized display state.


Window_State restrictions property
Window_State restrictions

Setting Window_State to MAXIMIZE is not supported on Motif.


Window Style property

  Related Topics	 All Properties

Description

Specifies whether the window is a Document window or a Dialog window.  Document and dialog windows are displayed differently on window managers that support a Multiple Document Interface (MDI) system of window management.

Applies to  window

Set  Form Builder

Default

Document

Restrictions:

Valid only for a secondary window.  (A root window is always a document window.)

Usage Notes

MDI applications display a default parent window, called the application window.  All other windows in the application are either document windows or dialog windows.

Document windows always remain within the application window frame.  If the operator resizes the application window so that it is smaller than a document window, the document window is clipped.  An operator can maximize a document window so that is occupies the entire workspace of the application window.

Dialog windows are free-floating, and the operator can move them outside the application window if they were defined as Movable.  If the operator resizes the application window so that it is smaller than a dialog window, the dialog window is not clipped.


Wrap Style property

 Restrictions	    Related Topics	 All Properties

Description

Specifies how text is displayed when a line of text exceeds the width of a text item or editor window.

The following list describes the allowable values for this property:

NONE	No wrapping: text exceeding the right border is not shown.

CHARACTER	Text breaks following the last visible character, and wraps to the next line.

WORD	Text breaks following last visible complete word, and wraps to the next line.

Applies to  text item, editor

Set  Form Builder

Refer to Built-in

GET_ITEM_PROPERTY

Default

WORD


Wrap Style restrictions property
Wrap Style restrictions

Valid only for multi-line text items.


Wrap Text property

  Related Topics	 All Properties

Description

Specifies whether the text in the text object wraps to the next line to fit within the bounding box.

Applies to  graphic text

Set  Form Builder

Default

Yes

Required/Optional  required


X Corner Radius property

 All Properties

Description

Specifies the amount of horizontal rounding (in layout units) of the corners of the rounded rectangle.

Applies to  graphic rounded rectangle

Set  Form Builder

Default

10

Required/Optional  required


X Position, Y Position
X Position, Y Position property

 Restrictions	 All Properties

Description

For an object, specifies where it appears on the screen.  For an item, specifies the position of the item's upper left corner relative to the upper left corner of the item's canvas.  The values you specify are interpreted in the current form coordinate units (character cells, centimeters, inches, pixels, or points), as specified by the Coordinate System form property.

Applies to  all items, editors, LOVs, windows, canvases

Set  Form Builder, programmatically

Usage Notes

The following information is specific to the current object.

ITEM

Determines where the item appears on the owning canvas.

Refer to Built-in

•	GET_ITEM_PROPERTY

•	SET_ITEM_PROPERTY

•	GET_RADIO_BUTTON_PROPERTY

•	SET_RADIO_BUTTON_PROPERTY

Default

x,y(0,0)

LOV

Determines where the LOV appears on the screen:  (0,0) is the upper left corner of the entire screen, regardless of where the root window appears on the screen.  The LOV can be displayed anywhere on the screen, including locations outside the form.

Refer to Built-in

•	GET_LOV_PROPERTY

•	SET_LOV_PROPERTY

Default

x,y(0,0)

WINDOW

Determines where the window appears on the screen:  (0,0) is the upper left corner of the entire screen.

Refer to Built-in

•	GET_WINDOW_PROPERTY

•	SET_WINDOW_PROPERTY

Default

x,y(0,0)


X Position, Y Position restrictions

•	Values for all items, editors, and LOVs must be non-negative.

•	Precision allowed is based on the current form coordinate units.  Rounding may occur when necessary.


Y Corner Radius property

 All Properties

Description

Specifies the amount of vertical rounding (in layout units) of the corners of the rounded rectangle.

Applies to  graphic rounded rectangle

Set  Form Builder

Default

10

Required/Optional  required


Windows and Canvases

Question

How can I change the title of my RUNFORM window?

Answer

Use the following code in a When-New-Form-Instance trigger:

Set_Window_Property(FORMS_MDI_WINDOW, TITLE, 'Your Title');


Items, Records, and Blocks

Question

How does a Display Item differ from a normal Text Item?

Answer

A Display Item is essentially a permanently non-enterable text-item. It can be used for implementing variable text, or for any on-screen values which do not require operator interaction (date/time, for example).

Since Display Items possess a "subset" of the features that a text item provides, they require slightly less memory for their definition.

Question

Why do I get a null entry in my drop-down list at startup?

Answer

Consider a drop-down list with the values:

Label      Value

-------    --------

One         1

Two         2

Three       3

If you have a drop-down list that is in a block where a record is yet to be instantiated, then the drop-down list item has a NULL value.  To visually reflect this, we show a blank label in the drop-down list.  To show the blank label on the form, add a NULL value to the list at the bottom, and set the value of the control to NULL.

In addition, if the item is not required, then we automatically add an empty list element to the set of choices so that the user can pick NULL as one of the values.

The trick is, as for any item, if you want some value to appear in the item at startup, you have to set the value or instantiate the record in the item's block so that the item takes on its default values.

Question

How can I dynamically prevent the user from entering a new record?

Answer

Have a When-New-Record-Instance trigger that does the following:

IF ((dynamic-condition-is-true) AND

   :System.Record_Status = 'NEW')

THEN

   RAISE Form_Trigger_Failure;

END IF;

Question

How can I dynamically make an entire block query-only at runtime?

Answer

Issue the following :

Set_Block_Property('blockname', INSERT_ALLOWED, PROPERTY_OFF);

Set_Block_Property('blockname', UPDATE_ALLOWED, PROPERTY_OFF);

Question

How can I change the color and font of an item dynamically at runtime?

Answer

Using the built-in Set_Item_Property:

Set_Item_Property( 'Blockname.Itemname', VISUAL_ATTRIBUTE, 'VisualAttributeName' );

Where 'VisualAttributeName' is either the name of a visual attribute you've set up in the form (which has foreground, background, font, etc.), or is the name of a logical visual attribute from the resource file.

Question

How can I have an item which acts like a disabled item, but  is not greyed out?

Answer

The INSERT_ALLOWED and UPDATE_ALLOWED attributes solve this problem.  Items with these attributes set to OFF don't show as disabled items but do not allow the user to change the values in either new or queried records.

Question

What exactly does 'Query Hits' and 'Query Options' mean in the context of a block?

Answer

Set_Block_Property(.., QUERY_HITS) lets your ON-COUNT transactional trigger tell Form Builder how many records the query (that you are handling yourself) will return so it may print out the message :

"FRM-xxxxx: Query will retrieve nnn record(s)."

Getting this property via Get_Block_Property(.., QUERY_HITS) simply returns the number of records that have been retrieved by the query.

Get_Block_Property(.., QUERY_OPTIONS) lets your transactional trigger know whether it's supposed to be doing a normal query, a COUNT(*) type query, or a lock record query.


Record Groups, Global Variables, and Parameters

Question

What should I be using Record Groups for?

Answer

Structurally, a Record Group is similar to an in-memory Oracle table in that it has a row/column framework and columns with datatypes of NUMBER, CHAR, and DATE.

Since record groups do not currently have any record buffering mechanism in Form Builder 6.0 akin to that offered by the database block object, populating a record group from a query should be done with caution.  Using a query that returns 10,000 records will allocate memory to fetch and store all rows returned from the query.

In particular, record groups are not designed to be a replacement for database tables while your application is running.  They may be optimal for relatively small lists of lookup values, or medium-sized data structures for application record-keeping on the client side.

For new applications, you should also consider the Table of Records construct provided by PL/SQL V2.3. A Table of Records is often more efficient in its memory usage and is generally faster to access.

On the other hand, a record group can be constructed dynamically at runtime, whereas the structure of a table of records is determined at design-time.  If flexibility of structure is required by your application, use a Record Group rather than a table of Records.

Question

When should I use global, parameter, or package variables?

Answer

There is no single right answer to this, but here are some guidelines that might help you decide:

Datatype:  Globals are always CHAR data.  Parameters are NUMBER, CHAR, or DATE.  Package variables can be any PL/SQL data type.

Creation:  Globals are created the first time they are assigned.

Parameters must be named and typed at design-time, or alternately may be added to a parameter list at runtime with the Add_Parameter() built-in.

Package variables are explicitly declared as part of a package.

Default Values:  Globals must have a value programmatically assigned.

Parameters can be assigned a default value of the proper datatype at design-time.

Package variables can be assigned a default value of the proper datatype at design-time.  Package variables can also be initialized with arbitrarily complex code in the initialization block of the package.

Assignment:  Globals are assigned directly through PL/SQL with the bind variable notation (:GLOBAL.GLOBAL_NAME), or indirectly using the Copy() built-in.

Parameters in the default parameter list (those created at design-time) are assigned directly through PL/SQL with the bind variable notation (:PARAMETER.PARAM_NAME), or indirectly with the Copy() built-in.  If part of a parameter list is not the default parameter list, then the Set_Parameter_Attr() built-in is used. In addition, parameters which are declared at design-time can be supplied with values on the command line using the "PARAMNAME=Value" syntax.

Package variables are assigned directly through PL/SQL.

Scope:  Global names are global to the whole runform session.  Therefore, if you try to combine two forms that happen to use the same global name for different purposes, the forms will not integrate without changes.

Parameter values are local to a particular form.  There is no interaction, unless a parameter is explicitly passed from one form to another.  When integrating forms it is essential to ensure that they share the correct parameter names.

Package variables are qualified by the name of the package.  If two packages declare the same variable name, there is no interaction between them.  Integrating forms that rely on package variables for their shared global data is much more straightforward than using the other two methods, because there are no hidden subtle interactions between same-name objects.

Persistence: Globals preserve their value for the duration of the Runform session, unless explicitly erased.  They are visible to all forms which get called during the session.  Any modification made to a global variable in a called form is visible to any calling form and all subsequent forms in the session.

Parameters are visible only to the form in which they are declared, unless they are passed as part of a parameter list.  In this case they supply incoming values for the form-level parameters declared for the called form.

The value of the parameter in the calling form is thus visible to the called form in this way.  Any modification made in a called form to a parameter is not visible to the calling form.  The called form gets "fed" a snapshot of the parameter values as they existed at the moment of the Call_Form(), and works with private copies of the values.

Package variables preserve their value for the duration of the Runform session.  They are visible to all forms which get called during the session provided the CALL_FORM argument data_mode is set to SHARE_LIBRARY_DATA.  Any modification made in a called form to a package variable is visible to any calling form and all subsequent forms in the session.

Documentation:  Globals can be created anywhere in any trigger.  Unless a developer is disciplined and uses some sort of methodology, globals variables can be very hard to find and document.  Errors are easy to make and hard to find, since a typing error when assigning to a global simply creates a new global under the new, mistyped name.

Parameters exist as named object at the form level, can have meaningful default values, and can be documented with object comments like any other forms object.

Package variables are declared explicitly in a package and can be explicitly initialized.  They can be easily documented in the PL/SQL code.

Summary: To pass values into a form from the command line, use parameters.

If you specifically need to create variables dynamically, use globals, but first consider whether a table of records would be a more efficient mechanism for storing many dynamically created values.

For all other purposes use package variables.

Question

How do I pass a Record Group from Form Builder to Reports Developer or Graphics Builder?

Answer

A record group is passed to Reports Developer or Graphics Builder as a DATA parameter.  This DATA parameter is a special type of parameter that gives a signal to the integration code to substitute the contents of the record group whose name you give for the results of the query named by the query name you indicate.  Simple example:

(1) In Reports Developer you create a report with a query:

Query Name:  FOOBAR_QUERY

Query:  SELECT DEPTNO, DNAME FROM DEPT

(2) In Form Builder you create a record group in your favorite way such that it has two columns, one NUMBER and one CHAR.  Then you populate that record group (still on the forms side).  Say the record group is called PETE, and has two columns A and B:

DECLARE

   f RecordGroup;

   g GroupColumn;

BEGIN

   f := CREATE_GROUP('Pete');

   g := ADD_GROUP_COLUMN( f , 'A', NUMBER_COLUMN);

   g := ADD_GROUP_COLUMN( f , 'B', CHAR_COLUMN, 20);

/*

** Then populate the group in your favorite way

*/

END;

(3) When you set up the parameter list that will be passed from forms to the other tool, you create a parameter named 'FOOBAR_QUERY' and give it the value of 'PETE'.  Since it is a DATA parameter, this pairing of 'FOOBAR_QUERY' to 'PETE' tells the integration code what to do when it starts up the other tool. Instead of running the select statement that defines 'FOOBAR_QUERY' in Reports Developer, the values from the 'PETE' record group will be substituted as if they *were* the result.

Question

Can I access the contents of a record group within a user exit?

Answer

To access the contents of a record group within a user exit, the values first have to be placed within a database block.  At present, user exits do not have any knowledge of the data structure of a Form Builder record group.

With the advent of ORA_FFI it is likely that the need for user exits will now diminish, as you can make Microsoft  Windows SDK and SLL function calls directly from PL/SQL.  You will thus still have access to the Record Group values.


Program Units and Libraries

Question

If I want to create a procedure should I use a library, a database stored procedure, or a local Form procedure?

Answer

These different forms of procedures will produce different performance results depending on what you are trying to achieve.  The database procedure will be invoked on the server side and will perform all of the processing there.  This may help reduce network traffic, but may overload the server if many clients are doing this.

Local form and library procedures are quite similar in that they are both stored and run on the client with any SQL statements being passed to the server.

The local procedures are typically faster on execution because they are actually part of the .FMX file, but may use more memory and have a longer startup time when the .FMX file is initially invoked.

Library procedures may be better in terms of overall memory as procedures are only loaded into memory in 4K chunks when they are required.  Once loaded, they are read from memory.  They have the additional advantage that the library can be attached to a number of forms at once.

If the code within the library procedures is altered, the form does not require re-generation.

If a library contains package global variables, those variables can be shared across forms in a runform session.

Question

How does the use of libraries affect the size of the .FMX file?

Answer

If the library code were included in the .FRM, there would be no reason to redo them the way we have. The beauty of the new scheme is that the library modules remain separate and compiled (into .PLL or .PLX files) so that runform can bring program units into memory at runtime without adding to the size of each and every .FMX file.

Think of it like a DLL.  The only overhead that's added to the form that attaches a library is that negligible amount required to remember the name of the libraries on which it depends.

Question

How should I make a reference to a block in my library program units?

Answer

At compile time, Form Builder will attempt to resolve all references to objects.  Therefore, if you have code thus:

:BLOCK1.ITEM1 := 'Value';

or

IF

   :BLOCK1.ITEM1 = 'Y'

THEN

....

Form Builder will attempt to resolve the reference to :BLOCK1.ITEM1.  When you are writing library code, there is no way to resolve these references, since the library could potentially be attached to *any* form.

Instead you need to use the Copy() and Name_In() built-ins when referencing Form Builder objects within libraries.  These built-ins do not attempt to resolve references at compile time.  So the above code would become :

Copy ('Value','BLOCK1.ITEM1');

or

IF

   Name_In ('BLOCK1.ITEM1') = 'Y'

THEN

 ...


PL/SQL Integration

Question

How is SQL within PL/SQL dealt with by Form Builder?

Answer

Since PL/SQL blocks in a form can have Form Builder built-ins, we cannot send the whole block to the database.

Form Builder processes the cursors which PL/SQL tells it are required for DML operations within PL/SQL within Form Builder.

That means SQL within PL/SQL takes advantage of the techniques to reduced network traffic implemented in 5.0.  These changes dramatically reduce the level of traffic seen using prior versions.

To send entire blocks of PL/SQL to the database, you can:

(1) Use Forms_DDL() built-in to send a lengthy string which makes up a block of code you want  to be executed on the server:

Forms_DDL('BEGIN ... END;');

(2) Call Stored procedures/functions/packages which have the bundled DML inside them and call these stored program units from Form Builder.

Question

How are the constants like INSERT_ALLOWED and PROPERTY_ON dealt with by PL/SQL?

Answer

All of these tokens that you pass to built-ins are numeric constants.  If you write a generic procedure that sets the properties of objects you need to make sure that the parameters passed are typed as NUMBER to ensure that no data type conflicts occur.


Timers

Question

If a timer expires during a long running query when is it handled?

Answer

The timer will always wait to be handled until the current operation has been completed.  In other words, the query is completed before the timer is serviced.

Question

If a REPEAT timer expires between a long query, does it repeat prior to being serviced by a WHEN-TIMER-EXPIRED trigger at the end of the query, or does it wait for servicing before repeating?

Answer

A repeating timer will never be restarted until after it has been serviced by an appropriate firing of WHEN-TIMER-EXPIRED.  A simple corollary to that fact is that no timer can ever exist twice in the "timers to be serviced" stack.


Triggers

Question

What is the difference between the following triggers :

- Post-Fetch vs. Post_Query

- Post-Forms-Commit vs. Post-Database-Commit

- Pre-Query vs. Pre-Select

Answer

A comparison of these triggers follows :

Post-Fetch vs. Post-Query

POST-FETCH fires just after each attempt to fetch records from the database.  Depending on the value of "Array Size" for the block in question, and how many records are actually delivered from the database in response to our request, this trigger may fire fewer times.

In contrast, POST-QUERY fires once for *each* record that is brought from the waiting area (where records first go after they are fetched in a bunch from the database) and added to the end of the current block's list of records.

Post-Forms-Commit vs. Post-Database-Commit

POST-FORMS-COMMIT fires as the last trigger which is still part of the current transaction during commit-time processing.  It is the last chance for the application to perform any processing or to rollback the transaction before the actual 'COMMIT' is issued.

The POST-DATABASE-COMMIT triggers fires just after the 'COMMIT' statement is issued by forms to close the current transaction.  At this point it is too late to rollback the transaction.

Pre-Query vs. Pre-Select

PRE-QUERY fires just before Forms begins to prepare the SQL statement that will be required to query the appropriate records from the database in response to the query criteria that have been entered into the example record.

It is the designer’s last chance to "deposit" query criteria into the items in the block as if they had been entered into the example record by the operator.

PRE-SELECT fires after the PRE-QUERY trigger, and just before the actual, physical construction of the SELECT statement begins.  It would typically be used in conjunction with an ON-SELECT trigger in which the designer would be supplanting the normal construction of the SELECT statement with a user exit of his own to construct and prepare the SELECT statement for execution (perhaps against a foreign datasource).


Locking

Question

Is it possible to defer locking of a record until commit time?

Answer

Yes, there is a block property called 'Locking Mode', which can be either 'Immediate' or 'Delayed'.  If you set it to 'Delayed', then a record in a block is not locked until commit-time, specifically until changes are 'posted'.

At that time, the current forms value is compared to the database value before issuing the update statement.  The user will get an error if the record has been updated since it was fetched.

'Locking Mode' can be changed at runtime in a trigger with the Set_Block_Property built-in.


Images

Question

How can I get an image from a file to be stored in my database?

Answer

To store images in the database, you need to read them into an item in the form, from the file system in one of the supported standard file formats :

                                                    'PCX'

                                                    'BMP'

READ_IMAGE_FILE('file_name',	’TIFF', 'block.image_item');

                                                    'JFIF'

                                                    'PICT'

Then commit it to the database:

COMMIT_FORM;

Make sure that 'block.image_item' is a database item in a database block and that the 'image_item' column in the base table on which the block is based is declared as LONG RAW.


General UI Issues

Question

Sometimes when I issue a Call_Form (.., NO_HIDE) my first form is still hidden.  Why?

Answer

Any application can only have one ROOT_WINDOW active at any time.  You are calling the second form while the focus is in this ROOT_WINDOW.  In this event the ROOT_WINDOW of the second form will overlay that of the first form, giving the appearance that the first form has been hidden.

Should you not want this to occur, always make sure that you issue the Call_Form built-in from a non ROOT_WINDOW.

ROOT_WINDOW is mainly used in older forms that were originally created in Forms 4.0.  In new forms, do not create a window called ROOT_WINDOW.

Question

How can I determine which user interface I am using at runtime?

Answer

Issue the built-in Get_Application_Property (USER_INTERFACE).


Menus

Question

How can I specify my menu items so that they assume the appropriate position for the GUI?

Answer

You can do this by using a feature called Magic Menu items.  For example, by making your menu item a magic item for "Help", it will be displayed in the standard position for the "Help" menu for whatever GUI you are running under.

Question

What is the cause of the message :

FRM-10249: No authorization to run application <name>

Answer

Make sure that you have done the following:

•	Created a database role

•	Assigned the user to that role

•	Assigned the role to at least one of the top level menu items in the menu application.

Having followed these steps, if you still get the FRM-10249 error and you are not storing the menu in the database, make sure that the Use File option in the form module property sheet is checked.

It is also worth checking that the menu base tables have a datatype of VARCHAR2 and not CHAR, where appropriate.


Upgrading from a Previous Release

Question

How do I upgrade application FORMB which has referenced objects from a library form FORMA?

Answer

Perform the following steps :

1	Produce an INP file for FORMA if you don't have one already. You would use "IAC30 FORMA UN/PW" to do this.

2	Upgrade FORMA.INP to FORMA.FMB.

3	Open FORMA.FMB from Form Builder 5.0, and choose File [image] Save As to the database (may have to visit your preference screen to be given the chance to save to the database).

4	Upgrade FORMB.FMB.  During the upgrade, reference information is still read from the *Forms 3.0 tables*.

5	When you subsequently Open or Generate FORMB.FMB from Form Builder 6.0, Form Builder will expect to *now* find the reference information in the Form Builder 6.0 database tables.

Note that in 6.0 you can reference from the file system as well as the database.

Question

If I have a format mask of DD/MM/YY and type in a date without the slashes, why does this no longer show the correct date as it did Forms 3.0?

Answer

From Forms 4.5 onward we have adopted the same date formatting approach that has been taken in Oracle8.

The issue here is that:

12121994

When put through the format mask, actually gets treated by the date formatting routines as:

12 1 21 9 94

   ~    ~

When the '1' and '9' that are marked with tilde's above get interpreted as the separator characters.

So this input becomes:

12 / 21 / 94

In a field that is expecting a four digit year, and so the effect described previously takes hold, and maps 94 to 0094.

You can use the "FX" format mask element to force the user to enter an exact match to your mask.

This has been done intentionally to tighten up the date routine input processing.  There were many cases where the dates package would accept very questionable input and the decision was taken to break this rather idiosyncratic behavior of forms in favor of the better overall date processing.

Question

What does the FORMS60_DEFAULTFONT parameter control?

Answer

FORMS60_DEFAULTFONT controls:

The font that will be used for default block display text, if the font is *monospaced*.  If it is not monospaced, the closest monospaced font to the default setting will be used for this.

The font that will be used for creating upgraded display text from V3/V2.3 forms.

The font that will be used to display any item which has the default visual attribute.

The width and height (in pixels) of a uniformly sized character cell when running a form which uses the Character Cell coordinate system *and* which has the Default Font Scaling option on.

When a form designed in the Character Cell coordinate system uses the "Default Font Scaling" option, at runtime the size of the default font (however it has been set on the platform on which you're running) governs the size of the character grid cells – the larger the font, the larger the grid cells are.

The (x,y) coordinates for position and size of every object is expressed in integer cell units since the form is in Character Cell units, so a larger grid with an object that is five cells long will mean an object that is (in absolute terms) longer than when running with a smaller default font.

It does not affect the size of the font in the field unless the item is using a default visual attribute.

Question

If I upgrade from SQL*Forms 2.3 to Form Builder 6.0, what becomes of my V2 style triggers?

Answer

The upgrade process from 2.3 to 6.0 is done via the Forms 6.0 Generator.  To upgrade from 4.5 to 6.0, simply open the form in the 6.0 Form Builder.

V2 style triggers are not altered during this process.

In 6.0 you will NOT be able to modify your V2 style triggers.  However they will still execute.

Form Builder 6.0 is likely to be the last release that supports V2 style triggers, so you should begin converting or replacing such triggers in any form that you expect to upgrade further.


Microsoft Windows-Specific Issues

Question

Is the Host() command under Forms synchronous or asynchronous on Windows?

Answer

Host() is only synchronous if the utility called creates an initial window, otherwise it is asynchronous.

For example, the Windows application 'winzip.exe' doesn't create an initial window and therefore:

Host('winzip.exe');   -- Will be Asynchronous

Whereas:

Host('notepad.exe');  -- Will be Synchronous

If you want a command to be synchronous that is not currently so, you will have to create a window (non-visible if you don't want to use it) in the WinMain of your application code.

Question

What gets loaded into memory when you run a form under Windows?

Answer

Runform consists of one, small F60RUN32.EXE executable, and RUNFORM.DLL. The Form Builder executable would be treated like any program that uses dynamic link libraries on Windows.

The .FMX file's contents are loaded into your PC's memory.  The .MMX file's contents are loaded into your PC's memory.  The .PLL / .PLX file's table of is completely loaded into your PC's memory, and program units would be loaded on demand.

Question

Why can’t I change the color of a button under Windows?

Answer

Under the Windows Toolkit there is currently no way to individually change the color of a button.  Through Windows, you can  change the color of *all* buttons including those for non-Oracle products.  In addition, you could also use an iconic button where the icon has a different color.

Question

Can Forms 6.0 call DLL's on Microsoft Windows?

Answer

Using the ORA_FFI package, you can invoke any Windows SDK function or DLL function directly from PL/SQL without the need for user exits.  See the Advanced Techniques manual  for more information on ORA_FFI.


Motif-Specific Issues

Question

Can I improve performance with any Motif settings?

Answer

In the Tk2Motif file make sure that the following settings exist:

Tk2Motif*dragReceiverProtocolStyle:     DRAG_NONE

Tk2Motif*dragInitiatorProtocolStyle:    DRAG_NONE

Question

How can I disable the blinking cursor to reduce network traffic?

Answer

To decrease the exchange of network packets associated with drawing and undrawing the blinking I-beam cursor in text edits and and text items (fields), you can set the following blinkRate properties to 0 (milliseconds). The default setting for both is a blinkRate of 500 ms.

Tk2Motif*field.blinkRate: 0

Tk2Motif*tedit.blinkRate: 0

Question

How can I change the look and feel of push buttons under Motif?

Answer

Push buttons under Motif can be made to look very respectable using the following settings in the Tk2Motif file:

Tk2Motif*pushb.defaultButtonShadowThickness: 0

Tk2Motif*pushb.shadowThickness: 2

Tk2Motif*pushb.highlightThickness: 1

Question

How can I change the font in the trigger text window?

Answer

Use the following resource setting:

Tk2Motif*tedit.fontList : my-favourite-font


JOIN of Multiple Tables

Prior to Forms version 6i, Forms supported the query data sources of type "Table" based on a single table. Now, Forms supports table query data sources based on a JOIN of multiple tables.  A JOIN of multiple tables is not appropriate for a DML data target, so the data target must still be based on a single table.

Follow the steps described in the Task Overview to create a block with a query data source based on a join of multiple tables and a DML data target based on a single table. See the Example to create an EMP block with a query data source based on a join of the EMP and DEPT tables and a DML data target based on the EMP table.

Task Overview

1.	Using the Data Block Wizard, create a block based on one of the tables in the join.

Often in a join, one of the tables is the "driving table" which is joined to several other foreign key lookup tables.  The Data Block Wizard helps create data items from table columns, so it is recommended that you choose the table that contains the most columns to be included in your block, which is usually the driving table. After using the Data Block Wizard, the block is created.

2.	Select the block, and set the Query Data Source Name property to the list of tables in the join.

The list of tables should be separated with commas, as they would appear in the FROM clause of the join SELECT statement.

3.	Set the WHERE clause to contain the join condition between the tables in the join.

4.	Set the DML Data Target Name property to the appropriate table for inserts, updates, and deletes. This is usually the driving table.

5.	Manually create new items for columns in the other tables in the join that you want to include in the block.

6.	Select each of the items created in step 5, and set the Database Item property to Yes.

7.	Select each of the items created in step 5, and set the Column Name property to the column name in the table.

8.	Select each of the items created in step 5, and set the Query Only property to Yes.

This prevents the item from being included in inserts and updates to the DML Data Target table.

9.	For all items where the column name is in more than one table in the join, qualify the column name with the table name in the Column Name property (for example table.column).

10.	For all items that are the primary key of the DML Data Target table, set the Primary Key property to Yes.

Example Using EMP and DEPT

This example uses the EMP and DEPT sample tables.  It creates an EMP block which displays the employee information and the name of department instead of the department number.  The EMP table is the driving table which is joined to the DEPT table to lookup the department name.

1.	Create a block based on the EMP table using the Data Block Wizard.

2.	Using the Property Palette, select the EMP block and change the "Query Data Source Name" from "EMP" to "EMP, DEPT".

3.	Set the "WHERE clause" to "EMP.DEPTNO = DEPT.DEPTNO".

4.	Set the "DML Data Target Name" to "EMP".

5.	Manually create new items that correspond to columns in the DEPT table.  For example, create "DNAME".

6.	Select the DNAME item and set "Database Item" to "Yes".

7.	Set the "Column Name" to "DEPT.DNAME".

8.	Set "Query Only" to "Yes". This will prevent the DNAME item from being included in updates to the EMP table.

9.	Qualify the column name of any items that are columns in both the EMP and DEPT tables.  For example, change the "Column Name" of the "DEPTNO" item from "DEPTNO" to "EMP.DEPTNO".  This will prevent an ambiguous column name error during query.

10.	Specify one of the items as the primary key.  For example, set "Primary Key" to "Yes" on the "Empno" item. This is required because the query data source and DML targets are different.


About record groups

  Related Topics

A record group is an internal Form Builder data structure that has a column/row framework similar to a database table.  However, unlike database tables, record groups are separate objects that belong to the form module in which they are defined.  A record group can have an unlimited number of columns of type CHAR, NUMBER, or DATE provided that the total number of columns does not exceed 64K.  Record group column names cannot exceed 30 characters.

A record group built from a query can store records from database tables much like a database view, with the added advantage that the record group is local to Form Builder, rather than existing in the database.  Also, the SELECT statement used to create and populate a query record group can be constructed dynamically at runtime.

Programmatically, record groups can be used whenever the functionality offered by a two-dimensional array of multiple data types is desirable.


About record group types

There are three types of record groups: query record groups, non-query record groups, and static record groups.

Query record group	A query record group is a record group that has an associated SELECT statement.  The columns in a query record group derive their default names, data types, and lengths from the database columns referenced in the SELECT statement.  The records in a query record group are the rows retrieved by the query associated with that record group. Query record groups can be created and modified at design time or at runtime.
Non-query record group	A non-query record group is a group that does not have an associated query, but whose structure and values can be modified programmatically at runtime. Non-query record groups can be created and modified only at runtime.
Static record group	A static record group is not associated with a query; instead, you define its structure and row values at design time, and they remain fixed at runtime. Static record groups can be created and modified only at design time.
You do not specify the record group type explicitly. The type is implied by when the record group is created (at design time or at runtime) and by how the group is defined.


About record group values

  Related Topics

The actual values in a record group come from one of three possible sources:

•	the execution of a SELECT statement that you associated with the record group at design time (query record groups)

•	the execution of built-in subprograms that populate the record group dynamically (query groups and non-query groups)

•	an array of static values that you associated with the record group at design time (static record groups)


About record groups and lists of values (LOVs)

  Related Topics

Every list of values (LOV) is associated with a specific record group.  The LOV is the interface object that allows operators to view, scroll, and select the records stored in the underlying record group.  When you define an LOV at design time, you must specify the record group on which the LOV will be based.

When you create an LOV, you can also create the underlying record group directly from the Create LOV dialog.


About record group built-in subprograms

  Related Topics

The following built-in subprograms are available for working with record groups programmatically.

The type of record group (static, query, or non-query) and when the group was created (at design time or at runtime) determine which built-in subprograms are valid for a particular group. For example, you cannot use the ADD_GROUP_COLUMN function to add a column to a record group that was created at design time.  Similarly, you cannot use the ADD_GROUP_ROW procedure to add a row to a static record group.

Creating and deleting groups:

•	CREATE_GROUP (function)

•	CREATE_GROUP_FROM_QUERY (function)

•	DELETE_GROUP (procedure)

Modifying a group's structure:

•	ADD_GROUP_COLUMN (function)

•	ADD_GROUP_ROW (procedure)

•	DELETE_GROUP_ROW (procedure)

Populating groups:

•	POPULATE_GROUP (function)

•	POPULATE_GROUP_WITH_QUERY (function)

•	SET_GROUP_CHAR_CELL (procedure)

•	SET_GROUP_DATE_CELL (procedure)

•	SET_GROUP_NUMBER_CELL (procedure)

Getting cell values:

•	GET_GROUP_CHAR_CELL (function)

•	GET_GROUP_DATE_CELL (function)

•	GET_GROUP_NUMBER_CELL (function)

Processing rows:

•	GET_GROUP_ROW_COUNT (function)

•	GET_GROUP_SELECTION_COUNT (function)

•	GET_GROUP_SELECTION (function)

•	RESET_GROUP_SELECTION (procedure)

•	SET_GROUP_SELECTION (procedure)

•	UNSET_GROUP_SELECTION (procedure)

Object ID functions:

•	FIND_GROUP (function)

•	FIND_COLUMN (function)


Creating a query record group at design time

  Related Topics

To create a query record group at design time:

1	In the Object Navigator, click the Record Groups node.

2	Click the Create button [image] in the toolbar.

3	In the New Record Group dialog, click Based on the Query Below and then enter a SELECT statement in the Query Text field.  The WHERE clause for the SELECT statement can include references to global variables and form parameters.

4	Click OK.

Form Builder validates the SELECT statement and dismisses the dialog.

Note:  The new record group does not yet have any rows.  The rows are returned at runtime by the query associated with the group:

•	You can execute the query associated with a query record group programmatically by calling the POPULATE_GROUP built-in subprogram.

•	When an LOV is based on a query record group, Form Builder executes the query associated with that record group whenever the LOV is displayed or whenever Form Builder needs to validate a text item that has the Use Validate from List property set to Yes.


Viewing the structure of your record group
Viewing the structure of a record group

To view the structure of a record group created at design time:

1	In the Object Navigator, double-click the icon beside the desired record group to display the Property Palette.

2	Under the Functional node, double-click the Column Specifications field.

The Query Record Group Column Specification dialog appears and displays the names of the selected columns in the Column Name text list.

The Data Type and Length fields display the attributes of the column currently selected in the Column Name list.

Tip:  To view the attributes of a different column, select that column in the list.  Length values are displayed only for CHAR columns. For NUMBER and DATE columns, Form Builder uses the default ORACLE lengths for these datatypes and disables the Length field property.

Note: Record groups created at runtime cannot be viewed in Form Builder.


Modifying the SELECT statement for your query record group
Modifying the SELECT statement for a query record group

  Related Topics

To modify the query record group SELECT statement:

1	In the Object Navigator, double-click the icon beside the desired record group to display the Property Palette.

2	Under the Functional node, modify the Record Group Query SELECT statement text as desired.

Tip:  If you modify the SELECT statement for a record group on which an existing LOV is based, you may need to update the LOV definition to make the LOV column definitions match the new record group columns.

Note: These instructions apply only to query record groups created at design time. At runtime, you can programmatically  alter the SELECT statement of a query record group that was created at runtime.


About manipulating a record group at runtime

  Related Topics

Once you create a query or non-query record group at runtime, you can perform the following operations on the group:

•	modify its structure by adding columns and rows

•	populate the group

•	modify the query associated with a query group

•	add and delete rows

•	set and get column values

•	mark and unmark rows as "selected"

Note: Static record groups can be created and modified only at design time.

Record group rows are numbered internally (1,2,3, and so on) and operations on individual rows and columns must reference those rows by row number.


Creating a query record group at runtime

  Examples	  Related Topics

You can use the CREATE_GROUP_FROM_QUERY function to create query record groups programmatically at runtime. To call this function, you pass in the SELECT statement that you want to associate with the record group.  The columns in the resulting group correspond to the database columns referenced in the SELECT statement.

The return value of CREATE_GROUP_FROM_QUERY is the object ID of the new group.  Assign this return value to a variable that you declared as type Record Group.

A call to CREATE_GROUP_FROM_QUERY creates a group that does not yet have any rows.  To populate the group you must explicitly execute its associated query by calling the function POPULATE_GROUP.  The return value of the POPULATE_GROUP function is 0 if the query succeeds or an ORACLE error number if it fails.


Replacing a record group's query

  Examples	  Related Topics

You can replace a group's current query with a new query by calling the POPULATE_GROUP_WITH_QUERY function.

The columns referenced in the new query must have the same structure as the columns referenced in the group's current query.  That is, you cannot alter the column structure of a record group by calling POPULATE_GROUP_WITH_QUERY.

For example, you might replace a group's query when you want to modify the default WHERE and ORDER BY clauses.

The POPULATE_GROUP_WITH_QUERY function returns 0 if the query succeeds or an ORACLE error number if it fails.

The new query remains associated with the record group, and you can execute it by making subsequent calls to the POPULATE_GROUP function.


Populating a query record group at runtime

  Related Topics

When you create and manipulate query groups programmatically, it is your responsibility to ensure that the values in the group are current with those in the database.  Remember that the rows in a query group are only as current as the last call to POPULATE_GROUP or POPULATE_GROUP_WITH_QUERY.


Creating a query record group at runtime examples

/* The following example creates a four-column record
** group based on two database tables, product and
** inventory.
*/

DECLARE
   group_id	RecordGroup;
   query_ok	NUMBER;
BEGIN
/* create the group prod_group and assign its id to the
** variable group_id  */
   group_id := Create_Group_From_Query ('prod_group',
     'SELECT product.id, product.name,
     inventory.warehouse_id, inventory.amount_in_stock
     FROM product, inventory
     WHERE product.id = warehouse.product_id');
/* now execute the new group's query, using the variable
** group_id to identify the group */
   query_ok := Populate_Group(group_id);

/* if the query failed, abort this trigger by raising a
** predefined exception */
   IF query_ok <> 0 THEN
     RAISE Form_Trigger_Failure;
   END IF;
END;


Replacing a record group's query examples

/* The following example demonstrates replacing a
** record group's query at runtime: */

IF (Populate_Group_With_Query
   ('prod_group',
   'SELECT product.id, product.name, inventory.warehouse_id,
     inventory.amount_in_stock
     FROM product, inventory
     WHERE product.id = warehouse.product_id
     AND inventory.amount_in_stock > 10'))
     <> 0 THEN
     RAISE form_trigger_failure;
END IF;


Creating and populating a non-query record group
Creating and populating non-query record group

  Examples	  Related Topics

Non-query record groups can only be created at runtime.

Use the CREATE_GROUP function to create a non-query record group.  Because the CREATE_GROUP function creates a group without columns or rows, it is usually followed by calls to the functions ADD_GROUP_COLUMN and ADD_GROUP_ROW.

CREATE_GROUP is a function that returns the internal ID of the new group.  ADD_GROUP_COLUMN returns the ID of the new column.  When you assign these IDs to variables of type Record Group and Group Column, you can reference them in subsequent operations.

You can also use POPULATE_GROUP_WITH_QUERY to populate a non-query group.  Doing so associates the indicated query with the group and so converts the non-query group into a query group.  The database columns referenced in the new query must correspond to the columns in the record group.

For example, you could build a non-query record group that has the appropriate columns, and then call POPULATE_GROUP_WITH_QUERY to associate a query with the group.


Creating and populating a non-query record group examples

/* The following example creates a record group called my_group.
** The resulting group is a three-column non-query record group
** that does not yet contain any rows.
*/

DECLARE
   group_id	RecordGroup;
   col1_id	GroupColumn;
   col2_id	GroupColumn;
   col3_id	GroupColumn;

BEGIN
/* Create a non-query group called my_group and assign its id
** to the variable group_id.
*/
   group_id := Create_Group('my_group');

/* Add three columns to the new group, using the variable
** group_id to identify the group.  The first two columns
** are of type CHAR_COLUMN and their length must be
** specified.
** The third is of type NUMBER_COLUMN and does not take a
** length parameter
*/
   col1_id := Add_Group_Column(group_id,'col1',CHAR_COLUMN,50);
   col2_id := Add_Group_Column(group_id,'col2',CHAR_COLUMN,50);
   col3_id := Add_Group_Column(group_id,'col3',NUMBER_COLUMN);

END;


Modifying an existing record group

  Related Topics

You can modify the structure of an existing record group in the following ways:

•	add rows to the group

•	delete rows from the group

•	add columns to the group

•	delete the group


Adding rows to a record group

  Examples	  Related Topics

Use the ADD_GROUP_ROW procedure to add rows to a group.  When you call ADD_GROUP_ROW, you indicate where you want Form Builder to insert the new row by either passing in a row number or specifying that the row be placed at the end of all existing rows.

To insert a new row at a specific position, pass the desired row number:

Add_Group_Row('my_group',3);

To add a row at the end of all existing rows, use the END_OF_GROUP constant to specify row placement:

Add_Group_Row('my_group',END_OF_GROUP);

The column values in the newly added row default to NULL.  To set the values of individual columns, use the procedure appropriate to the datatype of the cell:

•	SET_GROUP_CHAR_CELL

•	SET_GROUP_DATE_CELL

•	SET_GROUP_NUMBER_CELL

Note:  You cannot programmatically add rows to a static record group.


Adding rows to a record group examples

/* The following example adds a row at the end of the
** group my_group and then sets the values of each cell
** in the new row:
*/

DECLARE
   group_id	RecordGroup := Find_Group('my_group');
   total_rows	NUMBER;
   new_row	NUMBER;
BEGIN
/* find out how many rows there are in the group now */
   total_rows := Get_Group_Row_Count(group_id);

/* add a row at the end of the group my_group */
   Add_Group_Row(group_id, END_OF_GROUP);

/* increment total_rows to get the row number of the new row */
   new_row := total_rows + 1;

/* set the value of columns 1,2, and 3 in the new row */
   Set_Group_Char_Cell('my_group.col1, new_row, 'xyz company');
   Set_Group_Char_Cell('my_group.col2', new_row, 'district 12');
   Set_Group_Number_Cell('my_group.col3', new_row, 400);
END;


Deleting rows from a record group

  Related Topics

Use the DELETE_GROUP_ROW procedure to delete rows from existing groups.  The following example deletes the third row in the group named prod_group:

Delete_Group_Row('prod_group',3);

To delete all rows, pass in the constant ALL_ROWS:

Delete_Group_Row('prod_group',ALL_ROWS);

Note:  You cannot delete rows from a static record group.


Adding columns to a record group

  Examples	  Related Topics

Use the ADD_GROUP_COLUMN procedure to add a new column to an existing record group.  The record group to which you add the column must meet the following criteria:

•	The group must be a query or non-query group that was created programmatically (you cannot add columns to groups that were created at design time).

•	The group cannot currently have any rows.

Note that when you add a column to a query record group you must also replace the group's current query with a new query that selects values into the new column.


Adding columns to a record group examples

/* The following example adds a column to a query record
** group that was created by a call to CREATE_GROUP_FROM_QUERY
** and currently has rows returned by that query.
*/

DECLARE
  query_ok	NUMBER;

BEGIN
/* This is a query group that has rows from a previous call
** to Populate_Group, so first delete all its rows
*/
   Delete_Group_Row('prod_group',ALL_ROWS);

/* Now add a column of type DATE_COLUMN to the group */

   Add_Group_Column('prod_group', 'restock_date', DATE_COLUMN);

/* The structure of group's old query is no longer valid, so
** replace that query with a new query and populate the group
*/

   query_ok := Populate_Group_With_Query('prod_group',
   'SELECT product.id, product.name, inventory.warehouse_id,
   inventory.amount_in_stock, inventory.restock_date FROM product,
   inventory WHERE product.id = warehouse.product_id');

/* if the query failed, abort this trigger by raising a
** predefined exception */

   IF query_ok <> 0 THEN
     RAISE Form_Trigger_Failure;
  END IF;
END;


Deleting a record group

  Related Topics

Use the DELETE_GROUP procedure to delete a record group that was created programmatically:

Delete_Group('prod_group');

Note:  You cannot delete a group that was created at design time.


Performing operations on rows

  Related Topics

Once you have created and populated a record group, you can perform the following operations on its rows:

•	count the number of rows in the group

•	set the values of individual cells

•	get the current value of individual cells

•	mark rows as "selected" and then count and retrieve the selected rows

When you perform row operations you must identify rows by row number.  For example, to get the value of a cell, you must reference the cell by row number and column name.


Counting the number of rows in a record group

  Examples	  Related Topics

You can determine the number of rows in a record with the function GET_GROUP_ROW_COUNT.  This function is useful for determining how many iterations are required to loop through all the rows in a given group.


Counting the number of rows in a record group examples

/* The following example first executes the query
** associated with the query group named my_group,
** then assigns the number of rows returned by the
** query to the variable row_count.
*/

DECLARE
   group_id	RecordGroup;
   query_ok	NUMBER;
   row_count	NUMBER;
BEGIN
   query_ok := Populate_Group('my_group');
   row_count := Get_Group_Row_Count(group_id);
END;

/* The following example demonstrates the use of
** GET_GROUP_ROW_COUNT to determine how many iterations
** are required to loop through all of the rows in a
** given group.
*/

DECLARE
   group_id	RecordGroup := FIND_GROUP('my_group');
   row_count	NUMBER;

BEGIN

/* find out how many rows are in the group */

   row_count := Get_Group_Row_Count(group_id);

/* set the group's Status column to 'discontinued' for any
** rows with product id of 471
*/

   FOR j IN 1..row_count LOOP
   IF Get_Group_Number_Cell('my_group.prod_id', j) = 471
      THEN Set_Group_Char_Cell (my_group.status, j, 'discontinued');
   END LOOP;
END;


Getting and setting cell values

  Examples	  Related Topics

You can get and set the value of a cell at the intersection of a specific row and column.

To get the current value of a column in a specific row, use the function appropriate to the datatype of the cell:

•	GET_GROUP_CHAR_CELL

•	GET_GROUP_DATE_CELL

•	GET_GROUP_NUMBER_CELL

When you reference columns in a record group, use the complete group_name.column_name syntax.  Alternatively, you can reference columns by their internal object IDs.  To get the ID of a specific column, use the FIND_COLUMN function.

To set the value of a column in a specific row, use the procedure appropriate to the data type of the cell:

•	SET_GROUP_CHAR_CELL

•	SET_GROUP_DATE_CELL

•	SET_GROUP_NUMBER_CELL

Note:  You cannot set the values of cells in a static record group.


Getting and setting cell values examples

/* The following example gets the current value of the
** amount_in_stock column in the third row of the group
** my_group.
*/

DECLARE
   quantity	NUMBER;
   col_id	GroupColumn :=
     Find_Column('my_group.amount_in_stock');
BEGIN
   quantity := Get_Group_Number_Cell(col_id,3);
END;

/* The next example sets the value of the name column to
** Lisa Jean in the first row of the group named my_group.
*/

Set_Group_Char_Cell('my_group.name',1,'lisa jean');


Marking rows as selected

  Examples	  Related Topics

You can programmatically mark rows as "selected" when you perform row operations.  Selecting a row sets an internal flag on the row that you can refer to in subsequent row operations.

•	To mark a row as selected, use the procedure SET_GROUP_SELECTION.

•	To determine how many rows in a group have been selected, use the function GET_GROUP_SELECTION_COUNT.

•	To unmark a selected row, use UNSET_GROUP_SELECTION.

•	To deselect all currently selected rows in a group, use the procedure RESET_GROUP_SELECTION.

•	To get the row number of a row that has been marked as selected, use the function GET_GROUP_SELECTION. GET_GROUP_SELECTION returns the row number of the selected row specified.  For example, when rows 6, 11, and 18 are selected, they represent selections 1, 2, and 3, respectively. Thus, when three rows in a group are selected, the following function call returns the row number of the second selected row:

row_num := Get_Group_Selection(my_group,2);


Marking rows as selected examples

/* The following trigger loops through all of the rows in
** the group orders.  If the date stored in a row's
** date_ordered column is prior to 1980, the row is marked
** as selected.
*/

DECLARE
   group_id	RecordGroup := FIND_GROUP('orders');
   row_count	NUMBER;
   old_orders	NUMBER;

BEGIN

/* determine how many orders there are */

   row_count := Get_Group_Row_Count(group_id);

/* if an order is older than 1980, mark it for selection */

   FOR j IN 1..row_count LOOP
     IF Get_Group_Date_Cell('orders.date_ordered', j) <
       '01-JAN-80' THEN
       Set_Group_Selection(group_id, j);
     END IF;
   END LOOP;

/* count the total number of old orders */

   old_orders := Get_Group_Selection_Count(group_id);

END;

/* The following example is a procedure called kill_rows.
** The procedure takes a CHAR parameter that allows the name
** of a record group to be passed in at runtime. The procedure
** deletes all of the rows in the group that are currently
** selected.
*/

PROCEDURE kill_rows(group_name IN CHAR) IS
   group_id	RecordGroup := Find_Group('group_name');
   counter	NUMBER := 1;
   marked_rows	NUMBER;

BEGIN

/* determine how many rows are marked as selected */

   marked_rows := Get_Group_Selection_Count(group_id);

/* delete each row marked as selected */

   WHILE counter <= marked_rows LOOP
     Delete_Group_Row(group_id,
     Get_Group_Selection(group_id,counter));
     counter := counter + 1;
   END LOOP;

END;


What is a master-detail relation?

  Related Topics

A master-detail relation is an association between two data blocks—a master block and a detail block.  The relation reflects one of the following:

•	a primary-key to foreign-key relationship between the tables on which the blocks are based

•	a REF pointer relationship between the tables on which the blocks are based.

Consider an inventory-control application for a worldwide sporting goods distributor.  There is a REGION table for geographic regions, and WAREHOUSE tables for goods warehouses in the various regions.

The application includes data blocks based on each of these tables.  Since each warehouse is in a specific region, there is a primary-key to foreign-key relationship between the REGION and WAREHOUSE tables.  This relationship also defines a master-detail relation between the blocks:  the REGION block is the master block, while the WAREHOUSE block is the detail block.

The master-detail relation automatically does the following:

•	ensures that the detail block displays only those records that are associated with the current (master) record in the master block

•	coordinates querying between the two blocks

For example, when the end user changes the current record in the master block by navigating to a different region record, Form Builder updates the detail block to display only the records for warehouses that are within the selected region.  Similarly, when the end user queries a particular region in the master block, you can have Form Builder automatically retrieve the records for all of the warehouses in that region.


About the join condition
About the master-detail link

  Related Topics

Master and detail blocks are linked to each other in one of two ways: either through a relational join condition, or though a REF column in one block that points to data in the other block.

Join condition

The master block is related to the detail block through the join condition.  The join condition establishes the primary-key item(s) in the master block and the foreign-key item(s) in the detail block.  The join condition for the example application would be stated as follows:

warehouse.region_id = region.id

That is,

detail_block.foreign_key_item = master_block.primary_key_item

Note:  For Forms processing, it is recommended that you avoid basing a join condition on columns in the database that are of type CHAR.  (VARCHAR2 columns, however, are acceptable.)

REF pointer

A REF column in a table/block contains pointers to rows of data in another table/block.  This reference forms a natural master-detail relationship.  The detail block has a REF item that points to the master block.  Note that a REF link is not dependent on any primary or foreign key values in either table.


About block coordination

  Related Topics

To maintain the master-detail relation at runtime, Form Builder coordinates the master and detail blocks to ensure that the records displayed in the detail block are associated with the current record in the master block.

Any event that changes the current record in the master is a coordination-causing event.  Deleting a record or pressing [Up] or [Down] to move to a different record are both examples of coordination-causing events.  When such an event occurs, Form Builder automatically does the processing necessary to coordinate the master and detail blocks.

There are two phases of block coordination:  the clear phase and the population phase.  During the clear phase, Form Builder navigates internally to the detail block and flushes the obsolete detail records.  During the population phase, Form Builder issues a SELECT statement to repopulate the detail block with the detail records associated with the new master record.  These operations are accomplished through the execution of triggers.

To continue the example, consider what happens when the end user is on the first record in the REGION block and presses [Next Record]. Since Next Record is a coordination-causing event, Form Builder first navigates internally to the WAREHOUSE block and flushes the existing warehouse records (the clear phase).  Form Builder then makes the next region the current master record in the REGION block, and fetches the records of those warehouses that are within the selected region (the population phase).


About the Copy Value from Item property

  Related Topics

The mechanism that Form Builder used to coordinate the population of the detail block with the current record in the master block is the Copy Value from Item property on the foreign-key item in the detail block.  The Copy Value from Item property specifies the primary-key item in the master block whose value gets copied to the foreign-key item in the detail block whenever a detail record is created or queried.

Since the value of the primary-key item in the master record gets copied to the foreign-key item in the detail block, it is automatically incorporated in the WHERE clause of the SELECT statement that Form Builder issues to populate the detail block.

In the following example, the value of the foreign-key item WAREHOUSE.REGION_ID is copied from the current value of the primary-key item REGION.ID.  Thus, only warehouses that are in the currently selected master region get queried during block coordination.

  SELECT id, address, phone, manager_id
  FROM warehouse
  WHERE warehouse.region_id = foreign key value

When blocks are related through a compound join, the Copy Value from Item property is set on two or more foreign-key items in the detail block.


About the Relation object

  Related Topics

You can define a master-detail relation at any time during the form development process.  You define a master-detail relation between blocks by creating and setting the properties of a relation object.

A relation is a logical object that specifies the relationship between one master block and one corresponding detail block. In the Object Navigator, the relation object appears under the block that is the master block in the relation.

When you create a relation, Form Builder generates the triggers and PL/SQL procedures required to enforce coordination between the master and detail blocks.  The actual code that Form Builder generates depends on how the properties of the relation are set.


About creating a master-detail relation

  Related Topics

There are two ways to create a master-detail relation in Form Builder:

•	Create the relation on the Master-Detail Relation page of the Data Block Wizard (when you create the detail block for that relation).

•	In the Object Navigator, insert a relation object under the Relations node for the appropriate master block.  Both the master block and the detail block must already exist.

Limitations

In general, you should not create a master detail relation where the master block is based on a table and the detail block is based on a stored procedure.  Querying and coordination do not always work in such a relation.  However, there are no such limitations in the opposite case where the master block is based on a stored procedure and the detail block is based on a table.

Changing Relation Properties

Once you create a relation between two blocks, you can change its properties at any time.  When you change the Delete Record Behavior or Coordination properties of an existing relation, Form Builder adds, removes, or edits triggers as required.


Creating a master-detail relation with the Data Block Wizard

  Related Topics

When you create a new block with the Data Block wizard, you can use the wizard's Master-Detail page to create a master-detail relation.  See Data Block Wizard:  Master-Detail page


Creating a master-detail relation in the Object Navigator

  Related Topics

To create a master-detail relation in the Object Navigator:

1	In the Object Navigator, locate the block that you want to be the master block in the relation, and (if necessary) click the + to display the Triggers, Items, and Relations nodes related to the master block.

2	Select the Relations node under the master block, and choose Navigator [image] Create.

Form Builder displays the New Relation dialog, with the name of the master block you selected displayed in the Master Block field.

3	In the Detail field, enter the name of the detail block, or click Select... and select a block from the LOV.

4	Enter setting for the Master Deletes and Coordination behavior, Join Condition, then click OK.


Specifying the join condition for a master-detail relation

  Related Topics

You can specify a join condition with the following entries:

•	an item name that exists in both the master block and the detail block (do not preface the item names with colons)

•	an equating condition of two item names, where one item exists in the master block and the other exists in the detail block

•	a combination of item names and equating conditions

The following are valid join conditions:

•	an item name that occurs in both blocks:

ordid

•	an equating condition:

warehouse.region_id = region.id

•	compound joins can be entered in the following format:

block1.item1 = block2.item1 AND block1.item2 = block2.item2

Note:  The primary-foreign key relationship between the database tables can be a purely logical one.   Explicit primary-key or foreign-key column constraints in the relevant tables and columns are not required.


Setting relation properties that affect coordination

  Related Topics

When you create a master-detail relation, you must decide how Form Builder should manage coordination between the master and detail blocks.

Specifically, you need to answer the following questions:

•	Should end users be able to delete a master record if there are associated detail records present?

•	If end users can delete a master record, should Form Builder delete the associated detail records also?

•	If an end user makes a new record in the master block the current record, should Form Builder fetch the associated detail records immediately, or wait until the end user navigates to the detail block?

The answers to these questions will depend on application-specific requirements.  By setting the properties of the relation object, you can implement the master-detail functionality most appropriate for your application.

The properties that affect the functionality of a relation include Delete Record Behavior, Coordination, and Prevent Masterless Operation.

Delete Record Behavior Property  The Delete Record Behavior property (formerly called the Master Deletes property) allows you to specify how the deletion of a record in the master block should affect records in the detail block.  You can specify Cascading, Isolated, or Non-Isolated:

Cascading 	The master record can be deleted, and any associated detail records are automatically deleted from the database at commit time.  If relations are nested to several levels, only records in the immediate detail block are deleted.  That is, deletions do not automatically cascade to multiple levels of a relation chain.

Isolated	The master record can be deleted, but the associated detail records are not deleted from the database.

Non-Isolated 	The default setting.  The master record cannot be deleted if associated detail records exist in the database.

Note:  If your database is using the ORACLE7 Server cascading deletes feature, do not use the Cascading deletes option in Form Builder.

Coordination Properties  The values of the coordination properties Deferred and Automatic Query determine when the population phase of block coordination will occur:

Immediate	(Deferred = No)  The default setting.  When a coordination-causing event occurs, Form Builder fetches the detail records immediately.

Deferred	(Deferred = Yes, Automatic Query = No)  When a coordination-causing event occurs, Form Builder does not automatically fetch the detail records.  To fetch the detail records, the end user must navigate to the detail block and explicitly execute a query.

Deferred withAutomatic Query	(Deferred = Yes, Automatic Query = Yes)  When a coordination-causing event occurs, Form Builder defers fetching the associated detail records until the end user navigates to the detail block.


Choosing the appropriate coordination

  Related Topics

Think of deferred coordination as "deferred population."  That is, when a coordination-causing event occurs in the master block, the population phase of coordination is postponed, but Form Builder clears existing records in the detail block immediately.  This functionality prevents a detail block from displaying records that are inconsistent with the current record in the master block.

As a general rule, choose immediate coordination (Deferred = No) when the detail block is visible to the end user, and when it is assumed that the end user will always want to see the detail records associated with the current master record.

Deferred coordination with Automatic Query is preferable when the detail block is not immediately visible (to view detail records, end users must navigate to the detail block in a different window).

Deferred coordination also is useful when end users may not need to view the detail records at all.  In this case, deferring coordination can prevent an unnecessary database query.

Deferred coordination without Automatic Query is useful when you want end users to be able to switch to Enter-Query mode and specify additional query criteria in the detail block before population occurs.  This also allows end users to navigate through detail records without forcing coordination, and its attendant processing, to occur until it is actually required.


Setting the properties of foreign-key items in the detail block

When you create a relation, Form Builder sets the Copy Value from Item property on the foreign-key items in the detail block automatically.  The Copy Value from Item property specifies the name of the corresponding primary-key item in the format MASTER_BLOCK.ITEM_NAME.  At runtime, the value stored in the primary-key item in the master block is copied to the foreign-key item in the detail block whenever a detail record is created or queried.

When you create the relation in the Data Block Wizard, Form Builder does the following to the foreign-key item(s) in the detail block:

•	sets the Canvas property to NULL (makes item a NULL-canvas item)

•	sets the Visible, Enabled, Keyboard Navigable, Query Allowed, and Update Allowed properties to No

•	sequences items in the Object Navigator so the foreign-key items are last in the block's navigation sequence

Also, if the relation was created in the Data Block Wizard, Form Builder does not create a boilerplate text label for the foreign-key items.

When you create a relation in the Object Navigator, rather than in the Data Block Wizard, you might want to set these same properties yourself.

The purpose of these settings is to hide the foreign-key item(s) from the end user, since the same information is likely to be displayed in the primary-key item(s) in the detail block.  These settings are most appropriate when end users can view both the master and detail blocks at the same time.  If end users cannot see the master block when viewing detail records, you may want to undo these settings so that foreign-key item(s) are visible to the end user.  If you do, be sure the Update Allowed item property is set to No (so end users cannot edit the foreign-key value, thereby disrupting master-detail coordination).


Deleting a master-detail relation

  Related Topics

To delete a master-detail relation, select it in the Object Navigator and choose Navigator [image] Delete.  The following table shows what happens when you delete a master-detail relation or an object that is part of a relation:

If you delete...	Form Builder does this...
A master-detail relation	Deletes all master-detail triggers attached to the relation's master block, and clears the Copy Value from Item property of the foreign-key item(s) in the detail block.
The master or detail block in a relation	Deletes the relation and all associated master-detail triggers, but does not delete the master-detail procedures.
A detail block in a master-with-independent- details relation	Deletes the relation, removes the relevant detail section from the On-Clear-Details trigger and, if present, deletes the On-Populate-Details trigger.  Any comments or code that you added in this section also are removed.
The foreign-key item in a detail block, a master-detail trigger, or a master-detail procedure (not recommended)	Nothing.  However, a serious side effect is that master-detail block coordination will be disrupted.  Though you can hide the foreign-key item in the detail block (by making it a NULL-canvas item), you should not delete it entirely.  master-detail triggers and procedures are similarly crucial to ensure master-detail block coordination.


Preventing masterless operations in the detail block

 Examples	     Related Topics

With few exceptions, end users should be prevented from performing masterless operations in a detail block.  That is, end users should not be able to query or insert records in the detail block when there is no current record in the master block.

Setting the Prevent Masterless Operation relation property to Yes to prevent end users from performing masterless operations in the detail block of the relation has the following effects:

•	If end users attempt to insert records into the detail block when there is no master record in the master block, Form Builder will display an error message:FRM-41105: Cannot create records without a parent record.

•	If end users attempt to query records in the detail block when there is no master record (in the master block) that came from the database, Form Builder will display an error message:FRM-41106: Cannot query records without a parent record.

It is usually appropriate to prevent masterless inserts when end users are likely to encounter an error if they attempt to commit detail records that have been created independently of a master record.  Such an error occurs when the detail block derives the value of its foreign-key items from the primary-key items in the master record (by way of the Copy Value from Item property).

Similarly, you might want to prevent masterless queries in a detail block because end users cannot perform effective queries from the detail block.  End users can query the existence of specific detail records, but they cannot determine which master records own them.  (This assumes that the foreign-key item(s) in the detail block are not displayed.)

Preventing Navigation to the Detail Block  Setting the Prevent Masterless Operation property to Yes prevents end users from querying and inserting in a detail block for which there is no corresponding master record, but it does not prevent them from navigating to the detail block and attempting these operations.

In some applications, it may be desirable to disallow any attempt to navigate to a detail block when there is no master record.


Preventing masterless operations in the detail block examples

Example

/* One way to prevent end users from navigating to a detail

** block for which there is no master. It is based on the
** detail block WAREHOUSE and the master block REGION.
** Use a When-New-Block-Instance trigger on detail block
** WAREHOUSE:
*/
DECLARE
  alert_dummy   NUMBER;
BEGIN
/* See if there is a master record by checking the status
** of the current record in the master block
*/
IF GET_RECORD_PROPERTY(GET_BLOCK_PROPERTY
   ('region', current_record), 'region', STATUS) = 'NEW'
   OR :region.region_id IS NULL THEN
/*
** There isn't a master record; display an alert that tells the
** end user to query or enter a region record before moving to
** the warehouse block
*/
   alert_dummy := SHOW_ALERT('my_alert');
/*
** Put the input focus in the master block
*/
   GO_BLOCK('region');
END IF;
END;
/* The When-New-Block-Instance trigger fires whenever the end
** user navigates to the detail block. The built-in function
** GET_RECORD_PROPERTY is used to determine the status of
** the current record in the master block. (The function
** GET_BLOCK_PROPERTY is nested as the first argument to
** GET_RECORD_PROPERTY to return the record number of the
** current record in the region block.)
**
** If the status of the current record is NEW, indicating that
** the record is not an existing master record, Form Builder
** displays an alert window with the message "Query or enter
** a master record before moving to the detail block."
** The trigger then navigates to the master block to allow the
** end user to do just that.
*/


Creating complex master-detail relations

Many applications require complex master-detail relations that involve more than two blocks.  To create such relations, simply define as many individual relations as needed.

There is no practical limit to the number of relations that can be defined in a form.  Further, any block can be the master or detail in more than one relation, and a block that is the master in one relation can be the detail in another.

When you create complex master-detail relations, Form Builder automatically adjusts the existing triggers to manage the relations you define.

This topic describes three of the most common types of complex master-detail relations:

•	master-with-dependent-details

•	master-with-independent-details

•	detail-with-two-masters


About complex relations and cascading deletes

When you set the Delete Record Behavior property of a relation to Cascading, be aware that deletes are enforced only for the immediate detail block in the relation.  For example, consider the complex master-detail relation involving relations between blocks A and B  (A_B), and B and C  (B_C) where B is both the detail block in the A_B relation and the master block in the B_C relation.

When the Delete Record Behavior property is Cascading for the relation A_B, the detail records in Block B are automatically deleted if the master record in Block A is deleted.  Detail records in Block C are not automatically deleted when a master record in Block A is deleted.  If, however, the Delete Record Behavior property of relation B_C is Cascading, then detail records in Block C are deleted when Block A is deleted.  Detail records in Block C are affected by the deletion of Block A, because when the Delete Record Behavior property is Cascading for the A_B relation, the deletion of a master record in Block A causes the deletion of the detail records in Block B.  The detail records in Block B also serve as master records in the B_C relation.  Since the Delete Record Behavior property is Cascading for the B_C relation, the deletion of a master record in Block B causes the deletion of detail records in Block C.

Master-with-dependent-details

A master-with-dependent-details relation includes a master block and n levels of detail blocks, such that the first detail block is itself a master for its own detail block.

To create a master-with-dependent-details relation, define the individual relations A_B and B_C separately (in any order).

When you create this type of relation, consider the effect of the Delete Record Behavior and Coordination properties on the detail blocks.  For example, if one relation in a chain of related blocks is set to deferred coordination, all subsequent blocks will also be deferred.  Thus, when relation A_B is deferred and relation B_C is immediate, Form Builder does not coordinate Block C with Block B until Block B is coordinated with Block A.

Master-with-independent-details

A master-with-independent-details relation involves two or more detail blocks, both sharing the same master block.  This structure is useful when you want to display more than one set of detail records for a single master record.  A coordination-causing event in the master block results in both detail blocks being populated with the appropriate detail records.

In the sample application, the master block REGION could be displayed along with the detail blocks WAREHOUSE and CUSTOMER.  The end user could then see all of the warehouses and customers within the currently selected region.

To create this type of relation, define the individual relations A_B and A_C separatel (in any order).

Detail-with-two-masters

A detail-with-two-masters relation involves a single detail block that has two master blocks.  Form Builder displays the appropriate detail records for whichever master block is the current block in the form. For example, in the sample application referred to earlier, the ord block could be a detail block having two master blocks, CUSTOMER and EMP.  End users could then see all of the orders for a particular customer, or for a particular sales representative (employee).

Usually, when you create a detail-with-two-masters relation, you will be joining on different foreign-key items in the detail block.  In such cases, the Copy Value from Item property is set for each foreign-key item in the detail block to point to the primary-key item in the appropriate master block.  To create this type of relation, you need only define the two relations;  Form Builder will automatically support coordination.

In other cases, however, you might want to create a master-with-two-details with each relation joining on the same foreign-key item in the detail block.  However, because the Copy Value from Item property can only point to one master block item, you will need to write additional code to coordinate querying and updating for the second relation if you are joining on the same item in the detail block.

Depending on the desired functionality, this might include writing a Pre-Query trigger for the detail block to ensure that the correct primary-key item value is copied to the foreign-key item in the detail block. For example,

COPY(NAME_IN(:system.master_block||'.primary_key_item'),
                                   'detail_block.item');

You might also want to create a When-New-Block-Instance trigger that checks the coordination status of the detail block whenever the end user navigates to a different master block, and, if necessary, populates the detail block.


About master-detail triggers and procedures

When you create a master-detail relation, Form Builder generates different triggers depending on how the Delete Record Behavior and Coordination properties are set.  The following table shows how the Delete Record Behavior property determines which triggers Form Builder creates.  When you change the setting of the Delete Record Behavior property for an existing relation, Form Builder adds or removes triggers as needed. The actual code in these triggers depends on how the Coordination properties are set, and on whether the relation is part of a complex relation chain.

Delete Record Behavior Property	Resulting Triggers
Non-Isolated (the default)	On-Check-Delete-Master, On-Clear-Details, On-Populate-Details
Cascading	On-Clear-Details, On-Populate-Details, Pre-Delete
Isolated	On-Clear-Details, On-Populate-Details


Master-detail triggers

This section describes the triggers that Form Builder creates when you define a master-detail relation.  The example trigger text shown with each trigger description shows the basic structure of the trigger. The actual trigger text that you will see in your own forms will be application-specific, and may look somewhat different.

(If specific triggers already exist for the master block, those existing triggers are used, and Form Builder does not create new, additional ones.)

Form Builder also creates user-named procedures that are called by master-detail triggers.

Form Builder generates comments in the default trigger and procedure code.  Comments are denoted by the standard PL/SQL double-hyphen ('- -').

On-Clear-Details Trigger  Every master-detail relation must have an On-Clear-Details trigger.  It fires during the clear phase of coordination, and clears all of the detail records in the detail block.  This trigger calls the CLEAR_ALL_MASTER_DETAILS procedure, as shown in the following example trigger text:

-- Begin default relation program section
--
     Clear_All_Master_Details;
--
-- End default relation program section

On-Check-Delete-Master Trigger  Form Builder creates the On-Check-Delete-Master trigger when the Delete Record Behavior property is set to Non-Isolated.  It fires when there is an attempt to delete a master record.  The trigger queries the database to see if detail records exist for the master record.  If no details exist, the trigger deletes the master record.  If detail records are found, the trigger displays the message:

Cannot delete master record when matching detail records exist.

as shown in the following example trigger text:

--
-- Begin default relation declare section
--
    Declare
        Dummy_Define char(1);
        --
        -- Begin B detail declare section
        --
        cursor B_cur is
           select null from MASDET
           where PARENT = :A.ID;
        --
        -- End B detail declare section
        --
    --
    -- End default relation declare section
    --
    --
    -- Begin default relation program section
    --
    Begin
    --
    -- Begin B detail program section
    --
       Open B_cur;
       Fetch B_cur into Dummy_Define;
       if ( B_cur%found ) then
          Message('Cannot delete master record when matching
                   detail records exist.');
          Close B_cur;
          raise Form_Trigger_Failure;
      end if;
      Close B_cur;
    --
    -- End B detail program section
    --
End;
--
-- End default relation program section

On-Populate-Details Trigger  Form Builder creates a On-Populate-Details trigger for every master-detail relation.  It fires during the population phase of block coordination.  The trigger first checks the status of the master record and the value of its primary-key field, then navigates to the detail block to issue the appropriate query.  This trigger calls the QUERY_MASTER_DETAILS procedure, as shown in the following example trigger text:

--
-- Begin default relation declare section
--
Declare
    recstat     char(20) := :system.record_status;
    relation_id relation;
--
-- End default relation declare section
--
--
-- Begin default relation program section
--
Begin
    if ( recstat = 'NEW' or recstat = 'INSERT' ) then
       return;
    end if;
    --
    -- Begin B detail program section
    --
    if ((:A.ID is not null)) then
       relation_id := find_relation('A.AB');
       Query_Master_Details(relation_id, 'B');
    end if;
    --
    -- End B detail program section
    ----
End;

Pre-Delete Trigger  Form Builder creates the Pre-Delete trigger when the Delete Record Behavior property is set to Cascading.  It deletes the records in the detail block's base table that correspond to the master record that is being deleted.

--
-- Begin default relation program section
--
BEGIN
    --
    -- Begin detail_block detail program section
    --
    DELETE FROM detail_block_base_table
    WHERE foreign_key_column = :master_block.primary_key_item;
    --
    -- End detail_block detail program section
    --
END;
--
-- End default relation program section
--


Triggers for complex master-detail relations

When you create a complex master-detail relation, Form Builder adds or edits the existing master-detail triggers to support the relation you have defined. The following example illustrates how Form Builder adds or edits triggers as required.

Example:  Master with Independent Details  Consider a single relation A_B, with Delete Record Behavior property set to Non-Isolated and coordination property Deferred set to No (default settings).  Form Builder creates the following triggers on the master block to manage the relation:

•	On-Clear-Details

•	On-Check-Delete-Master

•	On-Populate-Details

If you then create a second relation A_C (having the same master block but a different detail block), you have created a master-with-independent-details relation; that is, one master block with two detail blocks.

To manage this relation, Form Builder does not create any additional triggers.  Instead, Form Builder adds a section to each existing trigger to facilitate clearing and populating the second detail block.  The generated comments in these triggers delimit the sections that manage each detail block.  For example, the comments in the On-Populate-Details trigger clearly show where each detail block section begins and ends:

-- Begin default relation program section
BEGIN
    --
    -- Begin first_detail_block program section
    --
    /* trigger text to clear the first detail block*/
    --
    -- End first_detail_block program section
    --
    --
    -- Begin second_detail_block program section
    --
    /* trigger text to clear the second detail block*/
    --
    -- End second_detail_block program section
    --
    /* final trigger text */
END;
-- End default relation program section
--


Modifying the default relation triggers

You may at some point want to add your own comments and code to the default master-detail triggers that Form Builder creates.  You can edit a default trigger as you would any trigger that you had created yourself.

Remember, however, that if you later change the properties of the relation, Form Builder may need to delete or edit the default triggers.  For example, changing a relation's Delete Record Behavior property from Cascading to Isolated causes Form Builder to remove the now unnecessary Pre-Delete trigger.

Consider the following points when you edit master-detail triggers:

•	Do not alter or delete the comments that Form Builder generates.  These comments tell Form Builder where to insert or delete trigger text when changes are necessary.

•	If you add code to a trigger, insert it before the "Begin default relation program section" comment or after the "End default relation program section" comment.

•	Form Builder does not delete a master-detail trigger that you have modified, provided that you place your code outside the default relation program section.  (Form Builder removes the relation program section, but does not delete the trigger.)


Master-detail procedures

This section shows the text of the master-detail procedures that Form Builder creates automatically when you define a relation.  These procedures are called from the master-detail triggers or from other procedures.

CLEAR_ALL_MASTER_DETAILS Procedure  This procedure is called by the On-Clear-Details trigger.  It navigates to the detail block and clears the detail records.

PROCEDURE Clear_All_Master_Details IS
    mastblk  CHAR(30);  /* Initial Master Block Causing Coord */
    coordop  CHAR(30);  /* Operation Causing the Coord        */
    trigblk  CHAR(30);  /* Cur Block On-Clear-Details Fires On*/
    startitm CHAR(61);  /* Item in which cursor started       */
    frmstat  CHAR(15);  /* Form Status                        */
    curblk   CHAR(30);  /* Current Block                      */
    currel   CHAR(30);  /* Current Relation                   */
    curdtl   CHAR(30);  /* Current Detail Block               */

FUNCTION First_Changed_Block_Below( Master CHAR ) RETURN CHAR
IS
    curblk CHAR(30);  /* Current Block    */
    currel CHAR(30);  /* Current Relation */
    retblk CHAR(30);  /* Return Block     */
BEGIN
    /*
    ** Init Local Vars
    */
    curblk := Master;
    currel :=Get_Block_Property(curblk,FIRST_MASTER_RELATION);
    /*
    ** While there exists another relation for this block
    */
    WHILE currel IS NOT NULL LOOP
       /*
       ** Get the name of the detail block
       */
       curblk := Get_Relation_Property(currel,DETAIL_NAME);
       /*
       ** If this block has changes, return its name
       */
       IF Get_Block_Property(curblk,STATUS) IN
                            ('CHANGED','INSERT') THEN
                            RETURN curblk;
       /*
       ** Otherwise, recursively look for changed blocks below
       */
       ELSE
          retblk := First_Changed_Block_Below(curblk);
       /*
       ** If some block below is changed, return its name
       */
       IF retblk IS NOT NULL THEN
          RETURN retblk;
       /*
       ** Otherwise, Consider the next relation
       */
       ELSE
          currel := Get_Relation_Property (currel,
                                           NEXT_MASTER_RELATION);
       END IF;
    END IF;
END LOOP;
/*
** If we get here, no changed blocks were found
*/
RETURN NULL;
END First_Changed_Block_Below;
BEGIN
    /*
    ** Init Local Vars
    */
    mastblk  := :System.Master_Block;
    coordop  := :System.Coordination_Operation;
    trigblk  := :System.Trigger_Block;
    startitm := :System.Trigger_Item;
    frmstat  := :System.Form_Status;
    /*
    ** If the coord op is anything but CLEAR_RECORD, then
    ** continue checking.
    */
    IF coordop <> 'CLEAR_RECORD' THEN
       /*
       ** If we're processing the driving master block...
       */
       IF mastblk = trigblk THEN
       /*
       ** If something in the form is changed, find the
       ** first changed block below the master
       */
       IF frmstat = 'CHANGED' THEN
          curblk := First_Changed_Block_Below(mastblk);
          /*
         ** If we find a changed block below, go there
         ** and Ask to commit the changes.
         */
      IF curblk IS NOT NULL THEN
         Go_Block(curblk);
         Check_Package_Failure;
         Clear_Block(ASK_COMMIT);
       /*
       ** If user cancels commit dialog, raise error
       */
       IF NOT( :System.Form_Status = 'QUERY' /* Yes */  OR
      :System.Block_Status = 'NEW'  /* No */ ) THEN
         RAISE Form_Trigger_Failure;
       END IF;
       END IF;
     END IF;
    END IF;
  END IF;
/*
** Clear all the detail blocks for this master without
** any further asking to commit.
*/
currel := Get_Block_Property(trigblk,FIRST_MASTER_RELATION);
WHILE currel IS NOT NULL LOOP
    curdtl := Get_Relation_Property(currel,DETAIL_NAME);
    IF ( Get_Block_Property(curdtl, STATUS) <> 'NEW' ) THEN
       Go_Block(curdtl);
       Check_Package_Failure;
       Clear_Block(NO_VALIDATE);
       IF ( :System.Block_Status <> 'NEW' ) THEN
          RAISE Form_Trigger_Failure;
       END IF;
    END IF;
    currel := Get_Relation_Property(currel,NEXT_MASTER_RELATION);
END LOOP;
/*
** Put cursor back where it started
*/
IF ( :System.Cursor_Item <> startitm ) THEN
    Go_Item(startitm);
END IF;
EXCEPTION
    WHEN Form_Trigger_Failure THEN
       IF :System.Cursor_Item <> startitm THEN
       Go_Item(startitm);
       END IF;
     RAISE;
END Clear_All_Master_Details;

QUERY_MASTER_DETAILS Procedure  This procedure is called from the On-Populate-Details trigger.  It navigates to the detail block and then executes a query to fetch the appropriate detail records.

PROCEDURE Query_Master_Details(rel_id Relation, detail CHAR) IS
    oldmsg CHAR(2);  /* Old Message Level Setting */
    reldef CHAR(5);  /* Relation Deferred Setting */
BEGIN
    /*
    ** Initialize Local Variable(s)
    */
    reldef := Get_Relation_Property(rel_id,
                     DEFERRED_COORDINATION);
    oldmsg := :System.Message_Level;
    /*
    ** If NOT Deferred, Goto detail & execute the query.
    */
    IF reldef = 'FALSE' THEN
       Go_Block(detail);
       Check_Package_Failure;
       :System.Message_Level := '5';
       Execute_Query;
       :System.Message_Level := oldmsg;
       /*
       ** If Deferred, Mark the detail block as un-coordinated
       */
    ELSE
       Set_Block_Property(detail, coordination_status,
                          NON_COORDINATED);
    END IF;
EXCEPTION
    WHEN Form_Trigger_Failure THEN
       :System.Message_Level := oldmsg;
    RAISE;
END Query_Master_Details;

CHECK_PACKAGE_FAILURE Procedure  This procedure is called by the CLEAR_ALL_MASTER_DETAILS and QUERY_MASTER_DETAILS procedures.  It checks to see if the previous statement executed successfully by looking at the status of the built-in Form Builder error variable FORM_SUCCESS.

PROCEDURE Check_Package_Failure IS
BEGIN
    IF (NOT Form_Success) THEN
       RAISE Form_Trigger_Failure;
    END IF;
END;


Modifying the default master-detail functionality

  Related Topics

In special situations, you may want to modify or extend the default master-detail functionality that Form Builder provides.  For example, if your application runs against non-ORACLE data sources or includes long relation chains that require non-standard functionality, you might want to implement your own block coordination mechanism.

Form Builder provides a number of triggers and built-in subprograms that are useful for such tasks, some of which are listed here.  For complete documentation on these triggers and routines, refer to the Form Builder online help system.

Triggers:

•	On-Clear-Details

•	On-Populate-Details

•	On-Check-Delete-Master

•	When-New-Record-Instance

•	When-New-Block-Instance

Built-in subprograms:

•	GET_BLOCK_PROPERTY

•	SET_BLOCK_PROPERTY

•	GET_FORM_PROPERTY

•	GET_RELATION_PROPERTY

•	SET_RELATION_PROPERTY

For example, you can use these built-in subprograms as follows:

•	Use GET_FORM_PROPERTY to get the name of the first and last block in the form (FIRST_BLOCK, LAST_BLOCK).

•	Use GET_BLOCK_PROPERTY to find out a block's current COORDINATION_STATUS (either COORDINATED or NON_COORDINATED) and a block's FIRST_RELATION, that is, the name of the first relation in which the block is a master.

•	Use SET_BLOCK_PROPERTY to set block properties dynamically.

•	Use GET_RELATION_PROPERTY to get the current property settings for a relation (MASTER_DELETES, DEFERRED_COORDINATION, and AUTOQUERY), the names of the master and detail blocks (MASTER_NAME, DETAIL_NAME), and the name of the next relation in the form (NEXT_MASTER_RELATION, NEXT_DETAIL_RELATION). For example, to assign the name of the master block in a relation to a local variable you might write the following:

  DECLARE
    master_block    VARCHAR2;
  BEGIN
    master_block := Get_Relation_Property('my_relation',
                                           MASTER_BLOCK);
  END;

•	Use SET_RELATION_PROPERTY to set the properties of a relation dynamically. For example, to set the Delete Record Behavior property you could call the following procedure:

  SET_RELATION_PROPERTY('my_relation',
                        master_deletes,
                        deferred_coordination);


Setting properties in the Property Palette
Setting properties

  Related Topics

To set the value of a property:

1	Select the object whose properties you want to set.

You can select objects in the Form Editor, Object Navigator, or the Menu Editor. When you select an object, the Property Palette displays the properties of that object. (If the Property Palette is not currently displayed, select Tools [image] Property Palette.)

2	In the Property Palette, select the property you want to set.

You can select properties by clicking or by navigating with the Up/Down arrow keys. When a property is selected, a text field, poplist, or More... button is displayed beside the property.

3	Set the selected property to the desired setting.


About setting properties of multiple selections

 Examples	     Related Topics

You can select multiple objects at the same time by Control-clicking in the Object Navigator or the editors. When two or more objects are selected, the message "Multiple Selection" is displayed at the top of the Property Palette instead of the Name field.

The Intersection/Union command on the Property Palette toolbar determines which properties are displayed in the property list when more than one object is selected. Switching between Intersection and Union changes the list of properties displayed in the Property Palette, but does not affect the setting of any property.

Intersection  The default.  Only properties common to all selected objects are displayed.

Union  All properties of every object selected are displayed.

Properties that are common to two or more objects in a multiple selection are listed only once, and the property setting is displayed as follows:

•	If the property has the same setting for all of the selected objects that have it in common, the common setting is displayed.

•	If the property is set differently for the objects that have it in common, the string "***** " is displayed.


Setting properties of multiple selections

  Related Topics

To set the properties of multiple selections:

1	In the Object Navigator or the editors, select the objects whose properties you want to set by using Control-click. The objects can be of different types and can even be in different documents.

2	In the Property Palette, set the Intersection/Union toggle command to specify which properties you want to see.

3	Set properties as desired.

Any change you make to a property setting is applied to all of the objects in the current selection to which that property applies.


Setting properties of multiple selections example

A form includes several text items, each of which displays the date in a different window. The Parameter Data Type property of each text item is DATE, which causes dates to be displayed in the default ORACLE format DD-MON-YY.

To use a different date format throughout the application, you need to set the Format Mask property for each text item that displays dates. Rather than setting each text item's Format Mask property individually, select all of the items in the Object Navigator, then set the Format Mask property once to change the format mask for each item selected.


Comparing the properties of one object to another

  Related Topics

To compare the properties of one object to another:

1	In the Object Navigator or the editors, select the first object so that its properties are displayed in the Property Palette.

2	In the Property Palette, click the Freeze/Unfreeze button to turn synchronization Off and "freeze" the Property Palette.

3	In the Object Navigator, Shift+double-click the object icon for the second object.

Form Builder displays a second Property Palette. If the second window is on top of the first, drag it to move it alongside the first window.


About copying properties from one object to another

  Related Topics

You can use the Copy Properties and Paste Properties commands to copy the property settings of one object to another object.

Properties can be copied and pasted in the Object Navigator, the Form Editor, the Menu Editor, and the Property Palette.

Copy Properties  You can copy the property settings of the selected objects to the clipboard.

Paste Properties  You can, paste the current clipboard property settings to any objects selected in that window. Properties that do not apply to the current selection are ignored.

You will most often copy the properties of an object to one or more objects of the same type. However, it is also possible to copy the properties of an object to objects of a different type. In this case, properties that do not apply to the target object are ignored.

You can copy the property settings of an object in one window and then paste those settings to an object in another window. For example, you might select a button in the Object Navigator, click the Copy Properties button to copy its property settings, then Paste those settings to a different button selected in the Form Editor.

When you copy the properties of a multiple selection, only properties that do not have conflicting values are copied to the clipboard. For example, if you copy the properties of three text items selected in the Object Navigator,  the Width and Height settings are copied only if each text item is the same size.


Copying properties from one object to another

  Related Topics

To copy properties:

1	Select the object whose property settings you want to copy.

2	Choose Edit [image] Copy Properties.

3	Select the target object.

4	Choose Edit [image] Paste Properties.


Setting properties at Runtime

  Related Topics

Many object properties can be set programmatically at runtime. For example, each window object has a Visible property that can be set to either Yes or No to show and hide the window. At runtime, you can call the built-in procedure SET_WINDOW_PROPERTY to show or hide the window dynamically, as shown here:

Set_Window_Property('my_window',VISIBLE, PROPERTY_ON);

The following built-in procedures are available for setting object properties at runtime:

•	SET_BLOCK_PROPERTY

•	SET_CANVAS_PROPERTY

•	SET_FORM_PROPERTY

•	SET_ITEM_PROPERTY

•	SET_LOV_PROPERTY

•	SET_MENU_ITEM_PROPERTY

•	SET_PARAMETER_ATTR

•	SET_RADIO_BUTTON_PROPERTY

•	SET_RECORD_PROPERTY

•	SET_RELATION_PROPERTY

•	SET_VIEW_PROPERTY

•	SET_WINDOW_PROPERTY

The built-in procedure SET_ITEM_PROPERTY can be used to set the properties of any type of item, including buttons, text items, check boxes, radio groups, etc.

Note:  Radio group items include individual radio buttons; use SET_ITEM_PROPERTY to set the properties of the radio group, and SET_RADIO_BUTTON_PROPERTY to set the properties of the individual buttons in the group.

Each built-in SET procedure has a corresponding GET function that allows you to programmatically determine the current setting of an object's properties. The following example uses GET_WINDOW_PROPERTY to determine if a window is currently hidden (VISIBLE = FALSE). If the window is hidden, SET_WINDOW_PROPERTY is called to show the window.

If Get_Window_Property('my_window',VISIBLE) = 'FALSE' THEN
   Set_Window_Property('my_window',VISIBLE,PROPERTY_ON);

To determine if a particular property can be set programmatically, refer to the property descriptions in online Help.


What is a sound item?

  Related Topics

Sound items allow end users to play and record sound data while working in a Form Builder application.  Developers can set up sound items to allow end users to play, record, and store sound data stored in a database column or in the file system.

To create a sound item for recording and playing sound data in a database table, you must base the item on a LONG RAW column.  Once you accomplish this step, Form Builder automatically provides all functionality for recording and playing sound.

Note:  You also can create a sound item that records and plays sound in a file in a file system.


About recording and playing sound data

Once you have created a sound item based on a LONG RAW database column, end users can play and record sound data when they use a Form Builder application by clicking the various buttons of the sound control item, provided they have the required software and hardware (sound card, drivers, speakers, microphone, etc.) for playing and recording sound data in their native environment.

To play and record sound data from a LONG RAW database column, the column either must contain sound data already, or be able to accept sound data from application end users (i.e., the item's Insert Allowed and Update Allowed properties are set to Yes).  When you create a sound item based on a LONG RAW column from the database, Form Builder automatically represents the item in the layout with a sound control widget that allows end users to play sound data.

Performance Issues  Transmitting large sound objects across a network can impede performance.  If you plan to store sound data in the database, reduce the effect on performance by setting the Update Changed Columns Only property to Yes for the sound item's block.  In this manner you increase the performance of your application—by avoiding network roundtrips involving records with non-updated sound items.

Playing and Storing Sound Data in a File  Form Builder provides three built-in procedures that developers can use to enable end users to play and record sound data in a file:

Refer to documentation for these built-ins for instructions on how to play and record sound data from a file in the file system.

•	PLAY_SOUND

•	READ_SOUND_FILE

•	WRITE_SOUND_FILE


About the sound item control

  Related Topics

When you create a sound item, Form Builder automatically represents the item in the layout with [image] , the sound item control.

The sound item control contains the following components, each of which is optional (except Play or Record, one of which always must be displayed):

•	  Play:  starts playback of the sound data from the current pointer position.  (Clicking Play during playback stops the pointer at the current position;  click Play again to continue playback.  If you play a sound to its end and then click Play again, Form Builder automatically moves the pointer to the beginning position before restarting playback of the sound.)

•	  Record:  starts recording sound data from the current pointer position.  (Clicking Record a second time stops recording.  If the pointer is at the beginning or middle position of an existing sound when you click Record, Form Builder overwrites the existing sound with the new sound data you record, from the current pointer position onward.)

•	  Rewind:  rewinds sound data (from the current pointer position) to the beginning of the sound.

•	  Fast Forward:  fast forwards the sound data (from the current pointer position) to the end of the sound.

•	  Volume:  displays a vertical slide control you can use to control playback and recording volume.  (Click-drag the handle up to increase volume, down to decrease.)

•	  Time Indicator:  displays three modes of time information for the sound data.  (Click the indicator text to toggle between total time, elapsed time, and remaining time.)

•	  Slider:  horizontal slide control indicates current pointer position within the sound data.  (Slide the handle left or right to reposition the pointer.)

Note:  To independently display or hide each sound control component (in the Form Builder layout and at runtime), set the component's display property to Yes (show) or No (hide).  There is an exception:  you cannot set both the Show Play Button and Show Record Button properties to No.  If you do, Form Builder displays the Play button at runtime by default.


Creating a sound item

  Next Step	    Related Topics

To create a sound item:

1	In the Object Navigator, click the Items node and click  the Create button  in the toolbar.

Or, from the Layout Editor, click  [image]  and drag an area on the canvas where you want the sound item to appear.

Form Builder creates an item and gives it a default name, such as ITEM17.

2	Change the item name to the name of the LONG RAW column from the database table on which the block is based.

Note:  You also can use the Data Block Wizard to create an item based on a LONG RAW database column.

3	Double-click the item's object icon to display the Property Palette.

4	Under the General node, set the Item Type property to Sound.

5	Under the Functional node:

•	Set the Sound Format property to AU, AIFF, AIFF_C, or WAVE (the format of the sound data).

•	Set the Audio Channels property to Mono (monophonic), Stereo (stereophonic), or Automatic (defaults to the channel setting of the sound data).

•	Set the Sound Quality property to Highest, High, Medium, Low, Lowest, or Automatic (defaults to the quality setting of the sound data).

6	Under the, Database node:

•	Set the Database Item property to Yes.

•	Set the Column Name property to the name of the LONG RAW database column where the sound data is stored.

7	Under the Physical node, set the Canvas property to the name of the canvas where the sound item control will be displayed.

By setting an item's type to Sound and placing it on a canvas, Form Builder automatically places the sound control widget on the canvas you specified.


Setting sound item control properties

  Related Topics

To set sound item control properties:

1	In the Object Navigator, under the Blocks and Items nodes, double-click the sound item's object icon to display the Property Palette.

2	In the Property Palette, under the Physical node, set the sound item control properties to Yes or No.  (Setting a property to Yes causes Form Builder to display the sound item control component at design time and runtime.)  The properties are:

•	Show Fast Forward Button  (default = No)

•	Show Play Button  (default = Yes)

•	Show Record Button  (default = No)

•	Show Rewind Button  (default = No)

•	Show Slider  (default = Yes)

•	Show Time Indicator  (default = Yes)

•	Show Volume Control  (default = Yes)


Manipulating sound items programmatically

  Related Topics

To programmatically show and hide the buttons of the sound item control, use the Form Builder built-ins GET_ITEM_PROPERTY and SET_ITEM_PROPERTY to get and set sound item control properties (e.g., Show_Rewind_Button).

Note:  Recall that you cannot hide Play if Record already is hidden.  Form Builder always displays either the Play or Record button by default at runtime;  you can hide one or the other, but not both.


About standards

  Related Topics

You can use Forms Developer to define and distribute application standards.

Standards ensure quality and a consistent look and feel within an application.  Standards also allow a team of developers to be more productive.  Developers working on one part of an application can create and test objects which can be easily reused in another part of the application with little or no modification.  To reuse a standard object, simply drag the desired object from the Object Library to the desired module.

When you create a standard, you perform these steps:

1	Define standards.

2	Within Form Builder, create objects that conform to standards.

3	Store standard objects in the Object Library.

4	Distribute standards to developers.


Guidelines for creating standards

  Related Topics

When creating standards, consider these guidelines:

•	Before creating your own standards, consider using the Forms Developer user interface standards.

•	Use the Object Library as the primary mechanism for creating and reusing standard objects.

•	Use caution when deleting source objects; deleting a source object will break the link to instance objects.


Setting Standards

  Related Topics

One common approach to application development is to start by creating and then refining standards, based on prototyping efforts and usability testing.  Because each company's requirements are unique, the best standards for your company will also be unique.

Consider developing three types of standards:

•	Coding standards, including naming standards for all objects and files.

•	GUI standards,  including standards for screen appearance, such as color, spacing and layout, as  well as standards for specific GUI objects, such as buttons and check boxes.

•	Usage standards, including look-and-feel standards that ensure that various parts of the application react to user input in the same way.

•	For guidance in setting UI standards, consult the following platform-specific references:

•	Microsoft Windows: The Windows Interface: An Application Design Guide

•	Motif:  Motif Style Guide

•	Macintosh:  Macintosh Human Interface Guidelines


Creating a reusable object

  Next Step	    Related Topics

To create a reusable object:

1	Choose Tools [image] Object Library.

2	In the Object Navigator, drag the desired object to the Object Library.

Form Builder creates a new version of the object and stores it in the Object Library.


Reusing an object in the Object Library

  Related Topics

To reuse an object in the Object Library:

1	In the Object Library, click the desired object.

2	Press Ctrl and drag the object to the desired module and node.

Form Builder displays the Copy/Subclass dialog.

3	Click Subclass.

Form Builder creates a subclassed version of the object.


Modifying an object in the Object Library

  Related Topics

To modify an object in the Object Library:

1	In the Object Library, press Ctrl and drag the desired object to the desired node in the Object Navigator.

Form Builder displays the Copy/Subclass dialog.

2	Click Copy.  This creates an editable copy of the object.

3	Modify the object as desired.

4	Drag the object back to the Object Library.

5	In the dialog, click Yes to replace the existing object with the modified object.


Adding a comment to an object in the Object Library

To add a comment to an object in the Object Library:

1	In the Object Library, click the desired object.

2	Click the Edit Comment button in the toolbar.

3	Type the desired text in the Comment dialog.


About SmartClasses

A SmartClass is a special object that you create within the Object Library.  Once you define an object as a SmartClass, you can create new objects based on the SmartClass by dragging the desired SmartClass to the Object Navigator, or you can apply the SmartClass to an existing object by choosing SmartClasses from the popup menu.  When you base an object on a SmartClass, that object is subclassed; it inherits its functionality and appearance from the SmartClass.

In both single and multi-developer environment, SmartClasses provide several benefits:

•	subclassing

•	rapid reuse and development

•	distributable

Typically, a SmartClass adheres to the user interface standards that you define for a project.  To distribute your standards, you store your standard objects within an Object Library document, then distribute the object libraries to your development team for reuse.

For example, you can store a standard block (EMP) and frame within the Object Library to create a standard block and layout.  Each time, the block is dragged into a form, the items within the EMP block are arranged consistently with the same visual representation.

SmartClasses differ from the other objects in the Object Library in that any object that is SmartClassed is always a subclassed object.

By default, when you drag an object (that is not a SmartClass) to a form, the object created is a copy, not a subclassed object.

Other objects in the Object Library can only be used to create new object intances, never to modify an existing object.  In contrast, SmartClasses can be applied to existing objects.


Creating a SmartClass

  Next Step	    Related Topics

To create a SmartClass:

1	Choose Tools [image] Object Library to display the Object Library.

2	In the Object Library, click the desired object.

3	Choose Object [image] SmartClass.


Creating an object based on a SmartClass

  Related Topics

To create an object based on a SmartClass:

1	In the Object Library, click the desired SmartClass.

2	Drag the SmartClass to the desired module and node.


Applying a SmartClass to an existing object

To apply a SmartClass to an existing object:

1	In the Object Navigator, click the desired object.

2	Click the right mouse button to display the popup menu.


Modifying a SmartClass

  Related Topics

To modify a SmartClass:

1	In the Object Library, drag the desired object to the appropriate node in the Object Navigator.  This creates an editable copy of the object in the Object Library.

2	Modify the object as desired.

3	Drag the object back to the Object Library.  This moves the object from the form into the Object Library.

4	In the dialog, click Yes to replace the existing object with the modified object.

Note: Any changes to the parent SmartClass are automatically inherited by every child instance of the SmartClass.


Distributing standards

To distribute standards:

Distribute your standards as either an object library (.OLB), form (.FMB), or menu (.MMB) module.

Tip: Distributing your standards within an Object Library module (.OLB) is the preferred method:

•	Object Library modules are automatically re-opened when Form Builder starts-up.  This provides immediate access to reusable objects.

•	In contrast to form and menu modules, Object Libraries provide SmartClasses.


About reuse

  Related Topics

Form Builder includes many features that make development projects easier by allowing you to reuse objects. Reusing objects helps you maintain consistency in your applications, and allows you to build on work that you or other developers have done previously.

Reusing Objects

There are many ways to reuse an object; you can:

•	copy an object

Copy an object when you want to create a new and separate instance of the the object.

•	subclass an object

Subclass an object when you want to create a new object that maintains a link to the source object. Once you create a subclassed object, any changes you make to the source object are inherited by the subclassed object when you open or recompile the module that contains the subclassed object.  If the both modules are open, changes are inherited immediately.

•	create a visual attribute

Create a visual attribute when you want to create a standard for font, color, and pattern properties for the form and menu objects that appear in your application's interface.

•	create an object group

Create an object group when you want to bundle objects into higher-level building blocks that can be used in other parts of an application and in subsequent development projects.

•	create a property class

Create a property class when you want to define a universal subclassing parent.

•	create a template form

Create a template form when you want to create a default starting point for team member development.

Templates typically include generic objects, such as boilerplate, toolbars, program units, and more.


About copying objects

  Related Topics

One of the simplest ways to reuse an object is to copy it.

When you copy an object, you create a new and separate instance of the the object, and any objects owned by the object being copied are always copied automatically.

For example, when you copy a block, the new block includes any items that were owned by the block and any triggers that were attached to the block or its items.

Note:  When you copy an object to another module, Form Builder does not automatically convert size and position coordinates if the target module uses a different coordinate system than the source module.


Copying an object

  Related Topics

To copy an object:

1	In the Object Navigator, click the desired object.

2	Press Ctrl and drag the object to the desired location.

Form Builder displays the Copy/Subclass dialog.

3	Click Copy.


About subclassing

  Related Topics

When you subclass an object, you create an object that inherits its functionality and appearance from another object.

Subclassing an object is similar to copying an object, except that the resulting subclassed object maintains a link to its source object. A subclassed object automatically inherits any changes that have been made to the source object when you open or recompile the module that contains the subclassed object unless both modules are open.  If both modules are open, changes are inherited immediately.

Subclassing allows you to:

•	create an independent subclass of any object

•	automatically propagate any changes made to the source object to each subclassed object

•	override a subclassed object's properties and structure

Subclassing, used in conjunction with the Object Library, can provide a powerful method for defining and enforcing look-and-feel requirements.  Any object that is stored within the Object Library can be subclassed into form and menu modules to create independent instances of the parent class.


Guidelines for subclassing objects

    Related Topics

When subclassing objects, consider these guidelines:

•	When you subclass an object, the objects owned by the source object get subclassed, not the objects associated with the source object.

For example, when you subclass a block, the graphic text labels for items in the block are not included.  Graphic text is owned by the canvas on which it appears. To subclass graphic text, you must subclass the desired canvas.

•	When you subclass an object across modules, both the source module and the target module must be open, and the source module must already have been saved, either to the file system or the database.

•	Use caution when deleting source objects; deleting a source object will break the links to any subclassed objects.

•	Use caution when you modify the name of a source object.

You can interfere with the functionality of the application when you change the name of an item that is referenced in trigger or program unit code, or that relates to a database column.

•	Use caution when overriding complex values (e.g., list elements).

•	Modifying a program unit that has been subclassed will require the subclassed program units to be recompiled.

•	You must use the Property Palette to modify subclassed code.  Modifying subclassed code in the PL/SQL Editor will break the link to the source object.


Subclassing an object

  Related Topics

To subclass an object:

1	In the Object Navigator or Object Library, click the desired object, then press Ctrl and drag the object to the desired location.

Form Builder displays the Copy/Subclass dialog.

2	Click Subclass.

Form Builder creates a subclassed object. If the name of the subclassed object conflicts with the name of an existing object, Form Builder assigns a new name to the subclassed object. A subclassed object is displayed in the Object Navigator with an arrow icon after its name to indicate that it is subclassed from another object


Modifying a source object

  Related Topics

To modify a source object:

1	Open the source module (either .FMB or .MMB) if it is not already open.

2	Modify the source object as desired.

Form Builder automatically propagates any changes made to the source object to each subclassed object when the module containing the subclassed object is next opened.


About modifying subclassed objects

  Related Topics

You can modify a subclassed object by doing any of the following:

•	Set the properties of the object as desired, overriding or inheriting properties as desired.

Use the Property Palette to quickly view a subclassed object's properties.  The Property Palette displays an arrow beside subclassed properties, a small circle beside default values, a square beside non-default values, and an arrow/check symbol beside local overrides.

•	Modify subclassed code as desired.

Use the Property Palette to modify subclassed triggers and program units.

Note: Do not use the PL/SQL Editor to modify subclassed code; doing so will break the link to the source object.


Modifying a subclassed object

  Related Topics

To modify a subclassed object:

1	In the Object Navigator, click the desired object.

2	Choose Tools [image] Property Palette.

3	Modify the object as desired.


Rolling back a property to its inherited value

To rollback a property to its inherited value:

1	In the Property Palette, click the desired property.

2	Click the Inherit button on the Property Palette toolbar.

The property inherits the setting of the corresponding property in the source object.

Note:  The Inherit command on the Property Palette toolbar is the only way to convert a variant property to an inherited property. Simply setting a variant property to the same value as the property in the class does not create an inherited property; rather, it creates a variant property that happens to be set to the same value as the property in the class. If you subsequently update the property setting in the class, the property is still variant and so will not inherit the change.


About subclass information

  Related Topics

During the life of an application, it may become necessary to update information about the source for a subclassed object.

For example, if the name of the source object has changed, Form Builder will be unable to locate the object when you compile a module that refers to it. Similarly, moving a source module from the file system into the database invalidates any references to that module.

You can update information about a subclassed object's source by setting the Subclass Information property.

The definition of a subclassed object includes information about the source object on which it is based, including the name of the source object, the name of the source module, and the storage location (file system or database).

Note:  You should use caution when modifying an object's Subclass Information.  If you enter the name or location of the source object incorrectly, the object's inherited properties will revert to the default values for that object's type.


Updating an object's subclass information

  Related Topics

To update an object's subclass information:

1	In the Object Navigator, double-click the subclassed object to display the Property Palette.

2	Under the General node, double-click the Subclass Information property and set the Subclass Information dialog attributes as necessary:

Access:  The source module location (File or Database).

Type:  The source module type (Form or Menu).

Module:  The name of the source module that contains the source object for the subclassed object.

Object Name:  The name of the source object.


About property classes

  Related Topics

A property class is a named object that contains a list of properties and their settings. Once you create a property class you can base other objects on it.  An object based on a property class can inherit the setting of any property in the class that makes sense for that object.

Property class inheritance is an instance of subclassing. Conceptually, you can consider a property class as a universal subclassing parent.

There can be any number of properties in a property class, and the properties in a class can apply to different types of objects. For example, a property class might contain some properties that are common to all types of items, some that apply only to text items, and some that apply only to check boxes.

When you base an object on a property class, you have complete control over which properties the object should inherit from the class, and which should be overridden locally.

Property classes are separate objects, and, as such, can be copied between modules as needed. Perhaps more importantly, property classes can be subclassed in any number of modules.


Guidelines for creating property classes

  Related Topics

When you work with property classes, consider these guidelines:

•	You can define property classes in form and menu modules.

•	After creating a property class, you can add and remove properties from it as desired. You can add properties one at a time, or with the Copy/Paste properties commands.

Often, you will want to remove some properties so that the class definition contains only properties that objects you base on the class will actually inherit.

For example, you might create a property class from the definition of an existing text item so you could apply the same font and height characteristics to other text items. However, the new property class would also contain the X Position and Y Position properties. Since these properties define display coordinates that would almost always need to be overridden for each text item you base on the class, you might want to remove them from the class definition.

•	When you base an object on a property class, the properties of that object are updated as follows:

•	properties for which there is a corresponding property in the property class are updated to match the property class setting

•	properties for which there is no corresponding property in the property class are left unchanged

•	When you remove properties from a property class or modify an object so that it is no longer based on a property class, any properties that the object was inheriting from the class revert to the default settings.

•	Property classes can only inherit from other property classes.

•	Property classes are similar to named visual attributes, but there are important differences you should be aware of:

•	Named visual attributes define only font, color, and pattern attributes; property classes can contain these and any other properties.

•	You can change the appearance of objects at runtime by changing the named visual attribute programmatically; property class assignment cannot be changed programmatically.

•	When an object is inheriting from both a property class and a named visual attribute, the named visual attribute settings take precedence, and any visual attribute properties in the class are ignored.


About modifying property classes

  Related Topics

Once an object is based on a property class, you can modify the definition of the object or its property class by doing any of the following:

•	Set the properties of the object as desired, overriding or inheriting properties as desired.

•	Add or remove properties from the property class.

•	Base the object on a different property class.

•	Disassociate the object from the property class by setting the Subclass Information property to <Null>.

Properties that inherit their value from a property class are displayed with an arrow symbol in front of the property name. Once an object is based on a class, you can override the setting of any inherited property to make that property variant. Variant properties and properties for which there is no corresponding property in the class are displayed normally, without the arrow symbol.


Creating a property class

  Next Step	    Related Topics

To create a property class in the Object Navigator:

1	In the Object Navigator, click the Property Classes node.

2	Click the Create button [image] in the toolbar.

A property class object with a default name is inserted under the node.


Viewing properties in a property class

  Related Topics

To view the definition of a property class:

1	In the Object Navigator, click the Property Classes node.

2	Double-click the desired property class object icon to see its properties.


Adding a property to a property class

To add a single property to a property class:

1	In the Object Navigator, click the Property Classes node.

2	Double-click the desired property class object icon to display the Property Palette.

3	Click the Add Property button on the Property Palette toolbar.

4	In the Add Property dialog:

Click the property you want to add to the property class.

Click OK.

5	In the Property Palette, set the new property as desired.

To copy properties into a property class:

Use the Copy Properties command to copy the properties of existing objects, then use the Paste Properties command to paste those properties and their settings to the property class.


Modifying a property class

  Related Topics

To modify a property in a property class:

1	In the Object Navigator, double-click the desired property class object icon.

2	In the Property Palette, modify the desired properties.


Removing a property from a property class

  Related Topics

To remove a property from a property class:

1	In the Object Navigator, click the Property Classes node.

2	Double-click the desired property class object icon.

3	In the Property Palette, click the property you want to remove to select it.

4	Click the Delete Property button on the Property Palette toolbar.


Basing an object on a property class

  Related Topics

To base an object on a property class:

1	In the Object Navigator, click the desired object.

2	Choose Tools [image] Property Palette.

3	Under the General node:

•	Double-click the Subclass Information property.

•	In the Subclass Information dialog, click Property Class.

•	In the Property Class Name field, select the desired property class.


Modifying an object that is based on a property class

  Related Topics

To modify an object that is based on a property class:

1	In the Object Navigator, click the desired object.

2	Modify the object as desired.

When you change the setting of an inherited property, the arrow in front of the property name is checked to show that the property is no longer inheriting its value from the underlying property class.


About defining triggers in property classes

  Related Topics

You can define a trigger in a property class when you want a form, block, or item that you base on the class to inherit the trigger. When an object based on a property class inherits a trigger, it executes the trigger in response to the triggering event, just as it would if you had attached the trigger to the object directly.

The new trigger appears under the Triggers node for the property class.

Once you have defined a trigger in a property class, any forms, blocks, or items you base on the class inherit the trigger. For example, if you define a When-Button-Pressed trigger in a property class, any form, block, or item of type button that you base on the property class inherits the When-Button-Pressed trigger. At runtime, these objects behave exactly as they would if you had attached the When-Button-Pressed trigger to each of them directly.

You can override property class trigger inheritance by attaching a trigger of the same type directly to the object that is inheriting a trigger. Thus, when you attach a When-Button-Pressed trigger to a button that is already inheriting a When-Button-Pressed trigger from its property class, the trigger attached to the button overrides the trigger the button is inheriting from the class.

When you define a trigger in a property class, the forms, blocks, and items that you base on the class inherit the trigger only if it is valid for that type of object. For example, if you base a text item  on a class that contains a When-Button-Pressed trigger, the trigger is ignored,  because When-Button-Pressed triggers are valid only for buttons. Similarly, a check box would not inherit a When-Timer-Expired trigger, because a When-Timer-Expired trigger is valid only for forms—not blocks or items.

Note: When you define a trigger in a property class, the trigger appears in the Object Navigator under the Triggers node for the class, but does not appear under the Triggers node for objects based on the class.


Defining a trigger in a property class

To define a trigger in a property class:

1	In the Object Navigator, click the Triggers node under the property class.

2	Click the Create button [image] in the toolbar.

3	In the dialog, select the desired trigger from the list of values.

The PL/SQL Editor appears, showing the trigger you selected.

4	Enter and compile the desired trigger code, then choose Close to dismiss the editor.


About visual attributes

  Related Topics

Visual attributes are the font, color, and pattern properties that you set for form and menu objects that appear in your application's interface.  Visual attributes can include the following properties:

•	Font properties:  Font Name, Font Size, Font Style, Font Width, Font Weight

•	Color and pattern properties:  Foreground Color, Background Color, Fill Pattern, Charmode Logical Attribute, White on Black

Every interface object has a Visual Attribute Group property that determines how the object's individual visual attribute settings (Font Size, Foreground Color, etc.) are derived. The Visual Attribute Group property can be set to Default, NULL, or the name of a named visual attribute defined in the same module.

There are several ways to set the visual attributes of objects:

•	In the Property Palette, set the Visual Attribute Group property as desired, then set the individual attributes (Font Name, Foreground Color, etc.) to the desired settings.

•	In the Layout Editor, select an item or a canvas and then choose the desired font, color, and pattern attributes from the Font dialog and Fill Color and Text Color palettes.

•	Define a named visual attribute object with the appropriate font, color, and pattern settings and then apply it to one or more objects in the same module. You can programmatically change an object's named visual attribute setting to change the font, color, and pattern of the object at runtime.

•	Subclass a visual attribute that includes visual attribute properties and then base objects on it that inherit those properties.

•	Create a property class that includes visual attribute properties and then base objects on it that inherit those properties.


About default visual attributes

Setting the Visual Attribute Group property to Default specifies that that the object should be displayed with default color, pattern, and font settings. When Visual Attribute Group is set to Default, the individual attribute settings reflect the current system defaults. The actual settings are determined by a combination of factors, including the type of object, the resource file in use, and the window manager.


About named visual attributes

  Related Topics

Setting the Visual Attribute Group property to a named visual attribute defined in the same module specifies that the object should use the attribute settings defined for the named visual attribute. A named visual attribute is a separate object in a form or menu module that defines a collection of visual attribute properties.  Once you create a named visual attribute, you can apply it to any object in the same module, much like styles in a word processing program.


Guidelines for creating visual attributes

  Related Topics

When you work with visual attributes, consider these guidelines:

•	When you apply a named visual attribute to an object, only those attributes that make sense for that object take effect.

•	If you plan to port your application to more than one platform, you should use named visual attribute settings.


Creating a named visual attribute

  Next Step	    Related Topics

To create a named visual attribute:

1	In the Object Navigator, click the Visual Attributes node.

2	Click the Create button [image] in the toolbar.

Form Builder inserts a new named visual attribute.

3	In the Property Palette, set the font, color, and pattern attributes of the named visual attribute as desired.


Basing an object on a visual attribute

To base an object on a visual attribute:

1	In the Object Navigator, double-click the desired object to display the Property Palette.

2	Under the Visual Attributes node, set the Visual Attribute Group property to the name of a named visual attribute.


Modifying a visual attribute

To modify a visual attribute:

1	In the Object Navigator, double-click the desired visual attributes object icon to display the Property Palette.

2	Under the Visual Attributes node, modify the desired properties.


About object groups

  Related Topics

An object group is a container for a group of objects. You define an object group when you want to package related objects so you can copy or subclass them in another module.

Object groups provide a way to bundle objects into higher-level building blocks that can be used in other parts of an application and in subsequent development projects.

For example, you might build an appointment scheduler in a form and then decide to make it available from other forms in your applications. The scheduler would probably be built from several types of objects, including a window and canvas, blocks, and items that display dates and appointments, and triggers that contain the logic for scheduling and other functionality. If you packaged these objects into an object group, you could then copy them to any number of other forms in one simple operation.

You can create object groups in form and menu modules. Once you create an object group, you can add and remove objects to it as desired.


Guidelines for creating object groups

  Related Topics

When working with object groups, consider these guidelines:

•	Dragging a block into an object group implicitly includes all objects that are owned by the block (items, triggers, relations). However, objects owned by the block do not appear under that block in the list of object group children.

•	Only top-level objects can be included in an object group.

Objects owned by blocks cannot be independently placed in an object group. This includes items, item-level triggers, block-level triggers, and relations. These objects cannot exist independently of the block in which they were defined. To include these objects in an object group, you must include the block itself by dragging the block object into the object group in the Object Navigator.

•	The objects in a group must all be defined in the same module; you cannot place objects from two different forms in the same object group.

•	An object group cannot contain another object group.

•	When an object in an object group is deleted from a module, it is removed from the object group automatically.

•	Deleting an object group from a module does not delete the objects it contains from the module.

•	Object groups do not store copies of the objects they contain, but rather pointers to the objects; defining object groups does not increase module size significantly (unless the object group is subclassed).


Creating an object group

  Related Topics

To create an object group:

1	In the Object Navigator, click the Object Groups node.

2	Click the Create button [image] in the toolbar.

An object group with a default name is inserted under the node. When you double-click to expand the object, the Object Group Children node appears. Objects you add to the group appear under this node.


Adding an object to an object group

  Related Topics

To add an object to an object group:

1	In the Object Navigator, click the + icon beside Object Groups node.

2	Drag the desired object to the Object Group Children node.


Modifying an object group

To modify an object group:

1	In the Object Navigator, double-click the desired object group object icon to display the Property Palette.

2	Modify the desired properties.


Removing an object from an object group

  Related Topics

To remove objects from an object group:

1	In the Object Navigator, click the object you want to remove.

2	Choose Navigator [image] Delete.

Note: Removing an object from an object group does not delete the object from the module.


About template forms

Any form can be used as a template form. Template forms allow you to provide other team members with a default starting point for creating forms.  They typically include generic objects such as graphics, text, images, toolbars, and program units, though they may include any object that can be used in a form. When you create a form based on a template form, Form Builder opens the template form and renames it, so that when you save the new form, you do not overwrite the template form.


Creating a form based on a template form

To create a form based on a template:

1	Choose File [image] New [image] Form Using Template.

2	In the Welcome dialog, click Build a Form Based on a Template to display the Open dialog.

3	Select a file (.FMX), then click Open.


Reusing code

  Related Topics

There are several ways to reuse code that you have written in Form Builder:

•	Copy triggers or program units between modules as you would any other type of object.

•	Subclass triggers or program units.

•	Create PL/SQL libraries of program units that can be called from any module to which the PL/SQL library is attached.

•	Subclass existing triggers in other modules.


About Forms Developer user interface standards

  Next Step	    Related Topics

Instead of developing your own user interface standards, you can create applications based on Forms Developer user interface standards.

Forms Developer includes two sets of user interface standards.

Generic Standards	Recommended for multiplatform deployments where multilanguage support is a requirement.
Win95 Standards	Recommended for Win95 only deployments where multilanguage support is not a requirement.
Forms Developer user interface standards are packaged within object libraries.  To use the standards, simply open an object library and drag the desired object from the Object Library to a node in the Object Navigator.   You can also subclass any object that exists within the Object Library.


Applying Win95 user interface standards to my items
Using the Forms Developer user interface standards for Win95

  Related Topics

I want to apply Win95 user interface standards to my...

•	button

•	check box

•	display item

•	list item

•	radio group

•	text item

•	text item with date format


Applying Win95 interface standards to a button

To create a standard button:

1	Choose File [image] Open.

2	In the Open dialog, double-click STNDRD20.OLB.

3	In the Object Navigator, click the desired item.

4	Click the right mouse button to display the popup menu.

5	Choose SmartClasses, then select the desired button SmartClass.

6	(Optional) In the Object Navigator, double-click the Stndrd20 object icon.

7	(Optional) In the Object Library, click the V_ATTRS tab and drag STD_TEXT_ITEM, STD_PROMPT, and STD_CURRENT_RECORD to the Visual Attributes node in the Object Navigator.


Applying Win95 interface standards to a check box

To create a standard check box:

1	Choose File [image] Open.

2	In the Open dialog, double-click STNDRD20.OLB.

3	In the Object Navigator, click the desired item.

4	Click the right mouse button to display the popup menu.

5	Choose SmartClasses, then select STD_CHECKBOX.

6	(Optional) In the Object Navigator, double-click the Stndrd20 object icon.

7	(Optional) In the Object Library, click the V_ATTRS tab and drag STD_TEXT_ITEM and STD_PROMPT to the Visual Attributes node in the Object Navigator.


Applying Win95 interface standards to a display item

To create a standard radio group:

1	Choose File [image] Open.

2	In the Open dialog, double-click STNDRD20.OLB.

3	In the Object Navigator, click the desired item.

4	Click the right mouse button to display the popup menu.

5	Choose SmartClasses, then select STD_TEXT_ITEM_DISPLAY.

6	(Optional) In the Object Navigator, double-click the Stndrd20 object icon.

7	(Optional) In the Object Library, click the V_ATTRS tab and drag STD_TEXT_ITEM, STD_PROMPT, and STD_CURRENT_RECORD to the Visual Attributes node in the Object Navigator.


Applying Win95 interface standards to a list item

To create a standard list item:

1	Choose File [image] Open.

2	In the Open dialog, double-click STNDRD20.OLB.

3	In the Object Navigator, click the desired item.

4	Click the right mouse button to display the popup menu.

5	Choose SmartClasses, then select STD_LIST_ITEM.

6	(Optional) In the Object Navigator, double-click the Stndrd20 object icon.

7	(Optional) In the Object Library, click the V_ATTRS tab and drag STD_TEXT_ITEM, STD_PROMPT, and STD_CURRENT_RECORD to the Visual Attributes node in the Object Navigator.


Applying Win95 interface standards to a radio group

To create a standard radio group:

1	Choose File [image] Open.

2	In the Open dialog, double-click STNDRD20.OLB.

3	In the Object Navigator, click the desired item.

4	Click the right mouse button to display the popup menu.

5	Choose SmartClasses, then select STD_RADIO_GROUP.

6	(Optional) In the Object Navigator, double-click the Stndrd20 object icon.

7	(Optional) In the Object Library, click the V_ATTRS tab and drag STD_TEXT_ITEM to the Visual Attributes node in the Object Navigator.


Applying Win95 interface standards to a text item

To create a standard text item:

1	Choose File [image] Open.

2	In the Open dialog, double-click STNDRD20.OLB.

3	In the Object Navigator, click the desired item.

4	Click the right mouse button to display the popup menu.

5	Choose SmartClasses, then select STD_TEXT_ITEM.

6	(Optional) In the Object Navigator, double-click the Stndrd20 object icon.

7	(Optional) In the Object Library, click the V_ATTRS tab and drag STD_TEXT_ITEM, STD_PROMPT, and STD_CURRENT_RECORD to the Visual Attributes node in the Object Navigator.


Applying a standard date format to a text item

To create a standard radio group:

1	Choose File [image] Open.

2	In the Open dialog, double-click STNDRD20.OLB.

3	In the Object Navigator, click the desired item.

4	Click the right mouse button to display the popup menu.

5	Choose SmartClasses, then select the desired date format.

6	(Optional) In the Object Navigator, double-click the Stndrd20 object icon.

7	(Optional) In the Object Library, click the V_ATTRS tab and drag STD_TEXT_ITEM, STD_PROMPT, and STD_CURRENT_RECORD to the Visual Attributes node in the Object Navigator.


About stored programs

  Related Topics

A stored procedure or stored function is a PL/SQL subprogram in the database that can be called by name from an application.  Form Builder supports drag and drop application partitioning by using stored PL/SQL subprograms.  Applications for deployment against the Oracle8 Server can include calls to server-side stored subprograms directly in the PL/SQL code of Form Builder triggers and user-named subprograms.  From within Form Builder triggers and user-named subprograms, you can execute procedures and functions defined in a PL/SQL package as well was as access any of the subprograms at either the local or remote database server.

Processing within the form is on hold until the stored procedure or function completes execution, so the network and database load must be considered with regard to response time.  The first time a user executes a stored procedure or function, the executable code is cached in the Oracle8 SGA—the shared global area. Because the code is cached, subsequent uses of the executable are faster. The first time any subprogram within a package is referenced, the entire package is loaded and becomes shareable.

Using a stored subprogram instead of a local Form Builder subprogram is recommended when a procedure or function provides standard functionality that other tools can share—such as validation and calculations.  Stored subprograms are also recommended when performing a significant number of DML operations that can be processed in a bundle by the server.


About default values for formal parameters

 Examples	     Related Topics

Default values for formal parameters are not supported.  However, you can create a stored package that contains:

•	overloaded procedure specification in the package spec

•	a private implementation using default parameters in the package body


About default values for formal parameters examples

/*

Create a stored procedure with zero, one, or two VARCHAR2 arguments.  The following 'Test' package procedure can be invoked by any of the following:
  test.test;
  test.test('Hi');
  test.test('Hi','There');
*/
CREATE PACKAGE Test IS
PROCEDURE Test;
PROCEDURE Test(a VARCHAR2 );
PROCEDURE Test(a VARCHAR2,
               b VARCHAR2);
END Test;

CREATE PACKAGE BODY Test IS
   PROCEDURE Private_Test( a in VARCHAR2 := 'Hello'
       b in VARCHAR2 := 'There')  IS

   BEGIN
      Dbms_Output.Put_Line(a);
      Dbms_Output.Put_Line(b);
   END;

   PROCEDURE Test IS
   BEGIN
      Private_Test;
   END;

   PROCEDURE Test(a VARCHAR2) IS
   BEGIN
      Private_Test (a);
   END;

   PROCEDURE Test(a VARCHAR2 , b VARCHAR2) IS
   BEGIN
      Private_Test (a, b);
   END;

END Test;


About accessing subprograms in another user's schema

 Examples	     Related Topics

To access a subprogram in another user's schema or one in a remote database, you must create a synonym to hide the username or Db_Link name from the PL/SQL compiler such that the result takes the form:

•	ProcSynonym(arg1,...,argN)

•	FuncSynonym(arg1,...,argN)

•	PackSynonym.ProcName(arg1,...,argN)

•	PackSynonym.FuncName(arg1,...,argN)

You can create synonyms to nickname remote stored programs, hiding the username or Db_Link:

•	Subprogram@DbLink

•	Package@DbLink

•	Package.Subprogram@DbLink

•	Schema.Subprogram@DbLink

•	Schema.Package

•	Schema.Package@DbLink

•	Schema.Package.Subprogram@DbLink

Where subprogram is either a procedure or a function.


About accessing subprograms in another user's schema examples

To call the package function 'LIBOWNER.LIB_HR.GET_SSN', you could create a synonym for the LIB_HR package that includes the schema name (the owner name) as follows:

CREATE SYNONYM lib_hr_syn
FOR libowner.lib_hr;

Then invoke the function from within your form as follows:

ss_num := lib_hr_syn.get_ssn(:Emp.Empno);

If the package function is at a remote site accessible through a database link named basel,  for example, then you could create a synonym for the package, including the database link name:

CREATE SYNONYM basel_lib_hr_syn
FOR libowner.lib_hr@basel;

and invoke the function within your PL/SQL code as:

ss_num := basel_lib_hr_syn.get_ssn(:Emp.Empno);

Alternately, you could create a synonym for the function itself, hiding both the schema and Db_Link information:

CREATE SYNONYM basel_lib_hr_get_ssn_syn
FOR libowner.lib_hr.get_ssn@basel;

and invoke the function from Form Builder as:

ss_num := basel_lib_hr_get_ssn_syn(:Emp.Empno);

Of course, any of the synonyms above could have been created as PUBLIC SYNONYMS if appropriate.


About resolving subprogram names

  Related Topics

When a form is compiled, the PL/SQL compliler may encounter the name of an identifier that could be a procedure or function.  The PL/SQL complier users a precedence mechanism to resolve ambiguities.

If an identifier such as PROCNAME is encountered that has the structure of a procedure or function, the compiler will use the first match found in the following search order:

1	Is it defined within the current PL/SQL block?

2	Is it a standard PL/SQL command?

3	Is it an Form Builder built-in subprogram procedure or function?

4	Is it a user-named procedure or function?

5	Is it defined in package DBMS_STANDARD on the serverside?

6	Does the current user have access to any such procedure or function on the server side?

If the answer is "no" to all of the above, then the compiler signals an error:

PL/SQL error 313 at line xxx, column yyy
'PROCNAME' not declared in this scope
or
PL/SQL error 201 at line xxx, column yyy
identifier 'FUNCTNAME' must be declared.


About stored procedure privileges

  Related Topics

You can create, edit, compile, and browse stored procedures directly from Form Builder if you have the appropriate privileges.

Execute Privilege	Allows the user to execute the public subprogram defined in a stored program unit.  Public subprograms are listed in the package specification.
Create Privilege	Allows the user to create, modify, and compile stored program units.
Compile Privilege	Allows the user to compile a stored program unit.
Drop Privilege	Allows the user to drop a stored program unit.


About the stored program unit editor

  Related Topics

You can create, edit, and compile the source text for stored procedures from the Stored Program Unit Editor.

Title	The title reflects the schema and name of the currently displayed stored program unit.
New	The New button allows the user to enter the source text for a new program unit.  A new program unit is only visible within the Stored Program Unit Editor.  New program units are not stored in the database until the first compile operation.
Save	The Save button synchronizes the source text displayed in the editor with the source text stored in the database and compiles the stored program unit on the server-side.
Revert	The Revert button discards any changes made in the source text pane and restores the stored program unit to its previous state.  The restored state is the most recent of the following: • after the last navigation to this stored program unit or its creation with the New button • after the last selection of the Compile button The Revert button is only enabled when there have been changes to the source text pane since one of the above states.
Drop	The Drop button drops an existing stored program unit or aborts the creation of a new one (after seeking confirmation via an alert). After dropping the stored program unit, the editor displays the preceding stored program unit in the Name combo box if one exists; otherwise, it displays the next stored program unit.  If there are no stored program units for the current owner, the editor is empty. The Drop button is enabled only if the stored program unit is new or the current user has drop privileges for the currently displayed stored program unit.
Close	The Close button closes the Stored Program Unit Editor window.  If the source text of the currently displayed stored program unit has been modified, the editor presents an Unsaved Changes alert.
Owner Combo Box	The Owner combo box identifies the user who owns the stored program unit currently displayed in the editor. Selecting a new entry in the Owner combo box updates the Name combo box and displays the first stored program unit in the Name list (if one exists).
Name Combo Box	The Name combo box displays the name of the currently selected stored program unit. The Name combo box contains the names of all accessible stored program units owned by the user currently selected in the Owner combo box.  A program unit is accessible if the current user has execute privileges on it. Selecting a new entry in the Name combo box updates the editor to display the newly selected stored program unit.  If the source text of the current stored program unit has been modified, the editor presents an Unsaved Changes alert.
Source Text Pane	The source text pane displays the source text of the current stored program unit.  It is editable only if the current user has create privileges for the stored program unit; otherwise, it is read-only.
Compilation Message Pane	The Compilation Message pane displays any compilation messages associated  with the current stored program unit. Clicking on a compilation message moves the text cursor in the source pane to the line and column associated with the message. The Compilation Message pane is hidden when the current stored program unit has no associated error messages.
Status Bar	The Status Bar displays information about the state of the current stored program unit.


Creating a stored program

  Related Topics

To create a stored program:

1	In the Object Navigator, expand the Database Objects node to display the schema nodes.

2	Expand a schema node to display the database objects.

3	Select the Stored Program Units node and choose Navigator [image] Create.

The New Program Unit dialog appears.

4	Specify the program unit name and type of program unit.  The type of a program unit can be either procedure, function, package spec or package body.

The Stored Program Unit Editor appears.

5	In the Stored Program Unit Editor, define and save the desired program units.

Note: When you compile a form, menu, or library containing references to stored procedures, functions, or packages, ensure that the stored subprogram to which you make reference exists on the server during compilation.


Modifying a stored program

  Related Topics

To modify a stored program:

1	In the Object Navigator, expand the Database Objects node to display the schema nodes.

2	Expand a schema node to display the database objects.

3	Expand the Stored Program Units node.

Stored procedures that you either own or have privileges to execute, compile, or drop appear.

4	Double-click on the desired stored procedure icon.

The Stored Program Unit Editor is displayed.

5	Modify the stored procedure as desired and click Save.


Invoking a stored program

 Examples	   Restrictions	    Related Topics

Invoking a server-side stored procedure or function within Form Builder is the identical to calling a local client-side procedure or function.

A server-side stored procedure is a PL/SQL block designed to be executed by the server-side PL/SQL engine.  It may accept inputs, and may return outputs, neither of which is mandatory.

The server-side stored procedure runs under the security domain (or schema) of the creator of the procedure, not the current user.  The current user needs EXECUTE privileges on the procedure to use it.

One important difference between procedures for Form Builder and procedures for the database is that server-side procedures do not understand references to Form Builder bind variables (such as :BLOCK.ITEMNAME, :GLOBAL.VARNAME, or :SYSTEM.CURSOR_ITEM).  Any data that procedures need for processing must be passed by way of parameters of appropriate datatype, by package variables, or by selecting from tables.

You should structure your Form Builder user-named routines to accept inputs and return results in parameters. This will make the eventual migration of the procedure into the database as painless as adding the word CREATE in front of the PROCEDURE declaration (in addition to running the resulting script in SQL*PLUS).

When invoking a stored procedure or function, only the following subset of possible usages is supported:

•	ProcName(arg1,...,argN)

•	FuncName(arg1,...,argN)

•	PackName.ProcName(arg1,...,argN)

•	PackName.FuncName(arg1,...,argN)


Invoking a stored program examples

DECLARE

   ld DATE;
   ln NUMBER;
   lv VARCHAR2(30);
BEGIN
/*
** Calling Form-Level Procedure/Function
*/
   forms_procedure_name(ld,ln,lv);
   ld := forms_function_name(ln,lv);

/*
** Calling Database Procedure/Function
*/
   database_procedure_name(ld,ln,lv);
   ld := database_function_name(ln,lv);
END;


Invoking a stored program restrictions

•	Since Form Builder creates the access routine for each stored subprogram to which your trigger or user-named subprogram refers, it is not possible to write a form containing calls to stored procedures or functions that will be compiled against both Oracle Version 6.0 and Version 7.0.  Once a form includes a reference to at least one stored subprogram, then it must be compiled against a Version 7.0 database, otherwise compilation errors result when the names of stored subprograms cannot be resolved by the PL/SQL compiler.

•	Calling stored procedures and functions is not supported from a menu PL/SQL context.

•	Changes made to stored subprogram definitions may not be usable by the form developer until after re-establishing a connection to the server.


About database triggers

  Related Topics

A database trigger is nearly identical in concept to the Form Builder trigger. The difference lies in the event that causes the trigger to fire and the location where the subsequent code is performed.

Database triggers are PL/SQL blocks that are associated with a given table; they fire upon the execution of UPDATE, INSERT, or DELETE operations against that table. They may fire BEFORE or AFTER each row the operation affects, or each statement.  The combinations give a maximum possibility of twelve triggers for any table.  While a trigger executes, it runs under the security domain (schema) of its creator, not the current user.

Within the body of the database trigger, your PL/SQL code may refer to both the old and the new values of the columns being affected.  For an INSERT, the old values are non-existent, while for a DELETE, the new values do not exist.  This makes data validation simple to implement, and auditing changed values extremely easy.

A database trigger can perform complex data verification that could not be feasibly declared as a constraint. If a database trigger fails with an error, the triggering statement (i.e., the INSERT, UPDATE, or DELETE that fired the trigger) is rolled back.

In a simple example, you could write the following trigger to prevent updates on the EMP table during weekends, unless the current user exists in a special WEEKEND_UPDATE_OK table, in which case the update is allowed.

CREATE OR REPLACE TRIGGER update_on_weekends_check

  BEFORE UPDATE OF sal ON EMP

  FOR EACH ROW

DECLARE

  my_count number(4);

BEGIN

  SELECT COUNT(u_name) FROM WEEKEND_UPDATE_OK INTO my_count

    WHERE u_name = user_name;

  IF my_count=0 THEN

    RAISE_APPLICATION_ERROR(20508, 'Update not allowed');

  END IF;

END;

Besides providing arbitrarily complex data validation, database triggers can also be used to perform any cause-and-effect sequence.  This makes database triggers particularly well suited for data auditing operations, data replication, and distributed data integrity checking (since constraints cannot reference remote databases).  If database triggers are written to supplant forms-side triggers (e.g. for table auditing) then the forms-side functionality will have to be disabled to avoid duplicating table operations.

One alternative is to use a package variable as a flag to communicate between the form and the database-side triggers (or procedures). In that manner, a decision can be made within the trigger or procedure on whether a particular operation might have already been performed by the Form Builder code.

Triggers (as well as stored procedures and functions) raise errors with the RAISE_APPLICATION_ERROR procedure.  The RAISE_APPLICATION_ERROR procedure assigns an error number within the special range 20000-20999 and provides an error message.  Since it is your PL/SQL database trigger that prepares the error message, the message can vary.  Within the Form Builder application, these errors can be trapped with the methods mentioned in the next section.


About database trigger processing

  Related Topics

Recall that database triggers fire in response to a DML statement such as INSERT, UPDATE, or DELETE.  So during normal Form Builder commit-time processing, as Form Builder issues INSERT statements to add newly entered records to the database, UPDATE statements to effect changes by the operator to existing records, and DELETE statements to remove records deleted by the operator from the database; database triggers will fire if enabled.

For example, consider the scenario where the following database triggers have been defined and enabled on the EMP table:

•	BEFORE DELETE

•	BEFORE DELETE FOR EACH ROW

•	AFTER DELETE

•	AFTER DELETE FOR EACH ROW

When the operator deletes a record that has been queried, the following sequence of events occurs:

1	Form Builder locks the record to be deleted.

2	Operator presses [Commit].

3	Form Builder fires the PRE-COMMIT trigger.

4	Form Builder fires the PRE-DELETE trigger.

5	Form Builder issues a DELETE statement to delete the row.

6	The database fires the BEFORE DELETE trigger.

7	The database fires the BEFORE DELETE FOR EACH ROW trigger.

8	The database deletes the record.

9	The database fires the AFTER DELETE FOR EACH ROW trigger.

10	The Database AFTER DELETE trigger fires.

11	Form Builder fires the POST-DELETE trigger.

12	Form Builder fires the POST-COMMIT trigger.

Recall that any error raised during Commit processing causes Form Builder to roll back the currently committing transaction to the savepoint that was issued when the Commit sequence began.  If any Database trigger fails (by raising an unhandled error or calling a  RAISE_APPLICATION_ERROR) as a result of a DML statement that Form Builder has issued automatically, then an "Oracle Error Occurred ..." message will appear. An error raised as a result of a DML statement in your PL/SQL trigger, on the other hand, can be handled gracefully.  If not handled, the error will produce the message: "XXX-YYYYYY trigger raised unhandled exception."


About declarative database constraints

  Related Topics

A database constraint is a rule that governs the logical integrity of your data. The rule is declared at table creation time, or can be added (with some restrictions) after the fact to an existing table.

Entity constraints Entity constraints can declaratively enforce a column (or ordered group of columns) to be NOT NULL, UNIQUE within the table, have a DEFAULT value if none is specified on INSERT, and/or satisfy a more complex logical condition given in a CHECK clause. These constraints provide intra-table integrity.

Referential constraints Referential constraints provide the logical link between a master and a detail table by establishing primary and foreign key relationships. Database constraints protect your data by automatically enforcing at the database level the rules you have declared.  If you create a record in a master table and one detail record, for example, the default operation of database constraints restricts updating of the primary key of the master record.  Default database constraints also prevent deleting of the master record (unless the ON DELETE CASCADE option is used when declaring all of the foreign key references).

Strategies for Constraint Checking Prior to Oracle7 Server, nearly all data integrity was provided at the application level--for form bulider, through triggers. The goal of application-side logic is to stop bad data before it happens.

The Oracle8 ability to perform implicit data verification at the kernel level means that current systems that had been coded to guarantee data integrity by the application will in essence be checking the same things twice.  To optimize, you might be tempted to strip out all application logic and leave all constraint checking to the database. However, you should weigh the benefits that constraints on both sides provide and determine if checking things twice is too costly.

Database constraints provide the ability to centrally protect the integrity of the data without necessarily coding the logic into each one of the tools. However, the reason that logic was coded into the application in the first place was to give the user immediate feedback on errors, facilitating their rapid correction with online help and appropriate error messages.

No user would appreciate entering a batch of fifty new orders, only to attempt to execute a commit and learn from ORACLE that the fourth order violated an integrity constraint.

You will most likely prefer to check the data both at data entry time and at commit time, recognizing that the small overhead of checking is well worth the additional security it provides. Database Constraints checking is more efficient than its application-based counterpart since constraints are processed intelligently by the kernel, completely within the realm (and RAM) of the kernel, and without additional network trips back to the client.

Note that if a column has been declared to have a DEFAULT value, the kernel will assign the DEFAULT value only when the record is INSERTed, provided that the given column is not listed among the columns in the INSERT clause.  Because Form Builder always lists ALL of the columns (i.e., database fields) in a block for INSERTS and UPDATES, the DEFAULT will never automatically be assigned unless the user either removes the field in question from the block (or marks it as non-database), or else codes an ON-INSERT trigger to override the normal Form Builder insert processing.

Also, be aware that some forms-based operations may become unnecessary when constraints are enabled. For example, deleting detail records when a corresponding master is removed, is internally handled by the kernel if the ON DELETE CASCADE option is specified for the parent-child foreign key relationship.

Master/Detail Blocks and Referential Integrity Applications that include master-detail blocks coordinated via the automatically generated triggers and procedures in SQL*Forms 3.0 should require no modification when running against tables with Declarative Referential Integrity constraints enabled.  Form Builder default logic will prevent the deletion of a master record when outstanding detail records exist, unless the design specified the Cascading Deletes option when creating the detail block. In that case, Form Builder uses a PRE-DELETE trigger to first delete the detail records, then deletes the master.

The order of operations was not critical running under ORACLE Version 6, but an application that had moved the standard PRE-DELETE logic to the POST-DELETE trigger instead would encounter problems running against Oracle8 Server when Primary/Foreign-Key relationships have been declared and enabled on the server-side.

Waiting until the POST-DELETE trigger to delete the detail records will cause Form Builder to issue the DELETE statement for the master record while detail records remain, and an error will be generated by the kernel:

ORA-02292: violated integrity constraint (OWNER.CONSTRAINT)
-- detail record found

However, if the foreign key relationship is specified with the ON DELETE CASCADE option, then no problem will arise, and the Form Builder POST-DELETE trigger will be needlessly performing an extra DELETE statement to remove the detail records that the Cascade Delete of the master already deleted.

So potentially any INSERT, UPDATE, or DELETE in your applications could generate an error caused by violating an enabled constraint.


About database trigger privileges

  Related Topics

You can create, edit, compile, and browse database triggers directly from Form Builder if you have the appropriate privileges.

Execute Privilege	Allows the user to execute the database trigger.
Create Privilege	Allows the user to create, modify, and compile database triggers.
Compile Privilege	Allows the user to compile a database trigger.
Drop Privilege	Allows the user to drop a database trigger.


About the database trigger editor

  Related Topics

Table Owner Combo Box	The Table Owner combo box identifies the user who owns the database trigger currently displayed in the editor.
	Selecting a new entry in the Table Owner combo box updates the Table combo box and displays the first database trigger in the Name list (if one exists).
Table Combo Box	The Table combo box displays the tables owned by the current user.
Name Combo Box	The Name combo box displays the name of the currently selected database trigger.
	The Name combo box contains the names of all accessible database triggers owned by the user currently selected in the Owner combo box.  A database trigger is accessible if the current user has execute privileges on it.
	Selecting a new entry in the Name combo box updates the editor to display the newly selected database trigger.  If the source text of the current database trigger has been modified, the editor presents an Unsaved Changes alert.
Triggering	When defining a database trigger, you can specify the trigger timing, that is, you can specify when the trigger action is to be executed in relation to the triggering statement: before or after the triggering statement.
Statement	A triggering event or statement is the SQL statement that causes a trigger to be fired.  A triggering event can be an INSERT, UPDATE, or DELETE statement for a specific table.
For Each Row	When you create a database trigger, you can specify a trigger restriction.  A trigger restriction is an option available for triggers that are fired for each row.  Its function is to conditionally control the execution of a trigger.  A trigger restriction is specified using a WHEN clause.
Trigger Body	Allows you to specify the PL/SQL code to be used as the body of the database trigger.
New	Creates a new code object of the same type and scope as the current code object. For example, when the current object is a trigger attached to an item, choosing New displays the Triggers LOV that allows you to create a new trigger attached to the same item. When the current object is a program unit, choosing New invokes the New Program Unit dialog.
Save	Compiles and saves the code in the Source Code field. The compiler detects syntax errors, semantic errors, and references to non-existent objects, procedures, and functions.  When you compile successfully, the status line displays the message <Successfully Compiled>.
Revert	Undoes any changes that were made to the source code since the editor was invoked or since the last Apply or Revert command.  Revert is disabled when there are no unapplied changes.
Drop	The Drop command drops an existing database trigger or aborts the creation of a new one (after seeking confirmation via an alert).
	After dropping the database trigger, the editor displays the preceding database trigger in the Name combo box if one exists; otherwise, it displays the next database trigger.  If there are no database triggers for the current owner, the editor is empty.
	The Drop button is enabled only if the database trigger is new or the current user has drop privileges for the currently displayed database trigger.
Close	Closes the Database Trigger Editor.
Clicking a  compilation message	Moves the insertion point to the line at which an error was detected in the Source Code field.


Creating a database trigger

 Examples	     Related Topics

To create a database trigger:

1	In the Object Navigator, expand the Database Objects node to display the schema nodes.

2	Expand a schema node to display the database objects.

3	Expand the Tables node to display the schema's database tables.

4	Select and expand the desired table.

5	Select the Triggers node and choose Navigator [image] Create.

The Database Trigger Editor appears.

6	In the Database Trigger Editor, define and save the desired program units.


Creating a database trigger examples

CREATE TRIGGER no_weekend_updates

BEFORE UPDATE
   ON EMP
DECLARE
   day_of_week NUMBER(2) := TO_NUMBER(TO_CHAR(SYSDATE,'D'));
   dummy CHAR(1);
BEGIN
   IF (day_of_week in (1,7))  /* Sunday,Saturday */
   THEN
      BEGIN
         SELECT 'X'/* Check Exceptions Table */
                   INTO dummy
                   FROM WEEKEND_UPDATE_OK
         WHERE USERID = USER;
      EXCEPTION
         WHEN NO_DATA_FOUND THEN /*Not Exception*/
                  RAISE_APPLICATION_ERROR(-20011,
                      'Try again on Monday!');
      END;
   END IF;
END;


Modifying a database trigger

  Related Topics

To modify a database trigger:

1	In the Object Navigator, expand the Database Objects node to display the schema nodes.

2	Expand a schema node to display the database objects.

3	Expand the Tables node to display the schema's database tables.

4	Select and expand the desired table.

5	Expand the Triggers node.

Database triggers that you either own or have privileges to execute, compile, or drop appear.

6	Double-click on the desired database trigger icon.

The Database Trigger Editor is displayed.

7	Modify the database trigger as desired and click Save.


About system variables

 Examples

A system variable is an Form Builder variable that keeps track of an internal Form Builder state.  You can reference the value of a system variable to control the way an application behaves.

Form Builder maintains the values of system variables on a per form basis.  That is, the values of all system variables correspond only to the current form.  The names of the available system variables are:

•	SYSTEM.BLOCK_STATUS

•	SYSTEM.COORDINATION_OPERATION

•	SYSTEM.CURRENT_BLOCK

•	SYSTEM.CURRENT_DATETIME

•	SYSTEM.CURRENT_FORM

•	SYSTEM.CURRENT_ITEM

•	SYSTEM.CURRENT_VALUE

•	SYSTEM.CURSOR_BLOCK

•	SYSTEM.CURSOR_ITEM

•	SYSTEM.CURSOR_RECORD

•	SYSTEM.CURSOR_VALUE

•	SYSTEM.CUSTOM_ITEM_EVENT

•	SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS

•	SYSTEM.DATE_THRESHOLD*

•	SYSTEM.EFFECTIVE_DATE*

•	SYSTEM.EVENT_WINDOW

•	SYSTEM.FORM_STATUS

•	SYSTEM.LAST_QUERY

•	SYSTEM.LAST_RECORD

•	SYSTEM.MASTER_BLOCK

•	SYSTEM.MESSAGE_LEVEL*

•	SYSTEM.MODE

•	SYSTEM.MOUSE_BUTTON_PRESSED

•	SYSTEM.MOUSE_BUTTON_SHIFT_STATE

•	SYSTEM.MOUSE_ITEM

•	SYSTEM.MOUSE_CANVAS

•	SYSTEM.MOUSE_X_POS

•	SYSTEM.MOUSE_Y_POS

•	SYSTEM.MOUSE_RECORD

•	SYSTEM.MOUSE_RECORD_OFFSET

•	SYSTEM.RECORD_STATUS

•	SYSTEM.SUPPRESS_WORKING*

•	SYSTEM.TAB_NEW_PAGE

•	SYSTEM.TAB_PREVIOUS_PAGE

•	SYSTEM.TRIGGER_BLOCK

•	SYSTEM.TRIGGER_ITEM

•	SYSTEM.TRIGGER_RECORD

All system variables, except the four indicated with an asterisk (*), are read-only variables.  These four variables are the only system variables to which you can explicitly assign values.  Form Builder also supplies 6 default values for date and time.  (See Date and Time System Default Values).

Local Variables

Because system variables are derived, if the value is not expected to change over the life of the trigger, you can save the system value in a local variable and use the local variable multiple times instead of getting the system variable value each time.


Date and Time System Default Values

Form Builder supplies six special default values $$DATE$$, $$DATETIME$$, $$TIME$$, $$DBDATE$$, $$DBDATETIME$$, and $$DBTIME$$ that supply date and time information. These variables have the  and the following special restrictions on their use:

•	For client/server applications, consider the performance implications of going across the network to get date and time information.

•	When accessing a non-ORACLE datasource, avoid using  $$DBDATE$$ and $$DBDATETIME$$.  Instead, use a When-Create-Record trigger to select the current date in a datasource-specific manner.

•	Use $$DATE$$, $$DATETIME$$, and $$TIME$$ to obtain the local system date/time; use $$DBDATE$$, $$DBDATETIME$$, and $$DBTIME$$ to obtain the database date/time, which may differ from the local system date/time when, for example, connecting to a remote database in a different time zone.

•	Use these variables only to set the value of the Initial Value, Highest Allowed Value or Lowest Allowed Value property.


About system variables examples

Assume that you want to create a Key-NXTBLK trigger at the form level that navigates depending on what the current block is.  The following trigger performs this function, using :SYSTEM.CURSOR_BLOCK stored in a local variable.

DECLARE
   curblk VARCHAR2(30);
BEGIN
   curblk := :System.Cursor_Block;
   IF curblk = 'Orders'
      THEN Go_Block('Items');
   ELSIF curblk = 'Items'
      THEN Go_Block('Customers');
   ELSIF curblk = 'Customers'
      THEN Go_Block('Orders');
   END IF;
END;

Uppercase Return Values

All system variables are case-sensitive, and most return their arguments as uppercase values. This will affect the way you compare results in IF statements.


$$DATE$$ system variable

 Examples

Syntax

$$DATE$$

Description

$$DATE$$ retrieves the current operating system date (client-side).  Use $$DATE$$ to designate a default value or range for a text item using the Initial Value or Lowest/Highest Allowed Value properties.  The text item must be of the CHAR, DATE, or DATETIME data type.

Use $$DATE$$ as a default value for form parameters.  In this case, the parameter's value is computed once, at form startup.

Usage Notes

The difference between $$DATE$$ and $$DATETIME$$ is that the time component for $$DATE$$ is always fixed to 00:00:00, compared to $$DATETIME$$, which includes a meaningful time component, such as 09:17:59.

The display of system variables is governed by the format mask, either a default data type format mask or one you specify.  For example, to use the default DD-MON-YY format, specify a DATE data type.  (Note that the default format mask depends on the value of NLS_LANG.)

Although $$DATE$$ displays only the date, its underlying value includes a time component which is saved at commit time.  If you specify a DATETIME data type and provide $$DATE$$ as the default, the underlying value will be DD-MON-YYYY HH:MM:SS: for example, 01-DEC-1994 00:00:00 (although only 01-DEC-1994 will be displayed).

Use $$DATE$$ when you want to compare the contents of this field with a field whose format mask does not have a time component, such as a SHIPDATE field of data type DATE.  In this case, both $$DATE$$ and SHIPDATE will have a time component of 00:00:00, so the comparison of two dates evaluating to the same day will be successful.


$$DATE$$ examples

Example 1

Assume that you want the value of a DATE text item, called ORDERDATE, to default to the current date.  When you define the ORDERDATE text item, specify $$DATE$$ in the text item Initial Value property.

Example 2

If you use $$DATE$$ in a parameter, such as :PARAMETER.STARTUP_DATE, then every time you reference that parameter, the date you started the application will be available:

IF :PARAMETER.Startup_Date + 1 < :System.Current_Datetime
   THEN Message ('You have been logged on for more than a day.');
ELSE Message ('You just logged on today.');
END IF;


$$DATETIME$$ system variable

 Examples

Syntax

$$DATETIME$$

Description

$$DATETIME$$ retrieves the current operating system date and time.  You can use $$DATETIME$$ to designate a default value or range for a text item using the Initial Value or Lowest/Highest Allowed Value properties.  The text item must be of the CHAR or DATETIME data type.

Use $$DATETIME$$ as a default value for form parameters.  In this case, the parameter's value is computed once, at form startup.

Usage Notes

The display of system variables is governed by the format mask, either a default data type format mask or one you specify. For example, if you want the default DD-MON-YY HH:MM:SS format, you must specify a DATETIME data type. (Note that the default format mask depends on the value of NLS_LANG.)

The difference between $$DATE$$ and $$DATETIME$$ is that the time component for $$DATE$$ is always fixed to 00:00:00, compared to $$DATETIME$$, which includes a meaningful time component, such as 09:17:59.

Note:  Do not use $$DATETIME$$ instead of $$DATE$$ unless to specify the time component.  If, for example, you use $$DATETIME$$ with the default DATE format mask of DD-MON-YY, you would be committing values to the database that the user would not see, because the format mask does not include a time component.  Then, because you had committed specific time information, when you later queried on date, the values would not match and you would not return any rows.


$$DATETIME$$ examples

Assume that you want the value of a DATETIME text item, called ORDERDATE, to default to the current operating system date and time.  When you define the ORDERDATE text item, specify $$DATETIME$$ in the Initial Value property.


$$DBDATE$$ system variable

 Examples 	   Restrictions

Syntax

$$DBDATE$$

Description

$$DBDATE$$ retrieves the current database date.  Use $$DBDATE$$ to designate a default value or range for a text item using the Initial Value or Lowest/Highest Allowed Value properties.  The text item must be of the CHAR, DATE, or DATETIME data type.

Usage Notes

The difference between $$DBDATE$$ and $$DBDATETIME$$ is that the time component for $$DBDATE$$ is always fixed to 00:00:00, compared to $$DBDATETIME$$, which includes a meaningful time component, such as 09:17:59.

Use $$DBDATE$$ to default a DATE item to the current date on the server machine, for example, when connecting to a remote database that may be in a different time zone from the client's time zone.

The display of system variables is governed by the format mask, either a default data type format mask or one you specify. For example, if you want the default DD-MON-YY format, you must specify a DATE data type.  (Note that the default format mask depends on the value of NLS_LANG.)

Although $$DBDATE$$ displays only the date, its underlying value includes a time component which is saved at commit time.  If you specify a DATETIME data type and provide $$DBDATE$$ as the default, the underlying value will be DD-MON-YYYY HH:MM:SS:  for example, 01-DEC-1994 00:00:00 (although only 01-DEC-1994 will be displayed).


$$ DBDATE$$ restrictions

•	If you are accessing a non-ORACLE datasource, avoid using $$DBDATE$$.  Instead, use a When-Create-Record trigger to select the current date in a datasource-specific manner.


$$ DBDATE$$ examples

To have the value of a DATE text item called ORDERDATE default to the current database date, for the ORDERDATE text item, specify $$DBDATE$$ in the Initial Value property.


$$DBDATETIME$$ system variable

 Examples 	   Restrictions

Syntax

$$DBDATETIME$$

Description

$$DBDATETIME$$ retrieves the current date and time from the local database.  Use $$DBDATETIME$$ to designate a default value or range for a text item using the Initial Value or Lowest/Highest Allowed Value properties.  The text item must be of the CHAR or DATETIME data type.

Usage Notes

Use $$DBDATETIME$$ to default a DATE item to the current date on the server machine, for example, when connecting to a remote database that may be in a different time zone from the client's time zone.

The display of system variables is governed by the format mask, either a default data type format mask or one you specify. For example, if you want a DD-MON-YY HH:MM:SS format, you must specify a DATETIME or CHAR data type.  (Note that the default format mask depends on the value of NLS_LANG.)

If you are building a client/server application, using $$DBDATETIME$$ could have performance implications, depending on the complexity of your network configuration.

Note:  Do not use $$DBDATETIME$$ instead of $$DBDATE$$ unless you plan to specify the time component.  If, for example, you use $$DBDATETIME$$ with the default DATE format mask of DD-MON-YY, you would be committing values to the database that the user would not see, because the format mask does not include a time component.  Then, because you had committed specific time information, when you later queried on date, the values would not match and you would not return any rows.


$$DBDATETIME$$ restrictions

If you are accessing a non-ORACLE datasource, avoid using $$DBDATETIME$$.  Instead, use a When-Create-Record trigger to select the current date and time in a datasource-specific manner.


$$DBDATETIME$$ examples

Assume that you want the value of a DATETIME text item, called ORDERDATE, to default to the current database date and time.  When you define the ORDERDATE text item, specify $$DBDATETIME$$ in the Lowest/Highest Allowed Value properties.


$$DBTIME$$ system variable

 Examples 	   Restrictions

Syntax

$$DBTIME$$

Description

$$DBTIME$$ retrieves the current time from the local database.  Use $$DBTIME$$ to designate a default value or range for a text item using the Initial Value or Lowest/Highest Allowed Value properties.  The text item must be of the CHAR or TIME data type.

Usage Notes

Use $$DBTIME$$ when connecting to a remote database that may be in a different time zone from the client's time zone.

The display of system variables is governed by the format mask, either a default data type format mask or one you specify. For example, if you want the default HH:MM:SS format, you must specify a TIME data type.  (Note that the default format mask depends on the value of NLS_LANG.)

If you are building a client/server application, using $$DBTIME$$ could have performance implications, depending on the complexity of your network configuration.


$$DBTIME$$ restrictions

If you are accessing a non-ORACLE datasource, avoid using $$DBTIME$$.  Instead, use a When-Create-Record trigger to select the current time in a datasource-specific manner.


$$DBTIME$$ examples

Assume that you want the value of a TIME text item, called ORDERTIME, to default to the current database time.  When you define the ORDERTIME text item, specify $$DBTIME$$ in the Initial Value property.


$$TIME$$ system variable

 Examples

Syntax

$$TIME$$

Description

$$TIME$$ retrieves the current operating system time.  Use $$TIME$$ to designate a default value or range for a text item using the Initial Value or Lowest/Highest Allowed Value properties.  The text item must be of the CHAR or TIME data type.

You also can use $$TIME$$ as a default value for form parameters.  In this case, the parameter's value is computed once, at form startup.

Usage Notes

The display of system variables is governed by the format mask, either a default data type format mask or one you specify. For example, if you want the default HH:MM:SS format, you must specify a TIME data type. (Note that the default format mask depends on the value of NLS_LANG.)


$$TIME$$ examples

Assume that you want the value of a TIME text item, called ORDERTIME, to default to the current operating system time.  When you define the ORDERTIME item, specify $$TIME$$ in the Initial Value property.


SYSTEM.BLOCK_STATUS system variable

 Examples 	     Related Topics

Syntax

SYSTEM.BLOCK_STATUS

Description

SYSTEM.BLOCK_STATUS represents the status of a Data block where the cursor is located, or the current data block during trigger processing.  The value can be one of three character strings:

CHANGED	Indicates that the block contains at least one Changed record.
NEW	Indicates that the block contains only New records.
QUERY	Indicates that the block contains only Valid records that have been retrieved from the database.
Usage Notes

Each time this value is referenced, it must be constructed by Form Builder.  If a block contains a large number of records, using SYSTEM.BLOCK_STATUS could adversely affect performance.


SYSTEM.BLOCK_STATUS examples

Assume that you want to create a trigger that performs a commit before clearing a block if there are changes to commit within that block.  The following Key-CLRBLK trigger performs this function.

IF :System.Block_Status = 'CHANGED'
   THEN Commit_Form;
END IF;
Clear_Block;


SYSTEM.COORDINATION_OPERATION system variable

  Related Topics

Syntax

SYSTEM.COORDINATION_OPERATION

Description

This system variable works with its companion SYSTEM.MASTER_BLOCK to help an On-Clear-Details trigger determine what type of coordination-causing operation fired the trigger, and on which master block of a master/detail relation.

The values of the two system variables remain constant throughout the clearing phase of any block synchronization.  SYSTEM.MASTER_BLOCK represents the name of the driving master block, and SYSTEM.COORDINATION_OPERATION represents the coordination-causing event that occurred on the master block.

The Clear_All_Master_Details procedure, which is automatically generated when a relation is created, checks the value of SYSTEM.COORDINATION_OPERATION to provide special handling for the CLEAR_RECORD and SYNCHRONIZE events, which may be different from the handling for other coordination-causing events. The Clear_All_Master_Details procedure also checks the value of SYSTEM.MASTER_BLOCK , to verify that while it is processing the master block of a relation coordination, it is searching only for blocks containing changes.

For example, given the relation hierarchy between blocks shown below, moving to the next record using the [Next Record] key or the Record, Next menu command while in Block C would cause blocks E, F, G, and H to be cleared (and perhaps subsequently queried, depending on the Deferred_Coordination property of the C [image] E and the C [image] F relations).

When the On-Clear-Details trigger fires for block C, the result is:

:System.Cooordination_Operation   = 'NEXT_RECORD'
:System.Master_Block              = 'C'

The Clear_All_Master_Details procedure will clear all of block C's details, causing a "chain reaction" of Clear_Block operations. Consequently, block F is cleared.

Since F is a master for both G and H, and it is being cleared, an On-Clear-Details trigger will fire for block F as well. However, since the clearing of block F was driven (indirectly) by a coordination-causing event in block C, these remain the values in the On-Clear-Details trigger for block F:

:System.Cooordination_Operation   = 'NEXT_RECORD'
:System.Master_Block              = 'C'

Note:  The values of these two system variables are well-defined only in the scope of an On-Clear-Details trigger, or any program unit called by that trigger. Outside this narrow context, the values of these two variables are undefined and should not be used.

The possible values of SYSTEM.COORDINATION_OPERATION, when it is appropriate to check that variable, are described in the following table.

Value	Description	Caused By
MOUSE	Mouse to non-current record	Mouse
UP	Move up a record	Menu, key, PL/SQL
DOWN	Move down a record	Menu, key, PL/SQL
SCROLL_UP	Scroll up records	Menu, key, PL/SQL
SCROLL_DOWN	Scroll down records	Mouse, key, PL/SQL
CLEAR_BLOCK	Clear current block	Menu, key, PL/SQL
CLEAR_RECORD	Clear current record	Menu, key, PL/SQL
CREATE_RECORD	Create new record	Mouse, menu, key, PL/SQL
DELETE_RECORD	Delete current record	Menu, key, PL/SQL
DUPLICATE_RECORD	Duplicate current record	Menu, key, PL/SQL
FIRST_RECORD	Move to first record	PL/SQL
LAST_RECORD	Move to last record	PL/SQL
NEXT_RECORD	Move to next record	Mouse, menu, key, PL/SQL
PREVIOUS_RECORD	Move to previous record	Mouse, menu, key, PL/SQL
GO_RECORD	Jump to record by number	PL/SQL
ENTER_QUERY	Enter Query mode	Menu, key, PL/SQL
EXECUTE_QUERY	Execute query	Menu, key, PL/SQL
COUNT_QUERY	Count queried records	Menu, key, PL/SQL
NEXT_SET	Fetch next set of records	Menu, key, PL/SQL
SYNCHRONIZE_ BLOCKS	Resume after commit error	Internal only


SYSTEM.CURRENT_BLOCK system variable

Syntax

SYSTEM.CURRENT_BLOCK

Description

The value that the SYSTEM.CURRENT_BLOCK system variable represents depends on the current navigation unit:

•	If the current navigation unit is the block, record, or item (as in the Pre- and Post- Item, Record, and Block triggers), the value of SYSTEM.CURRENT_BLOCK is the name of the block that Form Builder is processing or that the cursor is in.

•	If the current navigation unit is the form (as in the Pre- and Post-Form triggers), the value of SYSTEM.CURRENT_BLOCK is NULL.

The value is always a character string.

Note:  SYSTEM.CURRENT_BLOCK is included for compatibility with previous versions.  Oracle Corporation recommends that you use SYSTEM.CURSOR_BLOCK and SYSTEM.TRIGGER_BLOCK instead.


SYSTEM.CURRENT_DATETIME system variable

 Examples

Syntax

SYSTEM.CURRENT_DATETIME

Description

SYSTEM.CURRENT_DATETIME is a variable representing the operating system date.  The value is a CHAR string in the following format:

DD-MON-YYYY HH24:MM:SS

Default

current date

Usage Notes

SYSTEM.CURRENT_DATETIME is useful when you want to use the current operating system date and time in a PL/SQL trigger or procedure.   By using SYSTEM.CURRENT_DATETIME instead of $$DBDATETIME$$, you can avoid the performance impact caused by querying the database.

Note:  Local time and database time may differ.


SYSTEM.CURRENT_DATETIME examples

/*

**
** Trigger:  WHEN-TIMER-EXPIRED
** Example:  Update on-screen time every 30 seconds
*/
DECLARE
   time VARCHAR2(20);
BEGIN
   time := :System.Current_Datetime;
   :control.onscreen := SUBSTR(time, instr(time,' ')+1);
END;


SYSTEM.CURRENT_FORM system variable

 Examples

Syntax

SYSTEM.CURRENT_FORM

Description

SYSTEM.CURRENT_FORM represents the name of the form that Form Builder is executing.  The value is always a character string.

Usage Notes

You can use the GET_APPLICATION_PROPERTY built-in to obtain the name of the current form.


SYSTEM.CURRENT_FORM examples

Assume that you want any called form to be able to identify the name of the form that called it.  You can invoke the following user-defined procedure before Form Builder issues a call.  This procedure stores the name of the current form in a global variable named CALLING_FORM.

PROCEDURE STORE_FORMNAME IS
BEGIN
   :GLOBAL.Calling_Form := :System.Current_Form;
END;


SYSTEM.CURRENT_ITEM system variable

  Related Topics

Syntax

SYSTEM.CURRENT_ITEM

Description

The value that the SYSTEM.CURRENT_ITEM system variable represents depends on the current navigation unit:

•	If the current navigation unit is the item (as in the Pre- and Post-Item triggers), the value of SYSTEM.CURRENT_ITEM is the name of the item that Form Builder is processing or that the cursor is in.  The returned item name does not include a block name prefix.

•	If the current navigation unit is the record, block, or form (as in the Pre- and Post- Record, Block, and Form triggers), the value of SYSTEM.CURRENT_ITEM is NULL.

The value is always a character string.

Note:  SYSTEM.CURRENT_ITEM is included for compatibility with previous versions.  Oracle Corporation recommends that you use SYSTEM.CURSOR_ITEM or  SYSTEM.TRIGGER_ITEM instead.


SYSTEM.CURRENT_VALUE system variable

Syntax

SYSTEM.CURRENT_VALUE

Description

SYSTEM.CURRENT_VALUE represents the value of the item that is registered in SYSTEM.CURRENT_ITEM.

The value is always a character string.

Note:  SYSTEM.CURRENT_VALUE is included for compatibility with previous versions.  Oracle Corporation recommends that you use SYSTEM.CURSOR_ITEM and SYSTEM.CURSOR_VALUE instead.


SYSTEM.CURSOR_BLOCK system variable

 Examples

Syntax

SYSTEM.CURSOR_BLOCK

Description

The value that the SYSTEM.CURSOR_BLOCK system variable represents depends on the current navigation unit:

•	If the current navigation unit is the block, record, or item (as in the Pre- and Post- Item, Record, and Block triggers), the value of SYSTEM.CURSOR_BLOCK is the name of the block where the cursor is located.  The value is always a character string.

•	If the current navigation unit is the form (as in the Pre- and Post-Form triggers), the value of SYSTEM.CURSOR_BLOCK is NULL.


SYSTEM.CURSOR_BLOCK examples

Assume that you want to create a Key-NXTBLK trigger at the form level that navigates depending on what the current block is.  The following trigger performs this function, using :SYSTEM.CURSOR_BLOCK stored in a local variable.

DECLARE
   curblk VARCHAR2(30);
BEGIN
   curblk := :System.Cursor_Block;
   IF curblk = 'ORDERS'
      THEN Go_Block('ITEMS');
   ELSIF curblk = 'ITEMS'
      THEN Go_Block('CUSTOMERS');
   ELSIF curblk = 'CUSTOMERS'
      THEN Go_Block('ORDERS');
   END IF;
END;


SYSTEM.CURSOR_ITEM system variable

 Examples 	   Restrictions

Syntax

SYSTEM.CURSOR_ITEM

Description

SYSTEM.CURSOR_ITEM represents the name of the block and item,  block.item, where the input focus (cursor) is located.

The value is always a character string.

Usage Notes

Within a given trigger, the value of SYSTEM.CURSOR_ITEM changes when navigation takes place.  This differs from SYSTEM.TRIGGER_ITEM, which remains the same from the beginning to the end of single trigger.


SYSTEM.CURSOR_ITEM restrictions

Avoid using SYSTEM.CURSOR_ITEM in triggers where the current navigation unit is not the item, such as Pre- and Post-Record, Block, and Form triggers.  In these triggers, the value of SYSTEM.CURSOR_ITEM is NULL.


SYSTEM.CURSOR_ITEM examples

Assume that you want to create a user-defined procedure that takes the value of the item where the cursor is located (represented by SYSTEM.CURSOR_VALUE), then multiplies the value by a constant, and then reads the modified value into the same item.  The following user-defined procedure uses the COPY built-in to perform this function.

PROCEDURE CALC_VALUE IS
   new_value NUMBER;
BEGIN
   new_value := TO_NUMBER(:System.Cursor_Value) * .06;
   Copy(TO_CHAR(new_value), :System.Cursor_Item);
END;


SYSTEM.CURSOR_RECORD system variable

 Examples

Syntax

SYSTEM.CURSOR_RECORD

Description

SYSTEM.CURSOR_RECORD represents the number of the record where the cursor is located.  This number represents the record's current physical order in the block's list of records. The value is always a character string.


SYSTEM.CURSOR_RECORD examples

Assume that you want to redefine [Previous Item] on the first text item of the ITEMS block so that it navigates to the last text item of the ORDERS block if the current record is the first record.  The following Key-PRV-ITEM trigger on the ITEMS.ORDERID text item performs this function.

IF :System.Cursor_Record = '1'
   THEN Go_Item('orders.total');
   ELSE Previous_Item;
END IF;


SYSTEM.CURSOR_VALUE system variable

 Examples 	   Restrictions

Syntax

SYSTEM.CURSOR_VALUE

Description

SYSTEM.CURSOR_VALUE represents the value of the item where the cursor is located. The value is always a character string.

Usage Notes

Be aware that in triggers where the current navigation unit is not the item, such as Pre-Record , and Pre-Block triggers, SYSTEM.CURSOR_VALUE will contain the value of the item navigated from, rather than the value of the item navigated to.


SYSTEM.CURSOR_VALUE restrictions

•	Avoid using SYSTEM.CURSOR_VALUE in Pre-Form and Post-Form triggers, where the value of SYSTEM.CURSOR_VALUE is NULL.


SYSTEM.CURSOR_VALUE examples

Assume that you want to create a user-defined procedure that takes the value of the item where the cursor is located, multiplies the value by a constant, and then reads the modified value into the same item.  The following user-defined procedure uses the COPY built-in to perform this function.

PROCEDURE CALC_VALUE IS
   new_value NUMBER;
BEGIN
   new_value := TO_NUMBER(:System.Cursor_Value) * .06;
   Copy(TO_CHAR(new_value), :System.Cursor_Item);
END;


SYSTEM.CUSTOM_ITEM_EVENT system variable

 Examples

Syntax

SYSTEM.CUSTOM_ITEM_EVENT

Description

SYSTEM.CUSTOM_ITEM_EVENT stores the name of the event fired by a VBX (in 16-bit Microsoft Windows) or ActiveX (in 32-bit Windows) control.


SYSTEM.CUSTOM_ITEM_EVENT examples

Checks to see if the SpinDown event was fired by the SpinButton VBX control before navigating to the previous item.

IF  :System.Custom_Item_Event = 'SpinDown' THEN
 :QTY := :QTY -1;
END IF;


SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS system variable

 Examples

Syntax

SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS

Description

SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS stores the supplementary arguments for an event fired by a VBX (in 16-bit Microsoft Windows) or ActiveX (in 32-bit Windows) control.


SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS examples

Obtains the value of the 'Button' parameter that stores the value of a VBX control event, and passed the 'Button' value to the user-defined Move_Image subprogram.

DECLARE
 parmType  NUMBER;
 parmValue VARCHAR2(80);
BEGIN
 Get_Parameter_Attr(:System.Custom_Item_Event_Parameters,
                      'Button',parmType,parmValue);
 /*
 ** The value of the 'Button' parameter represents the
 ** direction to move an image.  The user-defined Move_Image
 ** subprogram moves an image two pixels in the direction
 ** specified by 'Button' parameter.
 */
 Move_Image(parmValue);
END;


SYSTEM.DATE_THRESHOLD system variable

Syntax

SYSTEM.DATE_THRESHOLD

Description

SYSTEM.DATE_THRESHOLD represents the database date requery threshold.  This variable works in conjunction with the three system variables $$DBDATE$$, $$DBDATETIME$$, and $$DBTIME$$, and controls how often Form Builder synchronizes the database date with the RDBMS.  The value of this variable must be specified in the following format:

MI:SS

Because frequent RDBMS queries can degrade performance, it is best to keep this value reasonably high.  However, keep in mind that if the value is not synchronized often enough, some time discrepancy can occur.  In addition, if you are building a client/server application,  the performance implications of  SYSTEM.DATE_THRESHOLD could vary depending on the complexity of your network configuration.

Default

01:00 (Synchronization occurs after one minute of elapsed time.)

This does not mean that Form Builder polls the RDBMS once every minute.  It means that whenever Form Builder needs to generate the value for the system variables $$DBDATE$$, $$DBDATETIME$$, $$DBTIME$$, or SYSTEM.EFFECTIVE_DATE, it updates the effective date  by adding the amount of elapsed time (as measured by the local operating system) to the most previously queried RDBMS value.

If the amount of elapsed time exceeds the date threshold, then a new query is executed to retrieve the RDBMS time and the elapsed counter is reset.

Usage Notes

If a form never references the database date, Form Builder never executes a query to retrieve the RDBMS date, regardless of the value of SYSTEM.DATE_THRESHOLD.

The operating system clock and the RDBMS clock rarely drift by more than one or two seconds, even after hours of elapsed time.  However, since your database administrator can reset the RDBMS clock at any time, it is safest to set the threshold no higher than a few minutes.

Often, a Form Builder block may contain multiple references to these $$DBDATE$$, $$DBDATETIME$$, or $$DBTIME$$ defaults.  By setting SYSTEM.DATE_THRESHOLD to the default of one minute, nearly all such references in a form can be satisfied with a single query of the RDBMS.


SYSTEM.EFFECTIVE_DATE system variable

 Examples 	   Restrictions

Syntax

SYSTEM.EFFECTIVE_DATE

Description

SYSTEM.EFFECTIVE_DATE represents the effective database date.  The variable value must always be in the following format:

DD-MON-YYYY HH24:MI:SS

Default

RDBMS date

Usage Notes

This system variable is convenient for testing.  Since you can use it to set a specific time, the time on the screen during an application would not cause subsequent test results to appear different than the known valid output.


SYSTEM.EFFECTIVE_DATE restrictions

This variable is only valid when the database contains a definition of the DUAL table.


SYSTEM.EFFECTIVE_DATE examples

Assume you have set a DATE or TIME text item to one of the three system variables $$DBDATE$$, $$DBDATETIME$$, or $$DBTIME$$.  To override that date or time, set the SYSTEM.EFFECTIVE_DATE system variable to a specific date and/or time.

:System.Effective_Date := '31-DEC-1997 10:59:00'

Note that the effective date "rolls forward" with the database clock.  For example, if you were to set the date as in the immediately preceding example, in an hour, the date would appear as follows:

31-DEC-1997 11:59:00

The value is synchronized to the RDBMS date.  If your database administrator changes the RDBMS date, the SYSTEM.EFFECTIVE_DATE is automatically changed by the same amount of change between old and new RDBMS dates.  Form Builder polls the RDBMS whenever a reference to the effective date is required by the application.


SYSTEM.EVENT_WINDOW system variable

  Examples 	  Related Topics

Syntax

SYSTEM.EVENT_WINDOW

Description

The SYSTEM.EVENT_WINDOW system variable represents the name of the last window that was affected by an action that caused one of the window event triggers to fire.  The following triggers cause this variable to be updated:

•	WHEN-WINDOW-ACTIVATED

•	WHEN-WINDOW-CLOSED

•	WHEN-WINDOW-DEACTIVATED

•	WHEN-WINDOW-RESIZED

From within these triggers, assign the value of the variable to any of the following:

•	global variable

•	parameter

•	variable

•	item, including a null canvas item


SYSTEM.EVENT_WINDOW examples

The following example sets the input focus into a particular item, depending on the window affected:

IF :System.Event_Window = 'ROOT_WINDOW' THEN
   Go_Item('EMPNO');
ELSIF :System.Event_Window = 'DEPT_WINDOW' THEN
   Go_Item('DEPTNO');
END IF;


SYSTEM.FORM_STATUS system variable

 Examples 	     Related Topics

Syntax

SYSTEM.FORM_STATUS

Description

SYSTEM.FORM_STATUS represents the status of the current form.  The value can be one of three character strings:

CHANGED	Indicates that the form contains at least one block with a Changed record.  The value of SYSTEM.FORM_STATUS becomes CHANGED only after at least one record in the form has been changed and the associated navigation unit has also changed.
NEW	Indicates that the form contains only New records.
QUERY	Indicates that a query is open.  The form contains at least one block with QUERY records and no blocks with CHANGED records.
Usage Notes

Each time this value is referenced, it must be constructed by Form Builder.  If a form contains a large number of blocks and many records, using SYSTEM.FORM_STATUS could affect performance.


SYSTEM.FORM_STATUS examples

Assume that you want to create a trigger that performs a commit before clearing a form if there are changes to commit within that form.  The following Key-CLRFRM trigger performs this function.

IF :System.Form_Status = 'CHANGED'
   THEN Commit_Form;
END IF;
Clear_Form;


SYSTEM.LAST_FORM system variable

Syntax

SYSTEM.LAST_FORM

Description

SYSTEM.LAST_FORM represents the form document ID of the previous form in a multi-form application, where multiple forms have been invoked using OPEN_FORM.  The value can be one of two character strings: either the form document ID or NULL.

Usage Notes

SYSTEM.LAST_FORM is not valid with CALL_FORM.


SYSTEM.LAST_QUERY system variable

 Examples

Syntax

SYSTEM.LAST_QUERY

Description

SYSTEM.LAST_QUERY represents the query SELECT statement that Form Builder most recently used to populate a block during the current Runform session.  The value is always a character string.


SYSTEM.LAST_QUERY examples

Example 1

Assume that you want to generate a report in Report Builder that retrieves information identical to a query you perform in Form Builder.  The following examples show how to use SYSTEM.LAST_QUERY to extract the WHERE/ORDER BY clause from the last query so you can pass the results to Report Builder using the RUN_PRODUCT built-in.

FUNCTION Last_Where_Clause
RETURN VARCHAR2
  IS
    tmp_lstqry VARCHAR2(10000) := :System.Last_Query;
    tmp_curblk VARCHAR2(40);
    tmp_index  NUMBER;
    tmp_where  VARCHAR2(2000);
  BEGIN
    /*
    ** See if we can find the word 'WHERE' in
    ** the text of the Last Query
    */
    tmp_index:= INSTR(tmp_lstqry,'WHERE');
    /*
    ** If we found it (at a positive index into
    ** the string), we extract the remainder of
    ** the text that follows the word 'WHERE' as
    ** the Where clause. This might include ORDER BY
    ** clause, too.
    */
    IF tmp_index > 0 THEN
      tmp_where := SUBSTR(tmp_lstqry, tmp_index + 6);
    END IF;
    RETURN (tmp_where);
EXCEPTION
  WHEN OTHERS THEN
    RETURN NULL;
END;

Example 2

PROCEDURE Run_Report_For_Last_Query

IS
   pl  ParamList;
   wc  VARCHAR2(2000); -- The Where Clause to Pass
BEGIN
   /*
   ** Create a parameter list for parameter passing
   */
   pl := Create_Parameter_List('tmp');
   /*
   ** Get the Where Clause from the Last Query
   ** using a user-defined function
   */
   wc := Last_Where_Clause;
   /*
   ** If there is a Non-NULL Last Where clause to
   ** pass, add a text parameter to the parameter
   ** list to specify the parameter name and its
   ** value. In this case the report definition has
   ** a parameter named 'the_Where_Clause' that
   ** it's expecting.
   */
   IF wc IS NOT NULL THEN
      Add_Parameter(pl,                  -- Handle to
                                         -- the ParamList
            'the_Where_Clause',          -- Name of Parameter
                                         -- in the Report
            TEXT_PARAMETER,              -- Type of Parameter
            wc                           -- String Value
                                         -- for Parameter
            );
   END IF;
   /*
   ** Launch the report, passing parameters in the
   ** parameter list.
   */
   Run_Product(REPORTS,              -- The Product to call
                'rep0058.rdf',       -- The name of the
                                     -- report definition
                SYNCHRONOUS,         -- The communications mode
                BATCH,               -- The Execution Mode
                FILESYSTEM,          -- The Location of the
                                     -- reports document
                pl                   -- The Handle to the
      );                                -- parameter list
   /*   Delete the parameter list  */
   Destroy_Parameter_List(pl);
END;


SYSTEM.LAST_RECORD system variable

 Examples

Syntax

SYSTEM.LAST_RECORD

Description

SYSTEM.LAST_RECORD indicates whether the current record is the last record in a block's list of records.  The value is one of the following two CHAR values:

TRUE	Indicates that the current record is the last record in the current block's list of records.
FALSE	Indicates that the current record is not the last record in the current block's list of records.


SYSTEM.LAST_RECORD examples

Assume that you want to create a user-defined procedure that displays a custom message when an operator navigates to the last record in a block's list of records.  The following user-defined procedure performs the basic function.

PROCEDURE LAST_RECORD_MESSAGE IS
BEGIN
   IF :System.Last_Record = 'TRUE'
      THEN Message('You are on the last row');
   END IF;
END;

You can then redefine [Down], [Next Record], and [Scroll Down] to call this user-defined procedure in addition to their normal processing.


SYSTEM.MASTER_BLOCK system variable

Syntax

SYSTEM.MASTER_BLOCK

Description

This system variable works with its companion SYSTEM.COORDINATION_OPERATION to help an On-Clear-Details trigger determine what type of coordination-causing operation fired the trigger, and on which master block of a master/detail relation.

The values of the two system variables remain constant throughout the clearing phase of any block synchronization. SYSTEM.MASTER_BLOCK represents the name of the driving master block, and SYSTEM_COORDINATION_OPERATION represents the coordination-causing event that occurred on the master block.

Please see the reference topic for SYSTEM.COORDINATION_OPERATION for more information.


SYSTEM.MESSAGE_LEVEL system variable

 Examples

Syntax

SYSTEM.MESSAGE_LEVEL

Description

SYSTEM.MESSAGE_LEVEL stores one of the following message severity levels: 0, 5, 10, 15, 20, or 25. The default value is 0.

SYSTEM.MESSAGE_LEVEL can be set to either a character string or a number. The values assigned can be any value between 0 and 25, but values lower than 0 or higher than 25 will generate an error.

During a Runform session, Form Builder suppresses all messages with a severity level that is the same or lower (less severe) than the indicated severity level.

Assign a value to the SYSTEM.MESSAGE_LEVEL system variable with standard PL/SQL syntax:

:System.Message_Level := value;

The legal values for SYSTEM.MESSAGE_LEVEL are 0, 5, 10, 15, 20,and 25.  Form Builder does not suppress prompts or vital error messages, no matter what severity level you select.


SYSTEM.MESSAGE_LEVEL examples

Assume that you want Form Builder to display only the most severe messages (level 25).  The following Pre-Form trigger suppresses all messages at levels 20 and below.

:System.Message_Level := '20';


SYSTEM.MODE system variable

 Examples

Syntax

SYSTEM.MODE

Description

SYSTEM.MODE indicates whether the form is in Normal, Enter Query, or Fetch Processing mode.  The value is always a character string.

NORMAL	Indicates that the form is currently in normal processing mode.
ENTER-QUERY	Indicates that the form is currently in Enter Query mode.
QUERY	Indicates that the form is currently in fetch processing mode, meaning that a query is currently being processed.
Usage Notes

When using SYSTEM.MODE to check whether the current block is in Enter Query mode, be aware that if testing from a When-Button-Pressed trigger in a control block, Enter Query mode will never be entered, because the control block is not the current block.


SYSTEM.MODE examples

Assume that you want Form Builder to display an LOV when the operator enters query mode and the input focus is in a particular text item.  The following trigger accomplishes that operation.

/*
** When-New-Item-Instance Trigger
*/
BEGIN
   IF :System.Cursor_Item = 'EMP.EMPNO' and
     :System.Mode = 'ENTER-QUERY'
   THEN
      IF NOT Show_Lov('my_lov') THEN
         RAISE Form_Trigger_Failure;
   END IF;
END;


SYSTEM.MOUSE_BUTTON_MODIFIERS system variable

Syntax

SYSTEM.MOUSE_BUTTON_MODIFIERS

Description

SYSTEM.MOUSE_BUTTON_MODIFIERS indicates the keys that were pressed during the click, such as SHIFT, ALT, or CONTROL. The value is always a character string.

For example, if the operator holds down the control and shift keys while pressing the mouse button, SYSTEM.MOUSE_BUTTON_MODIFIERS contains the value "Shift+Control+".

The values returned by this variable will be invariant across all platforms, and will not change across languages. SYSTEM.MOUSE_BUTTON_MODIFIERS should be used in place of SYSTEM.MOUSE_BUTTON_SHIFT_STATE.

Possible values are: "Shift+", "Caps Lock+", "Control+", "Alt+", "Command+", "Super+", and "Hyper+".


SYSTEM.MOUSE_BUTTON_PRESSED system variable

 Examples 	 Related Topics

Syntax

SYSTEM.MOUSE_BUTTON_PRESSED

Description

SYSTEM.MOUSE_BUTTON_PRESSED indicates the number of the button that was clicked, either 1, 2, or 3 (left, middle, or right). The value is always a character string.

Notes:

On Motif platforms pressing the right mouse button will not set the SYSTEM.MOUSE_BUTTON_PRESSED value.


SYSTEM.MOUSE_BUTTON_PRESSED examples

/*

**  Trigger:  When-Mouse-Click
**  Example:  When mouse button 1 is pressed,
**            a help window appears.
*/
DECLARE
   the_button_pressed  VARCHAR(1);
BEGIN
   the_button_pressed := :System.Mouse_Button_Pressed;
   IF the_button_pressed = '1' THEN
      Show_Window('online_help',20,5);
   END IF;
END;


SYSTEM.MOUSE_BUTTON_SHIFT_STATE system variable

 Examples 	 Related Topics

Syntax

SYSTEM.MOUSE_BUTTON_SHIFT_STATE

Description

SYSTEM.MOUSE_BUTTON_SHIFT_STATE indicates the key that was pressed during the click, such as SHIFT, ALT, or CONTROL.  The value is always a character string.  The string itself may depend on the user's platform.  For example, in Microsoft Windows, the strings returned are in the language of the operating system.

Key Pressed	Value
SHIFT	Shift+
CONTROL	Ctrl+
ALT	Alt+
SHIFT+CONTROL	Shift+Ctrl+


SYSTEM.MOUSE_BUTTON_SHIFT_STATE examples

/*

**  Trigger:  When-Mouse-Click
**  Example:  If the operator presses down on the Shift key and
**            then clicks on a boilerplate image, a window
**            appears.
*/
DECLARE
   key_pressed  VARCHAR(30) := 'FALSE';
   x_position_clicked NUMBER(30);
   y_position_clicked NUMBER(30);

BEGIN
   key_pressed := :System.Mouse_Button_Shift_State;
   x_position_clicked := To_Number(:System.Mouse_X_Pos);
   y_position_clicked := To_Number(:System.Mouse_Y_Pos);
/*
**  If the operator shift-clicked within the x and y
**  coordinates of a boilerplate image, display a window.
*/
   IF  key_pressed = 'Shift+' AND x_position_clicked
      BETWEEN 10 AND 20 AND y_position_clicked BETWEEN 10
      AND 20 THEN
      Show_Window('boilerplate_image_window');
   END IF;
END;


SYSTEM.MOUSE_CANVAS system variable

  Examples 	{button, ALink(SYSMBP; SYSMBSS;  SYSMOUFM; SYSMOUIT; SYSMOURC; SYSMRO; SYSMOUX; SYSMOUY,,,)} Related Topics

Syntax

SYSTEM.MOUSE_CANVAS

Description

If the mouse is in a canvas, SYSTEM.MOUSE_CANVAS represents the name of that canvas as a CHAR value.  If the mouse is in an item, this variable represents the name of the canvas containing the item.

SYSTEM.MOUSE_CANVAS is NULL if:

•	the mouse is not in a canvas

•	the operator presses the left mouse button, then moves the mouse

•	the platform is non-GUI


SYSTEM.MOUSE_CANVAS examples

/*

**  Trigger:  When-Mouse-Move
**  Example:  When the mouse enters any one of several overlapping
**            canvases, Form Builder brings that canvas to the
**            front.
*/
DECLARE
   canvas_to_front  VARCHAR(50);
BEGIN
   canvas_to_front := :System.Mouse_Canvas;
   Show_View(canvas_to_front);
END;


SYSTEM.MOUSE_FORM system variable

 Related Topics

Syntax

SYSTEM.MOUSE_FORM

Description

If the mouse is in a form document, SYSTEM.MOUSE_FORM represents the name of that form document as a CHAR value.  For example, if the mouse is in Form_Module1, the value for SYSTEM.MOUSE_ITEM is FORM_MODULE1.

Note:  SYSTEM.MOUSE_FORM is NULL if the platform is not a GUI platform.


SYSTEM.MOUSE_ITEM system variable

 Examples 	 	 Related Topics

Syntax

SYSTEM.MOUSE_ITEM

Description

If the mouse is in an item, SYSTEM.MOUSE_ITEM represents the name of that item as a CHAR value.  For example, if the mouse is in Item1 in Block2, the value for SYSTEM.MOUSE_ITEM is :BLOCK2.ITEM1.

SYSTEM.MOUSE_ITEM is NULL if:

•	the mouse is not in an item

•	the operator presses the left mouse button, then moves the mouse

•	the platform is not a GUI platform


SYSTEM.MOUSE_ITEM examples

/* Trigger:  When-Mouse-Click

**   Example:  Dynamically repositions an item if:
**             1) the operator clicks mouse button 2
**                on an item and
**             2) the operator subsequently clicks mouse button
**                2 on an area of the canvas that is
**                not directly on top of another item.
*/
DECLARE
   item_to_move       VARCHAR(50);
   the_button_pressed VARCHAR(50);
   target_x_position  NUMBER(3);
   target_y_position  NUMBER(3);
   the_button_pressed VARCHAR(1);
BEGIN
   /* Get the name of the item that was clicked.
   */
   item_to_move := :System.Mouse_Item;
   the_button_pressed := :System.Mouse_Button_Pressed;
   /*
   **  If the mouse was clicked on an area of a canvas that is
   **  not directly on top of another item, move the item to
   **  the new mouse location.
   */
   IF item_to_move IS NOT NULL AND the_button_pressed =  '2' THEN
      target_x_position := To_Number(:System.Mouse_X_Pos);
      target_y_position := To_Number(:System.Mouse_Y_Pos);
      Set_Item_Property(item_to_move,position,
          target_x_position,target_y_position);
      target_x_position := NULL;
      target_y_position := NULL;
      item_to_move := NULL;
   END IF;
END;


SYSTEM.MOUSE_RECORD system variable

 Examples 	 Related Topics

Syntax

SYSTEM.MOUSE_RECORD

Description

If the mouse is in a record, SYSTEM.MOUSE_RECORD represents that record's record number as a CHAR value.

Note:  SYSTEM.MOUSE_RECORD is 0 if the mouse is not in an item (and thus, not in a record).


SYSTEM.MOUSE_RECORD examples

/*

**  Trigger:  When-Mouse-Move
**  Example:  If the mouse is within a record, display a window
**            that contains an editing toolbar.
*/
DECLARE
   mouse_in_record  NUMBER(7);
BEGIN
   mouse_in_record := To_Number(:System.Mouse_Record);

   IF mouse_in_record > 0 THEN
      Show_Window('editing_toolbar');
   END IF;
END;


SYSTEM.MOUSE_RECORD_OFFSET system variable

 Related Topics

Syntax

SYSTEM.MOUSE_RECORD_OFFSET

Description

If the mouse is in a record, SYSTEM.MOUSE_RECORD_OFFSET represents the offset from the first visible record as a CHAR value. SYSTEM.MOUSE_RECORD_OFFSET is only valid within mouse triggers. Its value represents which row within the visible rows the mouse has clicked.

For example, if the mouse is in the second of five visible records in a multi-record block, SYSTEM.MOUSE_RECORD_OFFSET is 2.  (SYSTEM.MOUSE_RECORD_OFFSET uses a 1-based index).

Note:  SYSTEM.MOUSE_RECORD_OFFSET is 0 if the mouse is not in an item (and thus, not in a record).


SYSTEM.MOUSE_X_POS system variable

 Examples 	 	 Related Topics

Syntax

SYSTEM.MOUSE_X_POS

Description

SYSTEM.MOUSE_X_POS represents (as a CHAR value) the x coordinate of the mouse in the units of the current form coordinate system.  If the mouse is in an item, the value is relative to the upper left corner of the item's bounding box. If the mouse is on a canvas, the value is relative to the upper left corner of the canvas.

Note:  SYSTEM.MOUSE_X_POS is always NULL on character-mode platforms.


SYSTEM.MOUSE_X_POS examples

/*

**  Example:  See SYSTEM.MOUSE_ITEM  and
**            SYSTEM.MOUSE_BUTTON_SHIFT_STATE.
*/


SYSTEM.MOUSE_Y_POS system variable

 Examples 	 Related Topics

Syntax

SYSTEM.MOUSE_Y_POS

Description

SYSTEM.MOUSE_Y_POS represents (as a CHAR value) the y coordinate of the mouse, using units of the current coordinate system.  If the mouse is in an item, the value is relative to the upper left corner of the item's bounding box.  If the mouse is on a canvas, the value is relative to the upper left corner of the canvas.

Note:  SYSTEM.MOUSE_Y_POS is always NULL on character-mode platforms.


SYSTEM.MOUSE_Y_POS examples

/*

**  Example:  See SYSTEM.MOUSE_ITEM and
**            SYSTEM.MOUSE_BUTTON_SHIFT_STATE.
*/


SYSTEM.RECORD_STATUS system variable

 Examples 	     Related Topics

Syntax

SYSTEM.RECORD_STATUS

Description

SYSTEM.RECORD_STATUS represents the status of the record where the cursor is located.  The value can be one of four character strings:

CHANGED	Indicates that a queried record's validation status is Changed.
INSERT	Indicates that the record's validation status is Changed and that the record does not exist in the database.
NEW	Indicates that the record's validation status is New.
QUERY	Indicates that the record's validation status is Valid and that it was retrieved from the database.
Usage Notes

Both SYSTEM.RECORD_STATUS and the GET_RECORD_PROPERTY built-in return the status of a record in a given block, and in most cases, they return the same status.  However, there are specific cases in which the results may differ.

SYSTEM.RECORD_STATUS can in certain cases return a value of NULL, because SYSTEM.RECORD_STATUS is undefined when there is no current record in the system.  For example, in a When-Clear-Block trigger, Form Builder is at the block level in its processing sequence, so there is no current record to report on, and the value of SYSTEM.RECORD_STATUS is NULL.

GET_RECORD_PROPERTY, on the other hand, always has a value of NEW, CHANGED, QUERY, or INSERT, because it returns the status of a specific record without regard to the processing sequence or whether the record is the current record.


SYSTEM.RECORD_STATUS examples

Assume that you want to create a trigger that performs a commit before clearing a Changed record.  The following Key-CLRREC trigger performs this function.

IF :System.Record_Status IN ('CHANGED', 'INSERT') THEN
   Commit_Form;
END IF;
Clear_Record;


SYSTEM.SUPPRESS_WORKING system variable

 Examples

Syntax

SYSTEM.SUPPRESS_WORKING

Description

SYSTEM.SUPPRESS_WORKING suppresses the "Working..." message in Runform, in order to prevent the screen update usually caused by the display of the "Working..." message. The value of the variable is one of the following two CHAR values:

TRUE	Prevents Form Builder from issuing the  "Working..." message.
FALSE	Allows Form Builder to continue to issue the "Working..." message.


SYSTEM.SUPPRESS_WORKING examples

Assume that you want to have the form filled with data when the operator enters the form.  The following When-New-Form-Instance trigger will prevent the unwanted updates that would normally occur when you fill the blocks with data.

:System.Suppress_Working := 'TRUE';
Go_Block ('DEPT');
Execute_Query;
Go_Block ('EMP');
Execute_Query;
Go_Block ('DEPT');
:System.Suppress_Working := 'FALSE';


SYSTEM.TAB_NEW_PAGE system variable

 Examples 	     Related Topics

Syntax

SYSTEM.TAB_NEW_PAGE

Description

The system variable SYSTEM.TAB_NEW_PAGE specifies the name of the tab page to which navigation occurred.  Use it inside a When-Tab-Page-Changed trigger.


SYSTEM.TAB_NEW_PAGE examples

/* Use system variable SYSTEM.TAB_NEW_PAGE inside a

** When-Tab-Page-Changed trigger to change the label of
** the tab page to UPPERCASE when an end user navigates
** into the tab page:
*/
DECLARE
  tp_nm   VARCHAR2(30);
  tp_id   TAB_PAGE;
  tp_lbl  VARCHAR2(30);
BEGIN
  tp_nm  := :SYSTEM.TAB_NEW_PAGE;
  tp_id  := FIND_TAB_PAGE(tp_nm);
  tp_lbl := GET_TAB_PAGE_PROPERTY(tp_id, label);
  IF tp_nm LIKE 'ORD%' THEN
    SET_TAB_PAGE_PROPERTY(tp_id, label, 'ORDERS');
  END IF;
END;


SYSTEM.TAB_PREVIOUS_PAGE system variable

 Examples 	     Related Topics

Syntax

SYSTEM.TAB_PREVIOUS_PAGE

Description

The system variable SYSTEM.TAB_PREVIOUS_PAGE specifies the name of the tab page from which navigation occurred.  Use it inside a When-Tab-Page-Changed trigger.


SYSTEM.TAB_PREVIOUS_PAGE examples

/* Use system variable SYSTEM.TAB_PREVIOUS_PAGE inside a

** When-Tab-Page-Changed trigger to change the label of the
** tab page to initial-cap after an end user navigates out
** of the tab page:
*/
DECLARE
  tp_nm   VARCHAR2(30);
  tp_id   TAB_PAGE;
  tp_lbl  VARCHAR2(30);
BEGIN
  tp_nm  := :SYSTEM.TAB_PREVIOUS_PAGE;
  tp_id  := FIND_TAB_PAGE(tp_nm);
  tp_lbl := GET_TAB_PAGE_PROPERTY(tp_id, label);
  IF tp_nm LIKE 'ORD%' THEN
    SET_TAB_PAGE_PROPERTY(tp_id, label, 'Orders');
  END IF;
END;


SYSTEM.TRIGGER_BLOCK system variable

 Examples 	 	  Related Topics

Syntax

SYSTEM.TRIGGER_BLOCK

Description

SYSTEM.TRIGGER_BLOCK represents the name of the block where the cursor was located when the current trigger initially fired.  The value is NULL if the current trigger is a Pre- or Post-Form trigger.  The value is always a character string.


SYSTEM.TRIGGER_BLOCK examples

Assume that you want to write a form-level procedure that navigates to the block where the cursor was when the current trigger initially fired.  The following statement performs this function.

Go_Block(Name_In('System.Trigger_Block'));


SYSTEM.TRIGGER_ITEM system variable

 Examples 	   Restrictions

Syntax

SYSTEM.TRIGGER_ITEM

Description

SYSTEM.TRIGGER_ITEM represents the item (BLOCK.ITEM) in the scope for which the trigger is currently firing.  When referenced in a key trigger, it represents the item where the cursor was located when the trigger began.  The value is always a character string.

Usage Notes

SYSTEM.TRIGGER_ITEM remains the same from the beginning to the end of given trigger.  This differs from  SYSTEM.CURSOR_ITEM, which may change within a given trigger when navigation takes place.


SYSTEM.TRIGGER_ITEM restrictions

Avoid using SYSTEM.TRIGGER_ITEM in triggers where the current navigation unit is not the item, such as Pre- and Post-Record, Block, and Form triggers.  In these triggers, the value of  SYSTEM.TRIGGER_ITEM is NULL.


SYSTEM.TRIGGER_ITEM examples

Assume that you want to write a user-defined procedure that navigates to the item where the cursor was when the current trigger initially fired.  The following statement performs this function.

Go_Item(:System.Trigger_Item);


SYSTEM.TRIGGER_NODE_SELECTED system variable

Syntax

SYSTEM.TRIGGER_NODE_SELECTED

Description

SYSTEM.TRIGGER_NODE_SELECTED contains a valid value only during the WHEN-TREE-NODE-SELECTED trigger, indicating whether the trigger is firing for a selection or a deselection. The values are either TRUE or FALSE.


SYSTEM.TRIGGER_RECORD system variable

 Examples

Syntax

SYSTEM.TRIGGER_RECORD

Description

SYSTEM.TRIGGER_RECORD represents the number of the record that Form Builder is processing.  This number represents the record's current physical order in the block's list of records. The value is always a character string.


SYSTEM.TRIGGER_RECORD examples

In the following anonymous block, the IF statement uses SYSTEM.TRIGGER_RECORD to identify the current record before processing continues.

IF :System.Trigger_Record = '1'
   THEN Message('First item in this order.');
END IF;


Using Timers


About timers

  Related Topics

A timer is an "internal time clock" that you programmatically create to perform an action each time the timer expires.

Timer duration can be between 1 and 2,147,483,647 millisecond (1 second=1000 milliseconds).  The maximum duration of a timer is approximately 24.85 days.

When you work with timers you perform these steps:

1	Create the desired number of repeating or non-repeating timers using the CREATE_TIMER built-in subprogram.

2	Create a When-Timer-Expired trigger that performs the desired action whenever your timer expires.


About timer usage rules

  Related Topics

When using timers, consider these usage rules:

•	A When-Timer-Expired trigger cannot fire during transactions, trigger processing, navigation, etc.  Thus, a When-Timer-Expired trigger only fires while Form Builder is waiting to accept user input.

As a result, a timer may not expire exactly on the millisecond, but it will fire after the specified number of milliseconds.

•	By default, a timer repeats on expiration unless you specify NO_REPEAT.

•	When a timer is created, Form Builder puts it on a queue.

A When-Timer-Expired trigger will only fire once for each timer that is on the queue.

•	A repeating timer will not repeat while it is on the queue.  It will begin repeating once it has been serviced off of the queue by a When-Timer-Expired trigger.  Thus, only one instance of a timer may be placed on the expired timer queue at a time.

•	If the operator exits an application prior to timer expiration, any timer on the queue will not be executed by the When-Timer-Expired trigger.


Creating a timer

 Examples	     Related Topics

You can create a timer by using the CREATE_TIMER built-in subprogram.

CREATE_TIMER(timer_name, milliseconds, iterate);

where:

timer_name	Specifies the timer name of up to 30 alphanumeric characters.  The name must begin with an alphabetic character.  The datatype of the name is CHAR.
milliseconds	Specifies the duration of the timer in milliseconds.  The range of values allowed for this parameter is 1 to 2147483648 milliseconds. Values > 2147483648 will be rounded down to 2147483648.  Note that only positive numbers are allowed.  The datatype of the parameter is NUMBER.  See Restrictions below for more information.
iterate	Specifies whether the timer should repeat or not upon expiration.  Takes the following constants as arguments:
	REPEAT  Indicates that the timer should repeat upon expiration.  Default.
	NO_REPEAT  Indicates that the timer should not repeat upon expiration, but is to be used once only, until explicitly called again.


Creating a timer examples

/*  Create a repeating timer that expires every hour */
DECLARE
     hour_timer TIMER;
     one_hour     NUMBER(7):=3600000;
BEGIN
     hour_timer:= CREATE_TIMER('alarm',one_hour,REPEAT);
END;


Responding to multiple timers

 Examples	     Related Topics

When working with multiple timers, remember that the When-Timer-Expired is a form-level trigger.  It fires any time a timer expires.  If your application contains several timers, your When-Timer-Expired trigger should contain code that will handle the different timers accordingly.

Note:  To retrieve the timer name of the most recently executed timer, initiate a call to GET_APPLICATION_PROPERTY from within a When-Timer-Expired trigger.  Otherwise, the results of the built-in are undefined.


Responding to multiple timers examples

/*  Create a When-Timer-Expired trigger that can handle multiple
**  application timers.
*/
DECLARE
     expired_timer  CHAR(20);
BEGIN
     expired_timer:=GET_APPLICATION_PROPERTY(TIMER_NAME);
     IF expired_timer='T1'
        THEN /* handle timer T1 */;
     ELSIF expired_timer='T2'
        THEN /* handle timer T2 */;
     ELSE /* handle all other timers */;
     END IF;
END;


Modifying a timer programmatically

 Examples	     Related Topics

You can use the following built-in subprograms when working with timers:

•	CREATE_TIMER

•	DELETE_TIMER

•	FIND_TIMER

•	GET_APPLICATION_PROPERTY

•	SET_TIMER

Note:  You cannot change a timer's name programmatically.


Modifying a timer programmatically examples

/*
** Builtin:  FIND_TIMER
**
** Example:  If the timer exists, reset it. Otherwise create
**           it.
*/
PROCEDURE Reset_Timer_Interval( Timer_Name VARCHAR2,
Timer_Intv NUMBER ) IS
  tm_id       Timer;
  tm_interval NUMBER;
BEGIN
  /*
  ** User gives the interval in seconds, the timer routines
  ** expect milliseconds
  */
  tm_interval := 1000 * Timer_Intv;
  /* Lookup the timer by name */
  tm_id := Find_Timer(Timer_Name);
  /* If timer does not exist, create it */
  IF Id_Null(tm_id) THEN
    tm_id := Create_Timer(Timer_Name,tm_interval,NO_REPEAT);
  /*
  ** Otherwise, just restart the timer with the new interval
  */
  ELSE
    Set_Timer(tm_id,tm_interval,NO_REPEAT);
  END IF;
END;


Deleting a timer

 Examples	     Related Topics

You can delete repeating and non-repeating timers by using the DELETE_TIMER built-in subprogram.


Deleting a timer examples

/*
** Builtin:  DELETE_TIMER
** Example:  Remove a timer after first checking to see if it
**           exists
*/
PROCEDURE Cancel_Timer (tm_name VARCHAR2) IS
     tm_id  TIMER;
BEGIN
  tm_id:=Find_Timer(tm_name);
  IF NOT Id_Null(tm_id) THEN
    Delete_Timer(tm_id);
  ELSE
    Message('Timer '||' has already been cancelled.');
  END IF;
END;


About tooltips

  Related Topics

A tooltip is a small text box that displays help information about an item when the mouse enters the item.

A tooltip appears when the mouse enters an item and remains in the item for at least half a second. The text appears in a box centered directly beneath the item. The size of the box is determined by how much space is needed to display the text. The box is just large enough horizontally and vertically to display the text with a thin border around it.

The tooltip is displayed in the specified visual attribute. If a visual attribute is not specified, the tooltip uses the same visual attribute information as the item for which it is being displayed.

The tooltip remains visible until the mouse is moved outside the item or into a different item, another window is shown, or the user performs an action in the item for which the tooltip is being displayed.


Creating a tooltip

  Related Topics

To create a tooltip:

1	In the Object Navigator, double-click the object icon beside the item for which you want to create a tooltip. This will display the Property Palette.

2	Under the Help node, select the Tooltip property.

3	Type the desired tooltip text in the Tooltip property field.

Creating and Manipulating Tooltips Programmatically  You can also create and manipulate tooltips programmatically using TOOLTIP_TEXT and TOOLTIP_ATTRIBUTE with the following built-in subprograms:

GET_ITEM_PROPERTY

SET_ITEM_PROPERTY


About Triggers and Events

  Related Topics

Triggers are blocks of PL/SQL code that are written to perform tasks when a specific event occurs within an application.  In effect, a Form Builder trigger is an event-handler written in PL/SQL to augment (or occasionally replace) the default processing behavior.  Every trigger has a name, and contains one or more PL/SQL statements.  A trigger encapsulates PL/SQL code so that it can be associated with an event and executed and maintained as a distinct object.

When Form Builder responds to an event by executing the code in a trigger, that trigger is said to have "fired."  Most form applications include numerous triggers that fire in response to a variety of events.

A trigger must be attached to a specific object in the form, either an item, a block, or the form itself.  The object to which a trigger is attached defines the scope of the trigger, and so helps Form Builder decide which trigger to fire when the corresponding event occurs.  Not all triggers are relevant to all objects.  For example a When-Button-Pressed trigger would not be attached to a display item.

Trigger names correspond to pre-defined runtime events.  For example, the When-Button-Pressed trigger corresponds to the Button Pressed event, which occurs when an operator selects a button.  The name of the trigger establishes the association between the event and the trigger code; when operators click on a button with a mouse, Form Builder responds by executing the code in the When-Button-Pressed trigger.

For example, in a form with three buttons, each button has a When-Button-Pressed trigger attached to it, and each trigger contains different PL/SQL statements.  When an operator selects one of the buttons, that is, when the Button Pressed event occurs, Form Builder responds by firing only the When-Button-Pressed trigger attached to the selected button.  The When-Button-Pressed triggers attached to the other two buttons are outside the scope of the event, and so are ignored.


Types of Events

  Related Topics

Form Builder recognizes a predefined set of runtime events, each of which has a corresponding built in trigger.  When you add code to an application by writing a trigger, it is important to decide what event should fire the trigger.  The event you choose determines the name assigned to the trigger.

Interface Events

When selecting triggers, it is important to understand precisely when events occur, both in relation to other events, and in relation to form processing.  Some events are external interface events, and their occurrence is immediately apparent.  Examples of such events, and their corresponding triggers, include the following:

Event	Trigger Name
Pressing a button	When-Button-Pressed
Clicking a check box	When-Checkbox-Changed
Pressing the Tab key	KEY-FN
Internal Processing Events

Internal events occur as a result of runtime processing.  These events occur according to the Form Builder processing model.

Consider a form with two blocks, Block A and Block B, with text items in each block.  On GUI platforms, operators can move the input focus from a text item in Block A to a text item in Block B by clicking the target item with a mouse.  Although this operation involves only one interface action (the mouse-click in the target item), it actually sets off a series of internal processing events, each of which has one or more corresponding triggers:

Event	Trigger Name
Validate the item	When-Validate-Item
Leave the item	Post-Text-Item
Validate the record	When-Validate-Record
Leave the record	Post-Record
Leave the block	Post-Block
Enter the block	Pre-Block
Enter the record	Pre-Record
Enter the Item	Pre-Text-Item
Ready block for input	When-New-Block-Instance
Ready record for input	When-New-Record-Instance
Ready item for input	When-New-Item-Instance

It is important to understand that navigational events such as "Leave the Item" and "Enter the Block" occur as a result of internal form processing navigation.  These events occur as Form Builder validates data in the form and "navigates" through the object hierarchy to move from one item to another.

In the example, to move the input focus from a source item in one block to a target item in another, Form Builder first validates the value in the source item, then "enters the record" to validate all of the items in the record, then leaves the record and "enters the block," and so on, finally ending up in the target item.

The Form Builder processing model enforces the integrity of data at the item, record, block, and form level. The rich assortment of events to which can be responded with trigger code gives complete control over every aspect of an application.

Processes and Sub-Processes

A process is a series of individual, related events that occurs during a specific Form Builder Runform operation.  The previous example described a navigational process.  Other processes involve validation and database transactions.  For example, the Post and Commit Transaction process includes a complex series of events and sub-processes.


Trigger Definition Level and Scope

  Related Topics

When a trigger is created it is attached to a specific object, either an item, a block, or the form itself.  The object to which a trigger is attached determines the trigger's definition level in the object hierarchy.  For example, a trigger attached to a block named Customer has a definition level of block, and is said to be a "block-level trigger."

A trigger's definition level is important because it determines the trigger's scope.  The scope of a trigger is its domain within the Form Builder object hierarchy, and determines where an event must occur for the trigger to respond to it.

Trigger scope is defined as the trigger definition level (form, block, or item) and below. Thus, a block-level trigger fires if the trigger event occurs within that block, but it does not fire if the same event occurs in some other block.

Consider the When-New-Item-Instance trigger.  This trigger fires in response to the Enter the Item event, which occurs when the operator or the application navigates to a different item.  If the When-New-Item-Instance trigger is attached to a text item, it fires only when the operator enters that particular item.  If the same When-New-Item-Instance trigger were attached to the block, it would fire when the operator entered any item in that block.  Similarly, if the trigger were attached to the form, it would fire when the operator entered any item in any block in the form.

Precedence of Triggers that Respond to the Same Event

It is common to define triggers at different levels that respond to the same event.  When an event occurs that is within the scope of more than one trigger, the trigger with the lowest definition level takes precedence.

For example, you might attach a When-New-Item-Instance trigger to a block, and another When-New-Item-Instance trigger to a text item in that block.  When the operator navigates to the text item, the item-level trigger fires, and the block-level trigger is ignored.

Restrictions on Trigger Definition Levels

Some triggers can be defined only at a particular definition level. For example, the When-Validate-Record trigger, which fires when the Validate the Record event occurs, is only valid if attached to a block or to the form—it cannot be attached to an item. Most triggers, however, can be defined at the form, block or item level, and it is up to you to select the appropriate definition level to achieve the desired functionality.


Creating a trigger in the Object Navigator

  Related Topics

To create a trigger in the Object Navigator:

1	In the Object Navigator, position the cursor on the Triggers node under the form, block, or item to which you are attaching the trigger.

For example, if you are attaching a trigger to a button, click on the Triggers node under the name of the button.

2	Choose Navigator [image] Create to invoke the Triggers list of values (LOV).

3	Select the desired trigger name from the LOV, then click OK.

The PL/SQL Editor appears.  The Type, Object, and Name options are set for you automatically based on the object to which you are attaching the trigger and the trigger name you selected.

4	In the PL/SQL Editor, enter the desired trigger code.

5	Choose Compile to compile the trigger.

6	Choose Close to dismiss the editor.


Creating a trigger using Smart Triggers

  Related Topics

To create a trigger using Smart Triggers:

1	In the Object Navigator click on the object for which you want to attach a trigger.

2	Choose Program [image] Smart Triggers…

3	Choose a trigger from those displayed in the submenu.

The PL/SQL Editor appears.  The Type, Object, and Name options are set for you automatically based on the object to which you are attaching the trigger and the trigger name you selected.

4	In the PL/SQL Editor, enter the desired trigger code.

5	Choose Compile to compile the trigger.

6	Choose Close to dismiss the editor.


Creating a trigger in the PL/SQL Editor

  Related Topics

To create a trigger in the PL/SQL Editor:

1	In the PL/SQL Editor, set the Type option to Trigger.

2	Set the Object options to specify the object (form, block, or item) for which you are defining the trigger.

For example, to attach the trigger to a block, set the first Options drop-down list to the name of the block, and set the second drop-down list to Block Level.

3	Choose New to invoke the Triggers list of values (LOV).

4	Select the desired trigger name from the LOV, then click OK.

5	Enter the desired trigger code.

6	Choose Compile to compile.

7	Choose Close to dismiss the editor.


Creating a trigger in the Layout Editor

  Related Topics

To create a trigger for an item in the Layout Editor:

1	In the Layout Editor, select the item to which you want to attach the trigger.

2	From the pop-up menu, select Trigger to invoke the PL/SQL Editor. (On Microsoft Windows, press the right mouse button to display the pop-up menu.)

The Type and Object options in the PL/SQL Editor are set automatically, according to the item that was selected when the editor is invoked. If there is already a trigger attached to the item, its name and code appear in the Editor.

3	Choose New to invoke the Triggers list of values (LOV).

4	Select the desired trigger name from the LOV, then click OK.

5	Enter the desired trigger code.

6	Choose Compile to compile.

7	Choose Close to dismiss the editor.


Setting trigger properties

Like other objects, triggers have properties. Once a trigger is created, set its properties by selecting it in the Object Navigator and editing its properties in the Property Palette.


About compiling triggers

  Related Topics

Form Builder compiles any uncompiled triggers in a form when the form is generated to create a runtime file.  Compiling individual triggers is not required.  However, compiling locally allows errors in trigger code to be found and corrected at the time the trigger is written, rather than when the form is generated.

When a trigger is compiled, Form Builder checks the trigger text for syntax errors, semantic errors, and references to non-existent objects or subprograms.  If an error is detected, Form Builder displays the line number of the offending statement and provides a description of the error.


Calling user-named triggers

  Related Topics

A user-named trigger is one that has a unique, user-supplied name.  Because its name does not correspond to any Form Builder event, a user-named trigger can only be executed by calling it from within a built-in trigger, menu item command, or user-named subprogram.  To call a user-named trigger, use the EXECUTE_TRIGGER built-in procedure.  This procedure takes a parameter that names the trigger to be fired:

Execute_Trigger('my_user_named_trigger');

User-named triggers are required only in special situations.  For most applications, writing a user-named subprogram and then calling that from a trigger or menu item command is preferred.


About writing trigger code

  Related Topics

The code in Form Builder triggers and menu item commands is written in Oracle's PL/SQL language.  PL/SQL is an extension to the SQL database language, and both SQL statements and PL/SQL statements may be included in a Form Builder trigger.  Calls to Form Builder built-in subprograms and to user-named  PL/SQL subprograms are permitted.

Calling PL/SQL procedures within a PL/SQL trigger behaves as if the entire procedure text were substituted in-line at the place in the trigger that call to the procedure exists.  Any exception (including FORM_TRIGGER_FAIL) will follow normal PL/SQL exception handler scoping rules

The text of a Form Builder trigger is an anonymous PL/SQL block.  A block can consist of three sections:

1	a declaration section for variables, constants, cursors, and exceptions

2	a section of executable statements

3	a section of exception handlers

The syntax for delimiting the sections of a PL/SQL block looks like this:

DECLARE
-- declarative statements (optional)
BEGIN
-- executable statements (required)
EXCEPTION
-- exception handlers (optional)
END;

In a trigger, only the executable section is required.  A trigger that does not have a DECLARE section, does not need the BEGIN and END keywords, as they are added implicitly.  The following example shows such a trigger:

/*  Key-CLRREC Trigger:         */
IF :System.Record_Status = 'CHANGED' OR
   :System.Record_Status = 'INSERT' THEN
Commit_Form;
END IF;
Clear_Record;

However, if you include a DECLARE section, you must also include the BEGIN and END keywords so the compiler can detect the start of the executable section:

/*  When-Button-Pressed Trigger:  */
DECLARE
discount_variable NUMBER (5);
BEGIN
SELECT discount into discount_variable from Promotions
WHERE custid = :cust_id;
:total := calculate_total(:amount, discount_variable);
END;


About calling built-in subprograms in triggers

  Related Topics

Form Builder includes over 100 built-in subprograms that can be called from triggers.  A built-in subprogram is a packaged procedure or function that is always available within Form Builder.  Built-in subprograms are available to handle a variety of application functions.  For example, to programmatically move the input focus from one item to another, call one of the following built-in subprograms:

NEXT_ITEM	GO_ITEM
NEXT_BLOCK	GO_BLOCK
NEXT_RECORD

Other built-in subprograms exist to perform operations on data in the form or in the database:

CLEAR_RECORD	EXECUTE_QUERY
DELETE_RECORD	COMMIT_FORM
ENTER_QUERY

Still others can be used to control the display of interface objects at runtime:

MOVE_WINDOW	SHOW_LOV
HIDE_WINDOW	SHOW_ALERT
SHOW_EDITOR

The following example shows the text of a When-Button-Pressed trigger.  Pressing the button displays a dialog box called order_info_window that allows operators to enter information about an order:

/*  When-Button-Pressed trigger:   */
Show_Window('order_info_window');

This trigger has only one statement, the call to the built-in subprogram SHOW_WINDOW.  The SHOW_WINDOW subprogram is a procedure that displays the window named in its argument list.

In the Object Navigator, you can browse a list of Form Builder built-ins under the Built-in Packages node. The Standard Extensions package includes the core Form Builder built-ins.  Other packages provide specialized functionality for specific application purposes.


About restricted built-in subprograms

  Related Topics

Any built-in subprogram that initiates navigation is restricted.  This includes subprograms that move the input focus from one item to another, and those that involve database transactions.  Restricted built-ins are not allowed in triggers that fire in response to navigation.

For example, the GO_ITEM and NEXT_SET built-ins are both restricted procedures.  GO_ITEM moves the input focus from a source item to a target item, which requires navigation.  Similarly, the NEXT_SET procedure causes Form Builder to navigate internally to the block level, fetch a set of records, and then navigate to the first item in the first record.  (Note that this navigation happens internally as a result of default processing, and may not be apparent to the form operator.)

Because GO_ITEM and NEXT_SET both initiate navigation, they cannot be called from triggers that fire in response to internal navigational events; that is, triggers that fire while navigation is already occurring. Thus, a restricted procedure cannot be called from a Pre-Block trigger, because the  Pre-Block trigger fires during internal navigation.  In fact, restricted subprograms are not allowed from any PRE- or POST- navigational triggers.

You can, however, call a restricted built-in subprogram from a When-New-Instance trigger.  For example, the When-New-Item-Instance trigger fires after navigation to an item has succeeded, when the form is waiting for input. This is an important point to remember as you select trigger types during application development.

The reference topic of each trigger has a "Legal Commands" section that describes which types of built-ins (restricted or unrestricted) can be called from the trigger.  Also, each built-in description includes a "Built-in Type" section that indicates whether the built-in is a restricted or unrestricted procedure or function.


About writing SQL statements in triggers

  Related Topics

By default, a data block inherently supports query-by-example, update, insert, and delete functionality.  Form Builder issues the appropriate SELECT, UPDATE, INSERT, and DELETE SQL statements in response to operator actions and programmatic control.  For example, to execute a query programmatically, navigate to the desired block (for example, with GO_BLOCK ), then call the EXECUTE_QUERY built-in procedure.

There is no need to write the SQL SELECT statement to populate the appropriate items in the blocks, because data items are bound at design-time to the corresponding database columns, and Form Builder issues the SQL for you automatically.  Form Builder also issues the SQL statements required to support default locking functionality.

For most applications, write SQL statements in triggers to extend the default Form Builder functionality.  For example, to populate a look-up item that corresponds to a table other than the block's data table, write a SELECT...INTO statement in a Post-Query trigger.

It is possible to select a database value into a form item using block_name.item_name notation to refer to the form item:

SELECT column
INTO :block.item
FROM table
WHERE primarykey = :block.pri_key_item;

The statement above opens an implicit cursor.  Declare explicit cursors when you want to have complete control over database queries.

As a general rule, DML statements are supported only in transactional triggers; that is, triggers that fire in response to transaction processing events, such as Pre-Update, Post-Insert, and On-Delete. The On-Event triggers completely replace the default SQL that Form Builder would have issued at that point.  While you can write a trigger that uses any DML (Data Manipulation Language) statement, Oracle Corporation advises that you follow the recommendations that are stated for each trigger in the reference topics.

Using DML statements in certain triggers can de-synchronize the state of records between Form Builder and rows in the database, and can cause unexpected results.  Form Builder keeps track of changes to the data in a form by examining item, record, block, and form status.

For example, when the operator changes the value of a text item and then issues the Save command, Form Builder examines the status of the record to determine that an UPDATE needs to be processed.

When DML statements are issued independently of default processing, Form Builder is unaware of any such changes, and you cannot rely on the default commit processing to manage them.

DDL (Data Dictionary Language) commands, such as CREATE TABLE and DROP SEQUENCE, can be issued by calling the FORMS_DDL built-in procedure. Be aware that FORMS_DDL built-in always issues an implicit COMMIT_FORM after executing the desired statement. Consequently, FORMS_DDL built-in should be called only when the application does not have unsaved changes pending that the operator might want to subsequently undo.


Overview of trigger categories

  Related Topics

This topic provides an overview of commonly used triggers, grouped into the following functional categories:

•	block-processing triggers

•	interface event triggers

•	master-detail triggers

•	message-handling triggers

•	navigational triggers

•	query-time triggers

•	transactional triggers

•	validation triggers

This topic does not list all of the triggers available in Form Builder, many of which have highly specialized uses.  For a complete list of triggers, or for detailed information on a specific trigger, refer to the Triggers Category Page.


Block processing triggers

  Related Topics

Block processing triggers fire in response to events related to record management in a block.

Trigger	Typical Usage
When-Create-Record	Perform an action whenever Form Builder attempts to create a new record in a block.  For example, to set complex, calculated, or data-driven default values that must be specified at runtime, rather than design time.
When-Clear-Block	Perform an action whenever Form Builder flushes the current block; that is, removes all records from the block.
When-Database-Record	Perform an action whenever Form Builder changes a record's status to Insert or Update, thus indicating that the record should be processed by the next COMMIT_FORM operation
When-Remove-Record	Perform an action whenever a record is cleared or deleted.  For example, to adjust a running total that is being calculated for all of the records displayed in a block.


Interface event triggers

  Related Topics

Interface event triggers fire in response to events that occur in the form interface.  Some of these triggers, such as When-Button-Pressed, fire only in response to operator input or manipulation.  Others, like When-Window-Activated, can fire in response to both operator input and programmatic control.

Trigger	Typical Usage
When-Button-Pressed	Initiate an action when an operator selects a button, either with the mouse or through keyboard selection.
When-Checkbox-Changed	Initiate an action when the operator toggles the state of a check box, either with the mouse or through keyboard selection
When-Image-Activated	Initiate an action whenever the operator double-clicks an image item.
When-Image-Pressed	Initiate an action whenever an operator clicks on an image item.
Key- [all]	Replace the default function associated with a function key.  For example, you can define a Key-EXIT trigger to replace the default functionality of the [Help] key.
When-Radio-Changed	Initiate an action when an operator changes the current radio button selected in a radio group item.
When-Timer-Expired	Initiate an action when a programmatic timer expires.
When-Window-Activated	Initiate an action whenever an operator or the application activates a window.
When-Window-Closed	Initiate an action whenever an operator closes a window with the window manager's Close command.
When-Window-Deactivated	Initiate an action whenever a window is deactivated as a result of another window becoming the active window.
When-Window-Resized	Initiate an action whenever a window is resized, either by the operator or programmatically.


Master/Detail triggers

  Related Topics

Form Builder generates master/detail triggers automatically when a master/detail relation is defined between blocks.  The default master/detail triggers enforce coordination between records in a detail block and the master record in a master block.  Unless developing custom block-coordination schemes, you do not need to define these triggers.  Instead, simply create a relation object, and let Form Builder generate the triggers required to manage coordination between the master and detail blocks in the relation.

Trigger	Typical Usage
On-Check-Delete-Master	Fires when Form Builder attempts to delete a record in a block that is a master block in a master/detail relation.
On-Clear-Details	Fires when Form Builder needs to clear records in a block that is a detail block in a master/detail relation because those records no longer correspond to the current record in the master block.
On-Populate-Details	Fires when Form Builder needs to fetch records into a block that is the detail block in a master/detail relation so that detail records are synchronized with the current record in the master block.


Message-handling triggers

  Related Topics

Form Builder automatically issues appropriate error and informational messages in response to runtime events.  Message handling triggers fire in response to these default messaging events.

Trigger	Typical Usage
On-Error	Replace a default error message with a custom error message, or to trap and recover from an error.
On-Message	To trap and respond to a message; for example, to replace a default message issued by Form Builder with a  custom message.


Navigational triggers

  Related Topics

Navigational triggers fire in response to navigational events.  For instance, when the operator clicks on a text item in another block, navigational events occur as Form Builder moves the input focus from the current item to the target item.

Navigational events occur at different levels of the Form Builder object hierarchy (Form, Block, Record, Item).  Navigational triggers can be further sub-divided into two categories:  Pre- and Post- triggers, and When-New-Instance triggers.

Pre- and Post- Triggers  fire as Form Builder navigates internally through different levels of the object hierarchy.  As you might expect, these triggers fire in response to navigation initiated by an operator, such as pressing the [Next Item] key.  However, be aware that these triggers also fire in response to internal navigation that Form Builder performs during default processing.  To avoid unexpected results, you must consider such internal navigation when you use these triggers.

Trigger	Typical Usage
Pre-Form	Perform an action just before Form Builder navigates to the form from "outside" the form, such as at form startup.
Pre-Block	Perform an action before Form Builder navigates to the block level from the form level.
Pre-Record	Perform an action before Form Builder navigates to the record level from the block level.
Pre-Text-Item	Perform an action before Form Builder navigates to a text item from the record level.
Post-Text-Item	Manipulate an item when Form Builder leaves a text item and navigates to the record level.
Post-Record	Manipulate a record when Form Builder leaves a record and navigates to the block level.
Post-Block	Manipulate the current record when Form Builder leaves a block and navigates to the form level.
Post-Form	Perform an action before Form Builder navigates to "outside" the form, such as when exiting the form.
When-New-Instance-Triggers  fire at the end of a navigational sequence that places the input focus on a different item.  Specifically, these triggers fire just after Form Builder moves the input focus to a different item, when the form returns to a quiet state to wait for operator input.

Unlike the Pre- and Post- navigational triggers, the When-New-Instance triggers do not fire in response to internal navigational events that occur during default form processing.

Trigger	Typical Usage
When-New-Form-Instance	Perform an action at form start-up.  (Occurs after the Pre-Form trigger fires).
When-New-Block-Instance	Perform an action immediately after the input focus moves to an item in a block other than the block that previously had input focus.
When-New-Record-Instance	Perform an action immediately after the input focus moves to an item in a different record.  If the new record is in a different block, fires after the When-New-Block-Instance trigger, but before the When-New-Item-Instance trigger.
When-New-Item-Instance	Perform an action immediately after the input focus moves to a different item.  If the new item is in a different block, fires after the When-New-Block-Instance trigger.


Query-time triggers

  Related Topics

Query-time triggers fire just before and just after the operator or the application executes a query in a block.

Trigger	Typical Usage
Pre-Query	Validate the current query criteria or provide additional query criteria programmatically, just before sending the SELECT statement to the database.
Post-Query	Perform an action after fetching a record, such as looking up values in other tables based on a value in the current record.  Fires once for each record fetched into the block.


Transactional triggers

  Related Topics

Transactional triggers fire in response to a wide variety of events that occur as a form interacts with the data source.

Trigger	Typical Usage
On-Delete	Replace the default Form Builder processing for handling deleted records during transaction posting.
On-Insert	Replace the default Form Builder processing for handling inserted records during transaction posting.
On-Lock	Replace the default Form Builder processing for locking rows in the database.
On-Logon	Replace the default Form Builder processing for connecting to ORACLE, especially for a form that does not require a database connection or for connecting to a non-ORACLE data source.
On-Logout	Replace the default Form Builder processing for logout from ORACLE.
On-Update	Replace the default Form Builder processing for handling updated records during transaction posting.
Post-Database-Commit	Augment default Form Builder processing following a database commit.
Post-Delete	Audit transactions following the deletion of a row from the database.
Post-Forms-Commit	Augment the default Form Builder commit statement prior to committing a transaction.
Post-Insert	Audit transactions following the insertion of a row in the database.
Post-Update	Audit transactions following the updating of a row in the database.
Pre-Commit	Perform an action immediately before the Post and Commit Transactions process, when Form Builder determines that there are changes in the form to post or to commit.
Pre-Delete	Manipulate a record prior to its being deleted from the database during the default Post and Commit Transactions process; for example, to prevent deletion of the record if certain conditions exist.
Pre-Insert	Manipulate a record prior to its being inserted in the database during the default Post and Commit Transactions process.
Pre-Update	Validate or modify a record prior to its being updated in the database during the default Post and Commit Transactions process.

Note:  This is only a partial list of the transactional triggers available.  Many of the triggers not shown here are On-event triggers that exist primarily for applications that will run against a non-ORACLE data source.


Validation triggers

  Related Topics

Validation triggers fire when Form Builder validates data in an item or record.  Form Builder performs validation checks during navigation that occurs in response to operator input, programmatic control, or default processing, such as a Commit operation.

Trigger	Typical Usage
When-Validate-Item	Augment default validation of an item.
When-Validate-Record	Augment default validation of a record.


Other trigger categories

  Related Topics

The previous section listed triggers in groups according to their functions.  Triggers can also be categorized by name.  There are five such categories, each relating to a particular type of event that occurs during runtime processing.

When-Event Triggers signal a point at which Form Builder default processing may be augmented with additional tasks or operations. For example, the When-Validate-Item trigger fires immediately after Form Builder validates data in an item.

To augment the default validation checks that Form Builder performs, code additional validation in a When-Validate-Item trigger.  Most When-event triggers can include calls to restricted built-in subprograms.

On-Event Triggers signal a point at which Form Builder default processing may be replaced.  For example, the On-Logon trigger fires when Form Builder readies to log on to an ORACLE data source.  If the application requires a connection to a non-ORACLE data source, code an On-Logon trigger to pass the appropriate logon parameters to the non-ORACLE data source.  This completely replaces the default logon to ORACLE.  On-event triggers can include calls to unrestricted built-in subprograms.

Pre-Event Triggers signal a point just prior to the occurrence of either a When-event or an On-event.  Use triggers for these events to prepare objects or data for the upcoming event.  Pre-event triggers can include calls to unrestricted built-in subprograms.

Post-Event Triggers signal a point just following the occurrence of either a When-event or an On-event.  Write triggers for these events that validate objects or data, or that perform some auditing tasks based on the prior event.  Post-event triggers can include calls to unrestricted built-in subprograms.

Key Triggers have a one-to-one relationship with specific keys.  That is, the trigger fires when the operator presses a specific key or key-sequence.

Remember that most GUI applications offer operators more than one way to execute commands.  For instance, an operator might be able to execute a query by clicking a button, selecting a menu command, or pressing the [Execute Query] key.

In such situations, it would be a mistake to place all of your application logic in a key trigger that might never fire.  Similarly, in any mouse-driven application, you cannot rely entirely on key triggers for navigational keys like [Next Item] and [Next Block].  Because operators can navigate with a mouse, they may choose not to use these keys for navigation, and the associated triggers would not be fired.


Delete-Procedure Trigger

 All Triggers

Description

Automatically created by Form Builder when the delete data source is a stored procedure. This trigger is called when a delete operation is necessary. Think of this as an ON-DELETE trigger that is called by the system instead of doing default delete operations.

Do not modify this trigger.

Enter Query Mode  Not applicable.

On Failure

No effect


Function Key Triggers

 Restrictions	 All Triggers

Description

Function key triggers are associated with individual Runform function keys.  A function key trigger fires only when an operator presses the associated function key.  The actions defined in a function key trigger replace the default action that the function key would normally perform.

The following table shows all function key triggers and the corresponding Runform function keys.

Key Trigger	Associated Function Key
Key-CLRBLK	[Clear Block]
Key-CLRFRM	[Clear Form]
Key-CLRREC	[Clear Record]
Key-COMMIT	[Accept]
Key-CQUERY	[Count Query Hits]
Key-CREREC	[Insert Record]
Key-DELREC	[Delete Record]
Key-DOWN	[Down]
Key-DUP-ITEM	[Duplicate Item]
Key-DUPREC	[Duplicate Record]
Key-EDIT	[Edit]
Key-ENTQRY	[Enter Query]
Key-EXEQRY	[Execute Query]
Key-EXIT	[Exit]
Key-HELP	[Help]
Key-LISTVAL	[List of Values]
Key-MENU	[Block Menu]
Key-NXTBLK	[Next Block]
Key-NXT-ITEM	[Next Item]
Key-NXTKEY	[Next Primary Key]
Key-NXTREC	[Next Record]
Key-NXTSET	[Next Set of Records]
Key-PRINT	[Print]
Key-PRVBLK	[Previous Block]
Key-PRV-ITEM	[Previous Item]
Key-PRVREC	[Previous Record]
Key-SCRDOWN	[Scroll Down]
Key-SCRUP	[Scroll Up]
Key-UP	[Up]
Key-UPDREC	Equivalent to Record, Lock command on the default menu

Note that you cannot redefine all Runform function keys with function key triggers.  Specifically, you cannot ever redefine the following static function keys because they are often performed by the terminal or user interface management system and not by Form Builder.

[Clear Item]	[First Line]	[Scroll Left]
[Copy]	[Insert Line]	[Scroll Right]
[Cut]	[Last Line]	[Search]
[Delete Character]	[Left]	[Select]
[Delete Line]	[Paste]	[Show Keys]
[Display Error]	[Refresh]	[Toggle Insert/Replace]
[End of Line]	[Right]	[Transmit]

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

On Failure

no effect

Enter Query Mode  yes

Usage Notes

The default functionality performed by the following keys is not allowed in Enter Query mode:

[Clear Block]	[Down]	[Next Record]
[Clear Form]	[Duplicate Item]	[Next Set of Records]
[Clear Record]	[Duplicate Record]	[Previous Block]
[Accept]	[Block Menu]	[Previous Record]
[Insert Record]	[Next Block]	[Up]
[Delete Record]	[Next Primary Key]	[Lock Record]

Common Uses

Use function key triggers to perform the following tasks:

•	Disable function keys dynamically.

•	Replace the default behavior of function keys.

•	Dynamically remap function keys.

•	Perform complex or multiple functions with a single key or key sequence.


Function Key Triggers restrictions

•	Form Builder ignores the Key-Commit trigger when an operator presses [Commit/Accept] in a dialog box.


Insert-Procedure Trigger

 All Triggers

Description

Automatically created by Form Builder when the insert data source is a stored procedure.  This trigger is called when a insert operation is necessary.  Think of this as an ON-INSERT trigger that is called by the system instead of doing default insert operations.

Definition Level

Do not modify this trigger.

Enter Query Mode Not applicable.

On Failure

No effect


Key-Fn Trigger

 Restrictions	 All Triggers

Description

A Key-Fn trigger fires when an operator presses the associated key.

You can attach Key-Fn triggers to 10 keys or key sequences that normally do not perform any Form Builder operations.  These keys are referred to as Key-F0 through Key-F9.  Before you can attach key triggers to these keys, you or the DBA must use Oracle Terminal to map the keys to the appropriate functions.

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

•	Use Key-Fn triggers to create additional function keys for custom functions.

•	The key description shown in the default menu's Help [image] Keys menu will always be for the form-level trigger defined for that key. If there are any lower-level triggers (e.g., block-level triggers) that are also defined for the key, their descriptions will be shown when focus is in the lower level (e.g., the block) and [Show Keys] is pressed, but they will not be displayed in the default menu's Help [image] Keys menu.

•	Not all keys can be remapped on certain operating systems.  For example, the Microsoft Windows operating system always displays the Windows Help System when F1 is pressed, and attempts to close the application window when Alt-F4 is pressed.


Key-Fn Trigger restrictions

Form Builder ignores Key-Fn triggers in Edit mode.


Key-Others Trigger

 Restrictions	 All Triggers

Description

A Key-Others trigger fires when an operator presses the associated key.

A Key-Others trigger is associated with all keys that can have key triggers associated with them but are not currently defined by function key triggers (at any level).

A Key-Others trigger overrides the default behavior of a Runform function key (unless one of the restrictions apply).  When this occurs, however, Form Builder still displays the function key's default entry in the Keys screen.

Trigger Type key

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

Use Key-Others triggers to limit an operator's possible actions.  Specifically, use Key-Others triggers to perform the following tasks:

•	Disable all keys that are not relevant in a particular situation.

•	Perform one specific action whenever an operator presses any key.

Also note:

•	The key description shown in the default menu's Help [image] Keys menu will always be for the form-level trigger defined for that key. If there are any lower-level triggers (e.g., block-level triggers) that are also defined for the key, their descriptions will be shown when focus is in the lower level (e.g., the block) and [Show Keys] is pressed, but they will not be displayed in the default menu's Help [image] Keys menu.


Key-Others Trigger restrictions

Form Builder ignores a Key-Others trigger under the following conditions:

•	The form is in Enter Query mode and Fire in Enter-Query Mode is Off.

•	A list of values, the Keys screen, a help screen, or an error screen is displayed.

•	The operator is responding to a Runform prompt.

•	The operator presses a static function key.


Lock-Procedure Trigger

 All Triggers

Description

Automatically created by Form Builder when the lock data source is a stored procedure.  This trigger is called when a lock operation is necessary.  Think of this as an ON-LOCK trigger that is called by the system instead of doing default lock operations.

Do not modify this trigger.

Enter Query Mode Not applicable.

On Failure

No effect


On-Check-Delete-Master Trigger

 Examples	 All Triggers

Description

Form Builder creates this trigger automatically when you define a master/detail relation and set the Delete Record Behavior property to Non-Isolated.  It fires when there is an attempt to delete a record in the master block of a master/detail relation.

Definition Level  form or block

Legal Commands

Any command, unrestricted built-ins, restricted built-ins

Enter Query Mode  no

On Failure

Prevents the deletion of the current master record

Fires In

Master/Detail Coordination


On-Check-Delete-Master Trigger examples

Example

The following example replaces the On-Check-Delete-Master that is generated by default for a master/detail relation with a trigger that will fail if the sum of the distributions does not equal the purchase order total.

DECLARE
  the_sum NUMBER;
BEGIN
  SELECT SUM(dollar_amt)
    INTO the_sum
    FROM po_distribution
   WHERE po_number = :purchase_order.number;

/* Check for errors */
  IF the_sum <> :purchase_order.total THEN
    Message('PO Distributions do not reconcile.');
    RAISE Form_Trigger_Failure;
     ELSIF form_fatal OR form_failure THEN
     raise form_trigger_failure;
  end if;
END;


On-Check-Unique Trigger

 Examples	     Related Topics	 All Triggers

Description

During a commit operation, the On-Check-Unique trigger fires when Form Builder normally checks that primary key values are unique before inserting or updating a record in a base table.  It fires once for each record that has been inserted or updated.

Replaces the default processing for checking record uniqueness.  When a block has the PRIMKEYB property set to Yes, Form Builder, by default, checks the uniqueness of a record by constructing and executing the appropriate SQL statement to select for rows that match the current record's primary key values.  If a duplicate row is found, Form Builder displays message FRM-40600: Record has already been inserted.

For a record that has been marked for insert, Form Builder always checks for unique primary key values.  In the case of an update, Form Builder checks for unique primary key values only if one or more items that have the Primary Key item property have been modified.

Definition Level

form, block

Legal Commands

SELECT statements, PL/SQL, unrestricted built-ins

Enter Query Mode  no

Usage Notes

To perform the default processing from this trigger, call the CHECK_RECORD_UNIQUENESS built-in.

On Failure

no effect

Fires In

Check Record Uniqueness

Post and Commit Transactions

See Process Flowcharts


On-Check-Unique Trigger examples

Example

The following example verifies that the current record in question does not already exist in the DEPT table.

DECLARE
  CURSOR chk_unique IS SELECT 'x'
                         FROM dept
                        WHERE deptno = :dept.deptno;
  tmp VARCHAR2(1);
BEGIN
  OPEN chk_unique;
  FETCH chk_unique INTO tmp;
  CLOSE chk_unique;
  IF tmp IS NOT NULL THEN
    Message('This department already exists.');
    RAISE Form_Trigger_Failure;
     ELSIF form_fatal OR form_failure THEN
     raise form_trigger_failure;
  END IF;
END;


On-Clear-Details Trigger

 All Triggers

Description

Fires when a coordination-causing event occurs in a block that is a master block in a Master/Detail relation.  A coordination-causing event is any event that makes a different record the current record in the master block.

Definition Level  form, block

Legal Commands

Any command, unrestricted built-ins, restricted built-ins

Enter Query Mode  no

Usage Notes

Form Builder creates the On-Clear-Details trigger automatically when a Master/Detail block relation is defined.

On Failure

Causes the coordination-causing operation and any scheduled coordination triggers to abort.

Fires In

Master Detail Coordination

See Process Flowcharts


On-Close Trigger

 Examples	     Related Topics	 All Triggers

Description

Fires when an operator or the application causes a query to close.  By default, Form Builder closes a query when all of the records identified by the query criteria have been fetched, or when the operator or the application aborts the query.

The On-Close trigger augments the normal Form Builder "close cursor" phase of a query.

Definition Level  form

Legal Commands

SELECT statements, PL/SQL, unrestricted built-ins

Enter Query Mode  no

Usage Notes

•	Use an On-Close trigger after using the On-Select or On-Fetch triggers, specifically, to close files, close cursors, and free memory.

•	The On-Close trigger fires automatically when the ABORT_QUERY built-in is called from an On-Select trigger.

On Failure

no effect

Fires In

ABORT_QUERY

Close The Query

See Process Flowcharts


On-Close Trigger examples

Example

The following example releases memory being used by a user-defined data access method via the transactional triggers.

BEGIN
  IF NOT my_data source_open('DX110_DEPT') THEN
    my_datasource_close('DX110_DEPT');
     ELSIF form_fatal OR form_failure THEN
     raise form_trigger_failure;
  END IF;
END;


On-Column-Security Trigger

 Examples	     Related Topics	 All Triggers

Description

Fires when Form Builder would normally enforce column-level security for each block that has the Enforce Column Security block property set On.

By default, Form Builder enforces column security by querying the database to determine the base table columns to which the current form operator has update privileges.  For columns to which the operator does not have update privileges, Form Builder makes the corresponding base table items in the form non-updateable by setting the Update Allowed item property Off dynamically.  Form Builder performs this operation at form startup, processing each block in sequence.

Definition Level  form, block

Legal Commands

SELECT statements, PL/SQL, unrestricted built-ins

Enter Query Mode  no

Usage Notes

To perform the default processing from this trigger, call the ENFORCE_COLUMN_SECURITY built-in.

On Failure

no effect


On-Column-Security Trigger examples

Example

The following example sets salary and commission text items in the current block to disabled and non-updateable, unless the SUPERUSER role is enabled. Only users with the user-defined SUPERUSER role can change these number fields.

DECLARE
  itm_id Item;
  on_or_off NUMBER;
BEGIN
  IF NOT role_is_set('SUPERUSER') THEN
     on_or_off := PROPERTY_OFF;
  ELSE
    on_or_off := PROPERTY_ON;
  END IF;
  itm_id := Find_Item('Emp.Sal');
  Set_Item_Property(itm_id,ENABLED,on_or_off);
  Set_Item_Property(itm_id,UPDATEABLE,on_or_off);
  itm_id := Find_Item('Emp.Comm');
  Set_Item_Property(itm_id,ENABLED,on_or_off);
  Set_Item_Property(itm_id,UPDATEABLE,on_or_off);

 IF form_fatal OR form_failure THEN
     raise form_trigger_failure;
END IF;
END;


On-Commit Trigger

 Examples	  Related Topics	 All Triggers

Description

Fires whenever Form Builder would normally issue a database commit statement to finalize a transaction.  By default, this operation occurs after all records that have been marked as updates, inserts, and deletes have been posted to the database.

The default COMMIT statement that Form Builder issues to finalize a transaction during the Post and Commit Transactions process.

Definition Level  form

Legal Commands

SELECT statements, PL/SQL, unrestricted built-ins

Enter Query Mode  no

Usage Notes

•	Use an On-Commit trigger to change the conditions of normal Form Builder commit processing to fit the particular requirements of a commit to a non-ORACLE database.

•	To perform the default processing from this trigger, call to the  built-in.

On Failure

Aborts Post and Commit processing

Fires In

Post and Commit Transactions

See Process Flowcharts


On-Commit Trigger examples

Example

This example disables the commit operation when running against a datasource that does not support transaction control. If the application is running against ORACLE, the commit operation behaves normally.

BEGIN
  IF Get_Application_Property(DATA_SOURCE) = 'ORACLE' THEN
    Commit_Form;
     ELSIF form_fatal OR form_failure THEN
     raise form_trigger_failure;
  END IF;

  /*
  ** Otherwise, no action is performed
  */
END;


On-Count Trigger

 Examples	     Related Topics	 All Triggers

Description

Fires when Form Builder would normally perform default Count Query processing to determine the number of rows in the database that match the current query criteria.  When the On-Count trigger completes execution, Form Builder issues the standard query hits message:  FRM-40355: Query will retrieve <n> records.

Definition Level  form, block

Legal Commands

SELECT statements, PL/SQL, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

•	Use an On-Count trigger to replace default Count Query processing in an application running against a non-ORACLE data source.

•	To perform the default Form Builder processing from this trigger, include a call to the  built-in.

•	If you are replacing default processing, you can set the value of the Query_Hits block property to indicate the number of records in the non-ORACLE data source that match the query criteria.

•	Form Builder will display the query hits message (FRM-40355) even if the On-Count trigger fails to set the value of the Query_Hits block property.  In such a case, the message reports 0 records identified.

On Failure

no effect

Fires In

See Process Flowcharts


On-Count Trigger examples

Example

This example calls a user-named subprogram to count the number of records to be retrieved by the current query criteria, and sets the Query_Hits property appropriately.

DECLARE
  j NUMBER;
BEGIN
  j := Recs_Returned('DEPT',Name_In('DEPT.DNAME'));
  Set_Block_Property('DEPT',QUERY_HITS,j);
END;


On-Delete Trigger

 Examples	     Related Topics	 All Triggers

Description

Fires during the Post and Commit Transactions process and replaces the default Form Builder processing for handling deleted records during transaction posting.  Specifically, it fires after the Pre-Delete trigger fires and before the Post-Delete trigger fires, replacing the actual database delete of a given row.  The trigger fires once for each row that is marked for deletion from the database.

Definition Level  form or block

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

•	Use an On-Delete trigger to replace the default Form Builder processing for handling deleted records during transaction posting.

•	To perform the default Form Builder processing from this trigger, that is, to delete a record from your form or from the database, include a call to the DELETE_RECORD built-in.

On Failure

Form Builder rolls back to the most recent savepoint

Fires In

Post and Commit Transactions

See Process Flowcharts


On-Delete Trigger examples

Example

This example updates the employee table to set the Termination_Date, rather than actually deleting the employee from the database.

BEGIN
  UPDATE emp
     SET termination_date = SYSDATE
   WHERE empno = :Emp.Empno;
IF form_fatal OR form_failure THEN
   raise form_trigger_failure;
END IF;
END;


On-Dispatch-Event Trigger

 All Triggers

Description

This trigger is called when an ActiveX control event occurs. You can call the DISPATCH_EVENT built-in from within this trigger to specify the dispatch mode as either restricted or unrestricted.  For more information about working with ActiveX control events, see Responding to ActiveX Control Events.

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode No

On Failure

No effect


On-Dispatch Event Trigger examples
On-Dispatch Event examples

Example

/*

ON-DISPATCH-EVENT trigger
*/
BEGIN
IF SYSTEM.CUSTOM_ITEM_EVENT = 4294966696 THEN
/*when event occurs, allow it to apply to different items */.
FORMS4W.DISPATCH_EVENT(RESTRICTED_ALLOWED);
ELSE
/*run the default, that does not allow applying any other 	item */
FORMS4W.DISPATCH_EVENT(RESTRICTED_UNALLOWED);
ENDIF;

  IF form_fatal OR form_failure THEN
     raise form_trigger_failure;
  END IF;

END;


On-Error Trigger

 Examples	     Related Topics	 All Triggers

Description

An On-Error trigger fires whenever Form Builder would normally cause an error message to display.

Replaces

The writing of an error message to the message line.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

•	Use an On-Error trigger for the following purposes:

•	to trap and recover from an error

•	to replace a standard error message with a custom message

Use the ERROR_CODE , ERROR_TEXT , ERROR_TYPE , DBMS_ERROR_TEXT , or DBMS_ERROR_CODE built-in function in an On-Error trigger to identify a specific error condition.

•	In most cases, On-Error triggers should be attached to the form, rather than to a block or item.  Trapping certain errors at the block or item level can be difficult if these errors occur while Form Builder is performing internal navigation, such as during a Commit process.

On Failure

no effect


On-Error Trigger examples

Example

The following example checks specific error message codes and responds appropriately.

DECLARE
   lv_errcod  NUMBER       := ERROR_CODE;
   lv_errtyp  VARCHAR2(3)  := ERROR_TYPE;
   lv_errtxt  VARCHAR2(80) := ERROR_TEXT;
BEGIN
   IF (lv_errcod = 40nnn) THEN
   /*
   **  Perform some tasks here
   */
   ELSIF (lv_errcod = 40mmm) THEN
   /*
   **  More tasks here
   */
...
...
ELSIF (lv_errcod = 40zzz) THEN
   /*
   **  More tasks here
   */
ELSE
   Message(lv_errtyp||'-'||to_char(lv_errcod)||': '||lv_errtxt);
   RAISE Form_Trigger_Failure;
END IF;
END;


On-Fetch Trigger

 Examples	     Related Topics	 All Triggers

Description

When a query is first opened, fires immediately after the On-Select trigger fires, when the first records are fetched into the block.  While the query remains open, fires again each time a set of rows must be fetched into the block.

Definition Level  form or block

Legal Commands

SELECT statements, PL/SQL, unrestricted built-ins

Enter Query Mode  no

Usage Notes

When you write an On-Fetch trigger to replace default fetch processing, the trigger must do the following:

•	Retrieve the appropriate number of records from the non-ORACLE data source, as indicated by the setting of the Records_To_Fetch property.

•	Create that number of queried records in the current block.

•	Populate the records with the retrieved data.

•	Create queried records from an On-Fetch trigger by calling the CREATE_QUERIED_RECORD built-in subprogram.

While the query remains open, the On-Fetch trigger continues to fire as more records are needed in the block.  This behavior continues:

•	until no queried records are created in a single execution of the trigger.  Failing to create any records signals an end-of-fetch to Form Builder, indicating that there are no more records to be retrieved.

•	until the query is closed, either by the operator or programmatically through a call to ABORT_QUERY.

•	until the trigger raises the built-in exception FORM_TRIGGER_FAILURE.

To perform the default Form Builder processing from this trigger, include a call to the FETCH_RECORDS built-in.

Do not use an ABORT_QUERY built-in in an On-Fetch trigger.  ABORT_QUERY is not valid in an On-Fetch trigger, and produces inconsistent results.

On Failure

no effect

Fires In

Fetch Records

See Process Flowcharts


On-Fetch Trigger examples

This example calls a client-side package function to retrieve the proper number of rows from a package cursor.

DECLARE
  j NUMBER := Get_Block_Property(blk_name, RECORDS_TO_FETCH);
  emprow emp%ROWTYPE;

BEGIN
  FOR ctr IN 1..j LOOP
    /*
    ** Try to get the next row.
    */
    EXIT WHEN NOT MyPackage.Get_Next_Row(emprow);
    Create_Queried_Record;
    :Emp.rowid := emprow.ROWID;
    :Emp.empno := emprow.EMPNO;
    :Emp.ename := emprow.ENAME;
       :
       :
  END LOOP;
    IF form_fatal OR form_failure THEN
     raise form_trigger_failure;
  END IF;

END;


On-Insert Trigger

  Related Topics	 All Triggers

Description

Fires during the Post and Commit Transactions process when a record is inserted.  Specifically, it fires after the Pre-Insert trigger fires and before the Post-Insert trigger fires, when Form Builder would normally insert a record in the database.  It fires once for each row that is marked for insertion into the database.

Definition Level  form or block

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

•	Use an On-Insert trigger to replace the default Form Builder processing for handling inserted records during transaction posting.

•	To perform the default Form Builder processing from this trigger, include a call to the INSERT_RECORD built-in.

On Failure

Form Builder performs the following steps when the On-Insert trigger fails:

•	sets the error location

•	rolls back to the most recent savepoint

Fires In

Post and Commit Transactions

See Process Flowcharts


On-Lock Trigger

  Related Topics	 All Triggers

Description

Fires whenever Form Builder would normally attempt to lock a row, such as when an operator presses a key to modify data in an item.  The trigger fires between the keypress and the display of the modified data.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

•	Use an On-Lock trigger to replace the default Form Builder processing for locking rows.  For example, for an application intended for use on a single-user system, use the On-Lock trigger to speed processing by bypassing all lock processing.  Also, use On-Lock when accessing a non-ORACLE data source directly, not by way of Open Gateway.

•	When the On-Lock trigger fires as a result of an operator trying to modify data, the trigger fires only the first time the operator tries to modify an item in the record.  The trigger does not fire during subsequent modifications to items in the same record.  In other words, for every row that is to be locked, the trigger fires once.

•	To perform the default Form Builder processing from this trigger, include a call to the LOCK_RECORD built-in.

•	Use this trigger to lock underlying tables for non-updateable views.

Caution

In special circumstances, you may use the LOCK TABLE DML statement in an On-Lock trigger.  However, as this could result in other users being locked out of the table, please exercise caution and refer to the ORACLE RDMS Database Administrator's Guide before using LOCK TABLE.

On Failure

When the On-Lock trigger fails, the target record is not locked and Form Builder attempts to put the input focus on the current item.  If the current item cannot be entered for some reason, Form Builder attempts to put the input focus on the previous navigable item.

Fires In

Lock the Row

See Process Flowcharts


On-Logon Trigger

  Related Topics	 All Triggers

Description

Fires once for each logon when Form Builder normally initiates the logon sequence.

Definition Level  form

Legal Commands

unrestricted built-ins

Enter Query Mode  no

Usage Notes

•	Use an On-Logon trigger to initiate a logon procedure to a non-ORACLE data source.

•	Pre-Logon and Post-Logon triggers fire as part of the logon procedure.

•	To create an application that does not require a data source, supply a NULL command to this trigger to bypass the connection to a data source.

•	To perform the default Form Builder processing from this trigger, include a call to the LOGON built-in.

On Failure

Form Builder attempts to exit the form gracefully, and does not fire the Post-Logon trigger.

Fires In

LOGON

See Process Flowcharts


On-Logout Trigger

  Related Topics	 All Triggers

Description

Fires when Form Builder normally initiates a logout procedure from Form Builder and from the RDBMS.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

•	Use an On-Logout trigger to replace the default logout processing either from the RDBMS or from a non-ORACLE data source.

•	To perform the default Form Builder processing from this trigger, include a call to the LOGOUT built-in.

•	If you call certain built-ins from within one of the Logout triggers, the results are undefined.  For example, you cannot call the COPY built-in from a Pre-Logout trigger because Pre-Logout fires after the Leave the Form event.  Because the form is no longer accessible, a COPY operation is not possible.

On Failure

If an exception is raised in an On-Logout trigger and the current Runform session is exited, Form Builder will not fire other triggers, such as Post-Logout .

Fires In

LOGOUT

See Process Flowcharts


On-Message Trigger

 Examples	     Related Topics	 All Triggers

Description

Fires whenever Form Builder would normally cause a message to display and pre-empts the message.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

Use an On-Message trigger for the following purposes:

•	to trap and respond to an informative message

•	to replace a standard informative message with a custom message

•	to exclude an inappropriate message

•	Use the MESSAGE_CODE, MESSAGE_TEXT, MESSAGE_TYPE built-ins in an On-Message trigger to identify the occurrence of a specific message condition.

•	If you use the On-Message trigger to trap a message so that it does not display on the message line, the GET_MESSAGE built-in does not return a value.  To display the current message from this trigger, you must trap the message and explicitly write it to the display device.

•	In most cases, On-Message triggers should be attached to the form, rather than to a block or item. Trapping certain errors at the block or item level can be difficult if these errors occur while Form Builder is performing internal navigation, such as during a Commit process.

On Failure

no effect


On-Message Trigger examples

Example

The following example responds to an error message by displaying an alert that gives the user a message and gives the user the choice to continue or to stop:

DECLARE
  alert_button NUMBER;
  lv_errtype VARCHAR2(3) := MESSAGE_TYPE;
  lv_errcod NUMBER := MESSAGE_CODE;
  lv_errtxt VARCHAR2(80) := MESSAGE_TEXT;
BEGIN
  IF lv_errcod = 40350 THEN
    alert_button := Show_Alert('continue_alert');
    IF alert_button = ALERT_BUTTON1 THEN
      ...
    ELSE
      ...
    END IF;
  ELSE
    Message(lv_errtyp||'-'||to_char(lv_errcod)||':  '||lv_errtxt);
    RAISE Form_Trigger_Failure;
  END IF;
    IF form_fatal OR form_failure THEN
     raise form_trigger_failure;
  END IF;

END;


On-Populate-Details Trigger

 All Triggers

Description

Form Builder creates this trigger automatically when a Master/Detail relation is defined.  It fires when Form Builder would normally need to populate the detail block in a Master/Detail relation.

Definition Level  form, block

Legal Commands

SELECT statements, PL/SQL, unrestricted built-ins, restricted built-ins

Enter Query Mode  no

Usage Notes

Use an On-Populate-Details trigger when you have established a Master/Detail relationship and you want to replace the default populate phase of a query.

The On-Populate-Details trigger does not fire unless an On-Clear-Details trigger is present.  If you are using the default Master/Detail functionality, Form Builder creates the necessary triggers automatically.  However, if you are writing your own Master/Detail logic, be aware that the On-Clear-Details trigger must be present, even if it contains only the NULL statement.

When Immediate coordination is set, this causes the details of the instantiated master to be populated immediately.  Immediate coordination is the default.

When Deferred coordination is set and this trigger fires, Form Builder marks the blocks as needing to be coordinated.

If you intend to manage block coordination yourself, you can call the SET_BLOCK_PROPERTY (COORDINATION_STATUS) built-in.

On Failure

Can cause an inconsistent state in the form.

Fires In

Master/Detail Coordination

See Process Flowcharts


On-Rollback Trigger

  Related Topics	 All Triggers

Description

Fires when Form Builder would normally issue a ROLLBACK statement, to roll back a transaction to the last savepoint that was issued.

Definition Level  form

Legal Commands

SELECT statements, PL/SQL, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use an On-Rollback trigger to replace standard Form Builder rollback processing.

To perform default Form Builder processing from this trigger, include a call to the ISSUE_ROLLBACK built-in.

Fires In

CLEAR_FORM

Post and Commit Transactions

ROLLBACK_FORM

See Process Flowcharts


On-Savepoint Trigger

  Related Topics	 All Triggers

Description

Fires when Form Builder would normally issue a Savepoint statement.  By default, Form Builder issues savepoints at form startup, and at the start of each Post and Commit Transaction process.

Definition Level  form

Legal Commands

SELECT statements, PL/SQL, unrestricted built-ins

Enter Query Mode  no

Usage Notes

To perform default Form Builder processing from this trigger, include a call to the ISSUE_SAVEPOINT built-in.

In an On-Savepoint trigger, the  Savepoint_Name application property returns the name of the next savepoint that Form Builder would issue by default, if no On-Savepoint trigger were present.  In an On-Rollback trigger , Savepoint_Name returns the name of the savepoint to which Form Builder would roll back.

Suppress default savepoint processing by setting the Savepoint Mode form document property to Off.  When Savepoint Mode is Off, Form Builder does not issue savepoints and, consequently, the On-Savepoint trigger never fires.

On Failure

no effect

Fires In

CALL_FORM

Post and Commit Transactions

SAVEPOINT

See Process Flowcharts


On-Select Trigger

 Examples	     Related Topics	 All Triggers

Description

Fires when Form Builder would normally execute the open cursor, parse, and execute phases of a query, to identify the records in the database that match the current query criteria.

Definition Level  form or block

Legal Commands

SELECT statements, PL/SQL, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use an On-Select trigger to open and execute the database cursor.  Specifically, use this trigger when you are retrieving data from a non-ORACLE data source.  The On-Select trigger can be used in conjunction with the On-Fetch trigger to replace the processing that normally occurs in the EXECUTE_QUERY built-in subprogram.

To perform the default Form Builder processing from this trigger, include a call to the SELECT_RECORDS built-in.

On Failure

no effect

Fires In

EXECUTE_QUERY

Open The Query

See Process Flowcharts


On-Select Trigger examples

Example

In the following example, the On-Select trigger is used to call a user exit, 'Query,' and a built-in subprogram, SELECT_RECORDS, to perform a query against a database.

IF Get_Application_Property(DATASOURCE) = 'DB2' THEN
  User_Exit ( 'Query' );
  IF Form_Failure OR Form_Fatal THEN
    ABORT_QUERY;
  END IF;
ELSE
  /*
  **  Perform the default Form Builder task of opening the query.
  */
  Select_Records;
END IF;


On-Sequence-Number Trigger

 All Triggers

Description

Fires when Form Builder would normally perform the default processing for generating sequence numbers for default item values.  Replaces the default series of events that occurs when Form Builder interacts with the database to get the next value from a SEQUENCE object defined in the database.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

When a SEQUENCE is used as a default item value, Form Builder queries the database to get the next value from the SEQUENCE whenever the Create Record event occurs.  Suppress or override this functionality with an On-Sequence-Number trigger.

To perform the default Form Builder processing from this trigger, call the GENERATE_SEQUENCE_NUMBER built-in.

On Failure

no effect

Fires In

GENERATE_SEQUENCE_NUMBER

See Process Flowcharts


On-Update Trigger

 All Triggers

Description

Fires during the Post and Commit Transactions process while updating a record.  Specifically, it fires after the Pre-Update trigger fires and before the Post-Update trigger fires, when Form Builder would normally update a record in the database.  It fires once for each row that is marked for update in the form.

Definition Level  form or block

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use an On-Update trigger to replace the default Form Builder processing for handling updated records during transaction posting.

To perform the default Form Builder processing from this trigger, include a call to the UPDATE_RECORD built-in.

On Failure

Form Builder performs the following steps when the On-Update trigger fails:

•	sets the error location

•	rolls back to the most recently issued savepoint

Fires In

Post and Commit Transactions

See Process Flowcharts


Post-Block Trigger

 Restrictions	 All Triggers

Description

Fires during the Leave the Block process when the focus moves off the current block.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Block trigger to validate the block's current record; that is, the record that had input focus when the Leave the Block event occurred.

Use this trigger to test a condition and prevent the user from leaving a block based on that condition.

On Failure

If the trigger fails while trying to make the form the navigation unit, Form Builder tries to set the target to a particular block, record or item.  Failing that, Form Builder attempts to put the cursor at a target location, but, if the target is outside of the current unit or if the operator indicates an end to the process, Form Builder aborts the form.

Fires In

Leave the Block

See Process Flowcharts


Post-Block Trigger restrictions

A Post-Block trigger does not fire when the Validation Unit form document property is set to Form.


Post-Change Trigger

 Restrictions	    Related Topics	 All Triggers

Description

Fires when any of the following conditions exist:

•	The Validate the Item process determines that an item is marked as Changed and is not NULL.

•	An operator returns a value into an item by making a selection from a list of values, and the item is not NULL.

•	Form Builder fetches a non-NULL value into an item.  In this case, the When-Validate-Item trigger does not fire.  If you want to circumvent this situation and effectively get rid of the Post-Change trigger, you must include a Post-Query trigger in addition to your When-Validate-Item trigger.  See "Usage Notes" below.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

The Post-Change trigger is included only for compatibility with previous versions of Form Builder.  Its use is not recommended in new applications.

The Post-Query trigger does not have the restrictions of the Post-Change trigger.  You can use Post-Query to make changes to the fetched database values.  Given such changes, Form Builder marks the corresponding items and records as changed.

On Failure

If fired as part of validation initiated by navigation, navigation fails, and the focus remains in the original item.

If there are V2-style triggers in the form and Form Builder is populating a record with fetched values, the following restrictions apply:

•	Form Builder ignores any attempt to change the value of a database item in the record.

•	Form Builder does not execute any SELECT statement that only affects database items in the record.

•	Form Builder does not execute a SELECT statement that does not have an INTO clause.

•	If Form Builder does not execute a SELECT statement in a V2-style trigger step, it treats the trigger step as though the step succeeded, even when the Reverse Return Code trigger step property is set.

During fetch processing, Post-Change triggers defined as PL/SQL triggers do not operate with these restrictions.  Regardless of trigger style, during a record fetch, Form Builder does not perform validation checks, but marks the record and its items as Valid, after firing the Post-Change trigger for each item.

Fires In

Validate the Item

Fetch Records

See Process Flowcharts


Post-Change Trigger restrictions

Note that it is possible to write a Post-Change trigger that changes the value of an item that Form Builder is validating.  If validation succeeds, Form Builder marks the changed item as Valid and does not re-validate it.  While this behavior is necessary to avoid validation loops, it does allow you to commit an invalid value to the database.


Post-Database-Commit Trigger

 Examples	     Related Topics	 All Triggers

Description

Fires once during the Post and Commit Transactions process, after the database commit occurs.  Note that the Post-Forms-Commit trigger fires after inserts, updates, and deletes have been posted to the database, but before the transaction has been finalized by issuing the Commit.  The Post-Database-Commit Trigger fires after Form Builder issues the Commit to finalize the transaction.

Definition Level  form

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Database-Commit trigger to perform an action anytime a database commit has occurred.

On Failure

There is no rollback, because at the point at which this trigger might fail, Form Builder has already moved past the point at which a successful rollback operation can be initiated as part of a failure response.

Fires In

Post and Commit Transactions

See Process Flowcharts


Post-Database-Commit Trigger examples

Example

/*

** FUNCTION recs_posted_and_not_committed
**  RETURN BOOLEAN IS
** BEGIN
**  Default_Value('TRUE','Global.Did_DB_Commit');
**  RETURN (:System.Form_Status = 'QUERY'
**         AND :Global.Did_DB_Commit = 'FALSE');
** END;
*/
BEGIN
  :Global.Did_DB_Commit := 'FALSE';
END;


Post-Delete Trigger

 All Triggers

Description

Fires during the Post and Commit Transactions process, after a row is deleted.  It fires once for each row that is deleted from the database during the commit process.

Definition Level  form or block

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Delete trigger to audit transactions.

On Failure

Form Builder performs the following steps when the Post-Delete trigger fails:

•	sets the error location

•	rolls back to the most recent savepoint

Fires In

Post and Commit Transactions

See Process Flowcharts


Post-Form Trigger

 All Triggers

Description

Fires during the Leave the Form process, when a form is exited.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Form trigger for the following tasks:

•	To clean up the form before exiting.  For example, use a Post-Form trigger to erase any global variables that the form no longer requires.

•	To display a message to the operator upon form exit.

This trigger does not fire when the form is exited abnormally, for example, if validation fails in the form.

On Failure

processing halts

Fires In

Leave the Form

See Process Flowcharts


Post-Forms-Commit Trigger

 Examples	     Related Topics	 All Triggers

Description

Fires once during the Post and Commit Transactions process.  If there are records in the form that have been marked as inserts, updates, or deletes, the Post-Forms-Commit trigger fires after these changes have been written to the database but before Form Builder issues the database Commit to finalize the transaction.

If the operator or the application initiates a Commit when there are no records in the form have been marked as inserts, updates, or deletes, Form Builder fires the Post-Forms-Commit trigger immediately, without posting changes to the database.

Definition Level  form

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Forms-Commit trigger to perform an action, such as updating an audit trail, anytime a database commit is about to occur.

On Failure

Aborts post and commit processing: Form Builder issues a ROLLBACK and decrements the internal Savepoint counter.

Fires In

Post and Commit Transactions

See Process Flowcharts


Post-Forms-Commit Trigger examples

Example

This example can be used in concert with the Post-Database-Commit trigger to detect if records have been posted but not yet committed.

/*
** FUNCTION recs_posted_and_not_committed
** RETURN BOOLEAN IS
** BEGIN
**    Default_Value('TRUE','Global.Did_DB_Commit');
**    RETURN (:System.Form_Status = 'QUERY'
**       AND :Global.Did_DB_Commit = 'FALSE');
** END;
*/
BEGIN
  :Global.Did_DB_Commit := 'FALSE';
END;


Post-Insert Trigger

 All Triggers

Description

Fires during the Post and Commit Transactions process, just after a record is inserted.  It fires once for each record that is inserted into the database during the commit process.

Definition Level  form or block

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Insert trigger to audit transactions.

On Failure

Form Builder performs the following steps when the Post-Insert trigger fails:

•	sets the error location

•	rolls back to the most recent savepoint

Fires In

Post and Commit Transactions

See Process Flowcharts


Post-Logon Trigger

 Examples	  Related Topics	 All Triggers

Description

Fires after either of the following events:

•	The successful completion of Form Builder default logon processing.

•	The successful execution of the On-Logon trigger.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Logon trigger to provide an event point for a task such as setting up a custom environment with special variables--to initialize on an application level rather than a form-by-form basis.  You might accomplish this by initializing special global variables from this trigger.

On Failure

Varies based on the following conditions:

•	If the trigger fails during the first logon process, Form Builder exits the form, and returns to the operating system.

•	If the trigger fails after a successful logon, Form Builder raises the built-in exception FORM_TRIGGER_FAILURE .

Fires In

LOGON

See Process Flowcharts


Post-Logon Trigger examples

Example

This example calls a user exit to log the current username and time to an encrypted audit trail file on the file system, which for security reasons is outside the database.

BEGIN
  User_Exit('LogCrypt '||
            USER||' '  ||
            TO_CHAR(SYSDATE,'YYYYMMDDHH24MISS'));
END;


Post-Logout Trigger

  Related Topics	 All Triggers

Description

Fires after either of the following events:

•	Form Builder successfully logs out of ORACLE.

•	The successful execution of the On-Logout trigger.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Logout trigger to audit or to perform tasks on an Form Builder application that does not require or affect the RDBMS or other data source.

If you call certain built-ins from within one of the Logout triggers, the results are undefined.  For example, you cannot call COPY from a Pre-Logout trigger because Pre-Logout fires after the Leave the Form event.  Because the form is no longer accessible, a COPY operation is not possible.

On Failure

If this trigger fails while leaving the form, there is no effect.

If this trigger fails and you have initiated a call to the LOGOUT built-in from within the trigger, FORM_FAILURE is set to TRUE.

Fires In

LOGOUT

See Process Flowcharts


Post-Query Trigger

 Examples	     Related Topics	 All Triggers

Description

When a query is open in the block, the Post-Query trigger fires each time Form Builder fetches a record into a block.  The trigger fires once for each record placed on the block's list of records.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Query trigger to perform the following tasks:

•	populate control items or items in other blocks

•	calculate statistics about the records retrieved by a query

•	calculate a running total

•	When you use a Post-Query trigger to SELECT non-base table values into control items, Form Builder marks each record as CHANGED, and so fires the When-Validate-Item trigger by default.  You can avoid the execution of the When-Validate-Item trigger by explicitly setting the Status property of each record to QUERY in the Post-Query trigger.  To set record status programmatically, use SET_RECORD_PROPERTY .

On Failure

Form Builder flushes the record from the block and attempts to fetch the next record from the database.  If there are no other records in the database, Form Builder closes the query and waits for the next operator action.

Fires In

Fetch Records

See Process Flowcharts


Post-Query Trigger examples

Example

This example retrieves descriptions for code fields, for display in non-database items in the current block.

DECLARE

  CURSOR lookup_payplan IS SELECT Payplan_Desc
                             FROM Payplan
                            WHERE Payplan_Id =
                                  :Employee.Payplan_Id;

  CURSOR lookup_area    IS SELECT Area_Name
                             FROM Zip_Code
                             WHERE Zip = :Employee.Zip;

BEGIN
  /*
  ** Lookup the Payment Plan Description given the
  ** Payplan_Id in the Employee Record just fetched.
  ** Use Explicit Cursor for highest efficiency.
  */
  OPEN lookup_payplan;
  FETCH lookup_payplan INTO :Employee.Payplan_Desc_Nondb;
  CLOSE lookup_payplan;

  /*
  ** Lookup Area Descript given the Zipcode in
  ** the Employee Record just fetched. Use Explicit
  ** Cursor for highest efficiency.
  */
  OPEN lookup_area;
  FETCH lookup_area INTO :Employee.Area_Desc_Nondb;
  CLOSE lookup_area;
END;


Post-Record Trigger

 Restrictions	 All Triggers

Description

Fires during the Leave the Record process.  Specifically, the Post-Record trigger fires whenever the operator or the application moves the input focus from one record to another.  The Leave the Record process can occur as a result of numerous operations, including INSERT_RECORD , DELETE_RECORD , NEXT_RECORD , NEXT_BLOCK , CREATE_RECORD , PREVIOUS_BLOCK , etc.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Record trigger to perform an action whenever the operator or the application moves the input focus from one record to another.  For example, to set a visual attribute for an item as the operator scrolls down through a set of records, put the code within this trigger.

On Failure

The input focus stays in the current record.

Fires In

Leave the Record

See Process Flowcharts


Post-Record Trigger restrictions

A Post-Record trigger fires only when the form is run with a validation unit of the item or record, as specified by the Validation Unit form property.


Post-Select Trigger

 All Triggers

Description

The Post-Select trigger fires after the default selection phase of query processing, or after the successful execution of the On-Select trigger.  It fires before any records are actually retrieved through fetch processing.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Note:

Use the Post-Select trigger to perform an action based on the outcome of the Select phase of query processing such as an action based on the number of records that match the query criteria.

On Failure

no effect

Fires In

Execute the Query

Open the Query

See Process Flowcharts


Post-Text-Item Trigger

 Restrictions	    Related Topics	 All Triggers

Description

Fires during the Leave the Item process for a text item.  Specifically, this trigger fires when the input focus moves from a text item to any other item.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Text-Item trigger to calculate or change item values.

On Failure

Navigation fails and focus remains in the text item.

Fires In

Leave the Item

See Process Flowcharts


Post-Text-Item Trigger restrictions

The Post-Text-Item trigger does not fire when the input focus is in a text item and the operator uses the mouse to click on a button, check box, list item, or radio group item that has the Mouse Navigate property Off.  When Mouse Navigate is Off for these items, clicking them with the mouse is a non-navigational event, and the input focus remains in the current item (in this example, a text item).


Post-Update Trigger

 All Triggers

Description

Fires during the Post and Commit Transactions process, after a row is updated.  It fires once for each row that is updated in the database during the commit process.

Definition Level  form or block

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted function codes, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Post-Update trigger to audit transactions.

On Failure

Form Builder performs the following steps when the Post-Update trigger fails:

•	sets the error location

•	rolls back to the most recent savepoint

Fires In

Post and Commit Transactions

See Process Flowcharts


Pre-Block Trigger

 Restrictions	 All Triggers

Description

Fires during the Enter the Block process, during navigation from one block to another.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Block trigger to:

•	allow or disallow access to a block

•	set variable values

On Failure

Navigation fails and focus remains in the source item.

Fires In

Enter the Block

See Process Flowcharts


Pre-Block Trigger restrictions

A Pre-Block trigger fires only when the form is run with a validation unit of the item, record, or block, as specified by the Validation Unit form property.


Pre-Commit Trigger

 All Triggers

Description

Fires once during the Post and Commit Transactions process, before Form Builder processes any records to change.  Specifically, it fires after Form Builder determines that there are inserts, updates, or deletes in the form to post or commit, but before it commits the changes.  The trigger does not fire when there is an attempt to commit, but validation determines that there are no changed records in the form.

Definition Level  form

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Commit trigger to perform an action, such as setting up special locking requirements, at any time a database commit is going to occur.

On Failure

The Post and Commit process fails: No records are written to the database and focus remains in the current item.

Note:  If you perform DML in a Pre-Commit trigger and the trigger fails, you must perform a manual rollback, because Form Builder does not perform an automatic rollback.  To prepare for a possible manual rollback, save the savepoint name in an On-Savepoint trigger, using  GET_APPLICATION_PROPERTY (Savepoint_Name).  Then you can roll back using ISSUE_ROLLBACK (Savepoint_Name).

Fires In

Post and Commit Transactions

See Process Flowcharts


Pre-Delete Trigger

 All Triggers

Description

Fires during the Post and Commit Transactions process, before a row is deleted.  It fires once for each record that is marked for delete.

Note:  Form Builder creates a Pre-Delete trigger automatically for any master-detail relation that has the Delete Record Behavior property set to Cascading

Definition Level  form or block

Legal Commands

SELECT statements, Data Manipulation Language (DML) statements (i.e., DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Delete trigger to delete the detail record of a master record.

Use a Pre-Delete trigger to prevent the deletion of a record if that record is the master record for detail records that still exist.

On Failure

Form Builder performs the following steps when the Pre-Delete trigger fails:

•	sets the error location

•	rolls back to the most recent savepoint

Fires In

Post and Commit Transactions

See Process Flowcharts


Pre-Form Trigger

  Related Topics	 All Triggers

Description

Fires during the Enter the Form event, at form startup.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Form trigger to perform the following tasks:

•	assign unique primary key from sequence

•	restrict access to a form

•	initialize global variables

On Failure

Form Builder leaves the current form and fires no other triggers.

Fires In

Enter the Form

See Process Flowcharts


Pre-Insert Trigger

 Examples	 All Triggers

Description

Fires during the Post and Commit Transactions process, before a row is inserted.  It fires once for each record that is marked for insert.

Definition Level  form or block

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Insert trigger to perform the following tasks:

•	change item values

•	keep track of the date a record is created and store that in the record prior to committing

On Failure

Form Builder performs the following steps when the Pre-Insert trigger fails:

•	sets the error location

•	rolls back to the most recent savepoint

Fires In

Post and Commit Transactions

See Process Flowcharts


Pre-Insert Trigger examples

Example

This example assigns a primary key field based on a sequence number, and then writes a row into an auditing table, flagging creation of a new order.

DECLARE
  CURSOR next_ord IS SELECT orderid_seq.NEXTVAL FROM dual;
BEGIN

  /*
  ** Fetch the next sequence number from the
  ** explicit cursor directly into the item in
  ** the Order record. Could use SELECT...INTO,
  ** but explicit cursor is more efficient.
  */
  OPEN next_ord;
  FETCH next_ord INTO :Order.OrderId;
  CLOSE next_ord;

  /*
  ** Make sure we populated a new order id ok...
  */
  IF :Order.OrderId IS NULL THEN
    Message('Error Generating Next Order Id');
    RAISE Form_Trigger_Failure;
  END IF;

  /*
  ** Insert a row into the audit table
  */
  INSERT INTO ord_audit( orderid, operation, username, timestamp )
  VALUES ( :Order.OrderId,
           'New Order',
           USER,
           SYSDATE );

END;


Pre-Logon Trigger

 All Triggers

Description

Fires just before Form Builder initiates a logon procedure to the data source.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Logon trigger to prepare the form for the logon procedure, particularly to a non-ORACLE data source.

On Failure

The results of a failure depend on which of the following conditions applies:

•	If Form Builder is entering the form for the first time and the trigger fails, the form is exited gracefully, but no other triggers are fired.

•	If the trigger fails while Form Builder is attempting to execute the LOGON built-in from within the trigger, Form Builder raises the FORM_TRIGGER_FAILURE exception.

Fires In

LOGON

See Process Flowcharts


Pre-Logout Trigger

 All Triggers

Description

Fires once before Form Builder initiates a logout procedure.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Logout trigger to prepare the form for logging out from the data source, particularly a non-ORACLE data source.

If you call certain built-ins from within one of the Logout triggers, the results are undefined.  For example,  the COPY built-in cannot be called from a Pre-Logout trigger because Pre-Logout fires after the Leave the Form event.  Because the form is no longer accessible at this point, the COPY operation is not possible.

On Failure

The results of a failure depend on which of the following conditions applies:

•	If Form Builder is exiting the form and the trigger fails, the form is exited gracefully, but no other triggers are fired.

•	If the trigger fails while Form Builder is attempting to execute the LOGOUT built-in from within the trigger, Form Builder raises the FORM_TRIGGER_FAILURE exception.

If an exception is raised in a Pre-Logout trigger, Form Builder does not fire other triggers, such as On-Logout and Post-Logout .

Fires In

LOGOUT

See Process Flowcharts


Pre-Popup-Menu Trigger

 All Triggers

Description

This trigger is called when a user causes a pop-up menu to be displayed.  (In a Microsoft Windows environment, this occurs when a user presses the right mouse button.)  Actions defined for this trigger are performed before the pop-up menu is displayed.

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode yes

Usage Notes

Use this trigger to enable or disable menu items on a pop-up menu before it is displayed.

On Failure

No effect


Pre-Query Trigger

 Examples	     Related Topics	 All Triggers

Description

Fires during Execute Query or Count Query processing, just before Form Builder constructs and issues the SELECT statement to identify rows that match the query criteria.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Query trigger to modify the example record that determines which rows will be identified by the query.

On Failure

The query is canceled.  If the operator or the application had placed the form in Enter Query mode, the form remains in Enter Query mode.

Fires In

COUNT_QUERY

EXECUTE_QUERY

Open the Query

Prepare the Query

See Process Flowcharts


Pre-Query Trigger examples

Example

This example validates or modifies query criteria for a database block query.

BEGIN
  /*
  ** Set the ORDER BY clause for the current block
  ** being queried, based on a radio group
  ** called 'Sort_Column' in a control block named
  ** 'Switches'. The Radio Group has three buttons
  ** with character values giving the names of
  ** three different columns in the table this
  ** block is based on:
  **
  **     SAL
  **     MGR,ENAME
  **     ENAME
  */
  Set_Block_Property('EMP',ORDER_BY, :Switches.Sort_Column);
  /*
  ** Make sure the user has given one of the two
  ** Columns which we have indexed in their search
  ** criteria, otherwise fail the query with a helpful
  ** message
  */
  IF :Employee.Ename IS NULL AND :Employee.Mgr IS NULL THEN
    Message('Supply Employee Name and/or Manager Id '||
            'for Query.');
    RAISE Form_Trigger_Failure;
  END IF;

  /*
  ** Change the default where clause to either show "Current
  ** Employees Only" or "Terminated Employees" based on the
  ** setting of a check box named 'Show_Term' in a control
  ** block named 'Switches'.
  */
  IF Check box_Checked('Switches.Show_Term') THEN
    Set_Block_Property('EMP',DEFAULT_WHERE,'TERM_DATE IS NOT NULL');
  ELSE
    Set_Block_Property('EMP',DEFAULT_WHERE,'TERM_DATE IS NULL');
  END IF;
END;


Pre-Record Trigger

 Examples	   Restrictions	    Related Topics	 All Triggers

Description

Fires during the Enter the Record process, during navigation to a different record.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Record trigger to keep a running total.

On Failure

Navigation fails and focus remains in the current item.

Fires In

Enter the Record

See Process Flowcharts


Pre-Record Trigger restrictions

A Pre-Record trigger fires only when the form is run with a validation unit of the item or record, as specified by the Validation Unit form property.


Pre-Record Trigger examples

Example

The following trigger prevents the user from entering a new record given some dynamic condition and the status of SYSTEM.RECORD_STATUS evaluating to NEW.

IF (( dynamic-condition)
   AND :System.Record_Status = 'NEW') THEN
   RAISE Form_Trigger_Failure;
END IF;


Pre-Select Trigger

  Related Topics	 All Triggers

Description

Fires during Execute Query and Count Query processing, after Form Builder constructs the SELECT statement to be issued, but before the statement is actually issued.  Note that the SELECT statement can be examined in a Pre-Select trigger by reading the value of  the system variable SYSTEM.LAST_QUERY .

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Select trigger to prepare a query prior to execution against a non-ORACLE data source.

On Failure

No effect. The current query fetched no records from the table. The table is empty, or it contains no records that meet the query's search criteria.

Fires In

EXECUTE_QUERY

Open the Query

Prepare the Query

See Process Flowcharts


Pre-Text-Item Trigger

 Restrictions

Description

Fires during the Enter the Item process, during navigation from an item to a text item.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Text-Item trigger to perform the following types of tasks:

•	derive a complex default value, based on other items previously entered into the same record.

•	record the current value of the text item for future reference, and store that value in a global variable or form parameter.

On Failure

Navigation fails and focus remains in the current item.

Fires In

Enter the Item

See Process Flowcharts


Pre-Text-Item Trigger restrictions

A Pre-Text-Item trigger fires only when the form is run with a validation unit of the item, as specified by the Validation Unit form property.


Pre-Update Trigger

 Examples	 All Triggers

Description

Fires during the Post and Commit Transactions process, before a row is updated.  It fires once for each record that is marked for update.

Definition Level  form or block

Legal Commands

SELECT statements, DML statements (DELETE, INSERT, UPDATE), unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a Pre-Update trigger to audit transactions.

On Failure

Form Builder performs the following steps when the Pre-Update trigger fails:

•	sets the error location

•	rolls back to the most recent savepoint

Fires In

Post and Commit Transactions

See Process Flowcharts


Pre-Update Trigger examples

Example

The following example writes a row into an Audit Table showing old discount and new discount for a given customer, including timestamp and username making the change.

DECLARE
  old_discount NUMBER;
  new_discount NUMBER := :Customer.Discount_Pct;
  oper_desc    VARCHAR2(80);
  CURSOR old_value IS SELECT discount_pct FROM customer
                      WHERE CustId = :Customer.CustId;
BEGIN
  /*
  ** Fetch the old value of discount percentage from the
  ** database by CustomerId. We need to do this since the
  ** value of :Customer.Discount_Pct will be the *new* value
  ** we're getting ready to commit and we want to record for
  ** posterity the old and new values. We could use
  ** SELECT...INTO but choose an explicit cursor for
  ** efficiency.
  */
  OPEN old_value;
  FETCH old_value INTO old_discount;
  CLOSE old_value;

  /*
  ** If the old and current values are different, then
  ** we need to write out an audit record
  */
  IF old_discount <> new_discount THEN
    /*
    ** Construct a string that shows the operation of
    ** Changing the old value to the new value. e.g.
    **
    **   'Changed Discount from 13.5% to 20%'
    */
    oper_desc := 'Changed Discount from '||
                 TO_CHAR(old_discount)||'% to '||
                 TO_CHAR(new_discount)||'%';

    /*
    ** Insert the audit record with timestamp and user
    */
    INSERT INTO cust_audit( custid, operation, username,
       timestamp )
    VALUES ( :Customer.CustId,
             oper_desc,
             USER,
             SYSDATE );
  END IF;
END;


Query-Procedure Trigger

 All Triggers

Description

Automatically created by Form Builder when the query data source is a stored procedure. This trigger is called when a query operation is necessary. Think of this as an On-Query trigger that is called by the system instead of doing default query operations.

Do not modify this trigger.

Enter Query Mode See Usage Notes

Usage Notes

When constructing a query, any of the items may be used, but the Query Data Source Columns property must be set so that those items can be passed to the query stored procedure.  Then, the query stored procedure has to use those values to filter the data.  This means that the enter query mode does not happen automatically unless you specify it.

On Failure

No effect


Update-Procedure Trigger

 All Triggers

Description

Automatically created by Form Builder when the update data source is a stored procedure.  This trigger is called when a update operation is necessary.  Think of this as an On-Update trigger that is called by the system instead of doing default update operations.

Do not modify this trigger.

Enter Query Mode Not applicable.

On Failure

No effect


User-Named Trigger

 All Triggers

Description

A user-named trigger is a trigger defined in a form by the developer.  User-Named triggers do not automatically fire in response to a Form Builder event, and must be called explicitly from other triggers or user-named subprograms.  Each user-named trigger defined at the same definition level must have a unique name.

To execute a user-named trigger, you must call the EXECUTE_TRIGGER built-in procedure, as shown here:

Execute_Trigger('my_user_named_trigger');

Definition Level  form, block, or item

Legal Commands

Any commands that are legal in the parent trigger from which the user-named trigger was called.

Enter Query Mode  no

Usage Notes

User-named PL/SQL subprograms can be written to perform almost any task for which one might use a user-named trigger.

As with all triggers, the scope of a user-named trigger is the definition level and below.  When more than one user-named trigger has the same name, the trigger defined at the lowest level has precedence.

It is most practical to define user-named triggers at the form level.

Create a user-named trigger to execute user-named subprograms defined in a form document from menu PL/SQL commands and user-named subprograms.  (User-named subprograms defined in a form cannot be called directly from menu PL/SQL, which is defined in a different document.)  In the menu PL/SQL, call the EXECUTE_TRIGGER built-in to execute a user-named trigger, which in turn calls the user-named subprogram defined in the current form.

On Failure

Sets the FORM_FAILURE built-in to TRUE.  Because the user-named trigger is always called by the EXECUTE_TRIGGER built-in, you can test the outcome of a user-named trigger the same way you test the outcome of a built-in subprogram; that is, by testing for errors with the built-in functions FORM_FAILURE, FORM_SUCCESS, FORM_FATAL .


When-Button-Pressed Trigger

 Examples	 All Triggers

Description

Fires when an operator selects a button, by clicking with a mouse, or using the keyboard.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Use a When-Button-Pressed trigger to perform navigation, to calculate text item values, or for other item, block, or form level functionality.

On Failure

no effect


When-Button-Pressed Trigger examples

Example

This example executes a COMMIT_FORM if there are changes in the form.

BEGIN
  IF :System.Form_Status = 'CHANGED' THEN
    Commit_Form;
    /*
    ** If the Form_Status is not back to 'QUERY'
    ** following a commit, then the commit was
    ** not successful.
    */
    IF :System.Form_Status <> 'QUERY' THEN
      Message('Unable to commit order to database...');
      RAISE Form_Trigger_Failure;
    END IF;
  END IF;
END;


When-Checkbox-Changed Trigger

 All Triggers

Description

Fires when an operator changes the state of a check box, either by clicking with the mouse, or using the keyboard.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Use a When-Checkbox-Changed trigger to initiate a task dependent upon the state of a check box.

When an operator clicks in a check box, the internal value of that item does not change until navigation is completed successfully.  Thus, the When-Checkbox-Changed trigger is the first trigger to register the changed value of a check box item.  So for all navigation triggers that fire before the When-Checkbox-Changed trigger, the value of the check box item remains as it was before the operator navigated to it.

On Failure

no effect


When-Clear-Block Trigger

  Related Topics	 All Triggers

Description

Fires just before Form Builder clears the data from the current block.

Note that the When-Clear-Block trigger does not fire when Form Builder clears the current block during the CLEAR_FORM event.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

•	Use a When-Clear-Block trigger to perform an action every time Form Builder flushes the current block.  For example, you might want to perform an automatic commit whenever this condition occurs.

•	In a When-Clear-Block trigger, the value of SYSTEM.RECORD_STATUS is unreliable because there is no current record.  An alternative is to use GET_RECORD_PROPERTY to obtain the record status.  Because GET_RECORD_PROPERTY requires reference to a specific record, its value is always accurate.

On Failure

no effect on the clearing of the block

Fires In

CLEAR_BLOCK

COUNT_QUERY

ENTER_QUERY

Open the Query

See Process Flowcharts


When-Create-Record Trigger

 Examples	  Related Topics	 All Triggers

Description

Fires when Form Builder creates a new record.  For example, when the operator presses the [Insert] key, or navigates to the last record in a set while scrolling down, Form Builder fires this trigger.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a When-Create-Record trigger to perform an action every time Form Builder attempts to create a new record.  This trigger also is useful for setting complex, calculated, or data-driven default values that must be specified at runtime, rather than at design-time.

On Failure

Prevents the new record from being created. Returns to the previous location, if possible.

Fires In

CREATE_RECORD

See Process Flowcharts


When-Create-Record Trigger examples

Example

This example assigns data-driven or calculated default values without marking the record as changed.

DECLARE
  CURSOR ship_dflt IS SELECT val
                        FROM cust_pref
                       WHERE Custid = :Customer.Custid
                         AND pref   = 'SHIP';
BEGIN
  /*
  ** Default Invoice Due Date based on Customer's
  ** Net Days Allowed value from the Customer block.
  */
  :Invoice.Due_Date := SYSDATE + :Customer.Net_Days_Allowed;
  /*
  ** Default the shipping method based on this customers
  ** preference, stored in a preference table. We could
  ** use SELECT...INTO, but explicit cursor is more
  ** efficient.
  */
  OPEN ship_dflt;
  FETCH ship_dflt INTO :Invoice.Ship_Method;
  CLOSE ship_dflt;
END;


When-Custom-Item-Event Trigger

 Examples	     Related Topics	 All Triggers

Description

Fires whenever a JavaBean or ActiveX (on 32-bit Windows) or VBX (on 16-bit Microsoft Windows 3.x) custom component in the form causes the occurrence of an event.

Definition Level:

form, block, item

Legal Commands:

unrestricted built-ins, restricted built-ins

Enter Query Mode:

yes

Usage Notes

Use a When-Custom-Item-Event trigger to respond to a selection or change of value of a custom component.  The system variable SYSTEM.CUSTOM_ITEM_EVENT stores the name of the event that occurred, and the system variable SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS stores a parameter name that contains the supplementary arguments for an event that is fired by a custom control.

Control event names are case sensitive.

On Failure:

no effect


When-Custom-Item-Event Trigger examples

JavaBeans Example

This is an example of a procedure called by a When-Custom-Item-Event trigger in a form that uses two JavaBeans.  (For the context, see the complete example.)

The trigger is fired by the dispatching of a custom event in one of the JavaBeans, in response to a change in value.

     CustomEvent ce = new CustomEvent(mHandler, VALUECHANGED);

     dispatchCustomEvent(ce);

In the form, the When_Custom_Item_Event trigger that is attached to this JavaBean’s Bean Area item is automatically fired in response to that custom event.

In the trigger code, it executes the following procedure.  Note that this procedure picks up the new values set in the JavaBean container (a new animation rate, for example) by accessing the System.Custom_Item_Event_Parameters.

In this example, the procedure then uses the Set_Custom_Item_Property built-in to pass those values to the other JavaBean.

PROCEDURE Slider_Event_Trap IS

  BeanHdl          Item;

BeanValListHdl   ParamList;

paramType        Number;

EventName        VarChar2(20);

CurrentValue     Number(4);

NewAnimationRate Number(4);

Begin

-- Update data items and Display fields with current radius information

BeanValListHdl := get_parameter_list(:SYSTEM.Custom_Item_Event_Parameters);

EventName      := :SYSTEM.Custom_Item_Event;

:event_name    := EventName;

if (EventName = 'ValueChanged') then

   get_parameter_attr(BeanValListHdl,'Value',ParamType, CurrentValue);

   NewAnimationRate := (300 - CurrentValue);

   :Animation_Rate  := NewAnimationRate;

     set_custom_item_property('Juggler_Bean','SetAnimationRate', NewAnimationRate);

elsif (EventName = 'mouseReleased') then

   get_parameter_attr(BeanValListHdl,'Value',ParamType, CurrentValue);

     set_custom_item_property('Juggler_Bean','SetAnimationRate', CurrentValue);

  end if;

End;

VBX Example

This is an example of a procedure that can be called when Form Builder fires the When-Custom-Item-Event Trigger.

DECLARE
 TabEvent  varchar2(80);
 TabNumber Number;
BEGIN
 TabEvent := :system.custom_item_event;
 /*
 ** After detecting a Click event, identify the
 ** tab selected, and use the user-defined Goto_Tab_Page
 ** procedure to navigate to the selected page.
 */
 IF (UPPER(TabEvent) = 'CLICK') THEN
  TabNumber := VBX.Get_Property('TABCONTROL','CurrTab');
  Goto_Tab_Page(TabNumber);
 END IF;
END;


When-Database-Record Trigger

 All Triggers

Description

Fires when Form Builder first marks a record as an insert or an update.  That is, the trigger fires as soon as Form Builder determines through validation that the record should be processed by the next post or commit as an insert or update.  This generally occurs only when the operator modifies the first item in a record, and after the operator attempts to navigate out of the item.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a When-Database-Record trigger to perform an action every time a record is first marked as an insert or an update.

On Failure

no effect


When-Form-Navigate Trigger

 Examples	 All Triggers

Description

Fires when navigation between forms takes place, such as when the user changes the focus to another loaded form.

Definition Level  form

Legal Commands:

unrestricted built-ins, restricted built-ins

Enter Query Mode:

no

Usage Notes

Use a When-Form-Navigate trigger to perform actions when any cross form navigation takes place without relying on window activate and window deactivate events.

On Failure

no effect


When-Form-Navigate Trigger examples

Example

This is an example of a procedure that can be called when Form Builder fires the When-Form-Navigate Trigger.

DECLARE
 win_id WINDOW := FIND_WINDOW('WINDOW12');
BEGIN
 if (GET_WINDOW_PROPERTY(win_id,WINDOW_STATE) = 'MAXIMIZE' THEN
  SET_WINDOW_PROPERTY(win_id,WINDOW_STATE,MINIMIZE);
 else
  SET_WINDOW_PROPERTY(win_id,WINDOW_STATE,MAXIMIZE);
 end if;
END;


When-Image-Activated Trigger

 All Triggers

Description

Fires when an operator uses the mouse to:

•	single-click on an image item

•	double-click on an image item

Note that When-Image-Pressed also fires on a double-click.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

On Failure

no effect


When-Image-Pressed Trigger

 All Triggers

Description

Fires when an operator uses the mouse to:

•	single-click on an image item

•	double-click on an image item

Note that When-Image-Activated also fires on a double-click.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Use a When-Image-Pressed trigger to perform an action when an operator clicks or double-clicks on an image item.

On Failure

no effect


When-List-Activated Trigger

  Related Topics	 All Triggers

Description

Fires when an operator double-clicks on an element in a list item that is  displayed as a T-list.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

A When-List-Activated trigger fires only for T-list style list items, not for drop-down lists or combo box style list items.  The display style of a list item is determined by the List Style property.

On Failure

no effect


When-List-Changed Trigger

  Related Topics	 All Triggers

Description

Fires when an end user selects a different element in a list item or de-selects the currently selected element.  In addition, if a When-List-Changed trigger is attached to a combo box style list item, it fires each time the end user enters or modifies entered text.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Use a When-List-Changed trigger to initiate an action when the value of the list is changed directly by the end user.  The When-List-Changed trigger is not fired if the value of the list is changed programmatically  such as by using the DUPLICATE_ITEM built-in, or if the end user causes a procedure to be invoked which changes the value.  For example, the When-List-Changed trigger will not fire if an end user duplicates the item using a key mapped to the DUPLICATE_ITEM built-in.

On Failure

no effect


When-Mouse-Click Trigger

 All Triggers

Description

Fires after the operator clicks the mouse if one of the following events occurs:

•	if attached to the form, when the mouse is clicked within any canvas or item in the form

•	if attached to a block, when the mouse is clicked within any item in the block

•	if attached to an item, when the mouse is clicked within the item

Three events must occur before a When-Mouse-Click trigger will fire:

•	Mouse down

•	Mouse up

•	Mouse click

Any trigger that is associated with these events will fire before the When-Mouse-Click trigger fires.

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

Use the When-Mouse-Click trigger to perform an action every time the operator clicks the mouse within an item and/or canvas.

On Failure

no effect


When-Mouse-DoubleClick Trigger

 Examples	 All Triggers

Description

Fires after the operator double-clicks the mouse if one of the following events occurs:

•	if attached to the form, when the mouse is double-clicked within any canvas or item in the form

•	if attached to a block, when the mouse is double-clicked within any item in the block

•	if attached to an item, when the mouse is double-clicked within the item

Six events must occur before a When-Mouse-DoubleClick trigger will fire:

•	Mouse down

•	Mouse up

•	Mouse click

•	Mouse down

•	Mouse  up

•	Mouse double-click

Any trigger that is associated with these events will fire before the When-Mouse-DoubleClick trigger fires.

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

Use a When-Mouse-DoubleClick trigger to perform an action every time the operator double-clicks the mouse within an item and/or canvas.

On Failure

no effect


When-Mouse-DoubleClick Trigger examples

Example

Assume that an application requires Behavior A when the operator clicks the mouse and Behavior B when the operator double-clicks the mouse.  For example,  if the operator clicks the mouse, a product information window must appear.  If the operator double-clicks the mouse,  an online help window must appear.

Three triggers are used in this example, a When-Mouse-Click trigger, a When-Timer-Expired trigger, and a When-Mouse-DoubleClick trigger.

/*
**  Trigger:  When-Mouse-Click
**  Example:  When the operator clicks the mouse, create a timer
**            that will expire within .5 seconds.
*/

DECLARE
   timer_id        TIMER;
   timer_duration  NUMBER(5) := 500;
BEGIN
   timer_id := Create_Timer('doubleclick_timer', timer_duration,
     NO_REPEAT);
END;

/*
**  Trigger:  When-Timer-Expired
**  Example:  When the timer expires display the online help
**            window if the operator has double-clicked the mouse
**            within .5 seconds, otherwise display the product
**            information window.
*/
BEGIN
   IF :Global.double_click_flag = 'TRUE' THEN
     Show_Window('online_help');
     :Global.double_click := 'FALSE';
   ELSE
     Show_Window('product_information');
   END IF;
END;

/*
**  Trigger:  When-Mouse-DoubleClick
**  Example:  If the operator double-clicks the mouse, set a
**            flag that indicates that a double-click event
**            occurred.
*/
BEGIN
   :Global.double_click_flag := 'TRUE';
END;


When-Mouse-Down Trigger

 Restrictions	 All Triggers

Description

Fires after the operator presses down the mouse button if one of the following events occurs:

•	if attached to the form, when the mouse is pressed down within any canvas or item in the form

•	if attached to a block, when the mouse is pressed down within any item in the block

•	if attached to an item, when the mouse is pressed within the item

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

Use a When-Mouse-Down trigger to perform an action every time the operator presses down the mouse button within an item and/or canvas.

Note:  The mouse down event is always followed by a mouse up event.

On Failure

no effect


When-Mouse-Down Trigger restrictions

Depending on the window manager, navigational code within a When-Mouse-Down trigger may fail.  For example on Microsoft Windows, if the operator clicks the mouse button within a field (Item_One), a When-Mouse-Down trigger that calls GO_ITEM ('item_two') will fail because Windows will return focus to Item_One, not Item_Two since the When-Mouse-Up event occurred within Item_Two.


When-Mouse-Enter Trigger

 All Triggers

Description

Fires when the mouse enters an item or canvas if one of the following events occurs:

•	if attached to the form, when the mouse enters any canvas or item in the form

•	if attached to a block, when the mouse enters any item in the block

•	if attached to an item, when the mouse enters the item

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

Use a When-Mouse-Enter trigger to perform an action every time the mouse enters an item or canvas.

Do not use the When-Mouse-Enter trigger on a canvas that is larger than the window.  Iconic buttons and items on the canvas below the initial window cannot be selected.  The user is able to scroll the canvas to see the items.  However, as soon as the mouse enters that area, the trigger fires and returns focus to the previous target, so the user is never able to click on those items.

Changing a tooltip's property in a When-Mouse-Enter trigger cancels the tooltip before it is ever shown.

Be careful when calling a modal window from a When-Mouse-Enter trigger.  Doing so may cause the modal window to appear unnecessarily.

For example, assume that your When-Mouse-Enter trigger causes Alert_One to appear whenever the mouse enters Canvas_One.  Assume also that your application contains two canvases, Canvas_One and Canvas_Two.  Canvas_One and Canvas_Two do not overlap each other, but appear side by side on the screen.  Further, assume that Alert_One displays within Canvas_Two's border.

Finally, assume that the mouse has entered Canvas_One causing the When-Mouse-Enter trigger to fire which in turn causes Alert_One to appear.

When the operator dismisses the message box, Alert_One will appear again unnecessarily if the operator subsequently enters Canvas_One with the mouse.  In addition, when the operator moves the mouse out of Canvas_Two, any When-Mouse-Leave triggers associated with this event will fire.  This may not be the desired behavior.

On Failure

no effect


When-Mouse-Leave Trigger

 All Triggers

Description

Fires after the mouse leaves an item or canvas if one of the following events occurs:

•	if attached to the form, when the mouse leaves any canvas or item in the form

•	if attached to a block, when the mouse leaves any item in the block

•	if attached to an item, when the mouse leaves the item

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

Use a When-Mouse-Leave trigger to perform an action every time the mouse leaves an item and/or canvas.

On Failure

no effect


When-Mouse-Move Trigger

 All Triggers

Description

Fires each time the mouse moves if one of the following events occurs:

•	if attached to the form, when the mouse moves within any canvas or item in the form

•	if attached to a block, when the mouse moves within any item in the block

•	if attached to an item, when the mouse moves within the item

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

Use the When-Mouse-Move trigger to perform an action every time the operator moves the mouse.

The When-Mouse-Move trigger may have performance implications because of the number of times this trigger can potentially fire.

On Failure

no effect


When-Mouse-Up Trigger

 All Triggers

Description

Fires each time the operator presses down and releases the mouse button if one of the following events occurs:

•	if attached to the form, when the mouse up event is received within any canvas or item in a form

•	if attached to a block, when the mouse up event is received within any item in a block

•	if attached to an item, when the mouse up event is received within an item

Two events must occur before a When-Mouse-Up trigger will fire:

•	Mouse down

•	Mouse up

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode  yes

Usage Notes

Use the When-Mouse-Up trigger to perform an action every time the operator presses and releases the mouse.

The mouse up event is always associated with the item that received the mouse down event.  For example, assume that there is a When-Mouse-Up trigger attached to Item_One.  If the operator presses down the mouse on Item_One, but then releases the mouse on Item_Two, the mouse up trigger will fire for Item_One, rather than for Item_Two.

On Failure

no effect


When-New-Block-Instance Trigger

  Related Topics	 All Triggers

Description

Fires when the input focus moves to an item in a different block.  Specifically, it fires after navigation to an item, when Form Builder is ready to accept input in a block that is different than the block that previously had the input focus.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  no

Usage Notes

Use a When-New-Block-Instance trigger to perform an action every time Form Builder instantiates a new block.

On Failure

no effect

Fires In

Return for Input

See Process Flowcharts


When-New-Form-Instance Trigger

 Examples	 Restrictions	  Related Topics	 All Triggers

Description

At form start-up, Form Builder navigates to the first navigable item in the first navigable block.  A When-New-Form-Instance trigger fires after the successful completion of any navigational triggers that fire during the initial navigation sequence.

This trigger does not fire when control returns to a calling form from a called form.

In a multiple-form application, this trigger does not fire when focus changes from one form to another.

Definition Level  form

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins

Enter Query Mode  no

On Failure

no effect

Fires In

Run the Form

See Process Flowcharts


When-New-Form-Instance Trigger restrictions

1	When you call FORMS_OLE.GET_INTERFACE_POINTER from the When-New-Form-Instance trigger, an exception (ORA-305500) is raised unless you initialize the OLE item or the ActiveX control with the SYNCHRONIZE built-in.

2	When a new form is called, it will appear in the default x-y position on the screen.  If this is not the desired position, you can change the x-y coordinates.  However, they cannot be changed in this When-New-Form-Instance trigger.  (This trigger fires too late in the sequence.)  To change the coordinates, use the Pre-Form trigger.


When-New-Form-Instance Trigger examples

Example

This example calls routine to display dynamic images, starts a timer to refresh the on-screen clock, and queries the first block.

BEGIN
  Populate_Dynamic_Boilerplate;
  Start_OnScreen_Clock_Timer;
  Go_Block('Primary_Ord_Info');

  /*
  ** Query the block without showing
  ** the working message.
  */
  :System.Suppress_Working := 'TRUE';
  Execute_Query;
  :System.Suppress_Working := 'FALSE';
END;


When-New-Item-Instance Trigger

 Restrictions	    Related Topics	 All Triggers

Description

Fires when the input focus moves to an item.  Specifically, it fires after navigation to an item, when Form Builder is ready to accept input in an item that is different than the item that previously had input focus.

Definition Level  form, block, or item

Legal Commands

SELECT statements, restricted built-ins, unrestricted built-ins.

Enter Query Mode  yes

Usage Notes

Use a When-New-Item-Instance trigger to perform an action whenever an item gets input focus.   The When-New-Item-Instance trigger is especially useful for calling restricted (navigational) built-ins.

On Failure

no effect

Fires In

Return for Input

See Process Flowcharts


When-New-Item-Instance Trigger restrictions

The conditions for firing this trigger are not met under the following circumstances:

•	Form Builder navigates through an item, without stopping to accept input

•	the input focus moves to a field in an alert window, or to any part of an Form Builder menu


When-New-Record-Instance Trigger

  Related Topics	 All Triggers

Description

Fires when the input focus moves to an item in a record that is different than the record that previously had input focus.  Specifically, it fires after navigation to an item in a record, when Form Builder is ready to accept input in a record that is different than the record that previously had input focus.

Fires whenever Form Builder instantiates a new record.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Use a When-New-Record-Instance trigger to perform an action every time Form Builder instantiates a new record.  For example, when an operator presses [Down] to scroll through a set of records, Form Builder fires this trigger each time the input focus moves to the next record, in other words, each time Form Builder instantiates a new record in the block.

On Failure

no effect

Fires In

Return for Input

See Process Flowcharts


When-Radio-Changed Trigger

 All Triggers

Description

Fires when an operator selects a different radio button in a radio group, or de-selects the currently selected radio button, either by clicking with the mouse, or using the keyboard.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Use a When-Radio-Changed trigger to perform an action depending on the state of a radio group.  (De-selecting a radio button in a radio group sets the radio group value to NULL; operators use this technique in Enter Query mode to exclude a radio group from a query.)

When an operator clicks an item in a radio group, the internal value of that item does not change until navigation is completed successfully.  Thus, the When-Radio-Changed trigger is the first trigger to register the changed value of a radio group.  For all navigation triggers that fire before the When-Radio-Changed trigger, the value of the radio group remains as it was before the operator navigated to it.

On Failure

no effect


When-Remove-Record Trigger

 All Triggers

Description

Fires whenever the operator or the application clears or deletes a record.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a When-Remove-Record trigger to perform an action every time Form Builder clears or deletes a record.

On Failure

Form Builder navigates to the block level with or without validation depending on the current operation, and puts the cursor at the target block.

Fires In

CLEAR_RECORD

DELETE_RECORD

See Process Flowcharts


When-Tab-Page-Changed

 Examples	  Related Topics	 All Triggers

Description

Fires whenever there is explicit item or mouse navigation from one tab page to another in a tab canvas.

Definition Level  form

Legal Commands

unrestricted built-ins, restricted built-ins

Enter Query Mode  no

Usage Notes

•	Use a When-Tab-Page-Changed trigger to perform actions when any tab page is changed during item or mouse navigation.

•	When-Tab-Page-Changed fires only when tab page navigation is explicit;  it does not respond to implicit navigation.  For example, the trigger will fire when the mouse or keyboard is used to navigate between tab pages, but the trigger will not fire if an end user presses [Next Item] (Tab) to navigate from one field  to another field in the same block, but on different tab pages.

•	When-Tab-Page-Changed does not fire when the tab page is changed programmatically.

On Failure

no effect


When-Tab-Page-Changed examples

Example

/* Use a When-Tab-Page-Changed trigger to dynamically

** change a tab page's label from lower- to upper-case
** (to indicate to end users if they already have
** navigated to the tab page):
*/
DECLARE
  tp_nm   VARCHAR2(30);
  tp_id   TAB_PAGE;
  tp_lb   VARCHAR2(30);

BEGIN
  tp_nm := GET_CANVAS_PROPERTY('emp_cvs', topmost_tab_page);
  tp_id := FIND_TAB_PAGE(tp_nm);
  tp_lb := GET_TAB_PAGE_PROPERTY(tp_id, label);

  IF tp_lb LIKE 'Sa%' THEN
    SET_TAB_PAGE_PROPERTY(tp_id, label, 'SALARY');
  ELSIF tp_lb LIKE 'Va%' THEN
    SET_TAB_PAGE_PROPERTY(tp_id, label, 'VACATION');
  ELSE null;
  END IF;
END;


When-Timer-Expired Trigger

 Examples	 Restrictions	  Related Topics	 All Triggers

Description

Fires when a timer expires.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Timers are created programmatically by calling the CREATE_TIMER built-in procedure.

•	The When-Timer-Expired trigger can not fire during trigger, navigation, or transaction processing.

•	Use a When-Timer-Expired trigger to initiate an event, update item values, or perform any task that should occur after a specified interval.

•	You can call GET_APPLICATION_PROPERTY(TIMER_NAME) in a When-Timer-Expired trigger to determine the name of the most recently expired timer.

On Failure

no effect

Fires In

Process Expired Timer

See Process Flowcharts


When-Timer-Expired Trigger restrictions

A When-Timer-Expired trigger will not fire when the user is currently navigating a menu.


When-Timer-Expired Trigger examples

Example

The following example displays a message box each time a repeating timer expires.  The following example is from a telemarketing application, in which sales calls are timed, and message boxes are displayed to prompt the salesperson through each stage of the call.  The message box is displayed each time a repeating timer expires.

DECLARE
  timer_id  TIMER;
  alert_id  ALERT;
  call_status NUMBER;
  msg_1       VARCHAR2(80) := 'Wrap up the first phase of your
                               presentation';
  msg_2       VARCHAR2(80) := 'Move into your close.';
  msg_3       VARCHAR2(80) := 'Ask for the order or
                               repeat the close.'
  two_minutes NUMBER(6) := (120 * 1000);
  one_and_half NUMBER(5) := (90 * 1000);
BEGIN
  :GLOBAL.timer_count := 1
  BEGIN
    timer_id := FIND_TIMER('tele_timer');
    alert_id := FIND_ALERT('tele_alert');
  IF :GLOBAL.timer_count = 1 THEN
    Set_Alert_Property(alert_id, ALERT_MESSAGE_TEXT, msg_1);
  call_status := Show_Alert(alert_id);
  IF call_status = ALERT_BUTTON1 THEN
    Delete_Timer(timer_id);
    Next_Record;
  ELSIF
    call_status = ALERT_BUTTON2 THEN
    :GLOBAL.timer_count := 0;
  ELSE
    Set_Timer(timer_id, two_minutes, NO_CHANGE);
  END IF;
ELSIF :GLOBAL.timer_count = 2 THEN
    Change_Alert_Message(alert_id, msg_2);
    call_status := Show_Alert(alert_id);
    IF call_status = ALERT_BUTTON1 THEN
      Delete_Timer(timer_id);
      Next_Record;
    ELSIF
      call_status = ALERT_BUTTON2 THEN
      :GLOBAL.timer_count := 0;
    ELSE
      Set_Timer(timer_id, one_and_half, NO_CHANGE);
    END IF;
  ELSE
    Change_Alert_Message(alert_id, msg_3);
    call_status := Show_Alert(alert_id);
    IF call_status = ALERT_BUTTON1 THEN
      Delete_Timer(timer_id);
      Next_Record;
    ELSIF
     call_status = ALERT_BUTTON2 THEN
     :GLOBAL.timer_count := 0;
    ELSE
      Set_Timer(timer_id, NO_CHANGE, NO_REPEAT);
    END IF;
  END IF;
  :GLOBAL.timer_count = 2;
  END;
END;


When-Tree-Node-Activated Trigger

 All Triggers

Description

Fires when an operator double-clicks a node or presses Enter when a node is selected.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode yes

Usage Notes

•	SYSTEM.TRIGGER_NODE is the node the user clicked on. SYSTEM.TRIGGER_NODE returns a value of type NODE.

•	No programmatic action will cause the When-Tree-Node-Activated trigger to fire. Only end-user action will generate an event.

On Failure

no effect


When-Tree-Node-Expanded Trigger

 All Triggers

Description

Fires when a node is expanded or collapsed.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode yes

Usage Notes

•	SYSTEM.TRIGGER_NODE is the node the user clicked on. SYSTEM.TRIGGER_NODE returns a value of type NODE.

•	No programmatic action will cause the When-Tree-Node-Espanded trigger to fire. Only end-user action will generate an event.

On Failure

no effect


When-Tree-Node-Selected Trigger

 All Triggers

Description

Fires when a node is selected or deselected.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

•	SYSTEM.TRIGGER_NODE is the node the user clicked on. SYSTEM.TRIGGER_NODE returns a value of type NODE.

•	No programmatic action will cause the When-Tree-Node-Selected trigger to fire. Only end-user action will generate an event.

On Failure

no effect


When-Validate-Item Trigger

 Examples	  Related Topics	 All Triggers

Description

Fires during the Validate the Item process.  Specifically, it fires as the last part of item validation for items with the New or Changed validation status.

Definition Level  form, block, or item

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

•	Use a When-Validate-Item trigger to supplement Form Builder default item validation processing.

•	It is possible to write a When-Validate-Item trigger that changes the value of an item that Form Builder is validating.  If validation succeeds, Form Builder marks the changed item as Valid and does not re-validate it.  While this behavior is necessary to avoid validation loops, it does make it possible for your application to commit an invalid value to the database.

•	The setting you choose for the Defer Required Enforcement property can affect the When-Validate-Item trigger.  See Defer_Required_Enforcement for details.

On Failure

If fired as part of validation initiated by navigation, navigation fails, and the focus remains on the original item.

Fires In

Validate the Item

See Process Flowcharts


When-Validate-Item Trigger examples

Example

The following example finds the commission plan in the COMMPLAN table, based on the current value of the commcode item in the EMPLOYEE block in the form, to verify that the code is valid.  If the code in the COMMPLAN table is located, the description of the COMMPLAN is obtained and deposited in the non-database Description item. Otherwise, an error is raised.

** Method 1: Using a SELECT...INTO statement, the trigger
**           looks more readable but can be less efficient
**           than Method 2 because for ANSI Standard
**           compliance, the SELECT...INTO statement must
**           return an error if more than one row is
**           retrieved that matches the criteria. This
**           implies PL/SQL may attempt to fetch data twice
**           from the table in question to insure that there
**           aren't two matching rows.
*/
BEGIN
  SELECT description
    INTO :Employee.Commplan_Desc
    FROM commplan
   WHERE commcode = :Employee.Commcode;
EXCEPTION
  WHEN No.Data_Found THEN
    Message('Invalid Commission Plan, Use <List> for help');
    RAISE Form_Trigger_Failure;
  WHEN Too_Many_Rows THEN
    Message('Error. Duplicate entries in COMMPLAN table!');
    RAISE Form_Trigger_Failure;
END;

/*
** Method 2: Using an Explicit Cursor looks a bit more
**           daunting but is actually quite simple. The
**           SELECT statement is declared as a named cursor
**           in the DECLARE section and then is OPENed,
**           FETCHed, and CLOSEd in the code explicitly
**           (hence the name). Here we guarantee that only a
**           single FETCH will be performed against the
**           database.
*/
DECLARE
  noneFound BOOLEAN;
  CURSOR cp IS SELECT description
                 FROM commplan
                WHERE commcode = :Employee.Commcode;
BEGIN
  OPEN cp;
  FETCH cp INTO :Employee.Commplan_Desc;
  noneFound := cp%NOTFOUND;
  CLOSE cp;
  IF noneFound THEN
    Message('Invalid Commission Plan, Use <List> for help');
    RAISE Form_Trigger_Failure;
  END IF;
END;


When-Validate-Record Trigger

 Examples	  Related Topics	 All Triggers

Description

Fires during the Validate the Record process.  Specifically, it fires as the last part of record validation for records with the New or Changed validation status.

Definition Level  form or block

Legal Commands

SELECT statements, unrestricted built-ins

Enter Query Mode  no

Usage Notes

Use a When-Validate-Record trigger to supplement Form Builder default record validation processing.

Note that it is possible to write a When-Validate-Record trigger that changes the value of an item in the record that Form Builder is validating.  If validation succeeds, Form Builder marks the record and all of the fields as Valid and does not re-validate.  While this behavior is necessary to avoid validation loops, it does make it possible for your application to commit an invalid value to the database.

On Failure

If fired as part of validation initiated by navigation, navigation fails, and the focus remains on the original item.

Fires In

Validate the Record

See Process Flowcharts


When-Validate-Record Trigger examples

Example

The following example verifies that Start_Date is less than End_Date.  Since these two text items have values that are related, it's more convenient to check the combination of them once at the record level, rather than check each item separately. This code presumes both date items are mandatory and that neither will be NULL.

/* Method 1: Hardcode the item names into the trigger.
**           Structured this way, the chance this code will
**           be reusable in other forms we write is pretty
**           low because of dependency on block and item
**           names.
*/
BEGIN
  IF :Experiment.Start_Date > :Experiment.End_Date THEN
    Message('Your date range ends before it starts!');
    RAISE Form_Trigger_Failure;
  END IF;
END;

/* Method 2: Call a generic procedure to check the date
**           range. This way our date check can be used in
**           any validation trigger where we want to check
**           that a starting date in a range comes before
**           the ending date. Another bonus is that with the
**           error message in one standard place, i.e. the
**           procedure, the user will always get a
**           consistent failure message, regardless of the
**           form they're currently in.
*/
BEGIN
  Check_Date_Range(:Experiment.Start_Date,:Experiment.End_Date);
END;

/*
** The procedure looks like this
*/
PROCEDURE Check_Date_Range( d1 DATE, d2 DATE ) IS
BEGIN
  IF d1 > d2 THEN
    Message('Your date range ends before it starts!');
    RAISE Form_Trigger_Failure;
  END IF;
END;


When-Window-Activated Trigger

  Related Topics	 All Triggers

Description

Fires when a window is made the active window.  This occurs at form startup and whenever a different window is given focus.  Note that on some window managers, a window can be activated by clicking on its title bar.  This operation is independent of navigation to an item in the window.  Thus, navigating to an item in a different window always activates that window, but window activation can also occur independently of navigation.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Use this trigger to perform the following types of tasks:

•	Capture initial settings of window properties, by way of the GET_WINDOW_PROPERTY built-in.

•	Enforce navigation to a particular item whenever a window is activated.

•	Keep track of the most recently fired window trigger by assigning the value from SYSTEM.EVENT_WINDOW to a variable or global variable.

On Failure

no effect


When-Window-Closed Trigger

 Examples	  Related Topics	 All Triggers

Description

Fires when an operator closes a window using a window-manager specific Close command.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Use this trigger to programmatically close a window when the operator issues the window-manager Close command.

You can hide the window that contains the current item.

On Failure

no effect


When-Window-Closed Trigger examples

Example

The following example of a call to SET_WINDOW_PROPERTY from this trigger closes a window whenever the operator closes it by way of the window manager operation:

Set_Window_Property('window_name', VISIBLE, PROPERTY_OFF);


When-Window-Deactivated Trigger

  Related Topics	 All Triggers

Description

Fires when an operator deactivates a window by setting the input focus to another window within the same form.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Use this trigger to audit the state of a window whenever the operator deactivates the window by setting the input focus in another window.

Note that if this form opens another form, this deactivate trigger does not immediately fire.  Instead, it will fire later when control returns to this form.  (Assuming this window also has an activate trigger, then when control returns to this form, first the deactivate trigger fires followed immediately by the activate trigger.)

On Failure

no effect


When-Window-Resized Trigger

  Related Topics	 All Triggers

Description

Fires when a window is resized, either by the operator or programmatically through a call to RESIZE_WINDOW or SET_WINDOW_PROPERTY.  (Even if the window is not currently displayed, resizing the window programmatically fires the When-Window-Resized trigger.)  This trigger also fires at form startup, when the root window is first drawn.  It does not fire when a window is iconified.

Definition Level  form

Legal Commands

SELECT statements, unrestricted built-ins, restricted built-ins

Enter Query Mode  yes

Usage Notes

Use this trigger to perform any one of the following types of tasks:

•	Capture the changed window properties, such as width, height, x coordinate, or y coordinate.

•	Audit the actions of an operator.

•	Set the input focus in an item on the target window.

•	Maintain certain visual standards by resetting window size if the window was improperly resized.

On Failure

no effect


About error messages

•	message prefix and number

•	description of error

•	possible cause(s) of the error

•	action(s) you might take to resolve the error

When you encounter an error message, first check the message prefix to determine which component generated the message.  Then look at the message number and description.  If you need more information, consult the component's online help system for a full description of the error message (including cause and action).

Error Message Prefixes

Each component has a unique prefix for its error messages.  The following list shows the error message prefixes for Forms Developer:

Prefix	Component

FRM	Form Builder

OG	Graphics Builder

PDE	Procedure Builder

In addition to Forms Developer error messages, you may encounter messages from other products.  The following list shows other error message prefixes you may encounter and sources of information for researching the error:

Prefix	Source	Help

REP	Reports Developer	Reports Developer online help

ORA	Oracle Server	Oracle Server Messages and Codes Manual

PLS	PL/SQL	Oracle Server Messages and Codes Manual

NET	SQL*Net	Oracle Network Products Messages Manual

The Oracle Server Messages and Codes Manual contains error message prefixes 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.


About embedded variables in messages

To help you find and fix errors, Forms Developer embeds object names, numbers, and character strings in some error messages.  In online help, these embedded variables are represented by terms placed in angle brackets (< >).

For example, the error message:

PDE-CCM002: LIB1 is not an open library.

would appear in online help as:

PDE-CCM002: <library name> is not an open library.


Working with Forms Runtime messages

  Related Topics

To control the messages that end users see when they use a Form Builder application, you can:

•	use the SYSTEM.MESSAGE_LEVEL system variable to suppress specific "severity levels" of messages

•	use On-Error and On-Message triggers to replace the standard processing of messages

•	use the SYSTEM.SUPPRESS_WORKING system variable to prevent the update of an end user's screen (by suppressing the "Working..." message)

Message Severity Levels

Forms Runtime messages are ranked by severity.  Use the SYSTEM.MESSAGE_LEVEL system variable to can control the minimum severity level that displays to end users.

There are six levels of message severity that you can affect, listed here in increasing order of severity.

Level	Message  Description
0	All types of messages from the other levels of severity.
5	Reaffirms an obvious condition.
10	Indicates that the end user has made a procedural mistake.
15	Declares that the end user is attempting to perform a function for which the form is not designed.
20	Indicates a condition where the end user cannot continue an intended action due to a problem with a trigger or another outstanding condition.
25	Indicates a condition that could result in the form performing incorrectly.
>25	Indicates a message severity level that you cannot suppress via the SYSTEM.MESSAGE_LEVEL system variable.

Severity levels of individual Forms Runtime messages are labelled with "Level" in the Form Builder online help system.

Message Types

To use On-Error and On-Message triggers to replace Forms Runtime messages, you need to be aware of the three types of Forms Runtime messages:

Informative 	Informs end users of the present state of processing  (e.g.,  Last value retrieved.)  or provides end users with context-sensitive guidance  (e.g.,  Press [Accept] to enter answer.).  Use the On-Message trigger to suppress the appearance of these messages.

Error 	Inform end users of error conditions that prevent the end user's actions  (e.g.,  Function key not allowed. Press [Show Function Keys] for list of valid keys.).  Use On-Error triggers to suppress the appearance of these messages.  However, you cannot suppress error messages that appear on the command line  (e.g.,  Too many arguments on command line.).

Working 	Inform end users that Form Builder currently is processing  (e.g.,  Working...).  You cannot use On-Error or On-Message triggers, or the SYSTEM.MESSAGE_LEVEL system variable to suppress these messages.

Message types of individual Forms Runtime messages are labelled with "Type" in the Form Builder online help system.


Calling Oracle Customer Support

Some errors (e.g., internal errors) will require that you call Oracle Customer Support to report the error.  When you call, please provide the following information:

1	Your name, company, and Oracle Support ID number.

2	The hardware, operating system, and release number of the operating system on which the product is running.

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 ... from the menu.)

4	All other products (and their version numbers) in use when you encountered the error (e.g., Oracle 7.1.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.  Minimal effect-if any-on operations.


About upgrading forms

  Related Topics

Forms Developer is upwardly compatible with earlier versions of Oracle Forms, including Versions 3.0, 4.0, 4.5, and 5.0.

Note: Before converting your forms or menus, Oracle Corporation recommends that you first make backup copies of all files. Once you upgrade a module, you will not be able to open it in an earlier version of Forms Developer.


Upgrading a form

  Related Topics

To upgrade a version 4.x or 5.x form to Forms Developer6i :

1	Start Forms Developer Form Builder.

2	Choose File [image] Open to display the file or database dialog.

3	Choose the module you want to upgrade.

4	Click OK.

5	Choose File [image] Save.

6	Choose Program [image] Compile [image] All to compile the newly-upgraded module.

Note: All form modules and libraries must be upgraded and recompiled.

To upgrade a pre-4.0 form to Forms Developer6i:

To upgrade a pre-4.0 form to Forms Developer6i, first upgrade the form to version 4.5 (using Forms 4.5 to perform the upgrade), and then upgrade from version 4.5 to version 6i according to the instructions above.

To upgrade a pre-4.0 form to version 4.5, type this statement at the command line, substituting the correct form of the Forms 4.5 Generate command for your environment:

f45gen32 <module_name> <username>/<password> upgrade=yes version=<version_number>

To upgrade from:	Use this version number:
Version 3.0	30
Version 2.3	23
Version 2.0	20


Creating a data block

  Next Step	     Related Topics

To create a data block from a table:

Choose Tools-->Data Block Wizard to invoke a wizard that guides you through the process of building a data block.

Or,

1	In the Object Navigator, click the Blocks node.

2	Click the Create button [image] in the toolbar.

3	Double-click the Block object icon [image] to display the Property Palette.

4	Under the Database node:

•	Set the Query Data Source Type property to Table.

•	Type the name of a database table in the Query Data Source Name field.

5	Under the Advanced Database node:

•	Set the DML Data Target Type property to Table.

•	Type the name of your data source in the DML Data Source Name field.

6	Under the General node, click the Name property, then type a name or accept the default name.

You can use any name that follows ORACLE naming conventions and is unique among blocks in the form. The block name is an internal descriptor that is not displayed at runtime.


Creating an interface item

  Next Step

To create an interface item:

1	In the Object Navigator, click the plus icon beside the desired Blocks node.

Form Builder expands the block node and displays its subnodes.

2	Click the plus icon beside the Items node.

3	Click the Create button [image] in the toolbar.

A new item with a default name is inserted under the Items node.

4	Double-click the object icon beside the newly created item to display the Property Palette.

5	Under the Database node, set the Database Item property to No.

Note: When you create an item in a data block, Forms assumes the item is a data item, and sets its Database Item property to Yes. Data items are automatically included in any SELECT, UPDATE, and INSERT statements issued to the database.  If the item you are creating is a control item in a data block, you must explicitly set its Database Item property to No.

6	Under the General node, set the Type property to specify the type of item you want.

The default item type is text item.  You can change the default by setting the Type property to the item type desired (check box, radio group, list item, and so on).

7	Under the Physical node, set the Canvas property to the name of the desired canvas.

Note: To display an item at runtime, you must assign each interface item in a form to a canvas.


Modifying the definition of a data block

  Related Topics

To modify the definition of a data block:

In the Object Navigator, click the desired block, and choose Tools [image] Data BlockWizard to invoke a wizard that guides you through the process of modifying the definition of a data block.


About Forms Runtime Diagnostics

  Related Topics

Forms Runtime Diagnostics (FRD) is a runtime event-based logging system designed to help you debug your applications.

When a form is run with FRD enabled, a combination of external user-application interactions and internal Forms processing events are written in chronological order to a log on the file system. These events can then be analyzed for correctness.

You can collect the following information:

•	Trigger firing

•	Built-in execution

•	Messages

•	Files opened

•	Unhandled exceptions

•	External user events


Using Forms Runtime Diagnostics

  Related Topics

To initiate data collection:

Provide the string collect to the runtime argument record as follows:

f60runm module=foo userid=scott/tiger@hockey record=collect

This will create a file in the current working directory with name: collect_<process ID>. In order to choose the name of the file yourself, provide the string as the value of the log= argument:

f60runm module=foo userid=scott/tiger@hockey record=collect log=myfile


Forms Runtime Diagnostics expected output

  Related Topics

The following output for each of the instrumented events can be expected from using Forms Runtime Diagnostics.

Triggers

Place any type of trigger at any level in the object hierarchy. Upon firing, it should be logged as follows:

<trigger_name> Trigger Fired:

Form: <form_name>

Block: <block_name>

Item: <item_name>

The level of the trigger corresponds to the last item in the list. A trigger on Form level, therefore, would have only the form name listed below the trigger name.

A state delta should be written to the log following a trigger fire. A state delta is a dump of all internal state information that has changed since the occurrence of the previous state delta. The first state delta will dump the entire forms state to the log.

Built-ins

When a PL/SQL Forms built-in is executed, the diagnostic output should appear as follows:

Executing <built-in name> Built-In:

In Argument 0 -Type: <type> Value: <value>

In Argument 1 -Type: <type> Value: <value>

…

Out Argument 0 -Type: <type> Value: <value>

…

Parameter types to be tested include the following: String, Number, Integer, Float, Oracle Number, Date. Out argument 0 generally represents the function return value.

Messages

Any messages produced by Forms should appear in the log as it was displayed:

Error Message: <message>

File Opens

Files opened are written to the log in the following format:

Opened file: <file_name>

If a file fails to be opened, it should appear in the log as follows:

Failed to open file: <file_name>

Unhandled Exceptions

When an exception is raised that is not caught, it will be logged to the file in the following format:

Unhandled Exception: <exception_name>

If the name is unavailable, FRD will record the exception number for reference:

Unhandled Exception ORA- <exception_number>

Unhandled exceptions should be followed in the log by a state delta.

Runtime External User Events

FRD uses existing runtime mechanisms to log user events. Runtime information written to the log will always be proceeded by a # sign followed by a number representing the chronological order of the event. For each event, runtime will generally write two information blocks, the first detailing the event itself and the second representing a state delta.


About the user exit interface

  Related Topics

Foreign functions are subprograms written in a 3GL programming language that allow you to customize your Form Builder applications to meet the unique requirements of your users.  Foreign functions are often used to enhance performance or provide additional functionality to Form Builder.

In Form Builder, you can call a user exit from within a trigger or user-named subprogram using the USER_EXIT built-in.  The user exit must be written to return an integer value status code from the function.  The return value of the user exit indicates success, failure, or fatal error.  Following the execution of the USER_EXIT built-in, the values of the error variables in Form Builder—FORM_FAILURE, FORM_FATAL, and FORM_SUCCESS—are set accordingly.

Special handling is required to make a user exit callable from Forms Runtime.  When using a user exits on Microsoft Windows, user exit functions must be linked into a dynamic link library, and a special configuration library must be updated with information about each user exit.  The configuration file provides information about the user exit interfaces and the entry points that allow Form Builder to invoke foreign functions from a user exit interface.  When using user exits on other platforms, a configuration file must be updated with information about each user exit, and the compiler version of that file, plus the compiled version of the user exit code, must be linked into the Forms Runtime executable.

Note:  An alternative approach for calling a foreign function is from a PL/SQL interface.  The ORA_FFI built-in package provides a PL/SQL interface for invoking foreign functions from Form Builder.


EXEC SQL statement

 Restrictions

An EXEC SQL statement is a SQL command prefixed with "EXEC SQL."  EXEC SQL statements allow you to perform any SQL command in an Oracle Precompiler foreign function.  Use EXEC SQL statements to select or manipulate data in the database from a foreign function.

Syntax

EXEC SQL sql_statement;

where sql_statement is any valid Oracle SQL statement, except for the restricted commands noted in this section.

You need to perform an explicit CONNECT in an Oracle Precompiler foreign function because Form Builder does not establish the connection automatically, except on UNIX.  The Oracle Server does support concurrent connects.  For more information, refer to the Programmer's Guide to the Oracle Precompilers.


EXEC SQL statement restrictions

Using SQL commands in an Oracle Precompiler foreign function has the following restrictions:

•	Do not issue a SQL COMMIT or ROLLBACK statement from within a foreign function if there are changes in a form that have not been posted to the database when the foreign function is called.

•	Do not issue any command that would implicitly cause a database commit, such as a DDL command within a foreign function, if there are changes in a form that have not been posted to the database when the foreign function is called.


EXEC TOOLS GET statement

 Examples	   Restrictions

An EXEC TOOLS GET statement retrieves a value from Form Builder into an Oracle Precompiler foreign function.  Specifically, it places the value of a Form Builder item or variable into a host language variable.  Once the foreign function retrieves a value from Form Builder, the foreign function can use that value for calculation, manipulation, or updating.

Syntax

EXEC TOOLS GET form_variable_1[, form_variable_2, ...]

   INTO :host_variable_1[, :host_variable_2, ...];

where:

form_variable_n	Specifies the name of the Form Builder item or variable from which you are reading a value.
host_variable_n	Specifies the name of the host language variable into which you are reading a value.
Notes:

The form_variable can be a reference to any of the following items:

•	a fully-qualified item (block.item)

•	a form parameter

•	a Form Builder system variable

•	a Form Builder global variable

•	a host language variable (prefixed with a colon) whose value is any of the above choices

Refer to the Programmer's Guide to the Oracle Precompilers for any restrictions on host language variables.


EXEC TOOLS GET statement restrictions

It is not possible to get or set values directly into a record group from a foreign function.


EXEC TOOLS GET statement examples

Example

/*

** Example:  Read an item name from a block (empblock.empname)

*/

EXEC SQL BEGIN DECLARE SECTION;

char itm_buff[255];    /* buffer for item value */

VARCHAR itm_name[255]; /* Forms item name       */

EXEC SQL END DECLARE SECTION;

strcpy(itm_name.arr,"EMBLOCK.EMPNAME");

itm_name.len=strlen("EMBLOCK.EMPNAME");

EXEC TOOLS GET :itm_name

INTO :itm_buff;


EXEC TOOLS SET statement

 Examples

An EXEC TOOLS SET statement sends a value from an Oracle Precompiler foreign function to Form Builder.  Specifically, it places the value of a constant or the value of a host language variable into a Form Builder item or variable.

Any value that an EXEC TOOLS SET statement passes to a form item displays after the foreign function returns processing control to the form that called the foreign function (providing, of course, that the item has the Enabled item property set to Yes).

Syntax

EXEC TOOLS SET form_variable[, ...]

    VALUES ({:host_variable | constant}[, ...]);

where:

form_variable	Specifies the name of the Form Builder item or variable into which you are reading a value.
host_variable	Specifies the name of the host language variable from which you are reading a value.
constant	Specifies the constant that you are reading.  Do not precede a constant with a colon.
Notes:

The form_variable can be a reference to any of the following items:

•	a fully-qualified item (block.item)

•	a form parameter

•	a Form Builder system variable

•	a Form Builder global variable

•	a host language variable (prefixed with a colon) whose value is any of the above choices

Refer to the Programmer's Guide to the Oracle Precompilers for any restrictions on host language variables.

Represent host variables and constants in standard SQL format:

Value	Result
:holder1	Inserts the value of the host variable, holder1 (preceded by a semi-colon).
'Summit Sporting Goods'	Inserts the constant string value, Summit Sporting Goods (enclosed in single quotes).
413	Inserts the constant numeric value, 413 (no quotes for numeric values).


EXEC TOOLS SET statement examples

Example

/*

** Example:  Write 'SMITH' into emp.ename

*/

EXEC SQL BEGIN DECLARE SECTION;

char itm_buff[255];  /*buffer for item value */

VARCHAR itm_name[255]; /* Forms item name */

EXEC SQL END DECLARE SECTION;

strcpy(itm_name.arr,"EMP.ENAME");

itm_name.len = strlen("EMP.ENAME");

strcpy(itm_buff,"SMITH");

EXEC TOOLS SET :itm_name

VALUES (:itm_buff);


EXEC TOOLS MESSAGE statement

 Examples

An EXEC TOOLS MESSAGE statement displays a message on the Form Builder message line.

Syntax

EXEC TOOLS MESSAGE (message [severity]);

where:

message	Specifies the message being passed to Form Builder.  The message can be a quoted string or a host language variable.
Severity	Specifies the severity level of the message  being passed to Form Builder.


EXEC TOOLS MESSAGE statement examples

Example

/*

** Example:  Error message for text item

*/

EXEC TOOLS MESSAGE

   'Incorrect argument: Expecting item name. Please re-enter.';


EXEC TOOLS GET CONTEXT statement

 Examples

An EXEC TOOLS GET CONTEXT statement obtains context information (a pointer name) previously saved using EXEC TOOLS SET CONTEXT and reads it into a foreign function.

Syntax

EXEC TOOLS GET CONTEXT context_name [, ...]

   INTO :host_variable_1[, :host_variable_2, ...];

where:

context_name	Specifies the name of the context you are saving.
host_variable_n	Specifies the name of the host language variable into which you are reading the context value.
Notes:

The context_name can be a reference to one of the following items:

•	a host language variable (prefixed with a colon)

•	a constant


EXEC TOOLS GET CONTEXT statement examples

Example

/*

** Example:  Get previously saved context information

*/

EXEC SQL BEGIN DECLARE SECTION;

char *pctx;

EXEC SQL END DECLARE SECTION;

EXEC TOOLS GET CONTEXT appl_1 INTO :pctx;


EXEC TOOLS SET CONTEXT statement

 Examples

An EXEC TOOLS SET CONTEXT statement saves context information  from one foreign function for use in subsequent foreign function invocations.  Use EXEC TOOLS SET CONTEXT instead of creating a global variable to hold information.  EXEC TOOLS SET CONTEXT allows you to assign a meaningful text name to a pointer representing a location in memory.  You can retrieve the pointer using EXEC TOOLS GET CONTEXT.

Syntax

EXEC TOOLS SET CONTEXT host_name[, ...]

    BY context_name [, ...];

where:

host_name	Specifies the host language variable containing the information to be saved.
context_name	Specifies the name of the saved context.

Notes:

The context_name can be a reference to one of the following items:

•	a host language variable (prefixed with a colon)

•	a constant


EXEC TOOLS SET CONTEXT statement examples

Example

/*

** Example:  Save context information for later use

*/

EXEC SQL BEGIN DECLARE SECTION;

char my_context[20];

EXEC SQL END DECLARE SECTION;

strcpy(my_context, "context_1");

EXEC TOOLS SET CONTEXT :my_context BY appl_1;


EXEC ORACLE statement

An EXEC ORACLE statement is a statement that is not standard SQL and is used to execute Oracle Precompiler options.  For more information, refer to the Programmer's Guide to the Oracle Precompilers.


Creating a user exit

  Example	  Related Topics

To create a user exit:

1	Write the user exit using one of the host programming languages.

2	Recommendation: Create an Oracle Precompiler foreign function using the C programming language.

3	Create an IAPXTB control structure that registers each user exit

4	Integrate a user exit with Form Builder


About IAPXTB control structures

  Related Topics

The IAPXTB control structure is a data structure that contains information regarding all foreign functions that can be invoked from a user exit.  The IAPXTB control structure designates the entry points necessary for linking foreign functions to Form Builder.  The following table describes each column in the IAPXTB control structure:

Column	Content
NAME	This column specifies a user exit name for a foreign function that can be invoked from a user exit.  (This is not necessarily the name of the file that contains the foreign function or the name of the foreign function that is called.)  Note that some host languages are case sensitive.
FUNCTION	This column specifies the name of the foreign function.
TYPE	This column specifies the language in which the foreign function is written.  Valid values include:XITCC for C, XITCOB for COBOL, XITFOR for FORTRAN, XITPLI for PL/I, XITPAS for PASCAL, and XITAda for Ada

You must enter one entry in the IAPXTB control structure for every foreign function that can be invoked from a user exit.  This is true for all foreign functions that can be invoked from a user exit, whether a foreign function is in a file that is precompiled and compiled by itself, or precompiled and compiled with several other foreign functions.  You should maintain all foreign functions that can be invoked from a user exit for a production system in one IAPXTB control structure.  It’s a good idea to keep test versions of your foreign functions in a separate IAPXTB control structure.


Creating an IAPXTB control structure

 Examples	    Related Topics

To create the IAPXTB control structure:

1	Define the IAPXTB data structure.

Make sure you define the data structure with three fields representing the name of the user exit, the name of the foreign function, and the language used to develop the foreign function.

2	Enter the data for each foreign function.

3	Compile the IAPXTB source file to generate an object code file.  Retain the IAPXTB object code file for integrating the user exit with Form Builder.


About integrating a user exit with Form Builder

  Related Topics

Integration of a user exit to Form Builder depends on the operating system and the language used to write the foreign function.

On Microsoft Windows, you create a dynamic link library with foreign function object code files and IAPXTB control structure object code files.  When a foreign function is invoked from a user exit, a dynamic link library loads into memory.

For other environments, you must rebuild the Forms Runtime executable by linking the object code files from the foreign function and IAPXTB control structure to Form Builder object code files.


Integrating a user exit with Form Builder

 Examples	    Related Topics

To integrate a user exit with Form Builder:

1	Identify the foreign function object code file.

2	Identify the IAPXTB control structure object code file.

3	Link the foreign function object code file and the IAPXTB control structure object code file with either a dynamic link library or Forms Runtime.


Invoking a foreign function from a user exit

 Restrictions	    Related Topics

After creating a user exit to a foreign function, invoke the foreign function using a user exit interface from Form Builder.  To invoke a foreign function from a user exit, call the USER_EXIT built-in subprogram from a trigger or from a user-named subprogram.

When you invoke a foreign function from a user exit, Form Builder temporarily passes processing control to the foreign function.  When execution of the foreign function is complete, Form Builder regains processing control.

Syntax

USER_EXIT(user_exit_string);

USER_EXIT(user_exit_string, error_string);

The USER_EXIT built-in calls the foreign function named in the user_exit_string.

Parameters

user_exit_string	Specifies a user exit name for a foreign function to call from a user exit, including any parameters.  Maximum length of the user_exit_string is 255 characters.
error_string	Specifies a user-defined error message that Form Builder displays if the call to the foreign function fails. Maximum length of the error_string is 255 characters.


Invoking a foreign function from a user exit restrictions

The user exit name that represents a foreign function (in the user_exit_string of the USER_EXIT built-in subprogram) must follow the rules of your operating system and host language.  Be aware that these rules might include case sensitivity.  Also note that only one foreign function can be invoked per USER_EXIT built-in call.


Passing parameter values to a foreign function using USER_EXIT

  Related Topics

You can pass parameters to a foreign function that is invoked from a user exit by defining user_exit_string and error_string in the USER_EXIT built-in subprogram.

When you define user_exit_string and error_string in Form Builder, the foreign function recognizes the values as corresponding to a command line value and an error message value.  For instance, Form Builder treats the value of user_exit_string as a string variable.  The value of user_exit_string is the command line to a foreign function.

The following are foreign function parameters and their corresponding Form Builder definitions for each foreign function invoked from a user exit:

Foreign Function Parameter	Form Builder Definition
Command Line	user_exit_string.
Command Line Length	length (in characters) of user_exit_string.
Error Message	error_string.
Error Message Length	length (in characters) of error_string.
In-Query	a boolean value that reflects whether the foreign function was invoked from a user exit when the form was in Enter Query mode.

Although Form Builder automatically invokes the foreign function from the user_exit_string, Form Builder does not automatically parse the user_exit_string.  It is the responsibility of the foreign function to parse the user_exit_string.

You can pass any number of parameters to a foreign function from the user_exit_string of the USER_EXIT built-in.  Use this feature to pass information such as item names.  For example, to pass two parameters, PARAM1 and PARAM2, to the CALCULATE_VALUES foreign function, you specify the following statement:

User_Exit('CALCULATE_VALUES PARAM1 PARAM2');


Returning a value from a foreign function using USER_EXIT

  Related Topics

When the execution of the Form Builder USER_EXIT built-in subprogram is complete, an integer value is returned to Form Builder.  This integer value indicates whether the USER_EXIT built-in subprogram executed with success, failure, or a fatal error.  (For example, if you are creating a foreign function in C, Form Builder provides the constants in a ".h" file.)

Error variables in Form Builder--FORM_FAILURE, FORM_FATAL, and FORM_SUCCESS--are set according to the value that is returned from the USER_EXIT built-in subprogram.  You can query the error variables to determine the success or failure of the execution of the USER_EXIT built-in subprogram just as you would for any built-in subprogram.  The trigger that calls the USER_EXIT built-in subprogram determines how to handle the return condition.

For example, you might want to check the value of FORM_SUCCESS after executing a foreign function from a user exit:

User_Exit('my_exit');

IF NOT Form_Success THEN

/* handle the error */

END IF;


About writing a user exit on Microsoft Windows

  Related Topics

On Microsoft Windows, a foreign function that can be invoked from a user exit is contained in a dynamic link library(DLL).  A DLL is a library that loads into memory only when the contained code is invoked, and a DLL can be shared by multiple applications.  Before proceeding, you should be familiar with the procedure for building DLLs, as described in your compiler manual.

Note: Some C runtime functions are not available in .DLL files.  For more information, refer to your compiler documentation.

The following is an example of creating and invoking a foreign function from a user exit. This example uses the UE_SAMP.MAK project file.


Writing a user exit on Microsoft Windows

  Related Topics

To create a foreign function that can be invoked from a user exit on Microsoft Windows:

1.	Write a foreign function using Pro*C and Oracle precompiler statements to access the database.

For example, create a text file called UEXIT.PC, then add the following text:

/* UEXIT.PC file */

/* This foreign function adds an ID column to the EMP table. */

#ifndef UE

#include "ue.h"

#endif

#ifndef _WINDLL

#define SQLCA_STORAGE_CLASS extern

#endif

EXEC SQL INCLUDE sqlca.h

void AddColumn() {

EXEC SQL alter table EMP add ID varchar(9);

}

2	Precompile the foreign function with an Oracle precompiler (Pro*C precompiler).

For example, use Pro*C to precompile the UEXIT.PC file.  When you precompile UEXIT.PC, Pro*C creates a C file called UEXIT.C.

3.	Create your header files.

Your header file must define your foreign function.  For example, modify the sample header file, UE.H, by adding the following text:

extern   void   AddColumn();

4.	Compile UEXIT.C to generate a foreign function object code file.  Be sure to specify the large memory model on your compiler.

5.	Create the IAPXTB control structure.

Modify the file UE_XTB.C file by including the UEXIT.H file and adding the user exit name, foreign function name, and language type.  Follow the example in the UE_XTB.C file.  In this case, the following entry is added to the file:

Add_ID_Column, AddColumn, XITCC

6.	Modify any required foreign function integration files.

Modify the UE_SAMP.DEF file by adding export statements to include the AddColumn foreign function.  Follow the examples in the UE_SAMP.DEF file.

7.	Build a DLL for use with Forms Runtime.

With the exception of UEXIT.C, the following files should already be included in the UE_SAMP.MAK project file:

\orawin95\forms\userexit\uez.obj

\orawin95\forms\userexit\osswep.obj

\orawin95\forms\userexit\ue_samp.def

\orawin95\forms\userexit\ue_xtb.c

\orawin95\forms\userexit\uexit.c

The UE_SAMP.MAK project is set up to link the following files:

LIBC.LIB

OLDNAMES

\orawin95\forms60\userexit\f60r.LIB

\orawin95\pro20\userexit\sqllib18.lib

\orawin95\pro20\userexit\sqxlib18.lib

After building the UE_SAMP.MAK project, the result is a DLL named UE_SAMP.DLL.  Add the UE_SAMP.DLL entry to the list of DLLs defined by the FORMS60_USEREXITS parameter in the registry.

Alternatively, you can rename UE_SAMP.DLL to F60XTB32.DLL, backup the F60XTB32.DLL in the c:\orawin95\bin directory, and copy the new F60XTB32.DLL to the c:\orawin95\bin directory.

8.	Make sure you include the name of the DLL in the FORMS60_USEREXITS variable in the registry, or rename the DLL to F60XTB32.DLL.  If you rename the DLL to F60XTB32.DLL, replace the existing F60XTB32.DLL in the \ORAWIN95\BIN directory with the new F60XTB32.DLL.

9.	Invoke the foreign function from a user exit in Form Builder.

In this case, a When-Button-Pressed Trigger calls the foreign function from a user exit.  The following statement demonstrates how to invoke the AddColumn foreign function by specifying the user exit name Add_ID_Column in the USER_EXIT built-in subprogram:

/* Trigger: When-Button-Pressed */

USER_EXIT('Add_ID_Column');


Microsoft Windows user exit interface files

  Related Topics

During the installation of Form Builder for Windows, a group of files related to the user exit interface (with the exception of F60XTB32.DLL) are copied to the \ORAWIN95\FORMS60\USEREXIT directory.  You may not require all of the files contained in this directory.  All foreign functions that can be invoked from a user exit interface from Form Builder for Windows must be contained in a DLL.

F60XTB32.DLL	is the default file containing foreign functions that can be invoked from a user exit interface.  This file is a DLL that ships with Form Builder, and does not initially contain user-defined foreign functions.  This file is placed in the \ORAWIN95\BIN directory during installation.  When you create new foreign functions, replace the existing F60XTB32.DLL file with a new F60XTB32.DLL.

To assist you in creating the IAPXTB control structure, Form Builder provides you with two IAPXTB control structure source files, UE_XTB.C and UE_XTBN.C.  Each file serves as a template for creating an IAPXTB control structure.  Modify a IAPXTB control structure source file to include the foreign functions you define.  Include the appropriate file in your project.  You only need one of the two source files to create the IAPXTB control structure.

UE_XTB.C	is a file that contains an example of an entry for the IAPXTB control structure.  Modify this file and add your foreign function entries.  This is the file that is in the UE_SAMP.MAK project file.
UE_XTBN.C	is a file that contains an empty IAPXTB control structure.  Add your foreign function entries to create an IAPXTB control structure.  This is the file that is in the UE_XTBN.MAK project file.

The following files are project files that contain all the required files to create a DLL containing foreign functions that you can invoke from a user exit interface in Form Builder.

UE_SAMP.MAK	is a project file that includes the IAPXTB control structure from the UE_XTB.C file.  Building this project generates UE_SAMP.DLL.  You can rename the DLL from UE_SAMP.DLL to F60XTB32.DLL and replace the existing F60XTB32.DLL in the \ORAWIN95\BIN directory, or you can add UE_SAMP.DLL to the list of DLLs defined by the FORMS60_USEREXITS parameter in the registry.
UE_XTBN.MAK	is a project file that includes the IAPXTB control structure from the UE_XTBN.C file.  Building this project generates UE_XTBN.DLL.  This is the project file that is used to generate the initial F60XTB32.DLL that resides in the \ORAWIN95\BIN directory.  You can rename the DLL from UE_XTBN.DLL to F60XTB32.DLL and replace the existing F60XTB32.DLL in the \ORAWIN95\BIN directory, or you can add UE_XTBN.DLL to the list of DLLs defined by the FORMS60_USEREXITS parameter in the registry.

In addition to your foreign function object code files and an IAPXTB control structure object code file, you need the following files in your project file to generate a user exit interface DLL (These files are included in UE_SAMP.MAK and UE_XTBN.MAK):

UE_SAMP.DEF	contains definitions you need to build your own DLL.
OSSWEP.OBJ	is the Dynamic Link Library Windows Entry Point .OBJ file you need to build your own DLL.  (You may replace OSSWEP.OBJ with an .OBJ file of your own.)
UEZ.OBJ	is an .OBJ file that you link to your own .OBJ files.


Compiling Microsoft Windows foreign functions

  Related Topics

When compiling your foreign functions, be sure to specify the large memory model.  Refer to your Microsoft Windows compiler documentation for additional information, such as restrictions on building a Microsoft Windows DLL, and the use of #define statements.  (Your foreign function code may need to include the UE.H file to access typedefs and #define statements.)


Creating the IAPXTB control structure for Microsoft Windows

  Related Topics

Create the IAPXTB control structure by using the UE_XTB.C or the UE_XTBN.C file as a template.  Alternatively, create your own IAPXTB control structure in a self-defined file.

Note: On Microsoft Windows, an IAPXTB control structure is required for building each DLL that contains foreign functions that can be invoked from a user exit.  Include only those entries in the IAPXTB control structure used for corresponding foreign functions that are contained in a DLL.

The following is an excerpt from a slightly modified UE_XTB.C file:

extern exitr iapxtb[] = { /* Holds exit routine pointers */

   "UE_Name", UE_Funct, XITCC,

   "USEREXECSQL", uxsql, XITCC,

   (char *)0, 0, 0    /* zero entry marks the end */

} /* end iapxtb */

The file includes the user exit name UE_Name.  In this example, the following line was added to the original UE_XTB.C file:

"UE_Name", UE_Funct, XITCC,

UE_Name	is the user exit name for use by the USER_EXIT built-in subprogram to invoke the foreign function from Form Builder.
UE_Funct	is the name of the foreign function that temporarily takes over processing control from Form Builder.
XITCC	specifies the C programming language that is used to develop the foreign function.


About building a Microsoft Windows dynamic link library

  Related Topics

Two project files, UE_SAMP.MAK and UE_XTBN.MAK, are guides to help you create a DLL containing foreign functions that can be invoked from a user exit.

You also have the option of defining your own project file.  When creating your own project file, remember to include a IAPXTB control structure object code file, the foreign function object code files, and the required files for integrating foreign functions that can be invoked from a user exit in Form Builder.

One of the required files for integrating foreign functions with Form Builder is the UE_SAMP.DEF file.  Use the UE_SAMP.DEF file to export foreign functions.  Some export statements for Form Builder already exist.  Do not modify the existing export statements, because the functions are used by Form Builder to access user exits.

The UE_SAMP.MAK project file is used here as an example.  In addition to the object code files containing your foreign functions, UE_SAMP.MAK includes the following files:

\orawin95\forms60\userexit\uez.obj

\orawin95\forms60\userexit\osswep.obj

\orawin95\forms50\userexit\f60xtb.def

\orawin95\forms60\userexit\ue_xtb.c

You must also link the following files:

LDLLCEW.LIB

LIBW.LIB

OLDNAMES

\orawin95\forms60\userexit\F60R.LIB

If you are creating an Oracle Precompiler foreign function, you must link the following libraries:

\orawin95\forms60\userexit\sql18win.lib

\orawin95\forms60\userexit\sqx18win.lib

You create UE_SAMP.DLL after building the UE_SAMP.MAK project file.  You can rename UE_SAMP.DLL to F60XTB32.DLL, make a backup copy of F60XTB32.DLL located in \ORAWIN95\BIN, and replace the existing F60XTB32.DLL with the new F60XTB32.DLL.  Alternatively, you can add UE_SAMP.DLL to the list of DLLs defined by the FORMS60_USEREXITS parameter in the registry.


Defining foreign functions in multiple dynamic link libraries

Foreign functions developed for use in Form Builder for Windows are contained in DLLs.  Form Builder establishes a single DLL, F60XTB32.DLL, for containing foreign functions.  F60XTB32.DLL is the default DLL for containing foreign functions.  Multiple foreign functions can be contained in a single DLL.

Using a single DLL that contains all foreign functions can cause conflicts, especially when two programs try to access the same DLL.  To alleviate dynamic library conflicts, Form Builder supports multiple user exit DLLs; foreign functions can be contained in multiple DLLs without restrictions on the name of the DLL.

FORMS60_USEREXITS parameter  The FORMS60_USEREXITS parameter in the registry allows you to define multiple DLLs to contain foreign functions that can be invoked from a user exit.  The FORMS60_USEREXITS parameter includes a semicolon delimited list of user exit DLLs.

This is an example of defining multiple user exit DLLs

FORMS60_USEREXITS = C:\mathlib\add.dll;C:\mathlib\mult.dll;

A DLL loads into memory when any one of the foreign functions it contains is invoked from the user exit.  Although the FORMS60_USEREXITS parameter can list many DLLs that each contain multiple user exit foreign functions, only one such DLL is in memory at any time.

Form Builder determines the foreign function to invoke from a user exit using the following criteria:

•	If the FORMS60_USEREXITS parameter does not exist in the registry, foreign functions must be contained in a single user exit DLL named F60XTB32.DLL and located in the \ORAWIN95\BIN directory.

•	If the FORMS60_USEREXITS parameter exists in the registry and there are multiple user exit DLLs define, the first occurrence of the foreign function in the list of DLLs is invoked.

•	If there are multiple user exit DLLs that contain non-unique foreign function names, the non-unique function name that is invoked is the first occurrence of function that follows the content in the user exit cache memory.

NOTE:  To avoid calling an unexpected foreign function, do not use the same foreign function name more than once in any of your user exit DLLs.  An example of a non-unique function name is when two different functions have the same name, but are contained in different user exit DLLs.

User Exit Cache Memory  Form Builder deals with non-unique function names by maintaining a user exit cache memory.  Exiting a form clears the user exit cache memory, otherwise the user exit cache memory retains the last called foreign function in memory until you call another foreign function.

Invoking a foreign function that has a non-unique function name depends on what is in the user exit cache memory.  The first occurrence of a foreign function with a non-unique function name that follows the foreign function in the user exit cache memory is invoked.

If the user exit cache memory is empty, the first occurrence of a function with the non-unique function name in the list of DLLs is invoked.  Because the cache memory is not cleared until you exit a form, subsequent calls to a non-unique function name may result in an unexpected foreign function call.  For instance, you may accidentally call a function that follows a function with a unique name as opposed to calling a function that appears earlier in the sequence of user exit DLLs.  Although in many cases, the user exit cache memory correctly identifies foreign functions with non-unique names, you should use unique foreign function names in the list of DLLs that are members of the FORMS60_USEREXITS variable whenever possible.


Accessing the Microsoft Windows SDK from a User Exit

  Related Topics

You can invoke Microsoft Windows SDK functions from a user exit.  Invoking Microsoft Windows SDK functions is similar to invoking user-defined foreign functions from a user exit on Microsoft Windows.  Instead of including the object code files of your user-defined foreign function when building a dynamic link library, you must include the source files of the Microsoft Windows SDK function.

Parameter values for Microsoft Windows SDK functions can be passed to or received from Form Builder like other foreign functions.  For Microsoft Windows SDK functions that require a window handle parameter, you can obtain the window handle from Form Builder using the GET_ITEM_PROPERTY function to examine the Window_Handle property.  A window handle is a unique internal character constant that is used to refer to objects.

There are many reasons for accessing the Microsoft Windows SDK.  For example, by obtaining a window handle from Form Builder, you can invoke Microsoft Windows SDK functions to externally modify the properties of objects in your Form Builder applications.  The following is an example of calling the Microsoft Windows SDK function GetWindowRect from a Form Builder trigger or user-defined subprogram:

:block1.item_handle := get_item_property('block1.item1',Window_Handle);

USER_EXIT(GetWinRec || :block1.item_handle,'error_message');


Deploying Forms on the Web

  Display the HTML (in 95)	  Display the HTML (in NT)

Deploying Applications on the Web provides both conceptual and reference information to help you deploy your new and existing Forms Developer applications on the Web.  Documentation specific to deploying Forms applications on the Web is found here.

During the Oracle Developer install process, an HTML version of Deploying Applications on the Web is placed in /BIN directory of your ORACLE_HOME directory.  If you are using Microsoft Windows NT the ORACLE_HOME directory is usually \ORANT.  If you are using Windows 95 (or 98) the ORACLE_HOME directory is usually \ORAWIN95.  You can display the table of contents in your default browser from this directory, or by clicking the appropriate Display the HTML button at the top of this topic.


Introducing windows and canvases

When you build a form, you use windows and canvases to present the visual elements of a form (i.e., interface items and boilerplate objects) to end users.  A single form can include any number of windows and canvases.

The Relationship Between Windows and Canvases  For each window you create, you also must create at least one canvas;  similarly, each canvas you create must be assigned to a window.  At runtime, windows and canvases are displayed and closed in response to navigation events and programmatic control.

To define the relationships between interface items, canvases, and windows, you must set a variety of their properties.  For example, each interface item (text item, check box, etc.) has a Canvas property that specifies the canvas on which the item is displayed.  (Note that when you create an item in the Layout Editor, Form Builder sets this property for you automatically, depending on the current canvas.)  Similarly, each canvas has a Window property that specifies the window in which it is displayed.


What is a window?

  Related Topics

A window is a container for all visual objects that make up a Form Builder application, including canvases.  A single form can include any number of windows.  While every new form automatically includes a default window named WINDOW1, you can create additional windows as needed by inserting them under the Windows node in the Object Navigator.

By itself, the window object is an empty frame.  The frame provides a title bar and handles for interacting with the window, making it possible for end users to scroll, move, and resize the window.

A windows typically contains a canvas with navigable items, and thus is invoked at runtime in response to navigation to items on that canvas.  Windows also can be displayed and closed programmatically, independent of any item navigation events.  At runtime, when a window is displayed programmatically, or when navigation occurs to an item on a canvas assigned to that window, Form Builder displays the window with the appropriate canvas background.

To define the appearance and functionality of the windows you create, you can specify numerous window properties, including size, display position, and title.  You also can get (examine) and set most properties programmatically at runtime.  Finally, you can dynamically show and hide windows as required.


About window types

  Related Topics

When you create a window, you specify its type by setting the Window Style property.

There are two window styles:

•	Document

•	Dialog

Document Windows  Document windows typically display the main canvases and work areas of your application where most data entry, and data retrieval is performed.

Dialog Windows  Dialog windows are free-floating, containers typically used for modal dialogs that require immediate user interaction.


What is a canvas?

A canvas is a surface--inside a window container--on which you place the interface items and boilerplate objects that end users interact with when they run the form.  By default, any canvas you create at runtime is assigned to the window named WINDOW1.  To explicitly associate a canvas to a specfic window, set the canvas' Window property accordingly.


About canvas types

  Related Topics

Form Builder provides four types of canvases, all of which can be displayed in the same window at runtime.  A canvas' type defines how Form Builder will display it in the window to which it is assigned.  When you create a canvas, you specify its type by setting the Canvas Type property.  The four canvas types are:

•	Content

•	Stacked

•	Tab

•	Toolbar

Content Canvas  The most common canvas type is the content canvas (the default type).  A content canvas is the "base" view that occupies the entire content pane of the window in which it is displayed.  You must define at least one content canvas for each window you create.

Stacked Canvas  A stacked canvas is displayed atop—or stacked on—the content canvas assigned to the current window.  Stacked canvases obscure some part of the underlying content canvas, and often are shown and hidden programmatically.  You can display more than one stacked canvas in a window at the same time.

Tab Canvas  A tab canvas—made up of one or more tab pages—allows you to group and display a large amount of related information on a single dynamic Form Builder canvas object.  Like stacked canvases, tab canvases are displayed on top of a content canvas, partly obscuring it.  Tab pages (that collectively comprise the tab canvas) each display a subset of the information displayed on the entire tab canvas.

Toolbar Canvas  A toolbar canvas often is used to create toolbars for individual windows.  You can create two types of toolbar canvases:  horizontal or vertical.  Horizontal toolbar canvases are displayed at the top of a window, just under its menu bar, while vertical toolbars are displayed along the far left edge of a window.


About views

  Related Topics

When you work with canvases in Form Builder, the relationship between a canvas and its view is a fundamental concept.  Think of the view as a rectangle positioned over the canvas;  the area of the canvas visible within the view is what end users see when the canvas is displayed at runtime.

Modifying the View Size and Position  For a stacked canvas, you can specify the size of the view at design time by setting the View Width and View Height properties.  For a content, tab or toolbar canvas, these properties are ignored because the view size is determined by the size of the window itself.  Changing the size of the window at runtime (e.g., resizing it with the mouse) effectively changes the size of the view for that window's content canvas.

For any type of canvas, you can set properties that specify the view's point of origin on the canvas;  that is, to position the view rectangle at a specific location on its canvas.  Moving the view, like resizing the view, changes the part of the canvas that end users see in the window at runtime.  When a content canvas is larger than its view (that is, larger than its window), the window can be scrolled to change the position of the view on the canvas, thus making a different part of the canvas visible.


About MDI and SDI windows

  Related Topics

Form Builder fully supports both the Microsoft Windows MDI (Multiple Document Interface) and SDI (Single Document Interface) systems of window management.

Multiple Document Interface

MDI applications display a default parent window, called the application window.  All other windows in the application are either document windows or dialog windows.

Document windows always are displayed within the MDI application window frame.  If the end user resizes the MDI window so it is smaller than a document window, the document window is clipped.  end users can maximize a document window so that it occupies the entire content area of the application window.  Dialog windows are free-floating, and the end user can move them outside the application window if they are defined as movable.  If the end user resizes the MDI window to make it smaller than a dialog window, the dialog window is not clipped.

The MDI application window is created by the window manager at runtime, and does not appear in a form's list of windows.  However, you can use the SET_WINDOW_PROPERTY built-in to resize, minimize, and maximize the MDI window programmatically.

Single Document Interface

Although MDI is the default system of window management during Forms Runtime, Form Builder also provides support for an SDI root window on Microsoft Windows.

You can set the system of window management to SDI by specifying the USESDI command line option.  When SDI is enabled, calls to the FORMS_MDI_WINDOW constant returns NULL for the MDI window handle.  There is no multiple interface root window, MDI toolbars exist in parent windows, and MDI menus are attached to each window.


About the root window

Note:  the concept of a root window is no longer used in Form Builder Release 5 and later.  However, for purposes of forward compatibility, the name ROOT_WINDOW, the associated properties and built-ins, and the root window behavior are still supported.

A root window displays the console for the currently-active form in your application.  Creating a root window in a form is optional, and is used most often in multiple-form applications (which are designed to run several form modules simultaneously).

A root window has special characteristics.  In a multiple-form application, using a root window allows you to have a single window that always displays the console for the currently-active form.  This is an advantage only on platforms other than Microsoft Windows, since on Microsoft Windows the console always appears on the MDI application window.

At runtime, only one root window can be displayed at a time.  When several forms, each of which has a root window, are running at the same time, the result is a single root window that displays the console for whichever form is currently the active form in the application.

In addition to displaying the active form's console, the root window in a multiple-form application also displays the current form's current content canvas.  As the end user navigates between open forms, the background area of the root window updates to display the canvas that is assigned to the root window in the currently active form.

In a multiple-form application, the fact that there can be only one root window displayed at a time also affects the behavior of forms that invoke other forms by executing the OPEN_FORM or CALL_FORM built-ins.  If both the called form and the calling form have a root window, and the first navigable item in the called form is on a canvas assigned to the root window, then executing OPEN_FORM or CALL_FORM causes the called form to take over the root window from the calling form.

Creating a Root Window You create a root window by creating a default window and giving it the name ROOT_WINDOW.

For non-Microsoft Windows forms, you indicate the window on which you want the console to display by setting the Console Window form property.  In a multiple-form application, you can create a root window in each form, and assign the console to it by setting the Console Window property to ROOT_WINDOW.

Due to the root window's unique characteristics, some of its properties have fixed settings.  Overriding these settings in the Form Builder has no effect on the window's runtime behavior.  The properties (and their default settings) are as follows:

•	Closeable  (Yes)

•	Fixed Size  (No)

•	Iconifiable  (Yes)

•	Inherit Menu  (Yes)

•	Movable  (Yes)

•	Name

•	Remove on Exit  (No)

•	Style  (Document)

•	Vertical/Horizontal Scroll Bar  (No)

•	Zoomable  (Yes)

Displaying the Root Window  Form Builder displays the root window at form startup, and it remains displayed throughout the session.  This is true even if the root window does not contain navigable items or even any canvases. For example, an application might use the root window only as a menu bar that displays the Form Builder status and message lines, and then use secondary windows to display the main application canvases.


About the console

  Related Topics

The console includes the status line and message line, and is displayed at the bottom of the window to which it is assigned.

On Microsoft Windows, the console is displayed on the MDI application window by default;  you cannot display it on individual document or dialog windows in the form.  To hide the console, set the form-level property Console Window to NULL.

On non-Windows platforms, you can display the console in one window only, and you cannot change the console assignment at runtime.  To display the console in a window, set the form-level property Console Window to the appropriate window.  To hide the console, set the form property Console Window to NULL.


About window modality

  Related Topics

A window can be either modeless or modal.  A modal window (often a dialog) requires the end user to respond before continuing to work in the current application.  A modeless window requires no such response.  When you create a window, you specify its modality by setting the Modal property to Yes or No.  The default is No (modeless).

Modeless Windows  You can display multiple modeless windows at the same time, and end users can navigate freely among them (provided your application logic allows it).  On most GUI platforms, you can layer modeless windows so that they appear either in front of or behind other windows.

Modeless windows remain displayed until they are dismissed by the end user or hidden programmatically.  You can set the Hide on Exit property for a modeless window to specify whether it should remain displayed when the end user navigates to another window.  You also can set the properties of a modeless window to specify its border and title, and whether end users should be allowed to scroll, resize, move, close, iconify, and zoom the window.

Modal Windows  Modal windows are usually used as dialogs, and have restricted functionality compared to modeless windows.  On some platforms, for example, end users cannot resize, scroll, or iconify a modal window.  Modal windows are often displayed with a platform-specific border unique to modal windows. On some platforms, modal windows are "always-on-top" windows that cannot be layered behind modeless windows.

In addition to platform-specific restrictions, modal windows have the following characteristics:

•	The Hide on Exit property does not apply to modal windows.  By default, Form Builder prevents end users from navigating out of modal windows with the mouse, but does allow them to navigate to another window with keyboard commands.  When such navigation occurs, Form Builder always closes the modal window, unless the target window is itself a modal window.

•	Modal dialog windows cannot have scroll bars, thus setting the Scroll Bar properties has no effect. (Modal non-dialog windows, however, can have scroll bars.)

System-level vs. Application-level Modality  On some platforms, modal windows are modal only with respect to other windows in the same application.  That is, when Form Builder displays a modal window, the end user is still allowed to work in windows owned by other applications.

On other platforms, modal windows are modal with respect to the entire system, and must be dismissed before end users can send input to windows that belong to other applications.


About scrolling windows

A scrolling window allows an end user to use scroll bars to scroll the content canvas currently displayed in that window.  Conceptually, think of scrolling as moving the content canvas to change the X,Y coordinates of the view's point of origin, thereby revealing a different part of that canvas.  Note that scrolling does not change the size of the view, merely its location on the canvas.

A window can be scrolled horizontally only when its display width is less than the width of the content canvas currently displayed in the window.  Similarly, it can be scrolled vertically only when its height is less than the height of its current content canvas.  (Remember that end users can change the size of a window at runtime.)

When a window is the same size as or larger than its current content canvas, scrolling has no effect since no portion of the canvas is outside the current view (that is, outside the window itself).

The scroll bars on a window scroll only the window's content canvas; however, any stacked canvases displayed in the window will move up/down and left/right as if they were part of the content canvas.  (You can also define scroll bars on stacked canvases, but these are independent of the window's scroll bars.)


Creating a window

  Related Topics

To create a window:

1	In the Object Navigator, click the Windows node.

2	Click the Create button [image] in the toolbar.

Form Builder creates a window, and gives it a default name, such as WINDOW3.

3	Double-click the window's object icon.

4	In the Property Palette, set the window properties as desired.

The properties under the Functional and Physical nodes control the window's appearance and functionality at runtime.  Some window managers may not support all of these properties.

Note:  You must assign at least one content canvas to every window you create.  To assign a canvas to a window, set the canvas' Window property to the appropriate window.


Creating a scrolling window

To create a scrolling window:

1	Create a window and set its properties as follows:

Width/Height The initial display size.  (Remember that end users can resize a window at runtime if you allow them to.)

Modal  No.  (A modal window cannot be scrollable.)

H/V Scroll Bar  Yes, for one or both.  (Controls the direction in which end users should be able to scroll the window.)

2	Create a canvas for the window and set its properties as follows:

Canvas Type  Content.

Width/Height  Set so the canvas is larger than its window.

Window  The name of the window you created in Step 1.

View H/V Scroll Bar  Ignore.  (These properties apply only to a stacked canvas.)


Associating an icon with a window

  Related Topics

On GUI platforms, end users can iconify, or minimize, a modeless window so that it is represented on the screen by only a bitmap icon.  Once iconified, the end user can redisplay the window by double-clicking the icon.

To create an iconifiable window, you must associate the window with an icon resource file that exists in your runtime operating system.  To do so, set the following window properties:

Minimize Allowed  Yes.

Icon Filename  Name of the bitmap icon file.  (Form Builder searches for this file in your system's default resource path.)

Minimized Title  Text that displays with the icon at runtime.  (If you do not specify a title, some window managers use a default title for the icon.)

To prevent end users from iconifying a window, set the Minimize Allowed property to No.   (The Icon Filename and Minimized Title properties are ignored if the Minimize Allowed property is set to No.)

Note:  On Microsoft Windows, the lookup path for icon files is defined by the UI60_ICON environment variable located in the ORACLE.INI file, or in the Microsoft Windows 32-bit registry.  When you enter the name of the icon file in the Icon Filename property, do not include the path or .ICO file extension.


About modal dialog windows

Modal dialog windows often are used as interactive dialog boxes.  When an application needs information from the end user before it can continue, you can display a modal dialog window to allow the end user to enter the required information.  Most dialogs require the end user to either provide the necessary information or dismiss the dialog and cancel the operation.

File and Print dialogs are examples of interactive windows that—on most GUI platforms—are implemented as modal dialogs.  Alerts and lists of values (LOVs) are examples of specialized modal dialog windows that are native objects in Form Builder.


Displaying a modal dialog window

  Related Topics

When you create a modal dialog, decide how the dialog will be displayed and closed.  Since a modal dialog requires input from the end user, its content canvas always should contain navigable items.  For this reason, the simplest way to display a modal dialog is through navigation from an item in the current window to the first navigable item in the dialog window.  When such navigation occurs, Form Builder automatically displays the window (in this case, the modal dialog) that contains the target item.

The navigation event might be the end user pressing the Tab [Next Item] key, or, more likely, a button trigger or menu command that navigates programmatically.  For example, you might call the NEXT_BLOCK, GO_BLOCK, or GO_ITEM built-ins from a When-Button-Pressed trigger to navigate to a target item in the dialog.

You can also execute the SHOW_WINDOW built-in to display the modal window.  When you use SHOW_WINDOW to display a modal window, it implicitly navigates to the first navigable item on the canvas for that window.

Invoking a Modal Window from a Modal Window  You can invoke a modal window from another modal window.  For example, the standard Microsoft Windows Printer Setup modal dialog has an Options button that invokes a second modal dialog.  When a modal window has been invoked from another modal window, navigation to any modeless window in the same form automatically closes both the parent and child modal windows.


Closing a modal dialog window

Most application designs call for modal dialogs to remain displayed until the end user either accepts or cancels them.  When you create such a window, you must ensure that the end user is only allowed to close it in response to the desired events.

By default, setting the Modal property to Yes prevents end users from navigating out of the window with the mouse, but does not prevent them from navigating to another window by pressing keys such as [Next Item] (Tab) or [Next Block].  When end users are allowed to use keys to navigate to another window, Form Builder always closes the modal window, unless the target window is itself a modal window. (Note that the Hide on Exit property is ignored for a modal window.)

If you navigate to a new modal window, the old modal window stays up. However, trying to navigate from a modal window to a different modal window which was already up causes the current window to be hidden.

Defeating Keyboard Navigation  When you implement a modal dialog, usually you want to prevent the end user from navigating out of the window with navigation keys;  you want the dialog to be closed only in response to specific events, such as the end user pressing an OK or Cancel button.

You can defeat keyboard navigation out of a modal dialog in several ways:

•	Set the Previous Navigation Block and Next Navigation Block properties for the blocks in the dialog to prevent end users from navigating with the [Next Block] and [Previous Block] keys.  For example, for a block named DIALOG, you could set both properties to DIALOG to make navigation circular, thus preventing end users from using keys to navigate to any other block.

•	Write appropriate block-level triggers for each block in the modal window.  For example, you might define a block-level Key-Others trigger that would disable all keys except those keys for which you had also defined a key-trigger (such as Key-Nxt-Item) to enable tabbing between items in the modal window.

Once you have prevented end users from closing a dialog through keyboard navigation, you must write the commands to close the dialog in response to the desired events.  You can close a modal dialog programmatically by navigating to an item or block in a modeless window with built-ins such as GO_ITEM and GO_BLOCK.  For example, a modal window might contain an OK button with a When-Button-Pressed trigger that executes a GO_BLOCK statement to navigate out of the modal window.


Creating a modal dialog window

To create a modal dialog window:

1	Create a new window and set its properties as follows:

Window Style  Dialog.  (Valid only on Microsoft Windows.)

Modal  Yes.

Width/Height  Optional.  (A dialog typically is smaller than the modeless window from which the end user invokes it.)

2	Create a content canvas and set its Window property to the modal window you created in Step 1.

3	Create the items that will appear in the window.

4	Decide on the events that will display and close the modal dialog at runtime.


About working with canvases

While you can create and delete canvases in the Object Navigator, you will use the Layout Editor to accomplish most of your canvas-related tasks.

Editing Canvases  In the Layout Editor, you edit one canvas at a time.  By default, the canvas itself is an object that can be selected and formatted.  You can hide the canvas object by toggling the View [image] Show Canvas menu option.  Many canvas properties can be set graphically in the Layout Editor, as well as in the Property Palette.

Note:  You cannot clear, cut, copy, export, or duplicate the canvas or view objects in the Layout Editor.


Creating a canvas

  Related Topics

To create a canvas in the Object Navigator:

1	In the Object Navigator, click the Canvases node, and Click the Create button [image] in the toolbar.

Form Builder creates a new canvas, and gives it a default name, such as CANVAS4.

2	Click the canvas'  object icon, and choose Tools [image] Property Palette.

3	In the Property Palette, under the General node, set the Canvas Type property to the desired type.

Note:  The default canvas type is Content.  For a content canvas, the properties that appear under the Stacked View heading do not apply.

4	Set the Window property to the window in which you want to display the canvas.

By default, new canvases are assigned to the first window listed under the Windows node in the Object Navigator.

Note:  To display the new canvas in the Layout Editor, double-click the canvas' object icon in the Object Navigator.


Defining a primary canvas

  Related Topics

To define the primary canvas for a window, set its Primary Canvas property to the desired canvas.  Form Builder displays a window with its primary canvas when the window is being displayed programmatically, rather than in response to a navigation event.

When to Set the Primary Canvas Property  Setting the Primary Canvas property is optional.  Most windows are displayed in response to navigation to an item on a specific canvas.  In such cases, setting the Primary Canvas property is not required, since the canvas to be displayed is never ambiguous.

The first time you display a window during a session by using the SHOW_WINDOW built-in, Form Builder displays the window with its primary canvas.  If the Primary Canvas property is left unspecified, the window is displayed without a view, and appears empty.

You also might want to set the Primary Canvas property in the situation when a window is displayed due to navigation to an item on a stacked canvas.  If you want the window's content canvas to be displayed behind the stacked canvas, you must set the Primary Canvas property accordingly.

Form Builder always displays the target item and canvas during a navigation event.  So even if you have set the Primary Canvas property to specify a primary canvas, Form Builder will display a different canvas if necessary to make the target item visible.


Deleting a canvas

  Related Topics

To delete a canvas:

1	In the Object Navigator, click the object icon of the canvas you want to delete.

2	Click the Delete icon in the toolbar.

Note:  When you delete a canvas, Form Builder also deletes any boilerplate items that are part of the canvas.  However, interface items assigned to the canvas are not deleted;  rather, they become NULL-canvas items (items that are not assigned to any canvas).  Note that NULL-canvas items are not displayed at runtime.


Working with stacked and tab canvases in the Layout Editor

You can create and edit both stacked and tab canvases directly in the Layout Editor.

Creating  To create stacked or tab canvases, you can use the Stacked Canvas or Tab Canvas buttons on the Layout Editor toolbar.  To create a tab canvas, for example, first display the Layout Editor.  Next, click [image] in the toolbar, then click-drag a rectangular region where you want the tab canvas to appear on the underlying content canvas.  Once you have created the tab canvas in this manner, you can immediately resize or move it while still in the Layout Editor.

Editing  You can use the Layout Editor to edit items on a stacked or tab canvas in two ways:  (1) directly, or (2) on the stacked view of a content canvas.  To directly edit a stacked or tab canvas, invoke the Layout Editor, select the appropriate canvas from the Canvas combination box at the top of the window, then move, resize or manipulate the items of the canvas.  To edit a stacked or tab canvas on the stacked view of a content canvas, invoke the Layout Editor, display the appropriate content canvas, choose Show [image] Stacked Views, select the appropriate canvas from the Stacked Canvases dialog, then move, resize, or manipulate the items of the canvas.

Automatic Synchronization  Form Builder automatically synchronizes items on the stacked view of the content canvas and the corresponding item on the actual stacked canvas.  For example, any movement, resizing or changes in visual attributes to an item on a stacked canvas from the stacked view on the content canvas is reflected in the stacked canvas when invoked from a Layout Editor.  Similarly, when changes are made to items on a stacked canvas from a Layout Editor, the changes are reflected in the stacked view on the content canvas.


Resizing a canvas in the Layout Editor

To resize a canvas in the Layout Editor:

1	In the Layout Editor, make sure the canvas object is displayed by choosing View and checking the Show Canvas option (the default).

2	Scroll the Layout Editor window until the lower right corner of the canvas is visible, then click on the right edge or bottom edge of the canvas to select it.

When the canvas is selected, a black selection handle is displayed at its lower-right corner.

3	Click and drag the selection handle to resize the canvas as desired.


Setting a canvas' visual attributes in the Layout Editor

To set a canvas' visual attributes in the Layout Editor:

1	In the Layout Editor, make sure the canvas is displayed in the Canvas combination box (i.e., it is the current canvas in the Layout Editor).

2	Choose the desired colors from the color palettes.


Adjusting the view in the Layout Editor

  Related Topics

Displaying the View  To display the view for the current canvas as a 1 point black rectangle in the Layout Editor, enable the View [image] Show View menu option.

Resizing the View  For a content or toolbar canvas, the view rectangle represents the window to which the canvas is assigned. Resizing the view in the Layout Editor changes the Width and Height properties of the window.  Conversely, changing the Width or Height properties of the window resizes the view rectangle in the Layout Editor.  For a stacked canvas, the view is independent of the window in which the canvas is displayed, and its size is controlled by the Viewport Width and Viewport Height properties.

Moving the View  To move the view, click on the outline of the view and drag it to the desired location. Moving the view changes the Viewport X/Y Position on Canvas properties. To resize the view, click on it to select it, then drag one of the selection handles.


About content canvases

When building an application, one of the first steps is to create content canvases that will be displayed in the windows of your form(s).  While you can assign more than one content canvas to the same window at design time, at runtime only one content canvas is displayed at one time in the window.

Creating a content canvas

There are three ways to create a content canvas in Form Builder:

•	Layout Wizard  When you use the Layout Wizard to arrange data block items on a canvas, the Layout Wizard allows you to place data block items on a new content canvas (which the Layout Wizard will create for you and give a default name, such as CANVAS3).

•	Layout Editor  In the Layout Editor, you can create items and boilerplate objects on a specific canvas.  (If there are no canvases in a form when you invoke the Layout Editor, Form Builder automatically creates a default content canvas for you to work on.)

•	Object Navigator  To create a content canvas in the Object Navigator, first you create the canvas, then you specify its type by setting the Canvas Type property in the Property Palette.


Assigning multiple content canvases to a window

  Related Topics

If you decide to assign more than one content canvas to the same window at design time, you are designating potential content canvases for that window.  At runtime, you can display only one content canvas in a single window at a time.  In other words, when more than one content canvas is assigned to the same window, runtime events determine which is the current content canvas displayed in that window.

Consider a form with one window and two content canvases (both assigned to the window).  At form startup, Form Builder must determine which canvas initially should be displayed in the window.  By default, Form Builder sets the input focus to the first navigable item in the first block in the form.  In this example, the content canvas that contains the first navigable item in the form (as defined by navigation sequence) becomes the current content canvas for the window.

Now consider an online Help window to which two content canvases are assigned.  Each content canvas displays boilerplate Help text, and neither contains navigable items.  End users can invoke the Help window by pressing a button that executes the SHOW_WINDOW built-in procedure.  Again, Form Builder must determine which canvas initially should be shown when the window is invoked.  Since navigation is not occurring, the content canvas designated as the window's primary canvas is displayed in the window.  (To designate a primary canvas for a window, set the optional Primary Canvas property.)


About stacked canvases

  Related Topics

Stacked canvases are displayed in a window along with the window's content canvas(es) and any number of other stacked canvases.  You can set the bevel, color, and pattern attributes of a stacked canvas to make it look different than the underlying content canvas.  Contrarily, you can make the stacked canvas look like the content canvas, and then show and hide the stacked canvas programmatically so end users are unaware that a separate canvas is being displayed.

This technique can be used to make items or boilerplate appear to change dynamically. When navigating from a content canvas item to a stacked canvas item, you can only see the stacked canvas, since the content canvas disappears.

Creating a stacked canvas is similar to creating a content canvas.  To define a stacked canvas, you need to set certain canvas properties that apply only to stacked canvases, and create items and boilerplate text and graphics as you would for a content canvas.

Note:  To convert an existing content canvas to a stacked canvas, simply change its Canvas Type property from Content to Stacked.

At runtime, stacked canvases are displayed automatically in response to navigation in the same manner as content canvases.  To show and hide stacked canvases programmatically, use the SHOW_VIEW, HIDE_VIEW, and SET_VIEW_PROPERTY built-ins.

Uses for Stacked Canvases

You can use stacked canvases to do the following:

•	Display items or boilerplate graphics that end users need to see only in certain situations.  (Define a stacked canvas that displays help text or images that remain hidden until they are explicitly invoked by the end user.)

•	Display headers that display constant information such as company names, dates, and status information.  (Define a stacked canvas that always appears in front of the current content canvas.  When the current content canvas is replaced by another, the stacked canvas remains visible in the window.  Use this technique to avoid duplicating interface elements on multiple content canvases in the same window.)

•	Create a block with items that scroll dynamically in the window where they are displayed, much like a spreadsheet.  (If a block contains more items than fit in a window, Form Builder automatically scrolls the window as the end user tabs to items outside the window's frame.  This can cause important fields—such as primary key values—to be scrolled out of the window and thus out of the end user's view.  For example, for a block that displays information about orders, the Order ID always should be visible, regardless of navigation by the end user.  By placing the Order ID item on the underlying content canvas, and placing items that can be scrolled out of sight on a stacked canvas, the stacked canvas becomes the scrolling region, rather than the window itself.  Note that stacked canvases can have their own scroll bars, independent of the window's scroll bars.)


Creating a stacked canvas

  Related Topics

To create a stacked canvas:

1	In the Object Navigator, under the Canvases node, double-click the object icon of the content canvas on which you wish to create a stacked canvas.

2	In the Layout Editor, click the Stacked Canvas button in the toolbar.

3	Click-drag the region where you want to place the stacked canvas.

Form Builder creates a stacked canvas, and gives it a default name, such as CANVAS6.

4	In the Object Navigator, under the Canvases node, click the stacked canvas'  object icon, then choose Tools [image] Property Palette.

5	In the Property Palette, under the Physical, Viewport and Miscellaneous nodes, set properties as follows:

Visible  Yes (stacked canvas will be visible when window is invoked),  or No (stacked canvas remains hidden until displayed in response to navigation or programmatic events).

Width/Height  Canvas dimensions.  Stacked canvases typically are smaller than the content canvas(es) in the same window.

Bevel  Canvas border type.  Use a border to visually separate a stacked canvas from other canvases in the same window.

Viewport Width/Height  Dimensions of the stacked canvas'  view.  If the view is smaller than the canvas, end users can scroll the canvas at runtime.

Viewport X/Y Position on Canvas  X,Y display coordinates of the view's upper-left corner (relative to the upper-left corner of the content canvas currently displayed in the window).  0,0 (the default) displays the stacked canvas at the upper-left corner of the content canvas.

View H/V Scroll Bar  Will the stacked canvas have a scroll bar (horizontal, vertical, both, none)?  End users can scroll the stacked canvas independently of the underlying content canvas.

6	Define the stacked canvas' position in the stacking order.

If the stacked canvas is not displayed programmatically or in response to navigation, make sure that its position in the stacking order places it in front of the content canvas assigned to the same window.  If not, it will be shown behind the content canvas, and will not be visible at runtime.  Recall that the stacking order of canvases in a window is defined by the sequence in which they are listed under the Canvases node in the Object Navigator.


Editing a stacked canvas in the Layout Editor

To edit a stacked canvas in the Layout Editor:

1	In the Object Navigator, open the Canvases node and click the object icon of the desired stacked canvas.

2	Double-click the object icon for the stacked canvas.

You now can create items and boilerplate graphics as you would for a content canvas. You can also graphically change the size of the canvas or of the view itself.


Displaying a content canvas' stacked views in the Layout Editor

  Related Topics

To display stacked views assigned to a content canvas' window:

1	In the Object Navigator, under the Canvases node, double-click the content canvas'  object icon.

2	In the Layout Editor, choose View [image] Stacked Views.

Form Builder displays the Stacked Canvases dialog, which shows all stacked canvases assigned to the same window as the content canvas currently displayed in the Layout Editor.

3	Select the stacked canvas(es) that you want to display in the Layout Editor.  (Deselect those you do not want to display).

To select a stacked canvas, click it in the Stacked Canvases dialog.  Control-click multiple stacked canvases to display them on the same content canvas.

To deselect a stacked canvas already displayed on the content canvas, Control-click the selected stacked canvas in the Stacked Canvases dialog.

When you display a stacked canvas this way, you see exactly what the end user will see at runtime.  That is, you see only the portion of the stacked canvas that is within its view, as defined by the Viewport Width and Viewport Height properties.

Once the stacked canvas is displayed, you can change its properties in the Layout Editor by manipulating it graphically, as follows:

•	Move the stacked canvas to change its Viewport X Position and Viewport Y Position properties.

•	Resize the stacked canvas to change its Viewport Width and Viewport Height properties.  Resizing the view this way does not change the size of the canvas, only the size of the view.  To resize the canvas, set the Width and Height canvas properties in the Property Palette.  Only items and boilerplate that are completely on the canvas will display at runtime, even if the view is larger than the canvas.

•	For a stacked canvas with scroll bars, scroll the canvas to change the initial runtime settings for the Viewport X Position on Canvas and Viewport Y Position on Canvas properties.


About tab canvases

  Related Topics

A tab canvas, made up of one or more tab pages, allows you to group and display a large amount of related information on a single, dynamic canvas object.  Like stacked canvases, tab canvases are displayed on top of a content canvas, partly obscuring it.  Tab pages each display a subset of the information displayed on the entire tab canvas.


About tab pages

  Related Topics

A tab canvas can have many tab pages, and must have at least one.  Think of tab pages as the folders in a filing system.  Each individual tab page (folder) has a labelled tab that developers and end users click to access the page.  At design time or runtime, you click the labelled tab to display the page at the front of the tab canvas, thereby obscuring any other page(s).

Each tab page occupies an equal amount of space on the tab canvas, roughly equal to the size of the canvas itself.  This layering of related canvas sections enables you to display more information on a single canvas.

Tab pages are sub-objects of a tab canvas.  Like the canvas to which it is attached, each tab page has properties;  similarly, any item you place on a tab canvas has a canvas property as well as tab page properties.  The ordering of tab pages in the Object Navigator determines the left-to-right (or top-to-bottom) order of the tabs at runtime.


Creating a tab canvas

  Related Topics

To create a tab canvas:

1	In the Object Navigator, under the Canvases node, double-click the object icon of the content canvas on which you wish to create a tab canvas.

2	In the Layout Editor, click [image] in the toolbar.

3	Click-drag the region where you want to place the tab canvas.

Form Builder creates a tab canvas (with two tab pages), and gives it a default name, such as CANVAS6.

4	In the Object Navigator, under the Canvases node, click the tab canvas' object icon, then choose Tools [image] Property Palette to display the Property Palette.

5	Under the Viewport node:

•	Set the Viewport X/Y Position on Canvas properties.  (Enter X,Y display coordinates of the view's upper-left corner, relative to the upper-left corner of the content canvas currently displayed in the window.  0,0 (the default) displays the tab canvas at the upper-left corner of the content canvas.)

•	Set the Viewport Width/Height properties.  (Enter dimensions of the tab canvas' view.  If the view is smaller than the canvas, end users can scroll the canvas at runtime.)

6	Under the Physical node:

•	Set the Visible property to Yes (tab canvas will be visible when window is invoked), or No (tab canvas remains hidden until displayed in response to navigation or programmatic events).

•	Set the Width/Height properties.  (Enter dimensions of the canvas.  Tab canvases typically are smaller than the content canvas(es) in the same window.)

7	Define the tab canvas' position in the stacking order.

If the tab canvas is not displayed programmatically or in response to navigation, make sure that its position in the stacking order places it in front of the content canvas assigned to the same window.  If not, it will be shown behind the content canvas, and will not be visible at runtime.  Recall that the stacking order of canvases in a window is defined by the sequence in which they are listed under the Canvases node in the Object Navigator.


Creating a tab page

  Related Topics

To create a tab page:

1	In the Object Navigator, under the Canvases node, click the Tab Pages node of the tab canvas.

2	Click the Create button [image] in the toolbar once for each tab page you wish to create.

Form Builder creates the tab page(s) and provides a default name for each, such as PAGE3.

3	Choose Tools [image] Property Palette.

4	In the Property Palette, under the Functional node, set the Label property to the text you want to appear on the tab page's tab area at runtime.  (End users will click the tab area to navigate between the pages of a tab canvas.)


Placing an item on a tab page

To place an item on a tab page:

1	In the Object Navigator, double-click the item's object icon.

2	In the Property Palette, under the Physical node, set the item's Canvas and Tab Page properties to the correct values to make sure the item appears on the desired tab canvas and tab page.

Note:  When you add an item to a tab page, be sure the entire item (and any associated boilerplate graphics) is completely within the tab page region.


Moving an item to another tab page

To move an item to another tab page:

1	In the Object Navigator, click the item's object icon, and choose Tools [image] Layout Editor.

2	In the Layout Editor, click the item(s) and click the Cut or Copy buttons in the toolbar.

Form Builder cuts or copies the item to the clipboard.

3	Click the tab of the tab page on which you wish to paste the item(s), then click the tab page itself once Form Builder displays it.

4	Click the Paste tool in the toolbar.

Form Builder pastes the item to the selected tab page, in the same X,Y position where the item was located on its previous tab page.

Note:  You also can move an item to another tab page by changing the item's Tab Page property in the Property Palette.


Reordering tab pages

To reorder tab pages:

1	In the Object Navigator, under the Canvases node, click the Tab Pages node of the tab canvas.

2	Click-drag the object icon of a tab page, and reposition it in the hierarchy to change its place in the order

Note:  The ordering of tab pages in the Object Navigator determines the left-to-right (or top-to-bottom) order of the tabs at runtime.  The highest tab in the Object Navigator will be displayed either at the top or far left of the tab stack at runtime, depending on the orientation of the tabs.


Deleting a tab page

To delete a tab page:

1	In the Object Navigator, under the Canvases node, click the Tab Pages node of the tab canvas.

2	Click the tab page's object icon, and click the Delete button in the toolbar.

Form Builder displays a confirmation alert.

3	Click Yes to delete the tab page.

Form Builder deletes the tab page.

Note:  Deleting the last page of a tab canvas does not delete the canvas itself.


Displaying a tab canvas

To display a tab canvas in the Layout Editor:

1	In the Object Navigator, double-click the tab canvas' object icon,

or

Double-click the object icon of a content canvas that is assigned to the same window as the tab canvas, then choose View [image] Stacked Views and select the tab canvas(es) you want to view on the content canvas,

or

Double-click the object icon of a content canvas that is assigned to the same window as the tab canvas, then select the tab canvas from the Canvas combination box at the top of the Layout Editor.


Switching tab pages at design time

To switch the tab pages at design time:

1	Click the labelled tab.  If the tab you wish to view is not visible, click on any visible tab to give it the focus, and use the right- and left-arrow keys to switch between the tab pages.


Resizing a tab canvas

To resize a tab canvas in the Layout Editor:

1	In the Object Navigator, under the Canvases node, double-click the tab canvas' object icon.

The Layout Editor appears.

2	Choose View [image] Show View.

3	Select the tab canvas view.

4	Select a point and click-drag the tab canvas to the desired size.

Note:  Keep in mind that when you resize a tab canvas, Form Builder resizes each of its tab pages automatically.  Objects previously within the borders of a tab page may therefore fall outside the tab page border if you resize the tab canvas.


Moving a tab canvas

To move a tab canvas on the content canvas:

1	In the Object Navigator, under the Canvases node, double-click the content canvas' object icon.

The Layout Editor appears.

2	Choose View [image] Show View.

3	Select the tab canvas view.

4	In the Layout Editor, click and drag the tab canvas view to the desired position on the content canvas.

Note:  By moving the tab canvas, you are changing the Viewport X Position and the Viewport Y Position of its view.


Displaying Canvases

Displaying a stacked canvas' views

Displaying a tab canvas


About toolbar canvases

You can create toolbar canvases, both horizontal and vertical, for any window in a form.  Form Builder displays horizontal toolbar canvases across the top of a window, and vertical toolbar canvases on the left edge of a window.  (The Form Builder has several toolbars:  for example, the Object Navigator window has both horizontal and vertical toolbars; the Property Palette has a horizontal toolbar only.)

When you create a toolbar canvas, you assign it to a window by setting the canvas Window property, and then register it with the window by setting the window's Vertical Toolbar Canvas or Horizontal Toolbar Canvas properties as appropriate.

You can change the appearance of a toolbar at runtime by dynamically showing and hiding different items on the toolbar.  You also can create more than one toolbar for the same window, and display them in response to navigation events and programmatic control, much like stacked canvases assigned to the same window.

MDI Window Toolbar Canvas  On Microsoft Windows, you can create toolbars for the MDI application window as well as for any document windows in the form.  The MDI application window is created and managed by the window manager, and does not appear in the list of window objects in a form module.

Note:  In multiple-form applications, each form can potentially have its own MDI toolbar.  As the end user navigates among forms, the MDI window is updated to display the MDI toolbar defined in the current form.  If an MDI toolbar is not defined in the current form, the MDI window is displayed without a toolbar whenever that form has focus.


Creating a toolbar canvas

  Related Topics

To create a toolbar canvas:

1	In the Object Navigator, click the Canvases node, and Click the Create button [image] in the toolbar.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the General and Physical nodes, set properties as follows:

Canvas Type—Horizontal Toolbar or Vertical Toolbar.

Window—the name of the window in which you will display the toolbar canvas.

Width/Height—the dimensions of the toolbar canvas.  A toolbar canvas generally is as wide (or tall) as the window to which it is assigned, and as deep (or wide) enough to display a single row (or column) of items.  (Note that Form Builder accepts any dimensions you specify, even if the resulting toolbar completely obscures the window's content canvas.)

4	In the Object Navigator, under the Windows node, click the window to which you assigned the toolbar canvas in Step 3.

5	Double-click the window's object icon to display the Property Palette.

6	In the Property Palette, under the Functional node, set the Horizontal Toolbar Canvas and/or Vertical Toolbar Canvas properties to the name of the toolbar you created in Step 1.

7	Add items and boilerplate graphics to the toolbar canvas as you would for any other canvas.

Note: Use of navigable and mouse-navigable items in a toolbar canvas is not supported.


Creating a toolbar canvas for the MDI window

  Related Topics

To create an MDI toolbar canvas:

1	In the Object Navigator, click the Canvases node, and Click the Create button [image] in the toolbar.

2	Choose Tools [image] Property Palette.

3	In the Property Palette, under the General node, set the Canvas Type property to Horizontal Toolbar or Vertical Toolbar.

4	In the Object Navigator, under the Forms node, double-click the current form module's object icon to display the Property Palette.

5	In the Property Palette, under the Physical node, set the Form Horizontal Toolbar Canvas and/or Form Vertical Toolbar Canvas properties to the name of the toolbar you created in Step 1.

Note:  When you create a canvas toolbar to display on the MDI window, Form Builder will ignore the window assignment for that canvas (specified by its Window property setting) at runtime, and will automatically map the toolbar canvas to the MDI window instead.

6	Add items and boilerplate to the new toolbar canvas as you would to a content or stacked canvas.

Note: Use of navigable and mouse-navigable items in an MDI toolbar canvas is not supported.


Creating multiple toolbar canvases for the same window

  Related Topics

It is possible to create two or more toolbar canvases of the same type (horizontal or vertical) and assign them to the same form window by setting the canvas Window property.

When two or more toolbars are assigned to the same form window, Form Builder will attempt to display the primary toolbar canvas on the window at runtime.  You specify the primary toolbar canvas for a window by setting the window's Horizontal Toolbar Canvas or Vertical Toolbar Canvas property.

However, Form Builder may display a toolbar canvas other than the primary toolbar canvas if navigation occurs to an item on another toolbar, or if the application programmatically shows or raises a different toolbar canvas by executing SHOW_VIEW or SET_VIEW_PROPERTY.

Defining MDI toolbars also can result in a situation where more than one toolbar canvas is being mapped to the same form window.  For example, you might create a form with two toolbar canvases of the same type (horizontal or vertical) that are assigned to the same form window, one of which is designated as the MDI toolbar (by setting the form module Form Horizontal/Vertical Toolbar Canvas properties).  On Microsoft Windows, the MDI toolbar is always mapped to the MDI window, and is not displayed on the window to which it is assigned (as indicated by its Window property setting).  However, on non-Windows platforms that support toolbars, such as Motif, the MDI toolbar is mapped to the window to which it is assigned, and becomes one of that window's potential toolbar canvases.  In this case, Form Builder will attempt to display the window with the toolbar that you designated as the primary toolbar, but may display a different toolbar in response to navigation or programmatic events.


About stacking order

When you work with canvases, you must define each canvas' position in the stacking order, with respect to other canvases assigned to the same window.  The stacking order determines which canvases are displayed in front of (or "on top of") other canvases in the same window.  The stacking order of canvases can change at runtime in response to navigation and programmatic events.

Stacking order is important, particularly when you have multiple content and stacked canvases assigned to the same window.  You always should position a stacked canvas in front of any content canvas(es) assigned to the same window;  if not, the content canvas(es) will completely obscure the stacked canvas(es) at runtime.

Initial Stacking Order  The initial stacking order of canvases is determined by the order they are listed under the Canvases node in the Object Navigator:  the first canvas listed under the Canvases node is displayed behind all other canvases assigned to the same window.  The last canvas in the list is displayed in front of all other canvases.

Changing the Stacking Order  To change the stacking order, drag canvases in the Object Navigator to position them in the desired sequence. To re-sequence canvases this way, make sure the Object Navigator is in Ownership View (the default).


About content canvases in the stacking order

  Related Topics

When you assign multiple content canvases and at least one stacked canvas to the same window, be aware of how Form Builder manages content canvases in the stacking order.  Since Form Builder can display only one content canvas at a time in a single window, it treats all content canvases assigned to the same window as if each one had the same position in the stacking order, relative to the stacked canvases assigned to that window.

Consider a window with four canvases:  CNT_A and CNT_C are content canvases;  STK_B is a stacked canvas;  TAB_D is a tab canvas.

At runtime, Form Builder displays one content canvas at a time in the window.  If, at form startup, the application navigates to an item on CNT_A, it becomes the current content canvas displayed in the window.  If the end user then navigates to an item on CNT_C, it replaces CNT_A, but at the same position in the stacking order, rather than at its design-time position as specified in the Object Navigator.

This functionality allows the current content canvas to be replaced without hiding stacked canvases currently displayed in the same window.  When CNT_C replaces CNT_A, the stacked and tab canvases, which are positioned above CNT_A at design time, remain visible.

When you use this technique, make sure that the stacked and tab canvases are sequenced in front of (above) the first content canvas that will be displayed in the window.


How stacking order changes at runtime

At runtime, the stacking order you established at design time changes as canvases are raised in response to navigation and programmatic control.

When an end user or the application navigates to an item on a canvas that is hidden behind another canvas, Form Builder automatically raises the target canvas to the front of the window, thus changing the current stacking order.  (Therefore, if you design your form such that stacked or tab canvases always are invoked in response to navigation, the design-time stacking order is unimportant.)

Similarly, if you execute the SHOW_VIEW or SET_VIEW_PROPERTY built-in procedures to display a canvas programmatically, Form Builder displays the indicated canvas in front of all other canvases displayed in that same window.


Displaying and closing a window in response to navigation

  Related Topics

Displaying a Window in Response to Navigation  At runtime, Form Builder always keeps the item that currently has focus visible to the end user.  To make the target item visible when a navigation event occurs, Form Builder will invoke, raise or show windows that are currently hidden or are currently behind other windows.

When a navigation event occurs, Form Builder first determines which canvas the target item is on, and then displays the window to which that canvas is assigned.  For example, at form startup, Form Builder identifies the item that is the first navigable item in the first navigable block in the form, and then displays the canvas and window to which that item is assigned.

You can take advantage of this behavior by using navigation events to invoke windows, without having to write code to display them explicitly.

Examples of navigation events include Next Item, Previous Item, Next Block, and Previous Block.  The end user can issue these commands by pressing keys or selecting commands on the Default menu.  You can also initiate navigation programmatically by calling the appropriate built-ins, including GO_ITEM and GO_BLOCK.

Closing a Window in Response to Navigation  When an end user or the application navigates out of a modeless window, the window's Hide on Exit property determines whether the window remains displayed or is closed automatically.

If Hide on Exit is set to Yes, Form Builder closes the window automatically when the end user or the application navigates to an item in another window.  If Hide on Exit is set to No (the default), Form Builder does not close the window when navigation to an item in another window occurs.

Note that the Hide on Exit property is ignored for modal windows (windows with the Modal property set to Yes).


Displaying and closing a window programmatically

 Examples	     Related Topics

Displaying a Window  To display a window that does not contain navigable items, you must display it programmatically.  For such windows, you also must set the Primary Canvas property to specify the content canvas that you want displayed in the window.

To display a window at runtime, use either the SHOW_WINDOW or SET_WINDOW_PROPERTY built-in procedures.  (When you use SHOW_WINDOW, you have the option to specify X,Y display coordinates.  If you do not, Form Builder uses the window's current display coordinates.)

When you display a window programmatically, Form Builder displays the following canvases in the window:

•	the window's current content canvas

•	any stacked canvases  assigned to the window that have the Visible property set to Yes

Note:  If you programmatically display a window that is already displayed, but is layered behind other windows, Form Builder raises the window in front of the other windows.

Closing a Window  To close a window, you can use either the HIDE_WINDOW or SET_WINDOW_PROPERTY built-in procedures.

The Current Item  When you display and hide windows programmatically, keep in mind that Form Builder always keeps the item that currently has focus visible to the end user.  If you attempt to programmatically close the window that contains the current item, Form Builder ignores the call.  If you display a window that obscures the current item, Form Builder executes the call, but then immediately raises windows or canvases as necessary to keep the current item visible.


Displaying and closing a window programmatically examples

/*

** Example 1: These 2 procedure calls display a window named
** MY_WIN, with equivalent results:

   SHOW_WINDOW('my_win');
   SET_WINDOW_PROPERTY('my_win', visible, property_true);

** Example 2: This procedure call displays the same window at
** screen coordinates 5 and 10:

   SHOW_WINDOW('my_win', 5, 10);

** Example 3: The SET_WINDOW_PROPERTY built-in sets only one
** window property at a time; you must call it twice to achieve
** the same result as the previous example:

   SET_WINDOW_PROPERTY('my_win', visible, property_true);
   SET_WINDOW_PROPERTY('my_win', window_position, 5, 10);

** Example 4: These 2 procedure calls close a window named MY_WIN,
** with equivalent results:

   HIDE_WINDOW('my_win');
   SET_WINDOW_PROPERTY('my_win', visible, property_false);

*/


Moving and resizing a window programmatically

 Examples	     Related Topics

Moving a Window  To move a window, use the built-in procedures MOVE_WINDOW or SET_WINDOW_PROPERTY.

Resizing a Window  To resize a window, use the built-in procedures RESIZE_WINDOW or SET_WINDOW_PROPERTY.

Minimizing/Maximizing a Window  To programmatically minimize (iconify) or maximize (enlarge to full-screen) a window, use the SET_WINDOW_PROPERTY built-in to set the Window State property to Minimize or Maximize.

Manipulating the MDI Application Window  On Microsoft Windows, you can manipulate the MDI application window programmatically.  To do so, refer to the window name as FORMS_MDI_WINDOW.  You can programmatically set selected MDI windows properties.  For details, refer to the online help for the SET_WINDOW_PROPERTY built-in.

Manipulating Windows at Application Startup  To set the size, position, and display state of a window at application start-up (i.e., before the end user sees the form), call the appropriate built-ins from a When-New-Form-Instance trigger.  If you are developing an application to run on different operating systems and display devices, you can use the GET_APPLICATION_PROPERTY built-in to examine the following properties, and then size your windows accordingly:

•	DISPLAY_HEIGHT

•	DISPLAY_WIDTH

•	OPERATING_SYSTEM

•	USER_INTERFACE

Note:  The built-in subprograms that change the size and position of objects require arguments for X,Y display coordinates and width/height dimensions.  At runtime, Form Builder interprets these arguments in the units specified by the form module Coordinate System property:  either in character cells, centimeters, inches, pixels, or points.


Moving and resizing a window programmatically examples

/*

** Example 1: These 2 procedure calls move the window MY_WIN to
** X,Y coordinates 6 and 8:

   MOVE_WINDOW('my_win', 6, 8);
   SET_WINDOW_PROPERTY('my_win', position, 6, 8);

** Example 2: These 2 procedure calls resize MY_WIN to a width
** of 80 and a height of 20:

   RESIZE_WINDOW('my_win', 80, 20);
   SET_WINDOW_PROPERTY('my_win', window_size, 80, 20);

** Example 3: This procedure call minimizes the document window
** MY_WIN:

   SET_WINDOW_PROPERTY('my_win', window_state, minimize);

** Example 4: This procedure call uses the Form Builder constant
** FORMS_MDI_WINDOW to maximize the MDI window (applies only to
** Microsoft Windows):

   SET_WINDOW_PROPERTY(forms_mdi_window, window_state, maximize);

*/


Scrolling a window programmatically

 Examples	     Related Topics

When you scroll a window programmatically, you actually change the position of the view on the window's canvas (i.e., changing the Viewport X Position on Canvas and Viewport Y Position on Canvas property settings).

To scroll a window programmatically, use one of two built-in procedures:

•	SCROLL_VIEW scrolls the window to X,Y coordinates you specify.

•	SET_VIEW_PROPERTY allows to set either the X or Y coordinates of the view by setting the Viewport X Position on Canvas or Viewport Y Position on Canvas properties.  (Note that to set both X and Y coordinates of the view, you must call this built-in twice.)

Dynamic Scrolling  When end users or the application navigate among items, Form Builder always keeps the target item visible to the end user.  If necessary, Form Builder will automatically scroll a canvas to bring the target item within the view.  For example, when an end user presses [Next Item] (Tab) to move to an item that is on the same canvas but currently outside the window, Form Builder dynamically scrolls the canvas to make the target item visible.

The only exception to this rule is if the end user or the application scrolls the window explicitly, rather than in response to navigation.  In this case, Form Builder does allow the item that currently has input focus to be scrolled out of the view.  However, the next navigational event will again cause the target item to be scrolled within the view.


Scrolling a window programmatically examples

/*

** Example 1: This procedure call scrolls a window's content
** canvas horizontally to X,Y coordinates 14 and 10:

   SCROLL_VIEW('my_con_view', 14, 10);

** Example 2: These 2 procedure calls also reposition the content
** canvas' view to X,Y coordinates 14 and 10:

   SET_VIEW_PROPERTY('my_con_view', x_pos_on_canvas, 14);
   SET_VIEW_PROPERTY('my_con_view', y_pos_on_canvas, 10);

*/


Using triggers to respond to window events at runtime

You can use the following triggers to respond to window events:

•	When-Window-Activated

•	When-Window-Closed

•	When-Window-Deactivated

•	When-Window-Resized

When working with these triggers, you can examine the built-in system variable SYSTEM.EVENT_WINDOW to determine the name of the window for which the trigger fired.


Showing and hiding a canvas programmatically

 Examples	     Related Topics

Showing a Canvas  To programmatically display a canvas in the window to which it is assigned, use either the built-in procedures SHOW_VIEW or SET_VIEW_PROPERTY.

Note:  With one exception, when you display a canvas programmatically, Form Builder raises it in front of any other canvases in the same window, regardless of the stacking order you specified at design time, of whether the canvas was already displayed (but hidden behind another canvas) when the built-in was called.  The exception is when you try to programmatically display a canvas that would obscure the current item's canvas;  in this case Form Builder will display the canvas, but behind the current item's canvas.

If you use the SHOW_VIEW or SET_VIEW_PROPERTY built-ins to display a content canvas, it replaces the window's current content canvas.

Hiding a Canvas  To programmatically hide a canvas, use the built-in procedures HIDE_VIEW or SET_VIEW_PROPERTY.


Showing and hiding a canvas programmatically examples

/*

** Example 1: These 2 procedure calls both display a content
** canvas named A_STACK:

   SHOW_VIEW('a_stack');
   SET_VIEW_PROPERTY('a_stack', visible, property_true);

** Example 2: These 2 procedure calls both hide a content canvas
** named A_STACK:

   HIDE_VIEW('a_stack');
   SET_VIEW_PROPERTY('a_stack', visible, property_false);

*/


Working with the Raise on Entry canvas property

  Related Topics

The canvas property Raise on Entry determines how stacking order is affected by navigation (by the end user or the application) to an item on the canvas.  If you set Raise on Entry to:

•	No,  Form Builder raises the canvas to the front of the window only if the target item is hidden behind another canvas in that same window (when the end user or application navigates to an item on that canvas.

•	Yes,  Form Builder raises the canvas to the front of the window whenever the end user or the application navigates to an item on that canvas.  (Be careful about setting Raise on Entry to Yes for a content canvas;  since a content canvas occupies the entire content area of its window, it always will obscure any stacked canvases when Form Builder raises it to the front of the canvas stack.)

Stacked Canvases

Setting the Raise on Entry property for a stacked canvas can be tricky.  To get it right, you may have to consider window interaction, default navigation, stacking order, and programmatic manipulation of windows and canvases.

A stacked canvas with Raise on Entry property set to No can be displayed only through navigation or programmatic control.

Recall that when an end user (or your application) navigates to an item on the stacked canvas, Form Builder displays the canvas in its assigned window.  But a window also can be shown programmatically, or in response to navigation to an item on the window's content canvas.  In these situations, you must set Raise on Entry to Yes so Form Builder will display the stacked canvas when the window is first displayed.

Note that a stacked canvas with its Raise on Entry property set to Yes might still be hidden in the following situations:

•	If the stacked canvas' position in the stacking order places it behind a content canvas or other stacked canvas in the same window.

•	If the window is displayed because of navigation to an item on another of its canvases, Form Builder will hide the stacked canvas if it overlaps the target item.  (Form Builder at first displays the stacked canvas, then immediately raises the target canvas in front of the stacked canvas so that the target item visible.)

•	If the window is displayed because of navigation to an item on another of its canvases, and the target canvas has Raise on Entry set to Yes, Form Builder will raise the target canvas in front of the stacked canvas, even if the stacked canvas does not overlap the target item.


Events that change the current content canvas

  Related Topics

When a content canvas is displayed in a window—in response to navigation or programmatic control—it becomes the window's current content canvas.  Unless it is replaced by another content canvas, it remains the current content canvas for the duration of the runtime session (even if the end user closes or iconifies the window).

When multiple content canvases are assigned to the same window, the current content canvas can be replaced by another content canvas under the following circumstances:

•	the end user or the application navigates to an item on another content canvas assigned to the same window

•	a trigger or user-named subprogram executes the REPLACE_CONTENT_VIEW built-in procedure.

For example, the end user might press [Next Item] (Tab) to navigate to an item on a different content canvas.  Since a window can display only one content canvas at a time, Form Builder replaces the window's current content canvas with the new content canvas that contains the target item.


Replacing the current content canvas programmatically

 Examples	     Related Topics

To replace a window's current content canvas programmatically, use the built-in procedure REPLACE_CONTENT_VIEW.

The canvas specified must be a content canvas, and it must be assigned to the window indicated.  (You cannot replace a window's current content canvas with a canvas assigned to a different window.)

You also can use the SHOW_VIEW and SET_VIEW_PROPERTY built-ins to replace a window's content canvas.  If the window contains stacked canvases, however, there is an important functional difference between these built-ins and the REPLACE_CONTENT_VIEW built-in:

•	SHOW_VIEW and SET_VIEW_PROPERTY display the indicated content canvas in front of any stacked canvases in the window, thereby hiding those stacked canvases.

•	In contrast, REPLACE_CONTENT_VIEW displays the indicated content canvas at the same position in the stacking order as the content canvas it replaces.

Remember that Form Builder always keeps the current item visible to the end user.  If you programmatically replace the content canvas that contains the current item, Form Builder will automatically redisplay the original canvas.


Replacing the current content canvas programmatically examples

/*

** Example 1: This procedure call replaces the WIN_5 window's
** current content canvas with a content canvas named CVS_1:

   REPLACE_CONTENT_VIEW('win_5', 'cvs_1');

*/


Manipulating a stacked canvas programmatically

 Examples

Displaying a Stacked Canvas  To programmatically display a stacked canvas in the window to which it is assigned, you can use the SHOW_VIEW built-in procedure.  (Note that a stacked canvas' Visible property is set to No by default.)

Scrolling a Stacked Canvas  To scroll a stacked canvas so that a different region of the canvas is visible, use the built-in procedure SCROLL_VIEW (which moves the view relative to its canvas).

Moving a Stacked Canvas  To move the stacked canvas to a different location on the underlying content canvas, use the built-in procedure SET_VIEW_PROPERTY (which changes the canvas' Viewport Position property).  Note that this will not change the region of the canvas that is visible in the view.

Increasing the Dimensions of the View  To increase the dimensions of a stacked canvas' view (so that more of the canvas is visible), use the built-in procedure SET_VIEW_PROPERTY.  Note that increasing the  of the view does not change the X,Y coordinates of its upper-left corner on the stacked canvas, nor does it change the position of the view itself relative to the underlying content canvas.


Manipulating a stacked canvas programmatically examples

/* Example 1: These 2 procedure calls both display the stacked

** canvas STACK_IT:
*/
   SHOW_VIEW('stack_it');
   SET_VIEW_PROPERTY('stack_it', visible, property_true);

/* Example 2: This procedure call scrolls the view of the stacked
** canvas STACK_IT to X,Y coordinates 12 and 0:
*/
   SCROLL_VIEW('stack_it', 12, 0);

/* Example 3: This procedure call changes the position of the
** stacked canvas STACK_IT to X,Y coordinates 12 and 20 on the
** underlying content canvas:
*/
   SET_VIEW_PROPERTY('stack_it', display_position, 12, 20);

/* Example 4: This procedure call increases the width of the view,
** thereby making more of the canvas visible:
*/
   SET_VIEW_PROPERTY('stack_it', width, 22);


Manipulating a tab canvas programmatically

 Examples	     Related Topics

Like stacked canvases, use the SHOW_VIEW, HIDE_VIEW, and SET_VIEW_PROPERTY built-ins to show and hide a tab canvas programmatically.

To show or hide a tab page, use the SET_TAB_PAGE_PROPERTY built-in.  To make a tab page the topmost page on a canvas, use the SET_CANVAS_PROPERTY built-in.  To change the tab page on which an item is displayed, use the SET_ITEM_PROPERTY built-in.

Showing/Hiding a Tab Page  To show or hide a tab page, use the built-in procedure SET_TAB_PAGE_PROPERTY to set the tab page property VISIBLE.

Enabling/Disabling a Tab Page  To enable or disable a tab page, use the built-in procedure SET_TAB_PAGE_PROPERTY to set the tab page property ENABLED.  (A disabled tab page is displayed at runtime with its tab label greyed out.)

Setting the Topmost Tab Page  To make a tab page the top-most on its underlying tab canvas, use the built-in procedure SET_CANVAS_PROPERTY to set the canvas property TOPMOST_TAB_PAGE.


Manipulating a tab canvas programmatically examples

/*

** Example 1: This procedure call shows the tab page TAB1 on the
** tab canvas CAN5:
*/
   SET_TAB_PAGE_PROPERTY('can5.tab1', visible, property_true);

/* Example 2: This procedure call disables tab page TAB1, but
** leaves it visible on its underlying tab canvas CAN5:
*/
   SET_TAB_PAGE_PROPERTY('can5.tab1', enabled, property_false);

/* Example 3: This procedure call makes tab page TAB1 the
** top-most page on its underlying tab canvas CAN5:
*/
   SET_CANVAS_PROPERTY('can5', topmost_tab_page, 'tab1');


Manipulating a tab canvas at runtime

  Related Topics

Runtime navigation to and from a tab canvas—and between the canvas' tab pages—is subject to a few rules and restrictions.

Tab Canvas Navigation  At runtime, tab canvases are displayed automatically in response to navigation in the same manner as content and stacked canvases.

SYSTEM.CURRENT_ITEM and SYSTEM.TRIGGER_ITEM can legitimately not have focus, and may even be invisible, when a tab canvas has focus. Clicking on a tab canvas gives it focus but does not change SYSTEM.CURRENT_ITEM.

Tab Page Navigation  There are a number of ways to switch between tab pages at runtime.  The most direct method is to click the labelled tab at the edge of a tab page.  End users also can use the right- and left-arrow keys to switch between tab pages, but only if the labelled tab has focus (i.e., focus is not in an item or the tab canvas).  Switching tab pages in response to navigation is similar to displaying a hidden stacked canvas in response to navigation:  if navigation occurs between an item on tab page TP1 and and item on tab page TP2, Form Builder automatically displays TP2.  If navigation to an item on another tab page fails (due to validation), Form Builder returns focus to the previous item—not to the tab on which the previous item is located.


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.


 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 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.


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.


Query Builder messages

  Related Topics

Click a message range, then page using the browse buttons to find the message you are looking for.

BRW-15000 through BRW-15092

BRW-15093 through BRW-15146

BRW-15147 through BRW-15196

BRW-15197 through BRW-15390

BRW-15391 through BRW-15424

BRW-15430 through BRW-15520

BRW-15521 through BRW-15569

BRW-15570 through BRW-15912

BRW-15913 through BRW-16551

BRW-16552 through BRW-16660


BRW-15000: Internal error in Oracle Query Builder error handler

Cause:	Error handler couldn't be started.

Action:	Contact Oracle Customer Support.


BRW-15001: <message number>

Cause:	The message file could not be found or is incompatible with this version of Query Builder.

Action:	Check the Query Builder directory in Oracle Home for the proper message file.


BRW-15002: Out of memory!

Cause:	Out of memory.

Action:	Save documents and restart Oracle Query Builder.


BRW-15003: Invalid file name: <name>

Cause:	User entered an invalid file name (for example, too many characters).

Action:	Enter a new, valid file name.


BRW-15004: Internal error (<value1>:<value2>)

Cause:	Internal Error Occurred--Oracle Query Builder is in an unreliable state.

Action:	Contact Oracle Customer Support.


BRW-15005: No file name specified

Cause:	User did not enter a filename in the Export Data dialog box.

Action:	Enter a filename.


BRW-15006: Unable to DESCRIBE data table

Cause:	Internal message.

Action:	Contact Oracle Customer Support.


BRW-15007: SQL statement is too complex to display

Cause:	Exceeded the edit buffer size on MSWINDOWS.

Action:	Exclude some columns from the query to reduce the SQL statement size.


BRW-15009: Insufficient privileges to log in through Oracle Query Builder

Cause:	Connect privileges are disabled in the SYSTEM.BROWSER_PROFILE table.

Action:	Contact your DBA.


BRW-15065: Syntax error

Cause:	User typed a formula incorrectly.

Action:	Re-type the expression.


BRW-15066: Expression is too complex

Cause:	Expression is too complex.

Action:	Simplify the expression.


BRW-15068: Invalid function: <name>

Cause:	User entered an invalid function name.

Action:	Specify a valid function.


BRW-15069: Invalid column: <name>

Cause:	User entered an invalid column name.

Action:	Enter a valid column name.


BRW-15070: Invalid table: <name>

Cause:	User entered an invalid table name.

Action:	Enter a valid table name.


BRW-15071: Invalid owner: <name>

Cause:	User entered an invalid user or business area name.

Action:	Enter a valid user or business area name.


BRW-15072: Invalid condition

Cause:	User entered an invalid condition.

Action:	Delete the condition and enter a valid condition.


BRW-15073: Invalid expression

Cause:	User entered an invalid expression (usually blank).

Action:	Enter a valid expression.


BRW-15074: Invalid use of reserved word <name>

Cause:	User used a reserved word as an identifier.

Action:	Identifiers cannot be reserved words. Refer to the help or documentation for details.


BRW-15075: Invalid number of arguments to function <name>

Cause:	User entered too few or too many arguments for the given function.

Action:	Enter the appropriate arguments. Refer to the help or documentation for details.


BRW-15077: Ambiguous name: <name>

Cause:	User entered an ambiguous column name.

Action:	Enter a specific column name. You may have to include qualifiers.


BRW-15078: Redefinition of name: <name>

Cause:	User redefined a column or data table using a name that already exists.

Action:	Define the column or table using a new name.


BRW-15079: No columns selected in query

Cause:	Query was either built or entered with no displayed columns.

Action:	Select columns before re-executing the query.


BRW-15080: No tables specified in query

Cause:	User entered a query without specifying any tables.

Action:	Select tables before re-executing the query.


BRW-15081: START WITH requires CONNECT BY

Cause:	SQL statement contained a START WITH clause without a CONNECT BY clause.

Action:	Specify a CONNECT BY clause if you intend to use START WITH.


BRW-15082: PRIOR requires CONNECT BY

Cause:	SQL statement contained a PRIOR clause without a CONNECT BY clause.

Action:	Specify a CONNECT BY clause if you intend to use PRIOR.


BRW-15083: Bad argument type to function <name>

Cause:	User entered the wrong argument type for the function.

Action:	Enter the correct argument type.


BRW-15084: Unterminated comment
BRW-15084: Unerminated comment

Cause:	Buffer being read in has an unerminated C-type comment in it.

Action:	Edit the file (see that it terminates correctly) and reopen from Query Builder.


BRW-15085: Circular reference detected in defined column

Cause:	Modification of a defined column has led to a circular reference.

Action:	Redefine the column so that it doesn't refer to itself in its own definition.


BRW-15086: Arguments to a correlated subquery function must be columns

Cause:	A complex argument was given, such as avg (sal, deptno*2).

Action:	Specify only valid columns, not expressions, in the subquery.


BRW-15087: Invalid location: <name>

Cause:	User entered an invalid database location for a table.

Action:	Enter a valid database location.


BRW-15088: Ambiguous table: <name>

Cause:	User entered an ambiguous data table name (more than one table uses this name).

Action:	User must further qualify the data table. Refer to the help or documentation for details.


BRW-15089: Only one PRIOR operator allowed on an expression

Cause:	User typed 2 or more PRIOR clauses in an expression.

Action:	Remove one of the PRIOR clauses.


BRW-15090: The name <name> is already in use

Cause:	User entered a name that was already being used.

Action:	Enter a new name.


BRW-15091: Invalid name: <name>

Cause:	User entered an invalid name (with spaces or unprintable chars).

Action:	Enter a new name.


BRW-15092: Bad usage of outer relationship

Cause:	User specified an outer relationship on a non-column element.

Action:	Outer relationships are only valid for columns.


BRW-15093: Invalid number of elements in corresponding record

Cause:	User entered two records with different numbers of elements.

Action:	Re-enter the condition.


BRW-15094: Group function is nested too deeply

Cause:	User entered a double(triple) aggregate condition(expression).

Action:	Simplify aggregate condition/expression.


BRW-15096: Table name conflicts with <name1>, renamed to <name2>

Cause:	When opening a query, a table alias name conflicts with a new column.

Action:	User can rename the alias.


BRW-15097: Name conflicts with <name1>, renamed to <name2>

Cause:	When loading a saved query, an alias name conflicts with a new column.

Action:	Rename the alias.


BRW-15098: Duplicate table <name> in FROM clause

Cause:	Data table appears more than once in FROM clause (without an alias).

Action:	Remove the duplicate data tables in the FROM clause.


BRW-15099: Subquery returns incorrect number of values

Cause:	Subquery returns either too many or too few values.

Action:	Re-enter the condition.


BRW-15100: Correlated expressions are not allowed here

Cause:	User entered a correlated expression outside a condition.

Action:	Re-enter the condition/expression.


BRW-15101: Table alias cannot be reused in the same FROM clause: <name>

Cause:	User tried to use an alias in the same FROM clause it was defined in.

Action:	Remove the reference to the alias.


BRW-15102: Too many elements in record

Cause:	User entered a record with more than 254 elements.

Action:	Reduce the number of elements--split the condition into an OR.


BRW-15103: Unnamed SELECT statement in FROM clause

Cause:	SQL contained a query in the FROM clause without name.

Action:	Add the query name and reparse.


BRW-15110: Invalid number or precision exceeded: <column name>

Cause:	Non-numeric input or the number exceeded this column's precision.

Action:	Re-enter a valid number and precision.


BRW-15111: Invalid date: <value>

Cause:	Couldn't format using the columns format mask or either default mask.

Action:	Re-enter a valid format mask.


BRW-15112: Entry exceeds the size limit for this column: <##>

Cause:	User entered a string longer than the limit for this column.

Action:	Enter a shorter string.


BRW-15113: Not all parameters have been specified

Cause:	User attempted to execute a query without defining all parameters

Action:	Specify parameters or exclude parameterized expressions and retry.


BRW-15114: Parameters can only be constant expressions

Cause:	User attempted to enter a parameter value that depended on a column value.

Action:	Specify a valid parameter, one that does not depend on the value in a column.


BRW-151BRW-15: Bad usage of parameter <name>
BRW-15115: Bad usage of parameter <name>

Cause:	User entered a parameter name for a column or table.

Action:	Specify a valid parameter.


BRW-15116: Invalid parameter name <name>

Cause:	User entered an invalid parameter name.

Action:	Specify a valid parameter name.


BRW-15117: Invalid parameter <name>

Cause:	User entered an invalid parameter.

Action:	Specify valid parameter.


BRW-15128: Parser internal error: <value>

Cause:	Internal error in the parser/scanner.

Action:	Contact Oracle Customer Support.


BRW-15129: Defined column <name> cannot be used in correlated subquery function

Cause:	Use of derived columns (DQ4) in correlated subquery.

Action:	Remove that argument from the correlated subquery.


BRW-15130: Query execution failed

Cause:	Database access error.

Action:	Check database error and rerun query.


BRW-15131: Invalid relational operator

Cause:	User applied an invalid operator to a condition.

Action:	Enter a valid operator.


BRW-15132: FROM clause was not found where expected

Cause:	Encountered no FROM clause or GROUP/HAVING clause before a FROM clause.

Action:	Edit SQL statement.


BRW-15133: FROM clause was found without corresponding SELECT clause

Cause:	Encountered FROM clause before SELECT clause.

Action:	Edit SQL statement.


BRW-15135: Condition cannot be changed

Cause:	User attempted to change the top condition in Schema Editor.

Action:	Perform the operation on the children conditions.


BRW-15136: SQL contains set operators

Cause:	Set operations are not supported.

Action:	Run the query in SQLPlus.


BRW-15137: Unable to generate names for complex expressions

Cause:	Encountered expressions without names when opening a SQL file.

Action:	Define Names for columns in the .sql file.


BRW-15138: CONNECT BY clause existed, and was ignored

Cause:	Connect By is not supported at this (top) level.

Action:	Run the query in SQLPlus, if results of CONNECT BY were desired.


BRW-15139: Cannot ungroup condition

Cause:	Attempt to ungroup top condition.

Action:	This operation is not supported.


BRW-15141: Query table cannot contain parameters

Cause:	Encountered one or more parameters when creating a view.

Action:	Exclude parameters from query or ignore.


BRW-15142: Two or more columns have the same name: <name>

Cause:	Encountered duplicate column names when creating view.

Action:	Use the Define command to rename duplicate columns.


BRW-15143: <name> is already a display column

Cause:	User tried to specify a duplicate display column.

Action:	If duplicate column is desired, define a new name for it and re-display it.


BRW-15144: <name> is already a sort column

Cause:	User tried to specify a duplicate sort column.

Action:	If duplicate column is desired, define a new name for it and re-sort.


BRW-15145: <name> is already a group column

Cause:	User tried to specify a duplicate group column.

Action:	If duplicate column is desired, define a new name for it and re-group.


BRW-15146: Internal error in opening query

Cause:	Internal error in opening query.

Action:	Contact Oracle Customer Support.


BRW-15147: Internal error in saving query

Cause:	Internal error in saving query.

Action:	Contact Oracle Customer Support.


BRW-15148: Relationship must be between compatible data types/size

Cause:	User tried to relate two columns with incompatible data types.

Action:	Relate only compatible datatypes. Refer to the help or documentation for details.


BRW-15150: Cannot define a self-relationship

Cause:	User tried to define a relationship within a data table.

Action:	Alias the data table and then define the relationship.


BRW-15151: User-defined relationship already exists

Cause:	User tried to define a relationship that already exists.

Action:	No action required.


BRW-15152: Illegal column in defined relationship

Cause:	User specified an illegal expression when defining a relationship.

Action:	Retype in a new column.


BRW-15153: Table alias name cannot end with _A<number>

Cause:	Illegal alias name.

Action:	Input a new name that does not end with _A<number>.


BRW-15154: Cannot remove database relationship

Cause:	User tried to remove data dictionary relationship.

Action:	Only user-defined relationships can be deleted.


BRW-15155: The following documents may have been affected:<name>

Cause:	A saved query was being used as a data table in other query documents.

Action:	If you change or delete this query, you will affect these other queries.


BRW-15156: Cannot include table with the same name as the query

Cause:	User attempted to include data table D in query document D.

Action:	Rename the query before including this table.


BRW-15157: Cannot sort, group, or break on LONG columns

Cause:	Trying to sort, group or break on LONG column type.

Action:	Cancel the operation. Oracle does not support this.


BRW-15158: Cannot sort, group, or break on RAW columns

Cause:	Trying to sort, group or break on RAW column type.

Action:	Cancel the operation. Oracle does not support this.


BRW-15159: Cannot display LONG columns from remote databases

Cause:	Trying to include LONG column type from remote database data table.

Action:	Cancel the operation. Oracle does not support this.


BRW-15160: Maximum number <##> of columns exceeded

Cause:	User exceeded maximum number of display/group/sort columns supported.

Action:	Delete some unwanted columns, then re-include what you need.


BRW-15161: Error in opening <column name> display column(s)

Cause:	Unable to open DISPLAY column because database has changed since save.

Action:	This column may have changed or no longer exists in the database.


BRW-15162: Error in opening <column name> sort column(s)

Cause:	Unable to open SORT column because database has changed since save.

Action:	This column may have changed or no longer exist in the database.


BRW-15163: Error in opening <column name> group column(s)

Cause:	Unable to open GROUP column because database has changed since save.

Action:	This column may have changed or no longer exist in the database.


BRW-15164: Error in opening <column name> break column(s)

Cause:	Unable to open BREAK column because database has changed since save.

Action:	This column may have changed or no longer exist in the database.


BRW-15165: Maximum number <##> of break columns exceeded

Cause:	User exceeded the maximum number of break columns supported.

Action:	Delete some unwanted break columns, then re-include what you need.


BRW-15166: Error in opening <value> condition(s)

Cause:	Unable to open conditions because database has changed since save.

Action:	Tables or columns used in this condition may no longer exist in the database.


BRW-15167: Alias must be <##> bytes or less: <name>

Cause:	Alias name too long.

Action:	Try typing in an alias less than or equal to 30 bytes long.


BRW-15168: Cannot group on aggregate expression

Cause:	Tried to group on an aggregate expression.

Action:	Group on another expression.


BRW-15169: <name> has already been included as a break column

Cause:	User tried to specify a duplicate break column.

Action:	If duplicate column is desired, define a new name for it and re-break.


BRW-15170: Invalid Constraint for table <name>

Cause:	User entered an invalid constraint for the selected table.

Action:	Reenter constraint.


BRW-15171: Invalid Constraint for table column <name>

Cause:	User entered an invalid constraint for the selected column.

Action:	Reenter constraint.


BRW-15172: Subqueries are not allowed in Constraints

Cause:	User entered an invalid constraint.

Action:	Reenter constraint.


BRW-15173: Aggregate conditions are not allowed in Constraints

Cause:	User entered an invalid constraint.

Action:	Reenter constraint.


BRW-15174: Constraints can only be on one table

Cause:	User entered an invalid constraint.

Action:	Reenter constraint.


BRW-15175: Table not loaded because all columns are hidden

Cause:	All columns are hidden. At least one column needs to be displayed.

Action:	Use the Query Builder Administrator Utility to display hidden columns.


BRW-15188: Query returns 1 row

Cause:	Status message for 1-row Query Count.

Action:	No action required.


BRW-15189: Query returns <##> rows

Cause:	Status message for n-row Query Count.

Action:	No action required.


BRW-15190: Unable to count without executing; Query returns <= <##> row(s)

Cause:	Status message for n-row Query Count Distinct.

Action:	No action required.


BRW-15192: Illegal format <name1> for column '<name2>'

Cause:	User typed an unrecognizable format for a display column.

Action:	Try another format.


BRW-15193: Illegal format

Cause:	User typed an unrecognizable format for a display column

Action:	Try another format.


BRW-15195: Incompatible column type in relationship: <name>

Cause:	Trying to create illegal relationship.

Action:	Column types are incompatible. Refer to the help or documentation for details.


BRW-15196: Error in opening <name> table(s)

Cause:	Unable to open data tables because database was modified or object doesn't exist.

Action:	Check your connect string (or contact your DBA).


BRW-15197: Error in restoring position for <name> column(s)

Cause:	Unable to reposition column because database was modified or object doesn't exist.

Action:	Check your connect string (or contact your DBA).


BRW-15198: Error in restoring join: <value>

Cause:	Unable to restore link during open because database was modified or object doesn't exist.

Action:	Check your connect string (or contact your DBA).


BRW-15199: Error in restoring inclusion state for join: <value>

Cause:	Unable to set the inclusion state during open because database was modified or object doesn't exist.

Action:	Check your connect string (or contact your DBA).


BRW-15200: Error in restoring outer join state for join: <value>

Cause:	Unable to set the outer join during open because database was modified or object doesn't exist.

Action:	Check your connect string (or contact your DBA).


BRW-15258: Invalid document name: <name>

Cause:	User entered an invalid document name.

Action:	Enter a valid document name.


BRW-15259: Document exceeds 64K size limit

Cause:	User attempted to save/open a document larger than 64K.

Action:	Reduce size of document.


BRW-15260: Document <name> does not exist

Cause:	User specified a nonexistent document.

Action:	Specify another document.


BRW-15261: Document <name> already exists

Cause:	User tried to save under the name of an existing document.

Action:	Specify another document name or delete the existing document.


BRW-15262: Multiple documents named <name>

Cause:	Multiple documents with same name exist.

Action:	Delete all but one.


BRW-15263: Database object <name> already exists

Cause:	User tried to save under the name of an existing object.

Action:	Specify another document name.


BRW-15264: Table <name> does not exist

Cause:	View corresponding to a saved document has been removed.

Action:	Re-save the document (it no longer exists as a query view).


BRW-15265: Table <name> has been removed or modified

Cause:	Data Table view corresponding to a saved document has been modified.

Action:	Re-save the document.


BRW-15266: File <name> does not exist

Cause:	User specified a nonexistent file.

Action:	Specify another file.


BRW-15267: File <name> already exists

Cause:	User tried to save under the name of an existing file.

Action:	Specify another file name.


BRW-15268: Unable to open file <name>

Cause:	I/O core was unable to open a file.

Action:	Specify another file.


BRW-15269: Unable to lock file <name>

Cause:	I/O core was unable to lock a file.

Action:	Specify another file.


BRW-15270: Error reading file <name>

Cause:	Operating system error or file was not of the correct format.

Action:	Specify another file.


BRW-15271: Error writing file <name>

Cause:	Operating system error or I/O core error.

Action:	Retry operation.


BRW-15272: Obsolete Oracle Query Builder document <name>

Cause:	User attempted to open an old unsupported document.

Action:	Specify another document.


BRW-15273: File <name> is not a Oracle Query Builder file

Cause:	User attempted to open a non-Query Builder file.

Action:	Specify another file to open.


BRW-15274: File <name> is not a valid SQL file

Cause:	User attempted to import an invalid SQL file.

Action:	Specify another file to import.


BRW-15275: No data to export or print

Cause:	User attempted to export or print a query (or region) with no data.

Action:	Specify another region; execute query; change query.


BRW-15277: Unable to overwrite current table <name>

Cause:	Error in trying to delete/rename old data table in save.

Action:	Fix problem with data table and re-save.


BRW-15278: Document saved, but view <name> could not be created

Cause:	The query is not a valid view. It has been saved, but not as a database view.

Action:	Redefine query as a valid view, or ignore (query will be saved, but not as a view).


BRW-15279: '<name>' is not a recognized SQL literal

Cause:	User attempted to import a non-SQLPlus file.

Action:	Specify another file to import.


BRW-15320: Internal I/O core error (<value>, line <##>)

Cause:	Internal State is invalid.

Action:	Contact Oracle Customer Support.


BRW-15321: Resource not found (<name>).

Cause:	Resource names do not match Query Builder code (or file is corrupted).

Action:	Get a correct version of the Query Builder resource file.


BRW-15322: Resource file not found.

Cause:	directory structure incorrect, or file is missing for some reason.

Action:	Locate the resource file (check NLS_LANG file name).


BRW-15323: Query already open in current application (<name>)

Cause:	User attempted to open multiple queries with the same name.

Action:	Specify another file.


BRW-15324: Unable to start up windowing system

Cause:	Incorrect/missing environment variables (e.g. DISPLAY, APIPATH).

Action:	All required environment variables must be set correctly.


BRW-15342: Unable to find snapshot information

Cause:	This database does not support snapshots (or database error).

Action:	Check that you have a snapshot dictionary table.


BRW-15387: Login failed

Cause:	Database or SQLNet error occurred.

Action:	Check the login information and try again.


BRW-15388: Unable to load database relationships

Cause:	Schema internal error in loading database relationships.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15389: Unable to load list of accessible owners

Cause:	Schema internal error in loading list of accessible owners.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15390: Unable to load list of accessible tables

Cause:	Schema internal error in loading list of data tables.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15391: Unable to load table

Cause:	Schema internal error in loading data table.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15392: Unable to load table

Cause:	Schema internal error in loading table.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15393: Unable to load synonym

Cause:	Schema internal error in loading synonym.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15394: Unable to load query

Cause:	Schema internal error in loading query.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15395: Unable to load table column information

Cause:	Schema internal error in loading column information.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15396: Unable to load synonym column information

Cause:	Schema internal error in loading synonym column information.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15397: Unable to load constraints

Cause:	Schema internal error in loading constraints.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15398: Unable to find primary key information

Cause:	Schema internal error in finding primary keys.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15399: Unable to find foreign key information

Cause:	Schema internal error in finding foreign keys.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15400: Unable to load table and column comments

Cause:	Schema internal error in getting comments.

Action:	Contact Oracle Customer Support if this is not expected.


BRW-15401: Error in loading database link <name>

Cause:	Schema internal error in loading database link.

Action:	Refer to accompanying error messages for more information.


BRW-15402: Error in loading owner <name>

Cause:	Schema internal error in loading database link.

Action:	Refer to accompanying error messages for more information.


BRW-15403: Error in loading table <name>

Cause:	Schema internal error in loading data table.

Action:	Refer to accompanying error messages for more information.


BRW-15404: Error in loading primary key constraint for <name> (<value>)

Cause:	Schema internal error in loading primary constraint.

Action:	Refer to accompanying error messages for more information.


BRW-15405: Error in loading foreign key constraint <name>

Cause:	Schema internal error in loading foreign constraint.

Action:	Refer to accompanying error messages for more information.


BRW-15406: Error in loading synonym <name>

Cause:	Schema internal error in loading primary constraint.

Action:	Refer to accompanying error messages for more information.


BRW-15407: Table referred to by synonym <name> no longer exists

Cause:	User tried to create a synonym for a nonexistent data table.

Action:	Recreate the synonym.


BRW-15408: Error in loading column information for <name>

Cause:	Oracle error or the data table has been removed.

Action:	Recreate the data table.


BRW-15409: Error in loading constraint information for <name> (<value>)

Cause:	Oracle error.

Action:	Try it again.


BRW-15410: Table that foreign key <name> (<value>) refers to is inaccessible

Cause:	The table that the foreign key refers to is inaccessible.

Action:	Grant the table to the current user.


BRW-15411: Logout failed

Cause:	Internal error in logging out.

Action:	Exit or close the document.


BRW-15412: Table of query <name> was modified. Query loaded as view.

Cause:	The view that the query depends on has been modified after the last save.

Action:	Open the query and save it again to use it as a data table.


BRW-15413: Table of query <name> was removed. Query will not be loaded.

Cause:	The view that the query depends on has been removed.

Action:	Open the query, and save it again to use it as a data table.


BRW-15414: Table <name> no longer exists

Cause:	This data table no longer exists in the database.

Action:	Contact system administrator if you need this table.


BRW-154BRW-15: Maximum number (254) of table columns exceeded

Cause:	User tried to load a data table that has more than 254 columns.

Action:	Contact system administrator.


BRW-15416: Maximum number (8192) of tables per user exceeded

Cause:	User owns too many data tables.

Action:	Contact system administrator.


BRW-15417: Maximum number (1024) of owners and databases exceeded

Cause:	User tried to load too many user, owner, and database links.

Action:	Contact system administrator.


BRW-15418: Unable to find database link information

Cause:	This database does not support database link, or database error.

Action:	Try again later if this is unexpected.


BRW-15419: Unable to find synonym information

Cause:	This database does not support synonyms, or database error.

Action:	Try again later if this is unexpected.


BRW-15420: Unable to find constraint information

Cause:	This database does not support constraints, or database error.

Action:	Try again later if this is unexpected.


BRW-15421: Unable to find table comment table

Cause:	This database does not support comments on table, or database error.

Action:	Try again later if this is unexpected.


BRW-15422: Unable to find table Column comments table

Cause:	This database does not support comments on column, or database error.

Action:	Try again later if this is unexpected.


BRW-15423: Synonym to SEQUENCE is not currently supported

Cause:	User tried to load a synonym that refers to a sequence.

Action:	This action is not supported.


BRW-15424: Maximum number of login attempts (3) exceeded

Cause:	User tried to login too many times.

Action:	Contact system administrator for correct username, password, and/or connect string.


BRW-15430: Index information not loaded

Cause:	Cannot find index table.

Action:	This is a non-Oracle database; try an ODBC driver.


BRW-15434: Maximum columns in table is <##>

Cause:	User tried to create more than the maximum number of allowed columns in a table.

Action:	Create fewer columns.


BRW-15435: DBA privilege is needed to perform this operation

Cause:	Need DBA privileges.

Action:	Ask your system administrator to grant you DBA privilege.


BRW-15447: Cannot remove Query. Use File Delete... from Query window

Cause:	User tried to remove a query.

Action:	This is not legal from the Schema Editor. Use the Query window instead.


BRW-15448: Cannot copy Query. Use File Save As... from Query window

Cause:	User tried to copy a query.

Action:	This is not legal from the Schema Editor. Use the Query window instead.


BRW-15449: Cannot copy with data from table with only LONG columns

Cause:	User tried to copy a table with a LONG column.

Action:	Database doesn't support this.


BRW-15450: Operation not allowed on removed table

Cause:	User tried to do something to a removed data table.

Action:	Undo the remove first.


BRW-15451: Operation not allowed on removed column

Cause:	User tried to do something to a removed column.

Action:	Undo the remove first.


BRW-15452: Cannot rename another owner's table

Cause:	User tried to set the name of a granted data table.

Action:	This is not allowed. Ask the owner to do it for you.


BRW-15466: Table name too long (Max <##> bytes)

Cause:	Data Table name to long.

Action:	Shorten the name and try again.


BRW-15467: Name already in use. Please choose another name.

Cause:	Name already in use.

Action:	Choose another name.


BRW-15468: Column name too long (Max <##> bytes)

Cause:	Column name too long.

Action:	Shorten the name and try again.


BRW-15493: Operation currently not supported

Cause:	Internal error.

Action:	Contact Oracle Customer Support.


BRW-15494: Error in loading SQL text of views

Cause:	Internal error.

Action:	Contact Oracle Customer Support.


BRW-15495: Error in loading SQL text for view <name>

Cause:	Internal error.

Action:	Contact Oracle Customer Support.


BRW-15496: Scale must be between <##> and <##>

Cause:	Illegal value for scale.

Action:	Input legal value for scale.


BRW-15498: Cannot modify a query

Cause:	It is not legal to modify a query.

Action:	Open the query and modify it as a Query Builder document.


BRW-15499: Cannot set column attributes of table duplicated with data

Cause:	User tried to set the column type of a table duplicated with data.

Action:	First commit the table then try again.


BRW-15501: No more application virtual memory

Cause:	No more disk space or system memory for Virtual Memory Manager.

Action:	Close a document or make some room on your disk.


BRW-15502: Can only have <##> rows per document

Cause:	Exceeded self-imposed, compile-time row maximum.

Action:	Consider adding conditions to the query.


BRW-15504: Unable to determine database character set

Cause:	There was a problem with SELECT USERENV('LANGUAGE') FROM DUAL.

Action:	Non-Oracle database--not supported.


BRW-15505: Unable to open virtual memory file

Cause:	No write permission or file system full.

Action:	Change permission on directory or delete some files.


BRW-15506: Unable to close virtual memory file

Cause:	Operating system error.

Action:	Ask system administrator for assistance.


BRW-15507: Unable to read from virtual memory file

Cause:	Virtual memory file does not exist.

Action:	Make sure the virtual memory file is opened.


BRW-15508: Unable to write to virtual memory file

Cause:	File system is full, or virtual memory file was not opened.

Action:	Delete some files. Make sure virtual memory file is opened.


BRW-15509: Unable to create virtual memory manager

Cause:	Internal error, or out of memory.

Action:	Ask system administrator for assistance.


BRW-15511: Maximum virtual memory size exceeded

Cause:	User input is too big for virtual memory size.

Action:	Try again.


BRW-15513: Null value in command '<name>'

Cause:	User entered <command>= on the command line with no option selected.

Action:	Add a value for <command>.


BRW-15514: Null command in command line

Cause:	User entered =<value> at command line but didn't specify a command.

Action:	Add the command.


BRW-155BRW-15: Unrecognized command '<name>' in command line

Cause:	User entered an illegal command at command line.

Action:	Change command.


BRW-15516: Command '<name>' specified twice in command line

Cause:	User entered a command twice at command line.

Action:	Remove one.


BRW-15517: Incompatible commands '<name1>' and '<name2>' specified

Cause:	User entered 2 incompatible commands at command line.

Action:	Remove one.


BRW-15518: Invalid option '<name1>' in command '<name2>'

Cause:	User entered an illegal option to a command at command line.

Action:	Change option.


BRW-15519: Multiple login specifications in command line

Cause:	User entered 2 login specifications at command line.

Action:	Remove one.


BRW-15520: Invalid document name '<name>' in command line

Cause:	User entered an illegal document name at command line.

Action:	Change document name.


BRW-15521: '<name>' command specified without a document

Cause:	User entered a command without specifying a document at command line.

Action:	Add missing document.


BRW-15522: '<name1>' command specified without '<name2>'

Cause:	User entered a command without another required command.

Action:	Add missing command.


BRW-15523: Mismatched parentheses in '<name>' command

Cause:	User entered mismatched parentheses in the command line.

Action:	Correct mismatched parentheses.


BRW-15530: Cannot edit a deleted row

Cause:	User tried to edit a row which is marked for deletion.

Action:	Undelete the row first.


BRW-15531: Row has been deleted from the database

Cause:	Another user deleted this row since you last ran the query.

Action:	Contact Oracle Customer Support. This should never happen.


BRW-15532: Row has been modified by another user. Requery.

Cause:	Another user updated this row since you last ran the query.

Action:	Try again.


BRW-15533: Row is currently locked by another user.

Cause:	Someone else is editing this row.

Action:	Try again later.


BRW-15539: Error in inserting <##> row(s)

Cause:	One or more rows in input file failed on insert.

Action:	Modify input file or ignore.


BRW-15540: Operation not allowed on data of this type

Cause:	User tried to edit a cell with data of an uneditable type.

Action:	Unknown.


BRW-15541: Too many edited rows. Please select Commit

Cause:	Too many pending INSERTS, UPDATES or DELETES in a document.

Action:	Select Commit or Revert.


BRW-15545: Error in reading QXF file. Parsing halted.

Cause:	Syntax error in reading QXF file.

Action:	Fix QXF file.


BRW-15546: Parse Error: Line <##>

Cause:	Incorrect syntax at that particular line.

Action:	Debug that line.


BRW-15547: Operator unspecified in relationship block.

Cause:	Operator unspecified in relationship block in QXF File.

Action:	Specify an operator field within the block.


BRW-15548: Error: Argument missing in <name> of relationship block.

Cause:	No argument in a column field in a relationship block.

Action:	Specify the column name in that field.


BRW-15549: CONDITION_TEXT missing within condition block.

Cause:	No argument in the CONDITION_TEXT field within condition block.

Action:	Specify the CONDITION_TEXT field.


BRW-15550: Illegal INCLUSION_ORDER value (<name1>) in expression '<name2>'.

Cause:	Illegal INCLUSION_ORDER value in expression.

Action:	Correct INCLUSION_ORDER value.


BRW-15551: Expression '<name>' included but INCLUSION_ORDER unspecified.

Cause:	The INCLUSION_ORDER unspecified for an included expression block.

Action:	Specify the INCLUSION_ORDER field.


BRW-15552: Expression '<name>' not included but INCLUSION_ORDER is non-null

Cause:	Expression is not included (INCLUDED = FALSE) but INCLUSION_ORDER is non-null.

Action:	Correct the values in these fields.


BRW-15553: Error: Empty TEXT string in expression '<name>'.

Cause:	The TEXT string is unspecified within a QXF expression block.

Action:	Specify the TEXT string.


BRW-15554: Error: SORT_PRIORITY unspecified for sorted expression '<name>'.

Cause:	SORT_PRIORITY unspecified for sorted expression.

Action:	Specify the SORT_PRIORITY.


BRW-15555: Illegal INCLUSION_ORDER value for field '<name1>'in table '<name2>'.

Cause:	Illegal INCLUSION_ORDER value for field.

Action:	Correct the INCLUSION_ORDER value.


BRW-15556: Field '<name1>' in table '<name2>' included but INCLUSION_ORDER is null.

Cause:	Field is included (INCLUDED = FALSE) but INCLUSION_ORDER is unspecified.

Action:	Correct the values in these fields.


BRW-15557: Field '<name1>' (table '<name2>') excluded but INCLUSION_ORDER exists.

Cause:	The field in specified data table is not included but the INCLUSION_ORDER is non-null.

Action:	Correct the values in these fields.


BRW-15558: SORT_PRIORITY unspecified for sorted field '<name1>' in table '<name2>'.

Cause:	SORT_PRIORITY unspecified for a sorted field.

Action:	Specify the SORT_PRIORITY for that field.


BRW-15559: Error: Illegal value '<name1>' for INCLUSION_ORDER in table '<name2>'.

Cause:	A negative value in inclusion order.

Action:	Correct that value.


BRW-15560: Table '<name>' included but INCLUSION_ORDER unspecified.

Cause:	Data Table included (INCLUDED = TRUE) but INCLUSION_ORDER is unspecified.

Action:	Correct the values in these fields.


BRW-15561: Table '<name>' is excluded but INCLUSION_ORDER is non-null.

Cause:	Data Table not included (INCLUDED = FALSE) but INCLUSION_ORDER is non-null.

Action:	Correct the values in these fields.


BRW-15562: Error: There should be no more than one main condition block.

Cause:	There are more than one main (root) condition blocks.

Action:	Eliminate some condition blocks, or use a conjunction.


BRW-15563: Error: QXF file version 1.0 expected.

Cause:	Illegal version number specified in VERSION field.

Action:	Modify the version.


BRW-15564: Parse Error: Line <##>: Invalid font style '<name>'.

Cause:	Invalid font style.

Action:	Check font style and correct it.


BRW-15565: Parse Error: Line <##>: Invalid font style argument.

Cause:	Invalid font style argument.

Action:	Check font style strings and correct them.


BRW-15566: Parse Error: Line <##>: Invalid aggregate function '<name>'

Cause:	Invalid aggregate function name.

Action:	Correct the function name.


BRW-15567: Parse Error: Line <##>: Invalid summarize argument.

Cause:	Invalid summarize field argument.

Action:	Correct the field argument.


BRW-15568: Parse Error: Line <##>: Invalid field argument.

Cause:	Invalid field argument.

Action:	Correct field argument.


BRW-15569: Warning: QXF file is only partially loaded because of error.

Cause:	Error in loading QXF file.

Action:	Correct those errors.


BRW-15570: Parse Error: Line <##>: Invalid operator '<name>' in relationship block.

Cause:	Invalid Operator within relationship block.

Action:	Check operator and correct it.


BRW-15571: Parse Error: Line <##>: Invalid operator field argument.

Cause:	Invalid Object ID within Derived Item Expression.

Action:	Correct Object ID in dictionary.


BRW-15572: Inconsistent object IDs in derived item expression.

Cause:	Invalid operator field argument within relationship block.

Action:	Check operator strings and correct them.


BRW-15580: Unable to load list of accessible business areas

Cause:	End User Layer is missing business area tables.

Action:	Reinstall End User Layer. Ask system administrator for assistance.


BRW-15581: Cannot add columns to table created with duplicate data

Cause:	User tried to add columns to a table created with duplicate table data.

Action:	Commit the duplicate table then try again.


BRW-15582: New or duplicate table is only allowed on existing table.

Cause:	Create new table on another new/duplicate/modified table.

Action:	Commit the new/duplicate/modified table first.


BRW-15583: Index requires at least one column

Cause:	User tried to remove the last column of an index.

Action:	Add other columns then remove.


BRW-15584: Column <name> is of type LONG and will not be copied

Cause:	Cannot copy a LONG column when creating a snapshot.

Action:	Column cannot be copied.


BRW-15600: Syntax not supported

Cause:	Attempted to parse unsupported syntax.

Action:	Use alternate Oracle 8 syntax.


 BRW-15601: Invalid Oracle 8 SQL syntax

Cause:	Cannot use Oracle 8 language syntax.

Action:	Use Oracle 7 SQL.


BRW-15602: Type Constructor in Oracle 8 SQL is not supported

Cause:	Oracle 8 SQL’s type constructors are not supported.

Action:	Revert to Oracle 7.


BRW-15603: REF in Oracle 8 SQL is not supported

Cause:	Oracle 8 SQL’s REF is not supported.

Action:	Use Oracle 7 instead.


BRW-15604: CAST in Oracle 8 SQL is not supported

Cause:	Oracle 8 SQL’s CAST is not supported.

Action:	Use Oracle 7 instead.


BRW-15605: MULTISET in Oracle 8 SQL is not supported.

Cause:	Oracle 8 SQL’s MULTISET is not supported.

Action:	Use Oracle 7 instead.


BRW-15606: METHODS in Oracle 8 SQL are not supported.

Cause:	Oracle 8 SQL’s METHODS are not supported.

Action:	Use Oracle 7 instead.


BRW-15607: THE subquery in Oracle 8 SQL is not supported

Cause:	Oracle 8 SQL’s THE subquery is not supported.

Action:	Use Oracle 7 instead.


BRW-15608: PARTITION of tables in Oracle 8 SQL is not supported

Cause:	Oracle 8 SQL’s PARTITION of tables is not supported.

Action:	Use Oracle 7 instead.


BRW-15609: The TABLE keyword in a subquery in Oracle 8 SQL is not supported

Cause:	TABLE keyword in subquery is not supported.

Action:	Use Oracle 7 instead.


BRW-15610: Rename the Table as a Table Alias

Cause:	Attempted to use a table instead of a table alias/

Action:	Rename the table with a table alias.


BRW-15641: Help system initialization failed. Help will be unavailable.

Cause:	Unable to locate help document or help resource file.

Action:	User may continue but help menu is unavailable. Use online or paper documentation.


BRW-15643: Resource file not found (<name>), trying default resource file.

Cause:	NLS_LANG set but file not found.

Action:	Try to open the resource file using the default language.


BRW-15644: Unable to locate help document (<name>), trying default help document.

Cause:	NLS_LANG set but file not found.

Action:	Try to open the help doc using the default language.


BRW-15647: Unable to locate help document

Cause:	Couldn't find help file in correct directory with correct language.

Action:	Check Query Builder directory structure. Make sure NLS_LANG is set correctly.


BRW-15648: Help system creation error

Cause:	Help system couldn't start up.

Action:	Query Builder couldn't find the help resource file, or NLS_LANG is not set, or memory is low.


BRW-15649: Input for <name> was too low. Minimum valid number is <##>.

Cause:	The value input was too low.

Action:	Try again with a higher value.


BRW-15650: Input for <name> was too high. Maximum valid number is <##>.

Cause:	The value input was too high.

Action:	Try again with a lower value.


BRW-15651: Input for <name> was out of range. Must be between <##> and <##>.

Cause:	The value input was out of the valid range.

Action:	Try again with a valid number.


BRW-15652: Value was reset to <value>.

Cause:	The value input was changed because it was out of the valid range.

Action:	Try again with a valid number or Query Builder will use the value shown.


BRW-15653: Pref file error: Value <value> was too low. Minimum valid number is <##>.

Cause:	The value input was too low.

Action:	Try again with a higher value.


BRW-15654: Pref file error: Value <value> was too high. Maximum valid number is <##>.

Cause:	The value input was too high.

Action:	Try again with a lower value.


BRW-15655: Pref file error: Value <value> out of range. Must be between <##> and <##>.

Cause:	The value input was out of the valid range.

Action:	Try again with a valid number.


BRW-15656: Pref file error: Value for <value> not recognized

Cause:	The value set in the preference file was invalid.

Action:	Try again with a valid number.


BRW-15657: Value for OWNERLIST=NAME must contain at least one name

Cause:	The value for OWNERLIST=NAME was NULL.

Action:	Try again with a valid name


BRW-15900: Unable to find time period information

Cause:	This database does not support time periods, or database error.

Action:	Try again later if this is unexpected.


BRW-15901: Table <name1> referred to by object <name2> no longer exists

Cause:	Base data source of object has been removed.

Action:	Refresh/delete object.


BRW-15902: Table referred to by object <name> no longer exists

Cause:	Base data source of object has been removed.

Action:	Refresh/delete object.


BRW-15903: Opposite table <name> is not in a business area. Join info inaccessible.

Cause:	Relationship: Opposite data table/object not in any group.

Action:	Grant that object to a group.


BRW-15904: Relationship name cannot be longer than <##> bytes

Cause:	Relationship Name longer than limit.

Action:	Use a shorter name.


BRW-15905: Column heading cannot be longer than <##> bytes

Cause:	Item Heading longer than limit.

Action:	Use a shorter heading.


BRW-15906: Column format cannot be longer than <##> bytes

Cause:	Item Format longer than limit.

Action:	Use a shorter format.


BRW-15907: Column display width cannot have more than <##> digits

Cause:	Item Display Width Precision longer than limit.

Action:	Use Shorter Display width.


BRW-15908: Time period name cannot be longer than <##> bytes

Cause:	Time Period Name too long.

Action:	Use a shorter time period name.


BRW-15909: Period column and sequence column of time period are the same

Cause:	Period and sequence columns of time period set to the same column.

Action:	make sure period and sequence columns are different.


BRW-15910: Unable to load time period <name>

Cause:	Schema internal error in loading time period.

Action:	Refer to accompanying error messages for more information.


BRW-15911: Time period <name> already exists

Cause:	Time period name must be unique.

Action:	Create time period under a different name.


BRW-15912: Illegal display width value.

Cause:	Illegal display width value.

Action:	Re-enter a legal value.


BRW-15913: <name> key text cannot be empty.

Cause:	Foreign or Primary Key text is empty.

Action:	Enter text for primary or foreign key.


BRW-15914: Relationship name cannot be empty.

Cause:	Relationship name is null.

Action:	Enter relationship name.


BRW-15924: Business area name cannot be empty

Cause:	Business area name is empty or contains only spaces.

Action:	Enter a new name.


BRW-15925: Table <name1> has already been imported as <name2>

Cause:	Table can only be imported once with a given name.

Action:	Import table under a different name.


BRW-15926: Business area <name> already exists

Cause:	Business area name must be unique.

Action:	Create business area under a different name.


BRW-15927: Business area <name1> already contains a table named <name2>

Cause:	Table name must be unique within a business area.

Action:	Rename/reimport table and add to business area.


BRW-15928: Business area name too long (Max <##> bytes)

Cause:	Business area name too long.

Action:	Shorten the name and try again.


BRW-15929: Business area description too long (Max <##> bytes)

Cause:	Business area description too long.

Action:	Shorten the description and try again.


BRW-15930: Error committing table <name>

Cause:	Error occurred while committing table.

Action:	Try again.


BRW-15931: Error committing business area <name>

Cause:	Error occurred while committing business area.

Action:	Try again.


BRW-15932: Error committing time period <name>

Cause:	Error occurred while committing time period.

Action:	Try again.


BRW-15933: Error committing relationship <name>

Cause:	Error occurred while committing relationship

Action:	Try again.


BRW-15937: Error generating SQL for table <name>

Cause:	Error occurred while generating SQL for a table.

Action:	Try again.


BRW-15938: Error generating SQL for business area <name>

Cause:	Error occurred while generating SQL for a business area.

Action:	Try again.


BRW-15939: Error generating SQL for time period <name>

Cause:	Error occurred while generating SQL for a time period.

Action:	Try again.


BRW-15940: Error generating SQL for relationship <name>

Cause:	Error occurred while generating SQL for relationship.

Action:	Try again.


BRW-15950: No Oracle Query Builder tables--Database open/save is disabled

Cause:	There is no Query Builder system query table in the database.

Action:	Create a system query table (run the Query Builder install script).


BRW-15951: Product user profile information not loaded

Cause:	Cannot load the user profile table.

Action:	Ask system administrator to create one.


BRW-15952: User privilege table not loaded

Cause:	Missing USER_USERS table (Non Oracle or Oracle V7 database).

Action:	None available.


BRW-15953: Table privilege table not loaded

Cause:	Cannot find Privilege table.

Action:	Non-Oracle database or Oracle V7 database.


BRW-15954: Oracle Query Builder 2.5 tables are missing or not installed properly

Cause:	No QUERY BUILDER_DOCS_SQL table.

Action:	Re-install Query Builder 2.5 tables.


BRW-15955: Query returned zero rows

Cause:	Query returned no rows.

Action:	Modify the query so that it requests data that exists in the database.


BRW-16000: Document saved using End User Layer, not Native dictionary. Continue?

Cause:	User tried to open in Native mode a document saved using the End User Layer.

Action:	Run Query Builder with DICTIONARY=ENDUSER or continue (End User Layer objects will be inaccessible).


BRW-16001: Document saved using Native dictionary, not End User Layer. Continue?

Cause:	User tried to open in ENDUSER mode a document saved using the Native dictionary.

Action:	Run Query Builder with DICTIONARY=NATIVE or continue (some database objects may be inaccessible).


BRW-16250: Document already exists. Do you want to overwrite?

Cause:	User tried to Save As over an existing document.

Action:	User may overwrite or cancel.


BRW-16251: Table has been modified. Continue?

Cause:	View was removed and recreated; may be inconsistent with document.

Action:	Either continue or abort save.


BRW-16500: Memory not available for local sort. Re-execute?

Cause:	All rows not yet fetched for local sort.

Action:	Re-execute query now or later.


BRW-16503: Data not available for local sort. Re-execute?

Cause:	All rows not yet fetched for local sort.

Action:	Re-execute query now or later.


BRW-16504: Data not available for local break. Re-execute?

Cause:	All rows not yet fetched for local break.

Action:	Re-execute query now or later.


BRW-16525: Query may require a Cartesian product. Continue?

Cause:	Query combines results of unrelated tables.

Action:	Ignore message or relate tables before executing. Refer to help or documentation for details.


BRW-16531: Redefine parameter <name>?

Cause:	User entered previously deleted parameter in expression or condition.

Action:	Press OK if this is what you intended.


BRW-16532: Parameter <name> does not exist. Define?

Cause:	User entered new parameter in expression or condition.

Action:	Press OK if this is what you intended.


BRW-16549: Revert will undo all changes on these tables. Revert anyway?

Cause:	Confirmation before reverting data tables.

Action:	Click OK to revert all selected data tables, Cancel to cancel the operation.


BRW-16550: Table <name> has primary/unique keys that are referenced. Remove?

Cause:	Table contains constraints.

Action:	Click OK to remove the data table, Cancel to cancel the operation.


BRW-16551: Column has primary/unique keys or indexes. Remove anyway?

Cause:	Column is used by constraints or indexes.

Action:	Click OK to remove the column, Cancel to cancel the operation.


BRW-16552: Disable all constraints?

Cause:	Message to confirm that all constraints should be disabled.

Action:	User may confirm or cancel.


BRW-16553: Enable all constraints?

Cause:	Message to confirm that all constraints should be enabled.

Action:	User may confirm or cancel.


BRW-16575: There are uncommitted edits which will be lost. Commit?

Cause:	User has tried to exit the Data Editor without committing changes.

Action:	Click Commit or lose changes.


BRW-16576: Defined Column, Summary and Break values may not be current. Re-execute?

Cause:	Values edited while displaying breaks, summaries, or defined columns.

Action:	Execute query to update values.


BRW-16623: There is no data available for this operation.

Cause:	Alert message if number of rows or columns available to print is zero.

Action:	User should try re-executing the query, or include some columns.


BRW-16624: Query definition has changed. Data may not be current. Continue?

Cause:	Query document has changed since last execute.

Action:	Either re-execute the query, continue export, or cancel.


BRW-16625: The printer does not support all fonts needed. Substitute fonts?

Cause:	The font or some style or weight does not exist for the selected printer.

Action:	User may continue with font substitution or cancel.


BRW-16626: Not enough memory for Print Preview.

Cause:	Unable to create bitmap for print preview.

Action:	No action required.


BRW-16627: There is no data available for this operation. Execute query?

Cause:	Alert message if export data called with empty worksheet.

Action:	User should try executing the query or cancel.


BRW-16628: Unable to get printer device. Printing will be unavailable. Continue?

Cause:	Error creating a toolkit printer surface with uiprc().

Action:	User may continue with no printing or cancel.


BRW-16629: Do you want to update the container before exiting?

Cause:	Message to prompt user to save changes when closing/quitting OLE doc.

Action:	User may save or abort changes, or cancel.


BRW-16650: The printer does not support all fonts needed. Substitute fonts?

Cause:	The font or some style or weight does not exist for the selected printer.

Action:	User may continue with font substitution or cancel.


BRW-16651: No printer has been chosen. Use Default?

Cause:	The user has not explicitly named a printer to use.

Action:	User may continue with the system default printer or cancel.


BRW-16652: Margins for this document are too wide and must be reset.

Cause:	The user has set the margins to be too large leaving no content.

Action:	User must reset the margins.


BRW-16653: No printer has been chosen. Use Default?

Cause:	The user has not explicitly named a printer to use.

Action:	User may continue with the system default printer or cancel.


BRW-16654: No pages printed.

Cause:	User has set copies to 0 or the start/end page outside the range.

Action:	Reset page range.


BRW-16660: Query definition has changed. Data may not be current. Re-execute?

Cause:	Query document has changed since last DDE update.

Action:	Re-execute the query before DDE update, or update without executing.


These are the new features for R6.0, other than the Oracle8 items (which are in their own folder in the common area).


PL/SQL editing enhancements

The Program Unit and Stored Program Unit editors now support a range of editing features in Microsoft Windows such as:

•	Automatic indenting--As you enter code in the editors, lines are automatically indented.

•	Color syntax highlighting--Keywords, comments, and strings are colored differently.

•	Column and line selection--You can select columns of text as well as lines of source code.

•	Drag and drop text manipulation--Highlighted text may be copied or moved by dragging and dropping.

•	Multiple split views--You can create up to four separate views of the current program unit in the editor.

•	Printing--You can print the current program unit.

•	Unlimited undo/redo--You can undo/redo all edit actions up to the last save operation.


LOV wizard

  Related Topics

The LOV Wizard enables you to create and modify a list of values (LOV), a scrollable popup window that provides the user with a single- or multi-column selection list. The Wizard guides you through the process of selecting an existing record group or creating a new query record group, selecting columns from the record group for display, and formatting the LOV. You can also use the LOV Wizard in its re-entrant mode to modify existing LOVs.


Hierarchical tree control

  Related Topics

The hierarchical tree displays data in the form of a standard navigaotor, similar to those used in Forms Developer.

You can populate a hierarchical tree with values contained in a Record Group or Query Text. At runtime, you can programmatically add, remove, modify, or evaluate elements in a hierarchical tree.

The amount of data displayed at any one time depends upon the expansion of individual data nodes, whether through built-ins or a user clicking on a node. The data set generally will be initially specified in Form Builder, and may be modified or entirely replaced at runtime.


Forms Runtime Diagnostics

  Related Topics

Forms Runtime Diagnostics (FRD) is a runtime event-based logging system designed to help you debug your application.

When a form is run with FRD enabled, a combination of external user-application interactions and internal Forms processing events are written in chronological order to a log on the file system. These events can then be analyzed for correctness.


Extending and customizing your application with Java
Extending your application with Pluggable Java Components

  Related Topics

When you create a WebForms application, you can extend and customize its functionality.

This can be done in two ways:

•	By adding JavaBeans to your application.

•	By replacing standard user-interface components in the form with your own customized versions, or even adding your own specialized user-interface components.

The JavaBeans and customized components supported by WebForms are referred to as Pluggable Java Components.

What Are JavaBeans?

JavaBeans are application units written in Java.  They are portable, reusable, and platform-independent. Functionally, a JavaBean can do anything that is possible within the Java language.

JavaBeans can be used individually, or can be combined with each other or with non-Java programs to quickly construct large-scale applications with a wide range of abilities.

JavaBeans are similar to Java applets, but all JavaBeans conform to the public JavaBeans specification, and have certain characteristics that enhance their usability as application components.  They have persistence, they permit introspection, and they use properties, methods, and events for communicating with other components in an application.

Why Are JavaBeans Useful?

Adding a JavaBean to your forms application allows you to easily extend its capabilities.  Although you can write your own JavaBeans, most developers prefer to obtain them ready-made, allowing them to speed up their development process.  The off-the-shelf beans can be quickly snapped into your application.

Ready-to-use JavaBeans are available from an ever-growing list of software vendors.  And the available beans offer a wide variety of instant functionality.

How Do Pluggable Java Components Work?

The WebForms product supplies you with interface mechanisms that allow you to easily add JavaBeans and customized interface components to your application.

Your JavaBeans and customized components make use of a special Forms-defined interface, called the IView interface.  This Java interface is provided for you.

Your JavaBeans also make use of a special Forms-provided Java class, called the VBean class.  By wrapping your JavaBean in a container that extends this class, your JavaBean can easily communicate with your form at runtime.  The JavaBean can be started from the form, and values can be passed back and forth.

In addition to the IView interface and VBean class, WebForms also provides you with certain form properties, built-ins, triggers, and system variables for communicating with your pluggable components.

What the User Sees

For the end user at runtime, the JavaBean is represented by an interface item on the screen.  Clicking on the item initiates the execution of the JavaBean.  Other controls and data items may also be associated with the bean, to allow runtime interaction or display of changed values or results.

Communication at Runtime

During its initiation process at the beginning of runtime, WebForms sets up communication mechanisms with the JavaBean.  WebForms accesses your container class and instantiates the container and its bean. This initiation process registers a listener relationship, so that properties can be shared and events communicated during runtime.

Forms Elements Affected

Elements in the WebForms product affected by this new Pluggable Java Components feature include:

•	The Item Type property, to which a new item type, called Bean Area, has been added.

•	A new property, called Implementation Class property, which connects the item to your Java component through its fully-qualified class name.

•	New built-ins, called Get_Custom_Property and Set_Custom_Property, used for communicating with the Java component.

•	The When-Custom-Item-Event trigger, used for receiving event information from the Java component.  (Applicable only for the Bean Area.)

•	The System.Custom_Item_Event and System.Custom_Item_Event_Parameters storage areas, used for receiving event identifiers and values from the Java component.

For additional information about Pluggable Java Components, use the related topics button above.


Launching WebForms from the Designer

  Related Topics

Now it's easier to preview your forms designed to be run from the web.  Click on the Run Form Web icon [image] in the Object Navigator or Layout Editor to launch the Web Previewer with your form running locally in a Java UI shell.


Java user interface shell

As part of the Network Computing initiative, Oracle is defining a new desktop environment for Java components.   As a first step towards this desktop environment, Oracle is developing a lightweight Window and Menu System which will be part of the Oracle desktop environment.  This Java UI Shell supports configurable Look and Feel of Java UI components.

For more information on the client UI Shell, see Configuring the Forms Developer Server.


Expansion of the Defer Required Enforcement property

A third option has been added to the Defer Required Enforcement property.  This new option allows you to run in Release 5.0 compatibility mode, but still retain some of the Release 4.5 behavior.

When you choose this option, a null value is accepted in a Required item during item-level validation (although the item instance is not marked as valid), and the When-Validate-Trigger does fire.

For details, see Defer Required Enforcement property.


New property for controlling truncation and validation

A new application property, called Flag User Value Too Long, has been added.

This property allows you to choose how Form Builder will behave during validation when the end user has typed in a value that exceeds the item‘s Maximum Length property.

This property applies only in a 3-tier environment in which the middle tier (the Forms server) specifies a multi-byte character set other than UTF8.

For details, see Flag User Value Too Long property .


New ability to list all tab pages

A new key, called List Tab Pages (corresponding to the F2 key), has been added to the tab canvas functionality.

If the end users press this key, they are shown a pop-down list of all the tab-page names for that canvas.  From this list, they can pick the tab-page that they want to activate.

This feature is handy in those cases where there are so many tabs for the canvas that not all can appear simultaneously.


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.


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 Windows registry for Microsoft Windows 95/NT 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.


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


The Object Navigator

Viewing objects in the Object Navigator

About the Object Navigator

Changing Object Navigator views

Navigating and selecting objects in the Object Navigator

Expanding and collapsing objects in the Object Navigator

Finding Object Navigator entries with fast search

Setting a mark in the Object Navigator

Working with multiple panes

Creating and moving objects in the Object Navigator

Creating and deleting objects in the Object Navigator

Changing the names of objects in the Object Navigator

Moving and copying objects in the Object Navigator

Copying objects between modules


The Layout Editor

General Information

About the  Layout Editor

Layout Editor tool palette

Switching to a different canvas in the Layout Editor

Selecting objects in the Layout Editor

Moving objects in the Layout Editor

Resizing objects in the Layout Editor

Aligning objects in the Layout Editor

Grouping objects in the Layout Editor

Ordering objects in the Layout Editor

Blocks and Items

Creating items

Setting Layout Editor block context

Working with multi-record blocks

Formatting Objects

Setting color and pattern attributes in the Layout Editor

Formatting items in the Layout Editor


The PL/SQL Editor

Writing Code in the PL/SQL Editor

Creating a trigger

Writing trigger code

Calling a built-in subprogram

About the PL/SQL Editor

PL/SQL Editor context

PL/SQL Editor commands

Using PL/SQL in Forms Builder


The Menu Editor

Steps to build a custom Menu

Creating a menu module

Creating menus and menu items

Assigning commands to menu items

Attaching a menu module to a form

Using the Menu Editor

Displaying menus in the Menu Editor

About menu object names and labels

Changing menu object names and labels

Adding Special Menu Items

About special menu item types

Creating special menu items

Commands for check and radio menu items

Setting the state of check and radio menu items

Magic item default functionality


Defining an interface item

  Next Step

I want to define the behavior of my...

•	ActiveX controls

•	Buttons

•	Chart items

•	Check boxes

•	Image items

•	List items

•	OLE container items

•	Radio groups

•	Sound items

•	Text items


Defining an ActiveX control

  Related Topics

What would you like to do?

Embed an ActiveX control in a form

Set and get ActiveX control properties

Invoke ActiveX control methods

Respond to ActiveX control events

Registering ActiveX controls

Deploying ActiveX controls with your application


Defining a button

  Related Topics

What would you like to do?

Add a button label

Create an iconic button

Create a default button

Manipulate a button at runtime


Defining a chart item

What would you like to do?

 Create a chart item


Defining a check box

  Related Topics

What would you like to do?

Specify a default value for a check box

Manipulate a check box at runtime


Defining an image item

  Related Topics

What would you like to do?

Populate an image item

Manipulate images at runtime


Defining a list item

  Related Topics

What would you like to do?

Specify a default value for a list item

Manipulate a list item at runtime

Add a list element

Retrieve and store list elements in a record group

Delete a list element


Defining an OLE container item

  Related Topics

What would you like to do?

Embed an OLE object

Link an OLE object

Display an OLE object

Edit an OLE object

Convert an OLE object


Defining a radio group

  Related Topics

What would you like to do?

Specify a default value for a radio group

Manipulate a radio group at runtime


Defining a sound item

  Related Topics

What would you like to do?

Set sound item control properties

Manipulate sound items programmatically


Defining a text item

  Related Topics

What would you like to do?

Create single-line and multi-line text items

Making a text item value required

Specify the maximum length for a text item

Specify a required value for a text item

Specify a fixed length value for a text item

Specify a valid range of values

Hide text item values

Format values with format masks

Assign a list of values (LOV) to a text item

Manipulate a text item at runtime


Built-in packages

 Alphabetic list	  Related Topics

Active X (OCX) Built-ins

Alert Built-ins

Application Built-ins

Block Built-ins

Canvas Built-ins

Chart Built-ins

Form Built-ins

Item Built-ins

Menu Built-ins

Message Built-ins

Multiple Form Built-ins

OLE Built-ins

Parameter List Built-ins

PECS Built-ins

Query Built-ins

Record Built-ins

Relation Built-ins

Report Built-ins

Tab Page Built-ins

Transactional Built-ins

Web Built-ins

Window Built-ins


Form Builder Built-ins

 All Built-ins

A

ABORT_QUERY

ADD_GROUP_COLUMN

ADD_GROUP_ROW

ADD_LIST_ELEMENT

ADD_OLEARGS

ADD_PARAMETER

APPLICATION_PARAMETER

B

BELL

BLOCK_MENU

BREAK

C

CALL_FORM

CALL_INPUT

CALL_OLE

CALL_OLE_<return type>

CANCEL_REPORT_OBJECT

CHECK_RECORD_UNIQUENESS

CHECKBOX_CHECKED

CHECKED

CLEAR_BLOCK

CLEAR_EOL

CLEAR_FORM

CLEAR_ITEM

CLEAR_LIST

CLEAR_MESSAGE

CLEAR_RECORD

CLOSE_FORM

COMMIT_FORM

CONVERT_OTHER_VALUE

COPY

COPY_REGION

COPY_REPORT_OUTPUT

COUNT_QUERY

CREATE_GROUP

CREATE_GROUP_FROM_QUERY

CREATE_OLEOBJ

CREATE_PARAMETER_LIST

CREATE_QUERIED_RECORD

CREATE_RECORD

CREATE_TIMER

CREATE_VAR

CUT_REGION

D

DBMS_ERROR_CODE

DBMS_ERROR_TEXT

DEBUG_MODE

DEFAULT_VALUE

DELETE_GROUP

DELETE_GROUP_ROW

DELETE_LIST_ELEMENT

DELETE_PARAMETER

DELETE_RECORD

DELETE_TIMER

DESTROY_PARAMETER_LIST

DESTROY_VARIANT

DISPATCH_EVENT

DISPLAY_ERROR

DISPLAY_ITEM

DOWN

DO_KEY

DUMMY_REFERENCE

DUPLICATE_ITEM

DUPLICATE_RECORD

E

EDIT_TEXTITEM

ENFORCE_COLUMN_SECURITY

ENTER

ENTER_QUERY

ERASE

ERROR_CODE

ERROR_TEXT

ERROR_TYPE

EXECUTE_QUERY

EXECUTE_TRIGGER

EXIT_FORM

F

FETCH_RECORDS

FIND_ALERT

FIND_BLOCK

FIND_CANVAS

FIND_COLUMN

FIND_EDITOR

FIND_FORM

FIND_GROUP

FIND_ITEM

FIND_LOV

FIND_MENU_ITEM

FIND_RELATION

FIND_REPORT_OBJECT

FIND_TAB_PAGE

FIND_TIMER

FIND_VIEW

FIND_WINDOW

FIRST_RECORD

FORM_FAILURE

FORM_FATAL

FORM_SUCCESS

FORMS_DDL

FORMS_OLE.ACTIVATE_SERVER

FORMS_OLE.CLOSE_SERVER

FORMS_OLE.EXEC_VERB

FORMS_OLE.FIND_OLE_VERB

FORMS_OLE.GET_INTERFACE_POINTER

FORMS_OLE.GET_VERB_COUNT

FORMS_OLE.GET_VERB_NAME

FORMS_OLE.INITIALIZE_CONTAINER

FORMS_OLE.SERVER_ACTIVE

G

GENERATE_SEQUENCE_NUMBER

GET_APPLICATION_PROPERTY

GET_BLOCK_PROPERTY

GET_CANVAS_PROPERTY

GET_FILE_NAME

GET_FORM_PROPERTY

GET_GROUP_CHAR_CELL

GET_GROUP_DATE_CELL

GET_GROUP_NUMBER_CELL

GET_GROUP_RECORD_NUMBER

GET_GROUP_ROW_COUNT

GET_GROUP_SELECTION

GET_GROUP_SELECTION_COUNT

GET_INTERFACE_POINTER

GET_ITEM_INSTANCE_PROPERTY

GET_ITEM_PROPERTY

GET_LIST_ELEMENT_COUNT

GET_LIST_ELEMENT_LABEL

GET_LIST_ELEMENT_VALUE

GET_LOV_PROPERTY

GET_MENU_ITEM_PROPERTY

GET_MESSAGE

GET_OLEARG_<type>

GET_OLE_MEMBERID

GET_OLE_<proptype>

GET_PARAMETER_ATTR

GET_PARAMETER_LIST

GET_RADIO_BUTTON_PROPERTY

GET_RECORD_PROPERTY

GET_RELATION_PROPERTY

GET_REPORT_OBJECT_PROPERTY

GET_TAB_PAGE_PROPERTY

GET_VAR_BOUNDS

GET_VAR_DIMS

GET_VAR_TYPE

GET_VIEW_PROPERTY

GET_WINDOW_PROPERTY

GO_BLOCK

GO_FORM

GO_ITEM

GO_RECORD

H

HELP

HIDE_MENU

HIDE_VIEW

HIDE_WINDOW

HOST

I

ID_NULL

IMAGE_SCROLL

IMAGE_ZOOM

INIT_OLEARGS

INITIALIZE_CONTAINER

INSERT_RECORD

ISSUE_ROLLBACK

ISSUE_SAVEPOINT

ITEM_ENABLED

J

K

L

LAST_OLE_ERROR

LAST_OLE_EXCEPTION

LAST_RECORD

LIST_VALUES

LOCK_RECORD

LOGON

LOGON_SCREEN

LOGOUT

M

MENU_CLEAR_FIELD

MENU_NEXT_FIELD

MENU_PARAMETER

MENU_PREVIOUS_FIELD

MENU_REDISPLAY

MENU_SHOW_KEYS

MESSAGE

MESSAGE_CODE

MESSAGE_TEXT

MESSAGE_TYPE

MOVE_WINDOW

N

NAME_IN

NEW_FORM

NEXT_BLOCK

NEXT_ITEM

NEXT_FORM

NEXT_KEY

NEXT_MENU_ITEM

NEXT_RECORD

NEXT_SET

O

OLEVAR_EMPTY

OPEN_FORM

P

PASTE_REGION

PAUSE

PECS.ADD_CLASS

PECS.ADD_EVENT

PECS.COLLECTOR

PECS.DISABLE_CLASS

PECS.ENABLE_CLASS

PECS.END_EVENT

PECS.POINT_EVENT

PECS.START_EVENT

PLAY_SOUND

POPULATE_GROUP

POPULATE_GROUP_WITH_QUERY

POPULATE_LIST

POST

PREVIOUS_BLOCK

PREVIOUS_FORM

PREVIOUS_ITEM

PREVIOUS_MENU

PREVIOUS_MENU_ITEM

PREVIOUS_RECORD

PRINT

PTR_TO_VAR

Q

QUERY_PARAMETER

R

READ_IMAGE_FILE

READ_SOUND_FILE

RECALCULATE

REDISPLAY

RELEASE_OBJ

REPLACE_CONTENT_VIEW

REPLACE_MENU

REPORT_OBJECT_STATUS

RESET_GROUP_SELECTION

RESIZE_WINDOW

RETRIEVE_LIST

RUN_PRODUCT

RUN_REPORT_OBJECT

S

SCROLL_DOWN

SCROLL_UP

SCROLL_VIEW

SELECT_ALL

SELECT_RECORDS

SET_ALERT_BUTTON_PROPERTY

SET_ALERT_PROPERTY

SET_APPLICATION_PROPERTY

SET_BLOCK_PROPERTY

SET_CANVAS_PROPERTY

SET_FORM_PROPERTY

SET_GROUP_CHAR_CELL

SET_GROUP_DATE_CELL

SET_GROUP_NUMBER_CELL

SET_GROUP_SELECTION

SET_INPUT_FOCUS

SET_ITEM_INSTANCE_PROPERTY

SET_ITEM_PROPERTY

SET_LOV_COLUMN_PROPERTY

SET_LOV_PROPERTY

SET_MENU_ITEM_PROPERTY

SET_OLE

SET_PARAMETER_ATTR

SET_RADIO_BUTTON_PROPERTY

SET_RECORD_PROPERTY

SET_RELATION_PROPERTY

SET_REPORT_OBJECT_PROPERTY

SET_TAB_PAGE_PROPERTY

SET_TIMER

SET_VAR

SET_VIEW_PROPERTY

SET_WINDOW_PROPERTY

SHOW_ALERT

SHOW_EDITOR

SHOW_KEYS

SHOW_LOV

SHOW_MENU

SHOW_VIEW

SHOW_WINDOW

SYNCHRONIZE

T

TERMINATE

TO_VARIANT

U

UNSET_GROUP_SELECTION

UP

UPDATE_CHART

UPDATE_RECORD

USER_EXIT

V

VALIDATE

VARPTR_TO_VAR

VAR_TO_TABLE

VAR_TO_<type>

VAR_TO_VARPTR

VBX.FIRE_EVENT

VBX.GET_PROPERTY

VBX.GET_VALUE_PROPERTY

VBX.INVOKE_METHOD

VBX.SET_PROPERTY

VBX.SET_VALUE_PROPERTY

W

WEB.SHOW_DOCUMENT

WHERE_DISPLAY

WRITE_IMAGE_FILE

WRITE_SOUND_FILE

X

Y

Z


ActiveX Built-ins

 All Built-ins

ADD_OLEARGS

CALL_OLE

CALL_OLE_<return type>

CREATE_OLEOBJ

CREATE_VAR

DESTROY_VARIANT

DISPATCH_EVENT

GET_OLEARG_<type>

GET_OLE_MEMBERID

GET_OLE_<proptype>

GET_VAR_BOUNDS

GET_VAR_DIMS

GET_VAR_TYPE

INIT_OLEARGS

LAST_OLE_ERROR

LAST_OLE_EXCEPTION

OLEVAR_EMPTY

PTR_TO_VAR

RELEASE_OBJ

SET_OLE

SET_VAR

TO_VARIANT

VARPTR_TO_VAR

VAR_TO_TABLE

VAR_TO_<type>

VAR_TO_VARPTR


Alert Built-ins

 All Built-ins

FIND_ALERT

ID_NULL

SET_ALERT_BUTTON_PROPERTY

SET_ALERT_PROPERTY

SHOW_ALERT


Application Built-ins

 All Built-ins

DO_KEY

GET_APPLICATION_PROPERTY

HOST

PAUSE

SET_APPLICATION_PROPERTY

USER_EXIT


Block Built-ins

 All Built-ins

BLOCK_MENU

CLEAR_BLOCK

FIND_BLOCK

GET_BLOCK_PROPERTY

GO_BLOCK

ID_NULL

NEXT_BLOCK

PREVIOUS_BLOCK

SET_BLOCK_PROPERTY


Canvas Built-ins

 All Built-ins

FIND_CANVAS

FIND_VIEW

GET_CANVAS_PROPERTY

GET_VIEW_PROPERTY

HIDE_VIEW

ID_NULL

PRINT

SCROLL_VIEW

SET_CANVAS_PROPERTY

SET_VIEW_PROPERTY

SHOW_VIEW


Chart Built-ins

 All Built-ins

UPDATE_CHART


Form Built-ins

 All Built-ins

BELL

BREAK

CALL_FORM

CALL_INPUT

CLEAR_FORM

COMMIT_FORM

DEBUG_MODE

ENTER

ERASE

EXECUTE_TRIGGER

EXIT_FORM

FIND_FORM

FORM_FAILURE

FORM_FATAL

FORM_SUCCESS

GET_FORM_PROPERTY

HELP

ID_NULL

NEW_FORM

OPEN_FORM

POST

REDISPLAY

REPLACE_MENU

SET_FORM_PROPERTY

SHOW_KEYS

SHOW_MENU

SYNCHRONIZE


Item Built-ins

 All Built-ins

CHECKBOX_CHECKED

CLEAR_EOL

CLEAR_ITEM

CONVERT_OTHER_VALUE

COPY

COPY_REGION

CUT_REGION

DEFAULT_VALUE

DISPLAY_ITEM

DUMMY_REFERENCE

DUPLICATE_ITEM

EDIT_TEXTITEM

FIND_ITEM

GET_FILE_NAME

GET_ITEM_INSTANCE_PROPERTY

GET_ITEM_PROPERTY

GET_RADIO_BUTTON_PROPERTY

GO_ITEM

ID_NULL

IMAGE_SCROLL

IMAGE_ZOOM

NAME_IN

NEXT_ITEM

NEXT_KEY

PASTE_REGION

PLAY_SOUND

PREVIOUS_ITEM

READ_IMAGE_FILE

READ_SOUND_FILE

RECALCULATE

SELECT_ALL

SET_ITEM_INSTANCE_PROPERTY

SET_ITEM_PROPERTY

SET_RADIO_BUTTON_PROPERTY

WRITE_IMAGE_FILE

WRITE_SOUND_FILE


Menu Built-ins

 All Built-ins

APPLICATION_PARAMETER

FIND_MENU_ITEM

GET_MENU_ITEM_PROPERTY

HIDE_MENU

ITEM_ENABLED

MENU_CLEAR_FIELD

MENU_PARAMETER

MENU_PREVIOUS_FIELD

MENU_REDISPLAY

MENU_SHOW_KEYS

NEXT_MENU_ITEM

PREVIOUS_MENU

PREVIOUS_MENU_ITEM

QUERY_PARAMETER

REPLACE_MENU

SET_INPUT_FOCUS

SET_MENU_ITEM_PROPERTY

SHOW_MENU

TERMINATE

WHERE_DISPLAY


Message Built-ins

 All Built-ins

CLEAR_MESSAGE

DBMS_ERROR_CODE

DBMS_ERROR_TEXT

DISPLAY_ERROR

ERROR_CODE

ERROR_TEXT

ERROR_TYPE

GET_MESSAGE

MESSAGE

MESSAGE_CODE

MESSAGE_TEXT

MESSAGE_TYPE


Multiple Form Built-ins

 All Built-ins

CLOSE_FORM

GO_FORM

NEW_FORM

NEXT_FORM

OPEN_FORM

PREVIOUS_FORM


OLE Built-ins

 All Built-ins

FORMS_OLE.ACTIVATE_SERVER

FORMS_OLE.CLOSE_SERVER

FORMS_OLE.EXEC_VERB

FORMS_OLE.FIND_OLE_VERB

FORMS_OLE.GET_INTERFACE_POINTER

FORMS_OLE.GET_VERB_COUNT

FORMS_OLE.GET_VERB_NAME

FORMS_OLE.INITIALIZE_CONTAINER

FORMS_OLE.SERVER_ACTIVE


Parameter List Built-ins

 All Built-ins

ADD_PARAMETER

CREATE_PARAMETER_LIST

DELETE_PARAMETER

DESTROY_PARAMETER_LIST

GET_PARAMETER_ATTR

ID_NULL

RUN_PRODUCT

SET_PARAMETER_ATTR


PECS Built-ins

 All Built-ins

PECS.ADD_CLASS

PECS.ADD_EVENT

PECS.COLLECTOR

PECS.DISABLE_CLASS

PECS.ENABLE_CLASS

PECS.END_EVENT

PECS.POINT_EVENT

PECS.START_EVENT


Query Built-ins

 All Built-ins

ABORT_QUERY

COUNT_QUERY

ENTER_QUERY

EXECUTE_QUERY


Record Built-ins

 All Built-ins

CHECK_RECORD_UNIQUENESS

CLEAR_RECORD

CREATE_QUERIED_RECORD

CREATE_RECORD

DELETE_RECORD

DOWN

DUPLICATE_RECORD

FIRST_RECORD

GENERATE_SEQUENCE_NUMBER

GET_RECORD_PROPERTY

GO_RECORD

INSERT_RECORD

LAST_RECORD

LOCK_RECORD

NEXT_RECORD

NEXT_SET

PREVIOUS_RECORD

SCROLL_DOWN

SCROLL_UP

SELECT_RECORDS

SET_RECORD_PROPERTY

UP

UPDATE_RECORD


Relation Built-ins

 All Built-ins

FIND_RELATION

GET_RELATION_PROPERTY

ID_NULL

SET_RELATION_PROPERTY


Report Built-ins

 All Built-ins

CANCEL_REPORT_OBJECT

COPY_REPORT_OUTPUT

FIND_REPORT_OBJECT

GET_REPORT_OBJECT_PROPERTY

RUN_REPORT_OBJECT

SET_REPORT_OBJECT_PROPERTY


Tab Page Built-ins

 All Built-ins

FIND_TAB_PAGE

GET_TAB_PAGE_PROPERTY

SET_TAB_PAGE_PROPERTY


Transaction Built-ins

 All Built-ins

CHECK_RECORD_UNIQUENESS

DELETE_RECORD

ENFORCE_COLUMN_SECURITY

FETCH_RECORDS

FORMS_DDL

GENERATE_SEQUENCE_NUMBER

INSERT_RECORD

ISSUE_ROLLBACK

ISSUE_SAVEPOINT

LOGON

LOGON_SCREEN

LOGOUT

SELECT_RECORDS

UPDATE_RECORD


Web Built-ins

 All Built-ins

WEB.SHOW_DOCUMENT


Window Built-ins

 All Built-ins

FIND_WINDOW

GET_WINDOW_PROPERTY

HIDE_WINDOW

ID_NULL

MOVE_WINDOW

REPLACE_CONTENT_VIEW

RESIZE_WINDOW

SET_WINDOW_PROPERTY

SHOW_WINDOW


Properties

 Alphabetic list	  Related Topics

Alert properties

Application properties

Block properties

Canvas properties

Chart properties

Editor properties

Form Parameter properties

Form Module properties

Frame properties

Graphics properties

Item properties

LOV properties

Menu properties

Named Visual Attribute Properties

Prompt properties

Record properties

Record Group properties

Relation properties

Report properties

Tab Page properties

Trigger properties

Window properties


Form Builder Properties

 All Properties

A

About Control

Access Key

Alert Style

Alias

Allow Expansion

Allow Multi-Line Prompts

Allow Start-Attached Prompts

Allow Top-Attached Prompts

Application Instance

Arrow Style

Associated Menus

Audio Channels

Automatical Column Width

Automatic Display

Automatic Position

Automatic Query

Automatic Refresh

Automatic Select

Automatic Skip (Item)

Automatic Skip (LOV)

B

Background_Color

Bevel

Block Description

Bottom Title (Editor)

Builtin Date Format

Button 1 Label, Button 2 Label, Button 3 Label

C

Calculation Mode

Calling_Form

Canvas

Canvas Type

Cap Style

Case Insensitive Query

Case Restriction

Character Cell WD/HT

Check Box Mapping of Other Values

Checked

Clip Height

Clip Width

Clip X Position

Clip Y Position

Close Allowed

Closed

Column Mapping Properties

Column Name

Column Specifications

Column Title

Column Value

Command Text

Command Type

Comments

Communication Mode (Chart)

Communication Mode (Report)

Compress

Compression_Quality

Conceal Data

Connect_String

Console Window

Control Help

Control Properties

Coordinate System

Coordination

Coordination_Status

Copy Value from Item

Current_Form

Current_Form_Name

Current_Record

Current Record Visual Attribute

Current_Row_Background_Color

Current_Row_Fill_Pattern

Current_Row_Font_Name

Current_Row_Font_Size

Current_Row_Font_Spacing

Current_Row_Font_Style

Current_Row_Font_Weight

Current_Row_Foreground_Color

Current_Row_White_On_Black

Cursor Mode

Cursor_Style

Custom Spacing

D

Dash Style

Data Block Description

Data Source Data Block (Chart)

Data Source Data Block (Report)

Data Source X Axis

Data Source Y Axis

Data Type

Data Type (Record Group)

Database Block

Database_Value

Datasource

Default Alert Button

Default Button

Default Font Scaling

Deferred

Defer_Required_Enforcement

Delete Allowed

Delete Procedure Arguments

Delete Procedure Name

Delete Procedure Result Set Columns

Delete Record Behavior

Detail Block

Detail  Reference Item

Direction

Display without Privilege

Display_Height

Display in Keyboard Help

Display Hint Automatically

Display Quality

Display_Width

Display Width (LOV)

Distance Between Records

Dither

DML Array Size

DML Data Target Name

DML Data Target Type

E

Edge Background Color

Edge Foreground Color

Edge Pattern

Editor

Editor X Position, Editor Y Position

Elements in List

Enabled (Item)

Enabled (Menu Item)

Enabled (Tab Page)

End Angle

Enforce Column Security

Enforce Primary Key

Enterable

Execution Mode (Chart)

Execution Mode (Report)

Execution Style

F

File_Name

Fill

Fill_Pattern

Filter Before Display

Fire in Enter-Query Mode

First_Block

First_Detail_Relation

First_Item

First_Master_Relation

First Navigation Block

Fixed Bounding Box

Fixed Length (Item)

Fixed Length (Menu Substitution Parameter)

Font Spacing

Font_Name

Font_Size

Font_Spacing

Font_Style

Font_Weight

Foreground_Color

Form Horizontal Toolbar Canvas

Form Vertical Toolbar Canvas

Form_Name

Format Mask

Formula

Frame Alignment

Frame Title

Frame Title Alignment

Frame Title Font Name

Frame Title Font Size

Frame Title Font Spacing

Frame Title Font Style

Frame Title Font Weight

Frame Title Font Foreground Color

Frame Title Offset

Frame Title Reading Order

Frame Title Spacing

Frame Title Visual Attribute Group

G

Graphics Type

Group_Name

H

Help

Hide on Exit

Highest Value Allowed

Hint (Item)

Hint (Menu Item)

Hint (Menu Substitution Parameter)

Horizontal Justification

Horizontal Margin

Horizontal Object Offset

Horizontal Origin

Horizontal Toolbar Canvas

I

Icon Filename

Icon in Menu

Iconic

Image_Depth

Image_Format

Implementation Class

Include REF Item

Inherit Menu

Initial Keyboard State

Initial Menu

Initial Value

Insert Allowed (Block)

Insert Allowed (Item)

Insert Procedure Arguments

Insert Procedure Name

Insert Procedure Result Set Columns

Interaction Mode

Isolation Mode

Item_Is_Valid

Item Roles

Item_Tab_Page (item)

Item Type

J

Join Condition

Join Style

Justification

K

Keep Cursor Position

Keyboard Accelerator

Keyboard Help Description

Keyboard Navigable

Keyboard State

Key Mode

L

Label (Item)

Label (Menu Item)

Label (Menu Parameter)

Label (Tab Page)

Last_Block

Last_Item

Last Query

Layout Data Block

Layout Style

Length

Line Spacing

Line Width

Listed in Block Menu/Block Description

List Item Value

List of Values

List Style

List Type

List X Position

List Y Position

Lock Procedure Arguments

Lock Procedure Name

Lock Procedure Result Set Columns

Lock Record

Locking Mode

Lowest Value Allowed

M

Magic Item

Main Menu

Mapping of Other Values

Maximize Allowed

Maximum Length (Form Parameter)

Maximum Length (Item)

Maximum Length (Menu Substitution Parameter)

Maximum Objects Per Line

Maximum Query Time

Maximum Records Fetched

Menu Description

Menu Directory

Menu Filename

Menu Item Code

Menu Item Radio Group

Menu Item Type

Menu Module

Menu Role

Menu Source

Menu Style

Message

Minimize Allowed

Minimized Title

Modal

Module_NLS_Lang

Module Roles

Mouse Navigate

Mouse Navigation Limit

Move Allowed

Multi-Line

N

Name

Navigation Style

NextBlock

NextItem

Next_Detail_Relation

Next_Master_Relation

Next Navigation Block

Next Navigation Item

Number of Items Displayed

Number of Records Buffered

Number of Records Displayed

O

OLE Activation Style

OLE Class

OLE In-place Activation

OLE Inside-Out Support

OLE Popup Menu Items

OLE Resize Style

OLE Tenant Aspect

OLE Tenant Types

Operating_System

Optimizer_Hint

Order By

Other Reports Parameters

P

Parameter Data Type

Parameter Initial Value

Parameter Menu Initial Value

Password

PLSQL Date Format

Popup Menu (Item, Canvas)

Position (X, Y)

Precompute Summaries

Prevent Masterless Operation

Previous Navigation Block

PreviousBlock

PreviousItem

Previous Navigation Item

Primary Canvas

Primary Key (Item)

Program Unit Text

Prompt

Prompt Alignment

Prompt Alignment Offset

Prompt Attachment Edge

Prompt Attachment Offset

Prompt Background Color

Prompt Display Style

Prompt Font Name

Prompt Font Size

Prompt Font Spacing

Prompt Font Style

Prompt Font Weight

Prompt Foreground Color

Prompt Fill Pattern

Prompt Justification

Prompt Reading Order

Prompt Visual Attribute Group

Prompt_Fill_Pattern

Prompt_Font_Name

Prompt_Font_Size

Prompt_Font_Spacing

Prompt_Font_Style

Prompt_Font_Weight

Prompt_Foreground_Color

Prompt_White_On_Black

Property Class

Q

Query All Records

Query Allowed (Block)

Query Allowed (Item)

Query Array Size

Query Data Source Arguments

Query Data Source Columns

Query Data Source Name

Query Data Source Type

Query Length

Query Name

Query Only

Query_Hits

Query_Options

R

Radio Button Value

Raise on Entry

Reading Order

Real Unit

Record Group

Record Group Fetch Size

Record Group Query

Record Group Type

Record Orientation

Records_To_Fetch

Relation Type

Rendered

Report Destination Format

Report Destination Name

Report Destination Type

Report Server

Required (Item)

Required (Menu Substitution Parameter)

Resize Allowed

Return Item (LOV)

Rotation Angle

Runtime Compatibility Mode

S

Savepoint Mode

Savepoint_Name

Scroll Bar Alignment

Scroll Bar Height

Scroll Bar Width

Secure (Menu Substitution Parameter)

Share Library with Form

Show Fast Forward Button

Show Horizontal Scroll Bar

Show OLE Popup Menu

Show OLE Tenant Type

Show Palette

Show Play Button

Show Record Button

Show Rewind Button

Show Scroll Bar

Show Slider

Show Time Indicator

Show Vertical Scroll Bar

Show Volume Control

Shrinkwrap

Single Object Alignment

Single Record

Size

Sizing Style

Sound Format

Sound Quality

Start Angle

Start Prompt Alignment

Start Prompt Offset

Startup Code

Status (Block)

Status (Record)

Subclass Information

Submenu Name

Summarized Block

Summarized Item

Summary Function

Synchronize with Item

T

Tab Attachment Edge

Tab Page

Tab Page X Offset

Tab Page Y Offset

Tab Style

Tear-off Menu

Timer_Name

Title

Tooltip

Tooltip_Background_Color

Tooltip_Fill_Pattern

Tooltip_Font_Name

Tooltip_Font_Size

Tooltip_Font_Spacing

Tooltip_Font_Style

Tooltip_Font_Weight

Tooltip_Foreground_Color

Tooltip Visual Attribute Group

Tooltip_White_On_Black

Topmost_Tab_Page (Canvas)

Top Prompt Alignment

Top Prompt Offset

Top Title

Top_Record

Transactional Triggers

Trigger Style

Trigger Text

Trigger Type

U

Update Allowed (Block)

Update Allowed (Item)

Update Changed Columns Only

Update_Column

Update_Commit

Update Layout

Update Only if NULL

Update_Permission

Update Procedure Arguments

Update Procedure Name

Update Procedure Result Set Columns

Update_Query

Use 3D Controls

Use Security

User_Interface

User_NLS_Date_Format

User_NLS_Lang

Username

V

Validate from List

Validation

Validation Unit

Value When Checked

Value When Unchecked

VBX Control File

VBX Control Name

VBX Control Value

Vertical Fill

Vertical Justification

Vertical Margin

Vertical Object Offset

Vertical Origin

Vertical Toolbar Canvas

Viewport Height, Viewport Width

Viewport X Position, Viewport Y Position

Viewport X Position on Canvas, Viewport Y Position on Canvas

Visible

Visible (Canvas)

Visible (Item)

Visible in Menu

Visible (Tab Page)

Visible In Horizontal/Vertical Menu Toolbar

Visual_Attribute

Visual Attribute Group

Visual Attribute Type

W

Where Clause/Order By Clause

White_On_Black

Width/Height

Window

Window_Handle

Window_State

Window Style

Wrap Style

Wrap Text

X

X Corner Radius

X Position, Y Position

Y

Y Position, X Position

Z


Alert Properties

 All Properties

Alert style

Button 1 Label, Button 2 Label, Button 3 Label

Comments

Default Alert Button

Default Button

Menu Source

Message

Name

Property Class

Title


Application Properties

 All Properties

Calling_Form

Comments

Connect_String

Current_Form

Current_Form_Name

Cursor_Style

Datasource

Display_Height

Display_Width

Interaction_Mode

Isolation_Mode

Maximum_Query_Time

Maximum_Records_Fetched

Name

Operating_System

Password

Savepoint_Name

Timer_Name

User_Interface

Username

User_NLS_Lang


 Block Properties

 All Properties

Application Instance

Block Description

Comments

Current_Record

Current Record Visual Attribute Group

Data Block Description

Database Block

Delete Allowed

Delete Procedure Arguments

Delete Procedure Name

Delete Procedure Result Set Columns

DML Array Size

DML Data Target Name

DML Data Target Type

Enforce Column Security

Enforce Primary Key

Enterable

First_Block

First_Detail_Relation

First_Item

First_Master_Relation

Insert Allowed (Block)

Insert Procedure Arguments

Insert Procedure Name

Insert Procedure Result Set Columns

Join Condition

Key Mode

Last_Item

Listed in Block Menu/Block Description

Locking Mode

Lock Procedure Name

Lock Procedure Result Set Columns

Name

Navigation Style

NextBlock

Next Navigation Block

Number of Records Buffered

Number of Records Displayed

Optimizer_Hint

Order By

Precompute Summaries

Previous Navigation Block

PreviousBlock

Property Class

Query All Records

Query Allowed (Block)

Query Array Size

Query Data Source Arguments

Query Data Source Columns

Query Data Source Name

Query Data Source Type

Query_Hits

Query_Options

Record Orientation

Records_To_Fetch

Show Scroll Bar

Single Record

Status (Block)

Top_Record

Transactional Triggers

Update Allowed (Block)

Update Changed Columns Only

Update Procedure Arguments

Update Procedure Name

Update Procedure Result Set Columns

Where Clause/Order By Clause

Window_Handle


Canvas Properties

 All Properties

Bevel

Canvas Type

Comments

Form Horizontal Toolbar Canvas

Form Vertical Toolbar Canvas

Name

Popup Menu

Property Class

Raise on Entry

Size

Tab Attachment Edge

Tab Style

Topmost_Tab_Page

Viewport Height, Viewport Width

Viewport X Position, Viewport Y Position

Viewport X Position on Canvas, Viewport Y Position on Canvas

Visible (Canvas)

Visual Attribute Group

Width/Height

Window

X Position, Y Position


 Chart Properties

 All Properties

Communication Mode (Chart)

Data Source Data Block (Chart)

Execution Mode (Chart)


Editor Properties

 All Properties

Bottom Title (Editor)

Comments

Editor X Position, Editor Y Position

Name

Property Class

Show Horizontal Scroll Bar

Size

Top Title

Width/Height

Wrap Style

X Position, Y Position


Frame Properties

 All Properties

Allow Expansion

Allow Multi-Line Prompts

Allow Start-Attached Prompts

Allow Top-Attached Prompts

Distance Between Records

Frame Alignment

Frame Title

Frame Title Alignment

Frame Title Font Name

Frame Title Font Size

Frame Title Font Spacing

Frame Title Font Style

Frame Title Font Weight

Frame Title Font Foreground Color

Frame Title Offset

Frame Title Reading Order

Frame Title Spacing

Frame Title Visual Attribute Group

Horizontal Object Offset

Layout Style

Maximum Objects Per Line

Number of Records Displayed

Scroll Bar Alignment

Scroll Bar Width

Show Scroll Bar

Shrinkwrap

Single Object Alignment

Start Prompt Alignment

Start Prompt Offset

Top Prompt Alignment

Top Prompt Offset

Update Layout

Vertical Fill

Vertical Margin

Vertical Object Offset


Graphics Properties

 All Properties

Cap Style

Dash Style

Edge Background Color

Edge Foreground Color

Edge Pattern

Graphics Type

Join Style

Line Width

Rotation Angle


Item Properties

 All Properties

About Control

Access Key

Application Instance

Audio Channels

Automatic Skip (Item)

Bevel

Calculation Mode

Canvas

Case Insensitive Query

Case Restriction

Check Box Mapping of Other Values

Column Name

Comments

Compress

Compression_Quality

Conceal Data

Control Help

Control Properties

Copy Value from Item

Current Record Visual Attribute

Data Source X Axis

Data Source Y Axis

Database_Value

Default Button

Display Hint Automatically

Display Quality

Distance Between Records

Editor

Editor X Position, Editor Y Position

Elements in List

Enabled (Item)

Fixed Length (Item)

Format Mask

Formula

Highest Value Allowed

Hint (Item)

Icon Filename

Iconic

Image_Depth

Image_Format

Implementation Class

Initial Value

Initial Keyboard State

Insert Allowed (Item)

Item_Is_Valid

Item_Tab_Page (item)

Item Type

Justification

Keep Cursor Position

Keyboard Navigable

Keyboard State

Label (Item)

List Item Value

List of Values

List Style

List X Position

List Y Position

Lock Record

Lowest Value Allowed

Mapping of Other Values

Maximum Length (Item)

Mouse Navigate

Multi-Line

Name

NextItem

Next Navigation Item

Number of Items Displayed

OLE Activation Style

OLE Class

OLE In-place Activation

OLE Inside-Out Support

OLE Popup Menu Items

OLE Resize Style

OLE Tenant Aspect

OLE Tenant Types

Parameter Data Type

Popup Menu

PreviousItem

Previous Navigation Item

Primary Key (Item)

Property Class

Query Allowed (Item)

Query Length

Query Only

Radio Button Value

Rendered

Required (Item)

Size

Sizing Style

Show Fast Forward Button

Show Horizontal Scroll Bar

Show OLE Popup Menu

Show OLE Tenant Type

Show Palette

Show Play Button

Show Record Button

Show Rewind Button

Show Slider

Show Time Indicator

Show Volume Control

Sound Format

Sound Quality

Summarized Block

Summarized Item

Summary Function

Synchronize with Item

Tab Page

Tooltip

Tooltip Visual Attribute Group

Update Allowed (Item)

Update_Column

Update_Commit

Update Only if NULL

Update_Permission

Validate from List

Value When Checked

Value When Unchecked

VBX Control File

VBX Control Name

VBX Control Value

Visible (Item)

Visual Attribute Group

Width/Height

Window_Handle

Wrap Style

Wrap Text

X Position, Y Position


LOV Properties

 All Properties

Automatic Display

Automatic Refresh

Automatic Select

Automatic Skip (LOV)

Column Mapping Properties

Column Name

Column Specifications

Column Title

Comments

Display Width (LOV)

Filter Before Display

Group_Name

List Type

Name

Property Class

Record Group

Return Item (LOV)

Size

Title

X Position, Y Position


Menu Properties

 All Properties

Associated Menus

Bottom Title

Case Restriction

Checked

Command Text

Command Type

Comments

Display without Privilege

Enabled (Menu Item)

Fixed Length (Menu Substitution Parameter)

Help

Hint (Menu Item)

Hint (Menu Substitution Parameter)

Icon Filename

Icon in Menu

Item Roles

Keyboard Accelerator

Label (Menu Item)

Label (Menu Parameter)

Magic Item

Maximum Length (Menu Substitution Parameter)

Menu Description

Menu Directory

Menu Filename

Menu Item Radio Group

Menu Item Type

Menu Module

Menu Source

Module Roles

Parameter Data Type

Parameter Menu Initial Value

Property Class

Required (Menu Substitution Parameter)

Secure (Menu Substitution Parameter)

Share Library with Form

Startup Code

Tear-off Menu

Title

Use Security

Visible In Horizontal/Vertical Menu Toolbar

Visible in Menu

Visual Attribute Group


Module Properties

 All Properties

Application Instance

Character Cell WD/HT

Comments

Console Window

Coordinate System

Current Record Visual Attribute

Cursor Mode

Defer_Required_Enforcement

File_Name

First_Block

First Navigation Block

Font Spacing

Form Horizontal Toolbar Canvas

Form Vertical Toolbar Canvas

Form_Name

Initial Menu

Last_Block

Menu Module

Menu Role

Menu Source

Menu Style

Module_NLS_Lang

Mouse Navigation Limit

Name

Property Class

Real Unit

Runtime Compatibility Mode

Savepoint Mode

Title

Use 3D Controls

Validation

Validation Unit

Window_Handle


Parameter Properties

 All Properties

Comments

Maximum Length (Form Parameter)

Name

Parameter Data Type

Parameter Initial Value

Property Class


Prompt Properties

 All Properties

Prompt

Prompt Alignment

Prompt Alignment Offset

Prompt Attachment Edge

Prompt Attachment Offset

Prompt Background Color

Prompt Display Style

Prompt Fill Pattern

Prompt Font Name

Prompt Font Size

Prompt Font Spacing

Prompt Font Style

Prompt Font Weight

Prompt Foreground Color

Prompt Justification

Prompt Reading Order

Prompt Visual Attribute Group


Record Properties

 All Properties

Status (Record)


Record Group Properties

 All Properties

Column Name

Column Specifications

Column Value

Comments

Data Type

Delete Record Behavior

Length

Name

Property Class

Record Group Fetch Size

Record Group Query

Record Group Type


Relation Properties

 All Properties

Comments

Coordination

Coordination_Status

Deferred

Detail Block

Join Condition

Name

Next_Detail_Relation

Next_Master_Relation

Prevent Masterless Operation

Property Class


Report Properties

 All Properties

Communication Mode (Report)

Data Source Data Block (Report)

Execution Mode (Report)

Other Reports Parameters

Query Name

Report Destination Format

Report Destination Name

Report Destination Type


Tab Page Properties

 All Properties

Canvas

Enabled (Tab Page)

Label (Tab Page)

Tab Page X Offset

Tab Page Y Offset

Visible (Tab Page)

Visual Attribute Group


Trigger Properties

 All Properties

Comments

Display in Keyboard Help

Execution Style

Fire in Enter-Query Mode

Keyboard Help Description

Name

Property Class

Trigger Style

Trigger Text

Trigger Type


Name Visual Attribute Properties
Named Visual Attribute Properties

 All Properties

Background_Color

Foreground_Color

Name

Property Class

Size

Visible

Visual_Attribute

Visual Attribute Type

White_On_Black

Width/Height


Window Properties

 All Properties

Close Allowed

Comments

Hide on Exit

Horizontal Toolbar Canvas

Icon Filename

Inherit Menu

Maximize Allowed

Minimize Allowed

Minimized Title

Modal

Move Allowed

Name

Primary Canvas

Property Class

Resize Allowed

Show Horizontal Scroll Bar

Show Vertical Scroll Bar

Size

Title

Vertical Toolbar Canvas

Visible

Visual_Attribute

Visual Attribute Group

Window_State

Window Style

X Position, Y Position


Options

 Alphabetic list

Forms Runtime options

Form Compiler options

Form Builder options


Form Builder Preferences
Form Builder Options

 All Options

A

Access (Form Builder)

Add_Triggers (Form Compiler)

Array Processing

B

Batch (Form Compiler)

Block_Menu (Forms Runtime)

Buffer_Records in File

Build (Forms Compiler)

Build Before Running

C

Chart Wizard Welcome Page

Color Mode

Color Palette

Compile_All

CRT_File (Form Compiler)

D

Data Block Wizard Welcome Page

Debug (Forms Runtime)

Debug_Messages (Forms Runtime)

Delete (Form Compiler)

E

Extract (Form Compiler)

F

G

H

Help (Form Builder)

Help (Form Compiler)

Help (Forms Runtime)

HTML File Name

I

Insert (Form Compiler)

Interactive (Forms Runtime)

J

K

Keyin (Forms Runtime)

Keyout (Forms Runtime)

L

Layout Wizard Welcome Page

Logon (Form Compiler)

Logon_Screen (Forms Runtime)

LOV Welcome Page

M

Module_Access (Form Builder)

Module_Access (Form Compiler)

Module_Type (Form Builder)

Module_Type (Form Compiler)

N

Nofail (Form Compiler)

O

Optimize SQL (Forms Runtime)

Optimize Transaction Processing (Forms Runtime)

Output_File (Form Compiler)

Output_File (Forms Runtime)

P

Parse (Form Compiler)

Printer

Q

Query_Only (Forms Runtime)

Quiet Mode (Forms Runtime)

R

Run Modules Asynchronously

S

Save Before Building

Script (Form Compiler)

Statistics (Form Compiler)

Statistics (Forms Runtime)

Strip_Source (Forms Runtime)

Subclassing Path

Suppress Hints

T

Term (Forms Runtime)

U

Upgrade (Form Compiler)

Upgrade_Roles (Form Compiler)

Use System Editor

V

Version (Form Compiler)

W

Welcome Dialog

Wizard Welcome Pages

X

Y

Z


Runform Options
Forms Runtime Options

 All Options

Array

Block_Menu

Buffer_Records

Debug

Debug_Messages

Help

Interactive

Keyin

Keyout

Logon_Screen

OptimizeSQL

OptimizeTP

Options_Screen

Output_File

PECS

Query_Only

Quiet

Statistics

Term

Window_State


Generate Options
Form Compiler Options

 All Options

Add_Triggers

Batch

Build

Compile_All

CRT_File

Debug

Delete

Extract

Help

Insert

Logon

Module_Access

Module_Type

Nofail

Options_Screen

Output_File

Parse

Script

Statistics

Strip_Source

Upgrade

Upgrade_Roles

Version

Widen_Fields


Builder Options
Form Builder Options

 All Options

Color Mode

Color Palette

Generate Before Run

Help

Module_Access

Module_Type

Printer

Run Modules Asynchronously

Save Before Generate

Suppress Hints

Use System Editor

User Preferences


Triggers

 Alphabetic list	  Related Topics

Active X triggers

Block Processing triggers

Interface Event triggers

Key triggers

Master-Detail triggers

Message-Handling triggers

Mouse Event triggers

Navigation triggers

On triggers

Post triggers

Pre triggers

Query-Time triggers

Stored Procedure triggers

Transactional triggers

Validation triggers

When triggers


Form Builder Triggers

 All Triggers

A

B

C

D

Delete-Procedure

E

F

Function Key Triggers

G

H

I

Insert-Procedure

J

K

Key-Fn

Key-Others

L

Lock-Procedure

M

N

O

On-Check-Delete-Master

On-Check-Unique

On-Clear-Details

On-Close

On-Column-Security

On-Commit

On-Count

On-Delete

On-Dispatch-Event

On-Error

On-Fetch

On-Insert

On-Lock

On-Logon

On-Logout

On-Message

On-Populate-Details

On-Rollback

On-Savepoint

On-Select

On-Sequence-Number

On-Update

P

Post-Block

Post-Change

Post-Database-Commit

Post-Delete

Post-Form

Post-Forms-Commit

Post-Insert

Post-Logon

Post-Logout

Post-Query

Post-Record

Post-Select

Post-Text-Item

Post-Update

Pre-Block

Pre-Commit

Pre-Delete

Pre-Form

Pre-Insert

Pre-Logon

Pre-Logout

Pre-Popup-Menu

Pre-Query

Pre-Record

Pre-Select

Pre-Text-Item

Pre-Update

Q

Query-Procedure

R

S

T

U

Update-Procedure

User-Named

V

W

When-Button-Pressed

When-Checkbox-Changed

When-Clear-Block

When-Create-Record

When-Custom-Item-Event

When-Database-Record

When-Form-Navigate

When-Image-Activated

When-Image-Pressed

When-List-Activated

When-List-Changed

When-Mouse-Click

When-Mouse-DoubleClick

When-Mouse-Down

When-Mouse-Enter

When-Mouse-Leave

When-Mouse-Move

When-Mouse-Up

When-New-Block-Instance

When-New-Form-Instance

When-New-Item-Instance

When-New-Record-Instance

When-Radio-Changed

When-Remove-Record

When-Tab-Page-Changed

When-Timer-Expired

When-Validate-Item

When-Validate-Record

When-Window-Activated

When-Window-Closed

When-Window-Deactivated

When-Window-Resized

X

Y

Z


ActiveX Triggers

 All Triggers

On-Dispatch-Event


Block Processing Triggers

 All Triggers

When-Clear-Block

When-Create-Record

When-Database-Record

When-Remove-Record


Interface Event Triggers

 All Triggers

When-Button-Pressed

When-Checkbox-Changed

When-Custom-Item-Event

When-Image-Activated

When-List-Activated

When-List-Changed

When-Mouse-Click

When-Mouse-DoubleClick

When-Mouse-Down

When-Mouse-Enter

When-Mouse-Leave

When-Mouse-Move

When-Mouse-Up

When-Radio-Changed

When-Timer-Expired

When-Window-Activated

When-Window-Closed

When-Window-Deactivated

When-Window-Resized


Key Triggers

 All Triggers

Key-Fn

Key-Others


Master-Detail Triggers

 All Triggers

On-Check-Delete-Master

On-Clear-Details

On-Populate-Details


Message-Handling Triggers

 All Triggers

On-Error

On-Message


Mouse Event Triggers

 All Triggers

When-Custom-Item-Event

When-Mouse-Click

When-Mouse-DoubleClick

When-Mouse-Down

When-Mouse-Enter

When-Mouse-Leave

When-Mouse-Move

When-Mouse-Up


Navigation Triggers

 All Triggers

Post-Block

Post-Form

Post-Record

Post-Text-Item

Pre-Block

Pre-Form

Pre-Record

Pre-Text-Item

User-Named

When-New-Block-Instance

When-New-Form-Instance

When-New-Item-Instance

When-New-Record-Instance


On Triggers

 All Triggers

On-Check-Delete-Master

On-Check-Unique

On-Clear-Details

On-Close

On-Column-Security

On-Commit

On-Count

On-Delete

On-Dispatch-Event

On-Error

On-Fetch

On-Insert

On-Lock

On-Logon

On-Logout

On-Message

On-Populate-Details

On-Rollback

On-Savepoint

On-Select

On-Sequence-Number

On-Update


Post Triggers

 All Triggers

Post-Block

Post-Change

Post-Database-Commit

Post-Delete

Post-Form

Post-Forms-Commit

Post-Insert

Post-Logon

Post-Logout

Post-Query

Post-Record

Post-Select

Post-Text-Item

Post-Update


Pre Triggers

 All Triggers

Pre-Block

Pre-Commit

Pre-Delete

Pre-Form

Pre-Insert

Pre-Logon

Pre-Logout

Pre-Popup-Menu

Pre-Query

Pre-Record

Pre-Select

Pre-Text-Item

Pre-Update


Query-Time Triggers

 All Triggers

Post-Query

Pre-Query


Stored Procedure Triggers

 All Triggers

Delete-Procedure

Insert-Procedure

Lock-Procedure

Query-Procedure

Update-Procedure


Transactional Triggers

 All Triggers

On-Check-Delete-Master

On-Check-Unique

On-Clear-Details

On-Close

On-Column-Security

On-Commit

On-Count

On-Delete

On-Dispatch-Event

On-Error

On-Fetch

On-Insert

On-Lock

On-Logon

On-Logout

On-Message

On-Populate-Details

On-Rollback

On-Savepoint

On-Select

On-Sequence-Number

On-Update

Post-Block

Post-Change

Post-Database-Commit

Post-Delete

Post-Form

Post-Forms-Commit

Post-Insert

Post-Logon

Post-Logout

Post-Query

Post-Record

Post-Select

Post-Text-Item

Post-Update

Pre-Block

Pre-Commit

Pre-Delete

Pre-Form

Pre-Insert

Pre-Logon

Pre-Query

Pre-Select

Pre-Text-Item

Pre-Update


Validation Triggers

 All Triggers

When-Validate-Item

When-Validate-Record


When Triggers

 All Triggers

When-Button-Pressed

When-Checkbox-Changed

When-Clear-Block

When-Create-Record

When-Custom-Item-Event

When-Database-Record

When-Form-Navigate

When-Image-Activated

When-Image-Pressed

When-List-Activated

When-List-Changed

When-Mouse-Click

When-Mouse-DoubleClick

When-Mouse-Down

When-Mouse-Enter

When-Mouse-Leave

When-Mouse-Move

When-Mouse-Up

When-New-Block-Instance

When-New-Form-Instance

When-New-Item-Instance

When-New-Record-Instance

When-Radio-Changed

When-Remove-Record

When-Tab-Page-Changed

When-Timer-Expired

When-Validate-Item

When-Validate-Record

When-Window-Activated

When-Window-Closed

When-Window-Deactivated

When-Window-Resized


About the Type Wizard

The Type Wizard leads you through the steps necessary to create a new Oracle8 user-defined datatype, which may be an object type or a collection type.

An object type is a template that specifies the elements or attributes of a structured data unit. Attributes may be built-in datatypes or other structured data units. An object type also specifies the operations or methods you can perform on the data unit.  Methods are functions or procedures written in PL/SQL and stored in the database, or they could be written in C and stored externally.

A collection type may be a table type or a varying array type. Each collection type describes a data unit that consists of an indefinite number of elements, all of the same datatype.

A table type or nested table is an unordered set of data elements. It has a single column, which may be a built-in datatype or an object type. If an object type, the table can also be viewed as a multi-column table, with a column for each attribute of the object type.

A varying array type or VARRAY is an ordered set of data elements. The number of elements is variable and it refers to the size of the array. You must specify a maximum size when declaring the varying array type.

You can use the Type Wizard to create an object type (with attributes and methods), table type or VARRAY. Specifically, use the Type Wizard to complete the following tasks:

•	specify a name, attributes and methods for an object type

•	specify a name and the datatype information for a table type or VARRAY

•	add, edit or delete attributes of an object type

•	add, edit or delete methods of an object type

•	define restrictions for the methods of an object type

Navigating in the Type Wizard

The following buttons are provided to help you navigate your way through the pages:

•	Cancel-cancel all changes you have made and exit the wizard

•	Help-display online help text for the current page of the wizard

•	Back-navigate to the previous page in the wizard

•	Next-navigate to the next page in the wizard

•	Finish-save changes you have made with the wizard and exit the wizard

Note: If you click Next or Back before you have entered all necessary information for a particular page, the wizard prevents you from navigating to the next (or previous) page. Similarly, if you have not entered all necessary information into the wizard when you click Finish, the wizard automatically places you onto the page where you can finish entering the required data.


Type Wizard: Select Type page

  Next Step	  Related Topics

To select an Oracle8 type to create:

1	On the Select Type page, click a radio button to specify a type you want to create: Object or Collection.

If you select:

•	Object, the Type Wizard enables you to add attributes and methods.

•	Collection, the Type Wizard enables you to specify the kind of collection type and its datatype.

2	Type a name in the Type Name text box.

3	Click Next to display the next Object Type or Collection Type page, depending on your selection.


Type Wizard: Define Object Type Attributes page

  Next Step	  Related Topics

To add an attribute:

  On the Define Object Type Attributes page, click Add.

The Attribute dialog box displays.

To edit an attribute:

  On the Define Object Type Attributes page, select an attribute and click Edit.

Or,

  Double-click an attribute in the list box.

The Attribute dialog box displays.

To remove an attribute:

1	On the Define Object Type Attributes page, select an attribute and click Remove.

A message box displays, prompting you to confirm the deletion.

2	Click Yes to remove the highlighted attribute.

To change the attribute definition order:

  In the list box, click and drag the attribute you wish to move, and drop it at the new position.

Use this to change the order of the parameters of the implicit constructor method for the object type.  (The constructor method creates an instance of the type.)

The parameters of a constructor method are the attributes of the object type; they occur in the same order as the attribute definition order for the type.


The Attribute dialog box

The Attribute dialog box allows you to add a new attribute for an object type or to edit an existing one.

Attribute Name	Type a name for the attribute.
Datatype	Type a built-in datatype in the combo box or choose one from the drop-down list. To browse available object types, click the ... button to display the Type Selection dialog box.
Length	Type a number, or select a number by using the up and down arrows.
Precision	(for numeric datatypes only)  Type a number for the total number of digits.
Scale	(for numeric datatypes only) Type a number to specify the number of digits to the right of the decimal point.


The Type Selection dialog box

The Type Selection dialog box allows you to browse and select existing Oracle8 user-defined datatypes that you have access to in the currently connected database.

Type	Choose Object, Collection, or ALL to display the appropriate datatypes owned by the user name shown in the Owner drop-down list. When defining an object type, you can select another object type or collection type as the datatype for the object. When defining a collection type, you cannot select another collection type as the datatype for the object. The ALL option is disabled when defining a collection type.
Owner	Displays a drop-down list of the owners of the user-defined datatypes that you have access to.  Choose an owner name, or choose ALL to display the datatypes for all owners.
List box	Displays the types and names of the datatypes selected in the Type and Owner fields. Only the datatypes that you have access to are displayed. If ALL is selected in the Owner field, each name in the list is prefixed with the schema name in dotted notation. If ALL is selected in the Type field, each name is appended with its type in parentheses.   Click a datatype name in the list to select it.
Reference to Object	Check this check box to choose an object reference (REF) of the selected (highlighted) object type in the list box. Uncheck this check box to choose an object instance of the selected (highlighted) object type in the list box. Available for object types only.
OK	Selects the highlighted datatype in the list and closes the dialog box.


Type Wizard: Define Object Type Methods page

  Next Step	  Related Topics

Methods are functions and procedures written in PL/SQL and stored in the database, or they could be written in C and stored externally.  Methods characterize the behavior of the object type.

To add a method:

  On the Define Object Type Methods page, click Add.

The Method dialog displays

To edit a method:

  On the Define Object Type Methods page, select a method and click Edit.

Or,

  Double-click a method in the list box.

The Method dialog displays

To remove a method:

1	On the Define Object Type Methods page, select a method and click Remove.

A message box displays, prompting you to confirm the deletion.

2	Click Yes to remove the highlighted method.

To change the restrictions for the methods of an object type:

  On the Define Object Type Methods page, click Change.

The Default Restrictions dialog box displays.


The Default Restrictions dialog box

The Default Restrictions dialog box allows you to specify the default pragma restrictions for the methods of an object type. The pragma restrictions apply to member functions called from SQL statements. The restrictions deny member functions read/write access to database tables, packaged variables, or both.

To specify the default pragma constraints for the methods of an object type:

  Check or uncheck any of the check boxes.

Note: You can declare pragma restrictions for individual member functions. Such pragmas override the default restrictions.


The Method dialog box

The Method dialog box has two pages:  Definition and Restrictions.  The pages allow you to define an object type method and its parameters, and restrictions for the type.

The Definition page enables you to specify a method name and type, and optional parameters. For functions, you can specify a return type. The page consists of the following:

Method Name	Type a name for a method. This name cannot be the same as the object type name or any of the object type attributes.
Method Type	Choose a method type from the drop-down list. The method types are Procedure, Function, Map Function, and Order Function. Map Function and Order Function are comparison methods. You can specify either a map function or an order function for an object type, but not both.
Return Type	For functions, choose a return type from the drop-down list.
Parameter Name	Type a name for a parameter.
Datatype	Choose a built-in datatype from the drop-down list. To browse existing object types, click the ... button to display the Type Selection dialog box.
Direction	Choose IN, OUT or IN/OUT from the drop-down list.
Default Value	Type a default value for the parameter.
	Click to add the parameter to the list. The Parameter Name field is cleared.
	Click to remove the highlighted parameter from the list. A message box displays, prompting for confirmation.
List box	Displays the list of parameters defined for the method. To change the parameter definition order in the list box, click the parameter and drag it to the new position.

The Restrictions page enables you to override the default pragma restrictions already defined for the object type. Pragma restrictions apply to member functions called from SQL statements. The restrictions deny member functions read/write access to database tables, packaged variables, or both. The Restrictions page consists of the following:

Override Default Restrictions	Check this box to use the method restrictions in place of the default restrictions, then specify the constraints by checking or unchecking the options below.  Uncheck this box to use the default pragma restrictions. The options below are disabled when this check box is unchecked.
RNDS, WNDS, RNPS, WNPS	Check the appropriate check box to enforce the rule. Uncheck the appropriate check box to remove the rule.


Type Wizard: Define Collection Type page

  Next Step	  Related Topics

To define a collection type:

1	On the Define Collection Type page, click a radio button to specify a type you want to create: Table or Varying Array (VARRAY).

2	If you are creating a VARRAY, type the maximum size of the array in the Limit text box.

3	In the Datatype drop-down list, click the arrow on the right to choose a built-in datatype. To select an existing object type, click the ... button to display the Type Selection dialog box.

4	(if enabled) In the Length box, type a number.

5	(for numeric datatypes only) In the Precision box, type a number for the total number of digits.

6	(for numeric datatypes only) In the Scale box, type a number to specify the number of digits to the right of the decimal point.


Type Wizard: Finish page

  Related Topics

The last page of the Type Wizard displays the SQL statement that will generate the Oracle8 type you have just defined.  This page is read only; you cannot edit the SQL statement.

When you click Finish, the Type Wizard does the following:

•	For collection types-issues the CREATE TYPE AS TABLE or CREATE TYPE AS VARYING ARRAY SQL statement to the database.

•	For object types-issues the CREATE TYPE AS OBJECT SQL statement to the database. If the type specification is invalid or incomplete, an asterisk (*) appears after the Object Type label in the Object Navigator.

•	For object types with methods-creates an initial object body and displays it in the Stored Program Unit editor. Fill in the methods and click Save. The CREATE TYPE BODY SQL statement is issued to the database. If the object body is invalid,  error messages appear in the Compilation Messages pane. An asterisk (*) appears after the Object Body label in the Object Navigator.

Note: The Type Wizard stores the object type or collection type in the currently connected Oracle8 database server.


About the Type Wizard

  Related Topics

The Type Wizard is the quickest and easiest way to create an Oracle8 user-defined datatype. It leads you through the steps necessary to create a new object type or a collection type, which may be a table type or a varying array type (VARRAY).  You cannot use the Type Wizard to edit an existing type.

Specifically, use the Type Wizard to complete the following tasks:

•	specify a name, attributes and methods for an object type

•	specify a name and the datatype information for a table type or VARRAY

•	add, edit or delete attributes of an object type

•	add, edit or delete methods of an object type

•	define restrictions for the methods of an object type


Creating an Oracle8 user-defined datatype with the Type Wizard

  Related Topics

You must be connected to an Oracle8 database server to create a new Oracle8 datatype.

To create a new Oracle8 user-defined datatype:

1	In the Object Navigator, expand the Database Objects node.

2	Expand the schema node where you want to create a new datatype.

3	Click the Types node under the schema.

4	Click [image] in the Navigator toolbar or choose Navigator [image] Create from the menu to display the Type Wizard.

5	Follow the steps to create an object type or a collection type. Refer to the Type Wizard help for additional guidance.

The Type Wizard creates and stores the object type or collection type in the Oracle8 database server that is currently connected.


Editing an Oracle8 user-defined datatype

  Related Topics

Use the Stored Program Unit editor to modify existing object types and collection types.

You can edit the type specification of object types and collection types.  The specification declares the attributes of the data structure.  In the case of object types, the specification also specifies the optional methods that manipulate the data.

You can also edit the body of object types, which fully defines the methods and implements the specification.  You can debug or replace the body without changing the type specification.

To edit the type specification of an object type or a collection type:

  In the Object Navigator, double-click a type icon to display the type specification in the Stored Program Unit editor.

Or,

  From the pop-up menu on a type in the Object Navigator (right-click in Windows), click Edit Type to display the type specification in the Stored Program Unit editor.

Or,

  In the Stored Program Unit editor's Name drop-down list, click a type name to display the source.

Note:  The attributes and default restrictions of an object type are part of the type specification.

To edit the methods of an object type:

  From the pop-up menu on an object type in the Object Navigator (right-click in Windows), click Edit Body to display the object body (methods) in the Stored Program Unit editor.

Or,

  In the Stored Program Unit editor's Name drop-down list, click an object type name to display the source.


Deleting an Oracle8 user-defined datatype

  Related Topics

A message box displays prompting you for confirmation when you delete a user-defined datatype.

To delete a user-defined datatype:

 In the Object Navigator, click an object type, table type or varying array type, then choose Navigator [image] Delete from the menu or click [image] in the toolbar.

Or,

 Choose a type name from the Name drop-down list in the Stored Program Unit editor, then click Drop to delete the type.

Note:  You cannot delete a type that is referenced in another datatype, nested object or REF object. The references must be dropped before you can delete the type definition.


About Oracle8 user-defined datatypes

  Related Topics

Oracle8 is an object-relational database management system, which means you can define additional kinds of data-specifying both the data and the ways of operating on it-and use these types within the relational model.

There are two categories of user-defined datatypes: object types and collection types.  User-defined datatypes use the built-in datatypes (such as CHAR, VARCHAR2, and NUMBER) and other user-defined datatypes as the building blocks for datatypes that model the structure and behavior of data in applications.

An object type serves as a template for objects. An object type specifies the elements (or attributes) that make up a structured data unit like a purchase order.  Some attributes, such as the list of line items, may be other structured data units.  An object type also specifies the operations (or methods) you can perform on the data unit, such as determining the total value of a purchase order.

Collection types describe data units that are made up of an indefinite number of elements, all of the same datatype.  The collection types are varying array types and table types.

A varying array type specifies a data unit called VARRAY, which is an ordered set of data elements all of the same datatype.  The number of elements in a VARRAY (or its size) is variable.  However, you must specify a maximum size when you declare the varying array type.

A table type specifies a data unit called a nested table, which is an unordered set of data elements all of the same datatype.  A nested table has a single column, and the type of that column is a built-in type or an object type.


Built-ins overview

  Related Topics	 All Built-ins

Form Builder provides built-in subprograms that you can call from triggers and user-named subprograms that you write yourself. Built-ins provide programmatic control over standard application functions, including navigation, interface control, and transaction processing.

This section includes information on the following:

•	Built-in syntax

•	Built-in named parameters

•	Built-in code examples

•	Built-in object IDs

•	Restricted built-in subprograms

•	Built-in constants


Built-in syntax

 All Built-ins

Named parameters are shown in an italic monospaced font.  You can replace any named parameter with the actual parameter, which can be a constant, a literal, a bind variable, or a number.

SET_TIMER(timer_name, milliseconds, iterate);

In this example, the timer name you supply must be enclosed in single quotes, because the timer_name is a CHAR value.  The milliseconds parameter is passed as a number and, as such, does not require single quotes.  The iterate parameter is passed as a constant, and, as such, must be entered exactly as shown in the parameter description, without single quotes.  Capitalization is unimportant.

In those cases where a number of optional elements are available, various alternate syntax statements are presented.  These alternatives are presented to preclude having to decipher various complicated syntactical conventions.

Note that you sometimes use variables instead of including a specific object name.  In those cases, do not enclose the variable within  single quotes.  The following example illustrates a When-Timer-Expired trigger that calls the SET_TIMER built-in and references a variable that contains a valid timer name:

DECLARE
   the_timer  CHAR := GET_APPLICATION_PROPERTY(TIMER_NAME);
BEGIN
   SET_TIMER(the_timer, 60000, REPEAT);
END;


Built-in named parameters

 All Built-ins

The named parameter should be followed with the equal/greater than signs (=>), which point to the actual parameter that follows the named parameter.  For example, if you intend to change the milliseconds in the SET_TIMER Built-in you can directly use that parameter with the following syntax:

SET_TIMER(timer_name => 'my_timer', milliseconds => 12000,
                 iterate => NO_REPEAT);

Also, you can continue to call the built-in with the following syntax:

SET_TIMER('my_timer', 12000, NO_REPEAT);


Built-in code examples

Examples have been included for the built-in subprograms.  Some examples are simple illustrations of the syntax.  Others are more complex illustrations of how to use the Built-in either alone or in conjunction with other built-ins.  A few points to keep in mind regarding the syntax of examples:

•	Examples are shown exactly as they can be entered.

•	Casing and use of italics can be ignored and is included for readability.

•	Built-in names and other PL/SQL reserved words, such as IF, THEN, ELSE, BEGIN, and END are shown in capital letters for easier readability.

•	Named parameters, when illustrated, are shown in an italic typeface.  If you choose to use named parameters, enter these parameter names exactly as shown, without quotes and follow them with the equal/greater than symbols (=>).

•	CHAR type arguments must be enclosed in single quotes.

•	Any other data type argument should not be enclosed in quotes.

•	Special characters other than single quotes ('), commas (,), parentheses, underscores (_), and semicolons(;) should be ignored.


Built-in object IDs

 All Built-ins

Some built-in subprograms accept object IDs as actual parameters. An object ID is an internal, opaque handle that is assigned to each object when created in the Form Builder.  Object IDs are internally managed and cannot be externally viewed by the user.  The only method you can use to retrieve the ID is to define a local or global variable and assign the return value of the object to the variable.

You make the assignment by way of the FIND_ built-in functions.  Once you have used FIND_ within a PL/SQL block, you can use the variable as an object ID while still in that block.  The valid PL/SQL type for each object is included in the syntax descriptions for each parameter. The description for the FIND_BLOCK built-in provides an example of how to obtain an object ID.


Built-in form coordinate units

 All Built-ins

Many built-in subprograms allow you to specify size and position coordinates, using properties such as:

•	HEIGHT

•	WIDTH

•	DISPLAY_POSITION

•	VIEWPORT_X_POS

•	VIEWPORT_Y_POS

•	VIEW_SIZE

•	VIEWPORT_X_POS_ON_CANVAS

•	VIEWPORT_Y_POS_ON_CANVAS

When you specify coordinates or width and height, you express these measurements in units of the current form coordinate system, set on the Form Module property sheet.  The form coordinate system defines the units for specifying size and position coordinates of objects in the Form Builder.  Use the Coordinate System form module property to set the form's coordinate units:

•	character cells or

•	real units:

•	inches

•	centimeters

•	pixels

•	points

When you design in the character cell coordinate system, all object dimensions and position coordinates are expressed in character cells, so Form Builder accepts only whole numbers for size and position properties.

When you design using real units (inches, centimeters, or points),  all object dimensions and position coordinates are expressed in the units you specify, so Form Builder will accept decimals as well as whole numbers for size and position properties. The precision of real units is three digits, so you can specify coordinates to thousandths. If you use pixels or character cells, coordinates are truncated to whole numbers.


Built-in uppercase return values

 All Built-ins

The GET_X_PROPERTY built-ins, such as GET_FORM_PROPERTY, return CHAR arguments as uppercase values. This will affect the way you compare results in IF statements.


Restricted built-in subprograms

 All Built-ins

Restricted built-ins affect navigation in your form, either external screen navigation, or internal navigation.  You can call these built-ins only from triggers while no internal navigation is occurring.

Restricted built-ins cannot be called from the Pre and Post triggers, which fire when Form Builder is navigating from object to another.

Restricted built-ins can be called from the When triggers that are specific to interface items, such as When-Button-Pressed or When-Checkbox-Changed.  Restricted built-ins can also be called from any of the When-New-"object"-Instance triggers and from key triggers.

Unrestricted built-ins do not affect logical or physical navigation and can be called from any trigger.

The built-in descriptions include a heading, Built-In Type, that indicates if the built-in is restricted or unrestricted.


Built-in constants

 All Built-ins

Many of the built-in subprograms take numeric values as arguments.  Often, constants have been defined for these numeric arguments.  A constant is a named numeric value.  When passing a constant to a built-in do not enclose the constant value in quotation marks.

Constants can only appear on the right side of an operator in an expression.

In some cases, a built-in can take a number of possible constants as arguments.  Possible constants are listed in the descriptions for each parameter.

In the following example, BLOCK_SCOPE is a constant that can be supplied for the parameter constant VALIDATION_UNIT.  Other constants listed in the description are FORM, RECORD, and ITEM.

SET_FORM_PROPERTY('my_form', VALIDATION_UNIT, BLOCK_SCOPE);


Individual built-in descriptions

 Examples	 Restrictions	 All Built-ins

The remainder of this chapter presents individual built-in descriptions.  Each built-in is presented in the following format or a subset of the format, as applicable:

Syntax

Describes the syntax of the built-in.  If there are multiple formats for a Built-in then all formats are shown.  For example, if the target object of a built-in can be called by name or by object ID, then both forms of syntax are displayed

Built-in Type  Indicates whether the built-in is restricted or unrestricted

Returns  Indicates the return value or data type of a built-in function

Enter Query Mode  Indicates the capability to call the built-in during enter query mode.

Description

Indicates the general purpose and use of the built-in.

Parameters

Describes the parameters that are included in the syntax diagrams. Underlined parameters usually are the default.


Individual built-in descriptions restrictions

Indicates any restrictions.


Individual built-in descriptions examples

Provides an actual example that can be used in conjunction with the syntax to develop a realistic call to the built-in.


ABORT_QUERY built-in

 Restrictions	 All Built-ins

Description

Closes a query that is open in the current block.

A query is open between the time the SELECT statement is issued and the time when all the rows have been fetched from the database.  In particular, a query is not open when the form is in Enter Query mode, because the SELECT statement has not yet been issued.

Syntax

PROCEDURE ABORT_QUERY;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

A query is open between the time the SELECT statement is issued and the time when all the rows have been fetched from the database.  In particular, a query is not open when the form is in Enter Query mode, because the SELECT statement has not yet been issued.

Parameters

none

Usage Notes

ABORT_QUERY is not the equivalent of the Query, Cancel runtime default menu command.  It does not prevent the initial fetch from the database, but rather interrupts fetch processing, thus preventing subsequent fetches.


ABORT_QUERY restrictions

Do not use ABORT_QUERY in the following triggers:

•	On-Fetch.  The On-Fetch trigger is provided for applications using transactional triggers  to replace default Form Builder functions when running against non-Oracle data sources.  To signal that your On-Fetch trigger is done fetching rows, exit the On-Fetch trigger without issuing the CREATE_QUERIED_RECORD built-in.

•	Pre-Query.  The Pre-Query trigger fires before the query is open, so there is no open query to close and ABORT_QUERY is ignored. To programmatically cancel Enter Query mode, call the built-in EXIT_FORM, using a When-New-Record-Instance trigger to check a flag as follows:

IF (:global.cancel_query = 'Y'
      and :system.mode = 'ENTER-QUERY')
THEN
     Exit_Form;
     :global.cancel_query = 'N';
END IF;

•	Then set the flag to 'TRUE' either from a Pre-Query trigger or an On-Error trigger that traps for the FRM-40301 error.


ACTIVATE_SERVER

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

Activates an OLE server associated with an OLE container and prepares the OLE server to receive OLE automation events from the OLE container.

Syntax

PROCEDURE ACTIVATE_SERVER
  (item_id  Item);

PROCEDURE ACTIVATE_SERVER
  (item_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  no

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is Item.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.

Usage Notes

•	The OLE container must contain an OLE object and the OLE Server must be available for activation.


ACTIVATE_SERVER restrictions

Valid only on Microsoft Windows and Macintosh.


ACTIVATE_SERVER examples

/*
** Built-in: ACTIVATE_SERVER
** Example:  Activates the OLE server associated with the object
**           in the OLE container.
** Trigger:  When-Button-Pressed
*/
DECLARE
 item_id  ITEM;
 item_name VARCHAR(25) := 'OLEITM';
BEGIN
 item_id := Find_Item(item_name);
 IF Id_Null(item_id) THEN
  message('No such item: '||item_name);
 ELSE
  Forms_OLE.Activate_Server(item_id);
 END IF;
END;


ADD_GROUP_COLUMN built-in

 Examples	 Restrictions	 All Built-ins

Description

Adds a column of the specified type to the given record group.

Syntax

FUNCTION ADD_GROUP_COLUMN
  (recordgroup_id    RecordGroup,
   groupcolumn_name  VARCHAR2,
   column_type       NUMBER);

FUNCTION ADD_GROUP_COLUMN
  (recordgroup_name  VARCHAR2,
   groupcolumn_name  VARCHAR2,
   column_type       NUMBER);
FUNCTION ADD_GROUP_COLUMN
  (recordgroup_id,   RecordGroup
   groupcolumn_name  VARCHAR2,
   column_type       NUMBER,
   column_width      NUMBER);
FUNCTION ADD_GROUP_COLUMN
  (recordgroup_name  VARCHAR2,
   groupcolumn_name  VARCHAR2,
   column_type       NUMBER,
   column_width      NUMBER);

Built-in Type  unrestricted function

Enter Query Mode  yes

Returns  GroupColumn

Parameters

recordgroup_id	The unique ID that Form Builder assigns when it creates the group.  The data type of the ID is RecordGroup.

recordgroup_name	The name you gave to the record group when creating it.  The data type of the name is VARCHAR2.

groupcolumn_name	Specifies the name of the column.  The data type of the column name is VARCHAR2.

column_type	Specifies the data type of the column.  The allowable values are the following constants:

CHAR_COLUMN  Specify if the column can only accept VARCHAR2 data.

DATE_COLUMN  Specify if the column can only accept DATE data.

LONG_COLUMN  Specify if the column can only accept LONG data.

NUMBER_COLUMN  Specify if the column can only accept NUMBER data.

column_width	If you specify CHAR_COLUMN as the column_type, you must indicate the maximum length of the data.  COLUMN_WIDTH cannot exceed 2000, and must be passed as a whole number.

Error Conditions:

An error is returned under the following conditions:

•	You enter the name of a non-existent record group.

•	You specify the name for a group or a column that does not adhere to standard Oracle naming conventions.

•	You enter a column type other than CHAR, NUMBER, DATE, or LONG.


ADD_GROUP_COLUMN restrictions

•	You must add columns to a group before adding rows.

•	You cannot add a column to a group that already has rows; instead, delete the rows with DELETE_GROUP_ROW, then add the column.

•	You can only add columns to a group after it is created with a call to CREATE_GROUP.

•	If the column corresponds to a database column, the width of CHAR_COLUMN-typed columns cannot be less than the width of the corresponding database column.

•	If the column corresponds to a database column, the width of CHAR_COLUMN-typed columns can be greater than the width of the corresponding database column.

•	Only columns of type CHAR_COLUMN require the width parameter.

•	Performance is affected if a record group has a large number of columns.

•	There can only be one LONG column per record group.


ADD_GROUP_COLUMN examples

/*

** Built-in:  ADD_GROUP_COLUMN
** Example:   Add one Number and one Char column to a new
**            record group.
*/
PROCEDURE Create_My_Group IS
  rg_name VARCHAR2(15) := 'My_Group';
  rg_id   RecordGroup;
  gc_id   GroupColumn;
BEGIN
  /*
  ** Check to see if Record Group already exists
  */
  rg_id := Find_Group( rg_name );
  /*
  ** If Not, then create it with one number column and one           ** Char column
  */
  IF Id_Null(rg_id) THEN
    rg_id := Create_Group( rg_name );
    gc_id := Add_Group_Column(rg_id, 'NumCol',NUMBER_COLUMN);
    gc_id := Add_Group_Column(rg_id, 'CharCol',CHAR_COLUMN,15);
  END IF;
END;


ADD_GROUP_ROW built-in

 Examples	 Restrictions	 All Built-ins

Description

Adds a row to the given record group.

Syntax

PROCEDURE ADD_GROUP_ROW
  (recordgroup_id  RecordGroup,
   row_number      NUMBER);

PROCEDURE ADD_GROUP_ROW
  (recordgroup_name  VARCHAR2,
   row_number        NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

recordgroup_id	The unique ID that Form Builder assigns when it creates the group.  The data type of the ID is RecordGroup.

recordgroup_name	The name you gave to the record group when creating it.  The data type of the name is VARCHAR2.

row_number	A whole number that specifies a row in the group.  If you add a row to any but the last position in a group, all rows below that are logically renumbered.  To add a row to the end of a group, use the END_OF_GROUP constant.

Error Conditions:

Form Builder returns a runtime error given either of the following conditions:

•	If you enter the name of a non-existent record group.

•	If you supply a row number that is out of range or is invalid (for example, an alphabetic character).


ADD_GROUP_ROW restrictions

•	A group can consist of 0 or more rows.

•	You can add rows to a group only after it has been created and columns have been added.

•	If you specify a row number greater than the number of rows already in the group (or a negative number), the row is inserted at the end of the group.

•	You cannot add rows to a static group without a query.


ADD_GROUP_ROW examples

/*

** Built-in:  ADD_GROUP_ROW
** Example:   Add ten rows to a new record group and populate.
*/
PROCEDURE Populate_My_Group IS
  rg_name  VARCHAR2(20) := 'My_Group';
  rg_col1  VARCHAR2(20) := rg_name||'.NumCol';
  rg_col2  VARCHAR2(20) := rg_name||'.CharCol';
  rg_id    RecordGroup;
  gc_id    GroupColumn;
  in_words VARCHAR2(15);
BEGIN
  /*
  ** Check to see if Record Group already exists
  */
  rg_id := Find_Group( rg_name );
  /*
  ** If it does, then clear all the rows from the group and
  ** populate ten rows with the numbers from 1..10 along
  ** with the equivalent number in words.
  **
  **    Row#    NumCol    CharCol
  **    ----    ------    -------
  **      1        1        one
  **      2        2        two
  **      :        :         :
  **     10       10        ten
  */
  IF NOT Id_Null(rg_id) THEN
    Delete_Group_Row( rg_id, ALL_ROWS );
    FOR i IN 1..10 LOOP
      /*
      ** Add the i-th Row to the end (bottom) of the
      ** record group, and set the values of the two cells
      */
      in_words := TO_CHAR(TO_DATE(i,'YYYY'),'year');
      Add_Group_Row( rg_id, END_OF_GROUP );
      Set_Group_Number_Cell( rg_col1, i, i);
      Set_Group_Char_Cell( rg_col2, i, in_words);
    END LOOP;
  END IF;
END;


ADD_LIST_ELEMENT built-in

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

Adds a single element to a list item.

Syntax

PROCEDURE ADD_LIST_ELEMENT
  (list_name   VARCHAR2,
   list_index, NUMBER
   list_label  VARCHAR2,
   list_value  NUMBER);

PROCEDURE ADD_LIST_ELEMENT
  (list_id     ITEM,
   list_index  VARCHAR2,
   list_label  VARCHAR2,
   list_value  NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

list_id	Specifies the unique ID that Form Builder assigns when it creates the list item.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

list_name	The name you gave to the list item when you created it.  The data type of the name is VARCHAR2.

list_index	Specifies the list index value.  The list index is 1 based.

list_label	Specifies the VARCHAR2 string that you want displayed as the label of the list element.

list_value	The actual list element value you intend to add to the list item.


ADD_LIST_ELEMENT restrictions

For a base table list with the List Style property set to Poplist or T-list, Form Builder does not allow you to add another values element when the block contains queried or changed records.  Doing so causes an error.  This situation can occur if you have previously used DELETE_LIST_ELEMENT or CLEAR_LIST to remove the other values element that was specified at design time by the Mapping of Other Values list item property setting.

Note:  The block status is QUERY when a block contains queried records.  The block status is CHANGED when a block contains records that have been either inserted or updated.


ADD_LIST_ELEMENT examples

/*

**  Built-in:  ADD_LIST_ELEMENT
**  Example:  Deletes index value 1 and adds the value "1994" to
**            the list item called years when a button is pressed.
**  Trigger:  When-Button-Pressed
*/
BEGIN
   Delete_List_Element('years',1);
   Add_List_Element('years', 1, '1994', '1994');
END;


ADD-OLEARGS
ADD_OLEARGS

 All Built-ins

Description

Establishes the type and value of an argument that will be passed to the OLE object's method.

Syntax

PROCEDURE ADD_OLEARG
  (newvar NUMBER, vtype VT_TYPE := VT_R8);

...or...

PROCEDURE ADD_OLEARG
  (newvar VARCHAR2, vtype VT_TYPE := VT_BSTR);

...or...

PROCEDURE ADD_OLEARG
  (newvar OLEVAR, vtype VT_TYPE := VT_VARIANT);

Built-in Type  unrestricted procedure

Parameters

newvar	The value of this argument.  Its type (NUMBER, VARCHAR2, or OLEVAR) is its FORMS or PL/SQL data type.
vtype	The type of the argument as understood by the OLE method For a NUMBER argument, the default is VT_TYPE := VT_R8. For a VARCHAR2 argument, the default is VT_TYPE := VT_BSTR. For an OLEVAR argument, the default is VT_TYPE := VT_VARIANT.
Usage Notes

A separate ADD_OLEARG call is needed for each argument to be passed. The calls should be in order, starting with the first argument.

A list of the supported OLE VT_TYPEs can be found in OLE Variant Types .


ADD_PARAMETER built-in

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

Adds parameters to a parameter list.  Each parameter consists of a key, its type, and an associated value.

Syntax

PROCEDURE ADD_PARAMETER
  (list       VARCHAR2,
   key        VARCHAR2,
   paramtype  VARCHAR2,
   value      VARCHAR2);

PROCEDURE ADD_PARAMETER
  (name       VARCHAR2,
   key        VARCHAR2,
   paramtype  VARCHAR2,
   value      VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

list or name	Specifies the parameter list to which the parameter is assigned.  The actual parameter can be either a parameter list ID of type PARAMLIST, or the VARCHAR2 name of the parameter list.

key	The name of the parameter.  The data type of the key is VARCHAR2.

paramtype	Specifies one of the following two types:

TEXT_PARAMETER  A VARCHAR2 string literal.

DATA_PARAMETER  A VARCHAR2 string specifying the name of a record group defined in the current form.  When Form Builder passes a data parameter to Report Builder or Graphics Builder, the data in the specified record group can substitute for a query that Report Builder or Graphics Builder would ordinarily execute to run the report or display.

value	The actual value you intend to pass to the called module.  If you are passing a text parameter, the maximum length is 64K characters.  Data type of the value is VARCHAR2.


ADD_PARAMETER restrictions

•	A parameter list can consist of 0 (zero) or more parameters.

•	You cannot create a parameter list if one already exists; to do so will cause an error.  To avoid this error,  use ID_NULL to check to see if a parameter list already exists before creating one.  If a parameter list already exists, delete it with DESTROY_PARAMETER_LIST before creating a new list.

•	You cannot add a parameter of type DATA_PARAMETER if the parameter list is being passed to another form.


ADD_PARAMETER examples

/*

** Built-in:  ADD_PARAMETER
** Example:   Add a value parameter to an existing Parameter
**            List 'TEMPDATA', then add a data parameter to
**            the list to associate named query 'DEPT_QUERY'
**            with record group 'DEPT_RECORDGROUP'.
*/
DECLARE
  pl_id ParamList;
BEGIN
  pl_id := Get_Parameter_List('tempdata');
  IF NOT Id_Null(pl_id) THEN
    Add_Parameter(pl_id,'number_of_copies',TEXT_PARAMETER,'19');

    Add_Parameter(pl_id, 'dept_query', DATA_PARAMETER,
         'dept_recordgroup');
  END IF;
END;


ADD_TREE_DATA built-in

 Examples 	 All Built-ins

Description

Adds a data set under the specified node of a hierarchical tree item.

Syntax

PROCEDURE ADD_TREE_DATA

  (item_id ITEM,

   node FTREE.NODE,

   offset_type NUMBER,

   offset NUMBER,

   data_source NUMBER,

   data VARCHAR2);

PROCEDURE ADD_TREE_DATA

  (item_name VARCHAR2,

   node FTREE.NODE,

   offset_type NUMBER,

   offset NUMBER,

   data_source NUMBER,

   data VARCHAR2);

PROCEDURE ADD_TREE_DATA

  (item_name VARCHAR2,

   node FTREE.NODE,

   offset_type NUMBER,

   offset NUMBER,

   data_source NUMBER,

   data RECORDGROUP);

PROCEDURE ADD_TREE_DATA

  (item_id ITEM,

   node FTREE.NODE,

   offset_type NUMBER,

   offset NUMBER,

   data_source NUMBER,

   data RECORDGROUP);

Built-in Type   unrestricted procedure

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
node	Specifies a valid node.
offset_type	Specifies the type of offset for the node. Possible values are: PARENT_OFFSET SIBLING_OFFSET If offset_type is PARENT_OFFSET, adds a data subset immediately under the specified node at the location among its children indicated by offset. If offset_type is SIBLING_OFFSET, adds the new data as a sibling to the specified node.
offset	Indicates the position of the new node. If offset_type is PARENT_OFFSET,  then offset can be either 1-n or LAST_CHILD. If offset_type is SIBLING_OFFSET, then offset can be either NEXT_NODE or PREVIOUS_NODE.
data_source	Indicates the type of data source. Possible values are: RECORD_GROUP QUERY_TEXT
data	Specifies the data to be added. If data source is QUERY_TEXT, then data is the text of the query. If data source is RECORD_GROUP, then data is an item of type RECORDGROUP or the name of a record group.


ADD_TREE_DATA examples

/*

** Built-in:  ADD_TREE_DATA
*/

-- This code copies a set of values from a record group

-- and adds them as a top level node with any children

-- nodes specified by the structure of the record group.

-- The new top level node will be inserted as the last

-- top level node.

DECLARE

   htree         ITEM;

   rg_data       RECORDGROUP;

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Find the record group.

   rg_data := FIND_GROUP('new_data_rg');

   -- Add the new node at the top level and children.

   Ftree.Add_Tree_Data(htree,

                       Ftree.ROOT_NODE,

                       Ftree.PARENT_OFFSET,

                       Ftree.LAST_CHILD,

                       Ftree.RECORD_GROUP,

                       rg_data);

END;


ADD_TREE_NODE built-in

 Examples 	 All Built-ins

Description

Adds a data element to a hierarchical tree item.

Syntax

FUNCTION ADD_TREE_NODE

  (item_name VARCHAR2,

   node FTREE.NODE,

   offset_type NUMBER,

   offset NUMBER,

   state NUMBER,

   label VARCHAR2,

   icon VARCHAR2,

   value VARCHAR2);

FUNCTION ADD_TREE_NODE

  (item_id ITEM,

   node FTREE.NODE,

   offset_type NUMBER,

   offset NUMBER,

   state NUMBER,

   label VARCHAR2,

   icon VARCHAR2,

   value VARCHAR2);

Built-in Type   unrestricted procedure

Returns  NODE

Enter Query Mode  no

Parameters

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.
node	Specifies a valid node.
offset_type	Specifies the type of offset for the node. Possible values are: PARENT_OFFSET SIBLING_OFFSET
offset	Indicates the position of the new node. If offset_type is PARENT_OFFSET,  then offset can be either 1-n or LAST_CHILD. If offset_type is SIBLING_OFFSET, then offset can be either NEXT_NODE or PREVIOUS_NODE.
state	Specifies the state of the node. Possible vaues are: COLLAPSED_NODE EXPANDED_NODE LEAF_NODE
label	The displayed text for the node.
icon	The filename for the node’s icon.
value	Specifies the VARCHAR2 value of the node.


ADD_TREE_NODE examples

/*

** Built-in:  ADD_TREE_NODE
*/

-- This code copies a value from a Form item and

-- adds it to the tree as a top level node.  The

-- value is set to be the same as the label.

DECLARE

   htree         ITEM;

   top_node      FTREE.NODE;

   new_node      FTREE.NODE;

   item_value    VARCHAR2(30);

BEGIN

   -- Find the tree itself.

   htree := Find_Item('tree_block.htree3');

   -- Copy the item value to a local variable.

   item_value := :wizard_block.new_node_data;

   -- Add an expanded top level node to the tree

   -- with no icon.

   new_node := Ftree.Add_Tree_Node(htree,

                                   Ftree.ROOT_NODE,

                                   Ftree.PARENT_OFFSET,

                                   Ftree.LAST_CHILD,

                                   Ftree.EXPANDED_NODE,

                                   item_value,

                                   NULL,

                                   item_value);

END;


APPLICATION_PARAMETER built-in

  Related Topics	 All Built-ins

Description

Displays all the parameters associated with the current menu, and their current values, in the Enter Parameter Values dialog box.

Syntax

PROCEDURE APPLICATION_PARAMETER;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Failure:

If no parameters are defined for the current menu, Form Builder issues  error message FRM-10201: No parameters needed.


BELL built-in

 Examples	 All Built-ins

Description

Sets the terminal bell to ring the next time the terminal screen synchronizes with the internal state of the form.  This synchronization can occur as the result of internal processing or as the result of a call to the SYNCHRONIZE built-in subprogram.

Syntax

PROCEDURE BELL;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


BELL examples

The following example rings the bell three times:

FOR i in 1..3 LOOP
  BELL;
  SYNCHRONIZE;
END LOOP;


BLOCK_MENU built-in

 Examples	 All Built-ins

Description

Displays a list of values (LOV) containing the sequence number and names of valid blocks in your form.  Form Builder sets the input focus to the first enterable item in the block you select from the LOV.

Syntax

PROCEDURE BLOCK_MENU;

Built-in Type   restricted procedure

Enter Query Mode  yes; however, it is illegal to navigate out of the current block in Enter Query mode

Parameters

none


BLOCK_MENU examples

/*

** Built-in:  BLOCK_MENU
** Example:   Calls up the list of blocks in the form when the
**            user clicks a button, and prints a message if
**            the user chooses a new block out of the list to
**            which to navigate.
*/
DECLARE
  prev_blk  VARCHAR2(40) := :System.Cursor_Block;
BEGIN
  BLOCK_MENU;
  IF :System.Cursor_Block <> prev_blk THEN
    Message('You successfully navigated to a new block!');
  END IF;
END;


BREAK built-in

 Examples	   Restrictions	 All Built-ins

Description

Halts form execution and displays the Debugger, while the current form is running in debug mode.  From the Debugger you can make selections to view the values of global and system variables.  The BREAK built-in is primarily useful when you need to inspect the state of a form during trigger execution.

Syntax

PROCEDURE BREAK;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


BREAK restrictions

If the current form is not running in debug mode, issuing a call to the BREAK built-in subprogram has no effect.


BREAK examples

/*

** Built-in:  BREAK
** Example:   Brings up the debugging window for a particular
**            value of the 'JOB' item anytime the user
**            changes records.
** Trigger:   When-New-Record-Instance
*/
BEGIN
  IF :Emp.Job = 'CLERK' THEN
    Break;
    Call_Form('clerk_timesheet');
    Break;
  END IF;
END;


CALL_FORM built-in

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

Runs an indicated form while keeping the parent form active.  Form Builder runs the called form with the same Runform preferences as the parent form.  When the called form is exited Form Builder processing resumes in the calling form at the point from which you initiated the call to CALL_FORM.

Syntax

PROCEDURE CALL_FORM
  (formmodule_name  VARCHAR2);

PROCEDURE CALL_FORM
  (formmodule_name  VARCHAR2,
   display          NUMBER);
PROCEDURE CALL_FORM
  (formmodule_name  VARCHAR2,
   display          NUMBER,
   switch_menu      NUMBER);
PROCEDURE CALL_FORM
  (formmodule_name  VARCHAR2,
   display          NUMBER,
   switch_menu      NUMBER,
   query_mode       NUMBER);
PROCEDURE CALL_FORM
  (formmodule_name  VARCHAR2,
   display          NUMBER,
   switch_menu      NUMBER,
   query_mode       NUMBER,
   data_mode        NUMBER);
PROCEDURE CALL_FORM
  (formmodule_name  VARCHAR2,
   display          NUMBER,
   switch_menu      NUMBER,
   query_mode       NUMBER,
   paramlist_id     PARAMLIST);
PROCEDURE CALL_FORM
  (formmodule_name  VARCHAR2,
   display          NUMBER,
   switch_menu      NUMBER,
   query_mode       NUMBER,
   paramlist_name   VARCHAR2);
PROCEDURE CALL_FORM
  (formmodule_name  VARCHAR2,
   display          NUMBER,
   switch_menu      NUMBER,
   query_mode       NUMBER,
   data_mode        NUMBER,
   paramlist_id     PARAMLIST);
PROCEDURE CALL_FORM
  (formmodule_name  VARCHAR2,
   display          NUMBER,
   switch_menu      NUMBER,
   query_mode       NUMBER,
   data_mode        NUMBER,
   paramlist_name   VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

formmodule_name	The name of the called form (must be enclosed in single quotes).  Datatype is VARCHAR2.

display	HIDE  (The default.)  Form Builder will hide the calling form before drawing the called form.

NO_HIDE  Form Builder will display the called form without hiding the calling form.

switch_menu	NO_REPLACE  (The default.)  Form Builder will keep the default menu module of the calling form active for the called form.

DO_REPLACE  Form Builder will replace the default menu module of the calling form with the default menu module of the called form.

query_mode	NO_QUERY_ONLY  (The default.)  Form Builder will run the indicated form in normal mode, allowing the end user to perform inserts, updates, and deletes from within the called form.

QUERY_ONLY  Form Builder will run the indicated form in query-only mode, allowing the end user to query, but not to insert, update, or delete records.

data_mode	NO_SHARE_LIBRARY_DATA  (The default.)  At runtime, Form Builder will not share data between forms that have identical libraries attached (at design time).

SHARE_LIBRARY_DATA  At runtime, Form Builder will share data between forms that have identical libraries attached (at design time).

paramlist_id	The unique ID Form Builder assigns when it creates the parameter list.  You can optionally include a parameter list as initial input to the called form.  Datatype is PARAMLIST.

paramlist_name	The name you gave the parameter list object when you defined it.  Datatype is VARCHAR2.


CALL_FORM restrictions

•	Form Builder ignores the query_mode parameter when the calling form is running in QUERY_ONLY mode.  Form Builder runs any form that is called from a QUERY_ONLY form as a QUERY_ONLY form, even if the CALL_FORM syntax specifies that the called form is to run in NO_QUERY_ONLY (normal) mode.

•	A parameter list passed to a form via CALL_FORM cannot contain parameters of type DATA_PARAMETER.  Only text parameters can be passed with CALL_FORM.

•	Some memory allocated for CALL_FORM is not deallocated until the Runform session ends.  Exercise caution when creating a large stack of called forms.

•	When you execute CALL_FORM in a Pre-Logon, On-Logon, or Post-Logon trigger, always specify the DO_REPLACE parameter to replace the calling form's menu with the called form's menu.  Failing to specify DO_REPLACE will result in no menu being displayed for the called form.  (An alternative solution is to call the REPLACE_MENU built-in from a When-New-Form-Instance trigger in the called form.)


CALL_FORM examples

/* Example 1:

** Call a form in query-only mode.
*/
BEGIN
  CALL_FORM('empbrowser', no_hide, no_replace, query_only);
END;

/* Example 2:
** Call a form, pass a parameter list (if it exists)
*/
DECLARE
  pl_id        PARAMLIST;
  theformname  VARCHAR2(20);
BEGIN
  theformname := 'addcust';

  /* Try to lookup the 'TEMPDATA' parameter list */
  pl_id := GET_PARAMETER_LIST('tempdata');
  IF ID_NULL(pl_id) THEN
    CALL_FORM(theformname);
  ELSE
    CALL_FORM(theformname,
              hide,
              no_replace,
              no_query_only,
              pl_id);
  END IF;

  CALL_FORM('lookcust', no_hide, do_replace, query_only);
END;


CALL_INPUT built-in

 Restrictions	 All Built-ins

Description

Accepts and processes function key input from the end user.  When CALL_INPUT is terminated, Form Builder  resumes processing from the point at which the call to CALL_INPUT occurred.

Syntax

PROCEDURE CALL_INPUT;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


CALL_INPUT restrictions

CALL_INPUT is included for compatibility with previous versions.  You should not include this built-in in new applications.


CALL_OLE

 All Built-ins

Description

Passes control to the identified OLE object's method.

Syntax

PROCEDURE CALL_OLE

  (obj OLEOBJ, memberid PLS_INTEGER);

Built-in Type  unrestricted procedure

Parameters

obj	Name of the OLE object.
memberid	Member ID of the method to be run.
Usage Notes

•	Before this call is issued, the number, type, and value of the arguments must have been established, using the INIT_OLEARGS and ADD_OLEARGS procedures.

•	As a procedure call, no values are returned.  To obtain a return value from the method, use one of the  function versions of this call (CALL_OLE_CHAR, _NUM, _OBJ, or _VAR).

•	The method can raise a FORM_OLE_FAILURE exception.  If so, you can use the function LAST_OLE_EXCEPTION to obtain more information.


CALL_OLE_returntype
CALL_OLE_<returntype>

 All Built-ins

Description

Passes control to the identified OLE object's method.  Receives a return value of the specified type.

There are four versions of the function (denoted by the value in returntype), one for each of the argument types CHAR, NUM, OBJ, and VAR.

Syntax

FUNCTION CALL_OLE_CHAR
  (obj OLEOBJ, memberid PLS_INTEGER)
RETURN returnval VARCHAR2;

...or...

FUNCTION CALL_OLE_NUM
  (obj OLEOBJ, memberid PLS_INTEGER)
RETURN returnval NUMBER;

...or...

FUNCTION CALL_OLE_OBJ
  (obj OLEOBJ, memberid PLS_INTEGER)
RETURN returnval OLEOBJ;

...or...

FUNCTION CALL_OLE_VAR
  (obj OLEOBJ, memberid PLS_INTEGER)
RETURN returnval OLEVAR;

Built-in Type  unrestricted function

Returns  the method's return value in the specified format

Parameters

obj	Name of the OLE object.
memberid	Member ID of the object's method.
Usage Notes

•	Before this call is issued, the number, type, and value of the arguments must have been established, using the INIT-OLEARGS and ADD-OLEARGS procedures.

•	The method can raise a FORM_OLE_FAILURE exception.  If so, you can use the function LAST_OLE_EXCEPTION to obtain more information.


CANCEL_REPORT_OBJECT built-in

 All Built-ins

Description

Cancels a long-running, asynchronous report. You should verify the report is canceled by checking the status of the report using REPORT_OBJECT_STATUS .

Syntax

PROCEDURE CANCEL_REPORT_OBJECT
  (report_id VARCHAR2
);

Built-in Type  unrestricted procedure

Enter Query Mode yes

Parameters

report_id	The VARCHAR2 value returned by the RUN_REPORT_OBJECT built-in. This value uniquely identifies the report that is currently running either locally or on a remote report server.

Usage Notes

•	CANCEL_REPORT_OBJECT is useful only when a report is run asynchronously. You cannot cancel an report that is run synchronously.


CHECKBOX_CHECKED built-in

 Examples	 Restrictions	 All Built-ins

Description

A call to the CHECKBOX_CHECKED function returns a BOOLEAN value indicating the state of the given check box.  If the item is not a check box, Form Builder returns the following error:

FRM-41038:  Item <item_name> is not a check box.

Syntax

FUNCTION CHECKBOX_CHECKED
  (item_id  ITEM);

FUNCTION CHECKBOX_CHECKED
  (item_name  VARCHAR2);

Built-in Type  unrestricted function

Returns  BOOLEAN

Enter Query Mode  yes

A call to GET_ITEM_PROPERTY(item_name, ITEM_TYPE) can be used to verify the item type before calling CHECKBOX_CHECKED.

To set the value of a check box programmatically, assign a valid value to the check box using standard bind variable syntax.

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when it creates it. The data type of the ID is ITEM.

item_name	Specifies the string you defined as the name of the item at design time.  The data type of the name is VARCHAR2.


CHECKBOX_CHECKED restrictions

The CHECKBOX_CHECKED built-in returns a BOOLEAN value regarding the state of the given check box.  It does not return the actual value of the check box nor does it return the value you might have indicated for the Mapping of Other Values property.


CHECKBOX_CHECKED examples

/*

** Built-in:  CHECKBOX_CHECKED
** Example:   Sets the query case-sensitivity of the item
**            whose name is passed as an argument, depending
**            on an indicator checkbox item.
*/
PROCEDURE Set_Case_Sensitivity( it_name VARCHAR2) IS
  indicator_name VARCHAR2(80) := 'control.case_indicator';
  it_id          Item;
BEGIN
  it_id := Find_Item(it_name);

  IF Checkbox_Checked(indicator_name) THEN
    /*
    ** Set the item whose name was passed in to query case-
    ** sensitively (i.e., Case Insensitive is False)
    */
    Set_Item_Property(it_id, CASE_INSENSITIVE_QUERY,
                      PROPERTY_FALSE );
ELSE
    /*
    ** Set the item whose name was passed in to query case-
    ** insensitively (ie Case Insensitive True)
    */
    Set_Item_Property(it_id,CASE_INSENSITIVE_QUERY,PROPERTY_TRUE);
  END IF;
END;


CHECK_RECORD_UNIQUENESS built-in

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

When called from an On-Check-Unique trigger, initiates the default Form Builder processing for checking the primary key uniqueness of a record.

This built-in is included primarily for applications that will run against a non-ORACLE data source.

Syntax

PROCEDURE CHECK_RECORD_UNIQUENESS;

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

none


CHECK_RECORD_UNIQUENESS restrictions

Valid only in an On-Check-Unique trigger.


CHECK_RECORD_UNIQUENESS examples

/*

** Built-in:  CHECK_RECORD_UNIQUENESS
** Example:   Perform Form Builder record uniqueness checking
**            from the fields in the block that are marked as
**            primary keys based on a global flag setup at
**            startup by the form, perhaps based on a
**            parameter.
** Trigger:  On-Check-Unique
*/
BEGIN
  /*
  ** Check the global flag we set during form startup
  */
  IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
    User_Exit('chkuniq block=EMP');
  /*
  ** Otherwise, do the right thing.
  */
  ELSE
    Check_Record_Uniqueness;
  END IF;
END;


CLEAR_BLOCK built-in

 Examples	  Related Topics	 All Built-ins

Description

Causes Form Builder to remove all records from, or "flush," the current block.

Syntax

PROCEDURE CLEAR_BLOCK;

PROCEDURE CLEAR_BLOCK
  (commit_mode  NUMBER);

Built-in Type  restricted procedure

Enter Query Mode  no

Parameters

If the end user has made changes to records in the current block that have not been posted or committed, Form Builder processes the records, following the directions indicated by the argument supplied for the commit_mode parameter:

commit_mode	The optional action parameter takes the following possible constants as arguments:

ASK_COMMIT  Form Builder prompts the end user to commit the changes during CLEAR_BLOCK processing.

DO_COMMIT  Form Builder validates the changes, performs a commit, and flushes the current block without prompting the end user.

NO_COMMIT  Form Builder validates the changes and flushes the current block without performing a commit or prompting the end user.

NO_VALIDATE  Form Builder flushes the current block without validating the changes, committing the changes, or prompting the end user.


CLEAR_BLOCK examples

/*

** Built-in:  CLEAR_BLOCK
** Example:   Clears the current block without validation, and
**            deposits the primary key value which the user
**            has typed into a global variable which a
**            Pre-Query trigger will use to include it as a
**            query criterion.
** Trigger:   When-New-Item-Instance
*/
BEGIN
  IF :Emp.Empno IS NOT NULL THEN
    :Global.Employee_Id := :Emp.Empno;
    Clear_Block(No_Validate);
  END IF;
END;
/*
** Trigger:  Pre-Query
*/
BEGIN
  Default_Value(NULL, 'Global.Employee_Id');
  IF :Global.Employee_Id IS NOT NULL THEN
    :Emp.Empno := :Global.Employee_Id;
  END IF;
END;


CLEAR_EOL built-in

 Examples	 All Built-ins

Description

Clears the current text item's value from the current cursor position to the end of the line.

Syntax

PROCEDURE CLEAR_EOL;

Built-in Type   restricted procedure

Enter Query Mode  yes


CLEAR_EOL examples

/*

** Built-in:  CLEAR_EOL
** Example:   Clears out the contents of any number field when
**            the end user navigates to it.
** Trigger:   When-New-Item-Instance
*/
BEGIN
  IF Get_Item_Property(:System.Trigger_Item, DATATYPE) = 'NUMBER' THEN
      Clear_Eol;
  END IF;
END;


CLEAR_FORM built-in

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

Causes Form Builder to remove all records from, or flush, the current form, and puts the input focus in the first item of the first block.

Syntax

POROCEDURE CLEAR_FORM;

PROCEDURE CLEAR_FORM
  (commit_mode  NUMBER);
PROCEDURE CLEAR_FORM
  (commit_mode    NUMBER,
   rollback_mode  NUMBER);

Built-in Type  restricted procedure

Enter Query Mode  no

Parameters

If the end user has made changes to records in the current form or any called form, and those records have not been posted or committed, Form Builder processes the records, following the directions indicated by the argument supplied for the following parameter:

commit_mode	ASK_COMMIT  Form Builder prompts the end user to commit the changes during CLEAR_FORM processing.

DO_COMMIT  Form Builder validates the changes, performs a commit, and flushes the current form without prompting the end user.

NO_COMMIT  Form Builder validates the changes and flushes the current form without performing a commit or prompting the end user.

NO_VALIDATE  Form Builder flushes the current form without validating the changes, committing the changes, or prompting the end user.

rollback_mode	TO_SAVEPOINT  Form Builder rolls back all uncommitted changes (including posted changes) to the current form's savepoint.

FULL_ROLLBACK  Form Builder rolls back all uncommitted changes (including posted changes) which were made during the current Runform session.  You cannot specify a FULL_ROLLBACK from a form that is running in post-only mode.  (Post-only mode can occur when your form issues a call to another form while unposted records exist in the calling form.  To prevent losing the locks issued by the calling form, Form Builder prevents any commit processing in the called form.)


CLEAR_FORM restrictions

If you use a PL/SQL ROLLBACK statement in an anonymous block or a user-defined subprogram, Form Builder interprets that statement as a CLEAR_FORM built-in subprogram with no parameters.


CLEAR_FORM examples

/*

** Built-in:  CLEAR_FORM
** Example:   Clear any changes made in the current form,
**            without prompting to commit.
*/
BEGIN
  Clear_Form(No_Validate);
END;


CLEAR_ITEM built-in

 Examples	 All Built-ins

Description

Clears the value from the current text item, regardless of the current cursor position, and changes the text item value to NULL.

Syntax

PROCEDURE CLEAR_ITEM;

Built-in Type   restricted procedure

Enter Query Mode  yes


CLEAR_ITEM examples

/*

** Built-in:  CLEAR_ITEM
** Example:   Clear the current item if it does not represent
**            the first day of a month.
** Trigger:   When-New-Item-Instance
*/
BEGIN
  IF TO_CHAR(:Emp.Hiredate,'DD') <> '01' THEN
    Clear_Item;
    Message('This date must be of the form 01-MON-YY');
  END IF;
END;


CLEAR_LIST built-in

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

Clears all elements from a list item.  After Form Builder clears the list, the list will contain only one element (the null element), regardless of the item's Required property.

Syntax

PROCEDURE CLEAR_LIST
  (list_id  ITEM);

PROCEDURE CLEAR_LIST
  (list_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

list_id	Specifies the unique ID that Form Builder assigns when it creates the list item.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is ITEM.

list_name	The name you gave to the list item when you created it.  The data type of the name is VARCHAR2.

Usage Notes

•	Do not use the CLEAR_LIST built-in if the Mapping of Other Values property is defined and there are queried records in the block.  Doing so may cause Form Builder to be unable to display records that have already been fetched.

For example, assume that a list item contains the values A, B, and C and the Mapping of Other Values property is defined.  Assume also that these values have been fetched from the database (a query is open).  At this point, if you clear the list with CLEAR_LIST, an error will occur because Form Builder will attempt to display the previously fetched values (A, B, and C), but will be unable to because the list was cleared.

Before clearing a list, close any open queries.  Use the ABORT_QUERY built-in to close an open query.

Note:  The block status is QUERY when a block contains queried records.  The block status is CHANGED when a block contains records that have been either inserted or updated (queried records have been modified).


CLEAR_LIST restrictions

•	For a Poplist or T-list-style list item, CLEAR_LIST will not clear the default value element or the other values element from the list if they do not meet the criteria specified for deleting these elements with DELETE_LIST_ELEMENT.

When either the default value or other values element cannot be deleted, CLEAR_LIST leaves these elements in the list and clears all other elements. Refer to the restrictions on DELETE_LIST_ELEMENT for more information.


CLEAR_LIST examples

/*

**  Built-in:  CLEAR_LIST
**  Example:   See POPULATE_LIST
*/


CLEAR_MESSAGE built-in

 Examples	 All Built-ins

Description

Removes the current message from the screen message area.

Syntax

PROCEDURE CLEAR_MESSAGE;

Built-in Type   restricted procedure

Enter Query Mode  yes


CLEAR_MESSAGE examples

/*

** Built-in:  CLEAR_MESSAGE
** Example:   Clear the message from the message line.
*/
BEGIN
  Message('Working...',No_Acknowledge);
  SELECT current_tax
    INTO :Emp.Tax_Rate
    FROM tax_table
   WHERE state_abbrev = :Emp.State;
  Clear_Message;
END;


CLEAR_RECORD built-in

 Examples	  Related Topics	 All Built-ins

Description

Causes Form Builder to remove, or flush, the current record from the block, without performing validation.  If a query is open in the block, Form Builder fetches the next record to refill the block, if the record space is no longer filled after removing the current record.

A database record that has been cleared is not processed as a delete by the next Post and Commit Transactions process.

In a default master-detail block relation, clearing the master record causes all corresponding detail records to be cleared without validation.

Syntax

PROCEDURE CLEAR_RECORD;

Built-in Type   restricted procedure

Enter Query Mode  yes


CLEAR_RECORD examples

/*

** Built-in:  CLEAR_RECORD
** Example:   Clear the current record if it's not the last
**            record in the block.
*/
BEGIN
  IF :System.Last_Record = 'TRUE' AND :System.Cursor_Record = '1' THEN
    Message('You cannot clear the only remaining entry.');
    Bell;
  ELSE
    Clear_Record;
  END IF;
END;


CLOSE_FORM built-in

 Restrictions	  Related Topics	 All Built-ins

Description

In a multiple-form application, closes the indicated form. When the indicated form is the current form, CLOSE_FORM is equivalent to EXIT_FORM.

Syntax

PROCEDURE CLOSE_FORM
  (form_name  VARCHAR2);

PROCEDURE CLOSE_FORM
  (form_id  FORMMODULE);

Built-in Type  restricted procedure

Enter Query Mode  no

Parameters

form_name	Specifies the name of the form to close as a VARCHAR2.

form_id	The unique ID that is assigned to the form dynamically when it is instantiated at runtime. Use the FIND_FORM built-in to an appropriately typed variable. The data type of the form ID is FORMMODULE.


CLOSE_FORM restrictions

•	You cannot close a form that is currently disabled as a result of having issued CALL_FORM to invoke a modal called form.

•	You cannot close a form that has called you.  For example, if Form_A calls Form_B, then Form_B cannot close Form_A.


CLOSE_SERVER

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

Deactivates the OLE server associated with an OLE container.  Terminates the connection between an OLE server and the OLE container.

Syntax

PROCEDURE CLOSE_SERVER
  (item_id  Item);

PROCEDURE CLOSE_SERVER
  (item_name  VARCHAR2);

Built-in Type  unrestricted procedure

Enter Query Mode  no

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when created.  Use the FIND_ITEM built-in to return the ID to an appropriately typed variable.  The data type of the ID is Item.

item_name	Specifies the name of the object created at design time.  The data type of the name is VARCHAR2 string.


CLOSE_SERVER restrictions

Valid only on Microsoft Windows and Macintosh.


CLOSE_SERVER examples

/*

** Built-in: CLOSE_SERVER
** Example:  Deactivates the OLE server associated with the object
**           in the OLE container.
** Trigger:  When-Button-Pressed
*/
DECLARE
 item_id  ITEM;
 item_name VARCHAR(25) := 'OLEITM';
BEGIN
 item_id := Find_Item(item_name);
 IF Id_Null(item_id) THEN
  message('No such item: '||item_name);
 ELSE
  Forms_OLE.Close_Server(item_id);
 END IF;
END;


COMMIT_FORM built-in

 Examples	 Restrictions	 All Built-ins

Description

Causes Form Builder to update data in the database to match data in the form.  Form Builder first validates the form, then, for each block in the form, deletes, inserts, and updates to the database, and performs a database commit.  As a result of the database commit, the database releases all row and table locks.

If the end user has posted data to the database during the current Runform session, a call to the COMMIT_FORM built-in commits this data to the database.

Following a commit operation, Form Builder treats all records in all base-table blocks as if they are queried records from the database.  Form Builder does not recognize changes that occur in triggers that fire during commit processing.

Syntax

PROCEDURE COMMIT_FORM;

Built-in Type   restricted procedure

Enter Query Mode  no


COMMIT_FORM restrictions

If you use a PL/SQL COMMIT statement in an anonymous block or a form-level procedure, Form Builder interprets that statement as a call to the COMMIT_FORM built-in.


COMMIT_FORM examples

Example 1

/*

** Built-in:  COMMIT_FORM
** Example:   If there are records in the form to be
**            committed, then do so. Raise an error if the
**            commit was not successful.
*/
BEGIN
  /*
  ** Force validation to happen first
  */
  Enter;
  IF NOT Form_Success THEN
    RAISE Form_Trigger_Failure;
  END IF;
  /*
  ** Commit if anything is changed
  */
  IF :System.Form_Status = 'CHANGED' THEN
    Commit_Form;
    /*
    ** A successful commit operation sets Form_Status back
    ** to 'QUERY'.
    */
    IF :System.Form_Status <> 'QUERY' THEN
      Message('An error prevented your changes from being
               committed.');
      Bell;
      RAISE Form_Trigger_Failure;
    END IF;
  END IF;
END;

Example 2

/*

** Built-in:  COMMIT_FORM
** Example:   Perform Form Builder database commit during commit
**            processing. Decide whether to use this Built-in
**            or a user exit based on a global flag setup at
**            startup by the form, perhaps based on a
**
** Trigger:   On-Commit
*/
BEGIN
  /*
  ** Check the global flag we set during form startup
  */
  IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
    User_Exit('my_commit');
  /*
  ** Otherwise, do the right thing.
  */
  ELSE
    Commit_Form;
  END IF;
END;


CONVERT_OTHER_VALUE built-in

 Examples	 Restrictions	 All Built-ins

Description

Converts the current value of a check box, radio group, or list item to the value associated with the current check box state (Checked/Unchecked), or with the current radio group button or list item element.

Syntax

PROCEDURE CONVERT_OTHER_VALUE
  (item_id  ITEM);

PROCEDURE CONVERT_OTHER_VALUE
  (item_name  VARCHAR2);

Built-in Type  restricted procedure

Enter Query Mode  yes

Parameters

item_id	Specifies the unique ID that Form Builder assigns to the item when it creates the item.  The data type of the ID is ITEM.

item_name	Specifies the VARCHAR2 string you defined as the name of the item at design time.


CONVERT_OTHER_VALUE restrictions

If the item is not a check box, radio group, or list item, Form Builder returns error FRM-41026:  Item does not understand operation. To avoid this error, determine the item type by issuing a call to GET_ITEM_PROPERTY(item_name, ITEM_TYPE) before calling CONVERT_OTHER_VALUE.


CONVERT_OTHER_VALUE examples

/*

** Built-in:  CONVERT_OTHER_VALUE
** Example:   Ensure that a particular checkbox's value
**            represents either the checked or unchecked
**            value before updating the record.
** Trigger:   Pre-Update
*/
BEGIN
  Convert_Other_Value('Emp.Marital_Status');
END;


COPY built-in

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

Copies a value from one item or variable into another item or global variable.  Use specifically to write a value into an item that is referenced through the NAME_IN built-in.  COPY exists for two reasons:

•	You cannot use standard PL/SQL syntax to set a referenced item equal to a value.

•	You might intend to programmatically place characters such as relational operators in NUMBER and DATE fields while a form is in Enter Query mode.

Syntax

PROCEDURE COPY
  (source       VARCHAR2,
   destination  VARCHAR2);

Built-in Type   unrestricted procedure

Enter Query Mode  yes

Parameters

source	The source is a literal value.

destination	The destination can be either a text item or another global variable.

Usage Notes

•	When using COPY with date values, the format defined in the BUILTIN_DATE_FORMAT property will be used if the DATE_FORMAT_COMPATIBILITY_MODE property is set to 5.0.  If this property is set to 4.5 COPY will  expect date strings to be formatted using the default American format.

•	To use a text item as the source reference, you can use the following code:

COPY(NAME_IN(source), destination);


COPY restrictions

No validation is performed on a value copied to a text item.  However, for all other types of items, standard validation checks are performed on the copied value.


COPY examples

Example 1

/*

** Built-in:  COPY
** Example:   Force a wildcard search on the EmpNo item during
**            query.
** Trigger:   Pre-Query
*/
DECLARE
  cur_val VARCHAR2(40);
BEGIN
  /*
  ** Get the value of EMP.EMPNO as a string
  */
  cur_val := Name_In('Emp.Empno');
  /*
  ** Add a percent to the end of the string.
  */
  cur_val := cur_val || '%';
  /*
  ** Copy the new value back into the item so Form Builder
  ** will use it as a query criterion.
  */
  Copy( cur_val, 'Emp.Empno' );
END;

Example 2

/*

** Built-in:  COPY
** Example:   Set the value of a global variable whose name is
**            dynamically constructed.
*/
DECLARE
  global_var_name  VARCHAR2(80);
BEGIN
  IF :Selection.Choice = 5 THEN
    global_var_name := 'Storage_1';
  ELSE
    global_var_name := 'Storage_2';
  END IF;
  /*
  ** Use the name in the 'global_var_name' variable as the
  ** name of the global variable in which to copy the
  ** current 'Yes' value.
  */
  COPY( 'Yes', 'GLOBAL.'||global_var_name );
END;


COPY_REGION built-in

  Related Topics	 All Built-ins

Description

Copies the selected region of a text item or image item from the screen and stores it in the paste buffer until you cut or copy another selected region.

Syntax

PROCEDURE COPY_REGION;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none

Usage Notes

Use COPY_REGION, as well as the other editing functions, on text and image items only.  The cut and copy functions transfer the selected region into the system clipboard until you indicate the paste target.  At that time, the cut or copied content is pasted onto the target location.


COPY_REPORT_OBJECT_OUTPUT built-in

 Examples	 All Built-ins

Description

Copies the output of a report to a file.

Syntax

PROCEDURE COPY_REPORT_OBJECT_OUTPUT
  (report_id VARCHAR2(20),
   output_file VARCHAR2
);

Built-in Type  unrestricted procedure

Enter Query Mode yes

Parameters

report_id	The VARCHAR2 value returned by the RUN_REPORT_OBJECT built-in. This value uniquely identifies the report that is currently running either locally or on a remote report server.

output_file	The name of the file where the report output will be copied.

Usage Notes

•	Use the Report Destination Type property to specify the format of the output file.

•	To copy the output of a report from a remote machine, you must set the Report Destination Type property  to Cache.


COPY_REPORT_OBJECT_OUTPUT examples

DECLARE

repid REPORT_OBJECT;

v_rep  VARCHAR2(100);

rep_status varchar2(20);

BEGIN

repid := find_report_object('report4');

v_rep := RUN_REPORT_OBJECT(repid);

rep_status := report_object_status(v_rep);

if rep_status = 'FINISHED' then

message('Report Completed');

copy_report_object_output(v_rep,'d:\temp\local.pdf');

host('netscape d:\temp\local.pdf');

else

message('Error when running report.');

end if;

END;


COUNT_QUERY built-in

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

In an On-Count trigger, performs the default Form Builder processing for identifying the number of rows that a query will retrieve for the current block, and clears the current block.  If there are changes to commit in the block, Form Builder prompts the end user to commit them during COUNT_QUERY processing.  Form Builder returns the following message as a result of a valid call to COUNT_QUERY:

FRM-40355:  Query will retrieve <number> records.

This built-in is included primarily for applications that will run against a non-ORACLE data source.

Syntax

PROCEDURE COUNT_QUERY;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none


COUNT_QUERY restrictions

Valid only in triggers that allow restricted built-ins.


COUNT_QUERY examples

Example 1

/*

** Built-in:  COUNT_QUERY
** Example:   Display the number of records that will be retrieved
**            by the current query.
*/
BEGIN
  Count_Query;
END;

Example 2

/*

** Built-in:  COUNT_QUERY
** Example:   Perform Form Builder count query hits processing.
**            Decide whether to use this Built-in or a user
**            exit based on a global flag setup at startup by
**            the form, perhaps based on a parameter.
** Trigger:   On-Count
*/
BEGIN
  /*
  ** Check the global flag we set during form startup
  */
  IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
    /*
    ** User exit returns query hits count back into the
    ** CONTROL.HITS item.
    */
    User_Exit('my_count');
    /*
    ** Deposit the number of query hits in the appropriate
    ** block property so Form Builder can display its normal
    ** status message.
    */
    Set_Block_Property(:System.Trigger_Block,QUERY_HITS,
                     :control.hits);
  /*
  ** Otherwise, do the right thing.
  */
  ELSE
    Count_Query;
  END IF;
END;


CREATE_GROUP built-in

 Examples	 All Built-ins

Description

Creates a non-query record group with the given name.  The new record group has no columns and no rows until you explicitly add them using the ADD_GROUP_COLUMN, the ADD_GROUP_ROW, and the POPULATE_GROUP_WITH_QUERY built-ins.

Syntax

FUNCTION CREATE_GROUP
  (recordgroup_name  VARCHAR2,
   scope             NUMBER,
   array_fetch_size  NUMBER);

Built-in Type  unrestricted function

Returns  RecordGroup

Enter Query Mode  yes

Parameters

recordgroup_name	The string you defined as the name of the record group at design time.  When Form Builder creates the record group object it also assigns the object a unique ID of type RecordGroup.  You can call the record group by name or by ID in later calls to record group or record group column built-in subprograms.

scope	Specifies whether tlhe record group can be used only within the current form or within every form in a multi-form application.  Takes the following constants as arguments:

	FORM_SCOPE  Indicates that the record group can by used only within the current form.  This is the default value.
	GLOBAL_SCOPE  Indicates that the record group is global, and that it can be used within all forms in the application.  Once created, a global record group persists for the remainder of the runtime session.
array_fetch_size	Specifies the array fetch size.  The default array size is 20.


CREATE_GROUP examples

/*

** Built-in: CREATE_GROUP
** Example:  Creates a record group and populates its values
**           from a query.
*/
DECLARE
  rg_name  VARCHAR2(40) := 'Salary_Range';
  rg_id    RecordGroup;
  gc_id    GroupColumn;
  errcode  NUMBER;
BEGIN
  /*
  ** Make sure the record group does not already exist.
  */
  rg_id := Find_Group(rg_name);
  /*
  ** If it does not exist, create it and add the two
  ** necessary columns to it.
  */
  IF Id_Null(rg_id) THEN
    rg_id := Create_Group(rg_name);
    /* Add two number columns to the record group */
    gc_id := Add_Group_Column(rg_id, 'Base_Sal_Range',
                              NUMBER_COLUMN);
    gc_id := Add_Group_Column(rg_id, 'Emps_In_Range',
                              NUMBER_COLUMN);
  END IF;
  /*
  ** Populate group with a query
  */
  errcode := Populate_Group_With_Query( rg_id,
                  'SELECT SAL-MOD(SAL,1000),COUNT(EMPNO) '
                ||'FROM EMP '
                ||'GROUP BY SAL-MOD(SAL,1000) '
                ||'ORDER BY 1');
END;


CREATE_GROUP_FROM_QUERY built-in

 Examples	 Restrictions	 All Built-ins

Description

Creates a record group with the given name.  The record group has columns representing each column you include in the select list of the query.  Add rows to the record group with the POPULATE_GROUP built-in.

Note:  If you do not pass a formal column name or alias for a column in the SELECT statement, Form Builder creates ICRGGQ with a dummy counter <NUM>.   This happens whenever the column name would have been invalid. The first dummy name-counter always takes the number one. For example, the query SELECT 1 + 1 FROM DUAL would result in a column named ICRGGQ_1.

Syntax

FUNCTION CREATE_GROUP_FROM_QUERY
  (recordgroup_name  VARCHAR2,
   query             VARCHAR2,
   scope             NUMBER,
   array_fetch_size  NUMBER);

Built-in Type  unrestricted function

Returns  RecordGroup

Enter Query Mode  yes

Parameters

recordgroup_name	The name of the record group.  When Form Builder creates the record group object it also assigns the object a unique ID of type RecordGroup.

query	A valid SQL SELECT statement, enclosed in single quotes.  Any columns retrieved as a result of the query take the data types of the columns in the table.  If you restrict the query to a subset of the columns in the table, then Form Builder creates only those columns in the record group

scope	Specifies whether tlhe record group can be used only within the current form or within every form in a multi-form application.  Takes the following constants as arguments:

	FORM_SCOPE Indicates that the record group can by used only within the current form.  This is the default value.
	GLOBAL_SCOPE  Indicates that the record group is global, and that it can be used within all forms in the application.  Once created, a global record group persists for the remainder of the runtime session.
array_fetch_size	Specifies the array fetch size.  The default array size is 20.


CREATE_GROUP_FROM_QUERY restrictions

•	If a global record group is created from (or populated with) a query while executing form A, and the query string contains bind variable references which are local to A (:block.item or :PARAMETER.param), when form A terminates execution, the global query record group is converted to a global non-query record group (it retains the data, but a subsequent call to POPULATE_GROUP is considered an error).


CREATE_GROUP_FROM_QUERY examples

/*

** Built-in:  CREATE_GROUP_FROM_QUERY
** Example:   Create a record group from a query, and populate it.
*/
DECLARE
  rg_name  VARCHAR2(40) := 'Salary_Range';
  rg_id    RecordGroup;
  errcode  NUMBER;
BEGIN
  /*
  ** Make sure group doesn't already exist
  */
  rg_id := Find_Group( rg_name );
  /*
  ** If it does not exist, create it and add the two
  ** necessary columns to it.
  */
  IF Id_Null(rg_id) THEN
    rg_id := Create_Group_From_Query( rg_name,
                'SELECT SAL-MOD(SAL,1000) BASE_SAL_RANGE,'
               ||'COUNT(EMPNO) EMPS_IN_RANGE '
               ||'FROM EMP '
               ||'GROUP BY SAL-MOD(SAL,1000) '
               ||'ORDER BY 1');
  END IF;
  /*
  ** Populate the record group
  */
  errcode := Populate_Group( rg_id );
END;


CREATE_OLEOBJ

  Related Topics 	 All Built-ins

Description

In its first form, creates an OLE object, and establishes the object's persistence.  In its second form, alters the persistence of a previously-instantiated OLE object.

Syntax

FUNCTION CREATE_OLEOBJ
  (name OLEOBJ, persistence_boolean := TRUE)
RETURN objpointer OLEOBJ;

...or...

FUNCTION CREATE_OLEOBJ
  (localobject VARCHAR2,
   persistence_boolean := TRUE)
RETURN objpointer OLEOBJ;

Built-in Type  unrestricted function

Returns  pointer to the OLE object

Parameters

name	The program ID of the OLE object's server.
localobject	A pointer to the OLE object whose status is to be changed from non-persistent to persistent.
persistence_boolean	A boolean value of TRUE establishes the object as persistent.  This is an optional parameter.  If not supplied, the default value is persistent.
Usage Notes

A persistent object exists across trigger invocations.  A non-persistent object exists only as long as the trigger that spawned the call runs.


CREATE_PARAMETER_LIST built-in

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

Creates a parameter list with the given name.  The parameter list has no parameters when it is created; they must be added using the ADD_PARAMETER built-in subprogram. A parameter list can be passed as an argument to the CALL_FORM, NEW_FORM, OPEN_FORM, and RUN_PRODUCT built-in subprograms.

Syntax

FUNCTION CREATE_PARAMETER_LIST
  (name  VARCHAR2);

Built-in Type   unrestricted function

Returns  ParamList

Enter Query Mode  yes

Parameters

name	Specifies the VARCHAR2 name of the parameter list object.

When Form Builder creates the object, it assigns it a unique ID of type PARAMLIST.  You can call the parameter list by name or by ID in later calls to parameter list-related built-in subprograms.


CREATE_PARAMETER_LIST restrictions

•	You cannot create a parameter list named DEFAULT.  DEFAULT is reserved for the parameter list that Form Builder creates at the initiation of a runtime session.

•	You cannot create a parameter list if one already exists; to do so will cause an error.  To avoid this error,  use ID_NULL to check to see if a parameter list already exists before creating one.  If a parameter list already exists, delete it before creating a new list.


CREATE_PARAMETER_LIST examples

/*

** Built-in:  CREATE_PARAMETER_LIST
** Example:   Create a parameter list named 'TEMPDATA'. First
**            make sure the list does not already exist, then
**            attempt to create a new list. Signal an error
**            if the list already exists or if creating the
**            list fails.
*/
DECLARE
  pl_id   ParamList;
  pl_name VARCHAR2(10) := 'tempdata';
BEGIN
  pl_id := Get_Parameter_List(pl_name);
  IF Id_Null(pl_id) THEN
    pl_id := Create_Parameter_List(pl_name);
    IF Id_Null(pl_id) THEN
      Message('Error creating parameter list '||pl_name);
      RAISE Form_Trigger_Failure;
    END IF;
  ELSE
    Message('Parameter list '||pl_name||' already exists!');
    RAISE Form_Trigger_Failure;
  END IF;
END;


CREATE_QUERIED_RECORD built-in

 Examples	 Restrictions	  Related Topics	 All Built-ins

Description

When called from an On-Fetch trigger, creates a record on the block's waiting list.  The waiting list is an intermediary record buffer that contains records that have been fetched from the data source but have not yet been placed on the block's list of active records.  This built-in is included primarily for applications using transactional triggers to run against a non-ORACLE data source.

Note that there is no way to remove a record from the waiting list.  Consequently, the application must ensure that there is data available to be used for populating the record programmatically.

Syntax

PROCEDURE CREATE_QUERIED_RECORD;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


CREATE_QUERIED_RECORD restrictions

•	In blocks with a large number of records, this procedure can have side effects on disk I/O, memory allocation, or both.


CREATE_QUERIED_RECORD examples

/*

** Built-in:  CREATE_QUERIED_RECORD
** Example:   Fetch the next N records into this block. Record
**            count kept in Global.Record_Count.
** Trigger:   On-Fetch
*/
DECLARE
  fetch_count NUMBER;
  FUNCTION The_Next_Seq
  RETURN NUMBER IS
    CURSOR next_seq IS SELECT uniq_seq.NEXTVAL FROM DUAL;
    tmp NUMBER;
  BEGIN
    OPEN next_seq;
    FETCH next_seq INTO tmp;
    CLOSE next_seq;
    RETURN tmp;
  END;
BEGIN
  /*
  ** Determine how many records Form Builder is expecting us to
  ** fetch
  */
  fetch_count := Get_Block_Property('MYBLOCK',RECORDS_TO_FETCH);
  FOR i IN 1..fetch_count LOOP
    /*
    ** Create the Queried Record into which we'll deposit
    ** the values we're about to fetch;
    */
    Create_Queried_Record;
    :Global.Record_Count := NVL(:Global.Record_Count,0)+1;
    /*
    ** Populate the item in the queried record with a
    ** sequence function we declared above
    */
   :myblock.numbercol := the_next_seq;
  END LOOP;
END;


CREATE_RECORD built-in

 Examples	  Related Topics	 All Built-ins

Description

Creates a new record in the current block after the current record.  Form Builder then navigates to the new record.

Syntax

PROCEDURE CREATE_RECORD;

Built-in Type   restricted procedure

Enter Query Mode  no

Parameters

none


CREATE_RECORD examples

/*

** Built-in:  CREATE_RECORD
** Example:   Populate new records in a block based on return
**            values from a query
*/
PROCEDURE Populate_Rows_Into_Block( projid NUMBER)  IS
  CURSOR tempcur( cp_projid NUMBER ) IS
    SELECT milestone_name, due_date
      FROM milestone
     WHERE project_id = cp_projid
    ORDER BY due_date;
BEGIN
  /* Add these records to the bottom of the block */
  Last_Record;
  /* Loop thru the records in the cursor */
  FOR rec IN tempcur( projid ) LOOP
    /*
    ** Create an empty record and set the current row's
    ** Milestone_Name and Due_Date items.
    */
    Create_Record;
  : Milestone.Milestone_Name := rec.milestone_name;
  : Milestone.Due_Date       := rec.due_date;
  END LOOP;
  First_Record;
END;


CREATE_TIMER built-in

  Examples	  Restrictions	 All Built-ins

Description

Creates a new timer with the given name. You can indicate the interval and whether the timer should repeat upon expiration or execute once only.  When the timer expires, Form Builder fires the When-Timer-Expired trigger.

Syntax

FUNCTION CREATE_TIMER
  (timer_name    VARCHAR2,
   milliseconds  NUMBER,
   iterate       NUMBER);

Built-in Type   unrestricted function

Returns  Timer

Enter Query Mode  yes

Parameters

timer_name	Specifies the timer name of up to 30 alphanumeric characters.  The name must begin with an alphabetic character.  The data type of the name is VARCHAR2.

milliseconds	Specifies the duration of the timer in milliseconds.  The range of values allowed for this parameter is 1 to 2147483648 milliseconds. Values > 2147483648 will be rounded down to 2147483648.  Note that only positive numbers are allowed.  The data type of the parameter is NUMBER.  See Restrictions below for more information.

iterate	Specifies whether the timer should repeat or not upon expiration.  Takes the following constants as arguments:

REPEAT  Indicates that the timer should repeat upon expiration.  Default.

NO_REPEAT  Indicates that the timer should not repeat upon expiration, but is to be used once only, until explicitly called again.


CREATE_TIMER restrictions

•	Values > 2147483648 will be rounded down to 2147483648.

•	Milliseconds cannot be expressed as a decimal.

•	No two timers can share the same name in the same form instance, regardless of case.

•	If there is no When-Timer-Expired trigger defined at the execution of a timer, Form Builder returns an error.

•	If there is no When-Timer-Expired trigger defined at the execution of a timer, and the timer is a repeating timer, subsequent repetitions are canceled, but the timer is retained.

•	If there is no When-Timer-Expired trigger defined at the execution of a timer, and the timer is not a repeating timer, the timer is deleted.


CREATE_TIMER examples

The following example creates a timer called EMP_TIMER, and sets it to 60 seconds and an iterate value of NO_REPEAT:

DECLARE
    timer_id Timer;
    one_minute NUMBER(5) := 60000;
BEGIN
    timer_id := CREATE_TIMER('emp_timer', one_minute, NO_REPEAT);
END;


CREATE_VAR

  Related Topics 	 All Built-ins

Description

Creates an empty, unnamed variant.

There are two versions of the function, one for scalars and the other for arrays.

Syntax

FUNCTION CREATE_VAR
  (persistence BOOLEAN)
RETURN newvar OLEVAR;

...or...

FUNCTION CREATE_VAR
  (bounds OLE_SAFEARRAYBOUNDS,
   vtype VT_TYPE,
   persistence BOOLEAN)
RETURN newvar OLEVAR;

Built-in Type  unrestricted function

Returns  the created OLE variant.

Parameters

persistence	Controls the persistence of the variant after its creation.  A boolean value of TRUE establishes the variant as persistent; a value of FALSE establishes the variant as non-persistent. This is an optional parameter.  If not specified, the default value is non-persistent.
bounds	A PL/SQL table that specifies the dimensions to be given to the created array. For more information about the contents and layout of this parameter and the type OLE_SAFEARRAYBOUNDS, see ARRAY TYPES FOR OLE SUPPORT.
vtype	The OLE variant type (VT_TYPE) of the elements in the created array.  If the array will contain mixed element types, specify VT_VARIANT.
Usage Notes

•	The created variant is untyped, unless it is an array -- in which case its elements have the type you specify.

•	The created variant is also without a value.  Use the SET_VAR function to assign an initial value and type to the variant.

•	A persistent variant exists across trigger invocations.  A non-persistent variant exists only as long as the trigger that spawned the call runs.  See also DESTROY_VARIANT


CUT_REGION built-in

  Related Topics	 All Built-ins

Description

Removes a selected region of a text item or an image item from the screen and stores it in the paste buffer until you cut or copy another selected region.

Syntax

PROCEDURE CUT_REGION;

Built-in Type   restricted procedure

Enter Query Mode  yes

Parameters

none

Usage Notes

Use CUT_REGION, as well as the other editing functions, on text and image items only.  The cut and copy functions transfer the selected region into the system clipboard until you indicate the paste target.  At that time, the cut or copied content is pasted onto the target location.