Michael Peppler
Sybase Consulting
Sybase on Linux
Install Guide for Sybase on Linux
General Sybase Resources
General Perl Resources
BCP Tool
Bug Tracker
Mailing List Archive
Downloads Directory
Sybase on Linux FAQ
Sybperl FAQ
Michael Peppler's resume

sybperl-l Archive

Up    Prev    Next    

From: David Hajoglou <hojo at greenland dot i-tel dot com>
Subject: Re: Help pls.
Date: Oct 6 1999 5:32PM

     * NAME
          + Attributes
          + DateTime, Money and Numeric data behavior
          + Compatibility with Sybase Open Client documentation.
     * Sybase::DBlib
          + TEXT/IMAGE Routines
          + BCP Routines:
          + Attributes:
          + Status Variables
          + Examples
     * Sybase::Sybperl
     * Sybase::CTlib
          + DESCRIPTION
          + EXAMPLES
          + ATTRIBUTES
     * Using ct_get_data() and ct_send_data() to do raw TEXT processing
          + Retrieving TEXT columns using ct_get_data()
          + Updating TEXT columns using ct_send_data()
     * Common Sybase::DBlib and Sybase::CTlib routines
     * Special handling of DATETIME, MONEY & NUMERIC/DECIMAL values
     * BUGS
     * AUTHORS
   sybperl - Sybase extensions to Perl
   use Sybase::DBlib;
   use Sybase::CTlib;
   use Sybase::Sybperl;
   Sybperl implements three Sybase extension modules to perl (version
   5.002 or higher). Sybase::DBlib adds a subset of the Sybase DB-Library
   API. Sybase::CTlib adds a subset of the Sybase CT-Library (aka the
   Client Library) API. Sybase::Sybperl is a backwards compatibility
   module (implemented on top of Sybase::DBlib) to enable scripts written
   for sybperl 1.0xx to run with Perl 5. Using both the Sybase::Sybperl
   and Sybase::DBlib modules explicitly in a single script is not
   garanteed to work correctly.
   The general usage format for both Sybase::DBlib and Sybase::CTlib is
    use Sybase::DBlib;

    # Allocate a new connection, usually refered to as a database handle
    $dbh = new Sybase::DBlib username, password;

    # Set an attribute for this dbh:
    $dbh->{UseDateTime} = TRUE;

    # Call a method with this dbh:
    $dbh->dbcmd(sql code);

   The DBPROCESS or CS_CONNECTION that is opened with the call to new()
   is automatically closed when the $dbh goes out of scope:
    sub run_a_query {
       my $dbh = new Sybase::CTlib $user, $passwd;
       my @dat = $dbh->ct_sql("select * from sysusers");

       return @dat;
    # The $dbh is automatically closed when we exit the subroutine.

   It should be noted that an important difference between CTlib and
   DBlib is in how the SYBASE environment variable is handled. DBlib only
   checks for the SYBASE variable when it requires access to the
   interfaces file. This allows for definition of the SYBASE variable in
   your script. CTlib requires that the SYBASE variable be defined BEFORE
   initialization. If the variable is not defined then CTlib will not
   initialize properly and your script will not run.

   The Sybase::DBlib and Sybase::CTlib modules make a use of attributes
   that are either package global or associated with a specific $dbh.
   These attributes control certain behavior aspects, and are also used
   to store status information.
   Package global attributes can be set using the %Att hash table in
   either modules. The %Att variable is not exported, so it must be fully
    $Sybase::DBlib::Att{UseDateTime} = TRUE;

   NOTE: setting an attribute via the %Att variable does NOT change the
   status of currently allocated database handles.
   In this version, the available attributes for a $dbh are set when the
   $dbh is created. You can't add arbitrary attributes during the life of
   the $dbh. This has been done to implement a stricter behavior and to
   catch attribute errors.
   It is possible to add your own attributes to a $dbh at creation time.
   The Sybase::BCP module adds two attributes to the normal Sybase::DBlib
   attribute set by passing an additional attribute variable to the
   Sybase::DBlib new() call:
    $d = new Sybase::DBlib $user,$passwd,
                           $server,$appname, {Global => {}, Cols => {}};
DateTime, Money and Numeric data behavior

   As of version 2.04, the Sybase DATETIME and MONEY datatypes can be
   kept in their native formats in both the Sybase::DBlib and
   Sybase::CTlib modules. In addition, NUMERIC or DECIMAL values can also
   be kept in their native formats when using the Sybase::CTlib module.
   This behavior is normally turned off by default, because there is a
   performance penalty associated with it. It is turned on by using
   package or database handle specific attributes.
   Please see the discussion on Special handling of DATETIME, MONEY &
   NUMERIC/DECIMAL values below for details.
Compatibility with Sybase Open Client documentation.

   In general, I have tried to make the calls in this package behave the
   same way as their C language equivalents. In certain cases the
   parameters are different, and certain calls (dblogin() for example)
   don't do the same thing in C as in Perl. This has been done to make
   the life of the Perl programmer easier.
   You should if possible have the Sybase Open Client documentation
   available when writing Sybperl programs.
   A generic perl script using Sybase::DBlib would look like this:
    use Sybase::DBlib;

    $dbh = new Sybase::DBlib 'sa', $pwd, $server, 'test_app';
    $dbh->dbcmd("select * from sysprocesses\n");
    while(@data = $dbh->dbnextrow)
    .... do something with @data ....

   The API calls that have been implemented use the same calling sequence
   as their C equivalents, with a couple of exceptions, detailed below.
   Please see also Common Sybase::DBlib and Sybase::CTlib routines below.
   List of API calls
   Standard Routines:
   $dbh = new Sybase::DBlib [$user [, $server [, $appname [, {additional
   $dbh = Sybase::DBlib->dblogin([$user [, $pwd [, $server [, $appname,
          [{additional attributes}] ]]]])
          Initiates a connection to a Sybase dataserver, using the
          supplied user, password, server and application name
          information. Uses the default values (see DBSETLUSER(),
          DBSETLPWD(), etc. in the Sybase DB-library documentation) if
          the parameters are ommitted.
          Both forms of the call are identical.
          This call can be used multiple times if connecting to multiple
          servers with different username/password combinations is
          required, for example.
          The additional attributes parameter allows you to define
          application specific attributes that you wish to associate with
          the $dbh.
   $dbh = Sybase::DBlib->dbopen([$server [, $appname, [{attributes}] ]])
          Open an additional connection, using the current LOGINREC
   $status = $dbh->dbuse($database)
          Executes ``use database $database'' for the connection $dbh.
   $status = $dbh->dbcmd($sql_cmd)
          Appends the string $sql_cmd to the current command buffer of
          this connection.
   $status = $dbh->dbsqlexec
          Sends the content of the current command buffer to the
          dataserver for execution. See the DB-library documentation for
          a discussion of return values.
   $status = $dbh->dbresults
          Retrieves result information from the dataserver after having
          executed dbsqlexec().
   $status = $dbh->dbsqlsend
          Send the command batch to the server, but do not wait for the
          server to return any results. Should be followed by calls to
          dbpoll() and dbsqlok(). See the Sybase docs for further
   $status = $dbh->dbsqlok
          Wait for results from the server and verify the correctness of
          the instructions the server is responding to. Mainly for use
          with dbmoretext() in Sybase::DBlib. See also the Sybase
          documentation for details.
   ($dbproc, $reason) = Sybase::DBlib->dbpoll($millisecs)
   ($dbproc, $reason) = $dbh->dbpoll($millisecs)
          Note: The dbpoll() syntax has been changed since sybperl
          Poll the server to see if any connection has results pending.
          Used in conjunction with dbsqlsend() and dbsqlok() to perform
          asynchronous queries. dbpoll() will wait up to $millisecs
          milliseconds and poll any open DBPROCESS for results (if called
          as Sybase::DBlib->dbpoll()) or poll the specified DBPROCESS (if
          called as $dbh->dbpoll()). If it finds a DBPROCESS that is
          ready it returns it, along with the reason why it's ready. If
          dbpoll() times out, or if an interupt occurs $dbproc will be
          undefined, and $reason will be either DBTIMEOUT or DBINTERUPT.
          If $millisecs is 0 then dbpoll() returns immediately. If
          $millisecs is -1 then it will not return until either results
          are pending or a system interupt has occured. Please see the
          Sybase documentation for further details.
          Here is an example of using dbsqlsend(), dbpoll() and
  $dbh->dbcmd("exec big_hairy_query_proc");
  # here you can go do something else...
  # now - find out if some results are waiting
  ($dbh2, $reason) = $dbh->dbpoll(100);
  if($dbh2 && $reason == DBRESULT) {   # yes! - there's data on the pipe
     while($dbh2->dbresults != NO_MORE_RESULTS) {
        while(@dat = $dbh2->dbnextrow) {

   $status = $dbh->dbcancel
          Cancels the current command batch.
   $status = $dbh->dbcanquery
          Cancels the current query within the currently executing
          command batch.
          Free the command buffer (required only in special cases - if
          you don't know what this is you probably don't need it :-)
          Force the closing of a connection. Note that connections are
          automatically closed when the $dbh goes out of scope.
          Returns TRUE if the DBPROCESS has been marked DEAD by
   $status = $dbh->DBCURCMD
          Returns the number of the currently executing command in the
          command batch. The first command is number 1.
   $status = $dbh->DBMORECMDS
          Returns TRUE if there are additional commands to be executed in
          the current command batch.
   $status = $dbh->DBCMDROW
          Returns SUCCEED if the current command can return rows.
   $status = $dbh->DBROWS
          Returns SUCCEED if the current command did return rows
   $status = $dbh->DBCOUNT
          Returns the number of rows that the current command affected.
   $row_num = $dbh->DBCURROW
          Returns the number (counting from 1) of the currently retrieved
          row in the current result set.
   $spid = $dbh->dbspid
          Returns the SPID (server process ID) of the current connection
          to the Sybase server.
   $status = $dbh->dbhasretstat
          Did the last executed stored procedure return a status value?
          dbhasretstats must only be called after dbresults returns
          NO_MORE_RESULTS, ie after all the selet, insert, update
          operations of he sored procedure have been processed.
   $status = $dbh->dbretstatus
          Retrieve the return status of a stored procedure. As with
          dbhasretstat, call this function after all the result sets of
          the stored procedure have been processed.
   $status = $dbh->dbnumcols
          How many columns are in the current result set.
   $status = $dbh->dbcoltype($colid)
          What is the column type of column $colid in the current result
   $type = $dbh->dbprtype($colid)
          Returns the column type as a printable string.
   $status = $dbh->dbcollen($colid)
          What is the length (in bytes) of column $colid in the current
          result set.
   $string = $dbh->dbcolname($colid)
          What is the name of column $colid in the current result set.
   @dat = $dbh->dbnextrow([$doAssoc [, $wantRef]])
          Retrieve one row. dbnextrow() returns an array of scalars, one
          for each column value. If $doAssoc is non-0, then dbnextrow()
          returns a hash (aka associative array) with column name/value
          pairs. This relieves the programmer from having to call
          dbbind() or dbdata().
          If $wantRef is non-0, then dbnextrow() returns a reference to a
          hash or an array. This reference points to a static array (or
          hash) so if you wish to store the returned rows in an array,
          you must copy the array/hash:
  while($d = $dbh->dbnextrow(0, 1)) {
     push(@rows, [@$d]);

          The return value of the C version of dbnextrow() can be
          accessed via the Perl DBPROCESS attribute field, as in:
   @arr = $dbh->dbnextrow;              # read results
   if($dbh->{DBstatus} != REG_ROW) {
     take some appropriate action...

          When the results row is a COMPUTE row, the ComputeID field of
          the DBPROCESS is set:
   @arr = $dbh->dbnextrow;              # read results
   if($dbh->{ComputeID} != 0) { # it's a 'compute by' row
     take some appropriate action...

          dbnextrow() can also return a hash keyed on the column name:
   $dbh->dbcmd("select Name=name, Id = id from test_table");
   $dbh->dbsqlexec; $dbh->dbresults;

   while(%arr = $dbh->dbnextrow(1)) {
      print "$arr{Name} : $arr{Id}\n";

   @dat = $dbh->dbretdata[$doAssoc])
          Retrieve the value of the parameters marked as 'OUTPUT' in a
          stored procedure. If $doAssoc is non-0, then retrieve the data
          as an associative array with parameter name/value pairs.
   $bylist = $dbh->dbbylist($computeID)
          Returns the by list for a compute by clause. $bylist is a
          reference to an array of colids. You can use $dbh->dbcolname()
          to get the column names.
    $dbh->dbcmd("select * from sysusers order by uid compute count(uid) by uid"
    my @dat;
    while(@dat = $dbh->dbnextrow) {
        if($dbh->{ComputeID} != 0) {
            my $bylist = $dbh->dbbylist($dbh->{ComputeID});
            print "bylist = @$bylist\n";
        print "@dat\n";

   %hash = $dbh->dbcomputeinfo($computeID, $column)
          Returns a hash with the colid, op, len, type and utype of the
          compute by column. You can call this subroutine to get the
          information returned by DBlibrary's dbalt*() calls. The $column
          is the column number in the current compute by row (starting at
          1) and the $computeID is best retrieved from $dbh-{ComputeID}>.
          Please see the documentation of the dbalt*() calls in Sybase's
          DBlibrary manual.
   $string = $dbh->dbstrcpy
          Retrieve the contents of the command buffer.
   $ret = $dbh->dbsetopt($opt [, $c_val [, $i_val]])
          Sets option $opt with optional character parameter $c_val and
          optional integer parameter $i_val. $opt is one of the option
          values defined in the Sybase DBlibrary manual (
          DBSHOWPLAN, DBTEXTSIZE). For example, to set SHOWPLAN on, you
          would use

          See also dbclropt() and dbisopt() below.
   $ret = $dbh->dbclropt($opt [, $c_val])
          Clears the option $opt, previously set using dbsetopt().
   $ret = $dbh->dbisopt($opt [, $c_val])
          Returns TRUE if the option $opt is set.
   $string = $dbh->dbsafestr($string [,$quote_char])
          Convert $string to a 'safer' version by inserting single or
          double quotes where appropriate, so that it can be passed to
          the dataserver without syntax errors.
          The second argument to dbsafestr() (normally DBSINGLE, DBDOUBLE
          or DBBOTH) has been replaced with a literal ' or `` (meaning
          DBSINGLE or DBDOUBLE, respectively). Omitting this argument
          means DBBOTH.
   $packet_size = $dbh->dbgetpacket
          Returns the TDS packet size currently in use for this $dbh.

   $status = $dbh->dbwritetext($colname, $dbh_2, $colnum, $text [, $log])
          Insert or update data in a TEXT or IMAGE column. The usage is a
          bit different from that of the C version:
          The calling sequence is a little different from the C version,
          and logging is off by default:
          $dbh_2 and $colnum are the DBPROCESS and column number of a
          currently active query. Example:
   $dbh_2->dbcmd('select the_text, t_index from text_table where t_index = 5');
   $dbh_2->dbsqlexec; $dbh_2->dbresults;
   @data = $dbh_2->dbnextrow;

   $d->dbwritetext ("text_table.the_text", $dbh_2, 1,
        "This is text which was added with Sybperl", TRUE);

   $status = $dbh->dbpreptext($colname, $dbh_2, $colnum, $size [, $log])
          Prepare to insert or update text with dbmoretext().
          The calling sequence is a little different from the C version,
          and logging is off by default:
          $dbh_2 and $colnum are the DBPROCESS and column number of a
          currently active query. Example:
   $dbh_2->dbcmd('select the_text, t_index from text_table where t_index = 5');
   $dbh_2->dbsqlexec; $dbh_2->dbresults;
   @data = $dbh_2->dbnextrow;

   $size = length($data1) + length($data2);
   $d->dbpreptext ("text_table.the_text", $dbh_2, 1, $size, TRUE);
   $dbh->dbmoretext(length($data1), $data1);
   $dbh->dbmoretext(length($data2), $data2);


   $status = $dbh->dbmoretext($size, $data)
          Sends a chunk of TEXT/IMAGE data to the server. See the example
   $status = $dbh->dbreadtext($buf, $size)
          Read a TEXT/IMAGE data item in $size chunks.
    $dbh->dbcmd("select data from text_test where id=1");
    while($dbh->dbresults != NO_MORE_RESULTS) {
        my $bytes;
        my $buf = '';
        while(($bytes = $dbh->dbreadtext($buf, 512)) != NO_MORE_ROWS) {
            if($bytes == -1) {
                die "Error!";
            } elsif ($bytes == 0) {
                print "End of row\n";
            } else {
                print "$buf";
BCP Routines:

   See also the Sybase::BCP module.
          This is an exported routine (ie it can be called without a $dbh
          handle) which sets the BCP IN flag to TRUE/FALSE.
          It is necessary to call BCP_SETL(TRUE) before opening the
          connection with which one wants to run a BCP IN operation.
   $state = bcp_getl
          Retrieve the current BCP flag status.
   $status = $dbh->bcp_init($table, $hfile, $errfile, $direction)
          Initialize BCP library. $direction can be DB_OUT or DB_IN
   $status = $dbh->bcp_meminit($numcols)
          This is a utility function that does not exist in the normal
          BCP API. It's use is to initialize some internal variables
          before starting a BCP operation from program variables into a
          table. This call avoids setting up translation information for
          each of the columns of the table being updated, obviating the
          use of the bcp_colfmt call.
          See EXAMPLES, below.
   $status = $dbh->bcp_sendrow(LIST)
   $status = $dbh->bcp_sendrow(ARRAY_REF)
          Sends the data in LIST to the server. The LIST is assumed to
          contain one element for each column being updated. To send a
          NULL value set the appropriate element to the Perl undef value.
          In the second form you pass an array reference instead of
          passing the LIST, which makes processing a little bit faster on
          wide tables.
   $rows = $dbh->bcp_batch
          Commit rows to the database. You usually use it like this:
       while() {
           @data = split(/\|/);
           $d->bcp_sendrow(\@data);    # Pass the array reference

           # Commit data every 100 rows.
           if((++$count % 100) == 0) {

   $status = $dbh->bcp_done
   $status = $dbh->bcp_control($field, $value)
   $status = $dbh->bcp_columns($colcount)
   $status = $dbh->bcp_colfmt($host_col, $host_type, $host_prefixlen,
          $host_collen, $host_term, $host_termlen, $table_col [,
          $precision, $scale])
          If you have DBlibrary for System 10 or higher, then you can
          pass the additional $precision and $scale parameters, and have
          sybperl call bcp_colfmt_ps() instead of bcp_colfmt().
   $status = $dbh->bcp_collen($varlen, $table_column)
   $status = $dbh->bcp_exec
   $status = $dbh->bcp_readfmt($filename)
   $status = $dbh->bcp_writefmt($filename)
          Please see the DB-library documentation for these calls.
   DBMONEY Routines:
   NOTE: In this version it is possible to avoid calling the routines
   below and still get DBMONEY calculations done with the correct
   precision. See the Sybase::DBlib::Money discussion below.
   ($status, $sum) = $dbh->dbmny4add($m1, $m2)
   $status = $dbh->dbmny4cmp($m1, $m2)
   ($status, $quotient) = $dbh->dbmny4divide($m1, $m2)
   ($status, $dest) = $dbh->dbmny4minus($source)
   ($status, $product) = $dbh->dbmny4mul($m1, $m2)
   ($status, $difference) = $dbh->dbmny4sub($m1, $m2)
   ($status, $ret) = $dbh->dbmny4zero
   ($status, $sum) = $dbh->dbmnyadd($m1, $m2)
   $status = $dbh->dbmnycmp($m1, $m2)
   ($status, $ret) = $dbh->dbmnydec($m1)
   ($status, $quotient) = $dbh->dbmnydivide($m1, $m2)
   ($status, $ret, $remainder) = $dbh->dbmnydown($m1, $divisor)
   ($status, $ret) = $dbh->dbmnyinc($m1)
   ($status, $ret, $remain) = $dbh->dbmnyinit($m1, $trim)
   ($status, $ret) = $dbh->dbmnymaxneg
   ($status, $ret) = $dbh->dbmnymaxpos
   ($status, $dest) = $dbh->dbmnyminus($source)
   ($status, $product) = $dbh->dbmnymul($m1, $m2)
   ($status, $m1, $digits, $remain) = $dbh->dbmnyndigit($m1)
   ($status, $ret) = $dbh->dbmnyscale($m1, $multiplier, $addend)
   ($status, $difference) = $dbh->dbmnysub($m1, $m2)
   ($status, $ret) = $dbh->dbmnyzero
          All of these routines correspond to their DB-library
          counterpart, with the following exception:
          The routines which in the C version take pointers to arguments
          (in order to return values) return these values in an array
   status = dbmnyadd(dbproc, m1, m2, &result) becomes
   ($status, $result) = $dbproc->dbmnyadd($m1, $m2)

   RPC Routines:
   NOTE: Check out eg/ for an example on how to use these
   $dbh->dbrpcinit($rpcname, $option)
          Initialize an RPC call to the remote procedure $rpcname. See
          the DB-library manual for valid values for $option.
   $dbh->dbrpcparam($parname, $status, $type, $maxlen, $datalen, $value)
          Add a parameter to an RPC call initiated with dbrpcinit().
          Please see the DB-library manual page for details & values for
          the parameters.
          NOTE: All floating point types (MONEY, FLOAT, REAL, DECIMAL,
          etc.) are converted to FLOAT before being sent to the RPC.
          Execute an RPC initiated with dbrpcinit().
          NOTE: This call executes both dbrpcsend() and dbsqlok(). You
          can call $dbh->dbresults direcly after calling $dbh->dbrpcsend.
   dbrpwset($srvname, $pwd)
          Set the password for connecting to a remote server.
          Clear all remote server passwords.
   Registered procedure execution:
   $status = $dbh->dbreginit($proc_name)
   $status = $dbh->dbreglist
   $status = $dbh->dbreglist($parname, $type, $datalen, $value)
   $status = $dbh->dbregexec($opt)
          These routines are used to execute an OpenServer registered
          procedure. Please the Sybase DBlibrary manual for a description
          of what these routnines do, and how to call them.
   Two Phase Commit Routines:
   $dbh = Sybase::DBlib->open_commit($user, $pwd, $server, $appname)
   $id = $dbh->start_xact($app_name, $xact_name, $site_count)
   $status = $dbh->stat_xact($id)
   $status = $dbh->scan_xact($id)
   $status = $dbh->commit_xact($id)
   $status = $dbh->abort_xact($id)
   $string = Sybase::DBlib::build_xact_string($xact_name, $service_name,
   $status = $dbh->remove_xact($id, $site_count)
          Please see the Sybase documentation for this.
          NOTE: These routines have not been thouroughly tested!
   Exported Routines:
   $old_handler = dberrhandle($err_handle)
   $old_handler = dbmsghandle($msg_handle)
          Register an error (or message) handler for DB-library to use.
          Handler examples can be found in in the Sybperl
          distribution. Returns a reference to the previously defined
          handler (or undef if none were defined). Passing undef as the
          argument clears the handler.
          Set the name of the 'interfaces' file. This file is normally
          found by DB-library in the directory pointed to by the $SYBASE
          environment variable.
          Start recording all SQL sent to the server in file $filename.
          Returns a string identifying the version of DBlibrary that this
          copy of Sybperl was built with.
   $time = DBGETTIME
   $time = dbsettime($seconds)
   $time = dbsetlogintime($seconds)
          These utility routines are probably very seldom used. See the
          DB-library manual for an explanation of their use.
          Tell DB-library that we're done. Once this call has been made,
          no further activity requiring DB-library can be performed in
          the current program.
   Utility Routines:
   These routines are not part of the DB-library API, but have been added
   because they can make our life as programers easier, and exploit
   certain strenghts of Perl.
   $ret|@ret = $dbh->sql($cmd [, \&rowcallback [, $flag]])
          Runs the sql command and returns the result as a reference to
          an array of the rows. In a LIST context, return the array
          itself (instead of a reference to the array). Each row is a
          reference to an array of scalars.
          If you provide a second parameter it is taken as a procedure to
          call for each row. The callback is called with the values of
          the row as parameters.
          If you provide a third parameter, this is used in the call to
          dbnextrow() to retrieve associative arrays rather than 'normal'
          arrays for each row, and store them in the returned array. To
          pass the third parameter without passing the &rowcallback value
          you should pass the special value undef as second parameter:
        @rows = $dbh->sql("select * from sysusers", undef, TRUE);
        foreach $row_ref (@rows) {
            if($$row_ref{'uid'} == 10) {

          See also eg/ for an example.
          Contributed by Gisle Aas.
          NOTE: This routine loads all the data into memory. It should
          not be run with a query that returns a large number of rows. To
          avoid the risk of overflowing memory, you can limit the number
          of rows that the query returns by setting the 'MaxRows' field
          of the $dbh attribute field:
        $dbh->{'MaxRows'} = 100;

          This value is not set by default.
   @ret = $dbh->nsql($sql [, "ARRAY" | "HASH" ] [, \&subroutine ] );
          An enhanced version of the sql routine, nsql, is also
          available. nsql() provides better error checking (using its
          companion error and message handlers), optional deadlock retry
          logic, and several options for the format of the return values.
          In addition, the data can either be returned to the caller in
          bulk, or processes line by line via a callback subroutine
          passed as an argument (this functionality is similar to the
          r_sql() method).
          The arguments are an SQL command to be executed, the $type of
          the data to be returned, and the callback subroutine.
          if a callback subroutine is not given, then the data from the
          query is returned as an array. The array returned by nsql is
          one of the following:
    Array of Hash References (if type eq HASH)
    Array of Array References (if type eq ARRAY)
    Simple Array (if type eq ARRAY, and a single column is queried
    Boolean True/False value (if type ne ARRAY or HASH)

          Optionally, instead of the words ``HASH'' or ``ARRAY'' a
          reference of the same type can be passed as well. This is, both
          of the following are equivalent:
    $dbh->nsql("select col1,col2 from table","HASH");
    $dbh->nsql("select col1,col2 from table",{});

          For example, the following code will return an array of hash
    @ret = $dbh->nsql("select col1,col2 from table","HASH");
    foreach $ret ( @ret ) {
      print "col1 = ", $ret->{'col1'}, ", col2 = ", $ret->{'col2'}, "\n";

          The following code will return an array of array references: