首页 > 代码库 > APPCORE Routine APIs

APPCORE Routine APIs

Introduction to APPCORE Routine APIs

This chapter provides you with specifications for calling many Oracle E-Business Suite APIs from your PL/SQL procedures. Most routines in the APPCORE library are described here. Some APPCORE routines are described in other chapters (for example, the APP_SPECIAL routines are described in the chapter "Controlling the Toolbar and the Default Menu"). The routines described in this chapter include:

  • APP_COMBO: Combination Block API

  • APP_DATE: Date Conversion APIs

  • APP_EXCEPTION: Exception Processing APIs

  • APP_FIELD: Item Relationship Utilities

  • APP_FIND: Query Find Utilities

  • APP_ITEM: Individual Item Utilities

  • APP_ITEM_PROPERTY: Property Utilities

  • APP_NAVIGATE

  • APP_RECORD: Record Utilities

  • APP_REGION: Region Utilities

  • APP_STANDARD Package

  • APP_WINDOW: Window Utilities

APP_COMBO: Combination Block API

Use APP_COMBO to control navigation in combination blocks.

APP_COMBO.KEY_PREV_ITEM

VariableDescription
Summary
procedure  APP_COMBO.KEY_PREV_ITEM;
LocationAPPCORE library
DescriptionCall this procedure in the KEY-PREV-ITEM trigger to provide the standard behavior when back-tabbing from the first item in a record. This procedure ensures that the cursor automatically moves to the last item of the previous record.

See: Combination Blocks

APP_DATE and FND_DATE: Date Conversion APIs

You can use the APP_DATE and FND_DATE package utilities to format, convert, or validate dates. The packages are designed to hide the complexities of the various format masks associated with dates. These routines are particularly useful when you are manipulating dates as strings. The routines are designed to handle the multilingual, flexible format mask, and Y2K aspects of these conversions.

The APP_DATE routines are located in the APPCORE library and can be called from forms and other libraries, except for libraries that are attached to APPCORE, such as the CUSTOM library. For code in the CUSTOM library and other libraries attached to APPCORE, use the APP_DATE2 package in the special APPCORE2 library. The APP_DATE2 package is equivalent to APP_DATE, with the same routines and routine arguments.

The FND_DATE package is located in the database. You can call FND_DATE routines from SQL statements or other database packages. Many of the routines are in both the APP_DATE and the FND_DATE packages.

List of Date Terms

Because a date can be expressed in many different ways, it is useful to define several date-related terms that appear in the following APIs.

VariableDescription
Form date fieldA text item (in a form) that has a data type of "Date".
Form datetime fieldA text item (in a form) that has a data type of "Datetime".
Form character fieldA text item (in a form) that has a data type of "Char".
PL/SQL dateA PL/SQL variable declared as type "Date". Such a variable includes both date and time components.
User date formatThe format in which the user currently sees dates in forms.
User datetime formatThe format in which the user currently sees dates with a time component in forms.
Canonical date formatA standard format used to express a date as a string, independent of language. Oracle E-Business Suite uses YYYY/MM/DD HH24:MI:SS as the canonical date format.

Warning: The APP_DATE and FND_DATE routines make use of several package variables, such as canonical_mask, user_mask, and others. The proper behavior of Oracle E-Business Suite depends on these values being correct, and you should never change any of these variables.

APP_DATE.CANONICAL_TO_DATE and FND_DATE.CANONICAL_TO_DATE

VariableDescription
Summary
function APP_DATE.CANONICAL_TO_DATE(
     canonical varchar2)
return date;
VariableDescription
LocationAPPCORE library and database (stored function)
VariableDescription
DescriptionThis function takes a character string in the canonical date format (including a time component) and converts it to a PL/SQL date. 
If APP_DATE.CANONICAL_TO_DATE fails, the routine displays a message on the message line and raises form_trigger_failure. If FND_DATE.CANONICAL_TO_DATE fails, the routine raises a standard exception from the embedded TO_DATE call but does not return a message.
VariableDescription
Arguments (input)canonical - The VARCHAR2 string (in canonical format) to be converted to a PL/SQL date.

Example 1

declare
  hire_date varchar2(20) := ‘1980/01/01‘;
  num_days_employed number;
begin
  num_days_employed := trunc(sysdate) -
app_date.canonical_to_date(hire_date);
  message(‘Length of employment in days: ‘||
  to_char(num_days_employed));
end;

Example 2

select fnd_date.canonical_to_date(tab.my_char_date) 
from ...

APP_DATE.DISPLAYDATE_TO_DATE and FND_DATE.DISPLAYDATE_TO_DATE

VariableDescription
Summary
function APP_DATE.DISPLAYDATE_TO_DATE(chardate varchar2)
return date;
LocationAPPCORE library and database (stored function)
DescriptionThis function takes a character string in the user date format and converts it to a PL/SQL date. 
If APP_DATE.DISPLAYDATE_TO_DATE fails, the routine displays a message on the message line and raises form_trigger_failure. If FND_DATE.DISPLAYDATE_TO_DATE fails, the routine raises a standard exception from the embedded TO_DATE call but does not return a message.
In previous releases this function was named APP_DATE.CHARDATE_TO_DATE (that name has been retained for backwards compatibility).
Arguments (input)chardate - The VARCHAR2 string (in the user date format) to be converted to a PL/SQL date.

APP_DATE.DISPLAYDT_TO_DATE and FND_DATE.DISPLAYDT_TO_DATE

VariableDescription
Summary
function APP_DATE.DISPLAYDT_TO_DATE(charDT varchar2)
                  return date;
