SqlClrOpt%

Clears an option set by SqlSetOpt%.

Syntax

SqlClrOpt% ( sqlconn%, opt%, optparam$ )

where

sqlconn%

Is a SQL Server connection. The value of sqlconn% is returned by SqlOpen%. When sqlconn% is 0, the specified option is cleared for every active SQL Server connection.

opt%

Is the option to be cleared. Do not enclose opt% in quotation marks. For a list of the options available in DB-Library for Visual Basic, see DB-Library for Visual Basic Options.

optparam$

Is a parameter for an option. You must include optparam$ for all options, whether or not they take parameters. Enclose optparam$ in quotation marks.

If an option does not take a parameter, optparam$ is ignored. If an option does take a parameter, optparam$ is ignored for all options except SQLOFFSET and SQLSTAT.

The SQLOFFSET and SQLSTAT options can have several settings, each with a different parameter. In these cases, SqlClrOpt% needs a valid optparam$ to determine which option parameter to clear.

For a list of the options available in DB-Library for Visual Basic, see DB-Library for Visual Basic Options.

Returns

SUCCEED (1) or FAIL (0).

Remarks

SqlClrOpt% turns off options that have been set with SqlSetOpt%. Although you can set and clear some options directly through Transact-SQL, design your application to use SqlSetOpt% and SqlClrOpt% to set and clear options because SqlSetOpt% and SqlClrOpt% provide a uniform interface for setting and clearing all options. With these functions, your application can also use SqlIsOpt% to check the status of an option.

SqlClrOpt% does not immediately clear the options specified (with the exception of sqlbuffer and sqlnoautofree). Options are cleared when you send the statements in the command buffer to SQL Server by invoking SqlExec%. Also, the results of the command generated by SqlClrOpt% are not returned until the command is transferred to SQL Server. Therefore, design your application to expect the results returned from the command string generated by SqlClrOpt%. If an invalid parameter is specified, it is not detected until the command is sent to SQL Server and the results for that command are returned using SqlResults%.

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 SqlExec% 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 list of the options available in DB-Library for Visual Basic, see DB-Library for Visual Basic Options.

See Also

SqlIsOpt%, SqlSetOpt%; DB-Library for Visual Basic Options