dbclropt

Clears an option set by dbsetopt.

Syntax

RETCODE dbclropt (
PDBPROCESS dbproc,
INT option,
LPCSTR param );

Arguments

dbproc

Is the DBPROCESS structure that is the handle for a particular workstation/ Microsoft® SQL Server™ process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server. If dbproc is NULL, the option is set for all active and future DBPROCESS structures.

option

Is the option to be turned off.

param

Is the option parameter. Certain options take parameters. If an option does not take a parameter, param is ignored. If an option does take a parameter, param is ignored for all options except DBOFFSET and DBSTAT.

The DBOFFSET and DBSTAT options can have several settings, each with a different parameter. In these cases, dbclropt needs a valid param to determine which option parameter to clear.

For more information about a list of options that take parameters, see DB-Library Options.

If an invalid parameter is specified for one of the SQL Server options, it will not be discovered until the command is sent to SQL Server. The dbsqlexec or dbsqlsend calls will fail and DB-Library will invoke the user-installed message handler. If an invalid parameter is specified for one of the DB-Library options (DBBUFFER or DBTEXTLIMIT), dbclropt itself will fail.

Returns

SUCCEED or FAIL.

Remarks

This function clears SQL Server and DB-Library options that have been set with dbsetopt. Although SQL Server options can be set and cleared directly through Transact-SQL, use dbsetopt and dbclropt in an application to set and clear options. This provides a uniform interface for setting both SQL Server and DB-Library options. It also allows the application to use dbisopt to check the status of an option.

The dbclropt function does not immediately clear the options specified. With the exception of DBBUFFER and DBNOAUTOFREE, options are not cleared until the command buffer is sent to SQL Server (by invoking the dbsqlexec function). An additional result is returned by using dbresults. For information about results returned, see dbresults.

Note that the command string generated by this function is not immediately sent to SQL Server. Instead, it is buffered within DB-Library and sent the next time dbsqlexec is invoked. Therefore, any options requested by this function do not go into effect until then. Also, the results of the command generated by this function are not returned until the command is transferred to SQL Server. The application should be expecting the results returned from the command string generated by this function.

For a complete list of options, see DB-Library Options.

See Also