LocationAPPCORE library and database (stored function)
DescriptionThis function takes a character string in the user datetime format and converts it to a PL/SQL date. 
If APP_DATE.DISPLAYDT_TO_DATE fails, the routine displays a message on the message line and raises form_trigger_failure. If FND_DATE.DISPLAYDT_TO_DATE fails, the routine raises a standard exception from the embedded TO_DATE call but does not return a message.
In previous releases this function was named APP_DATE.CHARDT_TO_DATE (that name has been retained for backwards compatibility).
Arguments (input)charDT - The VARCHAR2 string (in the user datetime format) to be converted to a PL/SQL date.

APP_DATE.DATE_TO_CANONICAL and FND_DATE.DATE_TO_CANONICAL

VariableDescription
Summary
function APP_DATE.DATE_TO_CANONICAL(                  dateval date)                  return varchar2;
LocationAPPCORE library and database (stored function)
DescriptionThis function converts a PL/SQL date to a character string in the canonical date format. The entire time component is retained.
Arguments (input)dateval - The PL/SQL date to be converted.

Example

select fnd_date.date_to_canonical(hire_date) 
from emp ...

APP_DATE.DATE_TO_DISPLAYDATE and FND_DATE.DATE_TO_DISPLAYDATE

VariableDescription
Summary
function APP_DATE.DATE_TO_DISPLAYDATE(dateval date)  
return varchar2;
LocationAPPCORE library and database (stored function)
DescriptionThis function converts a PL/SQL date to a character string in the user date format. Any time component of the PL/SQL date is ignored. 
In previous releases this function was named APP_DATE.DATE_TO_CHARDATE (that name has been retained for backwards compatibility).
Arguments (input)dateval - The PL/SQL date to be converted.

Example

declare
  my_displaydate varchar2(30);
  my_dateval date;
begin
  my_displaydate :=
  app_date.date_to_displaydate(my_dateval);
end; 

APP_DATE.DATE_TO_DISPLAYDT and FND_DATE.DATE_TO_DISPLAYDT

VariableDescription
Summary
function APP_DATE.DATE_TO_DISPLAYDT(dateval date)
return varchar2;
LocationAPPCORE library and database (stored function)
DescriptionThis function converts a PL/SQL date to a character string in the user datetime format. Any time component of the PL/SQL date is preserved. 
In previous releases this function was named APP_DATE.DATE_TO_CHARDT (that name has been retained for backwards compatibility).
Arguments (input)dateval - The PL/SQL date to be converted.

Example

declare
  my_displaydt varchar2(30);
  my_dateval date;
begin
  my_displaydt :=
  app_date.date_to_displaydt(my_dateval);
end; 

APP_DATE.DATE_TO_FIELD

VariableDescription
Summary
procedure APP_DATE.DATE_TO_FIELD( dateval date,
          field varchar2,
          datetime varchar2 default ‘DEFAULT‘,   
          date_parameter boolean default FALSE);
LocationAPPCORE library
DescriptionThis procedure copies a PL/SQL date into a form field, form parameter, or global variable. Use this routine instead of the COPY built-in routine when date processing is required. 
When copying a value into form fields where the datatype is Date or Datetime, this procedure uses the appropriate internal mask to maintain the datatype.
When copying a value into form fields where the datatype is Char, by default this procedure applies the user datetime format if the field is long enough to hold it; otherwise this procedure applies the user date format.
When copying a value into global variables or form parameters, by default this procedure assumes a datatype of Char and applies the canonical date format, ignoring any time component. Use the date_parameter argument to override this behavior.
Arguments (input)dateval - The date to be copied.
field - The name of the field to which the date is copied, including the block name.
datetime - Use to override the default rules for determining date or datetime format. The default value is ‘DEFAULT‘. Specify ‘DATE‘ or ‘DATETIME‘ to force the copied value to have the date or datetime formats. Typically, you would use this argument to force the use of the datetime format in global variables and parameters, and for forcing use of the date format in character items that are longer than the datetime user mask.
date_parameter - Use this argument only if you are copying the value to a date parameter (with the date data type). If this argument is set to TRUE, the value is copied as a date value instead of as a character value.

Example

Replace the following code:

