Brief: Using message subfiles is a superior approach to interactive message handling. This technique provides the user with detailed information even when there are many errors on the screen. This article explores message subfiles and shows you how to take advantage of some of the message-handling APIs to simplify the implementation.
An interactive application on the AS/400 can use a variety of techniques to present error messages to the user. Message subfiles offer significantly more power and flexibility than other methods; you can give the user detailed information-whether there is one error or a dozen. Message subfiles are similar to ordinary subfiles except that they only contain messages. By taking advantage of three of the message handling APIs, as I'll show in this article, you can develop applications that use message subfiles quickly and easily.
To see a message subfile in action, you can enter an OS/400 command that generates multiple messages. The first error message appears at the bottom of the screen with a plus sign which tells you that there are more messages coming. By placing the cursor on the message, you can use the roll keys to view the additional messages. You can also obtain more information about a specific message by placing the cursor on a message and pressing the help key.
The Program Message Queue
In order to understand message subfiles, it is important to understand the concept of a program message queue. Every time a program is called, a program message queue is created within the job. The program message queue has the same name as the program. As the programmer, you can send messages to a program message queue. The system can also generate messages to a program message queue. A program can send messages to its own program message queue and called programs (those lower in the invocation stack) can send messages to the calling program's program message queue. For example, if program A calls program B, then program B can send messages to program A's program message queue.
A program message queue is just like any other message queue, except that there are no commands in the operating system to view the messages-you must display them using a message subfile. When you use the technique described in this article, the messages on the program message queue are copied to the message subfile. All messages on the program message queue automatically appear in the message subfile. If the program message queue is empty, then the message subfile is also empty. It's that simple!
A Typical Example
To illustrate the use of message subfiles, I have coded a Product Sale Price Entry screen as shown in 1. This screen prompts the user for a product code, a sale price and a sale start date. To keep this example simple, there are only a few conditions that generate errors: the only error on the product code field is a blank entry; similarly, if the sale price is not entered, then a message is generated and the sale start date must be a valid date in MM/DD/YY format. For any erroneous values, a message appears at the bottom of the screen. Additionally, all fields in error are shown in reverse image and the cursor is placed on the first field of those in error.
To illustrate the use of message subfiles, I have coded a Product Sale Price Entry screen as shown in Figure 1. This screen prompts the user for a product code, a sale price and a sale start date. To keep this example simple, there are only a few conditions that generate errors: the only error on the product code field is a blank entry; similarly, if the sale price is not entered, then a message is generated and the sale start date must be a valid date in MM/DD/YY format. For any erroneous values, a message appears at the bottom of the screen. Additionally, all fields in error are shown in reverse image and the cursor is placed on the first field of those in error.
The messages for the first two fields exist in a message file called MSF001MF. 2 shows the commands to create and load the message file. To learn more about AS/400 messages, refer to "AS/400 Messages: Part I" (MC, March 1992) and "AS/400 Messages: Part II" (MC, April 1992). The message for the third field is generated by the system.
The messages for the first two fields exist in a message file called MSF001MF. Figure 2 shows the commands to create and load the message file. To learn more about AS/400 messages, refer to "AS/400 Messages: Part I" (MC, March 1992) and "AS/400 Messages: Part II" (MC, April 1992). The message for the third field is generated by the system.
Now that you know what this example does, let's take a look at the DDS and RPG.
The DDS Message Subfile
3 shows the DDS code for the display file MSF001DF. The highlighted section of the figure is the code for the message subfile. A message subfile, like all subfiles, consists of two record formats-the subfile (SFL) record and the subfile control (SFLCTL) record. A message subfile differs from a regular subfile because it includes three DDS keywords: Subfile Message Record (SFLMSGRCD), Subfile Message Key (SFLMSGKEY) and Subfile Program Queue (SFLPGMQ).
Figure 3 shows the DDS code for the display file MSF001DF. The highlighted section of the figure is the code for the message subfile. A message subfile, like all subfiles, consists of two record formats-the subfile (SFL) record and the subfile control (SFLCTL) record. A message subfile differs from a regular subfile because it includes three DDS keywords: Subfile Message Record (SFLMSGRCD), Subfile Message Key (SFLMSGKEY) and Subfile Program Queue (SFLPGMQ).
There are actually two types of message subfiles; for a multiple-output operation message subfile, your program writes each message separately to the message subfile. This technique gives you greater control over what messages the user sees (e.g., only diagnostic messages). A single-output operation message subfile is automatically loaded with all of the messages currently in the program message queue.
I'll concentrate on this second type of message subfile since it is used more often and, in my opinion, is easier to code because the operating system is doing much of the work for you. For a detailed explanation of both types of message subfiles, refer to the documentation for the SFLPGMQ keyword in the DDS Reference manual.
To create a message subfile, you must specify the SFLMSGRCD keyword at the record level. The use of this keyword converts an ordinary subfile into a message subfile. The parameter (24 in our example) specifies the first line where messages will appear. When you use this keyword, two additional keywords are required in the subfile: the SFLMSGKEY and SFLPGMQ keywords (in that order). Both keywords require a field.
The SFLMSGKEY keyword must be specified first. The field associated with this keyword, MSGKEY in our example, is automatically defined as a four-byte, character, hidden field. This field contains the message-reference key for each message in the message subfile.
The SFLPGMQ keyword must be specified next. The field associated with this keyword, PGMQ in our example, is automatically created as a 10-byte, character, hidden field. Your program must load this field with the name of the program message queue that builds the message subfile. The program message queue has the same name as the program that uses the display file. For all program types except CL, you can optionally place an asterisk (*), left-justified, into the SFLPGMQ field. Doing this has the same effect as loading the field with the program name.
So far, we have looked at the keywords in the subfile record format. Now let's take a look at the keywords used in the subfile-control record format. Most of these keywords are the same ones you would find in an ordinary subfile, so I don't think it's necessary to elaborate on them. However, I would like to draw your attention to the last two keywords; Subfile Initialize (SFLINZ) and Subfile Program Queue (SFLPGMQ).
Earlier, I said that there are two types of message subfiles. Use these two keywords in the subfile-control record to make the subfile a single-output operation message subfile-the operating system automatically loads the message subfile for you. To code a multiple-output operation message subfile, leave out these two entries and perform WRITE operations to the subfile in your program- no messages will be loaded automatically for you.
RPG and the Message APIs
4 shows the code for the RPG program MSF001RG. This program begins by executing an initialization routine that loads a number of variables used as parameters for the message handling APIs.
Figure 4 shows the code for the RPG program MSF001RG. This program begins by executing an initialization routine that loads a number of variables used as parameters for the message handling APIs.
The main logic of the program is fairly simple. A loop is performed until the user presses the F3 key. Within this loop, the main screen is presented to the user and the Edit Screen (EDTSCR) subroutine is executed. If no errors are found, the screen is cleared. Normally, this is where you would write a record to a database file, but I left this part out for the purpose of this example. Now, let's take a closer look at the EDTSCR subroutine. This subroutine executes the Clear Message (CLRMSG) subroutine to remove all messages from the program message queue. Tests are then performed on the screen fields to determine if there are any errors. If either the product code (PRCODE) or sale price (SLPRCE) fields are found to be in error, then the MSGID field is loaded with the message identifier for the error message you want to send to the user. The Send Message (SNDMSG) subroutine is executed, which sends the message to the program message queue.
For the sale start date (SLDATE) field, the CL program MSF001CL is called to perform the date validation. The validation could have been performed with an in-line call to the Convert Date API, but I chose to call the CL program in order to show how a message can be moved from one program message queue to another (more on this later). For each field found in error, two indicators are set on. One indicator causes the field to be displayed in reverse image and positions the cursor on the field. The other is a general error indicator used to determine if any errors were found. All of these indicators are automatically set off in the display file by using the SETOF DDS keyword.
The CLRMSG subroutine calls the Remove Program Messages (QMHRMVPM) API, which removes messages from a program message queue. The API can remove individual messages by key, or remove all messages at once. In this case, we have requested that all messages be removed by passing the value '*ALL' in the Messages to Remove (MSGRMV) parameter. Doing this is functionally equivalent to executing the following command:
RMVMSG CLEAR(*ALL)
However, you cannot execute the RMVMSG command by calling QCMDEXC, because it is not allowed in this setting. You would have to write a separate CL program to execute it. The API eliminates the need to write a program. The other message APIs used here offer the same benefit.
The SNDMSG subroutine calls the Send Program Messages (QMHSNDPM) API. This API gives you several ways to send program messages. You can send a message from a message file, or simply send message text. You can include message data for substitution variables, if necessary. You can also specify which type of message to send (e.g., *COMP, *DIAG, *ESCAPE). In this example, I chose to send diagnostic messages from a message file. The result is the same as calling a CL program to execute a command such as the following:
SNDPGMMSG MSGID(MSG0001) + MSGF(MSF001MF) MSGTYPE(*DIAG)
I have not supplied any message data in this example. However, this could easily be done by placing the message data in the message data (MSGDTA) parameter and specifying the length in the message data length (DTALEN) parameter. As with the RMVMSG command, you cannot execute the SNDPGMMSG command by calling QCMDEXC. Once again, you can either use the API, or write a separate program to perform this task.
In my opinion, calling the APIs to remove and send messages from an RPG program is the only way to go. It allows you to perform a CL-like function from within your RPG program. Calling an API also eliminates the need to write a separate program to perform the same task. In other words, why reinvent the wheel? If there is already a program that does what you want to do, then I say use it!
5 shows the code for the CL program MSF001CL. This program accepts the sales date and an error flag as parameters. The Convert Date (CVTDAT) command validates the sales date and issues an escape message to the program message queue of the CL program if the date is invalid. The CL program monitors the escape message and the error flag is turned on. The Move Program Messages (QMHMOVPM) API moves messages from the current program's (MSF001CL) message queue to the previous one (MSF001RG). The current program message queue contains the escape message generated by the CVTDAT command. The previous program message queue is attached to the message subfile. So by calling this API, the message generated by the CL program appears in the message subfile of the RPG program.
Figure 5 shows the code for the CL program MSF001CL. This program accepts the sales date and an error flag as parameters. The Convert Date (CVTDAT) command validates the sales date and issues an escape message to the program message queue of the CL program if the date is invalid. The CL program monitors the escape message and the error flag is turned on. The Move Program Messages (QMHMOVPM) API moves messages from the current program's (MSF001CL) message queue to the previous one (MSF001RG). The current program message queue contains the escape message generated by the CVTDAT command. The previous program message queue is attached to the message subfile. So by calling this API, the message generated by the CL program appears in the message subfile of the RPG program.
You can specify up to four message types when you call QMHMOVPM; *COMP, *DIAG, *ESCAPE and *INFO. Generally, it is only necessary to move the diagnostic and escape messages, so that is what I've done in this example. There are two features that make this API very useful. First, all messages of the specified types are moved, which means that if there are multiple messages in the program message queue, they are all moved at once. Secondly, the API converts all escape messages to diagnostic messages, which is a good thing because if you send an escape message to an RPG program, it generally has a difficult time dealing with it.
If you haven't already figured it out, QMHMOVPM is one powerful API. There is no single CL command equivalent for what this API does. To perform the same task in CL, it would take a combination of RCVMSG and SNDPGMMSG commands executing in a loop. The API performs all of this with one CALL statement.
To clarify everything we have talked about up until now, take a look at 6. This diagram shows the relationships between the example programs, the program message queues and the message subfile.
To clarify everything we have talked about up until now, take a look at Figure 6. This diagram shows the relationships between the example programs, the program message queues and the message subfile.
Take Advantage of Message Subfiles
I hope that this article has taken some of the mystery out of message subfiles. I would encourage you to use them for all of your interactive message handling needs. Message subfiles have been around for a long time and remain an important part of a good interactive programming technique. Understanding how to code them is an essential skill for any AS/400 programmer. When you add to this the ability to work with message files using APIs, you have a powerful tool to perform message handling in your applications.
Robin Klima is a senior technical editor at Midrange Computing.
References DDS Reference (SC41-9620, CD ROM QBKA7401) System Programmer's Interface Reference (SC41-8223, CD ROM QBKA8401)
More Powerful Message Subfiles
Figure 1 Product Entry Screen
Product Sale Price Entry Enter product information, press Enter. Product code . . . . Sale price . . . . . .00 Sale start date . . 0/00/00 F3=Exit Product code not valid. +
More Powerful Message Subfiles
Figure 2 Message File MSF001MF
CRTMSGF MSGF(XXX/MSF001MF) ADDMSGD MSGID(MSG0001) MSGF(XXX/MSF001MF) + MSG('Product code not valid.') ADDMSGD MSGID(MSG0002) MSGF(XXX/MSF001MF) + MSG('Sale price not valid.')
More Powerful Message Subfiles
Figure 3 Display File MSF001DF
*============================================================ * To compile: * * CRTDSPF FILE(XXX/MSF001DF) SRCFILE(XXX/QDDSSRC) * *============================================================ *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+.. A DSPSIZ(24 80 *DS3) A PRINT A CA03(03) A R MSGSFL SFL A SFLMSGRCD(24) A MSGKEY SFLMSGKEY A PGMQ SFLPGMQ A R MSGCTL SFLCTL(MSGSFL) A SFLDSP A SFLDSPCTL A SFLSIZ(2) A SFLPAG(1) A N03 SFLEND A SFLINZ A PGMQ SFLPGMQ A R SCREEN A OVERLAY A SETOF(71) A SETOF(72) A SETOF(73) A SETOF(90) A 1 29'Product Sale Price Entry' A DSPATR(HI) A 5 2'Enter product information,' A COLOR(BLU) A 5 29'press Enter.' A COLOR(BLU) A 7 2'Product code . . . .' A PRCODE 6A B 7 25 A 71 DSPATR(RI) A 71 DSPATR(PC) A 9 2'Sale price . . . . .' A SLPRCE 7Y 2B 9 25EDTCDE(3) A 72 DSPATR(RI) A 72 DSPATR(PC) A 11 2'Sale start date . .' A SLDATE 6Y 0B 11 25EDTCDE(Y) A 73 DSPATR(RI) A 73 DSPATR(PC) A 23 2'F3=Exit' A COLOR(BLU) *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+..
More Powerful Message Subfiles
Figure 4 RPG Program MSF001RG
*============================================================ * To compile: * * CRTRPGPGM PGM(XXX/MSF001RG) SRCFILE(XXX/QRPGSRC) * *============================================================ *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+.. FMSF001DFCF E WORKSTN * I IDS I B 1 40STKCNT I B 5 80DTALEN I B 9 120ERRCOD *============================================================ * * Do until F3 Key pressed C *IN03 DOUEQ*ON * * Write message subfile and display screen C WRITEMSGCTL C EXFMTSCREEN * * Check for F3 key pressed C *IN03 IFEQ *OFF * * Edit the screen C EXSR EDTSCR * * If no errors then clear screen C *IN90 IFEQ *OFF C CLEARSCREEN C ENDIF * C ENDIF C ENDDO * C MOVE *ON *INLR *============================================================ * Edit the screen *============================================================ C EDTSCR BEGSR * * Clear message subfile C EXSR CLRMSG * * Validate product code C PRCODE IFEQ *BLANKS C MOVE 'MSG0001' MSGID 7 Product code C EXSR SNDMSG not entered C MOVE *ON *IN71 RI PC C MOVE *ON *IN90 Error C ENDIF * * Validate sale price C SLPRCE IFEQ 0 C MOVE 'MSG0002' MSGID Sale price C EXSR SNDMSG not entered C MOVE *ON *IN72 RI PC C MOVE *ON *IN90 Error C ENDIF * * Validate sale start date C CALL 'MSF001CL' C PARM SLDATE C PARM ERFLAG 1 * C ERFLAG IFEQ 'Y' Invalid date C MOVE *ON *IN73 RI PC C MOVE *ON *IN90 Error C END * C ENDSR *============================================================ * Clear message subfile *============================================================ C CLRMSG BEGSR * C CALL 'QMHRMVPM' C PARM PGMQ C PARM STKCNT C PARM MSGKY C PARM MSGRMV C PARM ERRCOD * C ENDSR *============================================================ * Send message to message subfile *============================================================ C SNDMSG BEGSR * C CALL 'QMHSNDPM' C PARM MSGID C PARM MSGF C PARM MSGDTA C PARM DTALEN C PARM MSGTYP C PARM PGMQ C PARM STKCNT C PARM MSGKEY C PARM ERRCOD * C ENDSR *============================================================ * Initialization subroutine *============================================================ C *INZSR BEGSR * C MOVEL'*' PGMQ C MOVEL'MSF001MF'MSGF 20 C MOVEL'*LIBL' MSGLIB 10 C MOVE MSGLIB MSGF C MOVE *BLANKS MSGKY 4 C MOVE *BLANKS MSGDTA 80 C MOVEL'*DIAG' MSGTYP 10 C MOVEL'*ALL' MSGRMV 10 * C ENDSR *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+..
More Powerful Message Subfiles
Figure 5 CL Program MSF001CL
/*===============================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/MSF001CL) SRCFILE(XXX/QCLSRC) */ /* */ /*===============================================================*/ MSF001CL: + PGM PARM(&SLDATE &ERFLAG) DCL VAR(&SLDATE) TYPE(*DEC) LEN(6 0) DCL VAR(&ERFLAG) TYPE(*CHAR) LEN(1) DCL VAR(&DATE) TYPE(*CHAR) LEN(6) DCL VAR(&MSGKEY) TYPE(*CHAR) LEN(4) DCL VAR(&MSGTYP) TYPE(*CHAR) LEN(40) + VALUE('*DIAG *ESCAPE') DCL VAR(&PGMQUE) TYPE(*CHAR) LEN(10) VALUE('*') DCL VAR(&NBRTYP) TYPE(*CHAR) LEN(4) VALUE(X'00000002') DCL VAR(&STKCNT) TYPE(*CHAR) LEN(4) VALUE(X'00000001') DCL VAR(&ERRCOD) TYPE(*CHAR) LEN(4) VALUE(X'00000000') CHGVAR VAR(&ERFLAG) VALUE('N') CHGVAR VAR(&DATE) VALUE(&SLDATE) CVTDAT DATE(&DATE) TOVAR(&DATE) FROMFMT(*MDY) TOFMT(*MDY) + TOSEP(*NONE) MONMSG MSGID(CPF0000) EXEC(DO) CHGVAR VAR(&ERFLAG) VALUE('Y') CALL PGM(QMHMOVPM) PARM(&MSGKEY &MSGTYP &NBRTYP &PGMQUE + &STKCNT &ERRCOD) ENDDO ENDPGM
More Powerful Message Subfiles
Figure 6 Overview of Subfile Message Example
UNABLE TO REPRODUCE GRAPHIC
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online