TRANSLATE function for CAF

The TRANSLATE function converts a Db2 hexadecimal error reason code from a failed OPEN request into an SQL error code and printable error message text. Db2 places the information into the SQLCODE and SQLSTATE host variables or related fields of the SQLCA of the caller.

The Db2 error reason code that is converted is read from register 0. The TRANSLATE function does not change the contents of registers 0 and 15, unless the TRANSLATE request fails; in that case, register 0 is set to X'C10205' and register 15 is set to 200.

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.
  • The TRANSLATE function is useful only if you used an explicit CONNECT call before an OPEN request that fails. For errors that occur during SQL or IFI requests, the TRANSLATE function performs automatically.
  • The TRANSLATE function can translate those codes that begin with X'00F3', but it does not translate CAF 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 following diagram shows the syntax for the TRANSLATE function.

DSNALI TRANSLATE function

Read syntax diagramSkip visual syntax diagramCALL DSNALI(function, sqlca ,retcode,reascode )
Parameters point to the following areas:
function
A 12-byte area the contains the word TRANSLATE followed by three blanks.
sqlca
The program's SQL communication area (SQLCA).
retcode
A 4-byte area in which CAF places the return code.

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

reascode
A 4-byte area in which CAF places a reason code.

This field is optional. If you do not specify reascode, CAF places the reason code in register 0. If you specify reascode, you must also specify retcode.

Examples of CAF TRANSLATE calls

The following table shows a TRANSLATE call in each language.
Table 1. Examples of CAF TRANSLATE calls
Language Call example
Assembler 
CALL  DSNALI,(FUNCTN,SQLCA,RETCODE, REASCODE)
C1 
fnret=dsnali(&functn[0], &sqlca, &retcode, &reascode);
COBOL 
CALL  'DSNALI' USING FUNCTN SQLCA RETCODE REASCODE.
PL/I1 
CALL  DSNALI(FUNCTN,SQLCA,RETCODE, REASCODE);
Note:
  • For C and PL/I applications, you must include the appropriate compiler directives, because DSNALI is an assembler language program. These compiler directives are described in the instructions for invoking CAF.