FIND_TIMER examples

FIND_TIMER examples FIND_TIMER examples

/*

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

FIND_TREE_NODE built-in

FIND_TREE_NODE built-in

Examples

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

Syntax
FUNCTION FIND_TREE_NODE

(item_name VARCHAR2,

search_string VARCHAR2,

search_type NUMBER,

search_by NUMBER,

search_root NODE,

start_point NODE);

FUNCTION FIND_TREE_NODE

(item_id ITEM,

search_string VARCHAR2,

search_type NUMBER,

search_by NUMBER,

search_root NODE,

start_point NODE);

Built-in Type unrestricted function

Returns NODE

Enter Query Mode no

Parameters

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

FIND_TREE_NODE examples FIND_TREE_NODE examples

/*

Built-in: FIND_TREE_NODE
*/

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

-- within the subtree beginning with the a node

-- with a label of "Zetie".

DECLARE

htree ITEM;

find_node NODE;

BEGIN

-- Find the tree itself.

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

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

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

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

-- Find the node with a label "Doran"

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

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

Ftree.NODE_LABEL, find_node, find_node);

IF NOT Ftree.ID_NULL(find_node) then

...

END IF;

END;

FIND_VA built-in FIND_VA built-in

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

Syntax
FUNCTION FIND_VA

(va_name PROPERTY);

Built-in Type unrestricted function

Returns Visual Attribute

Enter Query Mode yes

Parameters

a_name

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

FIND_VIEW built-in FIND_VIEW built-in

Examples Related Topics

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

Syntax
FUNCTION FIND_VIEW
(viewcanvas_name VARCHAR2);

Built-in Type unrestricted function

Returns ViewPort

Enter Query Mode yes

Parameters

iewcanvas_name Specifies the VARCHAR2 name of the canvas.

FIND_VIEW examples

FIND_VIEW examples

/*

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

FIND_WINDOW built-in

FIND_WINDOW built-in

Examples Related Topics

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

Syntax
FUNCTION FIND_WINDOW
(window_name VARCHAR2);

Built-in Type unrestricted function

Returns Window

Enter Query Mode yes

Parameters
window_name Specifies the valid VARCHAR2 window name.

FIND_WINDOW examples FIND_WINDOW examples

/*

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

FIRST_RECORD built-in

FIRST_RECORD built-in

Examples Related Topics

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

Syntax
PROCEDURE FIRST_RECORD;

Built-in Type restricted procedure

Enter Query Mode no

Parameters
none

FIRST_RECORD examples FIRST_RECORD examples

/*

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

FORM_FAILURE built-in

FORM_FAILURE built-in

Examples Related Topics

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

*Outcome*	*Returned Value*
success	FALSE
failure	TRUE
fatal error	FALSE

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

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

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

Syntax
FUNCTION FORM_FAILURE;

Built-in Type unrestricted function

Returns BOOLEAN

Enter Query Mode yes

Parameters
none

FORM_FAILURE examples FORM_FAILURE examples

/*

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

FORM_FATAL built-in

FORM_FATAL built-in

Examples Related Topics

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

*Outcome*	*Returned Value*
success	FALSE
failure	FALSE
fatal error	TRUE

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

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

Syntax
FUNCTION FORM_FATAL;

Built-in Type unrestricted function

Return Type:

BOOLEAN

Enter Query Mode yes

Parameters
none

FORM_FATAL examples FORM_FATAL examples

/*

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

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

FORM_SUCCESS built-in

FORM_SUCCESS built-in

Examples Related Topics

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

*Outcome*	*Returned Value*
success	TRUE
failure	FALSE
fatal error	FALSE

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

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

Syntax
FUNCTION FORM_SUCCESS;

Built-in Type unrestricted function

Return Type:

BOOLEAN

Enter Query Mode yes

Parameters
none

FORM_SUCCESS examples FORM_SUCCESS examples

/*

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

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

FORMS_DDL built-in

FORMS_DDL built-in

Examples Restrictions Related Topics

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

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

Syntax
FUNCTION FORMS_DDL
(statement VARCHAR2);

Built-in Type unrestricted function

Enter Query Mode yes

Parameters
statement Any string expression up to 32K:

a literal

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

a DML statement or

a DDL statement

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

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

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

Use semicolons where appropriate.

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

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

Line breaks, while permitted, are not required.

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

Omit the trailing semicolon to avoid an invalid character error.

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

FORMS_DDL restrictions FORMS_DDL restrictions

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

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

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

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

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

Update_Employee (:emp.empno);

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

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

FORMS_DDL examples FORMS_DDL examples

Example 1
/*

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

Example 2
/*

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

Example 3:
/*

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

Example 4:
/*

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

GENERATE_SEQUENCE_NUMBER built-in

GENERATE_SEQUENCE_NUMBER built-in

Examples Restrictions

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

Syntax
PROCEDURE GENERATE_SEQUENCE_NUMBER;

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
none

GENERATE_SEQUENCE_NUMBER restrictions GENERATE_SEQUENCE_NUMBER restrictions

Valid only in an On-Sequence-Number trigger.

GENERATE_SEQUENCE_NUMBER examples GENERATE_SEQUENCE_NUMBER examples

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

GET_APPLICATION_PROPERTY built-in

GET_APPLICATION_PROPERTY built-in

Examples Restrictions Related Topics

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

Syntax
FUNCTION GET_APPLICATION_PROPERTY
(property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

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

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

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

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

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

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

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

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

PASSWORD Returns the password of the current operator.

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

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

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

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

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

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

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

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

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

ifrun60 my_form scott/tiger@corpDB1

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

scott

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

tiger

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

corpDB1

GET_APPLICATION_PROPERTY restrictions GET_APPLICATION_PROPERTY restrictions

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

GET_APPLICATION_PROPERTY examples GET_APPLICATION_PROPERTY examples

Example 1
/*

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

IF tm_name = 'MY_ONCE_EVERY_FIVE_MINUTES_TIMER' THEN

:control.onscreen_clock := SYSDATE;

ELSIF tm_name = 'MY_ONCE_PER_HOUR_TIMER' THEN

Go_Block('connected_users');
Execute_Query;

END IF;
END;

Example 2
/*

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

GET_BLOCK_PROPERTY built-in

GET_BLOCK_PROPERTY built-in

Examples Related Topics

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

Syntax
FUNCTION GET_BLOCK_PROPERTY
(block_id Block,
property NUMBER);

FUNCTION GET_BLOCK_PROPERTY
(block_name VARCHAR2,
property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

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

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

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

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

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

CURRENT_RECORD Returns the number of the current record.

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

CURRENT_ROW_BACKGROUND_COLOR The color of the object's background region.

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

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

CURRENT_ROW_FONT_SIZE The size of the font, specified in points.

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

CURRENT_ROW_FONT_STYLE The style of the font.

CURRENT_ROW_FONT_WEIGHT The weight of the font.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PRECOMPUTE_SUMMARIES[Under Construction]

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

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

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

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

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

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

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

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

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

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

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

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

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

GET_BLOCK_PROPERTY examples GET_BLOCK_PROPERTY examples

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

GET_CANVAS_PROPERTY built-in

GET_CANVAS_PROPERTY built-in

Examples Related Topics

Description
Returns the given canvas property for the given canvas. .

Syntax
FUNCTION GET_CANVAS_PROPERTY
(canvas_id Canvas,
property NUMBER);

FUNCTION GET_CANVAS_PROPERTY
(canvas_name VARCHAR2,
property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

BACKGROUND_COLOR The color of the object's background region.

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

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

FONT_SIZE The size of the font, specified in points.

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

FONT_STYLE The style of the font.

FONT_WEIGHT The weight of the font.

FOREGROUND_COLOR The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.
HEIGHT Returns the height of the canvas, specified in the form coordinate units indicated by the Coordinate System form property.

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

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

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

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

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

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

GET_CANVAS_PROPERTY examples GET_CANVAS_PROPERTY examples

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

GET_FILE_NAME built-in

GET_FILE_NAME built-in

Examples

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

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

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

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

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

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

GET_FILE_NAME examples GET_FILE_NAME examples

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

GET_FORM_PROPERTY built-in

GET_FORM_PROPERTY built-in

Examples Related Topics

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

Syntax
FUNCTION GET_FORM_PROPERTY
(formmodule_id FormModule,
property NUMBER);

FUNCTION GET_FORM_PROPERTY
(formmodule_name VARCHAR2,
property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

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

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

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

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

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

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

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

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

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

CURRENT_ROW_BACKGROUND_COLOR The color of the object's background region.

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

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

CURRENT_ROW_FONT_SIZE The size of the font, specified in points.

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

CURRENT_ROW_FONT_STYLE The style of the font.

CURRENT_ROW_FONT_WEIGHT The weight of the font.

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

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

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

DEFER_REQUIRED_ENFORCEMENT Returns the setting that indicates whether enforcement of required fields has been deferred from item validation to record validation.

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

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

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

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

FORM_NAME Returns the name of the form.

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

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

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

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

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

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

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

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

SAVEPOINT_MODE Returns TRUE or FALSE to indicate whether savepoints are supported in the data source.

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

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

FORM_SCOPE if the current validation unit is the form.

BLOCK_SCOPE if the current validation unit is the block.

RECORD_SCOPE if the current validation unit is the record.

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

GET_FORM_PROPERTY examples GET_FORM_PROPERTY examples

Example 1
/*

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

Example 2
/*

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

GET_GROUP_CHAR_CELL built-in

GET_GROUP_CHAR_CELL built-in

Examples Restrictions Related Topics

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

Syntax
FUNCTION GET_GROUP_CHAR_CELL
(groupcolumn_id GroupColumn,
row_number NUMBER);

FUNCTION GET_GROUP_CHAR_CELL
(groupcolumn_name VARCHAR2,
row_number NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

GET_GROUP_CHAR_CELL restrictions GET_GROUP_CHAR_CELL restrictions

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

GET_GROUP_CHAR_CELL examples GET_GROUP_CHAR_CELL examples

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

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

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

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

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

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

GET_GROUP_DATE_CELL built-in

GET_GROUP_DATE_CELL built-in

Examples Restrictions Related Topics

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

Syntax
FUNCTION GET_GROUP_DATE_CELL
(groupcolumn_id GroupColumn,
row_number NUMBER);

FUNCTION GET_GROUP_DATE_CELL
(groupcolumn_name VARCHAR2,
row_number NUMBER);

Built-in Type unrestricted function

Returns DATE

Enter Query Mode yes

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

GET_GROUP_DATE_CELL restrictions GET_GROUP_DATE_CELL restrictions

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

GET_GROUP_DATE_CELL examples GET_GROUP_DATE_CELL examples

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

GET_GROUP_NUMBER_CELL built-in

GET_GROUP_NUMBER_CELL built-in

Examples Restrictions

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

Syntax
FUNCTION GET_GROUP_NUMBER_CELL
(groupcolumn_id GroupColumn,
row_number NUMBER);

FUNCTION GET_GROUP_NUMBER_CELL
(groupcolumn_name VARCHAR2,
row_number NUMBER);

Built-in Type unrestricted function

Returns NUMBER

Enter Query Mode yes

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

GET_GROUP_NUMBER_CELL restrictions GET_GROUP_NUMBER_CELL restrictions

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

GET_GROUP_NUMBER_CELL examples GET_GROUP_NUMBER_CELL examples

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

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

GET_GROUP_RECORD_NUMBER built-in

GET_GROUP_RECORD_NUMBER built-in

Examples Restrictions

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

Syntax
FUNCTION GET_GROUP_RECORD_NUMBER
(groupcolumn_id GroupColumn,
cell_value NUMBER);

FUNCTION GET_GROUP_RECORD_NUMBER
(groupcolumn_name VARCHAR2,
cell_value NUMBER);

Built-in Type unrestricted function

Returns NUMBER

Enter Query Mode yes

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

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

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

GET_GROUP_RECORD_NUMBER restrictions GET_GROUP_RECORD_NUMBER restrictions

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

GET_GROUP_RECORD_NUMBER examples GET_GROUP_RECORD_NUMBER examples

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

GET_GROUP_ROW_COUNT built-in

GET_GROUP_ROW_COUNT built-in

Examples Related Topics

Description
Returns the number of rows in the record group.

Syntax
FUNCTION GET_GROUP_ROW_COUNT
(recordgroup_id RecordGroup);

FUNCTION GET_GROUP_ROW_COUNT
(recordgroup_name VARCHAR2);

Built-in Type unrestricted function

Returns NUMBER

Enter Query Mode yes

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

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

GET_GROUP_ROW_COUNT examples GET_GROUP_ROW_COUNT examples

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

GET_GROUP_SELECTION built-in

GET_GROUP_SELECTION built-in

Examples Related Topics

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

Syntax
FUNCTION GET_GROUP_SELECTION
(recordgroup_id RecordGroup,
selection_number NUMBER);

FUNCTION GET_GROUP_SELECTION
(recordgroup_name VARCHAR2,
selection_number NUMBER);

Built-in Type unrestricted function

Returns NUMBER

Enter Query Mode yes

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

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

GET_GROUP_SELECTION examples GET_GROUP_SELECTION examples

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

GET_GROUP_SELECTION_COUNT built-in

GET_GROUP_SELECTION_COUNT built-in

Examples Related Topics

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

Syntax
FUNCTION GET_GROUP_SELECTION_COUNT
(recordgroup_id RecordGroup);

FUNCTION GET_GROUP_SELECTION_COUNT
(recordgroup_name VARCHAR2);

Built-in Type unrestricted function

Returns NUMBER

Enter Query Mode yes

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

GET_GROUP_SELECTION_COUNT examples GET_GROUP_SELECTION_COUNT examples

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

GET_INTERFACE_POINTER

GET_INTERFACE_POINTER

Examples Restrictions Related Topics

Description
Returns a handle to an OLE2 automation object.

Syntax
FUNCTION GET_INTERFACE_POINTER
(item_id Item);

FUNCTION GET_INTERFACE_POINTER
(item_name VARCHAR2);

Returns PLS_INTEGER

Built-in Type unrestricted function

Enter Query Mode no

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

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

GET_INTERFACE_POINTER restrictions GET_INTERFACE_POINTER restrictions

Valid only on Microsoft Windows and Macintosh.

GET_INTERFACE_POINTER examples GET_INTERFACE_POINTER examples

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

GET_ITEM_INSTANCE_PROPERTY built-in

GET_ITEM_INSTANCE_PROPERTY built-in

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

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

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

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

record_number A record number or CURRENT_RECORD.

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

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

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

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

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

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

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

Usage Notes:

When a record is fetched or a new record is created, its item instance properties are set to values that do not override the values specified at higher levels. For example, the BORDER_BEVEL and VISUAL_ATTRIBUTE properties get set to " ", REQUIRED is set to false, and other boolean properties are set to true.

GET_ITEM_PROPERTY built-in GET_ITEM_PROPERTY built-in

Examples Related Topics

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

Syntax
FUNCTION GET_ITEM_PROPERTY
(item_id, ITEM
property NUMBER);

FUNCTION GET_ITEM_PROPERTY
(item_name VARCHAR2,
property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

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

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

BACKGROUND_COLOR The color of the object's background region.

BLOCK_NAME Returns the VARCHAR2 block name for the item.

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

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

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

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

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

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

CURRENT_ROW_BACKGROUND_COLOR The color of the object's background region.

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

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

CURRENT_ROW_FONT_SIZE The size of the font, specified in points.

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

CURRENT_ROW_FONT_STYLE The style of the font.

CURRENT_ROW_FONT_WEIGHT The weight of the font.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

FONT_SIZE The size of the font, specified in points.

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

FONT_STYLE The style of the font.

FONT_WEIGHT The weight of the font.

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

FORMAT_MASK Returns the format mask used for the text item.

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

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

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

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

IMAGE_DEPTH Returns the color depth of the specified image item.

IMAGE_FORMAT Returns the format of the specified image item.

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

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

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

ITEM_NAME Returns the name of the item.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

POPUPMENU_COPY_ITEM

POPUPMENU_CUT_ITEM

POPUPMENU_DELOBJ_ITEM

POPUPMENU_INSOBJ_ITEM

POPUPMENU_LINKS_ITEM

POPUPMENU_OBJECT_ITEM

POPUPMENU_PASTE_ITEM

POPUPEMNU_PASTESPEC_ITEM

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

PREVIOUSITEM Returns the name of the previous item.

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

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

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

PROMPT_BACKGROUND_COLOR The color of the object's background region.

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

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

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

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

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

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

PROMPT_FONT_SIZE The size of the font, specified in points.

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

PROMPT_FONT_STYLE The style of the font.

PROMPT_FONT_WEIGHT The weight of the font.

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

PROMPT_TEXT Returns the text label that displays for an item.

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

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

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

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

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

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

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

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

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

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

SHOW_FAST_FORWARD_BUTTON Returns the VARCHAR2 value TRUE if

is displayed on the specified sound item, FALSE if not.

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

SHOW_PLAY_BUTTON Returns the VARCHAR2 value TRUE if

is displayed on the specified sound item, FALSE if not.

SHOW_RECORD_BUTTON Returns the VARCHAR2 value TRUE if

is displayed on the specified sound item, FALSE if not.

SHOW_REWIND_BUTTON Returns the VARCHAR2 value TRUE if

is displayed on the specified sound item, FALSE if not.

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

SHOW_TIME_INDICATOR Returns the VARCHAR2 value TRUE if

is displayed on the specified sound item, FALSE if not.

SHOW_VOLUME_CONTROL Returns the VARCHAR2 value TRUE if

is displayed on the specified sound item, FALSE if not.

TOOLTIP_BACKGROUND_COLOR The color of the object's background region.

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

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

TOOLTIP_FONT_SIZE The size of the font, specified in points.

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

TOOLTIP_FONT_STYLE The style of the font.

TOOLTIP_FONT_WEIGHT The weight of the font.

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

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

TOOLTIP_TEXT Returns the item�s tooltip text.

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

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

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

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

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

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

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

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

WIDTH Returns the width of the item.

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

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

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

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

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

GET_ITEM_PROPERTY examples GET_ITEM_PROPERTY examples

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

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

GET_LIST_ELEMENT_COUNT built-in

GET_LIST_ELEMENT_COUNT built-in

Examples Related Topics

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

Syntax
FUNCTION GET_LIST_ELEMENT_COUNT
(list_id Item);

FUNCTION GET_LIST_ELEMENT_COUNT
(list_name VARCHAR2);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

GET_LIST_ELEMENT_COUNT examples GET_LIST_ELEMENT_COUNT examples

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

GET_LIST_ELEMENT_LABEL built-in

GET_LIST_ELEMENT_LABEL built-in

Examples Related Topics

Description
Returns information about the requested list element label.

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

FUNCTION GET_LIST_ELEMENT_LABEL
(list_name VARCHAR2,
list_index NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

GET_LIST_ELEMENT_LABEL examples GET_LIST_ELEMENT_LABEL examples

/*

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

GET_LIST_ELEMENT_VALUE built-in

GET_LIST_ELEMENT_VALUE built-in

Examples Related Topics

Description
Returns the value associated with the specified list item element.

Syntax
FUNCTION GET_LIST_ELEMENT_VALUE
(list_id ITEM,
list_index NUMBER);

FUNCTION GET_LIST_ELEMENT_VALUE
(list_name VARCHAR2,
list_index NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

GET_LIST_ELEMENT_VALUE examples GET_LIST_ELEMENT_VALUE examples

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

GET_LOV_PROPERTY built-in

GET_LOV_PROPERTY built-in

Examples Related Topics

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

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

Syntax
FUNCTION GET_LOV_PROPERTY
(lov_id, property LOV);

FUNCTION GET_LOV_PROPERTY
(lov_name VARCHAR2,
property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

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

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

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

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

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

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

GET_LOV_PROPERTY examples GET_LOV_PROPERTY examples

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

GET_MENU_ITEM_PROPERTY built-in

GET_MENU_ITEM_PROPERTY built-in

Examples Related Topics

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

Syntax
FUNCTION GET_MENU_ITEM_PROPERTY
(menuitem_id MenuItem,
property NUMBER);

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

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

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

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

LABEL Returns the VARCHAR2 string for the menu item label.

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

GET_MENU_ITEM_PROPERTY examples GET_MENU_ITEM_PROPERTY examples

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

GET_MESSAGE built-in

GET_MESSAGE built-in

Examples Restrictions Related Topics

Description
Returns the current message, regardless of type.

Syntax
FUNCTION GET_MESSAGE;

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

Parameters
none

GET_MESSAGE restrictions GET_MESSAGE restrictions

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

GET_MESSAGE examples GET_MESSAGE examples

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

GET_OLE_proptype

GET_OLE_<proptype>

Description
Obtains an OLE property.

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

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

...or...

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

...or...

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

...or...

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

Built-in Type unrestricted function

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

Parameters

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

Usage Notes

If INIT_OLEARGS and ADD_OLEARG calls precede this GET_OLE_type call, and there have been no intervening GET_OLE, SET_OLE, or CALL_OLE calls, then this call will retrieve the property by using the arguments specified in those INIT_OLEARGS and ADD_OLEARG calls.
In contrast to a returned OLEVAR argument, whose persistence can be user-controlled, a returned OLEOBJ argument is always set to be non-persistent.

GET_OLEARG_type

GET_OLEARG_<type>

Description
Obtains the nth argument from the OLE argument stack.

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

Syntax
FUNCTION GET_OLEARG_CHAR
(which NUMBER)
RETURN olearg VARCHAR2;

...or...

FUNCTION GET_OLEARG_NUM
(which NUMBER)
RETURN olearg NUMBER;

...or...

FUNCTION GET_OLEARG_OBJ
(which NUMBER)
RETURN olearg OLEOBJ;

...or...

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

Built-in Type unrestricted function

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

Parameters

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

Usage Notes

Use this function to retrieve arguments whose value might change as a result of the method call.
In contrast to a returned OLEVAR argument, whose persistence can be user-controlled, a returned OLEOBJ argument is always set to be non-persistent.

GET-OLE-MEMBERID

GET_OLE_MEMBERID

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

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

Built-in Type unrestricted function

Returns member ID of the method or property

Parameters

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

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

GET_PARAMETER_ATTR built-in GET_PARAMETER_ATTR built-in

Related Topics

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

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

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

Built-in Type unrestricted procedure that returns two OUT parameters

Enter Query Mode yes

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

key The VARCHAR2 name of the parameter.

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

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

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

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

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

GET_PARAMETER_LIST built-in GET_PARAMETER_LIST built-in

Examples Related Topics

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

Syntax
FUNCTION GET_PARAMETER_LIST
(name VARCHAR2);

Built-in Type unrestricted function

Returns ParamList

Enter Query Mode yes

Parameters
name Specifies a valid VARCHAR2 parameter list name.

GET_PARAMETER_LIST examples GET_PARAMETER_LIST examples

See CREATE_PARAMETER_LIST

GET_RADIO_BUTTON_PROPERTY built-in GET_RADIO_BUTTON_PROPERTY built-in

Examples Related Topics

Description
Returns information about a specified radio button.

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

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

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

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

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

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

BACKGROUND_COLOR The color of the object's background region.
ENABLED Returns the VARCHAR2 string TRUE if property is set to Yes, and the VARCHAR2 string FALSE if property is set to No.

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

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

FONT_SIZE The size of the font, specified in points.

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

FONT_STYLE The style of the font.

FONT_WEIGHT The weight of the font.

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

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

LABEL Returns the actual string label for that radio button.

PROMPT_BACKGROUND_COLOR The color of the object's background region.

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

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

PROMPT_FONT_SIZE The size of the font, specified in points.

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

PROMPT_FONT_STYLE The style of the font.

PROMPT_FONT_WEIGHT The weight of the font.

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

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

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

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

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

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

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

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

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

GET_RADIO_BUTTON_PROPERTY examples GET_RADIO_BUTTON_PROPERTY examples

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

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

GET_RECORD_PROPERTY built-in

GET_RECORD_PROPERTY built-in

Examples Related Topics

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

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

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

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

block_name Specifies the block containing the target record.

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

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

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

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

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

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

In a Base Table Block: Change a Control Item	NEW	INSERT	<Q\|C>	<Q\|C>
In a Control Block: Change a Control Item	NEW	INSERT	<Q>	<Q\|C>
...and no record in current block is changed		INSERT	QUERY	<Q\|C>
...and no block in current form is changed		INSERT	QUERY	QUERY

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

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

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

GET_RECORD_PROPERTY examples GET_RECORD_PROPERTY examples

built-in: GET_RECORD_PROPERTY
** Example: Obtain the status of a record in given block
*/
BEGIN
IF Get_Record_Property(1,'orders',STATUS) = 'NEW' AND
Get_Record_Property(1,'customers',STATUS) = 'NEW' THEN
Message('You must enter a customer and order first!');
RAISE Form_Trigger_Failure;
END IF;
END;

