Describe an SQL statement

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
value = %SSC_DESCSQL(dbchannel, dbcursor, numvars, description)

Return value


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



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


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)


The maximum number of variables that can be returned in the description array. (n)


A returned record description. See the ssc_desc record in Examples below for the record layout. (a)


This routine provides a way of finding out the number of variables you should define with an %SSC_DEFINE, and describes an SQL statement associated with the specified cursor.

With %SSC_DEFINE you must define the same number of variables as are defined by the number of SELECT columns, although you may not always know this number ahead of time. For example, when you use a SELECT * statement, %SSC_DESCSQL can determine the number of columns returned.

If the number of variables specified in the description argument is less than the number of columns defined in the SELECT statement, only the number of specified variables will be loaded.


The data fields returned are the returned values from the database and do not always make sense. For example, Oracle won’t always return information in var_len for an integer that is 1, 2, 4, or 8 bytes.


The following example shows an SQL statement description layout in which var_descs is the layout of each column description.

.define MX_VARS     ,255
record ssc_desc
  var_nmbr          ,d3          ;Number of variables used
  group var_descs   ,[MX_VARS] a
    var_name        ,a30
    var_type        ,d2          ;Possible var_types are the following:
    var_len         ,d5          ;   0-integer
    var_dec         ,d2          ;   1-char
  end group                      ;   2-number
                                 ;   3-null-terminated char
                                 ;   4-packed decimal
                                 ;   5-zoned decimal
                                 ;   8-float
                                 ;   9-varchar
                                 ;   10-large binary object (blob)
                                 ;   11-large character object (clob)
                                 ;   12-datetime
                                 ;   80-varlen blob
                                 ;   81-Unicode char UTF-8 format
                                 ;   82-Unicode char UTF-16 format
                                 ;   83-Unicode char UCS-2 format
                                 ;   84-Unicode char UCS-4 format
                                 ;   85-Unicode LOB UTF-8 format
                                 ;   86-Unicode varchar UTF-8 format
                                 ;   87-Unicode varchar UTF-16 format
                                 ;   88-Unicode varchar UCS-2 format
                                 ;   89-Unicode varchar UCS-4 format
                                 ;   99-binary
                                 ; If var_type is an integer, var_len
                                 ; will always return the value of 10
                             ;Get SQL variable descriptions
sqlstm = "SELECT * FROM org WHERE deptnum = :1"
if (%ssc_open(dbchn, cur2, sqlstm, SSQL_SELECT,
  &           SSQL_STANDARD, 1, deptnum))
  goto err_exit
                             ;Open cursor #3 with an SQL SELECT statement 
if (%ssc_descsql(dbchn, cur2, MX_VARS, ssc_desc))
  goto err_exit
for ix from 1 thru var_nmbr  ;Display them
    sqlvar = var_descs(ix)
    display(1, "COL #", %string(ix), ": ",
  &            var_name, %string(var_type), " ",
  &            %string(var_len))
    writes(1, "COL #", %string(ix), ": ", var_name, %string(var_type),
  &        " ", %string(var_len), ".", %string(var_dec))
;Define for maximum variables and control actual number of variables
; with var_nmbr
  &             var8,var9,var10,...varn)