Errors are reported using one of the following functions:
- IDL_Message()
- IDL_MessageFromBlock()
- IDL_MessageSyscode()
- IDL_MessageSyscodeFromBlock()
These functions are patterned after the standard C library printf() function. They are really the same function, differing in which message block the error is issued from (the FromBlock versions allow you to specify the block) and their reporting of system errors that might accompany IDL errors (the Syscode versions allow you to specify a system error). IDL documentation often refers to IDL_Message(). This should be understood to be a generic reference to any of these four functions.
void IDL_Message(int code, int action, ...)
void IDL_MessageFromBlock(IDL_MSG_BLOCK block,int code, int action, ...)
void IDL_MessageSyscode(int code, IDL_MSG_SYSCODE_T syscode_type, int syscode, int action, ...)
void IDL_MessageSyscodeFromBlock(IDL_MSG_BLOCK block, int code, IDL_MSG_SYSCODE_T syscode_type, int syscode, int action, ...)
Arguments
block
Pointer to the IDL message block from which the error should be issued. If block is a NULL pointer, the default IDL core block (IDL_MBLK_CORE) is used.
code
This is the error code associated with the error message to be issued. There are two error codes in the default IDL core block (IDL_MBLK_CORE) that are available to programmers adding system routines to IDL. The use of these codes is described below. See “Error Codes,” below.
Note: For any significant development involving an IDL system routine, we recommend your code be packaged as a Dynamically Loadable Module (DLM), and that your DLM define a message block to contain its errors instead of using the GENERIC core block messages.
syscode_type
IDL_Message() always issues a single-line error message that describes the problem from IDL’s point of view. Often, however, there is an underlying system reason for the error that should also be displayed to give the user a complete picture of what went wrong. For example, the IDL view of the problem might be “Unable to open file,” while the underlying system reason for the error is “no such directory.” The IDL_MessageSyscode() functions allow you to include the relevant system error code, and have it incorporated into the IDL message on a second line of output. There are several different types of system error code that can be specified. The syscode_type argument is used to tell IDL_MessageSyscode() which type of system error is present:
IDL_MSG_SYSCODE_NONE
Indicates that there is no system error. In this case, the syscode argument is ignored, and IDL_MessageSyscode() is functionally equivalent to IDL_Message().
IDL_MSG_SYSCODE_ERRNO
The UNIX operating system uses a system provided global variable named errno for communicating system level errors. Whenever a call to a system function fails, it returns a value of -1 and puts an error code into errno that specifies the reason for the failure. Other functions, such as those provided by the standard C library, do not set errno. The system documentation (man pages) describes which functions do and do not set errno, and the rules for interpreting its value.
You should specify IDL_MSG_SYSCODE_ERRNO only if you are calling IDL_MessageSyscode() as the result of a failed function that is documented to set errno on your target platform. Otherwise, errno might contain an unrelated garbage value resulting in an incorrect error message. When specifying IDL_MSG_SYSCODE_ERRNO, you should supply the current value of errno as the syscode argument to IDL_MessageSyscode().
Note: The Microsoft Windows operating system has errno for compatibility with the expectations of C programmers, but typically does not set it. On this operating system, specifying IDL_MSG_SYSCODE_ERRNO may have no effect.
IDL_MSG_SYSCODE_WIN (Microsoft Windows Only)
Microsoft Windows system error codes. The value supplied to the syscode argument to IDL_MessageSyscode() should be a system error code, as returned by the Windows GetLastError() system function.
IDL_MSG_SYSCODE_WINSOCK (Microsoft Windows Only)
Microsoft Windows winsock error codes. The value supplied to the syscode argument to IDL_MessageSyscode() should be a system error code, as returned by the Windows WSAGetLastError() system function
syscode
Value of the system error code that should be reported. This argument is ignored if its value is zero (0), or if syscode_type is IDL_MSG_SYSCODE_NONE. Otherwise, it is interpreted as an error code of the type given by syscode_type, and the text of the specified system error will be output along with the IDL message on a separate second line.
action
IDL_Message() can take a number of different actions after issuing the error message. The action to take is specified by the action argument:
IDL_MSG_RET
Use this argument to make IDL_Message() return to the caller after issuing the error message. In this case, the calling routine can either continue or return to the interpreter as it sees fit.
IDL_MSG_INFO
Use this argument to issue a message that is not an error, but is informational in nature. The message is output and IDL_Message() returns to the caller. Normally, IDL_Message() sets the values of IDL’s !ERROR_STATE system variables, but not in this case.
IDL_MSG_EXIT
Use this argument to cause the IDL process to exit after the message is issued. This code should never be used in a system function or procedure—it is intended for use in other sections of the system.
IDL_MSG_LONGJMP
Use this argument to cause IDL_Message() to exit directly back to the interpreter after issuing the message. In this case, IDL_Message() does not return to its caller. It is an error to use this action code in code not called by the IDL interpreter since the resulting call to longjmp() will be invalid.
IDL_MSG_IO_LONGJMP
This action code is exactly like IDL_MSG_LONGJMP except that it is issued in response to an input/output error. This code is only used by the I/O module. User written system routines should use the existing I/O routines, so they do not need to use this action.
Modifier Codes
In addition, the following modifier codes can be ORed into the action code. They modify the normal behavior of IDL_Message():
IDL_MSG_ATTR_NOPRINT
Suppress the printing of the error message, but do everything else in the normal way.
IDL_MSG_ATTR_MORE
Use paging in the style of the UNIX more command to display the output. This option exists primarily for use by the IDL compiler, and is unlikely to be of interest to authors of system routines.
IDL_MSG_ATTR_NOPREFIX
Normally, IDL_Message() prefixes the output message with the string contained in IDL’s !MSG_PREFIX system variable. IDL_MSG_ATTR_NOPREFIX suppresses this prefix string.
IDL_MSG_ATTR_QUIET
If the IDL_MSG_INFO action has been specified and this bit mask has been included, and the IDL user has IDL’s !QUIET system variable, IDL_Message() returns without issuing a message.
IDL_MSG_ATTR_NOTRACE
Set this code to inhibit the traceback portion of the error message.
IDL_MSG_ATTR_BELL
Set this code to ring the bell when the message is output.
Note: The message format string specifies a format string to be used for the error message. This format string is exactly like those used by the standard C library printf() function. Any arguments following action are taken to be arguments for this format string.
Error Codes
As mentioned above, two error codes are reserved for use by writers of system routines. They are:
IDL_M_GENERIC
This message code specifies a format string of “%s”. The first argument after action is taken to be a null-terminated string that is substituted into the format string. For example, the C statement:
IDL_Message(IDL_M_GENERIC, IDL_MSG_LONGJMP, "Error! Help!")
causes IDL to abort the current routine and issue the message:
% Error! Help!
IDL_M_NAMED_GENERIC
This message code is exactly like the one above except that it prints the name of the system routine in front of the error string. For example, assuming that the name of the routine is MY_PROC, the C statement:
IDL_Message(IDL_M_NAMED_GENERIC, IDL_MSG_LONGJMP, "Error! Help!")
causes IDL to interrupt the current routine and issue the message:
% MY PROC: Error! Help!