GET_RELATION_PROPERTY built-in

GET_RELATION_PROPERTY built-in

Examples Related Topics

Description
Returns the state of the given relation property.

Syntax
FUNCTION GET_RELATION_PROPERTY
(relation_id Relation,
property NUMBER);

FUNCTION GET_RELATION_PROPERTY
(relation_name VARCHAR2,
property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

Parameters
relation_id Specifies the unique ID Form Builder assigns when it creates the relation. Use the FIND_RELATION built-in to return the ID to an appropriately typed variable. The data type of the ID is Relation.

relation_name Specifies the VARCHAR2 name you gave to the relation when you defined it, or the name that Form Builder assigned to the relation when created.

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

AUTOQUERY Returns the VARCHAR2 value TRUE if the Automatic Query relation property is Yes, FALSE if it is No. When the Deferred relation property is set to Yes, this property determines whether Form Builder automatically populates the detail block when a different record becomes the current record in the master block.

DEFERRED_COORDINATION Returns the VARCHAR2 value TRUE if the Deferred relation property is Yes, FALSE if it is No. This property determines whether the detail block is to be immediately coordinated with the current master record, or left clear until the operator navigates to the detail block.

DETAIL_NAME Returns the VARCHAR2 name of the detail block in the given master-detail relationship.

MASTER_DELETES Returns one of the following VARCHAR2 values to indicate the current setting of the block's Delete Record Behavior property: NON_ISOLATED, ISOLATED, or CASCADING.

MASTER_NAME Returns the VARCHAR2 name of the master block in the given master-detail relationship.

NEXT_DETAIL_RELATION Returns the VARCHAR2 name of the next detail relation, if one exists. To get the name of the first detail for a given block, issue a call to GET_BLOCK_PROPERTY. Returns NULL if none exists.

NEXT_MASTER_RELATION Returns the VARCHAR2 name of the next relation, if one exists. To get the name of the first relation for a given block, issue a call to GET_BLOCK_PROPERTY. Returns NULL if one does not exist.

PREVENT_MASTERLESS_OPERATION Returns the VARCHAR2 value TRUE if this relation property is Yes, FALSE if it is No. When set to Yes, Form Builder does not allow records to be inserted in the detail block when there is no master record in the master block, and does not allow querying in the detail block when there is no master record from the database.

GET_RELATION_PROPERTY examples GET_RELATION_PROPERTY examples

Built-in: GET_RELATION_PROPERTY
** Example: If the relation is not deferred, then go
** coordinate the detail block. Otherwise, mark
** the detail block as being in need of
** coordination for an eventual deferred query.
*/
PROCEDURE Query_The_Details(rel_id Relation,
detail VARCHAR2) IS
BEGIN
IF Get_Relation_Property(rel_id, DEFERRED_COORDINATION)
= 'FALSE' THEN
Go_Block(detail);
IF NOT Form_Success THEN
RAISE Form_Trigger_Failure;
END IF;
Execute_Query;
ELSE
Set_Block_Property(detail, coordination_status,
NON_COORDINATED);
END IF;
End;

GET_REPORT_OBJECT_PROPERTY built-in

GET_REPORT_OBJECT_PROPERTY built-in

Examples

Description
Programmatically obtain a property of a report object.

Syntax
FUNCTION GET_REPORT_OBJECT_PROPERTY
(report_id REPORT_OBJECT,
property NUMBER
);

FUNCTION GET_REPORT_OBJECT_PROPERTY
(report_name VARCHAR2,
property NUMBER
);

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
report_id Specifies the unique ID of the report. You can get the report ID for a particular report using FIND_REPORT_OBJECT .

report_name Specifies the unique name of the report.

property One of the following constants:

REPORT_EXECUTION_MODE: Returns a string value of the report execution mode, either BATCH or RUNTIME

REPORT_COMM_MODE: Returns a string value of the report communication mode, either SYNCHRONOUS or ASYNCHRONOUS

REPORT_DESTYPE: Returns a string value of the report destination type, either PREVIEW, FILE, PRINTER, MAIL, CACHE or SCREEN

REPORT_FILENAME: Returns a string value of the report filename

REPORT_SOURCE_BLOCK: Returns a string value of the report source block name

REPORT_QUERY_NAME: Returns a string value of the report query name

REPORT_DESNAME: Returns a string value of the report destination name

REPORT_DESFORMAT: Returns a string value of the report destination format

REPORT_SERVER: Returns a string value of the report server name

REPORT_OTHER: Returns a string value of the other user-specified report properties

Usage Notes
GET_REPORT_OBJECT_PROPERTY returns a string value for all properties. In contrast, SET_REPORT_OBJECT_PROPERTY sets properties using constant or string values. The value type depends on the particular property being set.

GET_REPORT_OBJECT_PROPERTY examples GET_REPORT_OBJECT_PROPERTY examples GET_REPORT_OBJECT_PROPERTY_examples

DECLARE

repid REPORT_OBJECT;

report_prop VARCHAR2(20);

BEGIN

repid := find_report_object('report4');

report_prop := get_report_object_property(repid,
REPORT_EXECUTION_MODE);

message('REPORT EXECUTION MODE PROPERTY IS ' || report_prop);

report_prop := get_report_object_property(repid, REPORT_COMM_MODE);

message('REPORT COMM_MODE PROPERTY IS ' || report_prop);

report_prop := get_report_object_property(repid, REPORT_DESTYPE);

message('REPORT DESTYPE PROPERTY IS ' || report_prop);

report_prop := get_report_object_property(repid, REPORT_FILENAME);

message('REPORT_FILENAME PROPERTY IS ' || report_prop);

END;

GET_TAB_PAGE_PROPERTY built-in GET_TAB_PAGE_PROPERTY built-in

Examples Related Topics

Description
Returns property values for a specified tab page.

Syntax
FUNCTION GET_TAB_PAGE_PROPERTY
(tab_page_id TAB_PAGE,
property NUMBER);

FUNCTION GET_TAB_PAGE_PROPERTY
(tab_page_name VARCHAR2,
property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

Parameters
tab_page_id The unique ID Form Builder assigned to the tab page object when you created it. Use the FIND_TAB_PAGE built-in to return the ID to a variable of datatype TAB_PAGE.

tab page_name The name you gave the tab page object when you created it. Note: if two tab pages in the same form module share the same name, you must provide the canvas and tab page (e.g., CVS_1.TAB_PG_1).

property The property the value of which you want to get for the given tab page. The possible properties are as follows:

BACKGROUND_COLOR The color of the object's background region.
CANVAS_NAME Returns the VARCHAR2 name of the canvas to which the tab page belongs.

ENABLED Returns the VARCHAR2 string TRUE if a tab page is enabled, FALSE if it is disabled (i.e., greyed out and unavailable).

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

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

FONT_SIZE The size of the font, specified in points.

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

FONT_STYLE The style of the font.

FONT_WEIGHT The weight of the font.

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

LABEL Returns the VARCHAR2 string for the tab page label.

VISIBLE Returns the VARCHAR2 value TRUE if the tab page is visible, FALSE if it is not. A tab page is reported visible if it is currently mapped to the screen, even if it is entirely hidden behind another tab page.

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

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

GET_TAB_PAGE_PROPERTY examples GET_TAB_PAGE_PROPERTY examples

/* Use FIND_TAB_PAGE and GET_TAB_PAGE_PROPERTY to check

if a tab page is enabled:
*/
DECLARE
tp_id TAB_PAGE;
live VARCHAR2(32);

BEGIN
tp_id := FIND_TAB_PAGE('tab_page_1');
live := GET_TAB_PAGE_PROPERTY(tp_id, enabled);
END;

GET_TREE_NODE_PARENT built-in

GET_TREE_NODE_PARENT built-in

Examples

Description
Returns the parent of the specified node.

Syntax
FUNCTION GET_TREE_NODE_PARENT

(item_name VARCHAR2

node NODE);

FUNCTION GET_TREE_NODE_PARENT

(item_id ITEM

node NODE);

Returns NODE
Built-in Type unrestricted function

Enter Query Mode no

Parameters

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

GET_TREE_NODE_PARENT examples GET_TREE_NODE_PARENT examples

/*

Built-in: GET_TREE_NODE_PARENT
*/

-- This code could be used in a WHEN-TREE-NODE-SELECTED

-- trigger to locate the parent of the node that was

-- clicked on.

DECLARE

htree ITEM;

parent_node NODE;

BEGIN

-- Find the tree itself.

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

-- Get the parent of the node clicked on.

parent_node := Ftree.Get_Tree_Node_Parent(htree, :SYSTEM.TRIGGER_NODE);

...

END;

GET_TREE_NODE_PROPERTY built-in GET_TREE_NODE_PROPERTY built-in

Examples

Description
Returns the value of the specified property of the hierarchical tree node.

Syntax
FUNCTION GET_TREE_NODE_PROPERTY

(item_name VARCHAR2,

node NODE,

property NUMBER);

FUNCTION GET_TREE_NODE_PROPERTY

(item_id ITEM,

node NODE,

property NUMBER);

Returns VARCHAR2
Built-in Type unrestricted function

Enter Query Mode no

Parameters

item_name	Specifies the name of the object created at design time. The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable. The data type of the ID is ITEM.
node	Specifies a valid node.
property	Specify one of the following properties: NODE_STATE Returns the state of the hierarchical tree node. This is either EXPANDED_NODE, COLLAPSED_NODE, or LEAF_NODE. NODE_DEPTH Returns the nesting level of the hierarchical tree node. NODE_LABEL Returns the label NODE_ICON Returns the icon name NODE_VALUE Returns the value of the hierarchical tree node.

GET_TREE_NODE_PROPERTY examples GET_TREE_NODE_PROPERTY examples

/*

Built-in: GET_TREE_NODE_PROPERTY
*/

-- This code could be used in a WHEN-TREE-NODE-SELECTED

-- trigger to return the value of the node that was

-- clicked on.

DECLARE

htree ITEM;

node_value VARCHAR2(100);

BEGIN

-- Find the tree itself.

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

-- Find the value of the node clicked on.

node_value := Ftree.Get_Tree_Node_Property(htree, :SYSTEM.TRIGGER_NODE, Ftree.NODE_VALUE);

...

END;

GET_TREE_PROPERTY built-in GET_TREE_PROPERTY built-in

Examples

Description
Returns property values of the specified hierarchical tree.

Syntax
FUNCTION GET_TREE_PROPERTY

(item_name VARCHAR2,

property NUMBER);

FUNCTION GET_TREE_PROPERTY

(item_id ITEM,

property NUMBER);

Returns VARCHAR2
Built-in Type unrestricted function

Enter Query Mode no

Parameters

item_name	Specifies the name you gave the object when you created it. The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable. The data type of the ID is ITEM.
property	Specify one of the following properties: DATASOURCE Returns the source used to initially populate the hierarchical tree, either in Form Builder or by using the SET_TREE_PROPERTY built-in. Returns EXTERNAL if neither property was set in Form Builder. RECORD_GROUP Returns the RecordGroup used to initially populate the hierarchical tree, either in Form Builder or by using the SET_TREE_PROPERTY built-in.. This may be a null string. QUERY_TEXT Returns the text of the query used to initially populate the hierarchical tree, either in Form Builder or by using the SET_TREE_PROPERTY built-in.. This may be a null string. NODE_COUNT Returns the number of rows in the hierarchical tree data set. SELECTION_COUNT Returns the number of selected rows in the hierarchical tree. ALLOW_EMPTY_BRANCHES Returns the character string TRUE or FALSE. ALLOW_MULTI-SELECT Returns the character string TRUE or FALSE.

Usage Notes
The values returned by datasource RECORD_GROUP and QUERY_TEXT do not necessarily reflect the current data or state of the tree.

GET_TREE_PROPERTY examples GET_TREE_PROPERTY examples

/*

Built-in: GET_TREE_PROPERTY
*/

-- This code could be used to find out how many nodes are

-- in a given tree.

DECLARE

htree ITEM;

node_count NUMBER;

BEGIN

-- Find the tree itself.

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

-- Get the node count of the tree.

node_count := Ftree.Get_Tree_Property(htree, Ftree.NODE_COUNT);

...

END;

GET_TREE_SELECTION built-in GET_TREE_SELECTION built-in

Examples

Description
Returns the data node indicated by selection. Selection is an index into the list of selected nodes.

Syntax
FUNCTION GET_TREE_SELECTION

(item_name VARCHAR2,

selection NUMBER);

FUNCTION GET_TREE_SELECTION

(item_id ITEM,

selection NUMBER);

Returns NODE

Built-in Type unrestricted function

Enter Query Mode no

Parameters

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

GET_TREE_SELECTION examples GET_TREE_SELECTION examples

/*

Built-in: GET_TREE_SELECTION
*/

-- This code will process all tree nodes marked as selected. See the

-- Ftree.Set_Tree_Selection built-in for a definition of "selected".

DECLARE

htree ITEM;

num_selected NUMBER;

current_node NODE;

BEGIN

-- Find the tree itself.

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

-- Find the number of nodes marked as selected.

num_selected := Ftree.Get_Tree_Property(htree, Ftree.SELECTION_COUNT);

-- Loop through selected nodes and process them. If you are deleting

-- nodes, be sure to loop in reverse!

FOR j IN 1..num_selected LOOP

current_node := Ftree.Get_Tree_Selection(htree, j);

...

END LOOP;

END;

GET_VA_PROPERTY built-in GET_VA_PROPERTY built-in

Description
Returns visual attribute property values for the specified property.

Syntax
FUNCTION GET_VA_PROPERTY

(va_id VISUALATTRIBUTE

property NUMBER);

FUNCTION GET_VA_PROPERTY

(va_name VARCHAR2

property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

Parameters

a_id	The unique ID Form Builder assinged to the visual attribute when you created it. The data type is VISUALATTRIBUTE.
a_name	The name you gave the visual attribute when you created it. The data type is VARCHAR2.
property	Specify one of the following properties: BACKGROUND_COLOR The color of the object's background region. FILL_PATTERN The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color. FONT_NAME The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent. FONT_SIZE The size of the font, specified in hundreds of points. For example, 8pt. would be 800. FONT_SPACING The width of the font, that is, the amount of space between characters (kerning). FONT_STYLE The style of the font. FONT_WEIGHT The weight of the font. FOREGROUND_COLOR The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item. WHITE_ON_BLACK Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

GET_VAR_BOUNDS GET_VAR_BOUNDS

Description
Obtains the bounds of an OLE variant's array.

Syntax
PROCEDURE GET_VAR_BOUNDS
(var OLEVAR, bounds OLE_SAFEARRAYBOUNDS);

Built-in Type unrestricted procedure

Parameters

ar	The variant.
bounds	The PL/SQL table that is populated with the bounds of the array. For more information about the contents and layout of this parameter, see Array Types for OLE Support

GET_VAR_DIMS GET_VAR_DIMS

Description
Determines if an OLE variant is an array, and if so, obtains the number of dimensions in that array.

Syntax
FUNCTION GET_VAR_DIMS
(var OLEVAR)
RETURN vardims PLS_INTEGER;

Built-in Type unrestricted function
Returns A value of zero (0) if the variant is not an array. Otherwise, the return value is the number of dimensions in the array.

Parameters

ar	The variant.

GET_VAR_TYPE GET_VAR_TYPE

Description
Obtains the type of an OLE variant.

Syntax
FUNCTION GET_VAR_TYPE
(var OLEVAR)
RETURN vartype VT_TYPE;

Built-in Type unrestricted function

Returns type of the variable

Parameters

ar	The variant.
artype	Type of the variant.

Usage Notes
A list of the supported VT_TYPEs can be found in OLE Variant Types .

GET_VERB_COUNT GET_VERB_COUNT

Examples Restrictions Related Topics

Description
Returns the number of verbs that an OLE server recognizes. An OLE verb specifies the action that you can perform on an OLE object, and the number of verbs available depends on the OLE server. The number of verbs is returned as a VARCHAR2 string and must be converted to NUMBER for use in determining the verb index and verb name for each verb. You must define an appropriately typed variable to accept the return value.

Syntax
FUNCTION GET_VERB_COUNT
(item_id Item);

FUNCTION GET_VERB_COUNT
(item_name VARCHAR2);

Returns VARCHAR2

Built-in Type unrestricted function

Enter Query Mode no

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

GET_VERB_COUNT restrictions GET_VERB_COUNT restrictions

Valid only on Microsoft Windows and Macintosh.

GET_VERB_COUNT examples GET_VERB_COUNT examples

Built-in: GET_VERB_COUNT
** Example: Obtains the number of verbs that the OLE server
** issues and recognizes when executed from the OLE container.
** Trigger: When-Button-Pressed
*/
DECLARE
item_id ITEM;
item_name VARCHAR(25) := 'OLEITM';
verb_cnt_str VARCHAR(20);
verb_cnt NUMBER;
verb_name VARCHAR(20);
loop_cntr NUMBER;
BEGIN
item_id := Find_Item(item_name);
IF Id_Null(item_id) THEN
message('No such item: '||item_name);
ELSE
verb_cnt_str := Get_Verb_Count(item_id);
verb_cnt := TO_NUMBER(verb_cnt_str);
FOR loop_cntr in 1..verb_cnt LOOP
verb_name := Get_Verb_Name(item_id,loop_cntr);
IF verb_name = 'Edit' THEN
Exec_Verb(item_id,verb_name);
END IF;
END LOOP;
END IF;
END;

GET_VERB_NAME

GET_VERB_NAME

Examples Restrictions Related Topics

Description
Returns the name of the verb that is associated with the given verb index. An OLE verb specifies the action that you can perform on an OLE object, and each OLE verb has a corresponding OLE verb index. You must define an appropriately typed variable to accept the return value.

Syntax
FUNCTION GET_VERB_NAME
(item_id Item,
verb_index VARCHAR2);

FUNCTION GET_VERB_NAME
(item_name VARCHAR2,
verb_index VARCHAR2);

Returns VARCHAR 2

Built-in Type unrestricted function

Enter Query Mode no

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

erb_index Specifies the numeric index of a verb. Use the FIND_OLE_VERB built-in to obtain this value. The data type of index is VARCHAR2.

GET_VERB_NAME restrictions

GET_VERB_NAME restrictions

Valid only on Microsoft Windows and Macintosh.

GET_VERB_NAME examples GET_VERB_NAME examples

Built-in: GET_VERB_COUNT
** Example: See EXEC_VERB and GET_VERB_COUNT
*/

GET_VIEW_PROPERTY built-in

GET_VIEW_PROPERTY built-in

Examples Related Topics

Description
Returns the indicated property setting for the indicated canvas.

Syntax
FUNCTION GET_VIEW_PROPERTY
(view_id ViewPort,
property NUMBER);

FUNCTION GET_VIEW_PROPERTY
(view_name VARCHAR2,
property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

Parameters

iew_id Specifies the unique ID that Form Builder assigns the canvas when it creates the object. Use the FIND_VIEW built-in to return the ID to an appropriately typed variable. The data type of the ID is ViewPort.
iew_name Specifies the name that you gave the object when defining it.

property Specifies the property whose state you want to get for the given canvas. You must make a separate call to GET_VIEW_PROPERTY for each property you need, as shown in the example. You can enter one of the following constants to obtain return values:

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

HEIGHT Returns the height of the view. For a content view, the height of the view is actually the height of the window in which the view is currently displayed. The size of each unit depends on how you defined the Coordinate System property for the form module.

VIEWPORT_X_POS For a stacked canvas, returns the x coordinate that reflects the current placement of the view's upper left corner relative to the upper left corner of the window's current content canvas. For a content view, returns 0. The value is returned as a VARCHAR2 and is expressed in the units defined by the form module Coordinate System property.

VIEWPORT_Y_POS For a stacked canvas, returns the y coordinate that reflects the current placement of the view's upper left corner relative to the upper left corner of the window's current content canvas. For a content view, returns 0. The value is returned as a VARCHAR2 and is expressed in the units defined by the form module Coordinate System property.

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

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

VISIBLE Returns the VARCHAR2 value TRUE if the view is visible, FALSE if it is not. A view is reported visible when it is a) in front of all other views in the window or b) only partially obscured by another view. A view is reported not visible when it is a) a stacked view that is behind the content view or b) completely obscured by a single stacked view. Note that this property is independent of the current window display state. Thus a view can be reported visible even when its window is currently hidden or iconified.

