/ 
DateTime-Format-Oracle-0.02
River stage two • 2 direct dependents • 29 total dependents
/ DateTime::Format::Oracle

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'}

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

  • current_date_parser

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

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

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

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

I have not yet implemented parse_timestamp, format_timestamp, parse_timestamp_with_timezone, nor format_timestamp_with_timezone.

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

SEE ALSO

Convert::NLS_DATE_FORMAT

datetime@perl.org mailing list

http://datetime.perl.org/