home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbmsghandle.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  7.4 KB  |  199 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89              dbmsghandle
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbmsghandle
  6.  
  7.   FUNCTION:
  8.        Install a user function to handle SQL Server messages.
  9.  
  10.   SYNTAX:
  11.        int (*dbmsghandle(handler))()
  12.  
  13.        int       (*handler)();
  14.  
  15.   COMMENTS:
  16.  
  17.        o dbmsghandle() installs  a  message-handler  function  that  you
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbmsghandle             Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.          supply.  When DB-Library receives a SQL Server error or  infor-
  27.          mational  message,  it  will  call this message handler immedi-
  28.          ately.  You must install a message handler in order  to  handle
  29.          SQL Server messages properly.
  30.  
  31.        o If the command buffer contains just a single command  and  that
  32.          command provokes a SQL Server message, DB-Library will call the
  33.          message handler during dbsqlexec().  If the command buffer con-
  34.          tains  multiple  commands  and  one  of the commands provokes a
  35.          SQL Server message, DB-Library will call  the  message  handler
  36.          when dbresults() is called for the particular command.
  37.        o You can de-install  an  existing  message  handler  by  calling
  38.          dbmsghandle()  with  a  NULL  parameter.   You can also, at any
  39.          time, install a new message  handler.   The  new  handler  will
  40.          automatically replace any existing handler.
  41.  
  42.        o See the SYBASE Reference Supplement for a  list  of  SQL Server
  43.          messages.   In  addition,  the Transact-SQL PRINT and RAISERROR
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89              dbmsghandle
  47.   ______________________________________________________________________
  48.          commands generate SQL Server messages that  dbmsghandle()  will
  49.          catch.
  50.  
  51.        o Another routine, dberrhandle(), installs an error handler  that
  52.          DB-Library  calls  in  response  to  DB-Library errors.  If the
  53.          application provokes messages from  DB-Library  and  SQL Server
  54.          simultaneously, DB-Library calls the SQL Server message handler
  55.          before it calls the DB-Library error handler.
  56.        o The routines dbsetuserdata() and dbgetuserdata() can be partic-
  57.          ularly useful when you need to transfer information between the
  58.          message handler and the program code that  triggered  it.   See
  59.          the dbsetuserdata() manual page for an example of how to handle
  60.          deadlock in this way.
  61.  
  62.   PARAMETERS:
  63.        handler -  A pointer to the user function  that  will  be  called
  64.            whenever   DB-Library  receives  an  error  or  informational
  65.  
  66.  
  67.  
  68.   dbmsghandle             Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.            message from SQL Server.  DB-Library calls this function with
  71.            eight parameters:
  72.  
  73.            dbproc    The affected DBPROCESS.
  74.  
  75.            msgno     The  current  message's  number  (datatype  DBINT).
  76.                      These numbers are documented in the System Adminis-
  77.                      tration Guide.
  78.            msgstate  The current message's error state number  (datatype
  79.                      int).   These  numbers provide Sybase Customer Sup-
  80.                      port with information  about  the  context  of  the
  81.                      error.
  82.  
  83.            severity  The current message's information  class  or  error
  84.                      severity  (datatype  int).  These numbers are docu-
  85.                      mented in the System Administration Guide.
  86.            msgtext   The null-terminated text  of  the  current  message
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89              dbmsghandle
  91.   ______________________________________________________________________
  92.                      (datatype char *).
  93.  
  94.            srvname   The null-terminated name of the  server  that  gen-
  95.                      erated  the  message (datatype char *).  A server's
  96.                      name is stored in the srvname column  of  its  sys-
  97.                      servers  system  table.   It  is used in server-to-
  98.                      server communication; in particular, it's used when
  99.                      one  server  logs  into another server to perform a
  100.                      remote procedure call.  If the server has no  name,
  101.                      srvname will be of length 0.
  102.            procname  The null-terminated name of  the  stored  procedure
  103.                      that  generated  the message (datatype char *).  If
  104.                      the message was not  generated  by  a  stored  pro-
  105.                      cedure, procname will be of length 0.
  106.  
  107.            line      The number of the command batch or stored procedure
  108.                      line  that generated the message (datatype DBUSMAL-
  109.                      LINT).  Line numbers start at 1.  The  line  number
  110.  
  111.  
  112.   dbmsghandle             Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.                      pertains to the nesting level at which the  message
  115.                      was  generated.   For  instance, if a command batch
  116.                      executes  stored  procedure  A,  which  then  calls
  117.                      stored  procedure  B, and a message is generated at
  118.                      line 3 of B, then line will be 3.
  119.  
  120.                      line will be 0 if there is no line  number  associ-
  121.                      ated  with  the  message.  Circumstances that could
  122.                      generate messages without line  numbers  include  a
  123.                      login  error  or a remote procedure call (performed
  124.                      via dbrpcsend()) to a stored procedure that doesn't
  125.                      exist.
  126.  
  127.            The message handler must return a value of 0 to DB-Library.
  128.  
  129.            The following example shows a typical  message  handler  rou-
  130.            tine:
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89              dbmsghandle
  135.   ______________________________________________________________________
  136.            #include <sybfront.h>
  137.            #include <sybdb.h>
  138.  
  139.            int msg_handler(dbproc, msgno, msgstate, severity, msgtext,
  140.                            srvname, procname, line)
  141.  
  142.            DBPROCESS       *dbproc;
  143.            DBINT           msgno;
  144.            int             msgstate;
  145.            int             severity;
  146.            char            *msgtext;
  147.            char            *srvname;
  148.            char            *procname;
  149.            DBUSMALLINT     line;
  150.  
  151.            {
  152.                printf ("Msg %ld, Level %d, State %d\n",
  153.  
  154.  
  155.  
  156.   dbmsghandle             Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.                        msgno, severity, msgstate);
  159.  
  160.                if (strlen(srvname) > 0)
  161.                    printf ("Server '%s', ", srvname);
  162.                if (strlen(procname) > 0)
  163.                    printf ("Procedure '%s', ", procname);
  164.                if (line > 0)
  165.                    printf ("Line %d", line);
  166.  
  167.                printf("\n\t%s\n", msgtext);
  168.  
  169.                return(0);
  170.            }
  171.  
  172.  
  173.   RETURNS:
  174.        A pointer to the previously-installed message handler.  This  may
  175.  
  176.  
  177.  
  178.   9                       Version 4.0 -- 5/1/89              dbmsghandle
  179.   ______________________________________________________________________
  180.        be NULL.
  181.  
  182.   SEE ALSO:
  183.        dberrhandle, dbgetuserdata, dbsetuserdata
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.