WIDTH Returns the width of the view. For a content view, the width of the view is actually the width of the window in which the view is currently displayed. The size of each unit depends on how you defined the Coordinate System property for the form module.

WINDOW_NAME Returns the name of the window where this canvas is displayed.

GET_VIEW_PROPERTY examples GET_VIEW_PROPERTY examples

Built-in: GET_VIEW_PROPERTY
** Example: Use the Width, and display position of one
** stacked view (View1) to determine where to
** position another one (View2) immediately to its
** right.
*/
PROCEDURE Anchor_To_Right( View2 VARCHAR2, View1 VARCHAR2) IS
vw_id1 ViewPort;
vw_id2 ViewPort;
x NUMBER;
y NUMBER;
w NUMBER;
BEGIN
/*
** Find View1 and get its (x,y) position, width
*/
vw_id1 := Find_View(View1);
x := Get_View_Property(vw_id1,VIEWPORT_X_POS);
y := Get_View_Property(vw_id1,VIEWPORT_Y_POS);
w := Get_View_Property(vw_id1,WIDTH);
/*
** Anchor View2 at (x+w,y+h)
*/
vw_id2 := Find_View(View2);
Set_View_Property(vw_id2,VIEWPORT_X_POS, x+w );
Set_View_Property(vw_id2,VIEWPORT_Y_POS, y );
END;

GET_WINDOW_PROPERTY built-in

GET_WINDOW_PROPERTY built-in

Related Topics

Description
Returns the current setting for the indicated window property for the given window.

Syntax
FUNCTION GET_WINDOW_PROPERTY
(window_id Window,
property NUMBER);

FUNCTION GET_WINDOW_PROPERTY
(window_name VARCHAR2,
property NUMBER);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

Usage Notes
On Microsoft Windows, you can reference the MDI application window with the constant FORMS_MDI_WINDOW.

Parameters
window_id Specifies the unique ID that Form Builder assigns the window at the time it creates it. Use the FIND_WINDOW built-in to return the ID to an appropriately typed variable. The data type of the ID is Window.

window_name Specifies the name that you gave the window when creating it.

property You must make a separate call to GET_WINDOW_PROPERTY for each property you need, as shown in the FIND_WINDOW example. Specify one of the following constants to get the current value or state of the property:

BACKGROUND_COLOR The color of the object's background region.

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

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

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

FONT_SIZE The size of the font, specified in points.

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

FONT_STYLE The style of the font.

FONT_WEIGHT The weight of the font.

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

HEIGHT Returns the height of the window.

HIDE_ON_EXIT Returns the VARCHAR2 value TRUE if the window has the Remove On Exit property set to Yes, otherwise, it is FALSE.

TITLE Returns the title of the window.

VISIBLE Returns the VARCHAR2 value TRUE if the window is visible, FALSE if it is not. A window is reported visible if it is currently mapped to the screen, even if it is entirely hidden behind another window or iconified (minimized).

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

WIDTH Returns the width of the window.

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

WIDOW_SIZE Returns the width and height of the window as a string, separated by commas.

WINDOW_STATE Returns the current display state of the window. The display state of a window is the VARCHAR2 string NORMAL, MAXIMIZE, or MINIMIZE.

X_POS Returns the x coordinate that reflects the window's current display position on the screen.

Y_POS Returns the y coordinate that reflects the window's current display position on the screen.

GO_BLOCK built-in GO_BLOCK built-in

Examples Related Topics

Description
GO_BLOCK navigates to an indicated block. If the target block is non-enterable, an error occurs.

Syntax
PROCEDURE GO_BLOCK
(block_name VARCHAR2);

Built-in Type restricted procedure

Enter Query Mode no

Parameters
block_name Specifies the name you gave the block when defining it. The data type of the name is VARCHAR2.

GO_BLOCK examples GO_BLOCK examples

Built-in: GO_BLOCK
** Example: Navigate to a block by name. Make sure to check
** that the Go_Block succeeds by checking FORM_SUCCESS.
*/
BEGIN
IF :Global.Flag_Indicator = 'NIGHT' THEN
Go_Block('Night_Schedule');
/*
** One method of checking for block navigation success.
*/
IF NOT FORM_SUCCESS THEN
RAISE Form_Trigger_Failure;
END IF;
ELSIF :Global.Flag_Indicator = 'DAY' THEN
Go_Block('Day_Schedule');
/*
** Another way of checking that block navigation
** succeeds. If the block the cursor is in hasn't
** changed after a block navigation, something went
** wrong. This method is more reliable than simply
** checking FORM_SUCCESS.
*/
IF :System.Trigger_Block = :System.Cursor_Block THEN
RAISE Form_Trigger_Failure;
END IF;
END IF;
Execute_Query;
Go_Block('Main');
END;

GO_FORM built-in

GO_FORM built-in

Restrictions Related Topics

Description
In a multiple-form application, navigates from the current form to the indicated target form. When navigating with GO_FORM, no validation occurs and no triggers fire except WHEN-WINDOW-DEACTIVATED, which fires for the form that initiates navigation, and WHEN-WINDOW-ACTIVATED, which fires for the target window in the target form.

Attempting to navigate to a form that has not yet been opened raises an error.

Syntax
PROCEDURE GO_FORM
(form_id FORMMODULE);

PROCEDURE GO_FORM
(form_name VARCHAR2);

Built-in Type restricted procedure

Enter Query Mode no

Parameters
form_id The unique ID that is assigned to the form dynamically when it is instantiated at runtime. Use the FIND_FORM built-in to return the ID to an appropriately typed variable. The data type of the ID is FORMMODULE.

form_name The name of the target form. The data type of name is VARCHAR2. The GO_FORM built-in attempts to search for the form module name, not the name of the .fmx file.

GO_FORM restrictions GO_FORM restrictions

