.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DateTime::Format::Oracle 3pm"
.TH DateTime::Format::Oracle 3pm "2021-01-04" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DateTime::Format::Oracle \- Parse and format Oracle dates and timestamps
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use DateTime::Format::Oracle;
\&
\&  $ENV{\*(AqNLS_DATE_FORMAT\*(Aq} = \*(AqYYYY\-MM\-DD HH24:MI:SS\*(Aq;
\&  my $dt = DateTime::Format::Oracle\->parse_datetime(\*(Aq2003\-01\-16 23:12:01\*(Aq);
\&  my $string = DateTime::Format::Oracle\->format_datetime($dt);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module may be used to convert Oracle date and timestamp values
into \f(CW\*(C`DateTime\*(C'\fR objects.  It also can take a \f(CW\*(C`DateTime\*(C'\fR object and
produce a date string matching the \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR.
.PP
Oracle has flexible date formatting via its \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR 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 \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR.
.PP
Timestamp values will match either the \f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR or
\&\f(CW\*(C`NLS_TIMESTAMP_TZ_FORMAT\*(C'\fR session variables.
.PP
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 \f(CW%ENV\fR hash
must also be updated.
.SH "METHODS"
.IX Header "METHODS"
This class offers the following methods.
.IP "\(bu" 4
nls_date_format
.Sp
This method is used to determine the current value of Oracle's
\&\f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR.  It currently just reads the value from
.Sp
.Vb 1
\&  $ENV{\*(AqNLS_DATE_FORMAT\*(Aq}
.Ve
.Sp
or if that is not set, from the package variable \f(CW$nls_date_format\fR,
which has a default value of \f(CW\*(C`YYYY\-MM\-DD HH24:MI:SS\*(C'\fR.  This is
a good default to have, but is not Oracle's default.  Dates will fail
to parse if Oracle's \s-1NLS_DATE_FORMAT\s0 and the value from this method
are not the same.
.Sp
If you want to use the default from this module, you can do something
like this after you connect to Oracle:
.Sp
.Vb 5
\&  $dbh\->do(
\&      "alter session set nls_date_format = \*(Aq" .
\&      DateTime::Format::Oracle\->nls_date_format .
\&      "\*(Aq"
\&  );
.Ve
.IP "\(bu" 4
nls_timestamp_format
.Sp
This method is used to determine the current value of Oracle's
\&\f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR.  It currently just reads the value from
.Sp
.Vb 1
\&  $ENV{\*(AqNLS_TIMESTAMP_FORMAT\*(Aq}
.Ve
.Sp
or if that is not set, from the package variable \f(CW$nls_timestamp_format\fR,
which has a default value of \f(CW\*(C`YYYY\-MM\-DD HH24:MI:SS\*(C'\fR.  This is
a good default to have, but is not Oracle's default.  Dates will fail
to parse if Oracle's \s-1NLS_TIMESTAMP_FORMAT\s0 and the value from this method
are not the same.
.Sp
If you want to use the default from this module, you can do something
like this after you connect to Oracle:
.Sp
.Vb 5
\&  $dbh\->do(
\&      "alter session set nls_timestamp_format = \*(Aq" .
\&      DateTime::Format::Oracle\->nls_timestamp_format .
\&      "\*(Aq"
\&  );
.Ve
.IP "\(bu" 4
nls_timestamp_tz_format
.Sp
This method is used to determine the current value of Oracle's
\&\f(CW\*(C`NLS_TIMESTAMP_TZ_FORMAT\*(C'\fR.  It currently just reads the value from
.Sp
.Vb 1
\&  $ENV{\*(AqNLS_TIMESTAMP_TZ_FORMAT\*(Aq}
.Ve
.Sp
or if that is not set, from the package variable \f(CW$nls_timestamp_tz_format\fR,
which has a default value of \f(CW\*(C`YYYY\-MM\-DD HH24:MI:SS TZHTZM\*(C'\fR.  This is
a good default to have, but is not Oracle's default.  Dates will fail
to parse if Oracle's \s-1NLS_TIMESTAMP_TZ_FORMAT\s0 and the value from this method
are not the same.
.Sp
If you want to use the default from this module, you can do something
like this after you connect to Oracle:
.Sp
.Vb 5
\&  $dbh\->do(
\&      "alter session set nls_timestamp_tz_format = \*(Aq" .
\&      DateTime::Format::Oracle\->nls_timestamp_tz_format .
\&      "\*(Aq"
\&  );
.Ve
.IP "\(bu" 4
parse_datetime
.Sp
Given a string containing a date and/or time representation
matching \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR, this method will return a new
\&\f(CW\*(C`DateTime\*(C'\fR object.
.Sp
If given an improperly formatted string, this method may die.
.IP "\(bu" 4
parse_date
.Sp
Alias to \f(CW\*(C`parse_datetime\*(C'\fR.  Oracle's date datatype also holds
time information.
.IP "\(bu" 4
parse_timestamp
.Sp
Given a string containing a date and/or time representation
matching \f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR, this method will return a new
\&\f(CW\*(C`DateTime\*(C'\fR object.
.Sp
If given an improperly formatted string, this method may die.
.IP "\(bu" 4
parse_timestamptz
=item * parse_timestamp_with_time_zone
.Sp
Given a string containing a date and/or time representation
matching \f(CW\*(C`NLS_TIMESTAMP_TZ_FORMAT\*(C'\fR, this method will return a new
\&\f(CW\*(C`DateTime\*(C'\fR object.
.Sp
If given an improperly formatted string, this method may die.
.IP "\(bu" 4
current_date_parser
.Sp
The current \f(CW\*(C`DateTime::Format::Builder\*(C'\fR generated parsing method
used by \f(CW\*(C`parse_datetime\*(C'\fR and \f(CW\*(C`parse_date\*(C'\fR.
.IP "\(bu" 4
current_timestamp_parser
.Sp
The current \f(CW\*(C`DateTime::Format::Builder\*(C'\fR generated parsing method
used by \f(CW\*(C`parse_timestamp\*(C'\fR.
.IP "\(bu" 4
current_timestamptz_parser
.Sp
The current \f(CW\*(C`DateTime::Format::Builder\*(C'\fR generated parsing method
used by \f(CW\*(C`parse_timestamptz\*(C'\fR.
.IP "\(bu" 4
format_datetime
.Sp
Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns a string matching
the current value of \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR.
.Sp
It is important to keep the value of \f(CW$ENV{\*(AqNLS_DATE_FORMAT\*(Aq}\fR the
same as the value of the Oracle session variable \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR.
.Sp
To determine the current value of Oracle's \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR:
.Sp
.Vb 1
\&  select NLS_DATE_FORMAT from NLS_SESSION_PARAMETERS
.Ve
.Sp
To reset Oracle's \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR:
.Sp
.Vb 1
\&  alter session set NLS_DATE_FORMAT=\*(AqYYYY\-MM\-DD HH24:MI:SS\*(Aq
.Ve
.Sp
It is generally a good idea to set \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR to an
unambiguos value, with four-digit year, and hour, minute, and second.
.IP "\(bu" 4
format_date
.Sp
Alias to \f(CW\*(C`format_datetime\*(C'\fR.
.IP "\(bu" 4
format_timestamp
.Sp
Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns a string matching
the current value of \f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR.
.Sp
It is important to keep the value of \f(CW$ENV{\*(AqNLS_TIMESTAMP_FORMAT\*(Aq}\fR the
same as the value of the Oracle session variable \f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR.
.Sp
To determine the current value of Oracle's \f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR:
.Sp
.Vb 1
\&  select NLS_TIMESTAMP_FORMAT from NLS_SESSION_PARAMETERS
.Ve
.Sp
To reset Oracle's \f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR:
.Sp
.Vb 1
\&  alter session set NLS_TIMESTAMP_FORMAT=\*(AqYYYY\-MM\-DD HH24:MI:SS\*(Aq
.Ve
.Sp
It is generally a good idea to set \f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR to an
unambiguos value, with four-digit year, and hour, minute, and second.
.IP "\(bu" 4
format_timestamptz
=item * format_timestamp_with_time_zone
.Sp
Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns a string matching
the current value of \f(CW\*(C`NLS_TIMESTAMP_TZ_FORMAT\*(C'\fR.
.Sp
It is important to keep the value of \f(CW$ENV{\*(AqNLS_TIMESTAMP_TZ_FORMAT\*(Aq}\fR the
same as the value of the Oracle session variable \f(CW\*(C`NLS_TIMESTAMP_TZ_FORMAT\*(C'\fR.
.Sp
To determine the current value of Oracle's \f(CW\*(C`NLS_TIMESTAMP_TZ_FORMAT\*(C'\fR:
.Sp
.Vb 1
\&  select NLS_TIMESTAMP_TZ_FORMAT from NLS_SESSION_PARAMETERS
.Ve
.Sp
To reset Oracle's \f(CW\*(C`NLS_TIMESTAMP_TZ_FORMAT\*(C'\fR:
.Sp
.Vb 1
\&  alter session set NLS_TIMESTAMP_TZ_FORMAT=\*(AqYYYY\-MM\-DD HH24:MI:SS TZHTZM\*(Aq
.Ve
.Sp
It is generally a good idea to set \f(CW\*(C`NLS_TIMESTAMP_TZ_FORMAT\*(C'\fR to an
unambiguos value, with four-digit year, and hour, minute, and second.
.IP "\(bu" 4
current_date_format
.Sp
The current generated method used by \f(CW\*(C`format_datetime\*(C'\fR,
\&\f(CW\*(C`format_date\*(C'\fR, and \f(CW\*(C`current_date_parser\*(C'\fR to keep track of
the \f(CW\*(C`strptime\*(C'\fR translation of \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR.
.IP "\(bu" 4
current_timestamp_format
.Sp
The current generated method used by \f(CW\*(C`format_timestamp\*(C'\fR,
\&\f(CW\*(C`format_timestamp_with_time_zone\*(C'\fR, and \f(CW\*(C`current_timestamp_parser\*(C'\fR to keep track of
the \f(CW\*(C`strptime\*(C'\fR translation of \f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR.
.IP "\(bu" 4
current_timestamptz_format
.Sp
The current generated method used by \f(CW\*(C`format_timestamptz\*(C'\fR,
\&\f(CW\*(C`format_timestamp_with_time_zone\*(C'\fR, and \f(CW\*(C`current_timestamp_parser\*(C'\fR to keep track of
the \f(CW\*(C`strptime\*(C'\fR translation of \f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR.
.IP "\(bu" 4
oracle_to_posix
.Sp
Given an \f(CW\*(C`NLS_DATE_FORMAT\*(C'\fR, \f(CW\*(C`NLS_TIMESTAMP_FORMAT\*(C'\fR, or
\&\f(CW\*(C`NLS_TIMESTAMP_TZ_FORMAT\*(C'\fR value, this method returns a
\&\f(CW\*(C`DateTime\*(C'\fR\-compatible \f(CW\*(C`strptime\*(C'\fR format value.
.Sp
Translation is currently handled by \f(CW\*(C`Convert::NLS_DATE_FORMAT\*(C'\fR.
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
Oracle is more flexible with the case of names, such as the month,
whereas \f(CW\*(C`DateTime\*(C'\fR generally returns names in \f(CW\*(C`ucfirst\*(C'\fR format.
.PP
.Vb 3
\&  MONTH \-> FEBRUARY
\&  Month \-> February
\&  month \-> february
.Ve
.PP
All translate to:
.PP
.Vb 1
\&  %B    \-> February
.Ve
.SS "\s-1TIME ZONES\s0"
.IX Subsection "TIME ZONES"
Oracle returns all dates and timestamps in a time zone similar to
the \f(CW\*(C`DateTime\*(C'\fR floating time zone, except for 'timestamp with time zone'
columns.
.SS "\s-1INTERVAL ELEMENTS\s0"
.IX Subsection "INTERVAL ELEMENTS"
I have not implemented \f(CW\*(C`parse_duration\*(C'\fR, \f(CW\*(C`format_duration\*(C'\fR,
\&\f(CW\*(C`parse_interval\*(C'\fR, nor \f(CW\*(C`format_interval\*(C'\fR, and have no plans to do so.
.PP
If you need these features, unit tests, method implementations, and
pointers to documentation are all welcome.
.SH "SUPPORT"
.IX Header "SUPPORT"
Support for this module is provided via the datetime@perl.org email
list.  See http://lists.perl.org/ for more details.
.SH "TODO"
.IX Header "TODO"
Possibly read an environment variable to determine a time zone to
use instead of 'floating'.
.PP
Test and document creating an instance via \f(CW\*(C`new\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Nathan Gray, <kolibrie@cpan.org>
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
I might have put this module off for another couple years
without the lure of Jifty, Catalyst, and DBIx::Class pulling
at me.
.PP
Thanks to Dan Horne for his \s-1RFC\s0 draft of this module.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (C) 2006, 2008, 2011 Nathan Gray.
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Convert::NLS_DATE_FORMAT
.PP
datetime@perl.org mailing list
.PP
http://datetime.perl.org/