sqlsetlogoption() — Set a Session-wide Option

Sets a session-wide option to change subsequent run-time behavior of the ESQL interface.

This function returns 0 if it succeeds in setting the option. If it fails (for example, with an option value out of range), it returns -1:

SYNTAX
int
sqlsetlogoption ( option, param )
  int                option;   /* INPUT */
  unsigned long int    param    /* INPUT */ 

option

The value of ESQL_LOCKFUNC, ESQL_LOCKPARM, ESQL_SCROLLABLE_STATIC, or ESQL_FORWARD_ONLY, as defined in your proesql.h header file. The value of option determines the meaning of param. Other options may be defined in the future.

param

A value that corresponds to the value of option.

NOTES

callback

Your callback function name.

param

The parameter setting in effect for the ESQL_LOCKPARM option at the time the SQL
statement was prepared or opened.

puser

User name of the resource lock owner that ESQL passes.

ptty

The terminal (TTY) name of the resource lock owner that ESQL passes.

The callback function cannot perform any database operations and must return one of the values listed in Table 4–5.

Table 4–5: Lock Callback Function Return Codes  
Return Code
Description
-2
Wait for the lock to clear indefinitely, and make no further callbacks to the function (default behavior).
-1
Continue waiting for the lock to clear, but make another callback to the function.
0
Stop waiting for the lock to clear and return to the application with SQLCODE set to -1 (error).

EXAMPLE

In the following example, the function lock_response_USR() is the callback function that sqlsetlogoption() registers. It accepts a positive or 0 value, and returns the reciprocal negative or 0 value (the return code) to tell ESQL how to respond to the locked record condition. It prints a message indicating the status of the lock response, where 0 indicates an unexpected record lock and 1 or 2 indicates expected record locks. A 0 causes the application to ignore the unexpected lock and continue execution. A 1 (returned as -1) causes the application to wait for lock grant completion only for a limited time, based on the value of a count (lockcount) that is incremented by the function every time it is called back for this condition. A 2 (returned as -2) reverts to the default behavior and the application waits for lock grant completion indefinitely.

The application example shows lock_response_USR() being registered to ignore any unexpected record lock conditions (ESQL_LOCKPARM value is 0). The application can, at another point (not shown), re-register and pass a 1 to lock_response_USR() to initiate a lock timeout for the next record lock condition. In this case, ESQL waits for the lock to clear and calls lock_response_USR() up to 50 times (++lockcount) before returning an error. At still another point, it can re-register and pass 2 to lock_response_USR() to wait for the next record lock condition indefinitely.

The scope of this example is necessarily limited, using ESQL_LOCKPARM to merely pass a reciprocal of the ESQL_LOCKFUNC return condition. A more typical use for ESQL_LOCKPARM might be to pass a pointer to a structure that maintains application context information, including record lock and lock resolution conditions. Then lock_response_USR() could manage the value of lockcount, check the latest record lock status, and return the lock handling condition entirely on its own:

#include "proesql.h"
static SQLRQHDL *sql0 = (SQLRQHDL *) 0;
static long     SQLCODE;
static int      lockcount = 0;
main(argc,argv)
  int argc;
  char *argv[];
{
              .
              .
              .
  sqlsetlogoption(ESQL_LOCKFUNC, (unsigned long int)lock_reponse_USR);
  sqlsetlogoption(ESQL_LOCKPARM, 0); /* Unexpected lock condition */

  sqlcdbind(&SQLCODE, (char *)0);
  sqldynrq(&sql0, "UPDATE customer SET name = NULL 
            WHERE credit-\limit <= 0");
  if (SQLCODE < 0)
  {
    printf("Error executing NULL customer UPDATE\n");
    return;
    }
              .
              .
              .
}
int
lock_response_USR(param, puser, ptty)
  unsigned long int param;
  char          *puser;
  char			         *ptty;
{
  if (param == 0)
    printf("User %s at %s has unexpected record lock: Continuing.\n"
            ,puser ,ptty);
  if (param == 1)
    if (++lockcount > 50)
    {
      printf("User %s at %s record lock wait timed out: Error.\n" 
              ,puser ,ptty)
      param = 0;
      lockcount = 0;
    }
  if (param != 0 && lockcount <= 50)
    printf("User %s at %s has record locked: Waiting.\n" ,puser ,ptty);
  return(-(param));
} 

SEE ALSO

sqldynposfetch() — Fetch Row of Dynamic Open Cursor for positioned fetches, sqldynprep() — Prepare a Dynamic SQL Statement for preparing SQL statements


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095