dbmsghandle

Installs a user function to handle Microsoft® SQL Server™ messages.

Syntax

DBMSGHANDLE_PROC dbmsghandle (DBMSGHANDLE_PROC handler );

Arguments

handler

Is a pointer to the user function that is called whenever DB-Library receives an error or informational message from SQL Server. DB-Library calls this function with these parameters:

dbproc

Is the affected DBPROCESS.

msgno

Is the online message number (data type DBINT). These numbers are documented in Troubleshooting. They are stored online in the sysmessages table, from which they can be selected.

msgstate

Is the message error state number (data type int). These numbers provide information about the context of the error.

severity

Is the message information class or error severity (data type int). These numbers are documented in Troubleshooting.

msgtext

Is the message null-terminated text (data type char *).

srvname

Is the null-terminated name of the server that generated the message (data type char *). A server name is stored in the srvname column of its sysservers system table. srvname is optional.

procname

Is the null-terminated name of the stored procedure that generated the message (data type char *). If the message was not generated by a stored procedure, procname is set to a length of 0. procname is optional.

line

Is the number of the command batch or stored procedure line that generated the message (data type DBUSMALLINT). Line numbers start at 1. line is optional.

The line number 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 the value of line becomes 3.

If no line number is associated with the message, line becomes 0. Circumstances that can generate messages without line numbers include a login error or a call to a remote procedure (through dbrpcsend) to a stored procedure that doesn’t exist.

The message handler must return a value of 0 to DB-Library.

Returns

A pointer to the previously installed message handler. This can be NULL.

Remarks

This function installs a message-handling function that you supply. When DB-Library receives a SQL Server error or informational message, it immediately calls this message handler. You must install a message handler to handle SQL Server messages.

Because the message handler is a callback function, special considerations are required when compiling these functions under the Microsoft Windows® operating system. For more information, see Building Applications.

Note The srvname, procname, and line parameters are optional, and compatibility with earlier versions of SQL Server is maintained through the cdecl parameter declaration convention.

Examples

The following example shows a typical message-handling function:

#include <sqlfront.h>
#include <sqldb.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 ("SQL Server message %ld, state %d, "
        "severity %d: \n\t%s\n", msgno, msgstate, severity, msgtext);
    if (strlen (srvname) != 0)
        printf ("Server '%s', ", srvname);
    if (strlen (procname) != 0)
        printf ("Procedure '%s', ", procname);
    if (line !=0)
        printf ("Line %d", line);

return (0);

}

See Also