TRANSLATE function for RRSAF

The RRSAF TRANSLATE function converts a hexadecimal reason code for a DB2® error into a signed integer SQL code and a printable error message. The SQL code and message text are placed in the SQLCODE and SQLSTATE host variables or related fields of the SQLCA.

Consider the following rules and recommendations about when to use and not use the TRANSLATE function:
  • You cannot call the TRANSLATE function from the Fortran language.
  • Call the TRANSLATE function only after a successful IDENTIFY operation. For errors that occur during SQL or IFI requests, the TRANSLATE function performs automatically.
  • The TRANSLATE function translates codes that begin with X'00F3', but it does not translate RRSAF reason codes that begin with X'00C1'.

If you receive error reason code X'00F30040' (resource unavailable) after an OPEN request, the TRANSLATE function returns the name of the unavailable database object in the last 44 characters of the SQLERRM field.

If the TRANSLATE function does not recognize the error reason code, it returns SQLCODE -924 (SQLSTATE '58006') and places a printable copy of the original DB2 function code and the return and error reason codes in the SQLERRM field. The contents of registers 0 and 15 do not change, unless TRANSLATE fails. In this case, register 0 is set to X'00C12204', and register 15 is set to 200.

The following diagram shows the syntax of the TRANSLATE function.

DSNRLI TRANSLATE function

>>-CALL DSNRLI--(--function, sqlca--+-----------------------------+--)-><
                                    '-,--retcode--+-------------+-'      
                                                  '-,--reascode-'        
Parameters point to the following areas:
function
An 18-byte area that contains the word TRANSLATE followed by nine blanks.
sqlca
The program's SQL communication area (SQLCA).
retcode
A 4-byte area in which RRSAF places the return code.

This parameter is optional. If you do not specify retcode, RRSAF places the return code in register 15 and the reason code in register 0.

reascode
A 4-byte area in which RRSAF places the reason code.

This parameter is optional. If you do not specify reascode, RRSAF places the reason code in register 0.

If you specify reascode, you must also specify retcode.

Example of RRSAF TRANSLATE calls

The following table shows a TRANSLATE call in each language.

Table 1. Examples of RRSAF TRANSLATE calls
Language Call example
Assembler 
CALL  DSNRLI,(XLATFN,SQLCA,RETCODE,REASCODE)
C1 
fnret=dsnrli(&connfn[0], &sqlca, &retcode, &reascode);
COBOL 
CALL  'DSNRLI' USING XLATFN SQLCA RETCODE REASCODE.
PL/I1 
CALL  DSNRLI(XLATFN,SQLCA,RETCODE,REASCODE);
Note:
  1. For C, C++, and PL/I applications, you must include the appropriate compiler directives, because DSNRLI is an assembler language program. These compiler directives are described in the instructions for invoking RRSAF.