The rgetlmsg() function

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 HCL OneDB.

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 HCL OneDB error message files (in the $ONEDB_HOME/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

/*
 * 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.