Informix-ESQL/C Programmer's Manual

Informix-ESQL/C Programmer's Manual
Chapter 11: Exception Handling

Home Contents Index Master Index New Book

Library Functions for Retrieving Error Messages

Each SQLCODE value has an associated message. Informix message files in the $INFORMIXDIR/msg directory store the message number and its text. This information, along with corrective actions, also appears in the Informix Error Messages manual.

When you use SQLCODE and the sqlca structure, you can retrieve error message text with the rgetlmsg() and rgetmsg() functions. Both of these functions take the SQLCODE error code as input and return the associated error message.

Tip: When you use SQLSTATE and the GET DIAGNOSTICS statement, you can access information in the MESSAGE_TEXT field of the diagnostics area to retrieve the message text that is associated with an exception. For more information, see "Exception Information".

The following pages describe the rgetlmsg() and rgetmsg() functions.

Important: Use rgetlmsg() in any new ESQL/C code that you write. ESQL/C provides the rgetmsg() function primarily for backward compatibility.

rgetlmsg()

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

Syntax

int rgetlmsg(msgnum, msgstr, lenmsgstr, msglen)

		long   msgnum;

		char  *msgstr;

		int  lenmsgstr;

		int *msglen;  


msgnum
is the error number. The four-byte parameter provides for the full range of Informix-specific error numbers.

msgstr
is a pointer to the buffer that receives the message string (the output buffer). 

lenmsgstr  
is the size of the msgstr output buffer. Make this value the size of the largest message that you expect to retrieve.

msglen
is a pointer to the integer 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.

For more information, see the Informix Error Messages manual.

Example

This sample program is in the rgetlmsg.ec file in the ESQL/C 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()

{

    int 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.

Example Output

RGETLMSG Sample ESQL Program running.





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



RGETLMSG Sample Program over.

rgetmsg()

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

Syntax

int rgetmsg(msgnum, msgstr, lenmsgstr)

		short   msgnum;

		char  *msgstr;

		short  lenmsgstr;  


msgnum
is the error number. The two-byte parameter restricts error numbers to between -32768 and +32767.

msgstr
is a pointer to the buffer that receives the message string (the output buffer). 

lenmsgstr  
is 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: ESQL/C supports the rgetmsg() function for backward compatibility. Some Informix error numbers currently exceed the range that the short integer, msgnum, supports. Informix recommends the rgetlmsg() function, which supports long integers as error numbers, 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() has a short data type while the SQLCODE value is 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.

For more information, see the Informix Error Messages manual.

Example

This sample program is in the rgetmsg.ec file in the ESQL/C 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");

}

Example Output

RGETMSG Sample ESQL Program running.





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



RGETMSG Sample Program over.

WIN NT/95

Displaying Error Text in a Windows Environment

Your ESQL/C application can use the Informix ERRMESS.HLP file to display text that describes an error and its corrective action. You can call the Windows API WinHelp() with the following WinHelp parameters.


WinHelp Parameter	Data
`HELP_CONTEXT`	Error number from `SQLCODE` or sqlca.sqlcode
`HELP_CONTEXTPOPUP`	Error number from `SQLCODE` or sqlca.sqlcode
`HELP_KEY`	Pointer to string that contains error number from `SQLCODE` or sqlca.sqlcode and is converted to `ASCII` with sprintf() or wsprintf()
`HELP_PARTIALKEY`	Pointer to string that contains error number from `SQLCODE` or sqlca.sqlcode and is converted to `ASCII` with sprintf() or wsprintf()

Informix-ESQL/C Programmer's ManualChapter 11: Exception Handling Home Contents Index Master Index New Book

Library Functions for Retrieving Error Messages

rgetlmsg()

Syntax

Usage

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

Example Output

rgetmsg()

Syntax

Usage

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

Example Output

Displaying Error Text in a Windows Environment

Informix-ESQL/C Programmer's Manual
Chapter 11: Exception Handling

Home Contents Index Master Index New Book

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.

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.