The target form cannot be a form that is currently disabled as a result of having invoked another form with CALL_FORM.

GO_ITEM built-in GO_ITEM built-in

Examples Restrictions Related Topics

Description
GO_ITEM navigates to an indicated item. GO_ITEM succeeds even if the target item has the Keyboard Navigable property set to No.

Syntax
PROCEDURE GO_ITEM
(item_id Item);

PROCEDURE GO_ITEM
(item_name VARCHAR2);

Built-in Type restricted procedure

Enter Query Mode yes

Parameters
item_id Specifies the unique ID that Form Builder assigns to the item when created. The data type of the ID is Item.

item_name Specifies the string you defined as the name of the item at design time. The data type of the name is VARCHAR2.

GO_ITEM restrictions GO_ITEM restrictions

GO_ITEM('emp.ename');

In Enter Query mode, GO_ITEM cannot be used to navigate to an item in a different block.

You cannot use GO_ITEM to navigate to a non-navigable item, such as a VARCHAR2t item or display item.

GO_ITEM examples GO_ITEM examples

Built-in: GO_ITEM
** Example: Invoke a dialog window by navigating to
** an item which is on the canvas which the window
** displays.
*/
PROCEDURE Open_Preference_Dialog IS
BEGIN
Go_Item('pref_dialog.printer_name');
END;

GO_RECORD built-in

GO_RECORD built-in

Examples Restrictions Related Topics

Description
Navigates to the record with the specified record number.

Syntax
PROCEDURE GO_RECORD
(record_number NUMBER);

Built-in Type restricted procedure

Enter Query Mode no

Parameters
record_number Specifies any integer value that PL/SQL can evaluate to a number. This includes values derived from calls to system variables, such as TO_NUMBER(:SYSTEM.TRIGGER_RECORD) + 8.

You can use the system variables SYSTEM.CURSOR_RECORD or SYSTEM.TRIGGER_RECORD to determine a record's sequence number.

GO_RECORD restrictions GO_RECORD restrictions

If the query is open and the specified record number is greater than the number of records already fetched, Form Builder fetches additional records to satisfy the call to this built-in.

GO_RECORD examples GO_RECORD examples

Built-in: GO_RECORD
** Example: Navigate to a record in the current block
** by record number. Also see FIRST_RECORD and
** LAST_RECORD built-ins.
*/
BEGIN
Go_Record( :control.last_record_number );
END;

HELP built-in

HELP built-in

Examples Related Topics

Description
Displays the current item's hint message on the message line. If the hint message is already displayed, HELP displays the detailed help screen for the item.

Syntax
PROCEDURE HELP;

Built-in Type restricted procedure

Enter Query Mode yes

Parameters
none

HELP examples HELP examples

/*

Built-in: HELP
** Example: Gives item-level hint/help.
*/
BEGIN
Help;
END;

HIDE_MENU built-in

HIDE_MENU built-in

Examples

Description
On character mode platforms, makes the current menu disappear if it is currently displayed, uncovering any part of the form display that the menu had covered. The menu will redisplay if the SHOW_MENU built-in is invoked or the operator presses [Menu].

Syntax
PROCEDURE HIDE_MENU;

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
none

HIDE_MENU examples HIDE_MENU examples

/*

Built-in: HIDE_MENU
** Example: Hides the menu from view on character-mode or
** block-mode devices
*/
BEGIN
Hide_Menu;
END;

HIDE_VIEW built-in

HIDE_VIEW built-in

Examples Related Topics

Description
Hides the indicated canvas.

Syntax
PROCEDURE HIDE_VIEW
(view_id ViewPort);

PROCEDURE HIDE_VIEW
(view_name VARCHAR2);

Built-in Type unrestricted procedure

Enter Query Mode yes

Description
Hides the indicated canvas.

Parameters

iew_id Specifies the unique ID that Form Builder assigns the view at the time it creates it. Use the FIND_VIEW built-in to return the ID to an appropriately typed variable. The data type of the ID is ViewPort.
iew_name Specifies the name that you gave the view when creating it.

HIDE_VIEW examples

HIDE_VIEW examples

/*

Built-in: HIDE_VIEW
** Example: Programmatically dismiss a stacked view from the
** operator's sight.
*/
PROCEDURE Hide_Button_Bar IS
BEGIN
Hide_View('Button_Bar');
END;

HIDE_WINDOW built-in

HIDE_WINDOW built-in

Examples Related Topics

Description
Hides the given window. HIDE_WINDOW is equivalent to setting VISIBLE to No by calling SET_WINDOW_PROPERTY.

Syntax
PROCEDURE HIDE_WINDOW
(window_id Window);

PROCEDURE HIDE_WINDOW
(window_name VARCHAR2);

Built-in Type unrestricted procedure

Enter Query Mode yes

window_name Specifies the name that you gave the window when creating it.

HIDE_WINDOW examples HIDE_WINDOW examples

/*

Built-in: HIDE_WINDOW
** Example: When a main window is closed, hide other
** "subordinate" windows automatically. To
** establish this window hierarchy we might define
** a static record group in the form called
** 'WINDOW_HIERARCHY' with a structure of:
**
** Parent_Window Child_Window
** ------------- -------------
** MAIN DETAIL1
** MAIN DETAIL2
** DETAIL1 DETAIL3
** DETAIL1 DETAIL4
** DETAIL2 DETAIL5
** DETAIL3 DETAIL6
**
** We also have to make sure we navigate to some
** item not on any of the canvases shown in the
** windows we are closing, or else that window
** will automatically be re-displayed by forms
** since it has input focus.
*/
PROCEDURE Close_Window( wn_name VARCHAR2,
dest_item VARCHAR2 ) IS
rg_id RecordGroup;
gc_parent GroupColumn;
gc_child GroupColumn;
the_Rowcount NUMBER;
/*
** Local function called recursively to close children at
** all levels of the hierarchy.
*/
PROCEDURE Close_Win_With_Children( parent_win VARCHAR2 ) IS
the_child VARCHAR2(40);
the_parent VARCHAR2(40);
BEGIN
FOR j IN 1..the_Rowcount LOOP
the_parent := Get_Group_Char_Cell(gc_parent,j);
/* If we find a matching parent in the table */
IF UPPER(the_parent) = UPPER(parent_win) THEN
the_child := Get_Group_Char_Cell(gc_child,j);
/*
** Close this child and any of its children
*/
Close_Win_With_Children( the_child );
END IF;
END LOOP;
/*
** Close the Parent
*/
Hide_Window( parent_win );
END;
BEGIN
/*
** Setup
*/
rg_id := Find_Group('WINDOW_HIERARCHY');
gc_parent := Find_Column('WINDOW_HIERARCHY.PARENT_WINDOW');
gc_child := Find_Column('WINDOW_HIERARCHY.CHILD_WINDOW');
the_Rowcount := Get_Group_Row_Count(rg_id);
/* Close all the child windows of 'wn_name' */
Close_Win_With_Children( wn_name );
/* Navigate to the Destination Item supplied by the caller */
Go_Item( dest_item );
END;

HOST built-in

HOST built-in

Examples

Description
Executes an indicated operating system command.

Syntax
PROCEDURE HOST
(system_command_string VARCHAR2);

PROCEDURE HOST
(system_command_string VARCHAR2,
screen_action NUMBER);

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
system_command_ string Specifies the system command you want to pass to your particular operating system.

screen_action Specifies one of the following constants:

no parameter Specifies that Form Builder will:

clear the screen

prompt the operator to return from the command

NO_PROMPT Specifies that Form Builder will:

clear the screen (does not prompt the operator to return from the command)

NO_SCREEN Specifies that Form Builder will:

not clear the screen

not prompt the operator to return from the system command

(The HOST command should not send output to the screen when using the NO_SCREEN parameter.)

Note: Thescreen_action parameter is only relevant to applications running in character mode, where the output of the Host command is displayed in the same window as the form. In GUI applications, the output of the Host command is displayed in a separate window.

HOST examples HOST examples

/*

built-in: HOST
** Example: Execute an operating system command in a
** subprocess or subshell. Uses the
** 'Get_Connect_Info' procedure from the
** GET_APPLICATION_PROPERTY example.
*/
PROCEDURE Mail_Warning( send_to VARCHAR2) IS
the_username VARCHAR2(40);
the_password VARCHAR2(40);
the_connect VARCHAR2(40);
the_command VARCHAR2(2000);
BEGIN
/*
** Get Username, Password, Connect information
*/
Get_Connect_Info(the_username,the_password,the_connect);
/*
** Concatenate together the static text and values of
** local variables to prepare the operating system command
** string.
*/
the_command := 'orasend '||
' to='||send_to||
' std_warn.txt '||
' subject="## LATE PAYMENT ##"'||
' user='||the_username||
' password='||the_password||
' connect='||the_connect;

Message('Sending Message...', NO_ACKNOWLEDGE);
Synchronize;
/*
** Execute the command string as an O/S command The
** NO_SCREEN option tells forms not to clear the screen
** while we do our work at the O/S level "silently".
*/
Host( the_command, NO_SCREEN );
/*
** Check whether the command succeeded or not
*/
IF NOT Form_Success THEN
Message('Error -- Message not sent.');
ELSE
Message('Message Sent.');
END IF;
END;

ID_NULL built-in

ID_NULL built-in

Examples Related Topics

Description
Returns a BOOLEAN value that indicates whether the object ID is available.

Syntax
FUNCTION ID_NULL
(Alert BOOLEAN);

FUNCTION ID_NULL
(Block BOOLEAN);
FUNCTION ID_NULL
(Canvas BOOLEAN);
FUNCTION ID_NULL
(Editor BOOLEAN);
FUNCTION ID_NULL
(FormModule BOOLEAN);
FUNCTION ID_NULL
(GroupColumn BOOLEAN);
FUNCTION ID_NULL
(Item BOOLEAN);
FUNCTION ID_NULL
(LOV BOOLEAN);
FUNCTION ID_NULL
(MenuItem BOOLEAN);
FUNCTION ID_NULL
(ParamList BOOLEAN);
FUNCTION ID_NULL
(RecordGroup BOOLEAN);
FUNCTION ID_NULL
(Relation BOOLEAN);
FUNCTION ID_NULL
(Timer BOOLEAN);
FUNCTION ID_NULL
(Viewport BOOLEAN);
FUNCTION ID_NULL
(Window BOOLEAN);

Built-in Type unrestricted function

Returns BOOLEAN

Enter Query Mode yes

Parameters
object_id You can call this function to test results of the following object ID types:

Alert

Block

Canvas

Editor

FormModule

GroupColumn

Item

LOV

MenuItem

ParamList

RecordGroup

Relation

Timer

Viewport

Window

Usage Notes

Use ID_NULL when you want to check for the existence of an object created dynamically at runtime. For example, if a specific record group already exists, you will receive an error message if you try to create that record group. To perform this check, follow this general process:

Use the appropriate FIND_ built-in to obtain the object ID.

Use ID_NULL to check whether an object with that ID already exists.

If the object does not exist, proceed to create it.

If you are going to test for an object�s existence at various times (that is, more than once during a run), then you need to reissue the appropriate FIND_ every time � once preceding each use of ID_NULL.

ID_NULL examples ID_NULL examples

See CREATE_GROUP

IMAGE_SCROLL built-in IMAGE_SCROLL built-in

Examples

Description
Scrolls the image item as close to the specified offset (the X,Y coordinates) as possible. This is useful if the image is bigger than the image item.

Syntax
PROCEDURE IMAGE_SCROLL
(item_name VARCHAR2,
X NUMBER,
Y NUMBER
);

PROCEDURE IMAGE_SCROLL
(item_id ITEM,
X NUMBER,
Y NUMBER
);

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
item_id Specifies the unique ID Form Builder assigns when it creates the image item.

item_name Specifies the name you gave the image when defining it.
X The X coordinate of the offset.

Y The Y coordinate of the offset.

IMAGE_SCROLL examples IMAGE_SCROLL examples

For example, suppose the image is twice the size of the image item, that is, the image coordinates are 0, 200, and the item coordinates are 0, 100. To roughly center the image, you can set IMAGE_SCROLL X, Y coordinates to 50, 50. This sets the top left corner of the item at 50 50 instead of 0, 0, which offsets the image so that it is displayed from its coordinates of 50 to 150.

IMAGE_ZOOM built-in IMAGE_ZOOM built-in

Examples Related Topics

Description
Zooms the image in or out using the effect specified in zoom_type and the amount specified in zoom_factor.

Syntax
PROCEDURE IMAGE_ZOOM
(image_id ITEM,
zoom_type NUMBER);

PROCEDURE IMAGE_ZOOM
(image_name VARCHAR2,
zoom_type NUMBER);
PROCEDURE IMAGE_ZOOM
(image_id ITEM,
zoom_type NUMBER,
zoom_factor NUMBER);
PROCEDURE IMAGE_ZOOM
(image_name VARCHAR2,
zoom_type NUMBER,
zoom_factor NUMBER);

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
image_id Specifies the unique ID Form Builder assigns when it creates the image item. The data type of the ID is ITEM.

image_name Specifies the name you gave the image when defining it.

zoom_type Specify one of the following constants to describe the effect you want to have on the image displayed:

ADJUST_TO_FIT Scales the image to fit within the display rectangle: the entire image is visible and the image fills as much of the image item as possible without distorting the image.

SELECTION_RECTANGLE Scales the image so the selected region fully fills the image item.

ZOOM_IN_FACTOR Enlarges the image by the zoom_factor.

ZOOM_OUT_FACTOR Reduces the image by the zoom_factor.

ZOOM_PERCENT Scales the image to the percentage indicated in zoom_factor.

zoom_factor Specifies either the factor or the percentage to which you want the image zoomed. Supply a whole number for this argument.

Usage Notes

Check zoom_factor for reasonableness. For example, specifying a ZOOM_IN_FACTOR of 100 would increase the size of your image 100 times, and could cause your application to run out of memory.

When specifying ZOOM_IN_FACTOR or ZOOM_OUT_FACTOR, you can use any positive integer value for zoom_factor, but performance is optimal if you use 2, 4, or 8.

When specifying ZOOM_PERCENT, you can use any positive integer value for zoom_factor. To enlarge the image, specify a percentage greater than 100.

The operator must use the mouse to select a region before specifying SELECTION_RECTANGLE, or Form Builder will return an error message.

Your design should include scroll bars on images that use SELECTION_RECTANGLE.

Valid for both color and black-and-white images.

IMAGE_ZOOM examples IMAGE_ZOOM examples

The following example shows a When-Button-Pressed trigger that doubles the size of the image every time the button is pressed.

Image_Zoom('my_image', zoom_in_factor, 2);

INIT-OLEARGS INIT_OLEARGS

Description
Establishes how many arguments are going to be defined and passed to the OLE object's method,

Syntax
PROCEDURE INIT_OLEARGS (num_args NUMBER);

Built-in Type unrestricted procedure

Parameters

num_args

Number of arguments that are to be passed to the method -- plus one.

Usage Notes

This built-in should be called before establishing the arguments' types and values with ADD_OLEARG.
This built-in and ADD_OLEARG would also be used to prepare for GET_OLE_* calls if the property is accessed (for example, with an index).
It is not necessary to use INIT_OLEARGS before a GET_OLE_* call if that call does not take OLE parameters.
Note that the number specified in num_args should be one more than the number of actual arguments. (Thus, if four arguments are to be passed, set num_arg to be five ). This increase is required only in preparation for GET_OLE_* calls, not for CALL_OLE, but does no harm in the latter case.

INITIALIZE_CONTAINER

INITIALIZE_CONTAINER

Examples Restrictions Related Topics

Description
Inserts an OLE object from a server-compatible file into an OLE container.

Syntax
PROCEDURE INITIALIZE_CONTAINER
(item_id Item,
file_name VARCHAR2);

PROCEDURE INITIALIZE_CONTAINER
(item_name VARCHAR2,
file_name VARCHAR2);

Built-in Type unrestricted procedure

Enter Query Mode no

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

file_name Specifies the name of the file containing the object for insertion into an OLE container. Include the path of the file location.

INITIALIZE_CONTAINER restrictions INITIALIZE_CONTAINER restrictions

Valid only on Microsoft Windows and Macintosh.

INITIALIZE_CONTAINER examples INITIALIZE_CONTAINER examples

/*

Built-in: INITIALIZE_CONTAINER
** Example: Initializes an OLE container by inserting an object
** from a specified file into an OLE container.
** Trigger: When-Button-Pressed
*/
DECLARE
item_id ITEM;
item_name VARCHAR(25) := 'OLEITM';
BEGIN
item_id := Find_Item(item_name);
IF Id_Null(item_id) THEN
message('No such item: '||item_name);
ELSE
Initialize_Container(item_id,'c:\OLE\oleobj.xls');
END IF;
END;

INSERT_RECORD built-in

INSERT_RECORD built-in

Examples Restrictions Related Topics

Description
When called from an On-Insert trigger, inserts the current record into the database during Post and Commit Transactions processing. This built-in is included primarily for applications that will run against a non-ORACLE datasource.

