Ubuntu Manpage: DateTime::Format::Oracle - Parse and format Oracle dates and timestamps

Provided by: libdatetime-format-oracle-perl_0.06-1_all

NAME

       DateTime::Format::Oracle - Parse and format Oracle dates and timestamps

SYNOPSIS

         use DateTime::Format::Oracle;

         $ENV{'NLS_DATE_FORMAT'} = 'YYYY-MM-DD HH24:MI:SS';
         my $dt = DateTime::Format::Oracle->parse_datetime('2003-01-16 23:12:01');
         my $string = DateTime::Format::Oracle->format_datetime($dt);

DESCRIPTION

       This module may be used to convert Oracle date and timestamp values into "DateTime"
       objects.  It also can take a "DateTime" object and produce a date string matching the
       "NLS_DATE_FORMAT".

       Oracle has flexible date formatting via its "NLS_DATE_FORMAT" session variable.  Date
       values will be returned from Oracle according to the current value of that variable.  Date
       values going into Oracle must also match the current setting of "NLS_DATE_FORMAT".

       Timestamp values will match either the "NLS_TIMESTAMP_FORMAT" or "NLS_TIMESTAMP_TZ_FORMAT"
       session variables.

       This module keeps track of these Oracle session variable values by examining environment
       variables of the same name.  Each time one of Oracle's formatting session variables is
       updated, the %ENV hash must also be updated.

METHODS

This class offers the following methods.

• nls_date_format

This method is used to determine the current value of Oracle's "NLS_DATE_FORMAT". It
currently just reads the value from

$ENV{'NLS_DATE_FORMAT'}

or if that is not set, from the package variable $nls_date_format, which has a default
value of "YYYY-MM-DD HH24:MI:SS". This is a good default to have, but is not Oracle's
default. Dates will fail to parse if Oracle's NLS_DATE_FORMAT and the value from this
method are not the same.

If you want to use the default from this module, you can do something like this after
you connect to Oracle:

$dbh->do(
"alter session set nls_date_format = '" .
DateTime::Format::Oracle->nls_date_format .
"'"
);

• nls_timestamp_format

This method is used to determine the current value of Oracle's "NLS_TIMESTAMP_FORMAT".
It currently just reads the value from

$ENV{'NLS_TIMESTAMP_FORMAT'}

or if that is not set, from the package variable $nls_timestamp_format, which has a
default value of "YYYY-MM-DD HH24:MI:SS". This is a good default to have, but is not
Oracle's default. Dates will fail to parse if Oracle's NLS_TIMESTAMP_FORMAT and the
value from this method are not the same.

If you want to use the default from this module, you can do something like this after
you connect to Oracle:

$dbh->do(
"alter session set nls_timestamp_format = '" .
DateTime::Format::Oracle->nls_timestamp_format .
"'"
);

• nls_timestamp_tz_format

This method is used to determine the current value of Oracle's
"NLS_TIMESTAMP_TZ_FORMAT". It currently just reads the value from

$ENV{'NLS_TIMESTAMP_TZ_FORMAT'}

or if that is not set, from the package variable $nls_timestamp_tz_format, which has a
default value of "YYYY-MM-DD HH24:MI:SS TZHTZM". This is a good default to have, but
is not Oracle's default. Dates will fail to parse if Oracle's NLS_TIMESTAMP_TZ_FORMAT
and the value from this method are not the same.

If you want to use the default from this module, you can do something like this after
you connect to Oracle:

$dbh->do(
"alter session set nls_timestamp_tz_format = '" .
DateTime::Format::Oracle->nls_timestamp_tz_format .
"'"
);

• parse_datetime

Given a string containing a date and/or time representation matching
"NLS_DATE_FORMAT", this method will return a new "DateTime" object.

If given an improperly formatted string, this method may die.

• parse_date

Alias to "parse_datetime". Oracle's date datatype also holds time information.

• parse_timestamp

Given a string containing a date and/or time representation matching
"NLS_TIMESTAMP_FORMAT", this method will return a new "DateTime" object.

If given an improperly formatted string, this method may die.

• parse_timestamptz =item * parse_timestamp_with_time_zone

Given a string containing a date and/or time representation matching
"NLS_TIMESTAMP_TZ_FORMAT", this method will return a new "DateTime" object.

If given an improperly formatted string, this method may die.

• current_date_parser

The current "DateTime::Format::Builder" generated parsing method used by
"parse_datetime" and "parse_date".

• current_timestamp_parser

The current "DateTime::Format::Builder" generated parsing method used by
"parse_timestamp".

• current_timestamptz_parser

The current "DateTime::Format::Builder" generated parsing method used by
"parse_timestamptz".

• format_datetime

Given a "DateTime" object, this method returns a string matching the current value of
"NLS_DATE_FORMAT".

