%SSC_LARGECOL

Get or put a large binary or char column

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
value = %SSC_LARGECOL(dbchannel, dbcursor, buf, SSQL_LARGEGET|SSQL_LARGEPUT, 
&      col, len[, binary])

Return value

value

This function returns SSQL_NORMAL (success) or SSQL_FAILURE (failure). (i)

Arguments

dbchannel

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

dbcursor

The logical cursor number (within the range from 1 through the maximum number specified by maxcur during %SSC_INIT). The cursor must have been opened by %SSC_OPEN. (n)

buf

The data for the column. For a get, a new string is created for buf. For a put, the data to be put must be passed in buf. (String)

SSQL_LARGEGET | SSQL_LARGEPUT

Get large binary or character data or put large binary or character data. (n)

col

The column position (zero based). (n)

len

For a get, this must be the length of the string returned into the host variable by %SSC_MOVE. For a put, this is the returned length of the put string. (n)

binary

(optional) If passed, this indicates that the column is a binary column, which prevents %SSC_LARGECOL from removing trailing characters. (n)

Discussion

%SSC_LARGECOL puts or gets large binary column (BLOB) or large character column (CLOB) data. In SQL Server, for example, these are VARCHAR(MAX) and VARBINARY(MAX) fields.

This routine takes a Synergy/DE String object and, for a get, creates a new String object. By using the Synergy/DE System.String data type, the object can exceed 65,535 bytes. Remember, though, that to access a String object that’s greater than 65,535 bytes on a 32‑bit system, you must range into the string.

To get large binary column or large character column data, do the following:

1. Specify the SSQL_LARGECOL and SSQL_SELECT options in the %SSC_OPEN call for the statement.
2. Use %SSC_DEFINE to set up an i4 host variable for the column.
3. Call %SSC_MOVE. %SSC_MOVE retrieves the size of the column and saves it in the i4 host variable.
4. After each %SSC_MOVE call, pass the i4 variable as the len argument in the %SSC_LARGECOL call.

To put large binary column or large character column data, do the following:

1. Specify SSQL_NONSEL in the %SSC_OPEN call for the statement. (Don’t specify SSQL_LARGECOL here. You’ll do that in step 3.)
2. Before calling %SSC_EXECUTE, call %SSC_LARGECOL to set up the buffer (buf) that will be bound with %SSC_EXECUTE.
3. Call %SSC_EXECUTE, specifying SSQL_LARGECOL.

Examples

The following code segment demonstrates how to get VARCHAR(MAX) data from a SQL Server database.

record data
       buffer  ,string
       length  ,i4
.
.
.
sqlp = "select bcol from btab where btab_id = :1"
if (sts = %ssc_open(dbchn, cur1, sqlp, SSQL_SELECT, SSQL_STANDARD + SSQL_LARGECOL, 1, id))
  goto err_exit
if (sts = %ssc_define(dbchn, cur1, 1, length)
  if (sts = %ssc_move(dbchn, cur1) != ssql_success)
    goto err_exit
  if (sts = %ssc_largecol(dbchn, cur1, buffer, SSQL_LARGEGET, 0, length))
      ;Where "0" (the col parameter) is the first column of bcol
    goto err_exit
  if (sts = %ssc_sclose(dbchn, cur1))
    goto err_exit