view release on metacpan or  search on metacpan

blib/lib/Mac/DtfSQL.pm  view on Meta::CPAN

=item B<$errcode = DtfResQueryFieldInfo ($hres, $colIndex, $fieldSize, $isNull);> 

 # retrieve information about a result set's field

 Arguments: 
   input:  $hres       a valid result handle
           $colIndex   is the 0-based index of the field to retrieve information about
           
   output: $fieldSize  field size in byte
           $isNull     true if the field's value is NULL, false otherwise 



=item B<$errcode = DtfResGetField ($hres, $colIndex, $retrieve_as_Type, $fieldVal, $isNull, $typeHint);> 

 # get the data of this field

 Arguments: 
   input:   $hres              a valid result handle
            $colIndex          is the column index of the field to retrieve (0-based).
            $retrieve_as_Type  either DTF_CT_DEFAULT (= 0) or DTF_CT_CSTRING (= 9) or DTF_CT_SQLSTRING (= 10)
            $typeHint          if $retrieve_as_Type is DTF_CT_DEFAULT, then you *must* specify 
                               the datatype of the data field
   
   output:  $fieldVal  the field's value
            $isNull    true if the field's value is NULL, false otherwise 


Note (1): Due to the differences between the Perl and the C language, the number of parameters  
is slightly different from the C version, i.e. the $typeHint parameter has been added.
 
Note (2): The retrieval as DTF_CT_BLOB type is *not* supported. This Perl interface doesn't handle 
the binary large objects data (blob) type.

Note (3): If you specify the DTF_CT_DEFAULT as the retrieval type, this means that the field value 
will be retrieved as stored in the database without converting it to a string. In this case, you 
have to specify a type hint, i.e. the C datatype of the data field. The type can be determined with
the DtfColCType (...) function (see above) and can be one of the following (integer) constants:

     - DTF_CT_CHAR           #  1   //  signed byte (char)
     - DTF_CT_UCHAR          #  2   //  unsigned byte (char)
     - DTF_CT_SHORT          #  3   //  short
     - DTF_CT_USHORT         #  4   //  unsigned short
     - DTF_CT_LONG           #  5   //  long
     - DTF_CT_ULONG          #  6   //  unsigned long
     - DTF_CT_DOUBLE         #  8   //  double
     - DTF_CT_CSTRING        #  9   //  character string
     - DTF_CT_DATE           # 13   //  date type (like string), format: 'yyyy/mm/dd' or 'yyyy-mm-dd' 
     - DTF_CT_TIME           # 14   //  time type (like string), 24 hour format 'hh:mm:ss' or with 
                                    //  second fractions 'hh:mm:ss.fff'
     - DTF_CT_TIMESTAMP      # 15   //  timestamp type (like string), format: YYYY-MM-DD hh:mm:ss[.fff]
     - DTF_CT_DECIMAL        # 16   //  decimal type

In Perl, these data types -- except the decimal type -- are all scalar types. But internally, Perl 
distinguishes between integer (IV), double (NV) and string (PV) scalar types. Thus, there is indeed a 
difference in retrieving data with the retrieval type set to DTF_CT_CSTRING or set to DTF_CT_DEFAULT.

However, for calculations with retrieved data, it makes no great difference (except for the decimal type) if 
you retrieve a field value as string or as stored in the database with attention to its actual datatype: The 
scalars will contain either numbers or strings. In general, conversion from one form to another is transparent, 
i.e. happens automatically in Perl. This should be suitable even for the decimal datatype when retrieved as 
string, because it is converted to a scalar holding a floating point number in arithmetical operations (although 
the accuracy may suffer).
  
Note (4): If you retrieve data of type decimal, you will get back a *decimal object* in $fieldVal-- see
the section DECIMAL NUMBERS below. This decimal object will be automatically created for you, 
i.e. there is no need to create a decimal object in before and pass it to the function. Hint:
When you retrieve data in a loop, use the ref() function
       
       if ref($fieldVal) { ... } else { ... } 
  
to distinguish between scalars and objects.



=item B<$errcode = DtfResDestroy ($hres);>

 # destroy the result handle

 Arguments: 
   in & out:  $hres  will be set to 0 (NULL) on output
   
S< >

=back


=head2 DISCONNECTING FROM A DATABASE

=over 4

=item B<$errcode = DtfTraDestroy ($htra);> 

 # destroy a transaction handle

 Arguments: 
   in & out:  $htra  will be set to 0 (NULL) on output



=item B<$errcode = DtfConDisconnect ($hcon);> 

 # disconnect from a connection handle

 Arguments: 
   input:  $hcon  a valid connection handle 



=item B<$errcode = DtfConDestroy ($hcon);> 

 # destroy a connection handle

 Arguments: 
   in & out:  $hcon  will be set to 0 (NULL) on output
   


=item B<$errcode = DtfEnvDestroy ($henv);>