COPY(to_char(my_date_value, ‘DD-MON-YYYY {HR24:MI:SS}‘,‘my_block.my_date_field‘);

with the following code:

app_date.date_to_field(my_date_value, ‘my_block.my_date_field‘);

APP_DATE.FIELD_TO_DATE

VariableDescription
Summary
function APP_DATE.FIELD_TO_DATE(
	field varchar2 default NULL, 
	date_parameter boolean default FALSE)
 return date;
LocationAPPCORE library
DescriptionThis function takes a value from a form field, form parameter, or global variable and returns a PL/SQL date. Use this routine instead of the NAME_IN built-in routine when date processing is required. 
When copying a value from form fields where the datatype is Date or Datetime, this procedure uses the appropriate internal mask to maintain the time component.
When copying a value from form fields where the datatype is Char, this procedure applies the user datetime format if the field is long enough to hold it; otherwise this procedure applies the user date format.
When copying a value from global variables or form parameters, by default this procedure assumes a datatype of Char and applies the canonical date format, with or without the time component depending on the current length.
If APP_DATE.FIELD_TO_DATE fails, the routine raises a standard exception from the embedded TO_DATE call but does not return a message.
Arguments (input)field - The name of the field from which the date should be copied, including the block name.
date_parameter - Use this argument only if you are copying the value from a date parameter (with the date data type). If this argument is set to TRUE, the value is copied from the parameter as a date instead of as a character value.

Example

Replace the following code:

to_date(NAME_IN(‘my_block.my_date_field‘), ‘DD-MON-YYYY {HH24:MI:SS}‘);

with the following code:

my_date = app_date.field_to_date(‘my_block.my_date_field‘);

APP_DATE.VALIDATE_CHARDATE

VariableDescription
Summary
procedure APP_DATE.VALIDATE_CHARDATE(
field varchar2 default NULL)
LocationAPPCORE library
DescriptionThis procedure checks to see if a character value in a given form field (datatype Char) is a valid date by parsing it with the user date format. 
If the conversion to a date with no time component fails, the routine displays a message on the message line and raises form_trigger_failure. If the conversion succeeds, the routine copies the converted value back into the field to ensure display consistency.
Arguments (input)field - The name of the character field to be validated, including the block name. If no field name is passed in, the procedure uses SYSTEM.CURSOR_ITEM.

APP_DATE.VALIDATE_CHARDT

VariableDescription
Summary
procedure APP_DATE.VALIDATE_CHARDT(
 field varchar2 default NULL)
LocationAPPCORE library
DescriptionThis procedure checks to see if a character value in a given form field (datatype Char) is a valid datetime string by parsing it with the user datetime format. 
If the conversion to a date with a time component fails, the routine displays a message on the message line and raises form_trigger_failure. If the conversion succeeds, the routine copies the converted value back into the field to ensure display consistency.
Arguments (input)field - The name of the character field to be validated, including the block name. If no field name is passed in, the procedure uses SYSTEM.CURSOR_ITEM.

FND_DATE.STRING_TO_DATE

VariableDescription
Summary
function FND_DATE.STRING_TO_DATE(
	p_string IN VARCHAR2,
	p_mask   IN VARCHAR2)                    
RETURN DATE; 
LocationDatabase (stored function)
DescriptionThis function converts a character string to a PL/SQL date using the given date format mask. This function tests all installed languages, if necessary, to find one that matches the language-dependent fragments of the given string. Use this routine when you need to convert character string data to dates and are unsure of the language used to store the character date.
This function returns NULL if the string cannot be converted. There is no error message. Your code must test for a NULL return value and handle the error as appropriate.
Language is important if the mask has language-dependent fragments, as in the format mask DD-MON-RRRR, where the "MON" fragment is language dependent. For example, the abbreviation for February is FEB, but the French abbreviation is FEV. The language testing order of this function is:
Language indicated by the setting of "NUMERIC DATE LANGUAGE".
Current (default) database language.
The "Base" language of the Oracle E-Business Suite installation (where the INSTALLED_FLAG column of the FND_LANGUAGES table is set to "B").
Other installed languages, ordered by the NLS_LANGUAGE column of the FND_LANGUAGES table (where the INSTALLED_FLAG column is set to "I").
Arguments (input)p_string - The character string to be converted.
p_mask - The format mask to use for the conversion, such as DD-MON-RRRR.

FND_DATE.STRING_TO_CANONICAL

VariableDescription
Summary
function FND_DATE.STRING_TO_CANONICAL(
     p_string IN VARCHAR2, 
     p_mask   IN VARCHAR2)
RETURN VARCHAR2; 
LocationDatabase (stored function)
DescriptionThis function is identical to FND_DATE.STRING_TO_DATE except that this function returns a character string in the canonical date format instead of returning a PL/SQL date.
Arguments (input)p_string - The character string to be converted.
p_mask - The format mask to use for the conversion, such as DD-MON-RRRR.

APP_EXCEPTION: Exception Processing APIs

You should use the APPCORE package APP_EXCEPTION to raise exceptions in the PL/SQL procedures written for your forms.

APP_EXCEPTION.RAISE_EXCEPTION

VariableDescription
Summary
procedure  APP_EXCEPTION.RAISE_EXCEPTION(
 exception_type varchar2 default null,
			  exception_code number   default null,
			  exception_text varchar2 default null);
LocationAPPCORE library and database (stored procedure)
DescriptionThis procedure stores exception information and raises exception form_trigger_failure.
VariableDescription
exception_textAdditional context information.
exception_typeError prefix that specifies error type (for example, ORA or APP)
exception_codeThe number that identifies the error.

APP_EXCEPTION.RETRIEVE

VariableDescription
Summary
procedure  APP_EXCEPTION.RETRIEVE;
LocationAPPCORE library and database (stored procedure)
DescriptionThis procedure retrieves exception information from the database.

APP_EXCEPTION.GET_TYPE

VariableDescription
Summary
function  APP_EXCEPTION.GET_TYPE return varchar2;
LocationAPPCORE library and database (stored function)
DescriptionThis function returns the exception type.

APP_EXCEPTION.GET_CODE

VariableDescription
Summary
function  APP_EXCEPTION.GET_CODE return number;
LocationAPPCORE library and database (stored function)
DescriptionThis function returns the exception code.

APP_EXCEPTION.GET_TEXT

VariableDescription
Summary
function  APP_EXCEPTION.GET_TEXT return varchar2;
LocationAPPCORE library and database (stored function)
DescriptionThis function returns the exception text.

APP_EXCEPTION.RECORD_LOCK_EXCEPTION

VariableDescription
DescriptionThis is a predefined exception. Call it in an exception handler to handle cases where the record cannot be locked. It is usually used with the APP_EXCEPTION.RECORD_LOCK_ERROR procedure.

APP_EXCEPTION.RECORD_LOCK_ERROR

VariableDescription
Summary
procedure  APP_EXCEPTION.RECORD_LOCK_ERROR (
counter  IN   OUT   number);
DescriptionThis procedure asks the user to continue or cancel an attempt to lock a record. It returns to the calling procedure to try again if the user continues. It displays an "Unable to reserve record" acknowledgement and raises FORM_TRIGGER_FAILURE if the user cancels.
APP_EXCEPTION.RECORD_LOCK_ERROR only asks the user every two attempts to lock a record (e.g., counter = 2, 4, 6, etc.). The calling procedure should attempt to lock the record in a loop and call RECORD_LOCK_ERROR in a WHEN APP_EXCEPTION.RECORD_ LOCK_EXCEPTION exception handler inside the loop. If the user continues, RECORD_LOCK_ERROR returns and the loop repeats. If the user cancels, RECORD_LOCK_ERROR raises FORM_TRIGGER_FAILURE and the loop exits.
VariableDescription
counterMaintained by RECORD_LOCK_ERROR to count the attempts to lock a record. Calling procedure should initialize to null or 0.

APP_EXCEPTION.DISABLED

VariableDescription
Summary
procedure  APP_EXCEPTION.DISABLED;
DescriptionThis procedure rings the bell. Call this procedure to disable simple functions (typically in a KEY- trigger).

APP_FIELD: Item Relationship Utilities

This section describes utilities you can use to maintain relationships between your form items.

APP_FIELD.CLEAR_FIELDS

VariableDescription
Summary
procedure  APP_FIELD.CLEAR_FIELDS(
 field1  varchar2, 
			 field2  varchar2 default NULL,
			 field3  varchar2 default NULL,
			 field4  varchar2 default NULL,
			 field5  varchar2 default NULL,
			 field6  varchar2 default NULL,
			 field7  varchar2 default NULL,
			 field8  varchar2 default NULL,
			 field9  varchar2 default NULL,
			 field10 varchar2 default NULL);
DescriptionThis procedure clears up to ten items if the items are not NULL and are not check boxes or required lists.

APP_FIELD.CLEAR_DEPENDENT_FIELDS

VariableDescription
Summary
procedure  APP_FIELD.CLEAR_DEPENDENT_FIELDS(
master_field varchar2,
			 field1  varchar2,
			 field2  varchar2 default NULL,
			 field3  varchar2 default NULL,
			 field4  varchar2 default NULL,
			 field5  varchar2 default NULL,
			 field6  varchar2 default NULL,
			 field7  varchar2 default NULL,
			 field8  varchar2 default NULL,
			 field9  varchar2 default NULL,
			 field10 varchar2 default NULL); 
DescriptionThis procedure clears up to ten dependent items if the master item is NULL and the dependent items are not NULL and not check boxes or required lists.
VariableDescription
master_fieldName of master item
field1 ... field10Name of dependent item(s).

APP_FIELD.SET_DEPENDENT_FIELD

VariableDescription
Summary
procedure  APP_FIELD.SET_DEPENDENT_FIELD(event           varchar2,
			master_field    varchar2,
			dependent_field varchar2
			invalidate      boolean    default  FALSE);   
procedure  APP_FIELD.SET_DEPENDENT_FIELD(
event           varchar2,
			condition       boolean,
			dependent_field varchar2
			invalidate      boolean    default  FALSE);   
DescriptionThis procedure makes an item enterable or not enterable based on whether the master item is NULL or a specified condition is TRUE, and clears the field. The dependent item can be a text item, check box, or poplist.
You typically call this procedure in the following triggers:

Triggers:

  • WHEN-VALIDATE-ITEM on the master field

  • WHEN-VALIDATE-ITEM on the field(s) the condition is based on or in event INIT on the dependent field

  • PRE-RECORD

  • POST-QUERY (required only when the dependent item is in a multi-record block)

VariableDescription
eventName of trigger event. If you call this trigger on a master field, pass VALIDATE instead of the trigger name (which may be WHEN-VALIDATE-ITEM, WHEN-CHECKBOX-CHANGED, WHEN-LIST-CHANGED, or WHEN-RADIO-CHANGED, any of which can also be used).
master_fieldName of master item
conditionTRUE when dependent item is to be enabled
dependent_fieldName of dependent item
invalidateIf TRUE, mark the item as invalid instead of clearing the dependent item. Set this flag to TRUE if the dependent item is a required list or option group.
For examples on using this procedure, see:Item Relations, , Mutually Inclusive Items with Dependent Items and Defaults.

APP_FIELD.SET_EXCLUSIVE_FIELD

VariableDescription
Summary
procedure  APP_FIELD.SET_EXCLUSIVE_FIELD(
event           varchar2,
			field1           varchar2,
			field2           varchar2,
			field3           varchar2  default NULL);
DescriptionThis procedure coordinates items so that only one item of a set may contain a value. If a value is entered in one of the items, the other items are cleared and made non-NAVIGABLE (users can still mouse into these items). This procedure only covers sets of two or three mutually-exclusive items.
VariableDescription
eventName of trigger event (WHEN-NEW-RECORD-INSTANCE, PRE-RECORD, or VALIDATE. VALIDATE is generally used in place of WHEN-VALIDATE-ITEM, WHEN-RADIO-CHANGED, WHEN-LIST-CHANGED, or WHEN-CHECKBOX-CHANGED, any of which can also be used.)
field1Name of exclusive item (BLOCK.FIELD)
field2Name of exclusive item (BLOCK.FIELD)
field3Name of exclusive item (BLOCK.FIELD, optional)

For examples on using this procedure, see: Mutually Exclusive Items.

APP_FIELD.SET_INCLUSIVE_FIELD

VariableDescription
Summary
procedure  APP_FIELD.SET_INCLUSIVE_FIELD(
event           varchar2,
			field1           varchar2,
			field2           varchar2,
			field3           varchar2  default NULL,
			field4           varchar2  default NULL,
			field5           varchar2  default NULL);
DescriptionThis procedure coordinates up to five items so that if any of the items contains a value, then all of the items require a value. If all of the items are NULL, then the items are not required.
VariableDescription
eventName of trigger event (WHEN-NEW-RECORD-INSTANCE, PRE-RECORD, or VALIDATE. VALIDATE is generally used in place of WHEN-VALIDATE-ITEM, WHEN-RADIO-CHANGED, WHEN-LIST-CHANGED, or WHEN-CHECKBOX-CHANGED, any of which can also be used.)
field1Name of inclusive item
field2Name of inclusive item
field3Name of inclusive item (optional)
field4Name of inclusive item (optional)
field5Name of inclusive item (optional)

For examples on using this procedure, see: Mutually Inclusive Items.

APP_FIELD.SET_REQUIRED_FIELD

VariableDescription
Summary
procedure  APP_FIELD.SET_REQUIRED_FIELD(
event           varchar2,
			condition       boolean,
			field1           varchar2,
			field2           varchar2  default NULL,
			field3           varchar2  default NULL,
			field4           varchar2  default NULL,
			field5           varchar2  default NULL);

DescriptionThis procedure makes an item required or not required based on whether a specified condition is true.
VariableDescription
eventName of trigger event
conditionTrue when items should be required
field1Name of item
field2Name of item
field3Name of item (optional)
field4Name of item (optional)
field5Name of item (optional)

For examples on using this procedure, see: Conditionally Mandatory Items.

APP_FIND: Query-Find Utilities

Use the following routines to implement the Find Window functionality.

See: Overview of Query Find

APP_FIND.NEW

VariableDescription
Summary
procedure  APP_FIND.NEW(
block_name varchar2);
DescriptionThis routine is called by the "New" button in a Find Window to return the user to a new record in the block on which the find is based.
VariableDescription
block_nameThe name of the block the Find Window is based on

APP_FIND.CLEAR

VariableDescription
Summary
procedure  APP_FIND.CLEAR;
DescriptionThis routine is called by the "Clear" button in a Find Window to clear the Find Window.

APP_FIND.CLEAR_DETAIL

VariableDescription
Summary
procedure  APP_FIND.CLEAR_DETAIL(
detail_block    varchar2);
DescriptionThis routine clears the result block of a find block (not a Find window). This action can only be performed from triggers that allow navigation.
VariableDescription
detail_blockThe name of the block to be cleared

Example

APP_FIND.CLEAR_DETAIL(‘MYBLOCK‘);

APP_FIND.FIND

VariableDescription
Summary
procedure  APP_FIND.FIND(
block_name    varchar2);

DescriptionThis routine is called by the "Find" button in a Find Window to execute the Find.
VariableDescription
block_nameThe name of the block the Find Window is based on

APP_FIND.QUERY_RANGE

VariableDescription
Summary
procedure  APP_FIND.QUERY_RANGE(
low_value    varchar2/date/number,
			high_value   varchar2/date/number,
			db_item_name varchar2);
DescriptionThis utility constructs the query criteria for ranges in a Find Window. Depending on the datatype of the low and high value, it creates a range of characters, dates, or numbers.
VariableDescription
low_valueThe low value of the range
high_valueThe high value of the range
db_item_nameThe name of the item in the block that is being queried

APP_FIND.QUERY_FIND

VariableDescription
Summary
procedure  APP_FIND.QUERY_FIND(
lov_name varchar2);

procedure APP_FIND.QUERY_FIND(
			block_window    varchar2,
			find_window     varchar2,
			find_block      varchar2);
DescriptionThese routines invoke either the Row-LOV or the Find Window. Call them from a user-named trigger "QUERY_FIND."
VariableDescription
lov_nameThe name of the Row-LOV
block_windowThe name of the window the Find Window is invoked for
find_windowThe name of the Find Window
find_blockThe name of the block in the Find Window

APP_ITEM: Individual Item Utilities

This section describes utilities for managing your items individually.

APP_ITEM.COPY_DATE

VariableDescription
Summary
procedure  APP_ITEM.COPY_DATE(
date_val  varchar2
			item_name varchar2);
DescriptionUse this procedure to copy a hardcoded date value into a field. This routine does the copy in this way:
copy(to_char(to_date(‘01-01-1900‘, ‘DD-MM-YYYY‘),
               ‘DD-MON-YYYY‘), ‘bar.lamb‘);
VariableDescription
date_valA character date, expressed in the format ‘DD-MM-YYYY‘
item_nameThe name of the item to copy the value into, expressed as block.item.

APP_ITEM.IS_VALID

VariableDescription
Summary
procedure  APP_ITEM.IS_VALID(
        val         varchar2
			dtype       varchar2  default ‘DATE‘);

function APP_ITEM.IS_VALID(
			val         varchar2
			dtype       varchar2  default ‘DATE‘)
return BOOLEAN;
DescriptionUse this routine with fields that are of character datatype but contain data in the format of a date, number or integer. The procedure raises an error if the value is not in a valid format for the specified datatype. The function returns TRUE if the value is in the correct format, otherwise FALSE
VariableDescription
valValue to be checked
dtypeDatatype value should use: DATE, INTEGER, or NUMBER.

APP_ITEM.SIZE_WIDGET

VariableDescription
Summary
procedure  APP_ITEM.SIZE_WIDGET(
        wid_name varchar2.
			max_width number default 20);

DescriptionThis procedure reads the current label for the specified widget and resizes the widget to fully show the label (used to ensure proper size for a translated label). It will not make the widget any larger than the maximum width specified, to prevent overlapping or expansion beyond the edge of the screen. Call this procedure only for check boxes in single-record formats, buttons and radio groups.
VariableDescription
wid_nameName of the widget in block.field syntax
max_widthThe maximum size to make the widget, in inches

APP_ITEM_PROPERTY: Property Utilities

These utilities help you control the Oracle Forms and Oracle E-Business Suite properties of your items.

APP_ITEM_PROPERTY.GET_PROPERTY

VariableDescription
Summary
function  APP_ITEM_PROPERTY.GET_PROPERTY(
       item_name varchar2, 
			property number) 
			return number;
function  APP_ITEM_PROPERTY.GET_PROPERTY(
			item_id item, 
			property number)
			 return number;
DescriptionThis function returns the current setting of an item property. It differs from the Oracle Forms‘s get_item_property in that it returns PROPERTY_ON or PROPERTY_OFF instead of TRUE or FALSE.
VariableDescription
item_nameName of the item to apply the property attribute to. Specify both the block and item name. You can supply the item_ID instead of the name of the item.
propertyThe property to set.

See: Setting Item Properties.

APP_ITEM_PROPERTY.SET_PROPERTY

VariableDescription
Summary
procedure  APP_ITEM_PROPERTY.SET_PROPERTY(
       item_name varchar2, 
			property varchar2, 
			value number);
procedure  APP_ITEM_PROPERTY.SET_PROPERTY(
			item_id item, 
			property varchar2,
			value number);
DescriptionThis procedure sets the property of an item. You should never use the Oracle Forms built-in SET_ITEM_PROPERTY to set the field properties DISPLAYED, ENABLED, ENTERABLE, ALTERABLE, INSERT_ ALLOWED, UPDATEABLE, NAVIGABLE, REQUIRED, and ICON_NAME directly. Use APP_ITEM_PROPERTY.SET_PROPERTY instead.
APP_ITEM_PROPERTY.SET_PROPERTY remaps some properties to do other things like change visual attributes. Also, there are some properties that APP_ITEM_PROPERTY provides that native Oracle Forms does not.
VariableDescription
item_nameName of the item to apply the property attribute to. Specify both the block and item name. You can supply the item_ID instead of the name of the item.
propertyThe property to set.
valueEither PROPERTY_ON or PROPERTY_OFF, or an icon name (to change the icon property).

See: Setting Item Properties

APP_ITEM_PROPERTY.SET_VISUAL_ATTRIBUTE

VariableDescription
Summary
procedure  APP_ITEM_PROPERTY.SET_VISUAL_ATTRIBUTE(
item_name varchar2, 
			property number 
			value number);

DescriptionThis procedure is no longer used. All colors are set as part of the Oracle Look and Feel (OLAF).

APP_NAVIGATE: Open a Form Function

Use this utility instead of FND_FUNCTION.EXECUTE to open a form function where you want to reuse an instance of the same form that has already been opened. Use FND_FUNCTION.EXECUTE for all other cases of opening forms and functions.

APP_NAVIGATE.EXECUTE

VariableDescription
Summary
procedure APP_NAVIGATE.EXECUTE( 		
		function_name	in varchar2, 		o
		pen_flag 	in varchar2 default ‘Y‘, 		
		session_flag	in varchar2 default ‘SESSION‘, 		
		other_params	in varchar2 default NULL, 		
		activate_flag	in varchar2 default ‘ACTIVATE‘, 		
		pinned	in boolean  default FALSE);
DescriptionThis procedure is similar to FND_FUNCTION.EXECUTE, except that it allows a form to be restarted if it is invoked a second time. For example, if form A invokes function B with this procedure, then at a later time invokes function B again, the same instance of form B will be reused (and form B would be restarted using any new parameters passed in the second call to APP_NAVIGATE.EXECUTE). This functionality is useful where you have a form B built to appear as a detail window of another form (A), and you want the "detail window" to reflect changes in the "master window". In contrast, FND_FUNCTION.EXECUTE always starts a new instance of a form. 
Only a function that was previously invoked using this call is a candidate for restarting; a function invoked with FND_FUNCTION.EXECUTE cannot be restarted if later a call is made to APP_NAVIGATE.EXECUTE. 
Multiple forms can share the same target form. For example, if form A invokes function B with APP_NAVIGATE.EXECUTE, and then later form C also invokes function B, the current instance of form B will be restarted.
APP_NAVIGATE.EXECUTE and FND_FUNCTION.EXECUTE store the position and size of the current (source) window in the following global variables so that the target form can access them:
  • global.fnd_launch_win_x_pos

  • global.fnd_launch_win_y_pos

  • global.fnd_launch_win_width

  • global.fnd_launch_win_height


The intended usage is so that the target form can be positioned relative to the current window of the calling form. When calling APP_NAVIGATE.EXECUTE, these values are available when the target form is opened the first time; it is not valid to refer to them during the RESTART event. 
Using APP_NAVIGATE.EXECUTE requires special code in the target form (form B) to respond to the APP_NAVIGATE.EXECUTE call appropriately. The target form must contain a user-named trigger called RESTART, as well as the required calls to APP_STANDARD.EVENT in the WHEN-NEW-FORM-INSTANCE and WHEN-FORM-NAVIGATE triggers. When a form is reused with APP_NAVIGATE, APPCORE will:
  1. Issue a do_key(‘clear_form‘) in the target form. This fires the same logic as when the user does Edit->Clear->Form. This is done to trap any pending changes in the target form.

  2. If that succeeds, then all form parameters in the target form are repopulated (parameters associated with the function called by APP_NAVIGATE, as well as values in the other_params argument specifically passed in by APP_NAVIGATE).

  3. User-named trigger RESTART in the target form is executed.


A good coding technique is to place all logic that responds to parameter values in a single procedure and have your WHEN-NEW-FORM-INSTANCE and RESTART triggers both call it. You may also want to add code called from the WHEN-NEW-FORM-INSTANCE trigger in the target form that checks the variables set by FND_FUNCTION.EXECUTE or APP_NAVIGATE.EXECUTE to indicate the position of the source form. You can then use these values to set the position of the target form relative to the source form.
Arguments (input)function_name - The developer name of the form function to execute.
open_flag - ‘Y‘ indicates that OPEN_FORM should be used; ‘N‘ indicates that NEW_FORM should be used. You should always pass ‘Y‘ for open_flag, which means to execute the function using the Oracle Forms OPEN_FORM built-in rather than the NEW_FORM built-in.
session_flag - Passing ‘Y‘ for session_flag (the default) opens your form in a new database session, while ‘N‘ opens the form in the same session as the existing form. Opening a form in a new database session causes the form to have an independent commit cycle. 
other_params - An additional parameter string that is appended to any parameters defined for the function in the Forms Functions form. You can use other_params to set some parameters dynamically. It can take any number of parameters. 
activate_flag - Either ACTIVATE or NO_ACTIVATE (default is ACTIVATE). This flag determines whether the focus goes to the new form (ACTIVATE) or remains in the calling form (NO_ACTIVATE). 
pinned - If set to TRUE will open a new instance of the function, never to be reused (the same as FND_FUNCTION.EXECUTE). If set to FALSE will attempt to reuse an instance of the function if it is currently running and was launched via APP_NAVIGATE.EXECUTE; otherwise it will open a new instance.

APP_RECORD: Record Utilities

Following are utilities that interact with a block at the record level.

APP_RECORD.TOUCH_RECORD

VariableDescription
Summary
procedure  TOUCH_RECORD(
		block_name		varchar2	default NULL,
	 	record_number		NUMBER		default NULL); 
DescriptionSets the status of a NEW record to INSERT_STATUS. For a QUERY record, the record is locked and the status is set to CHANGED_STATUS. In both cases this flags the record to be saved to the database.
VariableDescription
block_nameThe name of the block to touch
record_numberThe record that will be touched

APP_RECORD.HIGHLIGHT

VariableDescription
Summary
procedure  APP_RECORD.HIGHLIGHT(
		value		varchar2/number); 
DescriptionThis call changes the visual attribute of the current record by calling the DISPLAY_ITEM built-in for each multirow TEXT_ITEM, LIST and DISPLAY_ITEM of the current record. It will do nothing for items in which the RECORDS_DISPLAYED property is 1. To highlight data, pass ‘SELECTED_DATA‘. To turn off highlighting, pass ‘DATA‘. You can pass the name of any visual attribute you want to apply.
VariableDescription
valueThe name of the visual attribute you want to apply.
For more information, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.

Tip: To improve performance for large blocks with many hidden fields, position all hidden fields at the end of the block, and place a non-database item named "APPCORE_STOP" before the hidden items. When APP_RECORD.HIGHLIGHT reaches this field, it stops highlighting.

APP_RECORD.FOR_ALL_RECORDS

VariableDescription
Summary
procedure  APP_RECORD.FOR_ALL_RECORDS(
		block_name      varchar2, 
		trigger_name     varchar2);
procedure APP_RECORD.FOR_ALL_RECORDS(
			trigger_name     varchar2);
DescriptionThis call executes the specified trigger for every record of the current block or the specified block. If you specify a block, the GO_BLOCK built-in fires. When finished, the cursor returns to the original record and item. 
If the trigger fails, FORM_TRIGGER_FAILURE is raised and the cursor is left in the record in which the failure occurred. 
You can pass arguments to the specified trigger using global variables simply by setting the global variables before calling this routine. 
APP_RECORD.FOR_ALL_RECORDS fires once when there are no queried records.
VariableDescription
block_nameThe name of the block to navigate to
trigger_nameName of the trigger to execute

APP_RECORD.DELETE_ROW

VariableDescription
Summary
procedure  APP_RECORD.DELETE_ROW(
			check_delete        BOOLEAN   default FALSE,
			product_name        varchar2  default NULL,
			message_name        varchar2  default NULL);

function  APP_RECORD.DELETE_ROW(
			check_delete        BOOLEAN   default FALSE,
			product_name        varchar2  default NULL,
			message_name        varchar2  default NULL)
			return BOOLEAN;
DescriptionThis call provides a generic message to insure that the user really intends to delete the row. 
If the function version of this routine is called, it does not delete the row but returns TRUE if the user responds with a confirmation to delete the record and FALSE otherwise. If you have a complex delete, you can first confirm that the user wants to delete the record.
If the procedure version of this routine is called, the record is deleted if the user responds affirmatively. You should provide your own message when there is more than one block that allows delete.
VariableDescription
check_deleteForces block DELETE_ALLOWED to be checked (optional)
product_nameThe product shortname needed if passing your own message. Otherwise a default message will be supplied (optional)
message_nameThe name of the message if a product_name is supplied (optional)

APP_RECORD.VALIDATE_RANGE

VariableDescription
Summary
procedure  APP_RECORD.VALIDATE_RANGE(
		from_item     varchar2,
		to_item       varchar2,
		range_name    varchar2  default NULL,
		event_name    varchar2  default ‘WHEN-BUTTON-PRESSED‘,
		dtype         varchar2  default ‘DATE‘,
		product_name  varchar2  default NULL,
		message_name  varchar2  default NULL);
DescriptionThis call validates a range to assure that the "from" value is less than the "to" value. Call this routine from the WHEN-BUTTON-PRESSED trigger of a Find button, or a WHEN-VALIDATE-RECORD trigger (for example) to verify that any range data entered by the user is valid. 
If the range is invalid, the routine attempts to navigate to the beginning of the range. If you call VALIDATE_RANGE from a trigger that does not allow navigation, then provide a range name so that it can be displayed to the user when the default message is displayed.
You should define the range name in message dictionary and pass the message name to VALIDATE_RANGE. When you define your message, you should include a description that lets the translators know that it should be translated the same as the range title.
VariableDescription
from_itemThe block.item of the from value
to_itemThe block.item of the to value
range_nameName of the range (optional)
event_nameTrigger name, used to determine if navigation is possible (optional)
dtypeDatatype of the range (NUMBER or DATE, defaults to DATE) (optional)
product_nameThe product shortname needed if passing your own message. Otherwise a default message will be supplied (optional)
message_nameThe name of the message, if a product_name is supplied (optional)

APP_REGION: Region Utilities

Following are utilities used with alternative regions (for backwards compatibility only; alternative regions have been replaced by tabs).

APP_REGION.ALT_REGION

VariableDescription
Summary
function  APP_REGION.ALT_REGIONS(  		
		poplist_name varchar2)   		     
				return BOOLEAN;
DescriptionTakes the values currently in the poplist identified by poplist_name and shows them in LOV ‘appcore_alt_regions‘ (referenced in from APPSTAND automatically). If the user selects a row from the LOV, the corresponding poplist value will be updated and TRUE will be returned; otherwise no changes will be made to the poplist and this will return FALSE. Used for keyboard support of alternative region control.
VariableDescription
poplist_nameThe control poplist for an alternative region (‘block.field‘ format).

Example

if APP_REGION.ALT_REGIONS(‘CONTROL.LINE_REGIONS‘) then
    CONTROL.LINE_REGIONS(‘WHEN-LIST-CHANGED‘);
end if;

See: Coding Alternative Region Behavior

APP_STANDARD Package

APP_STANDARD.APP_VALIDATE

VariableDescription
Summary
procedure  APP_STANDARD.APP_VALIDATE (scope NUMBER);
DescriptionThis procedure acts similarly to Oracle Forms‘ built-in Validate, except that it navigates to the first item that caused the validation failure, and it provides support for the button standard. Use it instead of the Oracle Forms built-in.
VariableDescription
scopeThe scope of the validation. Valid values are DEFAULT_SCOPE, FORM_SCOPE, BLOCK_SCOPE, RECORD_SCOPE, and ITEM_SCOPE.

APP_STANDARD.EVENT

VariableDescription
Summary
procedure  APP_STANDARD.EVENT (
		event_name        varchar2);
DescriptionThis procedure invokes the standard behavior for the specified event. The TEMPLATE form contains all necessary calls to this trigger.
VariableDescription
event_nameName of the event or trigger

See: Special Triggers in the TEMPLATE form

APP_STANDARD.SYNCHRONIZE

VariableDescription
Summary
procedure  APP_STANDARD.SYNCHRONIZE;
DescriptionDynamic changes to the form can affect which menu items apply, although the state of the menu items is not re-evaluated automatically. If you make a change that affects which items in the toolbar and menu can be used, call this routine, and it re-evaluates the menu and toolbar. (For example, changing the INSERTABLE property of a block, changing the status of a record, etc.) 
See: Pulldown Menus and the Toolbar.

APP_STANDARD.PLATFORM

VariableDescription
Summary
APP_STANDARD.PLATFORM varchar2(30);
DescriptionThis package variable stores the name of the value returned by GET_APPLICATION_PROPERTY(USER_INTERFACE). Valid values include ‘MACINTOSH‘, MSWINDOWS‘, MSWINDOWS32‘, and ‘MOTIF‘.

Example

if APP_STANDARD.PLATFORM = ‘MSWINDOWS‘ then
		MDI_height := get_window_property(FORMS_MDI_WINDOW,
														HEIGHT); end if;  

APP_WINDOW: Window Utilities

The following utilities operate at the window level.

APP_WINDOW.CLOSE_FIRST_WINDOW

VariableDescription
Summary
procedure  APP_WINDOW.CLOSE_FIRST_WINDOW;  
DescriptionThis call exits the form. It raises FORM_TRIGGER_FAILURE if it fails.

APP_WINDOW.PROGRESS

VariableDescription
Summary
procedure  APP_WINDOW.PROGRESS( percent    number);  
DescriptionThis call manages all aspects of the progress_indicator object. If it is not already visible, the call opens and centers the window. When the percent >= 99.9, the window automatically closes. For any other percent, the progress bar resizes (with a four inch wide maximum).
VariableDescription
percentA number between 0 and 99.9, expressing the amount competed.

APP_WINDOW.SET_COORDINATION

VariableDescription
Summary
procedure  APP_WINDOW.SET_COORDINATION(
		event           varchar2,
		coordination    varchar2,
		relation_name   varchar2);
DescriptionThis call sets the deferred coordination attribute of a relation to ON or OFF based on the state of the coordination check box. The check box is either "DEFERRED" or "IMMEDIATE."
For a closed window, the relation is always "DEFERRED." 
When coordination is set to "DEFERRED," AutoQuery is turned on.
VariableDescription
eventThe name of the trigger event (either WHEN-CHECKBOX-CHANGED, WHEN-WINDOW-CLOSED, or OPEN-WINDOW)
coordinationIMMEDIATE or DEFERRED. Defaults to IMMEDIATE
relation_nameName of the relation, which is listed in the Oracle Forms Designer under the Block object in the Relation object

See: Master-Detail Relations

APP_WINDOW.SET_WINDOW_POSITION

VariableDescription
Summary
procedure  APP_WINDOW.SET_WINDOW_POSITION(
		child          varchar2,
		rel            varchar2,
		parent         varchar2     default  NULL);
DescriptionThis call positions a window in the following styles:
  • CASCADE

  • RIGHT

  • BELOW

  • OVERLAP

  • CENTER

  • FIRST_WINDOW


If the window was open but obscured, this call raises the windows. If the window was minimized, the call normalizes it.
If system resources are low (especially on MS Windows), a warning message appears.
VariableDescription
childThe name of the window to be positioned
relThe style of the window‘s position
parentName of the window to relative to which you want to position the child window

See: Non-Modal Windows.

APP_WINDOW.SET_TITLE

VariableDescription
Summary
procedure  APP_WINDOW.SET_TITLE(

	window_name  varchar2, 
	session      varchar2,
	instance1    varchar2 default ‘APP_ARGUMENT_NOT_PASSED‘,
	instance2    varchar2 default ‘APP_ARGUMENT_NOT_PASSED‘,
	instance3    varchar2 default ‘APP_ARGUMENT_NOT_PASSED‘);

DescriptionUse this utility to set the title of a window in the standard format.
VariableDescription
window_nameThe name of the window to set the title for
sessionGeneral session information (for example, Org, Set of Books), no more than 64 characters
instance[1,2,3]Context information from the master record (optional). The combined length should be no more than 250 characters.

APPCORE Routine APIs