AS/400-iSeries Starter Kit

In Chapter 26, I talked about processing database files using a CL program. I discussed declaring a file, extracting field definitions (both externally described and program-described), and processing database records. In this chapter, I want to examine how CL programs work with display files.

CL is an appropriate choice for certain situations that require displays. For example, CL works well with display files for menus because CL is the language used to override files, modify a user's library list, submit jobs, and check authorities -- all common tasks in a menu environment.

CL is also a popular choice for implementing a friendly interface at which users can enter parameters for commands or programs that print reports or execute inquiries. For example, a CL program can present an easily understood panel to prompt the user for a beginning and ending date; the program can then format and substitute those dates into a STRQMQRY (Start Query Management Query) command to produce a report covering a certain time period. When you want users to enter substitution values for use in an arcane command such as OPNQRYF (Open Query File), it is almost imperative that you let them enter selections in a format they understand (e.g., a prompt screen) and then build the command string in CL. It is much easier to build and execute complex CL commands in CL than it is in other languages, especially RPG/400 and COBOL/400.

CL Display File Basics

As with a database file, you must use the DCLF (Declare File) command to tell your CL program which display file you want to work with (for more details about declaring a file, see Chapter 26). Declaring the file lets the compiler locate it and retrieve the field and format definitions.

Figure 27.1 shows the DDS for a sample display file, USERMENUF, and Figure 27.2 shows part of a compiler listing for a CL program that declares USERMENUF. The default for DCLF's RCDFMT parameter, *ALL, tells the compiler to identify and retrieve the descriptions for all record formats in the file. Notice that the field and format definitions immediately follow the DCLF statement on the compiler listing.

If your display file has many formats and you plan to use only one or a few of them, you can specify up to 50 different record formats in the RCDFMT parameter instead of using the *ALL default value. Doing so reduces the size of the compiled program object by eliminating unnecessary definitions.

After you declare a display file, you can output record formats to a display device using the SNDF (Send File) command, read formats from the display device using the RCVF (Receive File) command, or perform both functions with the SNDRCVF (Send/Receive File) command. These commands parallel RPG/400's WRITE, READ, and EXFMT opcodes, respectively.

For instance, to present a record format named PROMPT on the display, you could code your CL as

SNDF RCDFMT(PROMPT)
RCVF RCDFMT(PROMPT)

or as

SNDRCVF RCDFMT(PROMPT)

To send more than one format to the screen at once (e.g., a standard header format, a function key format, and an input-capable field), you use a combination of the SNDF and SNDRCVF commands as you would use a combination of WRITE and EXFMT in RPG/400:

SNDF    RCDFMT(HEADER)
SNDF    RCDFMT(FKEYS)
SNDRCVF RCDFMT(DETAIL

Notice that the RCDFMT parameter value in each statement specifies the particular format for the operation. If there is only one format in the file, you can use RCDFMT's default value, *FILE, and then simply use the SNDF, RCVF, or SNDRCVF command without coding a parameter.

CL Display File Examples

Let's look at an example of how to use CL with a display file for a menu and a prompt screen. Figure 27.3 shows a menu based on the DDS in Figure 27.1. From the DDS, you can see that record format MENU displays the list of menu options, and record formats MSGF and MSGCTL control the IBM-supplied message subfile function that sends messages to the program message queue. Record format PROMPT01 is a panel that lets the user enter selection values for Batch Report 1.

Figure 27.4 shows CL program USERMENU, the program driver for this menu. As you can see, USERMENU sets up work variable &pgmq, displays the menu, and then, depending on user input, either executes the code that corresponds to the menu option selected or exits the menu.

The sample menu's menu options, option field, and function key description are all part of the MENU record format on the DDS. To display these fields to the user and allow input, program USERMENU uses the SNDRCVF command (C in Figure 27.4). Should the user enter an invalid menu option, select an option (s)he is not authorized to, or encounter an error, the program displays the appropriate message at the bottom of the screen by displaying message subfile record format MSGCTL (D). (I discuss this record format in more detail in a moment.) Figure 27.5 shows a completion message at the bottom of the sample menu.

The message subfile is a special form of subfile whose definition includes some predefined variables and special keywords. The message subfile record format is format MSGSFL (B in Figure 27.1). The keyword SFLMSGRCD(23) tells the display file to display the messages in this subfile beginning on line 23 of the panel. You can specify any line number for this keyword that is valid for the panel you are displaying.

The associated SFLMSGKEY keyword and the IBM-supplied variable MSGKEY support the task of retrieving a message from the program message queue associated with the SFLPGMQ keyword (i.e., the message queue named in variable PGMQ) and displaying the message in the form of a subfile. The CL program assigns the value USERMENU to variable &pgmq (A in Figure 27.4), thus specifying that the program message queue to be displayed is the one associated with program USERMENU.

MSGCTL, the next record format in the DDS, uses the standard subfile keywords (e.g., SFLSIZ, SLFINZ, SLFDSP) along with the SFLPGMQ keyword. This record format establishes the message subfile for this display file with a SFLSIZ value of 10 and a SFLPAG value of 1. In other words, the message subfile will hold up to 10 messages and will display one message on each page. Because of the value of the SFLMSGRCD keyword in the MSGSFL format, the message will be displayed on line 23. You can alter the SFLMSGRCD and SFLPAG values to display as many messages as you like and have room for on the screen. If more than one page of messages exists, the user can scroll through the pages by pressing Page up and Page down.

You might be asking, "What does program USERMENU have to do to fill the message subfile?" The answer: Absolutely nothing! This fact often confuses programmers new to message subfiles because they can't figure out how to load the subfile. You can think of the message subfile as simply a mechanism by which you can view the messages on the program message queue. By changing the value of variable &pgmq to USERMENU, I specified which program message queue to associate with the message subfile. That's all it takes.

Immediately after D in Figure 27.4, you can see that I change indicator 40 (variable &in40) to &@on and then output format MSGCTL using the SNDF command. In the DDS, indicator 40 controls the SFLINZ and SFLEND keywords (C in Figure 27.1) to initialize the subfile before loading it and to display the appropriate + or blank to let the user know whether more subfile records exist beyond those currently displayed. (You can specify SFLEND(*MORE) if you prefer to have the message subfile use the "More..." and "Bottom" subfile controls after the last record, but be sure your screen has a blank line at the bottom so that these subfile controls can be displayed.)

When the program outputs the MSGCTL format, the PGMQ and MSGKEY variables coded in the MSGSFL record format cause all messages to be retrieved from the program message queue and presented in the subfile. The user can move the cursor onto a message and press the Help key to get secondary text, when it is available, and can scroll through all the error messages in the subfile.

At B in Figure 27.4, the RMVMSG command clears *ALL messages from the current program queue (i.e., queue USERMENU). Clearing the queue at the beginning of the program ensures that old messages from a previous invocation do not remain in the queue.

Figure 27.6 shows a prompt screen a user might receive to specify selections for a menu option that submits a report program to batch. The user keys the appropriate values and presses Enter to submit the report. If the program encounters an error when validating the values, the display file uses an error subfile to display the error message at the bottom of the screen, like the error message in Figure 27.7.

You use the ERRSFL keyword in the DDS (A in Figure 27.1) to indicate an error subfile. An error subfile provides a different function than a message subfile. The error subfile automatically presents any error messages generated as a result of DDS message or validity-checking keywords (e.g., ERRMSG, SFLMSG, CHECK, VALUES). The purpose of the error subfile is to group error messages generated by these keywords for a particular record format, not to view messages on the program message queue. (For more information about error subfiles, see the Data Description Specifications Reference, SC41-9620.)

Considerations

The drawbacks to using CL for display file processing are CL's limited database file I/O capabilities and its lack of support for user-written subfiles. As I explained in Chapter 26, CL can only read database files. The fact that you cannot write or update database file records greatly reduces CL's usefulness in an interactive environment. The lack of support for user-written subfiles also limits its usefulness in applications that require user interaction.

But in many common situations, CL's strengths more than offset these limitations. CL's command processing, message handling, and string manipulation capabilities make it a good choice for menus, prompt screens, and other nondatabase-related screen functions.

While not always appropriate, for many basic interactive applications CL offers a simple alternative to a high-level language for display file processing. With this knowledge under your belt, you can choose the best and easiest language for applications that use display files.