Share via

SQLSETPROP( ) Function

  • Article

Specifies settings for an active connection.

SQLSETPROP(nConnectionHandle, cSetting [, eExpression])

Return Values

Numeric

Parameters

  • nConnectionHandle
    Specifies the connection handle to the data source returned by SQLCONNECT( ).
  • cSetting
    Specifies the setting. The following table lists the values for cSetting.
    Setting Description
    Asynchronous Specifies whether result sets are returned synchronously (false (.F.), the default), or asynchronously (true (.T.)).
    Read-Write.
    BatchMode Specifies whether SQLEXEC( ) returns result sets all at once (true (.T.), the default), or individually with SQLMORERESULTS( ) (false (.F.)).
    Read-Write.
    ConnectBusy Contains true (.T.) if a shared connection is busy; otherwise contains false (.F.).
    Read-Only.
    ConnectString The login connection string.
    Read-Only.
    ConnectTimeOut Specifies the time to wait (in seconds) before returning a connection time-out error. If you specify 0, the wait is indefinite and a time-out error is never returned. ConnectTimeOut can be 0 to 600. The default is 15.
    Read-Write.
    DataSource The name of the data source as defined in the ODBC.INI file.
    Read-Write.
    DispLogin Contains a numeric value that determines when the ODBC Login dialog box is displayed. DispLogin may assume the following values:

    1 or DB_PROMPTCOMPLETE (from FOXPRO.H).1 is the default.

    2 or DB_PROMPTALWAYS (from FOXPRO.H).

    3 or DB_PROMPTNEVER (from FOXPRO.H).

    If 1 or DB_PROMPTCOMPLETE is specified, Visual FoxPro displays the ODBC Login dialog box only if any required information is missing.

    If 2 or DB_PROMPTALWAYS is specified, the ODBC Login dialog box is always displayed, making it possible for you to change settings before connecting.

    If 3 or DB_PROMPTNEVER is specified, the ODBC Login dialog box isn't displayed and Visual FoxPro generates an error if the required login information isn't available.
    Read-Write.
    DispWarnings Specifies if error messages are displayed (true (.T.)) or are not displayed (false (.F.), the default).
    Read-Write.
    IdleTimeout The idle timeout interval in seconds. Active connections are deactivated after the specified time interval. The default value is 0 (wait indefinitely).
    Read-Write.
    ODBChdbc The internal ODBC connection handle, which may be used by external library files (FLL files) to call ODBC.
    Read-Only.
    ODBChstmt The internal ODBC statement handle, which may be used by external library files (FLL files) to call ODBC.
    Read-Only.
    PacketSize The size of the network packet used by the connection. Adjusting this value can improve performance. The default value is 4096 bytes (4K).
    Read-Write
    Password The connection password.
    Read-Only.
    QueryTimeOut Specifies the time to wait (in seconds) before returning a general time-out error. If you specify 0 (the default), the wait is indefinite and a time-out error is never returned. QueryTimeOut can be 0 to 600.
    Read-Write.
    Transactions Contains a numeric value that determines how the connection manages transactions on the remote table. Transactions may assume the following values:

    1 or DB_TRANSAUTO (from FOXPRO.H).1 is the default. Transaction processing for the remote table is automatically handled.

    2 or DB_TRANSMANUAL (from FOXPRO.H). Transaction processing is handled manually through SQLCOMMIT( ) and SQLROLLBACK( ).
    Read-Write.
    UserId The user identification. Read-Only.
    WaitTime The amount of time in milliseconds that elapses before Visual FoxPro checks if the SQL statement has completed executing. The default is 100 milliseconds.
    Read-Write.
  • eExpression
    Specifies the value for the setting you designate with cSetting. If you omit eExpression, the default value is restored for the setting.

Remarks

SQLSETPROP( ) returns 1 if it is successful; otherwise, it returns – 1 if a connection level error occurs or – 2 if an environment level error occurs.

Use SQLSETPROP( ) to specify settings at the connection level. To specify Visual FoxPro default settings at the environment level, include 0 as the connection handle.

The ConnectTimeOut option can be set only at the Visual FoxPro level and has no equivalent at the connection level. You can set all other options at either the connection or the Visual FoxPro level. Each option set at the Visual FoxPro level serves as a default value for subsequent connections.

Use SQLGETPROP( ) to return the current value for a specified setting.

Note   The ODBC login dialog must be disabled to support SQL pass through with Microsoft Transaction Server. Use SQLSETPROP(cConnectionHandle, 'DispLogin', 3) to disable the ODBC login dialog. The ODBC login dialog can also be disabled in the Connection Designer.

Example

SQLSETPROP( ) is used to set the packet size for the current connection.

* Clear environment
CLOSE ALL
CLEAR ALL
CLEAR

* Display the Select Connection or Datasource dialog box
* to choose a connection
nHandle=SQLCONNECT()

* Test connection, report results
IF nHandle > 0
   * Set PacketSize
   nSet=SQLSETPROP(nHandle, "PacketSize", 2048 )
   * Test setting and display results
   IF nSet > 0
      =MESSAGEBOX("PacketSize was set to 2048",0,"Connection Results")
   ELSE
      =MESSAGEBOX("Error setting PacketSize",0,"Connection Results")
   ENDIF
ELSE
   =MESSAGEBOX("No Connection",0,"Connection Results")
ENDIF
=SQLDISCONNECT(nHandle)

See Also

AERROR( ) | SQLGETPROP( ) | Connection Designer