%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, cursor[, ...])

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)

cursor

The ID number(s) of one or more open cursors (opened with %SSC_OPEN). Cursor must be in the range 1 through the number specified by maxcur when the database channel was initialized (with %SSC_INIT). (n)

Discussion

%SSC_SCLOSE soft closes one or more cursors opened in %SSC_OPEN. A soft close enables SQL Connection to reuse an associated database cursor. 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 cursor and its resources.
• A table cannot be dropped (that is, deleted) unless all cursors are hard closed.
• If you’ve specified fewer database or statement 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 database cursors (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 cursor 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