10.2.3.2 Converting time zones to character strings

Time zones add complexity to the problem of converting datetime values to character strings. Time zone information consists of the following elements:

• A displacement from UTC in terms of hours and minutes

• A time zone region name

• A time zone abbreviation

All these elements are stored separately in a TIMESTAMP WITH TIME ZONE variable. The displacement from UTC is always present, but whether you can display the region name or abbreviation depends on whether you've specified that information to begin with. Look closely at this example:

DECLARE

A TIMESTAMP WITH TIME ZONE;

B TIMESTAMP WITH TIME ZONE;

C TIMESTAMP WITH TIME ZONE;

BEGIN

A := TO_TIMESTAMP_TZ('2002-06-18 13:52:00.123456789 -5:00',

'YYYY-MM-DD HH24:MI:SS.FF TZH:TZM');

B := TO_TIMESTAMP_TZ('2002-06-18 13:52:00.123456789 US/Eastern',

'YYYY-MM-DD HH24:MI:SS.FF TZR');

C := TO_TIMESTAMP_TZ('2002-06-18 13:52:00.123456789 US/Eastern EDT',

'YYYY-MM-DD HH24:MI:SS.FF TZR TZD');

DBMS_OUTPUT.PUT_LINE(TO_CHAR(A,

'YYYY-MM-DD HH:MI:SS.FF AM TZH:TZM TZR TZD'));

DBMS_OUTPUT.PUT_LINE(TO_CHAR(B,

'YYYY-MM-DD HH:MI:SS.FF AM TZH:TZM TZR TZD'));

DBMS_OUTPUT.PUT_LINE(TO_CHAR(C,

'YYYY-MM-DD HH:MI:SS.FF AM TZH:TZM TZR TZD'));

END;

The output is:

2002-06-18 01:52:00.123457000 PM -05:00 -05:00

2002-06-18 01:52:00.123457000 PM -04:00 US/EASTERN EDT

2002-06-18 01:52:00.123457000 PM -04:00 US/EASTERN EDT

Note the following with respect to the display of time zone information:

• For A, we specified time zone in terms of a displacement from UTC. Thus, when A was displayed, only the displacement could be displayed.

• In the absence of a region name for A, Oracle provided the time zone displacement. This is preferable to providing no information at all.

• For B, we specified a time zone region. That region was translated internally into an offset from UTC, but the region name was preserved. Thus, both the UTC offset and the region name could be displayed.

• For B, Oracle correctly recognized that daylight savings time is in effect during the month of June. As a result, the value of B was implicitly associated with the EDT abbreviation.

• For C, we specified a time zone region and an abbreviation, and both those values could be displayed. No surprises here.

There's a one-to-many relationship between UTC offsets and time zone regions; the offset alone is not enough to get you to a region name. That's why you can't display a region name unless you specify one to begin with.

10.2.3.3 The fm element

PL/SQL offers the FM element as a modifier to a format mask. FM (fill mode) controls the suppression of padded blanks and leading zeros in values returned by the TO_CHAR function.

By default, the following format mask results in both padded blanks and leading zeros (there are five spaces between the month name and the day number):

TO_CHAR (SYSDATE, 'Month DD, YYYY') --> 'April 05, 1994'

With the FM modifier at the beginning of the format mask, however, both the extra blank and the leading zeros disappear:

TO_CHAR (SYSDATE, 'FMMonth DD, YYYY') --> April 5, 1994'

The modifier can be specified in upper-, lower-, or mixed-case; the effect is the same.

The FM modifier is a toggle, and can appear more than once in a format model. Each time it appears in the format, it changes the effect of the modifier. By default (that is, if FM is not specified anywhere in a format mask), blanks are not suppressed and leading zeros are included in the result value. So the first time FM appears in the format, it indicates that blanks and leading zeros are suppressed for any following elements. The second time it appears, it indicates that blanks and leading zeros are not suppressed for any following elements, and so on.

The following example suppresses the padded blank at the end of the month name, but preserves the leading zero on the day number with a second specification of FM:

TO_CHAR (SYSDATE, 'fmMonth FMDD, YYYY') --> April 05, 1994'

If you do not use FM in your mask, a converted date value is always right-padded with blanks to a fixed length (that length is dependent on the different format elements you use). If you do use FM, the length of your return value may vary depending on the actual values returned by the different format elements.

The FM modifier can also be used in the format model of a call to the TO_DATE function to fill a string with blanks or zeros to match the format model. This variation of FM was explored earlier in the discussion of the FX modifier.