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.

Form date A text item (in a form) that has a data type of "Date".
field
Form datetime A text item (in a form) that has a data type of "Datetime".
field
Form A text item (in a form) that has a data type of "Char".
character field
PL/SQL date A PL/SQL variable declared as type "Date". Such a variable includes
both date and time components.
User date The format in which the user currently sees dates in forms.
format
User datetime The format in which the user currently sees dates with a time
format component in forms.
Canonical A standard format used to express a date as a string, independent
date format 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
Summary function APP_DATE.CANONICAL_TO_DATE(
canonical varchar2)
return date;
Location APPCORE library and database (stored function)
Description This 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.
Arguments canonical - The VARCHAR2 string (in canonical format) to be
(input) 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
Summary function APP_DATE.DISPLAYDATE_TO_DATE(chardate varchar2)
return date;
Location APPCORE library and database (stored function)
Description This 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 chardate - The VARCHAR2 string (in the user date format) to be
(input) converted to a PL/SQL date.
 APP_DATE.DISPLAYDT_TO_DATE and
FND_DATE.DISPLAYDT_TO_DATE
Summary function APP_DATE.DISPLAYDT_TO_DATE(charDT varchar2)
return date;
Location APPCORE library and database (stored function)
Description This 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 charDT - The VARCHAR2 string (in the user datetime format) to be
(input) converted to a PL/SQL date.

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

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

APP_DATE.DATE_TO_DISPLAYDATE and
FND_DATE.DATE_TO_DISPLAYDATE
Summary function APP_DATE.DATE_TO_DISPLAYDATE(dateval date)
return varchar2;
Location APPCORE library and database (stored function)
Description This 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 dateval - The PL/SQL date to be converted.
(input)

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
Summary function APP_DATE.DATE_TO_DISPLAYDT(dateval date)
return varchar2;
Location APPCORE library and database (stored function)
Description This 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 dateval - The PL/SQL date to be converted.
(input)

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
Summary procedure APP_DATE.DATE_TO_FIELD( dateval date,
field varchar2,
datetime varchar2 default 'DEFAULT',
date_parameter boolean default FALSE);
Location APPCORE library
Description This 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 dateval - The date to be copied.
(input) 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
Summary function APP_DATE.FIELD_TO_DATE(
field varchar2 default NULL,
date_parameter boolean default FALSE)
return date;
Location APPCORE library
Description This 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 field - The name of the field from which the date should be copied,
(input) 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
Summary procedure APP_DATE.VALIDATE_CHARDATE(
field varchar2 default NULL)
Location APPCORE library
Description This 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 field - The name of the character field to be validated, including the
(input) block name. If no field name is passed in, the procedure uses
SYSTEM.CURSOR_ITEM.

APP_DATE.VALIDATE_CHARDT
Summary procedure APP_DATE.VALIDATE_CHARDT(
field varchar2 default NULL)
Location APPCORE library
Description This 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 field - The name of the character field to be validated, including the
(input) block name. If no field name is passed in, the procedure uses
SYSTEM.CURSOR_ITEM.

FND_DATE.STRING_TO_DATE
Summary function FND_DATE.STRING_TO_DATE(
p_string IN VARCHAR2,
p_mask IN VARCHAR2)
RETURN DATE;
Location Database (stored function)
Description This 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 p_string - The character string to be converted.
(input) p_mask - The format mask to use for the conversion, such as DD-
MON-RRRR.

FND_DATE.STRING_TO_CANONICAL
Summary function FND_DATE.STRING_TO_CANONICAL(
p_string IN VARCHAR2,
p_mask IN VARCHAR2)
RETURN VARCHAR2;
Location Database (stored function)
Description This 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 p_string - The character string to be converted.
(input) p_mask - The format mask to use for the conversion, such as DD-
MON-RRRR.