1 Version 4.0 -- 5/1/89 dbmsghandle
______________________________________________________________________
NAME: dbmsghandle
FUNCTION:
Install a user function to handle SQL Server messages.
SYNTAX:
int (*dbmsghandle(handler))()
int (*handler)();
COMMENTS:
o dbmsghandle() installs a message-handler function that you
dbmsghandle Version 4.0 -- 5/1/89 2
______________________________________________________________________
supply. When DB-Library receives a SQL Server error or infor-
mational message, it will call this message handler immedi-
ately. You must install a message handler in order to handle
SQL Server messages properly.
o If the command buffer contains just a single command and that
command provokes a SQL Server message, DB-Library will call the
message handler during dbsqlexec(). If the command buffer con-
tains multiple commands and one of the commands provokes a
SQL Server message, DB-Library will call the message handler
when dbresults() is called for the particular command.
o You can de-install an existing message handler by calling
dbmsghandle() with a NULL parameter. You can also, at any
time, install a new message handler. The new handler will
automatically replace any existing handler.
o See the SYBASE Reference Supplement for a list of SQL Server
messages. In addition, the Transact-SQL PRINT and RAISERROR
3 Version 4.0 -- 5/1/89 dbmsghandle
______________________________________________________________________
commands generate SQL Server messages that dbmsghandle() will
catch.
o Another routine, dberrhandle(), installs an error handler that
DB-Library calls in response to DB-Library errors. If the
application provokes messages from DB-Library and SQL Server
simultaneously, DB-Library calls the SQL Server message handler
before it calls the DB-Library error handler.
o The routines dbsetuserdata() and dbgetuserdata() can be partic-
ularly useful when you need to transfer information between the
message handler and the program code that triggered it. See
the dbsetuserdata() manual page for an example of how to handle
deadlock in this way.
PARAMETERS:
handler - A pointer to the user function that will be called
whenever DB-Library receives an error or informational
dbmsghandle Version 4.0 -- 5/1/89 4
______________________________________________________________________
message from SQL Server. DB-Library calls this function with
eight parameters:
dbproc The affected DBPROCESS.
msgno The current message's number (datatype DBINT).
These numbers are documented in the System Adminis-
tration Guide.
msgstate The current message's error state number (datatype
int). These numbers provide Sybase Customer Sup-
port with information about the context of the
error.
severity The current message's information class or error
severity (datatype int). These numbers are docu-
mented in the System Administration Guide.
msgtext The null-terminated text of the current message
5 Version 4.0 -- 5/1/89 dbmsghandle
______________________________________________________________________
(datatype char *).
srvname The null-terminated name of the server that gen-
erated the message (datatype char *). A server's
name is stored in the srvname column of its sys-
servers system table. It is used in server-to-
server communication; in particular, it's used when
one server logs into another server to perform a
remote procedure call. If the server has no name,
srvname will be of length 0.
procname The null-terminated name of the stored procedure
that generated the message (datatype char *). If
the message was not generated by a stored pro-
cedure, procname will be of length 0.
line The number of the command batch or stored procedure
line that generated the message (datatype DBUSMAL-
LINT). Line numbers start at 1. The line number
dbmsghandle Version 4.0 -- 5/1/89 6
______________________________________________________________________
pertains to the nesting level at which the message
was generated. For instance, if a command batch
executes stored procedure A, which then calls
stored procedure B, and a message is generated at
line 3 of B, then line will be 3.
line will be 0 if there is no line number associ-
ated with the message. Circumstances that could
generate messages without line numbers include a
login error or a remote procedure call (performed
via dbrpcsend()) to a stored procedure that doesn't
exist.
The message handler must return a value of 0 to DB-Library.
The following example shows a typical message handler rou-
tine:
7 Version 4.0 -- 5/1/89 dbmsghandle
______________________________________________________________________
#include <sybfront.h>
#include <sybdb.h>
int msg_handler(dbproc, msgno, msgstate, severity, msgtext,
srvname, procname, line)
DBPROCESS *dbproc;
DBINT msgno;
int msgstate;
int severity;
char *msgtext;
char *srvname;
char *procname;
DBUSMALLINT line;
{
printf ("Msg %ld, Level %d, State %d\n",
dbmsghandle Version 4.0 -- 5/1/89 8
______________________________________________________________________
msgno, severity, msgstate);
if (strlen(srvname) > 0)
printf ("Server '%s', ", srvname);
if (strlen(procname) > 0)
printf ("Procedure '%s', ", procname);
if (line > 0)
printf ("Line %d", line);
printf("\n\t%s\n", msgtext);
return(0);
}
RETURNS:
A pointer to the previously-installed message handler. This may
9 Version 4.0 -- 5/1/89 dbmsghandle
______________________________________________________________________
be NULL.
SEE ALSO:
dberrhandle, dbgetuserdata, dbsetuserdata