Syntax
PROCEDURE INSERT_RECORD;

Built-in Type restricted procedure

Enter Query Mode no

Parameters
none

INSERT_RECORD restrictions INSERT_RECORD restrictions

Valid only in an On-Insert trigger.

INSERT_RECORD examples INSERT_RECORD examples

/*

Built-in: INSERT_RECORD
** Example : Perform Form Builder standard insert processing
** based on a global flag setup at startup by the
** form, perhaps based on a parameter.
** Trigger: On-Insert
*/
BEGIN
/*
** Check the global flag we setup at form startup
*/
IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
User_Exit('my_insrec block=EMP');
/*
** Otherwise, do the right thing.
*/
ELSE
Insert_Record;
END IF;
END;

ISSUE_ROLLBACK built-in

ISSUE_ROLLBACK built-in

Examples Restrictions Related Topics

Description
When called from an On-Rollback trigger, initiates the default Form Builder processing for rolling back to the indicated savepoint.

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

Syntax
PROCEDURE ISSUE_ROLLBACK
(savepoint_name VARCHAR2);

Built-in Type unrestricted procedure

Enter Query Mode no

Parameters
savepoint name Name of the savepoint to which you want to rollback. A null savepoint_name causes a full rollback.

ISSUE_ROLLBACK restrictions ISSUE_ROLLBACK restrictions

Results are unpredictable when ISSUE_ROLLBACK is used outside an On-Rollback trigger or when used with a savepoint other than that provided by a call to GET_APPLICATION_PROPERTY(SAVEPOINT_NAME).

ISSUE_ROLLBACK examples ISSUE_ROLLBACK examples

/*

Built-in: ISSUE_ROLLBACK
** Example: Perform Form Builder standard Rollback processing.
** Decide whether to use this built-in based on a
** global flag setup at startup by the form.
** perhaps based on a parameter.
** Trigger: On-Rollback
*/
DECLARE
sp_name VARCHAR2(80);
BEGIN
/*
** Get the name of the savepoint to which Form Builder needs to
** rollback. (NULL = Full Rollback)
*/
sp_name := Get_Application_Property(SAVEPOINT_NAME);
/*
** Check the global flag we setup at form startup
*/
IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
User_Exit('my_rollbk name='||sp_name);
ELSE
Issue_Rollback(sp_name);
END IF;
END;

ISSUE_SAVEPOINT built-in

ISSUE_SAVEPOINT built-in

Examples Restrictions Related Topics

Description
When called from an On-Savepoint trigger, ISSUE_SAVEPOINT initiates the default processing for issuing a savepoint. You can use GET_APPLICATION_PROPERTY (SAVEPOINT_NAME) to determine the name of the savepoint that Form Builder would be issuing by default, if no On-Savepoint trigger were present.

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

Syntax
PROCEDURE ISSUE_SAVEPOINT
(savepoint_name VARCHAR2);

Built-in Type unrestricted procedure

Enter Query Mode no

Parameters
savepoint _name Name of the savepoint you want to be issued

ISSUE_SAVEPOINT restrictions ISSUE_SAVEPOINT restrictions

Never issue a savepoint with the name FM_<number>, unless the savepoint name was provided by a call to GET_APPLICATION_PROPERTY. Doing so may cause a conflict with savepoints issued by Form Builder.

ISSUE_SAVEPOINT examples ISSUE_SAVEPOINT examples

/*

Built-in: ISSUE_SAVEPOINT
** Example: Perform Form Builder standard savepoint processing.
** Decide whether to use this built-in based on a
** global flag setup at startup by the form,
** perhaps based on a parameter.
** Trigger: On-Savepoint
*/
DECLARE
sp_name VARCHAR2(80);
BEGIN
/* Get the name of the savepoint Form Builder needs to issue
*/
sp_name := Get_Application_Property(SAVEPOINT_NAME);
/* Check the global flag we setup at form startup
*/
IF :Global.Using_Transactional_Triggers = 'TRUE' THEN
User_Exit('my_savept name='||sp_name);
/* Otherwise, do the right thing.
*/
ELSE
Issue_Savepoint(sp_name);
END IF;
END;

ITEM_ENABLED built-in

ITEM_ENABLED built-in

Related Topics

Description
Returns the Boolean value TRUE when the menu item is enabled. Returns the Boolean value FALSE when the menu item is disabled.

Note: ITEM_ENABLED is equivalent to GET_MENU_ITEM_PROPERTY (MENU_ITEM, ENABLED).

Syntax
FUNCTION ITEM_ENABLED
(mnunam VARCHAR2,
itmnam VARCHAR2);

Built-in Type unrestricted function

Returns BOOLEAN

Enter Query Mode yes

Parameters
mnunam Specifies the VARCHAR2 name of the menu.

itmnam Specifies the VARCHAR2 name of the menu item.

LAST_OLE_ERROR LAST_OLE_ERROR

Description
Returns the identifying number of the most recent OLE error condition

Syntax

FUNCTION LAST_OLE_ERROR RETURN number;

Built-in Type unrestricted function

Returns number

Parameters None

Usage Notes

This function can be used for most error conditions. However, if the error was a PL/SQL exception, use the LAST_OLE_EXCEPTION function instead.
For more information about error values and their meanings, refer to winerror.h. Winerror.h is supplied by your C compiler vendor.

LAST_OLE_EXCEPTION

LAST_OLE_EXCEPTION

Description
Returns the identifying number of the most recent OLE exception that occurred in the called object.

Syntax
FUNCTION LAST_OLE_EXCEPTION
(source OUT VARCHAR2, description OUT VARCHAR2,
helpfile OUT VARCHAR2,
helpcontextid OUT PLS_INTEGER)
RETURN errornumber PLS_INTEGER;

Built-in Type unrestricted function

Returns error number that the OLE server assigned to this exception condition

Parameters

source	Name of the OLE server that raised the exception condition.
description	Error message text.
helpfile	Name of the file in which the OLE server has additional error information.
helpcontextid	ID of a specific document in the above help file.

Usage Notes
This function can be used after a PL/SQL FORM_OLE_FAILURE exception has occurred as a result of calling an OLE object server. For information about other types of errors (not PL/SQL exceptions), use the LAST_OLE_ERROR function.

LAST_RECORD built-in LAST_RECORD built-in

Examples

Description
Navigates to the last record in the block's list of records. If a query is open in the block, Form Builder fetches the remaining selected records into the block's list of records, and closes the query.

Syntax
PROCEDURE LAST_RECORD;

Built-in Type restricted procedure

Enter Query Mode no

Parameters
none

LAST_RECORD examples LAST_RECORD examples

See FIRST_RECORD

LIST_VALUES built-in LIST_VALUES built-in

Related Topics

Description
LIST_VALUES displays the list of values for the current item, as long as the input focus is in a text item that has an attached LOV. The list of values remains displayed until the operator dismisses the LOV or selects a value.

By default, LIST_VALUES uses the NO_RESTRICT parameter. This parameter causes Form Builder not to use the automatic search and complete feature. If you use the RESTRICT parameter, Form Builder uses the automatic search and complete feature.

Automatic Search and Complete Feature With the automatic search and complete feature, an LOV evaluates a text item's current value as a search value. That is, if an operator presses [List] in a text item that has an LOV, Form Builder checks to see if the item contains a value.

If the text item contains a value, Form Builder automatically uses that value as if the operator had entered the value into the LOV's search field and pressed [List] to narrow the list.

If the item value would narrow the list to only one value, Form Builder does not display the LOV, but automatically reads the correct value into the field.

Syntax
PROCEDURE LIST_VALUES
(kwd NUMBER);

Built-in Type restricted procedure

Enter Query Mode no

Parameters
kwd Specifies one of the following constants:

NO_RESTRICT Specifies that Form Builder will not use the automatic search and complete feature.

RESTRICT Specifies that Form Builder will use the automatic search and complete feature.

LOCK_RECORD built-in LOCK_RECORD built-in

Examples Related Topics

Description
Attempts to lock the row in the database that corresponds to the current record. LOCK_RECORD locks the record immediately, regardless of whether the Locking Mode block property is set to Immediate (the default) or Delayed.

When executed from within an On-Lock trigger, LOCK_RECORD initiates default database locking. The following example illustrates this technique.

Syntax
PROCEDURE LOCK_RECORD;

Built-in Type unrestricted procedure

Enter Query Mode no

Parameters
none

LOCK_RECORD examples LOCK_RECORD examples

/*

Built-in: LOCK_RECORD
** Example: Perform Form Builder standard record locking on the
** queried record which has just been deleted or
** updated. Decide whether to use default
** processing or a user exit by consulting a
** global flag setup at startup by the form,
** perhaps based on a parameter.
** Trigger: On-Lock
*/
BEGIN
/*
** Check the global flag we set up at form startup
*/
IF :Global.Non_Oracle_Datasource = 'TRUE' THEN
User_Exit('my_lockrec block=EMP');
/*
** Otherwise, do the right thing.
*/
ELSE
Lock_Record;
END IF;
END;

LOGON built-in

LOGON built-in

Examples Restrictions Related Topics

Description
Performs the default Form Builder logon processing with an indicated username and password. Call this procedure from an On-Logon trigger when you want to augment default logon processing.

Syntax
PROCEDURE LOGON
(username VARCHAR2,
password VARCHAR2);

PROCEDURE LOGON
(username VARCHAR2,
password VARCHAR2,
logon_screen_on_error VARCHAR2);

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
This built-in takes the following arguments:

username Any valid username of up to 80 characters.

password Any valid password of up to 80 characters, including a database connect string.

logon_screen_ on_error An optional BOOLEAN parameter that, when set to TRUE (default), causes Form Builder to automatically display the logon screen if the logon specified fails (usually because of a incorrect username/password). When logon_screen_on_error is set to FALSE and the logon fails, the logon screen will not display and FORMS_FAILURE is set to TRUE so the designer can handle the condition in an appropriate manner.

LOGON restrictions LOGON restrictions

If you identify a remote database, a SQL*Net connection to that database must exist at runtime.

Form Builder can connect to only one database at a time. However, database links may be used to access multiple databases with a single connection.

LOGON examples LOGON examples

/*

Built-in: LOGON
** Example: Perform Form Builder standard logon to the ORACLE
** database. Decide whether to use Form Builder
** built-in processing or a user exit by consulting a
** global flag setup at startup by the form,
** perhaps based on a parameter. This example
** uses the 'Get_Connect_Info' procedure from the
** GET_APPLICATION_PROPERTY example.
** Trigger: On-Logon
*/
DECLARE
un VARCHAR2(80);
pw VARCHAR2(80);
cn VARCHAR2(80);
BEGIN
/*
** Get the connection info
*/
Get_Connect_Info(un,pw,cn);
/*
** If at startup we set the flag to tell our form that we
** are not running against ORACLE, then call our
** appropriate MY_LOGON userexit to logon.
*/
IF :Global.Non_Oracle_Datasource = 'TRUE' THEN
User_Exit('my_logon username='||un||' password='||pw);
/*
** Otherwise, call the LOGON built-in
*/
ELSE
IF cn IS NOT NULL THEN
LOGON(un,pw||'@'||cn);
ELSE
LOGON(un,pw);
END IF;
END IF;
END;

LOGON_SCREEN built-in

LOGON_SCREEN built-in

Examples Restrictions Related Topics

Description
Displays the default Form Builder logon screen and requests a valid username and password. Most commonly, you will include this built-in subprogram in an On-Logon trigger to connect to a non-ORACLE data source.

Syntax
PROCEDURE LOGON_SCREEN;

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
none

LOGON_SCREEN restrictions LOGON_SCREEN restrictions

You must issue a call to the LOGON built-in to create the connection to your data source.

LOGON_SCREEN examples LOGON_SCREEN examples

/*

Built-in: LOGON_SCREEN
** Example: Use the default Form Builder logon screen to prompt
** for username and password before logging on to
** the database. This uses the 'Get_Connect_Info'
** procedure from the GET_APPLICATION_PROPERTY
** example.
*/
DECLARE
un VARCHAR2(80);
pw VARCHAR2(80);
cn VARCHAR2(80);
BEGIN
/*
** Bring up the logon screen
*/
Logon_Screen;
/*
** Get the username, password and
** connect string.
*/
Get_Connect_Info( un, pw, cn );
/*
** Log the user onto the database
*/
IF cn IS NOT NULL THEN
LOGON(un,pw||'@'||cn);
ELSE
LOGON(un,pw);
END IF;
END;

LOGOUT built-in

LOGOUT built-in

Examples Related Topics

Description
Disconnects the application from the ORACLE RDBMS. All open cursors are automatically closed when you issue a call to the LOGOUT built-in. You can programmatically log back on with LOGON. If you LOGOUT of a multiple-form application with multiple connections, Form Builder tries to re-establish all of those connections when you subsequently execute LOGON.

Syntax
PROCEDURE LOGOUT;

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
none

LOGOUT examples LOGOUT examples

/*

Built-in: LOGOUT
** Example: Perform Form Builder standard logout. Decide
** whether to use Form Builder built-in processing or a
** user exit by consulting a global flag setup at
** startup by the form, perhaps based on a
** parameter.
** Trigger: On-Logout
*/
BEGIN
/*
** Check the flag we setup at form startup
*/
IF :Global.Non_Oracle_Datasource = 'TRUE' THEN
User_Exit('my_logout');
/*
** Otherwise, do the right thing.
*/
ELSE
Logout;
END IF;

MENU_CLEAR_FIELD built-in

MENU_CLEAR_FIELD built-in

Restrictions

Description
MENU_CLEAR_FIELD clears the current field's value from the current cursor position to the end of the field. If the current cursor position is to the right of the last nonblank character, MENU_CLEAR_FIELD clears the entire field, making its value NULL.

Syntax
PROCEDURE MENU_CLEAR_FIELD;

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
none

MENU_CLEAR_FIELD restrictions MENU_CLEAR_FIELD restrictions

The Enter Parameter Values dialog must be displayed.

MENU_NEXT_FIELD built-in MENU_NEXT_FIELD built-in

Restrictions

Description
MENU_NEXT_FIELD navigates to the next field in an Enter Parameter Values dialog.

Syntax
PROCEDURE MENU_NEXT_FIELD;

Built-in Type restricted procedure

Enter Query Mode yes

Parameters
none

MENU_NEXT_FIELD restrictions MENU_NEXT_FIELD restrictions

You must be in an Enter Parameter Values dialog.

MENU_PARAMETER built-in MENU_PARAMETER built-in

Restrictions

Description
MENU_PARAMETER displays all the parameters associated with the current menu, and their current values, in the Enter Parameter Values dialog box.

Syntax
PROCEDURE MENU_PARAMETER;

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
none

MENU_PARAMETER restrictions MENU_PARAMETER restrictions

Valid only for menus running in full-screen display style.

MENU_PREVIOUS_FIELD built-in MENU_PREVIOUS_FIELD built-in

Restrictions

Description
MENU_PREVIOUS_FIELD returns to the previous field in an Enter Parameter Values dialog.

Syntax
PROCEDURE MENU_PREVIOUS_FIELD;

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
none

MENU_PREVIOUS_FIELD restrictions MENU_PREVIOUS_FIELD restrictions

You must be in an Enter Parameter Values dialog box.

MENU_REDISPLAY built-in MENU_REDISPLAY built-in

Restrictions

Description
This procedure redraws the screen in a menu.

Syntax
PROCEDURE MENU_REDISPLAY;

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
none

MENU_REDISPLAY restrictions MENU_REDISPLAY restrictions

You must be on a character mode or block mode platform.

MENU_SHOW_KEYS built-in MENU_SHOW_KEYS built-in

Restrictions

Description
MENU_SHOW_KEYS displays the Keys screen for the menu module at runtime.

Syntax
PROCEDURE MENU_SHOW_KEYS;

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
none

MENU_SHOW_KEYS restrictions MENU_SHOW_KEYS restrictions

MENU_SHOW_KEYS is available in any context.

MESSAGE built-in MESSAGE built-in

Examples Restrictions Related Topics

Description
Displays specified text on the message line.

Syntax
PROCEDURE MESSAGE
(message_string VARCHAR2,
user_response NUMBER);

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
message_string Specify a character string enclosed in single quotes or a variable of VARCHAR2 data type.

user_response Specifies one of the following constants:

ACKNOWLEDGE Specifies that Form Builder is to display a modal alert that the operator must dismiss explicitly, whenever two consecutive messages are issued. ACKNOWLEDGE forces the first message to be acknowledged before the second message can be displayed. This is the default.

NO_ACKNOWLEDGE Specifies that, when two consecutive messages are issued, the operator is not expected to respond to the first message displayed before Form Builder displays a second message. Using NO_ACKNOWLEDGE creates a risk that the operator may not see the first message, because the second message immediately overwrites it without prompting the operator for acknowledgement.

MESSAGE restrictions MESSAGE restrictions

The message_string can be up to 200 characters long. Note, however, that several factors affect the maximum number of characters that can be displayed, including the current font and the limitations of the runtime window manager.

