dbsetopt

Sets a SQL Server or DB-Library option.

Syntax

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

where

dbproc

Is the DBPROCESS structure that is the handle for a particular workstation/ 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 DBPROCESS structures.

option

Is the option to be set. See DB-Library Options.

param

Is a parameter for an option. Certain options take parameters. For example, the DBOFFSET option takes as its parameter the construct for which offsets are to be returned:

dbsetopt(dbproc, DBOFFSET, "compute")

The DBBUFFER option takes as its parameter the number of rows to be buffered. A parameter of -1 selects the default (currently 100 rows). The syntax is as follows:

dbsetopt(dbproc, DBBUFFER, "500")

Note The param variable must always be a character string enclosed in quotation marks, even in the case of a numeric value, as in the preceding DBBUFFER example.

If the option takes no parameters, param is ignored and may be NULL.

Returns

SUCCEED or FAIL.

This function fails if param is invalid for one of the DB-Library options. However, an invalid param for a SQL Server option does not cause dbsetopt to fail, because such a parameter does not get validated until the command buffer is sent to SQL Server.

Remarks

Although SQL Server options can be set and cleared directly through SQL, the application should use dbsetopt and dbclropt 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 the dbisopt function to check the status of an option.

This function does not immediately set the options specified. They are not set until the command buffer is sent to SQL Server (by invoking the dbsqlexec function). An additional result for each option set is returned through the dbresults function. (For information about results returned, see "dbresults.")

For a list of each option and its default status, see DB-Library Options.

See Also

dbclropt, dbisopt, dbresults, dbsqlexec; Bulk-Copy Functions, and DB-Library Options