Provided by: librose-db-perl_0.778-1_all bug

NAME

       Rose::DB::Informix - Informix driver class for Rose::DB.

SYNOPSIS

         use Rose::DB;

         Rose::DB->register_db(
           domain   => 'development',
           type     => 'main',
           driver   => 'Informix',
           database => 'dev_db',
           host     => 'localhost',
           username => 'devuser',
           password => 'mysecret',
           server_time_zone => 'UTC',
         );

         Rose::DB->default_domain('development');
         Rose::DB->default_type('main');
         ...

         # 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);
         ...

DESCRIPTION

       Rose::DB blesses objects into a class derived from Rose::DB::Informix when the driver is
       "informix".  This mapping of driver names to class names is configurable.  See the
       documentation for Rose::DB's new() and driver_class() methods for more information.

       This class cannot be used directly.  You must use Rose::DB and let its new() method return
       an object blessed into the appropriate class for you, according to its driver_class()
       mappings.

       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.

CLASS METHODS

       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 "SELECT SKIP N FIRST M ..." syntax.  If undefined,
           this feature will be looked up on a per-connection basis as needed.  The default is
           undefined.

       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.

           Informix does not have a native "ARRAY" data type, but it can be emulated using a
           "VARCHAR" column and a specially formatted string.  The formatting and parsing of this
           string is handled by the "format_array()" and "parse_array()" object methods.  The
           maximum length limit is honored by the "format_array()" object method.

           Informix does have a native "SET" data type, serviced by the "parse_set()" and
           "format_set()" 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.

