Map a database‑specific error code

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
value = %SSC_MAPMSG(dbchannel, mapfile, dfltcode, mapcode)

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 filename (without filename extension) that contains the error code mapping. (a)


The code to return if no match is found in the map file. (n)


Returned with the mapped code. (n)


%SSC_MAPMSG maps a database‑specific error code to a generic error code.

The text file that mapfile is set to must contain two numbers in each line: the first number is the database‑specific error code (most are negative), and the second number is the matching generic error code that you want returned. SQL Connection opens the error code mapping file once for each open database channel and appends the xx filename extension to the name of the mapfile text file, where xx is the database ID from the last %SSC_GETDBID function call.

When a status value of SSQL_FAILURE is returned, you can call this function to get the map message code. You can then process general error messages in your own error processing system.


The following code segment demonstrates how to map a database‑specific error code to an application generic error code using an Oracle database (with a mapfile of my_map.0).

mapfile = "my_map"
sts = %ssc_getemsg(dbchn, msg, len,, ecode)
sts = %ssc_mapmsg(dbchn, mapfile, ecode, map_code)
call do_case_map_code

The contents of the first line of the file if it mapped Oracle error –2 to a returned error 3 would be

–2 3