|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
value = %SSC_INIT(dbchannel, [maxcur], [maxcol], [bufsize][, cursors])
Return value
value
This function returns SSQL_NORMAL (success) or SSQL_FAILURE (failure). (i)
Arguments
dbchannel
An internal database channel to be used for a connection. The range is 1 to 100 (Windows) and 1 to 7 (Unix and OpenVMS). (n)
maxcur
(optional) The number of logical cursors to allocate for the channel. The default is 128; the maximum value is database dependent. (n)
maxcol
(optional) The maximum number of columns that can be returned from a query. The default is 254; the maximum value is database dependent. Ideally, this should be set to the largest number of columns of any table within the connected database. (n)
bufsize
(optional) The internal buffer size (in bytes) used for prefetch caching. The default is 32768; the maximum value is database dependent. If set to 0, the size of at least one row will be used for the prefetch buffer. (n)
cursors
(optional) The number of database and statement cursors to allocate for the channel. The default is maxcur; the maximum value is database dependent. (n)
Generally speaking, %SSC_INIT must be the first function call when using SQL Connection. There are two exceptions:
- On OpenVMS, %INIT_SSQL must be called prior to %SSC_INIT.
- If you chain to a program using the SSQL_KEEP_OPEN option for %SSC_CMD, do not use %SSC_INIT in the program you chain to.
%SSC_INIT initializes an SQL Connection session, establishes an internal structure containing information used by %SSC_CONNECT and other routines, and provides a method for defining communication with the low-level structures.
The internal structure is accessed by dbchannel, which is analogous to a channel established in a Synergy DBL OPEN statement. If you specify a previously initialized channel in a call to %SSC_INIT and there is an open connection, the open connection will be closed unless SSQL_KEEP_OPEN is set. When SSQL_KEEP_OPEN is set, %SSC_INIT calls on previously opened channels are ignored. You can have up to 7 concurrently open channels on Unix and OpenVMS and up to 100 concurrently open channels on Windows (to accommodate multi-threading). We recommend using .DEFINE identifiers for channel numbers.
Note the following:
- SQL Connection assigns a logical cursor to each SQL statement. If maxcur is set to a value that is greater than the cursors setting, SQL Connection is able to cache cursors by mapping multiple logical cursors to a single database or statement cursor. Because logical cursors require less memory than database or statement cursors, this improves performance. For optimal performance, set maxcur to the maximum number of SQL statements that will be open (and soft-closed) concurrently.
- If you use %SSC_SCLOSE, the value of cursors should be the maximum concurrent number of open cursors plus a percentage of the soft-closed cursors.
- We recommend that you test with bufsize set to a higher value than the default—for example, 1,048,576. This may improve performance.
- To conserve memory and resources, you can use values that are less than the defaults for maxcur, maxcol, bufsize, and cursors. Reducing the memory used by an application may enable it to support more concurrent users (see Reducing memory and enabling more concurrent users).
See also
Examples
The following is an example of SQL channel initialization using database channel 1 and setting 32 concurrent database and statement cursors, 100 maximum columns, and a 5000-byte prefetch buffer size.
dbchn = 1 ;Use database channel 1 if (%ssc_init(dbchn, 32, 100, 5000)) goto err_exit ;Initializes connection to use 32 concurrent cursors, ; 100 maximum columns, and 5000-byte prefetch buffer if (%ssc_connect(dbchn, user)) goto err_exit