OBJECT METHODS

   Value Parsing and Formatting
       format_array ARRAYREF | LIST
           Given a reference to an array or a list of values, return a specially formatted
           string.  Undef is returned if ARRAYREF points to an empty array or if LIST is not
           passed.  The array or list must not contain undefined values.

           If the resulting string is longer than "max_array_characters()", a fatal error will
           occur.

       format_date DATETIME
           Converts the DateTime object DATETIME into the appropriate format for the "DATE" data
           type.

       format_datetime DATETIME
           Converts the DateTime object DATETIME into the appropriate format for the "DATETIME
           YEAR TO SECOND" data type.

       format_datetime_year_to_fraction DATETIME
           Converts the DateTime object DATETIME into the appropriate format for the "DATETIME
           YEAR TO FRACTION" data type.

       format_datetime_year_to_fraction_[1-5] DATETIME
           Converts the DateTime object DATETIME into the appropriate format for the "DATETIME
           YEAR TO FRACTION(N)" data type, where N is an integer from 1 to 5.

       format_datetime_year_to_minute DATETIME
           Converts the DateTime object DATETIME into the appropriate format for the "DATETIME
           YEAR TO MINUTE" data type.

       format_datetime_year_to_month DATETIME
           Converts the DateTime object DATETIME into the appropriate format for the "DATETIME
           YEAR TO MONTH" data type.

       format_datetime_year_to_second DATETIME
           Converts the DateTime object DATETIME into the appropriate format for the "DATETIME
           YEAR TO SECOND" data type.

       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 "SET" data type.  Undef is returned if ARRAYREF points to
           an empty array or if LIST is not passed.  If the array or list contains undefined
           values, a fatal error will occur.

       format_timestamp DATETIME
           Converts the DateTime object DATETIME into the appropriate format for the "DATETIME
           YEAR TO FRACTION(5)" data type.

       parse_array STRING | LIST | ARRAYREF
           Parse STRING and return a reference to an array.  STRING should be formatted according
           to the Informix array data type emulation format returned by "format_array()".  Undef
           is returned if STRING is undefined.

           If a LIST of more than one item is passed, a reference to an array containing the
           values in LIST is returned.

           If a an ARRAYREF is passed, it is returned as-is.

       parse_boolean STRING
           Parse STRING and return a boolean value of 1 or 0.  STRING should be formatted
           according to Informix's native "boolean" data type.  Acceptable values are 't', 'T',
           or '1' for true, and 'f', 'F', or '0' for false.

           If STRING is a valid boolean keyword (according to validate_boolean_keyword) or if it
           looks like a function call (matches /^\w+\(.*\)$/) and keyword_function_calls is true,
           then it is returned unmodified.  Returns undef if STRING could not be parsed as a
           valid "boolean" value.

       parse_date STRING
           Parse STRING and return a DateTime object.  STRING should be formatted according to
           the Informix "DATE" data type.

           If STRING is a valid date keyword (according to validate_date_keyword) it is returned
           unmodified.  Returns undef if STRING could not be parsed as a valid "DATE" value.

       parse_datetime STRING
           Parse STRING and return a DateTime object.  STRING should be formatted according to
           the Informix "DATETIME YEAR TO SECOND" data type.

           If STRING is a valid "datetime year to second" keyword (according to
           validate_datetime_year_to_second_keyword) it is returned unmodified.  Returns undef if
           STRING could not be parsed as a valid "DATETIME YEAR TO SECOND" value.

       parse_datetime_year_to_fraction STRING
           Parse STRING and return a DateTime object.  STRING should be formatted according to
           the Informix "DATETIME YEAR TO FRACTION" data type.

           If STRING is a valid "datetime year to fraction" keyword (according to
           validate_datetime_year_to_fraction_keyword) it is returned unmodified.  Returns undef
           if STRING could not be parsed as a valid "DATETIME YEAR TO FRACTION" value.

       parse_datetime_year_to_fraction_[1-5] STRING
           These five methods parse STRING and return a DateTime object.  STRING should be
           formatted according to the Informix "DATETIME YEAR TO FRACTION(N)" data type, where N
           is an integer from 1 to 5.

           If STRING is a valid "datetime year to fraction" keyword (according to
           validate_datetime_year_to_fraction_keyword) it is returned unmodified.  Returns undef
           if STRING could not be parsed as a valid "DATETIME YEAR TO FRACTION(N)" value.

       parse_datetime_year_to_minute STRING
           Parse STRING and return a DateTime object.  STRING should be formatted according to
           the Informix "DATETIME YEAR TO MINUTE" data type.

           If STRING is a valid "datetime year to minute" keyword (according to
           validate_datetime_year_to_minute_keyword) it is returned unmodified.  Returns undef if
           STRING could not be parsed as a valid "DATETIME YEAR TO MINUTE" value.

       parse_datetime_year_to_month STRING
           Parse STRING and return a DateTime object.  STRING should be formatted according to
           the Informix "DATETIME YEAR TO MINUTE" data type.

           If STRING is a valid "datetime year to month" keyword (according to
           validate_datetime_year_to_month_keyword) it is returned unmodified.  Returns undef if
           STRING could not be parsed as a valid "DATETIME YEAR TO MONTH" value.

       parse_datetime_year_to_second STRING
           Parse STRING and return a DateTime object.  STRING should be formatted according to
           the Informix "DATETIME YEAR TO SECOND" data type.

           If STRING is a valid "datetime year to second" keyword (according to
           validate_datetime_year_to_second_keyword) it is returned unmodified.  Returns undef if
           STRING could not be parsed as a valid "DATETIME YEAR TO SECOND" value.

       parse_set STRING | LIST | ARRAYREF
           Parse STRING and return a reference to an array.  STRING should be formatted according
           to Informix's "SET" data type.  Undef is returned if STRING is undefined.

           If a LIST of more than one item is passed, a reference to an array containing the
           values in LIST is returned.

           If a an ARRAYREF is passed, it is returned as-is.

       parse_timestamp STRING
           Parse STRING and return a DateTime object.  STRING should be formatted according to
           the Informix "DATETIME YEAR TO FRACTION(5)" data type.

           If STRING is a valid timestamp keyword (according to validate_timestamp_keyword) it is
           returned unmodified.  Returns undef if STRING could not be parsed as a valid "DATETIME
           YEAR TO FRACTION(5)" value.

       validate_boolean_keyword STRING
           Returns true if STRING is a valid keyword for the "boolean" data type of the current
           data source, false otherwise.  Valid (case-insensitive) boolean keywords are:

               TRUE
               FALSE

       validate_date_keyword STRING
           Returns true if STRING is a valid keyword for the Informix "date", false otherwise.
           Valid (case-insensitive) date keywords are:

               current
               today

           The keywords are not case sensitive.  Any string that looks like a function call
           (matches /^\w+\(.*\)$/) is also considered a valid date keyword if
           keyword_function_calls is true.

       validate_datetime_keyword STRING
           Returns true if STRING is a valid keyword for the Informix "datetime year to second"
           data type, false otherwise.  Valid (case-insensitive) datetime keywords are:

               current
               current year to second
               current year to minute
               current year to hour
               current year to day
               current year to month
               today

           The keywords are not case sensitive.  Any string that looks like a function call
           (matches /^\w+\(.*\)$/) is also considered a valid datetime keyword if
           keyword_function_calls is true.

       validate_datetime_year_to_fraction_keyword STRING
           Returns true if STRING is a valid keyword for the Informix "datetime year to
           fraction(n)" data type (where n is an integer from 1 to 5), false otherwise.  Valid
           (case-insensitive) "datetime year to fraction" keywords are:

               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

           The keywords are not case sensitive.  Any string that looks like a function call
           (matches /^\w+\(.*\)$/) is also considered a valid "datetime year to fraction" keyword
           if keyword_function_calls is true.

       validate_datetime_year_to_minute_keyword STRING
           Returns true if STRING is a valid keyword for the Informix "datetime year to minute"
           data type, false otherwise.  Valid (case-insensitive) "datetime year to minute"
           keywords are:

               current
               current year to second
               current year to minute
               current year to hour
               current year to day
               current year to month
               today

           The keywords are not case sensitive.  Any string that looks like a function call
           (matches /^\w+\(.*\)$/) is also considered a valid "datetime year to minute" keyword
           if keyword_function_calls is true.

       validate_datetime_year_to_month_keyword STRING
           Returns true if STRING is a valid keyword for the Informix "datetime year to month"
           data type, false otherwise.  Valid (case-insensitive) "datetime year to month"
           keywords are:

               current
               current year to second
               current year to minute
               current year to hour
               current year to day
               current year to month
               today

           The keywords are not case sensitive.  Any string that looks like a function call
           (matches /^\w+\(.*\)$/) is also considered a valid "datetime year to month" keyword if
           keyword_function_calls is true.

       validate_datetime_year_to_second_keyword STRING
           Returns true if STRING is a valid keyword for the Informix "datetime year to second"
           data type, false otherwise.  Valid (case-insensitive) datetime keywords are:

               current
               current year to second
               current year to minute
               current year to hour
               current year to day
               current year to month
               today

           The keywords are not case sensitive.  Any string that looks like a function call
           (matches /^\w+\(.*\)$/) is also considered a valid "datetime year to second" keyword
           if keyword_function_calls is true.

       validate_timestamp_keyword STRING
           Returns true if STRING is a valid keyword for the Informix "timestamp" data type,
           false otherwise.  Valid (case-insensitive) timestamp keywords are:

               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

           The keywords are not case sensitive.  Any string that looks like a function call
           (matches /^\w+\(.*\)$/) is also considered a valid timestamp keyword if
           keyword_function_calls is true.

AUTHOR

       John C. Siracusa (siracusa@gmail.com)

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.