APPCORE Routine APIs

procedure  APP_COMBO.KEY_PREV_ITEM;

See: Combination Blocks

function APP_DATE.CANONICAL_TO_DATE(
     canonical varchar2)
return 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.

function APP_DATE.DISPLAYDATE_TO_DATE(chardate varchar2)
return 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).

function APP_DATE.DISPLAYDT_TO_DATE(charDT varchar2)
                  return 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).

function APP_DATE.DATE_TO_CANONICAL(                  dateval date)                  return varchar2;

function APP_DATE.DATE_TO_DISPLAYDATE(dateval date)
return varchar2;

In previous releases this function was named APP_DATE.DATE_TO_CHARDATE (that name has been retained for backwards compatibility).

function APP_DATE.DATE_TO_DISPLAYDT(dateval date)
return varchar2;

In previous releases this function was named APP_DATE.DATE_TO_CHARDT (that name has been retained for backwards compatibility).

procedure APP_DATE.DATE_TO_FIELD( dateval date,
          field varchar2,
          datetime varchar2 default ‘DEFAULT‘,
          date_parameter boolean default FALSE);

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.

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.

function APP_DATE.FIELD_TO_DATE(
	field varchar2 default NULL,
	date_parameter boolean default FALSE)
 return date;

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.

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.

procedure APP_DATE.VALIDATE_CHARDATE(
field varchar2 default NULL)

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.

procedure APP_DATE.VALIDATE_CHARDT(
 field varchar2 default NULL)

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.

function FND_DATE.STRING_TO_DATE(
	p_string IN VARCHAR2,
	p_mask   IN VARCHAR2)
RETURN 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").

p_mask - The format mask to use for the conversion, such as DD-MON-RRRR.

function FND_DATE.STRING_TO_CANONICAL(
     p_string IN VARCHAR2,
     p_mask   IN VARCHAR2)
RETURN VARCHAR2; 

p_mask - The format mask to use for the conversion, such as DD-MON-RRRR.

procedure  APP_EXCEPTION.RAISE_EXCEPTION(

 exception_type varchar2 default null,
			  exception_code number   default null,
			  exception_text varchar2 default null);

procedure  APP_EXCEPTION.RETRIEVE;

function  APP_EXCEPTION.GET_TYPE return varchar2;

function  APP_EXCEPTION.GET_CODE return number;

function  APP_EXCEPTION.GET_TEXT return varchar2;

procedure  APP_EXCEPTION.RECORD_LOCK_ERROR (
counter  IN   OUT   number);

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.

procedure  APP_EXCEPTION.DISABLED;

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

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

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

You typically call this procedure in the following triggers:

For examples on using this procedure, see:Item Relations, ,
Mutually Inclusive Items with Dependent Items and Defaults.

procedure  APP_FIELD.SET_EXCLUSIVE_FIELD(

event           varchar2,
			field1           varchar2,
			field2           varchar2,
			field3           varchar2  default NULL);

procedure  APP_FIELD.SET_INCLUSIVE_FIELD(

event           varchar2,
			field1           varchar2,
			field2           varchar2,
			field3           varchar2  default NULL,
			field4           varchar2  default NULL,
			field5           varchar2  default NULL);

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

procedure  APP_FIND.NEW(
block_name varchar2);

procedure  APP_FIND.CLEAR;

procedure  APP_FIND.CLEAR_DETAIL(

detail_block    varchar2);

procedure  APP_FIND.FIND(

block_name    varchar2);

procedure  APP_FIND.QUERY_RANGE(

low_value    varchar2/date/number,
			high_value   varchar2/date/number,
			db_item_name varchar2);

procedure  APP_FIND.QUERY_FIND(

lov_name varchar2);

procedure APP_FIND.QUERY_FIND(
			block_window    varchar2,
			find_window     varchar2,
			find_block      varchar2);

procedure  APP_ITEM.COPY_DATE(

date_val  varchar2
			item_name varchar2);

copy(to_char(to_date(‘01-01-1900‘, ‘DD-MM-YYYY‘),
               ‘DD-MON-YYYY‘), ‘bar.lamb‘);

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

function APP_ITEM.IS_VALID(
			val         varchar2
			dtype       varchar2  default ‘DATE‘)
return BOOLEAN;

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

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;

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

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.

procedure  APP_ITEM_PROPERTY.SET_VISUAL_ATTRIBUTE(

item_name varchar2,
			property number
			value number);

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

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.

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.

procedure  TOUCH_RECORD(
		block_name		varchar2	default NULL,
	 	record_number		NUMBER		default NULL);

procedure  APP_RECORD.HIGHLIGHT(
		value		varchar2/number); 

For more information, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.

procedure  APP_RECORD.FOR_ALL_RECORDS(
		block_name      varchar2,
		trigger_name     varchar2);

procedure APP_RECORD.FOR_ALL_RECORDS(
			trigger_name     varchar2);

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.

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;

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.

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

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.

function  APP_REGION.ALT_REGIONS(
		poplist_name varchar2)
				return BOOLEAN;

procedure  APP_STANDARD.APP_VALIDATE (scope NUMBER);

procedure  APP_STANDARD.EVENT (
		event_name        varchar2);

procedure  APP_STANDARD.SYNCHRONIZE;

See: Pulldown Menus and the Toolbar.

APP_STANDARD.PLATFORM varchar2(30);

procedure  APP_WINDOW.CLOSE_FIRST_WINDOW;  

procedure  APP_WINDOW.PROGRESS( percent    number);  

procedure  APP_WINDOW.SET_COORDINATION(
		event           varchar2,
		coordination    varchar2,
		relation_name   varchar2);

For a closed window, the relation is always "DEFERRED."

When coordination is set to "DEFERRED," AutoQuery is turned on.

procedure  APP_WINDOW.SET_WINDOW_POSITION(
		child          varchar2,
		rel            varchar2,
		parent         varchar2     default  NULL);

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

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‘);