MESSAGE examples MESSAGE examples

/*

Built-in: MESSAGE
** Example: Display several messages to the command line
** throughout the progress of a particular
** subprogram. By using the NO_ACKNOWLEDGE parameter,
** we can avoid the operator's having to
** acknowledge each message explicitly.
*/
PROCEDURE Do_Large_Series_Of_Updates IS
BEGIN
Message('Working... (0%)', NO_ACKNOWLEDGE);
/*
** Long-running update statement goes here
*/

SYNCHRONIZE;
Message('Working... (30%)', NO_ACKNOWLEDGE);
/*
** Another long-running update statement goes here
*/
Message('Working... (80%)', NO_ACKNOWLEDGE);
/*
** Last long-running statement here
*/
Message('Done...', NO_ACKNOWLEDGE);
END;

MESSAGE_CODE built-in MESSAGE_CODE built-in

Examples Related Topics

Description
Returns a message number for the message that Form Builder most recently generated during the current Runform session. MESSAGE_CODE returns zero at the beginning of a session, before Form Builder generates any messages.

Use MESSAGE_CODE to test the outcome of a user action (e.g., pressing a key) to determine processing within an On-Message trigger.

Refer to the Messages appendix for a list of messages and message numbers.

Syntax
FUNCTION MESSAGE_CODE;

Built-in Type unrestricted function

Returns NUMBER

Enter Query Mode yes

Parameters
none

MESSAGE_CODE examples MESSAGE_CODE examples

/*

Built-in: MESSAGE_CODE,MESSAGE_TEXT,MESSAGE_TYPE
** Example: Reword certain FRM message messages by checking
** the Message_Code in an ON-MESSAGE trigger
** Trigger: On-Message
*/
DECLARE
msgnum NUMBER := MESSAGE_CODE;
msgtxt VARCHAR2(80) := MESSAGE_TEXT;
msgtyp VARCHAR2(3) := MESSAGE_TYPE;
BEGIN
IF msgnum = 40400 THEN
Message('Your changes have been made permanent.');
ELSIF msgnum = 40401 THEN
Message('You have no unsaved changes outstanding.');
ELSE
/*
** Print the Normal Message that would have appeared
**
** FRM-12345: Message Text Goes Here
*/
Message(msgtyp||'-'||TO_CHAR(msgnum)||': '||msgtxt);
END IF;
END;

MESSAGE_TEXT built-in

MESSAGE_TEXT built-in

Examples Related Topics

Description
Returns message text for the message that Form Builder most recently generated during the current Runform session. MESSAGE_TEXT returns NULL at the beginning of a session, before Form Builder generates any messages.

Use MESSAGE_TEXT to test the outcome of a user action (e.g., pressing a key) to determine processing within an On-Message trigger.

Note: If your applications must be supported in more than one language, use the MESSAGE_CODE built-in instead of the MESSAGE_TEXT built-in. Referencing message codes rather than message text is particularly useful in applications that provide national language support.

Syntax
FUNCTION MESSAGE_TEXT;

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

Parameters
none

MESSAGE_TEXT examples MESSAGE_TEXT examples

/*

Built-in: MESSAGE_CODE,MESSAGE_TEXT,MESSAGE_TYPE
** Example: Reword certain FRM message messages by checking
** the Message_Code in an ON-MESSAGE trigger
** Trigger: On-Message
*/
DECLARE
msgnum NUMBER := MESSAGE_CODE;
msgtxt VARCHAR2(80) := MESSAGE_TEXT;
msgtyp VARCHAR2(3) := MESSAGE_TYPE;
BEGIN
IF msgnum = 40400 THEN
Message('Your changes have been made permanent.');
ELSIF msgnum = 40401 THEN
Message('You have no unsaved changes outstanding.');
ELSE
/*
** Print the Normal Message that would have appeared
**
** FRM-12345: Message Text Goes Here
*/
Message(msgtyp||'-'||TO_CHAR(msgnum)||': '||msgtxt);
END IF;
END;

MESSAGE_TYPE built-in

MESSAGE_TYPE built-in

Examples Related Topics

Description
Returns a message type for the message that Form Builder most recently generated during the current Runform session.

Use MESSAGE_TYPE to test the outcome of a user action (e.g., pressing a key) to determine processing within an On-Message trigger.

Syntax
FUNCTION MESSAGE_TYPE;

Built-in Type unrestricted function

Returns VARCHAR2

MESSAGE_TYPE returns one of three values for the message type:

FRM Indicates that an Form Builder message was generated.

ORA Indicates that an ORACLE message was generated.

NULL Indicates that Form Builder has not yet issued any messages during the session.

Enter Query Mode yes

Parameters
none

MESSAGE_TYPE examples MESSAGE_TYPE examples

/*

Built-in: MESSAGE_CODE,MESSAGE_TEXT,MESSAGE_TYPE
** Example: Reword certain FRM message messages by checking
** the Message_Code in an ON-MESSAGE trigger
** Trigger: On-Message
*/
DECLARE
msgnum NUMBER := MESSAGE_CODE;
msgtxt VARCHAR2(80) := MESSAGE_TEXT;
msgtyp VARCHAR2(3) := MESSAGE_TYPE;
BEGIN
IF msgnum = 40400 THEN
Message('Your changes have been made permanent.');
ELSIF msgnum = 40401 THEN
Message('You have no unsaved changes outstanding.');
ELSE
/*
** Print the Normal Message that would have appeared
**
** FRM-12345: Message Text Goes Here
*/
Message(msgtyp||'-'||TO_CHAR(msgnum)||': '||msgtxt);
END IF;
END;

MOVE_WINDOW built-in

MOVE_WINDOW built-in

Examples Related Topics

Description
Moves the given window to the location specified by the given coordinates.

If you have specified the form property Coordinate System as Character, then your x, y coordinates are specified in characters. If the Coordinate System is specified as Real, then your x, y coordinates are specified in the real units you have selected--pixels, inches, centimeters, or points.

Syntax
FUNCTION MOVE_WINDOW
(window_id Window,
x NUMBER,
y NUMBER);

FUNCTION MOVE_WINDOW
(window_name VARCHAR2,
x NUMBER,
y NUMBER);

Built-in Type unrestricted function

Enter Query Mode yes

Parameters
window_id Specifies the unique ID that Form Builder assigns the window when created. Use the FIND_WINDOW built-in to return the ID to an appropriately typed variable. The data type of the ID is Window.

window_name Specifies the name that you gave the window when creating it.

x Specifies the x coordinate on the screen where you want to place the upper left corner of a window.

y Specifies the y coordinate on the screen where you want to place the upper left corner of a window.

MOVE_WINDOW examples MOVE_WINDOW examples

/*

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

NAME_IN built-in

NAME_IN built-in

Examples Related Topics

Description
Returns the value of the indicated variable.

The returned value is in the form of a character string. However, you can use NAME_IN to return numbers and dates as character strings and then convert those strings to the appropriate data types. You can use the returned value as you would use any value within an executable statement.

If you nest the NAME_IN function, Form Builder evaluates the individual NAME_IN functions from the innermost one to the outermost one.

Syntax
FUNCTION NAME_IN
(variable_name VARCHAR2);

Built-in Type unrestricted function

Returns VARCHAR2

Enter Query Mode yes

Parameters

ariable_name Specifies a valid variable or text item. The data type of the name is VARCHAR2.

Usage Notes

If the returned value is a date string, NAME_IN will use the default American format to format the returned string.

NAME_IN examples NAME_IN examples

/*

Built-in: NAME_IN
** Example: Simple implementation of a Last-In-First-Out
** stack mechanism using Global variables.
** For each named stack, a global variable
** GLOBAL.<stackname>_PTR points to the largest
** element on the stack. PUSH increments this
** value as new elements are added. Values
** PUSH'ed on or POP'ed off the named stack are
** actually stored in GLOBAL variables of a
** conveniently formed name: GLOBAL.<stackname>nnn
** where 'nnn' is the number of the element on the
** stack.
**
** Usage:
** Push('MYSTACKNAME', '1');
** Push('MYSTACKNAME', '2');
**
** str_var := Pop('MYSTACKNAME'); -- Gets '2'
** str_var := Pop('MYSTACKNAME'); -- Gets '1'
** str_var := Pop('MYSTACKNAME'); -- Gets 'EOS'
**
*/
PROCEDURE Push ( the_stackname VARCHAR2,
the_value VARCHAR2 ) IS

ptr_name VARCHAR2(40); -- This stack's pointer name
prefix VARCHAR2(40); -- Common prefix for storage vars
elt_name VARCHAR2(40); -- Name of storage element
new_idx VARCHAR2(4) ; -- New stack pointer value
BEGIN
/*
** For any named stack that we reference, the global
** variables used for storing the stack's values and the
** stack's pointer all begin with a common prefix:
** GLOBAL.<stackname>
*/
prefix := 'GLOBAL.' || the_stackname;
/*
** This named stack's pointer resides in
** GLOBAL.<stackname>_PTR Remember that this is the *name*
** of the pointer.
*/
ptr_name := prefix || '_PTR';
/*
** Initialize the stack pointer with a default value of
** zero if the stack pointer did not exist previously, ie
** the GLOBAL.<stackname>_PTR had yet to be created.
*/
Default_Value( '0', ptr_name );
/*
** Since we're PUSH'ing a new element on the stack,
** increment the stack pointer to reflect this new
** element's position. Remember that GLOBAL variables are
** always of type VARCHAR2, so we must convert them TO_NUMBER
** before any calculations.
*/
new_idx := TO_CHAR( TO_NUMBER( Name_In( ptr_name ) ) + 1 ) ;
Copy( new_idx , ptr_name );
/*
** Determine the name of the global variable which will
** store the value passed in, GLOBAL.<stackname><new_idx>.
** This is simply the prefix concatenated to the new index
** number we just calculated above.
*/
elt_name := prefix||new_idx;
Copy( the_value , elt_name );
END;

FUNCTION Pop ( the_stackname VARCHAR2)
RETURN VARCHAR2 IS
ptr_name VARCHAR2(40); -- This stack's pointer name
prefix VARCHAR2(40); -- Common prefix for storage vars
elt_name VARCHAR2(40); -- Name of storage element
new_idx VARCHAR2(4) ; -- New stack pointer value
cur_idx VARCHAR2(4) ; -- Current stack pointer value
the_val VARCHAR2(255);

EMPTY_STACK CONSTANT VARCHAR2(3) := 'EOS';
NO_SUCH_STACK CONSTANT VARCHAR2(3) := 'NSS';
BEGIN
/*
** For any named stack that we reference, the global
** variables used for storing the stack's values and the
** stack's pointer all begin with a common prefix:
** GLOBAL.<stackname>
*/
prefix := 'GLOBAL.' || the_stackname;
/*
** This named stack's pointer resides in
** GLOBAL.<stackname>_PTR Remember that this is the *name*
** of the pointer.
*/
ptr_name := prefix || '_PTR';
/*
** Force a default value of NULL so we can test if the
** pointer exists (as a global variable). If it does not
** exist, we can test in a moment for the NULL, and avoid
** the typical error due to referencing non-existent
** global variables.
*/
Default_Value( NULL, ptr_name );
/*
** If the *value* contained in the pointer is NULL, then
** the pointer must not have existed prior to the
** Default_Value statement above. Return the constant
** NO_SUCH_STACK in this case and erase the global
** variable that the Default_Value implicitly created.
*/
IF Name_In( ptr_name ) IS NULL THEN
the_val := NO_SUCH_STACK;
Erase( ptr_name );
/*
** Otherwise, the named stack already exists. Get the
** index of the largest stack element from this stack's
** pointer.
*/
ELSE
cur_idx := Name_In( ptr_name ) ;
/*
** If the index is zero, then the named stack is already
** empty, so return the constant EMPTY_STACK, and leave
** the stack's pointer around for later use, ie don't
** ERASE it.
**
** Note that a stack can only be empty if some values
** have been PUSH'ed and then all values subsequently
** POP'ed. If no values were ever PUSH'ed on this named
** stack, then no associated stack pointer would have
** been created, and we would flag that error with the
** NO_SUCH_STACK case above.
*/
IF cur_idx = '0' THEN
the_val := EMPTY_STACK;
/*
** If the index is non-zero, then:
** (1) Determine the name of the global variable in
** which the value to be POP'ed is stored,
** GLOBAL.<stackname><cur_idx>
** (2) Get the value of the (cur_idx)-th element to
** return
** (3) Decrement the stack pointer
** (4) Erase the global variable which was used for
** value storage
*/
ELSE
elt_name:= prefix || cur_idx;
the_val := Name_In( elt_name );
new_idx := TO_CHAR( TO_NUMBER( Name_In(ptr_name) ) - 1 ) ;
Copy( new_idx , ptr_name );
Erase( elt_name );
END IF;
END IF;
RETURN the_val;
END;

NEW_FORM built-in

NEW_FORM built-in

Examples Related Topics

Description
Exits the current form and enters the indicated form. The calling form is terminated as the parent form. If the calling form had been called by a higher form, Form Builder keeps the higher call active and treats it as a call to the new form. Form Builder releases memory (such as database cursors) that the terminated form was using.

Form Builder runs the new form with the same Runform options as the parent form. If the parent form was a called form, Form Builder runs the new form with the same options as the parent form.

Syntax
PROCEDURE NEW_FORM
(formmodule_name VARCHAR2);

PROCEDURE NEW_FORM
(formmodule_name VARCHAR2,
rollback_mode NUMBER);
PROCEDURE NEW_FORM
(formmodule_name VARCHAR2,
rollback_mode NUMBER,
query_mode NUMBER);
PROCEDURE NEW_FORM
(formmodule_name VARCHAR2,
rollback_mode NUMBER,
query_mode NUMBER,
data_mode NUMBER);
PROCEDURE NEW_FORM
(formmodule_name VARCHAR2,
rollback_mode NUMBER,
query_mode NUMBER,
paramlist_id PARAMLIST);
PROCEDURE NEW_FORM
(formmodule_name VARCHAR2,
rollback_mode NUMBER,
query_mode NUMBER,
paramlist_name VARCHAR2);
PROCEDURE NEW_FORM
(formmodule_name VARCHAR2,
rollback_mode NUMBER,
query_mode NUMBER,
data_mode NUMBER,
paramlist_id PARAMLIST);
PROCEDURE NEW_FORM
(formmodule_name VARCHAR2,
rollback_mode NUMBER,
query_mode NUMBER,
data_mode NUMBER,
paramlist_name VARCHAR2);

Built-in Type restricted procedure

Enter Query Mode no

Parameters
formmodule_name Then name of the called form (must be enclosed in single quotes). Datatype is VARCHAR2.

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

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

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

uery_mode NO_QUERY_ONLY (The default.) Runs the indicated form normally, allowing the end user to perform inserts, updates, and deletes in the form.

QUERY_ONLY Runs the indicated form in query-only mode; end users can query records, but cannot perform inserts, updates or deletes.

data_mode NO_SHARE_LIBRARY_DATA (The default.) At runtime, Form Builder will not share data between forms that have identical libraries attached (at design time).

SHARE_LIBRARY_DATA At runtime, Form Builder will share data between forms that have identical libraries attached (at design time).

paramlist_id The unique ID Form Builder assigns when it creates the parameter list. Specify a parameter list when you want to pass parameters from the calling form to the new form. Datatype is PARAMLIST. A parameter list passed to a form via NEW_FORM cannot contain parameters of type DATA_PARAMETER (a pointer to record group).

paramlist_name The name you gave the parameter list object when you defined it. Datatype is VARCHAR2. A parameter list passed to a form via NEW_FORM cannot contain parameters of type DATA_PARAMETER (a pointer to record group).

NEW_FORM examples NEW_FORM examples

/* Create a generic procedure that will invoke the

formname passed-in using the method indicated by
** the 'newform' and 'queryonly' parameters.
*/
PROCEDURE GENERIC_CALL(formname VARCHAR2,
newform VARCHAR2,
queryonly VARCHAR2) IS

msglvl VARCHAR2(2);
error_occurred EXCEPTION;
BEGIN
/*
** Remember the current message level and temporarily
** set it to 10 to suppress errors if an incorrect
** formname is called
*/
msglvl := :SYSTEM.MESSAGE_LEVEL;
:SYSTEM.MESSAGE_LEVEL := '10';

IF newform = 'Y' THEN
IF queryonly = 'Y' THEN
NEW_FORM(formname, to_savepoint, query_only);
ELSIF queryonly = 'N' THEN
NEW_FORM(formname);
END IF;
ELSIF newform = 'N' THEN
IF queryonly = 'Y' THEN
CALL_FORM(formname, hide, no_replace, query_only);
ELSIF queryonly = 'N' THEN
CALL_FORM(formname);
END IF;
END IF;
IF NOT form_success THEN
MESSAGE('Cannot call form '||UPPER(formname)||
'. Please contact your SysAdmin for help.');
RAISE error_occurred;
END IF;
:SYSTEM.MESSAGE_LEVEL := msglvl;
EXCEPTION
WHEN error_occurred THEN
:SYSTEM.MESSAGE_LEVEL := msglvl;
RAISE form_trigger_failure;
END;

