Using the Error Subfile for messages in display files

I recently received a communication asking me if there was an easier way to display messages on a display file than using a message subfile. In my opinion there is a much simpler way using the Error Subfile, ERRSFL, keyword in the display file.

I have been using the Error Subfile for many years, so long that I cannot remember when I first encountered it. By using it I do not have to add all the code for the message subfile to my programs. I can just enter ERRSFL into my display and let the operating system do the hard work.

The ERRSFL has to added with other file level keywords at the top of the display files code:

01 A DSPSIZ(24 80 *DS3) 02 A ERRSFL 03 A INDARA 04 A CA03(03)

There are only certain display file keywords that will write to the Error subfile for you:

• Error message, ERRMSG
• Error message id, ERRMSGID
• Subfile message, SFLMSG
• Subfile message id, SFLMSGID
• Check for modulus 10 and 11, CHECK(M10)  CHECK(M11)
• Check for valid name and extended name, CHECK(VN)  CHECK(VNE)
• Comparison, COMP
• Range of values, RANGE
• List of values, VALUES

In this example my very simple display file looks like:

01 A DSPSIZ(24 80 *DS3) 02 A ERRSFL 03 A INDARA 04 A CA03(03) 05 A R SCREEN 06 A 4 3'Field 1 . .' 07 A FLD001 3A B 4 15 08 A 50 ERRMSG('Field 1 error') 09 A 5 3'Field 2 . .' 10 A FLD002 3A B 5 15 11 A 51 ERRMSG('Field 2 error' 51) 12 A 52 ERRMSGID(CPDA0FF QCPFMSG 52 + &TEXT) 13 A TEXT 132A P 14 A 6 3'Field 3 . .' 15 A FLD003 1A B 6 15VALUES('Y' 'N') 16 A CHKMSGID(CAE9078 QCPFMSG) 17 A 6 22'(Y,N)'

The ERRMSG keyword is up there with the other file level keywords on line 2.

Regular readers will know that I use the Indicator data area, INDARA on line 3, to handle indicators between display files and my RPG programs.

The first field, FLD001, has an error keyword, ERRMSG, on line 8 which is conditioned by indicator 50.

The second field, FLD002, has two error keywords. The first, ERRMSG on line 11, is conditioned by indicator 51. Notice how the indicator is also found within the ERRMSG keyword, this will reset the indicator to off after the display file record format is displayed. The second, ERRMSGID, has four parameters within the keyword:

1. Message id
2. Message file
3. Indicator that will be set off
4. Message data field

The message data field is defined on line 13. It is a 132 character field, which matches the definition in the message file, and is defined with a "P" in the Use column to indicate that it is a program-to-system field. I will show below how you can move a string to the program-to-system field and have it display as an error message.

The third field, FLD003, uses the VALUES keyword. I am sure we have all either used or seen this keyword before. The VALUES allows the display file to validate that any characters entered must be one of those given in the keyword, in this example it will need to be either "Y" or "N". I think one of the drawbacks of using this keyword is the cryptic message it delivers when something is entered that is not one of the allowed values:

Value entered for field is not valid. Valid values listed in message help.

By using the Check message id keyword, CHKMSGID, I can display a more meaningful error. In this example I used message id CPDA0FF from the QCPFMSG message file to display:

Enter Y or N.

So what does the RPG program look like? As you can see, below, the program is small.

01 dcl-f TESTDSPF workstn indds(IndDs) ; 02 dcl-ds IndDs qualified ; 03 Exit ind pos(3) ; 04 ErrFld1 ind pos(50) ; 05 ErrFld2a ind pos(51) ; 06 ErrFld2b ind pos(52) ; 07 end-ds ; 08 dou (IndDs.Exit) ; 09 exfmt SCREEN ; 10 if (FLD001 <> ' ') ; 11 IndDs.ErrFld1 = *on ; 12 endif ; 13 if (FLD002 = '?') ; 14 IndDs.ErrFld2b = *on ; 15 TEXT = 'What is your question?' ; 16 elseif (FLD002 <> ' ') ; 17 IndDs.ErrFld2a = *on ; 18 endif ; 19 enddo ; 20 *inlr = *on ;

The file definition for the display contains the INDDS, which identifies the name of the indicator area data structure, IndDs.

The indicator area data structure can be seen in line 2 – 7. The data structure is qualified.

As this is an example program the checking for errors is... well... very simple. If I enter "X" into both FLD001 and FLD002 I cause errors in both fields, which is shown on the display file like this:

Field 1 . . X__ Field 2 . . X__ Field 3 . . Y (Y,N) Field 1 error +

The error for Field 1 is displayed at the bottom screen with a "+" to indicate that this subfile contains more than one record. If I position my cursor on the error message and Page Down I see the second message for Field 2:

Field 2 error

The display file has automatically set off the error indicator for Field 2, as the error indicator is given in the ERRMSG keyword, see line 11 of the display file's code. The error indicator for Field 1 is still on. If Field 1 and 2 are cleared and Enter is pressed the error message for Field 1 will be displayed as the indicator is still on. I would have to set it off in the RPG code.

If put "?" in Field 2 the RPG code between lines 13 – 15 is executed. My message will be any sting I move into the program to system field, TEXT, this is displayed as a message:

Field 1 . . ___ Field 2 . . ?__ Field 3 . . Y (Y,N) What is your question?

And now for the field with the VALUES keyword, Field 3. If I enter "X" into Field 3 and press Enter the display file determines that "X" is not an allowed value and as the CHKMSGID keyword is present, line 16 of the display file, the message text of the given Message id is shown.

Field 1 . . ___ Field 2 . . ___ Field 3 . . X (Y,N) Enter Y or N.

By all means I have veered away from this post being just about the Error Subfile, ERRSFL, I hope additional information included about error messages will prove useful too.

 

You can learn more about this on the IBM website:

• ERRSFL
• ERRMSG and ERRMSGID
• VALUES
• CHKMSGID

 

This article was written for IBM i 7.2, and should work for earlier releases too.