view release on metacpan or  search on metacpan

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

    DTF_CF_NETWORK
    DTF_CF_FSSPEC

=head2 ATTRIBUTE CONSTANTS

Generally, you can use the function DtfAttrQueryInfo() to get the default values of all attributes. 
Use the function DtfHdlQueryAttribute() to get the actual value of an attribute after creating the 
appropriate handle and its dependent handles. For example, you cannot create a connection handle 
without creating an environment handle first (which is the connection handle's dependent handle -- 
got it? :).

Use DtfHdlSetAttribute() to change the value of an attribute. A handle's attributes can only be 
modified when the handle is not in locked state. A handle assumes the locked state by creating 
dependent handles on it. For example, the creation of a connection handle causes the environment 
handle to assume locked state. Additionally, a connection handle assumes locked state when it 
undergoes a transition into connected state (a user connects).


S<  >I<ATTRIBUTE TYPES>

    DTF_ATY_LONG 
    DTF_ATY_STRING 
    DTF_ATY_ENUM

S<  >I<INVALID ATTRIBUTE>

    DTF_AT_NONE

S<  >I<GLOBAL SCOPE ATTRIBUTES>
    
    DTF_AT_CODEPAGE

S<  >I<ENVIRONMENT SCOPE ATTRIBUTES>

    DTF_EAT_MESSAGEFILE    DTF_EAT_VMTYPE
    DTF_EAT_RESULTS        DTF_EAT_VMPATH 
    DTF_EAT_RESULTPAGES    DTF_EAT_VMSLOTS
    DTF_EAT_LOGLEVEL       DTF_EAT_VMFILESLOTS
    DTF_EAT_LOGFILE        DTF_EAT_VMFREEMEM 
    DTF_EAT_XSFILES


S<  >I<CONNECTION SCOPE ATTRIBUTES>

    DTF_CAT_TIMEOUT          DTF_CAT_R4STATE
    DTF_CAT_RESETADAPTER     DTF_CAT_R4PATH
    DTF_CAT_REMOVENETNAME    DTF_CAT_R4BACKUPPATH 
    DTF_CAT_NETSYNCDELAY     DTF_CAT_R4LOGFILESIZE
    DTF_CAT_TRANSACTIONS     DTF_CAT_DBTYPE
    DTF_CAT_CACHEBUFFERS     DTF_CAT_DBCREATOR
    DTF_CAT_PAGEALGO         DTF_CAT_SRVSETUP
    DTF_CAT_R4MODE           DTF_CAT_AUTORECOVER


S<  >I<TRANSACTION SCOPE ATTRIBUTES>    

    DTF_TAT_AUTOCOMMIT
    DTF_TAT_RESULTTYPE

    These two attributes are very important, as they control the auto-commit behavior of the
    database and the kind (sequential, random) of the result set's cursor. The following table 
    shows the available information regarding these attributes:

    --------------------+------------+---------------+---------------+-------------------
    Attribute           | Attr. Type | current Value | default Value | Range
    --------------------+------------+---------------+---------------+-------------------
    DTF_TAT_AUTOCOMMIT  | Enum       |         false |         false | false,true
    DTF_TAT_RESULTTYPE  | Enum       |    sequential |    sequential | sequential,random 
    --------------------+------------+---------------+---------------+-------------------



S<  >I<RESULT SCOPE ATTRIBUTES>

    DTF_RAT_TYPE
    
S<  >I<COLUMN SCOPE ATTRIBUTES>

    DTF_LAT_NAME
    DTF_LAT_TABLENAME
    DTF_LAT_CTYPE
    DTF_LAT_DEFINITION
    DTF_LAT_SIZE
    DTF_LAT_DISPLAYWIDTH
    DTF_LAT_PRECISION
    DTF_LAT_SCALE

    These attributes provide meta information about the result table's columns. This implies,
    that a result table/result handle must exist before you can get at this information.

    Let's assume you have created a table with the SQL statement
         
         "CREATE TABLE foobar (article varchar(30), price decimal(6,2))".

    The following tables show all the attribute informations you could retrieve for these two 
    columns, when they are part of a result set. After creating a column handle (dependent on 
    the result handle) with the function DtfColCreate(), you can use the functions DtfColName(), 
    DtfColTableName(), DtfColCType() in addition to DtfHdlQueryAttribute() and DtfAttrQueryInfo() 
    to retrieve the information. A value of -1 means not applicable. 
  
    column article:
 
    ------------------------+------------+---------------+---------------+----------
    Attribute               | Attr. Type | current Value | default Value | Range
    ------------------------+------------+---------------+---------------+----------
    DTF_LAT_NAME            | String     |       article |               | *
    DTF_LAT_TABLENAME       | String     |        foobar |               | *
    DTF_LAT_CTYPE           | Long       |             9 |             0 | 0-10 +++
    DTF_LAT_DEFINITION      | String     |   varchar(30) |               | *
    DTF_LAT_SIZE (in byte)  | Long       |            31 |             0 | *
    DTF_LAT_DISPLAYWIDTH    | Long       |            30 |             0 | *
    DTF_LAT_PRECISION       | Long       |            30 |             0 | *
    DTF_LAT_SCALE           | Long       |            -1 |             0 | *
    ------------------------+------------+---------------+---------------+----------
    +++ note that the range information for the C type is not correct, should be 0-16
 
    column price:
 
    ------------------------+------------+---------------+---------------+----------
    Attribute               | Attr. Type | current Value | default Value | Range
    ------------------------+------------+---------------+---------------+----------

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

=item B<$columncount = DtfResColumnCount ($hres);> 

 # get the number of columns of the result table

 Arguments:
   input:  $hres  a valid result handle



=item B<$errcode = DtfColCreate ($hres, $colIndex, $hcol);> 
 
 # create a column handle from the current result table

 Arguments:
   input:   $hres      a valid result handle
            $colIndex  identifies the result set's column between 0 and columnCount - 1
   
   output:  $hcol  a column handle



=item B<$tablename = DtfColTableName ($hcol);> 

 # get the table name this column belongs to

 Arguments:
   input: $hcol  a valid column handle



=item B<$columnname = DtfColName ($hcol);> 

 # get the column name

 Arguments:
   input: $hcol  a valid column handle



=item B<$datatype_code = DtfColCType ($hcol); >
  
 # get the column's C data type code (see below)

 Arguments:
   input: $hcol  a valid column handle



=item B<$errcode = DtfColDestroy ($hcol);> 

 # destroy the column handle

 Arguments:
   input: $hcol  a valid column handle



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

 # move to the first row of a result table with a sequential cursor
 # (the result table must be of type DTF_RT_SEQUENTIAL)

 Arguments: 
   input:  $hres  a valid result handle



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

 # move to the next row of a result table with a sequential cursor
 # (the result table must be of type DTF_RT_SEQUENTIAL)

 Arguments: 
   input:  $hres  a valid result handle



=item B<$errcode = DtfResMoveToRow ($hres, $rowIndex);> 

 # moves a result set's cursor to an absolute position
 # (the result table must be of type DTF_RT_RANDOM)

 Arguments: 
   input:  $hres      a valid result handle
           $rowIndex  is the 0-based index of the row to move the cursor to



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