view release on metacpan or  search on metacpan

Sybase.pm  view on Meta::CPAN

It is sometimes necessary (or beneficial) to specify other connection
properties. Currently the following are supported:

=over 4

=item server

Specify the server that we should connect to.

     $dbh = DBI->connect("dbi:Sybase:server=BILLING",
			 $user, $passwd);

The default server is I<SYBASE>, or the value of the I<$DSQUERY> environment
variable, if it is set.

=item host

=item port

If you built DBD::Sybase with OpenClient 12.5.1 or later, then you can
use the I<host> and I<port> values to define the server you want to
connect to. This will by-pass the server name lookup in the interfaces file.
This is useful in the case where the server hasn't been entered in the 
interfaces file.

     $dbh = DBI->connect("dbi:Sybase:host=db1.domain.com;port=4100",
			 $user, $passwd);

=item maxConnect

By default DBD::Sybase (and the underlying OpenClient libraries) is limited
to openening 25 simultaneous connections to one or more database servers.
If you need more than 25 connections at the same time, you can use the
I<maxConnect> option to increase this number.

     $dbh = DBI->connect("dbi:Sybase:maxConnect=100",
			 $user, $passwd);


=item database

Specify the database that should be made the default database.

     $dbh = DBI->connect("dbi:Sybase:database=sybsystemprocs",
			 $user, $passwd);

This is equivalent to 

    $dbh = DBI->connect('dbi:Sybase:', $user, $passwd);
    $dbh->do("use sybsystemprocs");


=item charset

Specify the character set that the client uses.

     $dbh = DBI->connect("dbi:Sybase:charset=iso_1",
			 $user, $passwd);

The default charset used depends on the locale that the application runs
in. If you wish to interact with unicode varaiables (see syb_enable_utf8, below) then
you should set charset=utf8. Note however that this means that Sybase will expect all
data sent to it for char/varchar columns to be encoded in utf8 (e.g. sending iso8859-1 characters
like e-grave, etc).

=item language

Specify the language that the client uses.

     $dbh = DBI->connect("dbi:Sybase:language=us_english",
			 $user, $passwd);

Note that the language has to have been installed on the server (via
langinstall or sp_addlanguage) for this to work. If the language is not
installed the session will default to the default language of the 
server.

=item packetSize

Specify the network packet size that the connection should use. Using a
larger packet size can increase performance for certain types of queries.
See the Sybase documentation on how to enable this feature on the server.

     $dbh = DBI->connect("dbi:Sybase:packetSize=8192",
			 $user, $passwd);

=item interfaces

Specify the location of an alternate I<interfaces> file:

     $dbh = DBI->connect("dbi:Sybase:interfaces=/usr/local/sybase/interfaces",
			 $user, $passwd);

=item loginTimeout

Specify the number of seconds that DBI->connect() will wait for a 
response from the Sybase server. If the server fails to respond before the
specified number of seconds the DBI->connect() call fails with a timeout
error. The default value is 60 seconds, which is usually enough, but on a busy
server it is sometimes necessary to increase this value:

     $dbh = DBI->connect("dbi:Sybase:loginTimeout=240", # wait up to 4 minutes
			 $user, $passwd);


=item timeout

Specify the number of seconds after which any Open Client calls will timeout
the connection and mark it as dead. Once a timeout error has been received
on a connection it should be closed and re-opened for further processing.

Setting this value to 0 or a negative number will result in an unlimited
timeout value. See also the Open Client documentation on CS_TIMEOUT.

     $dbh = DBI->connect("dbi:Sybase:timeout=240", # wait up to 4 minutes
			 $user, $passwd);

=item scriptName

Specify the name for this connection that will be displayed in sp_who
(ie in the sysprocesses table in the I<program_name> column).

Sybase.pm  view on Meta::CPAN

If this attribute is set then DBD::Sybase will B<not> allow multiple
simultaneously active statement handles on one database handle (i.e.
multiple $dbh->prepare() calls without completely processing the
results from any existing statement handle). This can be used
to debug situations where incorrect or unexpected results are
found due to the creation of a sub-connection where the connection
attributes (in particular the current database) are different.

Default: off

=item syb_bind_empty_string_as_null (bool)

If this attribute is set then an empty string (i.e. "") passed as
a parameter to an $sth->execute() call will be converted to a NULL
value. If the attribute is not set then an empty string is converted to
a single space.

Default: off

=item syb_cancel_request_on_error (bool)

If this attribute is set then a failure in a multi-statement request
(for example, a stored procedure execution) will cause $sth->execute()
to return failure, and will cause any other results from this request to 
be discarded.

The default value (B<on>) changes the behavior that DBD::Sybase exhibited
up to version 0.94. 

Default: on

=item syb_date_fmt (string)

Defines the date/time conversion string when fetching data. See the 
entry for the C<syb_date_fmt()> method elsewhere in this document for a
description of the available formats.

=item syb_has_blk (bool)

This read-only attribute is set to TRUE if the BLK API is available in
this version of DBD::Sybase. 

=item syb_disconnect_in_child (bool)

Sybase client library allows using opened connections across a fork (i.e. the opened connection 
can be used in the child process). DBI by default will set flags such that this connection will 
be closed when the child process terminates. This is in most cases not what you want. DBI provides
the InactiveDestroy attribute to control this, but you have to set this attribute manually as it
defaults to False (i.e. when DESTROY is called for the handle the connection is closed).
The syb_disconnect_in_child attribute attempts to correct this - the default is for this 
attribute to be False - thereby inhibitting the closing of the connection(s) when 
the current process ID doesn't match the process ID that created the connection.

Default: off

=item syb_enable_utf8 (bool)

If this attribute is set then DBD::Sybase will convert UNIVARCHAR, UNICHAR,
and UNITEXT data to Perl's internal utf-8 encoding when they are
retrieved. Updating a unicode column will cause Sybase to convert any incoming
data from utf-8 to its internal utf-16 encoding.

This feature requires OpenClient 15.x to work.

Default: off

=back

=head2 Statement Handle Attributes

The following read-only attributes are available at the statement level:

=over 4

=item syb_more_results (bool)

See the discussion on handling multiple result sets above.

=item syb_result_type (int)

Returns the numeric result type of the current result set. Useful when 
executing stored procedurs to determine what type of information is
currently fetchable (normal select rows, output parameters, status results,
etc...).

=item syb_do_proc_status (bool)

See above (under Database Handle Attributes) for an explanation.

=item syb_proc_status (read-only)

If syb_do_proc_status is set, then the return status of stored procedures will
be available via $sth->{syb_proc_status}.

=item syb_no_bind_blob (bool)

If set then any IMAGE or TEXT columns in a query are B<NOT> returned
when calling $sth->fetch (or any variation).

Instead, you would use

    $sth->syb_ct_get_data($column, \$data, $size);

to retrieve the IMAGE or TEXT data. If $size is 0 then the entire item is
fetched, otherwis  you can call this in a loop to fetch chunks of data:

    while(1) {
        $sth->syb_ct_get_data($column, \$data, 1024);
	last unless $data;
	print OUT $data;
    }

The fetched data is still subject to Sybase's TEXTSIZE option (see the
SET command in the Sybase reference manual). This can be manipulated with
DBI's B<LongReadLen> attribute, but C<$dbh->{LongReadLen}> I<must> be 
set before $dbh->prepare() is called to take effect (this is a change
in 1.05 - previously you could call it after the prepare() but 
before the execute()). Note that LongReadLen
has no effect when using DBD::Sybase with an MS-SQL server.