%SSC_STRDEF

Define a structure

value = %SSC_STRDEF(dbchannel, dbcursor, 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)

dbcursor

The logical cursor number. This must be between 1 and the maximum number specified by maxcur during %SSC_INIT (inclusive). The cursor must have been opened by %SSC_OPEN. (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.) However, 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.)
you are passing many variables to %SSC_DEFINE, %SSC_OPEN, or %SSC_SQLLINK. In this case, using %SSC_STRDEF may improve performance.

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

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.