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:
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.
- ESQL_LOCKFUNC — param contains the address of your own callback function to affect ESQL behavior when it encounters a resource lock.
- ESQL_LOCKPARM — param contains a parameter value to pass to your resource lock callback function.
- _ESQL_FORWARD_ONLY
—
SELECT statements will be prepared as normal (not scrollable) cursors. This is the default following sqllogin. param is not used.
- ESQL_SCROLLABLE_STATIC — SELECT statements will be prepared as scrollable cursors. param is not used.
NOTES
- The ESQL_LOCKFUNC and ESQL_LOCKPARM options that this function supports affect the behavior of ESQL when a resource lock is encountered during a row fetch. It lets you specify a callback function that can respond to the lock.
- In future releases, other values for option may be supported.
- If you do not call
sqlsetlogoption()
, ESQL waits indefinitely for a locked resource. This is the default behavior.- The interface for your callback function must conform to the following specification:
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.
EXAMPLE
- A common use of the callback function is to display a message that contains the lock owner and the terminal name in response to the lock condition. It then returns with a required value.
- Setting the callback function is on a per-request basis. Each setting is non-retroactive to any pending requests that have already been prepared or executed. For example, suppose you have not yet established a lock callback function; you prepare and open three cursor specifications, and then establish a lock callback function with a call to
sqlsetlogoption()
. If a lock is encountered while fetching rows for any of the previous three cursor requests, the application waits indefinitely for the lock to be released (the default behavior). However, if you prepare and open a fourth cursor specification and a lock is encountered while fetching rows for this request, your callback function is called, because the fourth cursor request was prepared after you established the callback function.- When you call
sqlsetlogoption()
with the ESQL_LOCKFUNC option, it establishes your callback function for all subsequent SQL statements prepared or opened during the session. (This callback function has no effect on previous statements prepared or opened.) Setting ESQL_LOCKFUNC implicitly sets param to the NULL value. (You can use this effect to reset any parameters you may have specified with prior calls tosqlsetlogoption()
using the ESQL_LOCKPARM option.) If you set ESQL_LOCKFUNC specifying a NULL value for thecallback
function address (param
),sqlsetlogoption()
resets the ESQL resource lock response to the default behavior.- When you call
sqlsetlogoption()
with the ESQL_LOCKPARM option, it resets your callback function parameter to the current value ofparam
. The new value lasts for all subsequent SQL statements prepared or opened during the session until either the callback function designation is changed (using the ESQL_LOCKFUNC option) or you specify a new value (using the ESQL_LOCKPARM option). (This parameter setting has no effect on previous statements prepared or opened.) Setting ESQL_LOCKPARM before your initial setting of ESQL_LOCKFUNC is not an error, but has no effect becauseparam
is reset to NULL with each setting of ESQL_LOCKFUNC.In the following example, the function
lock_response_USR()
is thecallback
function thatsqlsetlogoption()
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 tolock_response_USR()
to initiate a lock timeout for the next record lock condition. In this case, ESQL waits for the lock to clear and callslock_response_USR()
up to 50 times (++lockcount) before returning an error. At still another point, it can re-register and pass 2 tolock_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:
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 |