EGL Reference Guide for iSeries

Exception handling and status (system words)

As shown in the next table, exception handling and status words are used to control how programs respond to exceptions and error conditions (such as arithmetic overflow), and to determine what codes are returned when exceptions occur.


System word/Usage Description
sysLib.displayMsgNum
sysLib.displayMsgNum
(msgNumber)
Retrieves a value from the program's message table
sysLib.setError
sysLib.setError
(elementInError, msgKey, msgInsertList)
sysLib.setError
(msgText)
Associates a message with an item in a page handler or with the page handler itself
sysLib.validationFailed
sysLib.validationFailed
(msgNumber)
Involved in message presentation on a text or print form
sysVar.errorCode
sysVar.errorCode

Receives a status code after any of the following events:

  • The invocation of a call statement, if that statement is in a try block
  • An I/O operation on an indexed, MQ, relative, or serial file
  • The invocation of almost any system function in these cases--
    • The invocation is within a try block; or
    • The program is running in VisualAge Generator Compatibility mode and sysVar.handleSysLibErrors is set to 1

(For an overview that includes details on sysVar.errorCode, see Exception handling.)

sysVar.handleHardIOErrors
sysVar.handleHardIOErrors
Controls whether a program continues to run after a hard I/O error occurs on an I/O operation
sysVar.handleOverflow
sysVar.handleOverflow
Controls error processing after an arithmetic overflow
sysVar.handleSysLibErrors
sysVar.handleSysLibErrors
Specifies whether the value of the system variable sysVar.errorCode is affected by the invocation of a system function
sysVar.mqConditionCode
sysVar.mqConditionCode
Contains the completion code from an MQSeries API call following an add or scan I/O operation for an MQ record
sysVar.overflowIndicator
sysVar.overflowIndicator
Is set to 1 when arithmetic overflow occurs
sysVar.returnCode
sysVar.returnCode
Contains the external return code to be checked when the program ends; the check is by the JCL, by the command processor, or by the calling high-level language program
sysVar.sqlca
sysVar.sqlca
Contains the SQL communication area (SQLCA) returned for the last SQL I/O operation
sysVar.sqlcode
sysVar.sqlcode
Contains the return code for the most recently completed SQL I/O operation
sysVar.sqlerrd
sysVar.sqlerrd[index]
Is a static 6-element array, where each element contains the corresponding SQL communication area (SQLCA) value that was returned from the last SQL I/O option
sysVar.sqlerrmc
sysVar.sqlerrmc
Contains the substitution variables for the error message associated with the return code in sysVar.sqlcode
sysVar.sqlState
sysVar.sqlState
Contains the SQL state value for the most recently completed SQL I/O operation
sysVar.sqlwarn
sysVar.sqlwarn[index]
Is a static 11-element array, where each element contains a warning byte returned in the SQL communications area (SQLCA) for the last SQL I/O operation and where the index is one greater that the warning number in the SQL SQLCA description; sqlwarn[1], for example, refers to SQLWARN0
sysVar.validationMsgNum
sysVar.validationMsgNum
Contains the value assigned by sysLib.validationFailed


Related reference
EGL statements
Exception handling
Function invocations
System words
System words in alphabetical order

sysLib.displayMsgNum

The system function sysLib.displayMsgNum retrieves a value from the program's message table. The message is presented the next time that a form is presented by a converse, display, print, or show statement.

If possible, the message presentation is on the form itself, in the field to which the form property msgField refers. If the form property msgField has no value, the message is displayed previous to the display of the form, on a separate, modal screen or on a printable page.

sysLib.displayMsgNum takes as its only argument a value that is compared against each cell in the first column of the program's message table, which is the data table to which the program's msgTablePrefix property refers. The message retrieved by that function is in the second column of the same row.



sysLib.displayMsgNum syntax diagram

msgNumber
The message is retrieved from the message table by number. The argument must be an integer literal or an item of primitive type SMALLINT or INT or the BIN equivalent.


Related reference
System words in alphabetical order

sysLib.setError

The system function sysLib.setError associates a message with an item in a page handler or with the page handler as a whole. The message is placed at the location of a JSF message or messages tag in the JSP and is displayed when the related Web page is displayed.

If a validation function invokes sysLib.setError, the Web page is re-displayed automatically when the function ends.



sysLib.setError syntax diagram

