Document-ID: 40677.1
Subject: (V45) ORGANIZING AND USING BUILT-INS
Author: Unknown
Last Modified: 29 Aug 96
(V45) Organizing and Using Built-ins
====================================
Overview
--------
Built-in packages are a collection of predefined subprograms you can
use in your applications.
Oracle Forms includes over 100 built-in subprograms that you can call.
In the Object Navigator you can browse the Oracle Forms built-ins
under the Built-in packages node. The Standard Extensions package
includes the core Oracle Forms built-ins. Other packages provide
specialized functionality for specific application purposes.
Each built-in subprogram is a group of program instructions that
executes some application function. Built-in subprograms can be
called from triggers, menu item commands, and user-named subprograms,
but they cannot be edited or modified in any way. The various
built-ins are identified and organized by TYPE later in this bulletin.
Calling Built-in Subprograms
----------------------------
A built-in subprogram is a packaged procedure or function that is
always available within Oracle Forms.
To call a PROCEDURE, type the procedure name and any required
parameters as a statement in the executable section of a PL/SQL block
and terminate the call with a semicolon.
Generic form --> BUILT-INNAME(PARAMETERS);
Example: --> GO_ITEM('customer.cust_id');
A built-in FUNCTION differs from a procedure in two important ways:
1) a function RETURNS A VALUE of a specific TYPE
2) a function represents an expression of a specific datatype,
and must be part of a complete statement.
Generic form --> RETURNVALUE := BUILT_INNAME(PARAMETERS);
Example:
DECLARE
item_required VARCHAR2(5);
BEGIN
item_required := GET_ITEM_PROPERTY('customer.custid',REQUIRED);
END;
*** NOTE: Some built-ins return uppercase CHAR values. This affects
comparisons in IF statements.
How to Reference Oracle Forms Objects in Calls to Built-ins
-----------------------------------------------------------
NAME:
To reference an OBJECT by name, enclose the object name in single quotes:
'form_module_name' or 'block_name', or 'window_name'
RESIZE_WINDOW('my_window',50,35);
To reference an ITEM by name, include the name of the block to which the item
belongs to form a fully-qualified name: 'block_name.item_name'
GO_ITEM('customer.custr_id');
(To reference the VALUE stored in an item, put a colon in front of the fully
qualified item name: (:block_name.item_name)
INTERNAL ID:
Oracle Forms assigns an ID to each object you create. An object's ID
is an internal handle whose actual value is never externalized. You
can get the ID of an object by calling the built-in FIND-function
appropriate for that object class. Once an object ID has been
successfully assigned to a variable, you can use that variable to
reference the object, rather than referring to the object by name.
DECLARE
win_id WINDOW;
BEGIN
win_id := FIND_WINDOW('my_window');
END;
The following objects return unique object IDs of a specific datatype:
ALERT, BLOCK, CANVAS, RECORD GROUP COLUMN, EDITOR, FORM, RECORD GROUP, ITEM,
LIST OF VALUES, MENU ITEM, PARAMETER LIST, RELATION, TIMER, VIEW.
Restrictions
------------
Unrestricted built-ins do not affect logical or physical navigation
and can be called from any trigger. A restricted built-in is one that
causes navigation. A restricted trigger is one that fires during
navigation.
Any built-in subprogram that initiates navigation is restricted. This
includes subprograms that move the input focus from one item to
another AND subprograms that involve database transactions.
Restricted built-ins are illegal in triggers that fire in response to
navigation. Navigation can happen internally as a result of default
processing and can be unapparent to the form operator. Any trigger
(e.g. GO_ITEM) that initiates navigation cannot be called from
triggers that fire in response to INTERNAL NAVIGATION events. In
other words, these are triggers that fire while navigation is already
occurring, which include PRE- or POST- navigational triggers. You can
call restricted built-ins only where no internal navigation is occurring.
You CAN call a restricted built-in subprogram from:
1) a when_new_[OBJECT]_instance trigger because this trigger fires
AFTER navigation to the [OBJECT] has succeeded
2) WHEN triggers that are specific to interface items
(e.g. WHEN_BUTTON_PRESSED or WHEN_CHECKBOX_CHANGED)
3) KEY triggers
Error Processing and Built-ins
------------------------------
Calls to built-ins can succeed or fail. The programmer's
responsibility is to decide and define how processing should proceed
based on the success or failure of the built-in call. Theoretically,
error checking should be performed after EVERY call to a built-in.
Use FORM_FATAL, FORM_FAILURE, FORM_SUCCESS.
Example 1:
DECLARE
win_id WINDOW;
BEGIN
win_id := FIND_WINDOW('my_window');
-- check for problems and decide on a course of action
IF ID_NULL(win_id) THEN
MESSAGE('There is a problem here ....');
RAISE FORM_TRIGGER_FAILURE;
END IF;
-- instead of checking if the id is null,
-- you can check if the id is not null.
-- (i.e. to create a timer, first check if the timer does NOT exist)
END;
Example 2:
BEGIN
GO_ITEM('block.item_name');
IF NOT FORM_SUCCESS THEN
-- do what?
MESSAGE('There is a problem at this location');
RAISE FORM_TRIGGER_failure;
END IF;
-- do something else 1
-- do something else 2
-- do something else 3
END;
Example 3
BEGIN
:global.msg1 := ('There is a problem in place 1');
GO_ITEM('block.item_name');
checkit;
:global.msg1 := '';
-- do something else 1
-- do something else 2
-- do something else 3
END;
-- checkit procedure
BEGIN
IF NOT FORM_SUCCESS THEN
MESSAGE(:global.msg1);
RAISE FORM_TRIGGER_FAILURE;
END IF;
END;
Built-ins by Object Type
------------------------
[Items marked with an * are RESTRICTED built-ins].
Alert Built-ins Application Built-ins Block Built-ins
=============== ===================== ===============
FIND_ALERT DO_KEY* BLOCK_MENU
ID_NULL GET_APPLICATION_PROPERTY CLEAR_BLOCK*
SET_ALERT_BUTTON_PROPERTY HOST FIND_BLOCK
SET_ALERT_PROPERTY PAUSE GET_BLOCK_PROPERTY
SHOW_ALERT SET_APPLICATION_PROPERTY GO_BLOCK*
USER_EXIT ID_NULL
NEXT_BLOCK*
PREVIOUS_BLOCK*
SET_BLOCK_PROPERTY
Canvas/View Built-ins Form Built-ins Item Built-ins
===================== ============== ==============
FIND_CANVAS BELL CHECKBOX_CHECKED
FIND_VIEW BREAK CLEAR_EOL*
GET_CANVAS_PROPERTY CALL_FORM CLEAR_ITEM*
GET_VIEW_PROPERTY CALL_INPUT* CONVERT_OTHER_VALUE*
HIDE_VIEW CLEAR_FORM* COPY
ID_NULL COMMIT_FORM* COPY_REGION*
PRINT DEBUG_MODE CUT_REGION*
SCROLL_VIEW ENTER* DEFAULT_VALUE
SET_CANVAS_PROPERTY ERASE DISPLAY_ITEM*
SET_VIEW_PROPERTY EXECUTE_TRIGGER* DUPLICATE_ITEM*
SHOW_VIEW EXIT_FORM* EDIT_TEXTITEM*
FIND_FORM FIND_ITEM
FORM_FAILURE* GET_ITEM_PROPERTY
FORM_FATAL GET_RADIO_BUTTON_PROPERTY
FORM_SUCCESS GO_ITEM*
GET_FORM_PROPERTY ID_NULL
HELP* IMAGE_ZOOM
ID_NULL NAME_IN
NEW_FORM* NEXT_ITEM*
OPEN-FORM* NEXT_KEY*
POST* PASTE_REGION*
REDISPLAY PREVIOUS_ITEM*
REPLACE_MENU READ_IMAGE_FILE
SET_FORM_PROPERTY SELECT_ALL*
SHOW_KEYS SET_ITEM_PROPERTY
SHOW_MENU SET_RADIO_BUTTON_PROPERTY
SYNCHRONIZE WRITE_IMAGE_FILE
List Item Built-ins Menu Built-ins Messages Built-ins
=================== ============== ==================
ADD_LIST_ELEMENT APPLICATION_PARAMETER CLEAR_MESSAGE*
CLEAR_LIST BACKGROUND_MENU DBMS_ERROR_CODE
DELETE_LIST_ELEMENT FIND_MENU_ITEM DBMS_ERROR_TEXT
GET_LIST_ELEMENT_COUNT GET_MENU_ITEM_PROPERTY DISPLAY_ERROR
GET_LIST_ELEMENT_LABEL HIDE_MENUERROR_CODE
GET_LIST_ELEMENT_VALUE ITEM_ENABLED ERROR_TEXT
POPULATE_LIST MAIN_MENU* ERROR_TYPE
RETRIEVE_LIST MENU_CLEAR_FIELD GET_MESSAGE
MENU_NEXT_FIELD* MESSAGE
MENU_PARAMETER MESSAGE_CODE
MENU_PREVIOUS_FIELD MESSAGE_TEXT
MENU_REDISPLAY MESSAGE_TYPE
MENU_SHOW_KEYS
NEXT_MENU_ITEM*
PREVIOUS_MENU*
PREVIOUS_MENU_ITEM*
QUERY_PARAMETER
SET_INPUT_FOCUS
SET_MENU_ITEM_PROPERTY
SHOW_BACKGROUND_MENU
TERMINATE*
WHERE_DISPLAY
Misc Built-ins Multi-Form App Built-ins OLE Built-ins (MSW Only)
============== ======================== ========================
CREATE_TIMER CLOSE_FORM* FORMS_OLE.ACTIVATE_SERVER
DELETE_TIMER GO_FORM* FORMS_OLE.CLOSE_SERVER
FIND_EDITOR NEXT_FORM* FORMS_OLE.EXEC_VERB
FIND_LOV OPEN_FORM* FORMS_OLE.FIND_OLE_VERB
FIND_TIMER PREVIOUS_FORM* FORMS_OLE.GET_INTERFACE_
GET_LOV_PROPERTY POINTER
ID_NULL FORMS_OLE.GET_VERB_COUNT
LIST_VALUE FORMS_OLE.GET_VERB_NAME
SET_LOV_COLUMN_PROPERTY FORMS_OLE.INITIALIZE_
SET_LOV_PROPERTY CONTAINER
SET_TIMER FORMS_OLE.SERVER_ACTIVE
SHOW_EDITOR
SHOW_LOV
VALIDATE
Parameter List Built-ins Query Built-ins Relation Built-ins
======================== =============== ==================
ADD_PARAMETER ABORT_QUERY FIND_RELATION
CREATE_PARAMETER_LIST COUNT_QUERY* GET_RELATION_PROPERTY
DELETE_PARAMETER ENTER_QUERY* ID_NULL
DESTROY_PARAMETER_LIST EXECUTE_QUERY* SET_RELATION_PROPERTY
GET_PARAMETER_ATTR
GET_PARAMETER_LIST
ID_NULL
RUN_PRODUCT
SET_PARAMETER_ATTR
Record Built-ins Record Group Built-ins Transactional Built-ins
================ ====================== =======================
CHECK_RECORD_UNIQUENESS ADD_GROUP_COLUMN CHECK_RECORD_UNIQUENESS
CLEAR_RECORD* ADD_GROUP_ROW DELETE_RECORD*
CREATE_QUERRIED_RECORD* CREATE_GROUP ENFORCE_COLUMN_SECURITY
CREATE_RECORD* CREATE_GROUP_FROM_QUERY FETCH_RECORDS
DELETE_RECORD* DELETE_GROUP FORMS_DDL
DOWN* DELETE_GROUP_ROW GENERATE_SEQUENCE_NUMBER
DUPLICATE_RECORD* FIND_COLUMN INSERT_RECORD*
FIRST_RECORD* FIND_GROUP ISSUE_ROLLBACK
GENERATE_SEQUENCE_NUMBER GET_GROUP_CHAR_CELL ISSUE_SAVEPOINT
GET_RECORD_PROPERTY GET_GROUP_DATE_CELL LOGON
GO_RECORD* GET_GROUP_NUMBER_CELL LOGON_SCREEN
INSERT_RECORD* GET_GROUP_ROW_COUNT SELECT_RECORDS
LAST_RECORD GET_GROUP_SELECTION UPDATE_RECORDS*
LOCK_RECORD GET_GROUP_SELECTION_COUNT
NEXT_RECORD* ID_NULL
NEXT_SET* POPULATE_GROUP
PREVIOUS_RECORD* POPULATE_GROUP_WITH_QUERY
SCROLL_DOWN* RESET_GROUP_WITH_QUERY
SCROLL_UP* RESET_GROUP_SELECTION
SELECT_RECORDS* SET_GROUP_CHAR_CELL
SET_RECORD_PROPERTY SET_GROUP_DATE_CELL
UP SET_GROUP_NUMBER_CELL
UPDATE_RECORD* SET_GROUP_SELECTION
UNSET_GROUP_SELECTION
VBX Control Built-ins (MSW Only) Window Built-ins
================================ ================
VBX.FIRE_EVENT FIND_WINDOW
VBX.GET_PROPERTY HIDE_WINDOW
VBX.GET_VALUE_PROPERTY ID_NULL
VBX.INVOKE_METHOD MOVE_WINDOW
VBX.SET_PROPERTY REPLACE_CONTENT_VIEW
VBX.SET_VALUE_PROPERTY RESIZE_WINDOW
SHOW_WINDOW
The Developer/2000 built-in packages appear in the Object Navigator
under the Built-in Packages node. The services in these packages can
be used by any of the Developer/2000 Tools.
Packages Overview
-----------------
DDE
===
DDE is a mechanism by which applications can communicate and exchange
data in Windows. The DDE functions enable Oracle applications to
communicate with other DDE-compliant Windows applications.
DDE.APP_BEGIN
DDE.APP_END
DDE.APP_FOCUS
DDE.EXECUTE
DDE.GETFORMATNUM
DDE.GETFORMATSTR
DDE.INITIATE
DDE.POKE
DDE.REQUEST
DDE.TERMINATE
DEBUG
=====
The DEBUG package contains procedures, functions, and exceptions you
can use when debugging your PL/SQL program units.
DEBUG.BREAK
DEBUG.GETX
DEBUG.INTERPRET
DEBUG.SETX
DEBUG.SUSPEND
LIST
====
The LIST Package provides procedures, functions, and exceptions you
can use to create and maintain lists of character strings (VARCHAR2).
This provides a means of creating arrays in PL/SQL Version 1.
LIST.APPENDITEM
LIST.DESTROY
LIST.DELETEITEM
LIST.FAIL
LIST.GETITEM
LIST.INSERTITEM
LIST.LISTOFCHAR
LIST.MAKE
LIST.NITEMS
LIST.PREPENDITEM
OLE2
====
The OLE2 package provides a PL/SQL API for creating, manipulating, and
accessing attributes of OLE2 Automation Objects. OLE2 Automation
Objects encapsulate a set of attributes and methods that can be
manipulated or invoked from an OLE2 Automation Client. The OLE2
package allows users to access OLE2 Automation servers directly from
PL/SQL. Refer to the OLE2 Programmers documentation for each OLE2
Automation server for the object types, methods, and syntax
specification.
OLE2.ADD_ARG
OLE2.CREATE_ARGLIST
OLE2.CREATE_OBJ
OLE2.DESTROY_ARGLIST
OLE2.GET_CHAR_PROPERTY
OLE2.GET_NUM_PROPERTY
OLE2.GET_OBJ_PROPERTY
OLE2.INVOKE
OLE2.INVOKE_CHAR
OLE2.INVOKE_NUM
OLE2.INVOKE_OBJ
OLE2.LAST_EXCEPTION
OLE2.RELEASE_OBJ
OLE2.SET_PROPERTY
ORA_FFI Package
===============
The ORA_FFI package provides a foreign function interface for invoking
C functions in a dynamic library.
ORA_FFI.FFI_ERROR
ORA_FFI.FIND_FUNCTION
ORA_FFI.FIND_LIBRARY
ORA_FFI.FUNCHANDLETYPE
ORA_FFI.GENERATE_FOREIGN
ORA_FFI.IS_NULL_PTR
ORA_FFI.LIBHANDLETYPE
ORA_FFI.LOAD_LIBRARY
ORA_FFI.POINTERTYPE
ORA_FFI.REGISTER_FUNCTION
ORA_FFI.REGISTER_PARAMETER
ORA_FFI.UNLOAD_LIBARARY
ORA_NLS Package
===============
The ORA_NLS package enables you to extract high-level information
about your current language environment. You can use this information
to inspect attributes of the language, so you can customize your
applications to use local date and number formats. You can also
obtain information about character set collation and the character set
in general.
Facilities are also provided for retrieving the name of the current
language and character set, so you can create applications that test
for and take advantage of special cases.
ORA_NLS.AMERICAN
ORA_NLS.AMERICAN_DATE
ORA_NLS.BAD_ATTRIBUTE
ORA_NLS.GET_LANG_SCALAR
ORA_NLS.GET_LANG_STR
ORA_NLS.LINGUISTIC_COLLATE
ORA_NLS.LINGUISTIC_SPECIALS
ORA_NLS.MODIFIED_DATE_FMT
ORA_NLS.NO_ITEM
ORA_NLS.NOT_FOUND
ORA_NLS.RIGHT_TO_LEFT
ORA_NLS.SIMPLE_CS
ORA_NLS.SINGLE_BYTE
ORA_PROF Package
=================
The ORA_PROF package contains procedures, functions, and exceptions
you can use when tuning your PL/SQL program units. The services in
this package allow you to track the amount of time required to run
various pieces of your code.
ORA_PROF.BAD_TIMER
ORA_PROF.CREATE_TIMER
ORA_PROF.DESTROY_TIMER
ORA_PROF.ELAPSED_TIME
ORA_PROF.RESET_TIMER
ORA_PROF.START_TIMER
ORA_PROF.STOP_TIMER
TEXT_IO Package
===============
The TEXT_IO package contains constructs that provide ways to write and
read information to and from files. TEXT_IO offers several procedures
and functions, which fall into the following categories: file
operations, output (write) operations, and input (read) operations.
To see a complete example using several constructs from the TEXT_IO
package, see "Using TEXT_IO Constructs" in the Procedure Builder 1.5
Developer's Guide Manual. In addition, refer to Oracle Support
Bulletin 11165515.61 on using the TEXT_IO package.
TEXT_IO.FCLOSE
TEXT_IO.FILE_TYPE
TEXT_IO.FOPEN
TEXT_IO.GET_LINE
TEXT_I0.IS_OPEN
TEXT_IO.NEW_LINE
TEXT_IO.PUT
TEXT_IO.PUTF
TEXT_IO.PUT_LINE
TOOL_ENV Package
================
The TOOL_ENV package allows you to interact with Oracle environment variables.
TOOL_ENV.GETVAR
Example:
Given a procedure needs the current user's userid, include the
following PL/SQL statement using TOOL_ENV.GETVAR:
TOOL_ENV.GETVAR('USER', :userid);
TOOL_ERR Package
================
In addition to using exceptions to signal errors, some built-in
packages (e.g. DEBUG package) provide additional error information.
This information is maintained in the form of an "error stack".
The error stack contains detailed error codes and associated error
messages. Errors on the stack are indexed from zero (oldest) to n-1
(newest), where n is the number of errors currently on the stack.
Using the services provided by the TOOL_ERR package, you can access
and manipulate the error stack.
For a complete example see "Using TOOL_ERR Constructs" in the
Procedure Builder 1.5 Developer's Guide Manual.
TOOL_ERR.CLEAR
TOOL_ERR.CODE
TOOL_ERR.ENCODE
TOOL_ERR.MESSAGE
TOOL_ERR.NERRORS
TOOL_ERR.POP
TOOL_ERR.TOOL_ERROR
TOOL_ERR.TOP_ERROR
TOOL_RES Package
================
The TOOL_RES package provides you with a means of extracting string
resources from a resource file. The goal is to ease porting of PL/SQL
code from one language to another by isolating all of the textual data
in the resource file.
Building Resource Files:
------------------------
In addition to extracting textual data from existing resource files,
you can use the following utilities to create resource files that
contain textual data.
RESPA21 is a utility that generates a resource file (.RES) from a text
file (.PRN). The resulting resource file can be used with the
TOOL_RES package.
RESPR21 is a utility that converts a resource file (.RES) to a text
file (.PRN).
These utilities are distributed with Oracle*Terminal and are installed
automatically with this product. To display the supported command
line syntax of these utilities on your platform, run the utilities
without supplying any arguments.
TOOL_RES.BAD_FILE_HANDLE
TOOL_RES.BUFFER_OVERFLOW
TOOL_RES.FILE_NOT_FOUND
TOOL_RES.NO_RESOURCE
TOOL_RES.RFCLOSE
TOOL_RES.RFHANDLE
TOOL_RES.RFOPEN
TOOL_RES.RFREAD
References
----------
Forms 4.5 Forms Designer On Line HELP (Release 1.2)
Forms 4.5 Reference Manual Volume 1 (Release 1.2)
Chapter 3 and other miscellaneous chapters
Forms 4.5 Developer's Guide Manual (Release 1.2)
Chapters 2, 7, 18 and other miscellaneous chapters
Procedure Builder 1.5 Developer's Guide Manual
Chapter 8