About alerts 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 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 Creating an alert

Related Topics

To create an alert:

In the Object Navigator, click the Alerts node.
Click the Create button in the toolbar.
Double-click the alert object icon to display the Property Palette.
Set the Alert Style property to the style that corresponds to the severity of your message: either Stop, Caution, or Note.
At runtime, an icon representing the style you select displays next to the message in the alert window.
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.
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.
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

Displaying an alert

Examples 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 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 Changing the alert message

Examples 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 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 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 (*).

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*

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

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

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

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_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

MAIN_MENU

MAIL

MASTER_DELETES

MASTER_NAME

MAX*

MAXIMIZE

MAXIMIZE_COMPRESSION

MAX_LENGTH

MAX_QUERY_TIME

MAX_RECORDS_FETCHED

MEDIUM_COMPRESSION

MEDIUM_SOUND_QUALITY

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

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

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_OBJECT

REPORT_OBJECT_STATUS

REPORTS

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*

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_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

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 array processing 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 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 Enabling array processing for queries

Related Topics

To enable array processing for a queries:

Choose ToolsPreferences�
Click the Runtime tab.
Check the Array Processing check box.
Click OK.
In the Object Navigator, click the Block object icon .
Double-click the Block object icon to display the Property Palette.
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

Enabling array processing for DML

Related Topics

To enable array processing for DML:

Choose ToolsPreferences....
Click the Runtime tab.
Check the Array Processing check box.
In the Object Navigator, click the Block object icon .
Double-click the Block object icon to display the Property Palette.
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.

Built-ins overview

Built-ins overview

Related Topics

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 Built-in syntax

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 Built-in named parameters

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 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 Built-in object IDs

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 Built-in form coordinate units

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 Built-in uppercase return values

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 Restricted built-in subprograms

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 Built-in constants

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 Individual built-in descriptions

Examples Restrictions

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 Individual built-in descriptions restrictions

Indicates any restrictions.

Individual built-in descriptions examples 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 ABORT_QUERY built-in

Restrictions

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

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 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 ACTIVATE_SERVER

Examples Restrictions Related Topics

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 ACTIVATE_SERVER restrictions

Valid only on Microsoft Windows and Macintosh.

ACTIVATE_SERVER examples 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 ADD_GROUP_COLUMN built-in

Examples Restrictions Related Topics

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 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 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

ADD_GROUP_ROW built-in

Examples Restrictions Related Topics

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 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 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

ADD_LIST_ELEMENT built-in

Examples Restrictions Related Topics

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 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 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

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.
type	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 ADD_PARAMETER built-in

Examples Restrictions Related Topics

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.

alue 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

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.

ADD_PARAMETER examples 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

ADD_TREE_DATA built-in

Examples

Description
Adds a data set under the specified node of a hierarchical tree item.

Syntax
PROCEDURE ADD_TREE_DATA

(item_id ITEM,

node NODE,

offset_type NUMBER,

offset NUMBER,

data_source NUMBER,

data VARCHAR2);

PROCEDURE ADD_TREE_DATA

(item_name VARCHAR2,

node NODE,

offset_type NUMBER,

offset NUMBER,

data_source NUMBER,

data VARCHAR2);

PROCEDURE ADD_TREE_DATA

(item_name VARCHAR2,

node NODE,

offset_type NUMBER,

offset NUMBER,

data_source NUMBER,

data RECORDGROUP);

PROCEDURE ADD_TREE_DATA

