%SSC_GETEMSG

Get database error message

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
value = %SSC_GETEMSG(dbchannel, msg, len, [row_count][, errno])

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. This argument has a maximum size of 1024. (a)

msg

Returned with the extended error message. (a)

len

Returned with the length of the error message. (n)

row_count

(optional) Returned count of rows affected in the last call to %SSC_EXECUTE, %SSC_MOVE, or %SSC_EXECIO. This count is valid only when value is returned as SSQL_NORMAL. (n)

errno

(optional) Returned with the last database‑specific error number. For Synergy databases, this is the Synergy DBMS error number. (n)

If this number is negative, it’s probably a Vortex API error message (see Vortex API error messages).

Discussion

%SSC_GETEMSG returns Vortex API, SQL OpenNet, socket, database errors, and if you’re using an ODBC database driver (VTX11 or VTX12_SQLNATIVE), ODBC Driver Manager warnings and errors. (It doesn’t, however, return Synergy runtime errors. You’ll need to trap Synergy runtime errors in your program—see Trapping runtime errors—and you’ll need to use Vortex API logging to view socket errors.)

Some databases return multiple message lines for %SSC_GETEMSG. These lines are separated by the null character (%char(0)). For an example of message decoding, see printmsg.dbl. (You’ll find this file in the connect\synsqlx subdirectory of the main Synergy/DE installation directory.)

Examples

The following code segment displays a connection failure error message.

      if (%ssc_connect(dbchn, user))
        goto err_exit
      .
      .
      .
err_exit,
      sts = %ssc_getemsg(dbchn, msg, len)
      if (len)
        writes(1, msg(1,len))
      else
        writes(1, "No error message available.")