General Information

Driver version

DBD::RDB version 1.20

Feature summary

    Transactions                            Yes
    Locking                                 Yes, implicit and explicit
    Table joins                             Yes, inner and outer
    LONG/LOB datatypes                      Yes, as cursor
    Statement handle attributes available   After prepare()
    Placeholders                            Yes, "?"
    Stored Procedures                       Yes
    Bind output values                      Yes
    Table name letter case                  Uppercase
    Field name letter case                  Uppercase
    Quoting of otherwise invalid names      Yes, via double quotes
    Case-insensitive "LIKE" operator        No
    Server table RWO ID pseudocolumn        Yes
    Positioned update/delete                Yes
    Concurrent use of mutliple handles      Yes 

Author and contact details

The driver author is Andreas Stiller. He can be contacted at andreas.stiller at eds dot com

Supported database versions and options

The DBD::RDB modules supports Orcale RDB for OpenVMS, versions 6.x (untested), 7.0.x and 7.1 (tested). A RDB development installation and license is needed to build the module.

Connect Syntax

  use DBI;

  $dbh = DBI->connect("dbi:RDB:ATTACH FILENAME <rootfile>" );

  # The $user and $passwd parameters of the standard connect are unused.
  # They should be included instead in the ATTACH if needed for a remote
  # connection

The connect use the syntax of the CONNECT TO statement. The example above connects to a database with the rootfile <rootfile> and use the standard RDB alias. If inside SQL a connect works with

SQL> CONNECT TO 'connect-string';

then the next command should also work:

  $dbh = DBI->connect("dbi:RDB:connect-string");

An example with a second alias inside the same connection is

  $dbh = DBI->connect("dbi:RDB:ATTACH FILENAME <rootfile-1>, 
                               ATTACH ALIAS A FILENAME <rootfile-2>" );

Multiple connects (i.e. multiple $dbh's) are supported using the SET CONNECT inside the DBD.

Datatypes

Numerica data handling

DBD::RDB supports these numeric datatypes

    TINYINT              - signed 8-bit integer
    SMALLINT             - signed 16-bit integer
    INTEGER              - signed 32-bit integer
    BIGINT               - signed 64-bit integer
                         - all four can have PRECISION
    FLOAT                - native C 'double'
    REAL                 - native C 'float'
    DOUBLE PRECISION     - Synonym for FLOAT
                         - using PRECISION switch between float and double

The corresponding IV and NV representation is used. BIGINTs are represented as strings. The conversion between NV and float and vice versa signals floating overflow and underflow in case.

String data handling

DBD::RDB supports the following string datatypes

    VARCHAR(size)
    CHAR(size)
    CHAR

CHAR and VARCHAR have a limit of 65,271 octets. CHAR is fixed-length and blank-padded. NCHAR, NATIONAL CHR, etc. are not tested.

Date data handling

RDB stores all date/time columns in 64-Bit VMS format. That means that the driver does not see the choosen SQL datatype. From this internal format the date/time is converted to string format using a given format. The format is specified as a database handle attribute.

  $dbh->{rdb_dateformat} = '|!DB-!MAAU-!Y4|!H04:!M0:!S0.!C2|'

This is the VMS standard date format. Normally the attribute is used in the connect statement. Every format the LIBRTL routines can take is allowed. The default used in the connect is '|!Y4!MN0!D0|!H04!M0!S0!C2|'. This format is used for the conversion from RDB to Perl The other direction use the following list after checking the current output format.

    !DB-!MAAU-!Y4|!H04:!M0:!S0.!C2             1-DEC-2000 23:12:10.99
    !DB.!MAAU.!Y4|!H04:!M0:!S0.!C2             1.DEC.2000 23:12:10.99
    !D0.!MN0.!Y4|!H04:!M0:!S0.!C2              01.12.2000 23:12:10.99
    !D0.!MN0.!Y2|!H04:!M0:!S0.!C2              01.12.00 23:12:10.99
    !D0-!MN0-!Y4|!H04:!M0:!S0.!C2              01-12-2000 23:12:10.99
    !D0-!MN0-!Y2|!H04:!M0:!S0.!C2              01-12-00 23:12:10.99
    !Y4.!MN0.!D0|!H04:!M0:!S0.!C2              2000.12.01 23:12:10.99
    !Y4!MN0!D0|!H04!M0!S0!C7                   20001201 2312109912345
    !Y4!MN0!D0|!H04:!M0:!S0.!C7                20001201 23:12:10.9912345

The current value of SYS$LANGUAGE influence the meaning of MAAU (name of month) as in the corresponding LIBRTL routines.

Date Intervals are supported in all flavours. The format cannot be changed like for the date types.

Parameter Binding

Parameter binding is supported either in standard ? style or using named parameters. Named parameters can be used only with bind_param_inout. If the first parameter is not an integer then it is taken as parameter name (string) and compared against the parameter names used in the SQL statement. These are either the column names or whatever was suggested with SELECT xx AS yy.

Stored Procedures

Stored procedures are supported. The use of bind_param_input together with named parameter markers is recommended. An example is

    $dbh->do( "CREATE MODULE test_module_2 LANGUAGE SQL " .
              "PROCEDURE proc_b( OUT :a integer, INOUT :b integer, " .
              "                  IN :c char(5),  INOUT :parD char(10) ); " .
              "  BEGIN " .
              "   SET :b = :b + 10; " .
              "   SET :a = :b + 123; " .
              "   SET :parD = :c || :parD; " .
              "  END; " .
              "END MODULE" );
    $st_call = $dbh->prepare( "CALL proc_b( ?, ?, ?, ?)" );
    $st_call->bind_param_inout( "A", \$a, 0 );
    $st_call->bind_param_inout( "B", \$b, 0 );
    $st_call->bind_param_inout( "C", \$c, 0 );
    $st_call->bind_param_inout( "PARD", \$d, 0 );

    $b = 32;
    $c = 'abcde';
    $d = 'fghij';
    $st_call->execute;

    die unless $a == 165;
    die unless $b == 42;
    die unless $d eq "abcdefghij";

Other data handling issues

The segmented string data type is not supported.

RDB specific extensions to DBI/DBD functionality

The first is the date/time format handling (see above). The second is the possibility to open a CURSOR WITH HOLD. This option keeps the cursor open even after a commit. This option is applied during a prepare like

  $st = $dbh->prepare( "select column1 from table where " .
                       "       column2 > 10",
                       { rdb_hold => 1 } );

Examples

Examples can be found the test.pl file which tries to test all the described features...

AUTHOR

DBD::RDB by Andreas Stiller. DBI by Tim Bunce.

COPYRIGHT

The DBD::RDB module is Copyright (c) 2000 Andreas Stiller. Germany. The DBD::RDB module is free software; you can redistribute it and/or modify it under the same terms as Perl itself with the exception that it cannot be placed on a CD-ROM or similar media for commercial distribution without the prior approval of the author.