%SSC_STRDEF

Define a structure

value = %SSC_STRDEF(dbchannel, cursor, element_num, layout_def, rec)

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 of an open cursor (opened with %SSC_OPEN). This must be in the range 1 through the number specified by maxcur when the database channel was initialized (with %SSC_INIT). (n)

element_num

The number of array elements in each field of rec. (When using element_num, be aware that not all databases support bulk insertions or allow multirow operations. For more information, see %SSC_INIT.) (n)

layout_def

A record that describes the layout of rec. (a)

rec

The record SQL Connection will use at execution time to bind or define data. The layout_def structure describes the layout for this record. (a)

Discussion

%SSC_STRDEF provides an alternative way to bind and define data (see Using variables to map data). It’s generally best to use %SSC_OPEN, %SSC_BIND, %SSC_SQLLINK, or %SSC_DEFINE instead. (For the most part, %SSC_STRDEF has been superseded by support for real arrays in these and other SQL Connection functions.)

There are two instances in which you should use %SSC_STRDEF:

If you need more than 248 variables for a SELECT statement or more than 252 bind variables for a non-SELECT statement. (See Binding data.)
If you are passing many variables to %SSC_DEFINE, %SSC_OPEN, or %SSC_SQLLINK. In this case, using %SSC_STRDEF may improve performance.

When %SSC_STRDEF follows an %SSC_SQLLINK call, it binds variables only for the original SELECT statement (not the linked statement).

If the field type is integer, and the size is greater than 8, the field is mapped as a binary field.

%SSC_STRDEF does not support columns larger than 65,535 bytes.

Examples

.define ELMNT_NUM 5
.include "ssql.def"
record ar_data                         ;Data record structure
      s_dnum       ,[ELMNT_NUM]i4
      s_dnam       ,[ELMNT_NUM]a6
      s_dman       ,[ELMNT_NUM]d4
      s_ddiv       ,[ELMNT_NUM]a10
static record layout_def
      snm_vars       ,d3               ;Number of variables
      group ssql_vars ,[4]a            ;Array of field
                                       ; definitions
        sfld_typ     ,a1               ;Field type (A/D/I)
        sfld_siz     ,d5               ;Field length
        sfld_dec     ,d2               ;Field decimal point length
      endgroup
record row_count, i4
proc
.
.
.
;Build the structure definition
if.NOT. snm_vars
  begin
    snm_vars = 4
    ssql_vars[1].sfld_typ = 'I'
    ssql_vars[1].sfld_siz = 4
    ssql_vars[1].sfld_dec = 0
    ssql_vars[2].sfld_typ = 'A'
    ssql_vars[2].sfld_siz = 6
    ssql_vars[2].sfld_dec = 0
    ssql_vars[3].sfld_typ = 'D'
    ssql_vars[3].sfld_siz = 4
    ssql_vars[3].sfld_dec = 0
    ssql_vars[4].sfld_typ = 'A'
    ssql_vars[4].sfld_siz = 10
    ssql_vars[4].sfld_dec = 0
  end
;Set the SQL statement
sqlp = "SELECT deptnum, deptname, manager, division FROM org"
if (%ssc_open(dbchannel, cur3, sqlp, SSQL_SELECT))
  goto err_exit
;Define the structure for ELMNT_NUM elements in each array
if (%ssc_strdef(dbchannel, cur3, ELMNT_NUM, layout_def, ar_data))
  goto err_exit
;Fetch the five rows at once
sts = %ssc_move(dbchannel, cur3, ELMNT_NUM, row_count)
for ix from 1 thru row_count
  begin
    anum = s_dnum[ix]
    writes(1, anum + s_dnam[ix] + %a(s_dman[ix]) + s_ddiv[ix])
  end
if (%ssc_close(dbchannel, cur3))
  goto err_exit.