NAME

Sybase::TdsServer - A simple module to create a tds-server (like Sybase or freetds)

SYNOPSIS

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);

DESCRIPTION

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.

REQUIREMENTS

None, so far.

METHODS

new - the constructor

Parameters:

Servername

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.

Connect Handler

A reference to a subroutine that will be called whenever a client connects to the server. Parameters for the connect handler are:

connection handle: a handle identifying this connection.
user: the login provided by the client
password: the password provided by the client

Disconnect Handler

A reference to a subroutine that will be called whenever a client disconnects from the server. Parameters for the disconnect handler are:

connection handle: a handle identifying this connection.

Language Handler

A reference to a subroutine that will be called whenever a client sends data to the server. Parameters for the language handler are:

connection handle: a handle identifying this connection.
text: the text that was sent by the client

set_handler - setting event handling routines

Parameters:

type of handler

type of handler is one of the following:

capability
optioncmd
rpc

handler

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.

optioncmd

Will be called whenever a client sends an OPTIONCMD token to the server.
Parameters for the optioncmd handler are:

command: 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
option: The decimal value of the option, values range from 0 to 38.
argument length: The length of the argument for the option.
argument: The argument for the option.

rpc

Will be called whenever a client sends an rpc request.
FIXME: not implemented yet!
Parameters for the rpc handler are:

command: The command

capability

Will be called whenever capability requests come from the client.
Parameters for the capability handler are:

capabilities requested
capabilities offered

Both are binary values constaining one bit for each capability

Example:

$s->set_handler('optioncmd' => \&option_handler);

run - running the server

Parameters:

none

Example:

$s->run;

disconnect - disconnects a client forcibly

Parameters:

connect handle

Example:

$s->disconnect($connect_handle);

shutdown - shuts the server down.

The program will continue execution after the run.

Parameters:

none

Example:

$s->shutdown;

send_header - sends header information for a resultset

Parameters:

Connection Handle.

Reference to an array containing header information.

See 'Handlers' for more on header information.

Example:

$s->send_header($conn_handle, 
                [{ column_name => 'result', 
                   column_type => 'SYBVARCHAR', 
                   column_size => 30
                }] 
               );

send_row - sends a row of the resultset

Parameters:

Connection Handle.

Reference to an array containing row data.

See 'Handlers' for more on row data.

Example:

$s->send_row($conn_handle, ['data1', 'data2', 'data3'] );

send_done - sends a done token to the client

Parameters:

Connection Handle.

Status to be sent in done token.

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.

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

Number of rows.

Example:

$s->send_done($conn_handle, 0x00, 0, 1);

send_eed - sends a eed token to the client

Parameters:

Connection Handle.

Message Nr.

Class

Class is the severity of the error.

Status of the current transaction.

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

Message

The message text.

Servername

Procedurename (optional)

Linenr. (optional)

Example:

$s->send_eed($conn_handle, 1234, 0, 0, 'error message', 'this_server');

HANDLERS

The communication between the module and the application works with handlers (callbacks).

You have to provide the following handlers:

Connect Handler

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.

Disconnect Handler

This handler is called when a client disconnects from the server.

It gives the application the opportunity to clean up on a connection.

Language Handler

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:

column_name

The column name.

column_type

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.

column_size

The size of the column

Examples:

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

Structures

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:

hostname: The name of the computer on which the client runs
username: The username
password: The password
hostprocess: The process-id on the client machine
byteorder2: The byteorder for 2-byte integers 2 - little endian 3 - big endian
byteorder4: The byteorder for 4-byte integers 2 - little endian 3 - big endian
ascii_ebcdic: The character representation 6 - ascii 7 - ebcdic
float_repesentation: The floating point value representation 4 - ieee high 5 - VAX D 10 - ieee low 11 - ND5000
datetime_representation: The 8-byte datetime representation 8 - LSB HI (least significant is high) 9 - LSB LO (least significant is low)
interfacespare: ?
type: Type of dialog, only in server to server communication 1 - server to server 2 - remote user 4 - internal rpc
appname: Name of the client application
servername: Name of the server to which the client wants to connet to
remote_password: Servername and password for server-to-server connections
tds_version: Requested tds protocol version in dotted quad form. e.g.: 5.0.0.0
progname: Name of the client library
prog_version: Client library version in dotted quad form
noshort: Indicator whether to convert short type forms (e.g. smalldatetime) to their 8-byte respective 0 - don't convert 1 - convert
float4_representation: The 4-byte floating point value representation 12 - ieee high 13 - ieee low 14 - VAX D 15 - ND5000
datetime4_representation: The 4-byte datetime representation 16 - LSB HI (least significant is high) 17 - LSB LO (least significant is low)
language: The language for error messages and such
setlang: Indicator whether client wants to be informed of language changes by the server 0 - don't notify 1 - notify
seclogin: Bitmask for negotiated login 0x01 - encrypt 0x02 - challenge 0x04 - labels 0x08 - appdefined
secbulk: Bulkcopy security bitmask 0x01 - labeled
halogin: High availability login request 0x01 - session 0x02 - resume 0x04 - failover server
ha_session_id: Id for the ha session, only usefull in combination with halogin
charset: Requested character set
setcharset: Indicator whether client wants to be informed of character set changes by the server 0 - don't notify 1 - notify
packetsize: Size of tds packets

AUTHOR

Bernd Dulfer <bdulfer@cpan.org>

ACKNOWLEGDEMENTS

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

REQUIREMENTS

METHODS

new - the constructor

set_handler - setting event handling routines

run - running the server

disconnect - disconnects a client forcibly

shutdown - shuts the server down.

send_header - sends header information for a resultset

send_row - sends a row of the resultset

send_done - sends a done token to the client

send_eed - sends a eed token to the client

HANDLERS

Connect Handler

Disconnect Handler

Language Handler

Examples:

Structures

login hash

AUTHOR

ACKNOWLEGDEMENTS

SEE ALSO

Module Install Instructions