NEXT_BLOCK built-in

NEXT_BLOCK built-in

Examples Related Topics

Description
Navigates to the first navigable item in the next enterable block in the navigation sequence. By default, the next block in the navigation sequence is the block with the next higher sequence number, as defined by the order of blocks in the Object Navigator. However, the Next Navigation Block block property can be set to specify a different block as the next block for navigation purposes.

If there is no enterable block with a higher sequence, NEXT_BLOCK navigates to the enterable block with the lowest sequence number.

Syntax
PROCEDURE NEXT_BLOCK;

Built-in Type restricted procedure

Enter Query Mode no

Parameters
none

NEXT_BLOCK examples NEXT_BLOCK examples

/*

Built-in: NEXT_BLOCK
** Example: If the current item is the last item in the
** block, then skip to the next block instead of
** the default of going back to the first item in
** the same block
** Trigger: Key-Next-Item
*/
DECLARE
cur_itm VARCHAR2(80) := :System.Cursor_Item;
cur_blk VARCHAR2(80) := :System.Cursor_Block;
lst_itm VARCHAR2(80);
BEGIN
lst_itm := cur_blk||'.'||Get_Block_Property(cur_blk,LAST_ITEM);
IF cur_itm = lst_itm THEN
Next_Block;
ELSE
Next_Item;
END IF;
END;

NEXT_FORM built-in

NEXT_FORM built-in

Restrictions Related Topics

Description
In a multiple-form application, navigates to the independent form with the next highest sequence number. (Forms are sequenced in the order they were invoked at runtime.) If there is no form with a higher sequence number, NEXT_FORM navigates to the form with the lowest sequence number. If there is no such form, the current form remains current.

When navigating with NEXT_FORM, no validation occurs and no triggers fire except WHEN-WINDOW-DEACTIVATED, which fires for the form that initiates navigation, and WHEN-WINDOW-ACTIVATED, which fires for the target form.

Syntax
PROCEDURE NEXT_FORM;

Built-in Type restricted procedure

Enter Query Mode no

NEXT_FORM restrictions NEXT_FORM restrictions

The target form cannot be a form that is currently disabled as a result of having invoked another form with CALL_FORM.

NEXT_ITEM built-in NEXT_ITEM built-in

Examples Related Topics

Description
Navigates to the navigable item with the next higher sequence number than the current item. If there is no such item, NEXT_ITEM navigates to the item with the lowest sequence number. If there is no such item, NEXT_ITEM navigates to the current item.

If the validation unit is the item, NEXT_ITEM validates any fields with sequence numbers greater than the current item or less than the target item.

The function of NEXT_ITEM from the last navigable item in the block depends on the setting of the Navigation Style block property. The valid settings for Navigation Style include:

Same Record (Default): A Next Item operation from a block's last item moves the input focus to the first navigable item in the block, in that same record.

Change Record: A Next Item operation from a block's last item moves the input focus to the first navigable item in the block, in the next record. If the current record is the last record in the block and there is no open query, Form Builder creates a new record. If there is an open query in the block (the block contains queried records), Oracle forms retrieves additional records as needed.

Change Block: A Next Item operation from a block's last item moves the input focus to the first navigable item in the first record of the next block.

Syntax
PROCEDURE NEXT_ITEM;

Built-in Type restricted procedure

Enter Query Mode yes

Parameters
none

NEXT_ITEM examples NEXT_ITEM examples

/*

Built-in: NEXT_ITEM
** Example: See NEXT_BLOCK
*/

NEXT_KEY built-in

NEXT_KEY built-in

Examples Related Topics

Description
Navigates to the enabled and navigable primary key item with the next higher sequence number than the current item. If there is no such item, NEXT_KEY navigates to the enabled and navigable primary key item with the lowest sequence number. If there is no primary key item in the current block, an error occurs.

If the validation unit is the item, NEXT_KEY validates any fields with sequence numbers greater than the current item or less than the target item.

Syntax
PROCEDURE NEXT_KEY;

Built-in Type restricted procedure

Enter Query Mode yes

Parameters
none

NEXT_KEY examples NEXT_KEY examples

/*

Built-in: NEXT_KEY
** Example: Jump the cursor to the next primary key item in
** in the current block.
*/
BEGIN
Next_Key;
END;

NEXT_MENU_ITEM built-in

NEXT_MENU_ITEM built-in

Restrictions

Description
Navigates to the next menu item in the current menu.

Syntax
PROCEDURE NEXT_MENU_ITEM;

Built-in Type restricted procedure

Parameters
none

NEXT_MENU_ITEM restrictions NEXT_MENU_ITEM restrictions

NEXT_MENU_ITEM is available only in a custom menu running in the full-screen menu display style.

NEXT_RECORD built-in NEXT_RECORD built-in

Examples Restrictions Related Topics

Description
Navigates to the first enabled and navigable item in the record with the next higher sequence number than the current record. If there is no such record, Form Builder will fetch or create a record. If the current record is a new record, NEXT_RECORD fails.

Syntax
PROCEDURE NEXT_RECORD;

Built-in Type restricted procedure

Enter Query Mode no

Parameters
none

NEXT_RECORD restrictions NEXT_RECORD restrictions

Not allowed in Enter Query mode.

NEXT_RECORD examples NEXT_RECORD examples

/*

Built-in: NEXT_RECORD
** Example: If the current item is the last item in the
** block, then skip to the next record instead of
** the default of going back to the first item in
** the same block
** Trigger: Key-Next-Item
*/
DECLARE
cur_itm VARCHAR2(80) := :System.Cursor_Item;
cur_blk VARCHAR2(80) := :System.Cursor_Block;
lst_itm VARCHAR2(80);
BEGIN
lst_itm := cur_blk||'.'||Get_Block_Property(cur_blk,LAST_ITEM);
IF cur_itm = lst_itm THEN
Next_Record;
ELSE
Next_Item;
END IF;
END;

NEXT_SET built-in

NEXT_SET built-in

Examples Related Topics

Description
Fetches another set of records from the database and navigates to the first record that the fetch retrieves. NEXT_SET succeeds only if a query is open in the current block.

Syntax
PROCEDURE NEXT_SET;

Built-in Type restricted procedure

Enter Query Mode no

Parameters
none

NEXT_SET examples NEXT_SET examples

/*

Built-in: NEXT_SET
** Example: Fetch the next set of records from the database
** when a button is pressed.
** Trigger: When-Button-Pressed
*/
BEGIN
Next_Set;
END;

OLEVAR_EMPTY

OLEVAR_EMPTY

Description
An OLE variant of type VT_EMPTY.

Syntax
OLEVAR_EMPTY OLEVAR;

Usage Notes
This is a non-settable variable. It is useful for supplying empty or non-existant arguments to an OLE call.

OPEN_FORM built-in OPEN_FORM built-in

Restrictions Related Topics

Description
Opens the indicated form. Use OPEN_FORM to create multiple-form applications, that is, applications that open more than one form at the same time.

Syntax
PROCEDURE OPEN_FORM
(form_name VARCHAR2);

PROCEDURE OPEN_FORM
(form_name VARCHAR2,
activate_mode NUMBER);
PROCEDURE OPEN_FORM
(form_name VARCHAR2,
activate_mode NUMBER,
session_mode NUMBER);
PROCEDURE OPEN_FORM
(form_name VARCHAR2,
activate_mode NUMBER,
session_mode NUMBER,
data_mode NUMBER);
PROCEDURE OPEN_FORM
(form_name VARCHAR2,
activate_mode NUMBER,
session_mode NUMBER,
paramlist_name VARCHAR2);
PROCEDURE OPEN_FORM
(form_name VARCHAR2,
activate_mode NUMBER,
session_mode NUMBER,
paramlist_id PARAMLIST);
PROCEDURE OPEN_FORM
(form_name VARCHAR2,
activate_mode NUMBER,
session_mode NUMBER,
data_mode NUMBER,
paramlist_name VARCHAR2);
PROCEDURE OPEN_FORM
(form_name VARCHAR2,
activate_mode NUMBER,
session_mode NUMBER,
data_mode NUMBER,
paramlist_id PARAMLIST);

Built-in Type restricted procedure

Enter Query Mode no

Parameters:
no parameters Opens the form and sets focus to it. Equivalent to Open_Form(ACTIVATE, NO_SESSION);

form_name The name of the form to open. Datatype is VARCHAR2.

activate_mode ACTIVATE (The default.) Sets focus to the form to make it the active form in the application.

NO_ACTIVATE Opens the form but does not set focus to the form. The current form remains current.

session_mode NO_SESSION (The default.) Specifies that the opened form should share the same database session as the current form. POST and COMMIT operations in any form will cause posting, validation, and commit processing to occur for all forms running in the same session.

SESSION Specifies that a new, separate database session should be created for the opened form.

data_mode NO_SHARE_LIBRARY_DATA (The default.) At runtime, Form Builder will not share data between forms that have identical libraries attached (at design time).

SHARE_LIBRARY_DATA At runtime, Form Builder will share data between forms that have identical libraries attached (at design time).

paramlist_name The name of a parameter list to be passed to the opened form. Datatype is VARCHAR2.

paramlist_id The unique ID that Form Builder assigns to the parameter list at the time it is created. Use the GET_PARAMETER_LIST function to return the ID to a variable of type PARAMLIST.

Usage Notes

Whether you open a form with ACTIVATE or NO_ACTIVATE specified, any startup triggers that would normally fire will execute in the opened form. (However, see the usage note regarding SESSION-specified below.)

When you open a form with ACTIVATE specified (the default), the opened form receives focus immediately; trigger statements that follow the call to OPEN_FORM never execute.

When you open a form with NO_ACTIVATE specified, trigger statements that follow the call to OPEN_FORM will execute after the opened form has been loaded into memory and its initial start-up triggers have fired.

When you open a form with SESSION specified, the PRE-LOGON, ON-LOGON, and POST-LOGON triggers will not fire.

If the form that issues the OPEN_FORM built-in is running in QUERY_ONLY mode, then the opened form will also run in QUERY_ONLY mode.

On Microsoft Windows, if any window in the form that opens the independent form is maximized, the first window displayed by the opened form will also be maximized, regardless of its original design-time setting. (The GUI display state of a window is controlled by the Window_State property.)

For most applications, you should avoid using OPEN_FORM with forms that contain root windows. Because there can be only one root window displayed at a time, canvases that are assigned to the root window in the current form and in the opened form will be displayed in the same window. This causes the opened form to "take over" the root window from the original form, thus hiding the canvases in the original form partially or completely.

OPEN_FORM restrictions OPEN_FORM restrictions

You can set session On for all Runform invocations by setting the FORMSnn_SESSION environment variable to TRUE. When you set the FORMSnn_SESSION variable, all Runform invocations inherit its setting, unless you override the environment variable by setting the Session option from the Runform command line.

If you set session_mode to SESSION when you use OPEN_FORM to create a multiple-form application, you cannot set data_mode to SHARE_LIBRARY_DATA (Form Builder will display a runtime error message).

PASTE_REGION built-in PASTE_REGION built-in

Related Topics

Description
Pastes the contents of the clipboard (i.e., the selected region that was cut or copied most recently), positioning the upper left corner of the pasted area at the cursor position.

Syntax
PROCEDURE PASTE_REGION;

Built-in Type restricted procedure

Enter Query Mode yes

Parameters
none

Usage Notes

Use PASTE_REGION, as well as the other editing functions, on text and image items only. The cut and copy functions transfer the selected region into the system clipboard until you indicate the paste target. At that time, the cut or copied content is pasted onto the target location.

PAUSE built-in PAUSE built-in

Description
Suspends processing until the end user presses a function key. PAUSE might display an alert.

Syntax
PROCEDURE PAUSE;

Built-in Type unrestricted procedure

Enter Query Mode yes

Description
Suspends processing until the end user presses a function key. PAUSE might display an alert.

Parameters
none

PLAY_SOUND built-in PLAY_SOUND built-in

Examples Related Topics

Description
Plays the sound object in the specified sound item.

Syntax
PLAY_SOUND(item_id ITEM);

PLAY_SOUND(item_name VARCHAR2);

Built-in Type restricted

Enter Query Mode No

Parameters:
item_id The unique ID Form Builder gave the sound item when you created it.

item_name The name you gave the sound item when you created it.

PLAY_SOUND restrictions PLAY_SOUND restrictions

PLAY_SOUND examples PLAY_SOUND examples

/* Example 1: This procedure call (attached to a menu item)

plays a sound object from the specified sound item:
*/
GO_ITEM('about.abc_inc');
PLAY_SOUND('about.abc_inc');

/* Example 2: These procedure calls (attached to a
** When-Button-Pressed trigger) read a sound object from the
** file system and play it. Note: since an item must have focus
** in order to play a sound, the trigger code includes a call
** to the built-in procedure GO_ITEM:
*/
BEGIN
IF :clerks.last_name EQ 'BARNES' THEN
GO_ITEM('orders.filled_by');
READ_SOUND_FILE('t:\orders\clerk\barnes.wav',
'wave',
'orders.filled_by');
PLAY_SOUND('orders.filled_by');
END IF;
END;

POPULATE_GROUP built-in

POPULATE_GROUP built-in

Examples Restrictions Related Topics

Description
Executes the query associated with the given record group and returns a number indicating success or failure of the query. Upon a successful query, POPULATE_GROUP returns a 0 (zero). An unsuccessful query generates an ORACLE error number that corresponds to the particular SELECT statement failure. The rows that are retrieved as a result of a successful query replace any rows that exist in the group.

Note: Be aware that the POPULATE_GROUP array fetches 100 records at a time. To improve network performance, you may want to restrict queries, thus limiting network traffic.

Syntax
FUNCTION POPULATE_GROUP
(recordgroup_id RecordGroup);

FUNCTION POPULATE_GROUP
(recordgroup_name VARCHAR2);

Built-in Type unrestricted function

Returns NUMBER

Enter Query Mode yes

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

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

POPULATE_GROUP restrictions POPULATE_GROUP restrictions

Valid only for record groups

that were created at design time with a query

that were created by a call to the CREATE_GROUP_FROM_QUERY built-in

that have been previously populated with the POPULATE_GROUP_WITH_QUERY built-in (which associates a query with the record group)

POPULATE_GROUP examples POPULATE_GROUP examples

/*

Built-in: POPULATE_GROUP
** Example: See GET_GROUP_ROW_COUNT and CREATE_GROUP_FROM_QUERY
*/

POPULATE_GROUP_FROM_TREE built-in

POPULATE_GROUP_FROM_TREE built-in

Examples

Description
Populates a record group with the data from the hierarchical tree.

Syntax
PROCEDURE POPULATE_GROUP_FROM_TREE

(group_name VARCHAR2,

item_name VARCHAR2,

node NODE);

PROCEDURE POPULATE_GROUP_FROM_TREE

(group_name VARCHAR2,

item_id ITEM,

node NODE);

PROCEDURE POPULATE_GROUP_FROM_TREE

(group_id RECORDGROUP,

item_name VARCHAR2,

node NODE);

PROCEDURE POPULATE_GROUP_FROM_TREE

(group_id RECORDGROUP,

item_id ITEM,

node NODE);

Built-in Type unrestricted procedure

Enter Query Mode no

Parameters

group_name	Specifies the name of the group.
group_id	Specifies the ID assigned to the group.
item_name	Specifies the name of the object created at design time. The data type of the name is VARCHAR2 string.
Item_id	Specifies the unique ID that Form Builder assigns to the item when created. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable. The data type of the ID is ITEM.
node	Specifies a valid node. If specified, indicates a sub-tree used to populate the RecordGroup, including the specified node.

Usage Notes
The record group is cleared prior to inserting the hierarchical tree�s data set.

POPULATE_GROUP_FROM_TREE examples POPULATE_GROUP_FROM_TREE examples

/*

Built-in: POPULATE_GROUP_FROM_TREE
*/

-- This code will transfer all the data from a hierarchical tree

-- that is parented by the node with a label of "Zetie" to a

-- pre-created record group. Please see the documentation

-- for the structure of the required record group.

DECLARE

htree ITEM;

find_node NODE;

BEGIN

-- Find the tree itself.

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

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

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

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

-- Populate the record group with the tree data.

-- The record group must already exist.

Ftree.Populate_Group_From_Tree('tree_data_rg', htree, find_node);

END;

POPULATE_GROUP_WITH_QUERY built-in POPULATE_GROUP_WITH_QUERY built-in

Examples Restrictions Related Topics

Description
Populates a record group with the given query. The record group is cleared and rows that are fetched replace any existing rows in the record group.

If the SELECT statement fails, Form Builder returns an ORACLE error number. If the query is successful, this built-in returns 0 (zero).

You can use this built-in to populate record groups that were created by a call to either:

the CREATE_GROUP built-in or

the CREATE_GROUP_FROM_QUERY built-in