It is important to keep the value of $ENV{'NLS_DATE_FORMAT'} the same as the value of
the Oracle session variable "NLS_DATE_FORMAT".

To determine the current value of Oracle's "NLS_DATE_FORMAT":

select NLS_DATE_FORMAT from NLS_SESSION_PARAMETERS

To reset Oracle's "NLS_DATE_FORMAT":

alter session set NLS_DATE_FORMAT='YYYY-MM-DD HH24:MI:SS'

It is generally a good idea to set "NLS_DATE_FORMAT" to an unambiguos value, with
four-digit year, and hour, minute, and second.

• format_date

Alias to "format_datetime".

• format_timestamp

Given a "DateTime" object, this method returns a string matching the current value of
"NLS_TIMESTAMP_FORMAT".

It is important to keep the value of $ENV{'NLS_TIMESTAMP_FORMAT'} the same as the
value of the Oracle session variable "NLS_TIMESTAMP_FORMAT".

To determine the current value of Oracle's "NLS_TIMESTAMP_FORMAT":

select NLS_TIMESTAMP_FORMAT from NLS_SESSION_PARAMETERS

To reset Oracle's "NLS_TIMESTAMP_FORMAT":

alter session set NLS_TIMESTAMP_FORMAT='YYYY-MM-DD HH24:MI:SS'

It is generally a good idea to set "NLS_TIMESTAMP_FORMAT" to an unambiguos value, with
four-digit year, and hour, minute, and second.

• format_timestamptz =item * format_timestamp_with_time_zone

Given a "DateTime" object, this method returns a string matching the current value of
"NLS_TIMESTAMP_TZ_FORMAT".

It is important to keep the value of $ENV{'NLS_TIMESTAMP_TZ_FORMAT'} the same as the
value of the Oracle session variable "NLS_TIMESTAMP_TZ_FORMAT".

To determine the current value of Oracle's "NLS_TIMESTAMP_TZ_FORMAT":

select NLS_TIMESTAMP_TZ_FORMAT from NLS_SESSION_PARAMETERS

To reset Oracle's "NLS_TIMESTAMP_TZ_FORMAT":

alter session set NLS_TIMESTAMP_TZ_FORMAT='YYYY-MM-DD HH24:MI:SS TZHTZM'

It is generally a good idea to set "NLS_TIMESTAMP_TZ_FORMAT" to an unambiguos value,
with four-digit year, and hour, minute, and second.

• current_date_format

The current generated method used by "format_datetime", "format_date", and
"current_date_parser" to keep track of the "strptime" translation of
"NLS_DATE_FORMAT".

• current_timestamp_format

The current generated method used by "format_timestamp",
"format_timestamp_with_time_zone", and "current_timestamp_parser" to keep track of the
"strptime" translation of "NLS_TIMESTAMP_FORMAT".

• current_timestamptz_format

The current generated method used by "format_timestamptz",
"format_timestamp_with_time_zone", and "current_timestamp_parser" to keep track of the
"strptime" translation of "NLS_TIMESTAMP_FORMAT".

• oracle_to_posix

Given an "NLS_DATE_FORMAT", "NLS_TIMESTAMP_FORMAT", or "NLS_TIMESTAMP_TZ_FORMAT"
value, this method returns a "DateTime"-compatible "strptime" format value.

Translation is currently handled by "Convert::NLS_DATE_FORMAT".

LIMITATIONS

       Oracle is more flexible with the case of names, such as the month, whereas "DateTime"
       generally returns names in "ucfirst" format.

         MONTH -> FEBRUARY
         Month -> February
         month -> february

       All translate to:

         %B    -> February

   TIME ZONES
       Oracle returns all dates and timestamps in a time zone similar to the "DateTime" floating
       time zone, except for 'timestamp with time zone' columns.

   INTERVAL ELEMENTS
       I have not implemented "parse_duration", "format_duration", "parse_interval", nor
       "format_interval", and have no plans to do so.

       If you need these features, unit tests, method implementations, and pointers to
       documentation are all welcome.

SUPPORT

       Support for this module is provided via the datetime@perl.org email list.  See
       http://lists.perl.org/ for more details.

TODO

       Possibly read an environment variable to determine a time zone to use instead of
       'floating'.

       Test and document creating an instance via "new".

AUTHOR

       Nathan Gray, <kolibrie@cpan.org>

ACKNOWLEDGEMENTS

       I might have put this module off for another couple years without the lure of Jifty,
       Catalyst, and DBIx::Class pulling at me.

       Thanks to Dan Horne for his RFC draft of this module.

COPYRIGHT & LICENSE

       Copyright (C) 2006, 2008, 2011 Nathan Gray.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of
       Perl 5 you may have available.

NAME

SYNOPSIS

DESCRIPTION

METHODS

LIMITATIONS

SUPPORT

TODO

AUTHOR

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

SEE ALSO