.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Rose::DB::Informix 3pm"
.TH Rose::DB::Informix 3pm "2016-10-13" "perl v5.24.1" "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"
Rose::DB::Informix \- Informix driver class for Rose::DB.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Rose::DB;
\&
\&  Rose::DB\->register_db(
\&    domain   => \*(Aqdevelopment\*(Aq,
\&    type     => \*(Aqmain\*(Aq,
\&    driver   => \*(AqInformix\*(Aq,
\&    database => \*(Aqdev_db\*(Aq,
\&    host     => \*(Aqlocalhost\*(Aq,
\&    username => \*(Aqdevuser\*(Aq,
\&    password => \*(Aqmysecret\*(Aq,
\&    server_time_zone => \*(AqUTC\*(Aq,
\&  );
\&
\&
\&  Rose::DB\->default_domain(\*(Aqdevelopment\*(Aq);
\&  Rose::DB\->default_type(\*(Aqmain\*(Aq);
\&  ...
\&
\&  # Set max length of varchar columns used to emulate the array data type
\&  Rose::DB::Informix\->max_array_characters(128);
\&
\&  $db = Rose::DB\->new; # $db is really a Rose::DB::Informix\-derived object
\&
\&  $dt  = $db\->parse_datetime_year_to_minute(...);
\&  $val = $db\->format_datetime_year_to_minute($dt);
\&
\&  $dt  = $db\->parse_datetime_year_to_second(...);
\&  $val = $db\->format_datetime_year_to_second($dt);
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Rose::DB blesses objects into a class derived from Rose::DB::Informix when the driver is \*(L"informix\*(R".  This mapping of driver names to class names is configurable.  See the documentation for Rose::DB's \fInew()\fR and \fIdriver_class()\fR methods for more information.
.PP
This class cannot be used directly.  You must use Rose::DB and let its \fInew()\fR method return an object blessed into the appropriate class for you, according to its \fIdriver_class()\fR mappings.
.PP
Only the methods that are new or have different behaviors than those in Rose::DB are documented here.  See the Rose::DB documentation for the full list of methods.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP "\fBdefault_supports_limit_with_offset [\s-1BOOL\s0]\fR" 4
.IX Item "default_supports_limit_with_offset [BOOL]"
Get or set a boolean value that indicates whether or not all Informix databases that you plan to connect to support the \*(L"\s-1SELECT SKIP N FIRST M ...\*(R"\s0 syntax.  If undefined, this feature will be looked up on a per-connection basis as needed.  The default is undefined.
.IP "\fBmax_array_characters [\s-1INT\s0]\fR" 4
.IX Item "max_array_characters [INT]"
Get or set the maximum length of varchar columns used to emulate the array data type.  The default value is 255.
.Sp
Informix does not have a native \*(L"\s-1ARRAY\*(R"\s0 data type, but it can be emulated using a \*(L"\s-1VARCHAR\*(R"\s0 column and a specially formatted string.  The formatting and parsing of this string is handled by the \f(CW\*(C`format_array()\*(C'\fR and \f(CW\*(C`parse_array()\*(C'\fR object methods.  The maximum length limit is honored by the \f(CW\*(C`format_array()\*(C'\fR object method.
.Sp
Informix does have a native \*(L"\s-1SET\*(R"\s0 data type, serviced by the \f(CW\*(C`parse_set()\*(C'\fR and \f(CW\*(C`format_set()\*(C'\fR object methods.  This is a better choice than the emulated array data type if you don't care about the order of the stored values.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
.SS "Value Parsing and Formatting"
.IX Subsection "Value Parsing and Formatting"
.IP "\fBformat_array \s-1ARRAYREF\s0 | \s-1LIST\s0\fR" 4
.IX Item "format_array ARRAYREF | LIST"
Given a reference to an array or a list of values, return a specially formatted string.  Undef is returned if \s-1ARRAYREF\s0 points to an empty array or if \s-1LIST\s0 is not passed.  The array or list must not contain undefined values.
.Sp
If the resulting string is longer than \f(CW\*(C`max_array_characters()\*(C'\fR, a fatal error will occur.
.IP "\fBformat_date \s-1DATETIME\s0\fR" 4
.IX Item "format_date DATETIME"
Converts the DateTime object \s-1DATETIME\s0 into the appropriate format for the \*(L"\s-1DATE\*(R"\s0 data type.
.IP "\fBformat_datetime \s-1DATETIME\s0\fR" 4
.IX Item "format_datetime DATETIME"
Converts the DateTime object \s-1DATETIME\s0 into the appropriate format for the \*(L"\s-1DATETIME YEAR TO SECOND\*(R"\s0 data type.
.IP "\fBformat_datetime_year_to_fraction \s-1DATETIME\s0\fR" 4
.IX Item "format_datetime_year_to_fraction DATETIME"
Converts the DateTime object \s-1DATETIME\s0 into the appropriate format for the \*(L"\s-1DATETIME YEAR TO FRACTION\*(R"\s0 data type.
.IP "\fBformat_datetime_year_to_fraction_[1\-5] \s-1DATETIME\s0\fR" 4
.IX Item "format_datetime_year_to_fraction_[1-5] DATETIME"
Converts the DateTime object \s-1DATETIME\s0 into the appropriate format for the \*(L"\s-1DATETIME YEAR TO FRACTION\s0(N)\*(R" data type, where N is an integer from 1 to 5.
.IP "\fBformat_datetime_year_to_minute \s-1DATETIME\s0\fR" 4
.IX Item "format_datetime_year_to_minute DATETIME"
Converts the DateTime object \s-1DATETIME\s0 into the appropriate format for the \*(L"\s-1DATETIME YEAR TO MINUTE\*(R"\s0 data type.
.IP "\fBformat_datetime_year_to_month \s-1DATETIME\s0\fR" 4
.IX Item "format_datetime_year_to_month DATETIME"
Converts the DateTime object \s-1DATETIME\s0 into the appropriate format for the \*(L"\s-1DATETIME YEAR TO MONTH\*(R"\s0 data type.
.IP "\fBformat_datetime_year_to_second \s-1DATETIME\s0\fR" 4
.IX Item "format_datetime_year_to_second DATETIME"
Converts the DateTime object \s-1DATETIME\s0 into the appropriate format for the \*(L"\s-1DATETIME YEAR TO SECOND\*(R"\s0 data type.
.IP "\fBformat_set \s-1ARRAYREF\s0 | \s-1LIST\s0\fR" 4
.IX Item "format_set ARRAYREF | LIST"
Given a reference to an array or a list of values, return a string formatted according to the rules of Informix's \*(L"\s-1SET\*(R"\s0 data type.  Undef is returned if \s-1ARRAYREF\s0 points to an empty array or if \s-1LIST\s0 is not passed.  If the array or list contains undefined values, a fatal error will occur.
.IP "\fBformat_timestamp \s-1DATETIME\s0\fR" 4
.IX Item "format_timestamp DATETIME"
Converts the DateTime object \s-1DATETIME\s0 into the appropriate format for the \*(L"\s-1DATETIME YEAR TO \fIFRACTION\s0\fR\|(5)\*(R" data type.
.IP "\fBparse_array \s-1STRING\s0 | \s-1LIST\s0 | \s-1ARRAYREF\s0\fR" 4
.IX Item "parse_array STRING | LIST | ARRAYREF"
Parse \s-1STRING\s0 and return a reference to an array.  \s-1STRING\s0 should be formatted according to the Informix array data type emulation format returned by \f(CW\*(C`format_array()\*(C'\fR.  Undef is returned if \s-1STRING\s0 is undefined.
.Sp
If a \s-1LIST\s0 of more than one item is passed, a reference to an array containing the values in \s-1LIST\s0 is returned.
.Sp
If a an \s-1ARRAYREF\s0 is passed, it is returned as-is.
.IP "\fBparse_boolean \s-1STRING\s0\fR" 4
.IX Item "parse_boolean STRING"
Parse \s-1STRING\s0 and return a boolean value of 1 or 0.  \s-1STRING\s0 should be formatted according to Informix's native \*(L"boolean\*(R" data type.  Acceptable values are 't', 'T', or '1' for true, and 'f', 'F', or '0' for false.
.Sp
If \s-1STRING\s0 is a valid boolean keyword (according to validate_boolean_keyword) or if it looks like a function call (matches /^\ew+\e(.*\e)$/) and keyword_function_calls is true, then it is returned unmodified.  Returns undef if \s-1STRING\s0 could not be parsed as a valid \*(L"boolean\*(R" value.
.IP "\fBparse_date \s-1STRING\s0\fR" 4
.IX Item "parse_date STRING"
Parse \s-1STRING\s0 and return a DateTime object.  \s-1STRING\s0 should be formatted according to the Informix \*(L"\s-1DATE\*(R"\s0 data type.
.Sp
If \s-1STRING\s0 is a valid date keyword (according to validate_date_keyword) it is returned unmodified.  Returns undef if \s-1STRING\s0 could not be parsed as a valid \*(L"\s-1DATE\*(R"\s0 value.
.IP "\fBparse_datetime \s-1STRING\s0\fR" 4
.IX Item "parse_datetime STRING"
Parse \s-1STRING\s0 and return a DateTime object.  \s-1STRING\s0 should be formatted according to the Informix \*(L"\s-1DATETIME YEAR TO SECOND\*(R"\s0 data type.
.Sp
If \s-1STRING\s0 is a valid \*(L"datetime year to second\*(R" keyword (according to validate_datetime_year_to_second_keyword) it is returned unmodified.  Returns undef if \s-1STRING\s0 could not be parsed as a valid \*(L"\s-1DATETIME YEAR TO SECOND\*(R"\s0 value.
.IP "\fBparse_datetime_year_to_fraction \s-1STRING\s0\fR" 4
.IX Item "parse_datetime_year_to_fraction STRING"
Parse \s-1STRING\s0 and return a DateTime object.  \s-1STRING\s0 should be formatted according to the Informix \*(L"\s-1DATETIME YEAR TO FRACTION\*(R"\s0 data type.
.Sp
If \s-1STRING\s0 is a valid \*(L"datetime year to fraction\*(R" keyword (according to validate_datetime_year_to_fraction_keyword) it is returned unmodified.  Returns undef if \s-1STRING\s0 could not be parsed as a valid \*(L"\s-1DATETIME YEAR TO FRACTION\*(R"\s0 value.
.IP "\fBparse_datetime_year_to_fraction_[1\-5] \s-1STRING\s0\fR" 4
.IX Item "parse_datetime_year_to_fraction_[1-5] STRING"
These five methods parse \s-1STRING\s0 and return a DateTime object.  \s-1STRING\s0 should be formatted according to the Informix \*(L"\s-1DATETIME YEAR TO FRACTION\s0(N)\*(R" data type, where N is an integer from 1 to 5.
.Sp
If \s-1STRING\s0 is a valid \*(L"datetime year to fraction\*(R" keyword (according to validate_datetime_year_to_fraction_keyword) it is returned unmodified.  Returns undef if \s-1STRING\s0 could not be parsed as a valid \*(L"\s-1DATETIME YEAR TO FRACTION\s0(N)\*(R" value.
.IP "\fBparse_datetime_year_to_minute \s-1STRING\s0\fR" 4
.IX Item "parse_datetime_year_to_minute STRING"
Parse \s-1STRING\s0 and return a DateTime object.  \s-1STRING\s0 should be formatted according to the Informix \*(L"\s-1DATETIME YEAR TO MINUTE\*(R"\s0 data type.
.Sp
If \s-1STRING\s0 is a valid \*(L"datetime year to minute\*(R" keyword (according to validate_datetime_year_to_minute_keyword) it is returned unmodified.  Returns undef if \s-1STRING\s0 could not be parsed as a valid \*(L"\s-1DATETIME YEAR TO MINUTE\*(R"\s0 value.
.IP "\fBparse_datetime_year_to_month \s-1STRING\s0\fR" 4
.IX Item "parse_datetime_year_to_month STRING"
Parse \s-1STRING\s0 and return a DateTime object.  \s-1STRING\s0 should be formatted according to the Informix \*(L"\s-1DATETIME YEAR TO MINUTE\*(R"\s0 data type.
.Sp
If \s-1STRING\s0 is a valid \*(L"datetime year to month\*(R" keyword (according to validate_datetime_year_to_month_keyword) it is returned unmodified.  Returns undef if \s-1STRING\s0 could not be parsed as a valid \*(L"\s-1DATETIME YEAR TO MONTH\*(R"\s0 value.
.IP "\fBparse_datetime_year_to_second \s-1STRING\s0\fR" 4
.IX Item "parse_datetime_year_to_second STRING"
Parse \s-1STRING\s0 and return a DateTime object.  \s-1STRING\s0 should be formatted according to the Informix \*(L"\s-1DATETIME YEAR TO SECOND\*(R"\s0 data type.
.Sp
If \s-1STRING\s0 is a valid \*(L"datetime year to second\*(R" keyword (according to validate_datetime_year_to_second_keyword) it is returned unmodified.  Returns undef if \s-1STRING\s0 could not be parsed as a valid \*(L"\s-1DATETIME YEAR TO SECOND\*(R"\s0 value.
.IP "\fBparse_set \s-1STRING\s0 | \s-1LIST\s0 | \s-1ARRAYREF\s0\fR" 4
.IX Item "parse_set STRING | LIST | ARRAYREF"
Parse \s-1STRING\s0 and return a reference to an array.  \s-1STRING\s0 should be formatted according to Informix's \*(L"\s-1SET\*(R"\s0 data type.  Undef is returned if \s-1STRING\s0 is undefined.
.Sp
If a \s-1LIST\s0 of more than one item is passed, a reference to an array containing the values in \s-1LIST\s0 is returned.
.Sp
If a an \s-1ARRAYREF\s0 is passed, it is returned as-is.
.IP "\fBparse_timestamp \s-1STRING\s0\fR" 4
.IX Item "parse_timestamp STRING"
Parse \s-1STRING\s0 and return a DateTime object.  \s-1STRING\s0 should be formatted according to the Informix \*(L"\s-1DATETIME YEAR TO \fIFRACTION\s0\fR\|(5)\*(R" data type.
.Sp
If \s-1STRING\s0 is a valid timestamp keyword (according to validate_timestamp_keyword) it is returned unmodified.  Returns undef if \s-1STRING\s0 could not be parsed as a valid \*(L"\s-1DATETIME YEAR TO \fIFRACTION\s0\fR\|(5)\*(R" value.
.IP "\fBvalidate_boolean_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_boolean_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the \*(L"boolean\*(R" data type of the current data source, false otherwise.  Valid (case-insensitive) boolean keywords are:
.Sp
.Vb 2
\&    TRUE
\&    FALSE
.Ve
.IP "\fBvalidate_date_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_date_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the Informix \*(L"date\*(R", false otherwise.   Valid (case-insensitive) date keywords are:
.Sp
.Vb 2
\&    current
\&    today
.Ve
.Sp
The keywords are not case sensitive.  Any string that looks like a function call (matches /^\ew+\e(.*\e)$/) is also considered a valid date keyword if keyword_function_calls is true.
.IP "\fBvalidate_datetime_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_datetime_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the Informix \*(L"datetime year to second\*(R" data type, false otherwise.  Valid (case-insensitive) datetime keywords are:
.Sp
.Vb 7
\&    current
\&    current year to second
\&    current year to minute
\&    current year to hour
\&    current year to day
\&    current year to month
\&    today
.Ve
.Sp
The keywords are not case sensitive.  Any string that looks like a function call (matches /^\ew+\e(.*\e)$/) is also considered a valid datetime keyword if keyword_function_calls is true.
.IP "\fBvalidate_datetime_year_to_fraction_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_datetime_year_to_fraction_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the Informix \*(L"datetime year to fraction(n)\*(R" data type (where n is an integer from 1 to 5), false otherwise.  Valid (case-insensitive) \*(L"datetime year to fraction\*(R" keywords are:
.Sp
.Vb 10
\&    current
\&    current year to fraction
\&    current year to fraction(1)
\&    current year to fraction(2)
\&    current year to fraction(3)
\&    current year to fraction(4)
\&    current year to fraction(5)
\&    current year to second
\&    current year to minute
\&    current year to hour
\&    current year to day
\&    current year to month
\&    today
.Ve
.Sp
The keywords are not case sensitive.  Any string that looks like a function call (matches /^\ew+\e(.*\e)$/) is also considered a valid \*(L"datetime year to fraction\*(R" keyword if keyword_function_calls is true.
.IP "\fBvalidate_datetime_year_to_minute_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_datetime_year_to_minute_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the Informix \*(L"datetime year to minute\*(R" data type, false otherwise.  Valid (case-insensitive) \*(L"datetime year to minute\*(R" keywords are:
.Sp
.Vb 7
\&    current
\&    current year to second
\&    current year to minute
\&    current year to hour
\&    current year to day
\&    current year to month
\&    today
.Ve
.Sp
The keywords are not case sensitive.  Any string that looks like a function call (matches /^\ew+\e(.*\e)$/) is also considered a valid \*(L"datetime year to minute\*(R" keyword if keyword_function_calls is true.
.IP "\fBvalidate_datetime_year_to_month_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_datetime_year_to_month_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the Informix \*(L"datetime year to month\*(R" data type, false otherwise.  Valid (case-insensitive) \*(L"datetime year to month\*(R" keywords are:
.Sp
.Vb 7
\&    current
\&    current year to second
\&    current year to minute
\&    current year to hour
\&    current year to day
\&    current year to month
\&    today
.Ve
.Sp
The keywords are not case sensitive.  Any string that looks like a function call (matches /^\ew+\e(.*\e)$/) is also considered a valid \*(L"datetime year to month\*(R" keyword if keyword_function_calls is true.
.IP "\fBvalidate_datetime_year_to_second_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_datetime_year_to_second_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the Informix \*(L"datetime year to second\*(R" data type, false otherwise.  Valid (case-insensitive) datetime keywords are:
.Sp
.Vb 7
\&    current
\&    current year to second
\&    current year to minute
\&    current year to hour
\&    current year to day
\&    current year to month
\&    today
.Ve
.Sp
The keywords are not case sensitive.  Any string that looks like a function call (matches /^\ew+\e(.*\e)$/) is also considered a valid \*(L"datetime year to second\*(R" keyword if keyword_function_calls is true.
.IP "\fBvalidate_timestamp_keyword \s-1STRING\s0\fR" 4
.IX Item "validate_timestamp_keyword STRING"
Returns true if \s-1STRING\s0 is a valid keyword for the Informix \*(L"timestamp\*(R" data type, false otherwise.  Valid (case-insensitive) timestamp keywords are:
.Sp
.Vb 10
\&    current
\&    current year to fraction
\&    current year to fraction(1)
\&    current year to fraction(2)
\&    current year to fraction(3)
\&    current year to fraction(4)
\&    current year to fraction(5)
\&    current year to second
\&    current year to minute
\&    current year to hour
\&    current year to day
\&    current year to month
\&    today
.Ve
.Sp
The keywords are not case sensitive.  Any string that looks like a function call (matches /^\ew+\e(.*\e)$/) is also considered a valid timestamp keyword if keyword_function_calls is true.
.SH "AUTHOR"
.IX Header "AUTHOR"
John C. Siracusa (siracusa@gmail.com)
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This program is
free software; you can redistribute it and/or modify it under the same terms
as Perl itself.