itemInError
The name of the page-handler item that is in error.
this
Refers to the page handler from which sysLib.setError is issued. In this case, the message is not specific to an item, but is associated with the page handler as a whole. For details on this, see References to variables and constants.
msgKey
A character item or literal (type CHAR or MBCHAR) that provides the key into the message resource bundle or properties file used at run time. If the key is blank, the message is a concatenation of message inserts.
itemInsert
The character item or literal that is included as an insert to the output message. The substitution symbol in message text is an integer surrounded by braces, as in this example:
  Invalid file name {0}
msgText
The character item or literal that you can specify if you do not specify other arguments. The text is associated with the page as a whole.

You can associate multiple messages with an item or page handler. The EGL run time displays the messages when the page is re-displayed. If control is forwarded (specifically, if the page handler runs a forward statement), those messages are lost.


Related concepts
PageHandler part
References to variables and constants


Related tasks
Syntax diagram


Related reference
forward

sysLib.validationFailed

The system function sysLib.validationFailed is used in either of two ways:

In any case, the value assigned to sysLib.validationFailed is stored in the system variable sysVar.validationMsgNum.



sysLib.validationFailed syntax diagram

msgNumber
The number of the message to display. The argument must be an integer literal or an item of primitive type SMALLINT or INT or the BIN equivalent. This number is compared against each cell in the first column of the program's message table, which is the data table to which the program's msgTablePrefix property refers. The retrieved message is in the second column of the same row.

The message number is 9999 by default.


Related reference
sysLib.displayMsgNum
sysVar.validationMsgNum
System words in alphabetical order

sysVar.errorCode

The system variable sysVar.errorCode receives a status code after any of the following events:

You can use sysVar.errorCode in these ways:

sysVar.errorCode is set to 0 if the call, I/O, or system function invocation is successful.

The characteristics of sysVar.errorCode are as follows:

Primitive type
CHAR

Data length
8

Is value always restored after a converse?
Yes

For an overview that includes details on sysVar.errorCode, see Exception handling.

Definition considerations

If you are generating Java code, the list of possible sysVar.errorCode values is provided in EGL Java run-time error codes.

I/O errors and COBOL code

In relation to COBOL code, the following rules apply:

The next table indicates some of the COBOL file status codes that can be returned, along with the value that is placed in sysVar.errorCode if you generate COBOL output with the build descriptor option sysCodes set to NO. Also shown is the EGL I/O error value, which is unaffected by the value in sysCodes.


COBOL file status code (as placed in sysVar.errorCode when sysCodes is set to YES) sysVar.errorCode value when sysCodes is set to NO EGL I/O error value (a blank in this column means "not applicable")
00000000, 00000005, 00000007 00000000
00000002 00000103 duplicate, ioError
00000004 (var record format) 00000000
00000004 (other) 00000220 format, hardIOError, ioError
00000010, 00000014, 00000046 00000102 endOfFile, ioError
00000022 00000206 ioError, unique
00000023 (start) 00000102 endOfFile, ioError
00000023 (other) 00000205 noRecordFound, ioError
00000024, 00000034 (access method not relative or relative key not 0) 0000025A full, hardIOError, ioError
00000035 00000251 fileNotFound, hardIOError, ioError
00000038 00000218 fileNotAvailable, hardIOError, ioError
00000039, 00000095 00000220 format, ioError
0000009D (iSeries COBOL only) 00000381 deadlock, hardIIOError, ioError

The next table shows the setting for sysVar.errorCode when the run-time system returns other COBOL file status codes.


Type of request sysVar.errorCode value when sysCodes is set to NO EGL I/O error value
open 00000500 ioError, hardIOError
close or unlock 00000989 ioError, hardIOError
read or start 00000987 ioError, hardIOError
write 00000988 ioError, hardIOError

Example
  if (sysVar.errorCode = "00000008")
	  exit program;
  end


Related reference
EGL Java run-time error codes


Exception handling
Exception handling and status (system words)
System words in alphabetical order
sysVar.handleSysLibErrors
try

sysVar.handleHardIOErrors

The system variable sysVar.handleHardIOErrors controls whether a program continues to run after a hard error occurs on an I/O operation. The default value is 0. For background information, see Exception handling.

You can use sysVar.handleHardIOErrors in any of these ways:

The characteristics of sysVar.handleHardIOErrors are as follows:

Primitive type
NUM

Data length
1

Is value always restored after a converse?
Yes

Example

sysVar.handleHardIOErrors = 1;


Related reference
Exception handling
Exception handling and status (system words)

sysVar.handleOverflow

The system variable sysVar.handleOverflow controls error processing after an arithmetic overflow. Two types of overflow conditions are detected:

You can set sysVar.handleOverflow to one of the following values. (The default setting is 0.)