(item_id ITEM,

node 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 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 ADD_TREE_NODE built-in

Examples

Description
Adds a data element to a hierarchical tree item.

Syntax
FUNCTION ADD_TREE_NODE

(item_name VARCHAR2,

node NODE,

offset_type NUMBER,

offset NUMBER,

state NUMBER,

label VARCHAR2,

icon VARCHAR2,

value VARCHAR2);

FUNCTION ADD_TREE_NODE

(item_id ITEM,

node 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.
alue	Specifies the VARCHAR2 value of the node.

ADD_TREE_NODE examples 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 NODE;

new_node 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 APPLICATION_PARAMETER built-in

Related Topics

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 BELL built-in

Examples

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 BELL examples

The following example rings the bell three times:

FOR i in 1..3 LOOP
BELL;
SYNCHRONIZE;
END LOOP;

BLOCK_MENU built-in BLOCK_MENU built-in

Examples

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 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

BREAK built-in

Examples Restrictions

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 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 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

CALL_FORM built-in

Examples Restrictions Related Topics

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.

uery_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 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 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

CALL_INPUT built-in

Restrictions

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 restrictions

CALL_INPUT is included for compatibility with previous versions. You should not include this built-in in new applications.

CALL_OLE CALL_OLE

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>

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

CANCEL_REPORT_OBJECT built-in

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 CHECKBOX_CHECKED built-in

Examples Restrictions Related Topics

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 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 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

CHECK_RECORD_UNIQUENESS built-in

Examples Restrictions Related Topics

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 CHECK_RECORD_UNIQUENESS restrictions

Valid only in an On-Check-Unique trigger.

CHECK_RECORD_UNIQUENESS examples 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

CLEAR_BLOCK built-in

Examples Related Topics

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 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

CLEAR_EOL built-in

Examples

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 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

CLEAR_FORM built-in

Examples Restrictions Related Topics

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 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 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

CLEAR_ITEM built-in

Examples

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 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

CLEAR_LIST built-in

Examples Restrictions Related Topics

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

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 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 CLEAR_LIST examples

/*

Built-in: CLEAR_LIST
** Example: See POPULATE_LIST
*/

CLEAR_MESSAGE built-in

CLEAR_MESSAGE built-in

Examples

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 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

CLEAR_RECORD built-in

Examples Related Topics

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 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

CLOSE_FORM built-in

Restrictions Related Topics

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 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.

CLOSE_SERVER CLOSE_SERVER

Examples Restrictions Related Topics

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

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

CLOSE_SERVER restrictions CLOSE_SERVER restrictions

Valid only on Microsoft Windows and Macintosh.

CLOSE_SERVER examples 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

COMMIT_FORM built-in

Examples Restrictions

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 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 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

CONVERT_OTHER_VALUE built-in

Examples Restrictions Related Topics

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 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 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

COPY built-in

Examples Restrictions Related Topics

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

COPY expects 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 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 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

COPY_REGION built-in

Related Topics

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 COPY_REPORT_OBJECT_OUTPUT built-in

Examples

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

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 COPY_REPORT_OBJECT_OUTPUT examples

DECLARE

repid REPORT_OBJECT;

rep VARCHAR2(100);

rep_status varchar2(20);

BEGIN

repid := find_report_object('report4');

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 COUNT_QUERY built-in

Examples Restrictions Related Topics

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 COUNT_QUERY restrictions

Valid only in triggers that allow restricted built-ins.

COUNT_QUERY examples 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

CREATE_GROUP built-in

Examples Related Topics

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 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

CREATE_GROUP_FROM_QUERY built-in

Examples Restrictions Related Topics

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.

uery 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 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 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

CREATE_OLEOBJ

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 CREATE_PARAMETER_LIST built-in

Examples Restrictions Related Topics

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 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.

CREATE_PARAMETER_LIST examples 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

CREATE_QUERIED_RECORD built-in

Examples Restrictions Related Topics

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 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 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

CREATE_RECORD built-in

Examples Related Topics

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 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

CREATE_TIMER built-in

Examples Restrictions Related Topics

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 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 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 CREATE_VAR

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.
type	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

CUT_REGION built-in

Related Topics

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.

DBMS_ERROR_CODE built-in DBMS_ERROR_CODE built-in

Examples Related Topics

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 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

DBMS_ERROR_TEXT built-in

Examples Related Topics

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 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

DEBUG_MODE built-in

Restrictions

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 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 DEFAULT_VALUE built-in

Examples Restrictions Related Topics

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

alue_string A valid VARCHAR2 string, variable, or text item containing a valid string.
ariable_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

DEFAULT_VALUE restrictions

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

DEFAULT_VALUE examples 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

DELETE_GROUP built-in

Examples Restrictions Related Topics

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 DELETE_GROUP restrictions

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

DELETE_GROUP examples 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

DELETE_GROUP_ROW built-in

Examples Restrictions Related Topics

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 DELETE_GROUP_ROW restrictions

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

DELETE_GROUP_ROW examples 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

DELETE_LIST_ELEMENT built-in

Examples Restrictions Related Topics

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

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 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.

DELETE_LIST_ELEMENT examples DELETE_LIST_ELEMENT examples

/*

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

DELETE_PARAMETER built-in

DELETE_PARAMETER built-in

Examples Restrictions Related Topics

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 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 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

DELETE_RECORD built-in

Examples Related Topics

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 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

DELETE_TIMER built-in

Examples Restrictions Related Topics

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 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 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

DELETE_TREE_NODE built-in

Examples

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 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 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 DESTROY_PARAMETER_LIST built-in

Examples Related Topics

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

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

DESTROY_PARAMETER_LIST examples 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

DESTROY_VARIANT

Description
Destroys a variant that was created by the CREATE_VAR function.

Syntax
PROCEDURE DESTROY_VARIANT (variant OLEVAR);

Built-in Type unrestricted procedure

Parameters

ariant

The OLE variant to be destroyed.

DISPATCH_EVENT built-in DISPATCH_EVENT built-in

Examples

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 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_UNALLOWED);
ENDIF;
END;

DISPLAY_ERROR built-in DISPLAY_ERROR built-in

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 DISPLAY_ITEM built-in

Examples Related Topics

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 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

DOWN built-in

Related Topics

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 DO_KEY built-in

Examples Restrictions

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 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 DO_KEY examples

/*

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

DUMMY_REFERENCE built-in

DUMMY_REFERENCE built-in

Restrictions Related Topics

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 DUMMY_REFERENCE restrictions

none

DUPLICATE_ITEM built-in DUPLICATE_ITEM built-in

Restrictions Related Topics

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 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 DUPLICATE_RECORD built-in

Examples Restrictions Related Topics

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 DUPLICATE_RECORD restrictions

A previous record must exist in your current session.

DUPLICATE_RECORD examples 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

EDIT_TEXTITEM built-in

Examples Restrictions Related Topics

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 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 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

ENFORCE_COLUMN_SECURITY built-in

Restrictions Related Topics

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 ENFORCE_COLUMN_SECURITY restrictions

Valid only in an On-Column-Security trigger.

ENTER built-in ENTER built-in

Examples Related Topics

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 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

ENTER_QUERY built-in

Examples Restrictions Related Topics

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 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 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

ERASE built-in

Examples Related Topics

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 examples

ERASE('global.var');

ERROR_CODE built-in ERROR_CODE built-in

Examples Related Topics

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 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

ERROR_TEXT built-in

Examples Related Topics

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 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

ERROR_TYPE built-in

Examples Related Topics

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 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

EXEC_VERB

Examples Restrictions Related Topics

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

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

erb_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.
erb_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

EXEC_VERB restrictions

Valid only on Microsoft Windows and Macintosh.

EXEC_VERB examples 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

EXECUTE_QUERY built-in

Examples Restrictions Related Topics

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.

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 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 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

EXECUTE_TRIGGER built-in

Examples Restrictions Related Topics

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 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 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

EXIT_FORM built-in

Examples

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 EXIT_FORM examples

/*

Built-in: 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;

FETCH_RECORDS built-in

FETCH_RECORDS built-in

Examples Related Topics

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 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

FIND_ALERT built-in

Examples Related Topics

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 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

FIND_BLOCK built-in

Examples Related Topics

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 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

FIND_CANVAS built-in

Examples Related Topics

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 FIND_CANVAS examples

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

FIND_COLUMN built-in FIND_COLUMN built-in

Examples Related Topics

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 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

FIND_EDITOR built-in

Examples Related Topics

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 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

FIND_FORM built-in

Examples Related Topics

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 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

FIND_GROUP built-in

Examples Restrictions Related Topics

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 FIND_GROUP restrictions

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

FIND_GROUP examples FIND_GROUP examples

/*

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

FIND_ITEM built-in

FIND_ITEM built-in

Examples Related Topics

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 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

FIND_LOV built-in

Examples Related Topics

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 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

FIND_MENU_ITEM built-in

Examples Related Topics

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 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

FIND_OLE_VERB

Examples Restrictions Related Topics

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

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

erb_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

FIND_OLE_VERB restrictions

Valid only on Microsoft Windows and Macintosh.

FIND_OLE_VERB examples 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

FIND_RELATION built-in

Examples Related Topics

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 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

FIND_REPORT_OBJECT built-in

Examples

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
PROCEDURE FIND_REPORT_OBJECT
(report_name VARCHAR2
);

Built-in Type unrestricted procedure

Enter Query Mode yes

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

Usage Notes
Returns the report_id of data type REPORT.

FIND_REPORT_OBJECT examples FIND_REPORT_OBJECT examples

DECLARE

repid REPORT_OBJECT;

rep VARCHAR2(100);

BEGIN

repid := find_report_object('report4');

rep := RUN_REPORT_OBJECT(repid);

....

END;

FIND_TAB_PAGE built-in FIND_TAB_PAGE built-in

Examples Related Topics

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 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

FIND_TIMER built-in

Examples Related Topics

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.