The rgetmsg() function

The rgetmsg() function retrieves the error message text for a given error number that is specific to HCL Informix®. The rgetmsg() function can handle a short error number and, therefore, can only handle error numbers in the range of -32768 - +32767. For this reason, use the rgetlmsg() function in all new Informix® ESQL/C code.

Syntax

mint rgetmsg(msgnum, msgstr, lenmsgstr)
   mint  msgnum;
   char *msgstr;
   mint lenmsgstr;

msgnum: The error number. The two-byte parameter restricts error numbers to -32768 - +32767.
msgstr: A pointer to the buffer that receives the message string (the output buffer).
lenmsgstr: The size of the msgstr output buffer. Make this value the size of the largest message that you expect to retrieve.

Usage

Typically SQLCODE (sqlca.sqlcode) contains the error number. You can also retrieve message text for ISAM errors (in sqlca.sqlerrd[1]). The rgetmsg() function uses the Informix® error message files (in the $INFORMIXDIR/msg directory) for error message text. If the message is longer than the size of the buffer that you provide, the function truncates the message to fit.

Important: Informix® ESQL/C supports the rgetmsg() function for compatibility with earlier versions. Some Informix® error numbers currently exceed the range that the short integer, msgnum, supports. The rgetlmsg() function, which supports long integers as error numbers, is recommended over rgetmsg().

If your program passes the value in the SQLCODE variable (or sqlca.sqlcode) directly as msgnum, cast the SQLCODE value as a short data type. The msgnum argument of rgetmsg() and has a short data type while the SQLCODE value has a long data type.

Return codes

0: The conversion was successful.
-1227: Message file not found.
-1228: Message number not found in message file.
-1231: Cannot seek within message file.
-1232: Message buffer too small.

Example

This sample program is in the rgetmsg.ec file in the demo directory.

/*
 * rgetmsg.ec *
 *
 * The following program demonstrates the usage of the rgetmsg() function.
 * It displays an error message after trying to create a table that already
 * exists.
 */
EXEC SQL include sqlca; /* this include is optional */

main()
{
    char errmsg[400];

    printf("\nRGETMSG Sample ESQL Program running.\n\n");
    EXEC SQL connect to 'stores7';

    EXEC SQL create table customer (name char(20));
    if(SQLCODE != 0)
      {
      rgetmsg((short)SQLCODE, errmsg, sizeof(errmsg));
      printf("\nError %d: ", SQLCODE);
      printf(errmsg, sqlca.sqlerrm);
      }
    printf("\nRGETMSG Sample Program over.\n\n");
}

Output

RGETMSG Sample ESQL Program running.


Error -310: Table (informix.customer) already exists in database.

RGETMSG Sample Program over.