%SSC_INIT

Initialize a database channel

value = %SSC_INIT(dbchannel, [maxcur], [maxcol], [bufsize][, dbcursor])

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. (n)

maxcol

(optional) The maximum number of columns that can be returned from a query. The default is 254. (n)

bufsize

(optional) The internal buffer size (in bytes) used for prefetch caching. The default is 32768. (n)

dbcursor

(optional) The number of database cursors to allocate for the channel. The default is maxcur. (n)

Discussion

%SSC_INIT must be the first function call when using SQL Connection, except

on OpenVMS where %INIT_SSQL must be called prior to %SSC_INIT.
in a program you chain to when using the SSQL_KEEP_OPEN option for %SSC_CMD. In this case, 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. See Database connections for more information, and note the following:

You can have up to seven 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.
SQL Connection assigns a logical cursor to each SQL Statement. If maxcur is set to a value that is greater than the dbcursor setting, SQL Connection is able to cache cursors by mapping multiple logical cursors to a single database cursor. Because logical cursors require less memory than database 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 dbcursor should be the maximum concurrent number of open cursors plus a percentage of the soft-closed cursors.
Ideally, maxcol should be set to the largest number of columns of any table within the connected database.
The maximum values for maxcur, maxcol, bufsize, and dbcursor are database dependent.
We recommend that you test with bufsize set to a higher value than the default—for example, 65536. This may improve performance.
If 0 is specified for bufsize, the size of at least one row will be used for the prefetch buffer.
To conserve memory and resources, you can use values that are less than the defaults for maxcur, maxcol, bufsize, and dbcursor. Note that reducing the memory used by an application may enable it to support more concurrent users (see Reducing memory and enabling more concurrent users).
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.

Examples

The following is an example of SQL channel initialization using database channel 1 and setting 32 concurrent 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