dbmsghandle

Installs a user function to handle SQL Server messages.

Syntax

DBMSGHANDLE_PROC dbmsghandle (DBMSGHANDLE_PROC handler );

where

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 (datatype DBINT). These numbers are documented in the Microsoft SQL Server Administrator's Companion. They are stored online in the sysmessages table, from which they can be selected.

msgstate

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

severity

Is the message information class or error severity (datatype int). These numbers are documented in the Microsoft SQL Server Administrator's Companion.

msgtext

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

srvname

Is the null-terminated name of the server that generated the message (datatype 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 (datatype 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 (datatype DBUSMALLINT). Line numbers start at 1.

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.

line is optional.

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.

Since the message handler is a call-back function, special considerations are required when compiling these functions under the Windows operating system. For more information, see Building Applications.

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

Example

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

 printf("\n\t%s\n", msgtext);
    return(0);
}

See Also

dberrhandle