Value Effect on user overflow Effect on maximum value overflow
0 The program sets the system variable sysVar.overflowIndicator to 1 and continues The program ends with an error message
1 The program ends with an error message The program ends with an error message
2 The program sets the system variable sysVar.overflowIndicator to 1 and continues The program sets the system variable sysVar.overflowIndicator to 1 and continues

You can use sysVar.handleOverflow in these ways:

The characteristics of sysVar.handleOverflow are as follows:

Primitive type
NUM

Data length
1

Is value always restored after a converse?
Yes

Example
  sysVar.handleOverflow = 2;


Related reference
Assignments
Exception handling and status (system words)
sysVar.overflowIndicator

sysVar.handleSysLibErrors

The system variable sysVar.handleSysLibErrors specifies whether the value of system variable sysVar.errorCode is affected by the invocation of a system function. However, sysVar.handleSysLibErrors is available only when VisualAge Generator compatibility is in effect, as explained in Compatibility with VisualAge Generator.

For details and restrictions, see Exception handling.

You can use sysVar.handleSysLibErrors in these ways:

The characteristics of sysVar.handleSysLibErrors are as follows:

Primitive type
NUM

Data length
1

Is value always restored after a converse?
Only in a non-segmented text program; for details see Segmentation

Example
  sysVar.handleSysLibErrors = 1;


Related concepts
Compatibility with VisualAge Generator
Segmentation in text applications


Related reference
Exception handling
Exception handling and status (system words)
System words
sysVar.errorCode

sysVar.mqConditionCode

The system variable sysVar.mqConditionCode contains the completion code from an MQSeries API call following an add or scan I/O operation for an MQ record. Valid values and their related meanings are as follows:

00
OK
01
WARNING
02
FAILED

You can use sysVar.mqConditionCode in these ways:

The characteristics of sysVar.mqConditionCode are as follows:

Primitive type
NUM

Data length
2

Is value always restored after a converse?
Yes

Example
  add MQRecord;
  if (sysVar.mqConditionCode = 0)
	   // continue
  else
	   exit program;
  end


Related concepts
MQSeries support


Related reference
Exception handling
Exception handling and status (system words)
System words

sysVar.overflowIndicator

The system variable sysVar.overflowIndicator is set to 1 when arithmetic overflow occurs. By checking the value of this variable, you can test for overflow conditions.

After detection of an overflow condition, sysVar.overflowIndicator is not reset automatically. You must include code in your program to reset sysVar.overflowIndicator to 0 before performing any calculations that may trigger overflow checks.

You can use sysVar.overflowIndicator in these ways:

The characteristics of sysVar.overflowIndicator are as follows:

Primitive type
NUM

Data length
1

Is value always restored after a converse?
Yes

Example
  sysVar.overflowIndicator = 0;
  sysVar.handleOverflow = 2;
  a = b;
  if (sysVar.overflowIndicator = 1) 
    add errorrecord;
  end


Related reference
Assignments
Exception handling and status (system words)
sysVar.handleOverflow

sysVar.returnCode

The system variable sysVar.returnCode contains an external return code, as set by your program and made available to the operating system. It is not possible to pass return codes from one EGL program to another. A non-zero return code does not cause EGL to run an onException block, for example. The initial value of sysVar.returnCode is zero. The value must be in the range of 0 to 512.

In relation to Java code,sysVar.returnCode is meaningful only for a main text program (which runs outside of J2EE) or a main batch program (which runs either outside of J2EE or in a J2EE application client). The purpose of sysVar.returnCode in this context is to provide a code for the command file or exec that invokes the program. If the program ends with an error that is not under the program's control, the EGL run time ignores the setting of sysVar.returnCode and attempts to return the value 693.

In relation to COBOL code, the following statements apply:

You can use sysVar.returnCode in these ways:

The characteristics of sysVar.returnCode are as follows:

Primitive type
BIN

Data length
9

Is value always restored after a converse?
Yes

Example
  sysVar.returnCode = 6;


Related reference
Exception handling and status (system words)

sysVar.validationMsgNum

The system variable sysVar.validationMsgNum is available in a text application and contains the value assigned by sysLib.validationFailed. The value is reset to zero in each of the following cases:

You can test the value of sysVar.validationMsgNum to determine if a validation function reported an error.

You can use sysVar.validationMsgNum in these ways:

The characteristics of sysVar.validationMsgNum are as follows:

Primitive type
INT

Is value always restored after a converse?
No

Example

/*Keep the first message number that was set 
  during validation routines */
if (sysVar.validationMsgNum > 0)
    sysLib.validationFailed(10);
end


Related reference
converse
display
print
sysLib.validationFailed
System words in alphabetical order


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]