Sybase::TdsServer - A simple module to create a tds-server (like Sybase or freetds)
use Sybase::TdsServer; my $server = Sybase::TdsServer->new($servername, \&connect_handler, \&disconnect_handler, \&language_handler); $server->set_handler($handler, \&handling_sub); $server->run; $server->disconnect($connect_handle); $server->shutdown; $server->send_header($connect_handle, \@header); $server->send_row($connect_handle, \@row); $server->send_done($connect_handle, $status, $tran_state, $numrows); $server->send_eed($connect_handle, $msg_nr, $class, $tran_state, $msg, $server, $procedure, $line);
Sybase::TdsServer lets you create a server which listens to the TDS protocol spoken by Sybase clients. The server will accept multiple connections without threads or forking.
One possible use could be to create a server that listens to a Replication Agent running in a Sybase Server. This server could catch the data comming from the agent and do some further processing on it.
None, so far.
Parameters:
The name of the server that shall be created. This name must exist in the interfaces file, from which the ip-address and the portnumber will be fetched.
A reference to a subroutine that will be called whenever a client connects to the server. Parameters for the connect handler are:
a handle identifying this connection.
the login provided by the client
the password provided by the client
A reference to a subroutine that will be called whenever a client disconnects from the server. Parameters for the disconnect handler are:
A reference to a subroutine that will be called whenever a client sends data to the server. Parameters for the language handler are:
the text that was sent by the client
More on handlers further down.
Returnvalues:
The constructor returns a TdsServer-object if it succeeds, otherwise undef.
Example:
my $s = Sybase::TdsServer->new($servername, \&conn_handler, \&disconn_handler, \&lang_handler);
For simple examples of the handler, look at the file test.pl in this distribution.
type of handler is one of the following:
capability optioncmd rpc
handler is a reference to a subroutine which is called when the event arrives
handler types:
All handlers recieve a connection handle as their first parameter.
Will be called whenever a client sends an OPTIONCMD token to the server. Parameters for the optioncmd handler are:
The decimal value of the command of the OPTIONCMD token. One of: 1 = set - set an option 2 = deafult - set option to default 3 = list - request current setting 4 = info - report current setting
The decimal value of the option, values range from 0 to 38.
The length of the argument for the option.
The argument for the option.
Will be called whenever a client sends an rpc request. FIXME: not implemented yet! Parameters for the rpc handler are:
The command
Will be called whenever capability requests come from the client. Parameters for the capability handler are:
Both are binary values constaining one bit for each capability
$s->set_handler('optioncmd' => \&option_handler);
none
$s->run;
connect handle
$s->disconnect($connect_handle);
The program will continue execution after the run.
$s->shutdown;
Connection Handle.
Reference to an array containing header information.
See 'Handlers' for more on header information.
$s->send_header($conn_handle, [{ column_name => 'result', column_type => 'SYBVARCHAR', column_size => 30 }] );
Reference to an array containing row data.
See 'Handlers' for more on row data.
$s->send_row($conn_handle, ['data1', 'data2', 'data3'] );
Status is a bitmap with the following meaning:
0x0000 done final Result complete, successful 0x0001 done more Result complete, more results to follow 0x0002 done error Error occured in current command 0x0004 done inxact Transaction in progress for command 0x0008 done proc Result comes from a stored procedure 0x0010 done count 0x0020 done attn to acknowlegde an attention 0x0040 done event part of event notification
Status of the current transaction is one of the following:
0 not in tran 1 tran succeed 2 tran in progress 3 statement abort 4 tran abort
$s->send_done($conn_handle, 0x00, 0, 1);
Class is the severity of the error.
The message text.
$s->send_eed($conn_handle, 1234, 0, 0, 'error message', 'this_server');
The communication between the module and the application works with handlers (callbacks).
You have to provide the following handlers:
This handler is called when a new connection to the server is made.
It recieves a session-handle and a reference to the login hash, see 'structures' for info on the login hash.
Return true to acknowledge the connection, false to refuse.
This handler is called when a client disconnects from the server.
It gives the application the opportunity to clean up on a connection.
This handler is called when a new connection sends a language command to the server.
It recieves a session-handle, the string that was sent by the client.
The handler processes the string and sends back a result of the following form:
An array that contains references to arrays representing the header and the rows of the result set.
The header-array contains references to hashes for each column returned. Each row-array contains the value for the columns.
Each hash in the header-array must contain the entries:
The column name.
one of:
SYBCHAR SYBVARCHAR SYBINTN SYBINT1 SYBINT2 SYBINT4 SYBFLT8 SYBDATETIME SYBBIT SYBTEXT SYBNTEXT SYBIMAGE SYBMONEY4 SYBMONEY SYBDATETIME4 SYBREAL SYBBINARY SYBVOID SYBVARBINARY SYBNVARCHAR SYBNUMERIC SYBDECIMAL SYBFLTN SYBMONEYN SYBDATETIMN XSYBCHAR XSYBVARCHAR XSYBNVARCHAR XSYBNCHAR
For a further description look at the freetds documentation.
The size of the column
return [ [{column_name => 'result', column_type => 'SYBVARCHAR', column_size => 30}], [$answer], ];
Returns one row with one column name 'result', width 30.
return [ [{column_name => 'name', column_type => 'SYBVARCHAR', column_size => 30}, {column_name => 'address', column_type => 'SYBVARCHAR', column_size => 30}, {column_name => 'city', column_type => 'SYBVARCHAR', column_size => 30}], [$name[0], $address[0], $city[0]], [$name[1], $address[1], $city[1]], [$name[2], $address[2], $city[2]], ];
Returns three rows with three columns named 'name', 'address' and 'city'.
The tds login structure is recieved into a hash of which a reference is made available to the application
The hash has the following entries:
The name of the computer on which the client runs
The username
The password
The process-id on the client machine
The byteorder for 2-byte integers 2 - little endian 3 - big endian
The byteorder for 4-byte integers 2 - little endian 3 - big endian
The character representation 6 - ascii 7 - ebcdic
The floating point value representation 4 - ieee high 5 - VAX D 10 - ieee low 11 - ND5000
The 8-byte datetime representation 8 - LSB HI (least significant is high) 9 - LSB LO (least significant is low)
?
Type of dialog, only in server to server communication 1 - server to server 2 - remote user 4 - internal rpc
Name of the client application
Name of the server to which the client wants to connet to
Servername and password for server-to-server connections
Requested tds protocol version in dotted quad form. e.g.: 5.0.0.0
Name of the client library
Client library version in dotted quad form
Indicator whether to convert short type forms (e.g. smalldatetime) to their 8-byte respective 0 - don't convert 1 - convert
The 4-byte floating point value representation 12 - ieee high 13 - ieee low 14 - VAX D 15 - ND5000
The 4-byte datetime representation 16 - LSB HI (least significant is high) 17 - LSB LO (least significant is low)
The language for error messages and such
Indicator whether client wants to be informed of language changes by the server 0 - don't notify 1 - notify
Bitmask for negotiated login 0x01 - encrypt 0x02 - challenge 0x04 - labels 0x08 - appdefined
Bulkcopy security bitmask 0x01 - labeled
High availability login request 0x01 - session 0x02 - resume 0x04 - failover server
Id for the ha session, only usefull in combination with halogin
Requested character set
Indicator whether client wants to be informed of character set changes by the server 0 - don't notify 1 - notify
Size of tds packets
Bernd Dulfer <bdulfer@cpan.org>
Thanks to the team developing FreeTDS. Without their work this module would not exist.
I hope I can give something back to their project soon.
Perl www.freetds.org
To install Sybase::TdsServer, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sybase::TdsServer
CPAN shell
perl -MCPAN -e shell install Sybase::TdsServer
For more information on module installation, please visit the detailed CPAN module installation guide.