The rgetlmsg() function

The rgetlmsg() function retrieves the corresponding error message for a given error number that is specific to HCL Informix®. The rgetlmsg() function allows for error numbers in the range of a long integer.

Syntax

mint rgetlmsg(msgnum, msgstr, lenmsgstr, msglen)
   int4  msgnum;
   char *msgstr;
   mint lenmsgstr;
   mint *msglen;

msgnum: The error number. The four-byte parameter provides for the full range of error numbers that are specific to Informix®.
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.
msglen: A pointer to the mint that contains the actual length of the message that rgetlmsg() returns.

Usage

The msgnum error number is typically the value of SQLCODE (or sqlca.sqlcode). You can also retrieve message text for ISAM errors (in sqlca.sqlerrd[1]). The rgetlmsg() function uses the Informix® error message files (in the $INFORMIXDIR/msg directory) for error message text.

The rgetlmsg() function returns the actual size of the message that you request in the fourth parameter, msglen. You can use this value to adjust the size of the message area if it is too small. If the returned message is longer than the buffer that you provide, the function truncates the message. You can also use the msglen value to display only that portion of the msgstr message buffer that contains error text.

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 rgetlmsg.ec file in the demo directory.

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

main()
{
    mint msg_len;
    char errmsg[400];

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

    EXEC SQL create table customer (name char(20));

   if(SQLCODE != 0)
      {
      rgetlmsg(SQLCODE, errmsg, sizeof(errmsg), &msg_len); 
      printf("\nError %d: ", SQLCODE);
      printf(errmsg, sqlca.sqlerrm);
      }
   printf("\nRGETLMSG Sample Program over.\n\n");
}

This example uses the error message parameter in sqlca.sqlerrm to display the name of the table. This use of sqlca.sqlerrm is valid because the error message contains a format parameter that printf() recognizes. If the error message did not contain the format parameter, no error would result.

Output

RGETLMSG Sample ESQL Program running.


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

RGETLMSG Sample Program over.