When you use this built-in, the indicated query becomes the default query for the group, and will be executed whenever the POPULATE_GROUP built-in is subsequently called.

Note: Be aware that the POPULATE_GROUP_WITH_QUERY array fetches 20 records at a time. To improve network performance, you may want to restrict queries, thus limiting network traffic.

Syntax
FUNCTION POPULATE_GROUP_WITH_QUERY
(recordgroup_id RecordGroup,
query VARCHAR2);

FUNCTION POPULATE_GROUP_WITH_QUERY
(recordgroup_name VARCHAR2,
query VARCHAR2);

Built-in Type unrestricted function

Returns NUMBER

Enter Query Mode yes

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

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

uery A valid SELECT statement, enclosed in single quotes. Any columns retrieved as a result of the query take the data types of the columns in the table. If you restrict the query to a subset of the columns in the table, then Form Builder creates only those columns in the record group. The data type of the query is VARCHAR2.

POPULATE_GROUP_WITH_QUERY restrictions

POPULATE_GROUP_WITH_QUERY restrictions

The columns specified in the SELECT statement must match the record group columns in number and type.

POPULATE_GROUP_WITH_QUERY examples POPULATE_GROUP_WITH_QUERY examples

/*

Built-in: POPULATE_GROUP_WITH_QUERY
** Example: See CREATE_GROUP
*/

POPULATE_LIST built-in

POPULATE_LIST built-in

Examples Restrictions Related Topics

Description
Removes the contents of the current list and populates the list with the values from a record group. The record group must be created at runtime and it must have the following two column (VARCHAR2) structure:

Column 1: Column 2:

the list label the list value

Syntax
PROCEDURE POPULATE_LIST
(list_id ITEM,
recgrp_id RecordGroup);

PROCEDURE POPULATE_LIST
(list_id ITEM,
recgrp_name VARCHAR2);
PROCEDURE POPULATE_LIST
(list_name VARCHAR2,
recgrp_id RecordGroup);
PROCEDURE POPULATE_LIST
(list_name VARCHAR2,
recgrp_name VARCHAR2);

Built-in Type
unrestricted procedure

Enter Query Mode yes

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

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

recgrp_name The VARCHAR2 name you gave to the record group when you created it.

Usage Notes

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

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

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

POPULATE_LIST restrictions POPULATE_LIST restrictions

POPULATE_LIST returns error FRM-41337: Cannot populate the list from the record group if:

the record group does not contain either the default value element or the other values element and the list does not meet the criteria specified for deleting these elements with DELETE_LIST_ELEMENT. Refer to the restrictions on DELETE_LIST_ELEMENT for more information.

the record group contains an other value element but the list does not meet the criteria specified for adding an other value element with ADD_LIST_ELEMENT. Refer to the restrictions on ADD_LIST_ELEMENT for more information.

POPULATE_LIST examples POPULATE_LIST examples

/*

Built-in: POPULATE_LIST
** Example: Retrieves the values from the current list item
** into record group one, clears the list, and
** populates the list with values from record group
** two when a button is pressed.
** Trigger: When-Button-Pressed
*/
BEGIN
Retrieve_List(list_id, 'RECGRP_ONE');
Clear_List(list_id);
Populate_List(list_id, 'RECGRP_TWO');
END;

POPULATE_TREE built-in

POPULATE_TREE built-in

Examples

Description
Clears out any data already in the hierarchical tree, and obtains the data set specified by the RecordGroup or QueryText properties.

Syntax
PROCEDURE POPULATE_TREE

(item_name VARCHAR2);

PROCEDURE POPULATE_TREE

(item_id ITEM);

Built-in Type unrestricted procedure

Enter Query Mode no

Parameters

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

POPULATE_TREE examples POPULATE_TREE examples

/*

Built-in: POPULATE_TREE
*/

-- This code will cause a tree to be re-populated using

-- either the record group or query already specified

-- for the hierarchical tree.

DECLARE

htree ITEM;

top_node NODE;

find_node NODE;

BEGIN

-- Find the tree itself.

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

-- Populate the tree with data.

Ftree.Populate_Tree(htree);

END;

POST built-in POST built-in

Examples Related Topics

Description
Writes data in the form to the database, but does not perform a database commit. Form Builder first validates the form. If there are changes to post to the database, for each block in the form Form Builder writes deletes, inserts, and updates to the database.

Any data that you post to the database is committed to the database by the next COMMIT_FORM that executes during the current Runform session. Alternatively, this data can be rolled back by the next CLEAR_FORM.

Syntax
PROCEDURE POST;

Built-in Type restricted procedure

Enter Query Mode no

Parameters
none

Usage Notes
If this form was called via OPEN_FORM with the NO_SESSION parameter specified, then the POST will validate and write the data both in this form and in the calling form.

POST examples POST examples

/*

Built-in: POST
** Example: See EXIT_FORM
*/

PREVIOUS_BLOCK built-in

PREVIOUS_BLOCK built-in

Examples Related Topics

Description
Navigates to the first navigable item in the previous enterable block in the navigation sequence. By default, the previous block in the navigation sequence is the block with the next lower sequence number, as defined by the block order in the Object Navigator. However, the Previous Navigation Block block property can be set to specify a different block as the previous block for navigation purposes.

If there is no enterable block with a lower sequence, PREVIOUS_BLOCK navigates to the enterable block with the highest sequence number.

Syntax
PROCEDURE PREVIOUS_BLOCK;

Built-in Type restricted procedure

Enter Query Mode no

Parameters
none

PREVIOUS_BLOCK examples PREVIOUS_BLOCK examples

/*

Built-in: PREVIOUS_BLOCK
** Example: If the current item is the first item in the
** block, then skip back the previous block
** instead of the default of going to the last
** item in the same block
** Trigger: Key-Previous-Item
*/
DECLARE
cur_itm VARCHAR2(80) := :System.Cursor_Item;
cur_blk VARCHAR2(80) := :System.Cursor_Block;
frs_itm VARCHAR2(80);
BEGIN
frs_itm := cur_blk||'.'||Get_Block_Property(cur_blk,FIRST_ITEM);
IF cur_itm = frs_itm THEN
Previous_Block;
ELSE
Previous_Item;
END IF;
END;

PREVIOUS_FORM built-in

PREVIOUS_FORM built-in

Restrictions Related Topics

Description
In a multiple-form application, navigates to the form with the next lowest sequence number. (Forms are sequenced in the order they were invoked at runtime.) If there is no form with a lower sequence number, PREVIOUS_FORM navigates to the form with the highest sequence number. If there is no such form, the current form remains current.

When navigating with PREVIOUS_FORM, no validation occurs and no triggers fire except WHEN-WINDOW-DEACTIVATED, which fires for the form that initiates navigation, and WHEN-WINDOW-ACTIVATED, which fires for the target form.

Syntax
PROCEDURE PREVIOUS_FORM;

Built-in Type restricted procedure

Enter Query Mode no

PREVIOUS_FORM restrictions PREVIOUS_FORM restrictions

The target form cannot be a form that is currently disabled as a result of having invoked another form with CALL_FORM.

PREVIOUS_ITEM built-in PREVIOUS_ITEM built-in

Examples Related Topics

Description
Navigates to the navigable item with the next lower sequence number than the current item. If there is no such item, PREVIOUS_ITEM navigates to the navigable item with the highest sequence number. If there is no such item, PREVIOUS_ITEM navigates to the current item.

The function of PREVIOUS_ITEM from the first navigable item in the block depends on the setting of the Navigation Style block property. The valid settings for Navigation Style include:

Same Record (Default): A Previous Item operation from a block's first item moves the input focus to the last navigable item in the block, in that same record.

Change Record: A Previous Item operation from a block's first item moves the input focus to the last navigable item in the block, in the previous record.

Change Block: A Previous Item operation from a block's first item moves the input focus to the last navigable item in the current record of the previous block.

Syntax
PROCEDURE PREVIOUS_ITEM;

Built-in Type restricted procedure

Enter Query Mode yes

Parameters
none

PREVIOUS_ITEM examples PREVIOUS_ITEM examples

/*

Built-in: PREVIOUS_ITEM
** Example: See PREVIOUS_BLOCK
*/

PREVIOUS_MENU built-in

PREVIOUS_MENU built-in

Restrictions

Description
PREVIOUS_MENU navigates to the previously active item in the previous menu.

Syntax
PROCEDURE PREVIOUS_MENU;

Built-in Type restricted procedure

Parameters
none

PREVIOUS_MENU restrictions PREVIOUS_MENU restrictions

PREVIOUS_MENU applies only in full-screen and bar menus.

PREVIOUS_MENU_ITEM built-in PREVIOUS_MENU_ITEM built-in

Restrictions

Description
PREVIOUS_MENU_ITEM navigates to the previous menu item in the current menu.

Syntax
PROCEDURE PREVIOUS_MENU_ITEM;

Built-in Type restricted procedure

Parameters
none

PREVIOUS_MENU_ITEM restrictions PREVIOUS_MENU_ITEM restrictions

PREVIOUS_MENU_ITEM applies only in full-screen menus.

PREVIOUS_RECORD built-in PREVIOUS_RECORD built-in

Examples Related Topics

Description
Navigates to the first enabled and navigable item in the record with the next lower sequence number than the current record.

Syntax
PROCEDURE PREVIOUS_RECORD;

Built-in Type restricted procedure

Enter Query Mode no

Parameters
none

PREVIOUS_RECORD examples PREVIOUS_RECORD examples

/*

Built-in: PREVIOUS_RECORD
** Example: If the current item is the first item in the
** block, then skip back to the previous record
** instead of the default of going to the last
** item in the same block
** Trigger: Key-Previous-Item
*/
DECLARE
cur_itm VARCHAR2(80) := :System.Cursor_Item;
cur_blk VARCHAR2(80) := :System.Cursor_Block;
frs_itm VARCHAR2(80);
BEGIN
frs_itm := cur_blk||'.'||Get_Block_Property(cur_blk,FIRST_ITEM);
IF cur_itm = frs_itm THEN
Previous_Record;
ELSE
Previous_Item;
END IF;
END;

PRINT built-in

PRINT built-in

Examples

Description
Prints the current window to a file or to the printer.

Syntax
PROCEDURE PRINT;

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
none

PRINT examples PRINT examples

/*

Built-in: PRINT
** Example: Print the current window.
*/
BEGIN
Print;
END;

PTR_TO_VAR

PTR_TO_VAR

Description
First, creates an OLE variant of type VT_PTR that contains the supplied address. Then, passes that variant and type through the function VARPTR_TO_VAR.

Syntax
FUNCTION PTR_TO_VAR
(address PLS_INTEGER, vtype VT_TYPE)
RETURN newvar OLEVAR;

Built-in Type unrestricted function

Returns the created and transformed OLE variant.

Parameters

address	A variable whose value is an address.
type	The type to be given to the final version of the OLE variant (after its processing by VARPTR_TO_VAR).

Usage Notes
In most applications, there is no need to use this function. If the function is used, care must be taken to ensure that the correct address value is placed in the new variant.

QUERY_PARAMETER built-in QUERY_PARAMETER built-in

Examples

Description
Displays the Query Parameter dialog showing the current values of the specified substitution parameters. End users can set the value of any parameter you include in the list.

The Query Parameter dialog is modal, and control does not return to the calling trigger or procedure until the end user either accepts or cancels the dialog. This means that any PL/SQL statements that follow the call to QUERY_PARAMETER are not executed until the Query Parameter dialog is dismissed.

Syntax
PROCEDURE QUERY_PARAMETER
(parameter_string VARCHAR2);

Built-in Type unrestricted procedure

Parameters
parameter_string Specifies a string of substitution parameters for a menu item. The syntax for specifying the parameter_string parameter requires the ampersand &parm_name. Substitution parameters are referenced in PL/SQL code with the colon syntax ":param_name" used for all bind variables).

QUERY_PARAMETER examples QUERY_PARAMETER examples

/*

Built-in: QUERY_PARAMETER
** Example: Prompt for several menu parameters
** programmatically, validating their contents.
*/
PROCEDURE Update_Warehouse IS
validation_Err BOOLEAN;
BEGIN
WHILE TRUE LOOP
Query_Parameter('&p1 &q2 &z6');
/*
** If the user did not Cancel the box the Menu_Success
** function will return boolean TRUE.
*/
IF Menu_Success THEN
IF TO_NUMBER( :q2 ) NOT BETWEEN 100 AND 5000 THEN
Message('Qty must be in the range 100..5000');
Bell;
Validation_Err := TRUE;
END IF;
/*
** Start a sub-block so we can catch a Value_Error
** exception in a local handler
*/
BEGIN
IF TO_DATE( :z6 ) < SYSDATE THEN
Message('Target Date must name a day in the future.');
Bell;
Validation_Err := TRUE;
END IF;
EXCEPTION
WHEN VALUE_ERROR THEN
Message('Target Date must be of the form DD-MON-YY');
Bell;
Validation_Err := TRUE;
END;
/*
** If we get here, all parameters were valid so do the
** Update Statement.
*/
IF NOT Validation_Err THEN
UPDATE WAREHOUSE
SET QTY_TO_ORDER = QTY_TO_ORDER*0.18
WHERE TARGET_DATE = TO_DATE(:z6)
AND QTY_ON_HAND > TO_NUMBER(:q2)
AND COST_CODE LIKE :p1||'%';
END IF;
ELSE
/*
** If Menu_Success is boolean false, then return back
** from the procedure since user cancelled the dialog
*/
RETURN;
END IF;
END LOOP;
END;

READ_IMAGE_FILE built-in

READ_IMAGE_FILE built-in

Examples Related Topics

Description
Reads an image of the given type from the given file and displays it in the Form Builder image item.

Syntax
PROCEDURE READ_IMAGE_FILE
(file_name VARCHAR2,
file_type VARCHAR2,
item_id ITEM);

PROCEDURE READ_IMAGE_FILE
(file_name VARCHAR2,
file_type VARCHAR2,
item_name VARCHAR2);

Built-in Type unrestricted procedure

Enter Query Mode yes

Parameters
file_name Valid file name. The file name designation can include a full path statement appropriate to your operating system.

file_type The valid image file type: BMP, CALS, GIF, JFIF, JPG, PICT, RAS, TIFF, or TPIC. (Note: File type is optional, as Form Builder will attempt to deduce it from the source image file. To optimize performance, however, you should specify the file type.)

item_id The unique ID Form Builder assigns to the image item when it creates it. Use the FIND_ITEM built-in to return the ID to an appropriately typed variable. Datatype is ITEM.

item_name The name you gave the image item when you created it. Datatype is VARCHAR2.

Usage Notes

Form Builder searches for the image file along the same default path as it searches for an .FMX file. For more information on the specific search path for your platform, refer to the Form Builder documentation for your operating system.

READ_IMAGE_FILE examples READ_IMAGE_FILE examples

/* Read an image from the filesystem into an image item on the

form. In this example, the scanned picture identification
** for each employee is NOT saved to the database, but is
** stored on the filesystem. An employee's photo is a TIFF
** image stored in a file named <Userid>.TIF Each employee's
** Userid is unique.
** Trigger: Post-Query
*/
DECLARE
tiff_image_dir VARCHAR2(80) := '/usr/staff/photos/';
photo_filename VARCHAR2(80);
BEGIN
/*
** Set the message level high so we can gracefully handle
** an error reading the file if it occurs
*/
:System.Message_Level := '25';
/*
** After fetching an employee record, take the employee's
** Userid and concatenate the '.TIF' extension to derive
** the filename from which to load the TIFF image. The EMP
** record has a non-database image item named 'EMP_PHOTO'
** into which we read the image.
*/
photo_filename := tiff_image_dir||LOWER(:emp.userid)||'.tif';

/*
** For example 'photo_filename' might look like:
**
** /usr/staff/photos/jgetty.tif
** ------
**
** Now, read in the appropriate image.
*/

READ_IMAGE_FILE(photo_filename, 'TIFF', 'emp.emp_photo');
IF NOT FORM_SUCCESS THEN
MESSAGE('This employee does not have a photo on file.');
END IF;
:SYSTEM.MESSAGE_LEVEL := '0';
END;

READ_SOUND_FILE built-in

READ_SOUND_FILE built-in

Examples Related Topics

Description
Reads sound object from the specified file into the specified sound item.

Syntax
READ_SOUND_FILE(file_name VARCHAR2,
file_type VARCHAR2,
item_id ITEM);

READ_SOUND_FILE(file_name VARCHAR2,
file_type VARCHAR2,
item_name VARCHAR2);

Built-in Type
unrestricted

Enter Query Mode Yes

Parameters:
file_name The fully-qualified file name of the file that contains the sound object to be read.

file_type The file type for the sound data file. Valid values are: AU, AIFF, AIFF-C, and WAVE. (Note: file type is optional, but should be specified if known for increased performance.)

item_id The unique ID Form Builder gave the sound item when you created it.

item_name The name you gave the sound item when you created it.

Usage Notes

Specifying a file type for the sound file is optional. If you know the file type, however, specifying it can increase performance.