%SSC_SCLOSE

Soft close one or more open cursors

WTSupported in traditional Synergy on Windows

WNSupported in Synergy .NET on Windows

USupported on UNIX

VSupported on OpenVMS

value = %SSC_SCLOSE(dbchannel, dbcursor[, ...])

Return value

value

This function returns SSQL_NORMAL (success). (i)

Arguments

dbchannel

An internal database channel previously initialized using %SSC_INIT and connected by %SSC_CONNECT. (n)

dbcursor

One or more logical cursor numbers within the range from 1 through the maximum number specified by maxcur during %SSC_INIT. These cursors must have been opened by %SSC_OPEN. (n)

Discussion

%SSC_SCLOSE soft closes one or more logical cursors opened in %SSC_OPEN. A soft close enables SQL Connection to reuse the associated database cursor, if there is one. For information on closing and reusing cursors, see Closing cursors and Reusing cursors. Note the following:

• Use %SSC_SCLOSE only when you will reuse the cursor. Otherwise, use %SSC_CLOSE to free dbcursor and its resources.
• A table cannot be dropped (that is, deleted) unless all cursors are hard closed.
• If you’ve specified fewer database cursors than logical cursors (with %SSC_INIT), SQL Connection may hard close cursors that have been soft closed with %SSC_SCLOSE. However, when a cursor is reused with %SSC_OPEN, the result is the same as if the cursor had not been hard closed. In this way, SQL Connection manages a cache of cursors for you.
• For SQL Server, %SSC_SCLOSE frees cursor resources, including locks, for cursors for SELECT statements.
• The database cache may reach its limit, which will result in a severe decrease in performance if you do not hard close cursors.
• If you use ^VARARGARRAY, note that dbcursor is the last declared argument for this routine.

Examples

The following code segment shows re-use of a soft closed cursor (the SELECT statement isn’t re-parsed).

sqlp = "SELECT name, id, type FROM objects "
  &      " WHERE name = :1 AND type = :2"
do forever
          begin
    call get_name_and_type        ;Set the search name and type
    if (sts = %ssc_open(dbchn, cur1, sqlp, SSQL_SELECT,
  &                     SSQL_STANDARD, 2, spec, stype))
      goto err_exit
    if (%ssc_define(dbchn, cur1, 3, name, id, type))
      goto err_exit
    sts = %ssc_move(dbchn, cur1, 1)
    if (sts.eq.SSQL_NOMORE) then
      exitloop
    else if (sts.eq.SSQL_FAILURE)
      goto err_exit
    call do_processing
    if (sts = %ssc_slose(dbchn, cur1))
      goto err_exit
  end