A #GSORT User's Primer to Open Query File

Business Intelligence
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

A #GSORT User's Primer to Open Query File by Ted Holt

Meet #GSORT's Replacement on the AS/400.

The fact that you are reading this article indicates that you probably know your way around #GSORT. Perhaps you've been coding sort specs since the days of the System/3, when the sort program was called $DSORT. You probably got pretty excited when you got a S/34 and learned to work magic in your sort routines with conditional OCL. You may be a little dismayed, however, to find that the AS/400 relegates #GSORT to a second class status. Relax and rejoice! OS/400 has something much better -- Open Query File (OPNQRYF). And just as you became a #GSORT guru, you can become an OPNQRYF guru.

Why OPNQRYF is Better

OPNQRYF is a much better tool than #GSORT (FMTDTA on the AS/400) for several reasons. One, OPNQRYF uses external file definitions, not field starting and ending positions. This means that you will not usually have to revise OPNQRYF commands when you change a file's record layout (for example, to increase the size of a field).

Two, OPNQRYF has more powerful record selection techniques. The %RANGE and %VALUE functions, for instance, are much easier to use than multiple include/omit lines. In addition, you can use parentheses to clean up even the messiest and/or logic.

Three, OPNQRYF can sort on calculated fields. It can also join two files and sort on fields from both files. The S/34 and S/36 require that you build a work file with another high-level language program before beginning the sort.

Four, OPNQRYF includes a number of useful functions, such as summarizing and averaging, as well as some which are not so useful in your everyday work, such as trigonometric functions and logarithms. These reduce High Level Language (HLL) coding, and may sometimes provide the only solution to a problem.

Five, OPNQRYF does not build a physical file. Instead, it creates an open data path through which the high-level program will access the data. There is no need to be concerned about temporary files remaining on the disk taking up space.

Six, because OPNQRYF is a CL command, its syntax is free-format. That is, there is no need to worry about aligning certain entries in certain columns. Anyone who has struggled with the alignment of parameters and other substitution expressions within sort specs can understand the superiority of free-format coding.

Comparing OPNQRYF to #GSORT

To help you start on your way to mastering OPNQRYF, let's look at a few simple sort examples. We'll look at the #GSORT code first, to familiarize ourselves with the particular sort situation. Then we'll see the same thing using OPNQRYF. These examples will use a simple sales history file, which is described in 1. The DDS needed to build the file is shown in 2.

To help you start on your way to mastering OPNQRYF, let's look at a few simple sort examples. We'll look at the #GSORT code first, to familiarize ourselves with the particular sort situation. Then we'll see the same thing using OPNQRYF. These examples will use a simple sales history file, which is described in Figure 1. The DDS needed to build the file is shown in Figure 2.

Suppose we wish to sort our sales data by customer number. We would write the code shown in 3a. (The examples will show tag-along sorts, but they will apply as easily to addrout sorts).

Suppose we wish to sort our sales data by customer number. We would write the code shown in Figure 3a. (The examples will show tag-along sorts, but they will apply as easily to addrout sorts).

The CL code needed to accomplish the same thing is shown in 3b. The Override Database File (OVRDBF) command makes the sales history file a shared file. In other words, when the HLL program opens SLSHIST, it will share the open data path (ODP) created by the OPNQRYF command.

The CL code needed to accomplish the same thing is shown in Figure 3b. The Override Database File (OVRDBF) command makes the sales history file a shared file. In other words, when the HLL program opens SLSHIST, it will share the open data path (ODP) created by the OPNQRYF command.

The OPNQRYF command does not retrieve data. Rather, it establishes an ODP through which data can be accessed. The data is then retrieved by the HLL program, which will open and close the file as usual. Any file that is accessed through an OPNQRYF ODP must be processed by key so in the case of an RPG program you will want to specify a 'K' in Record Address Type (column 31 of the F specification for the file).

The Close File (CLOF) command closes the ODP. At this point, the override is no longer needed, and it may be deleted, if desired.

This example illustrates the superiority of external file definitions. If the beginning or ending position of CUSNBR is ever changed, someone will have to modify the #GSORT specifications, but the OPNQRYF will require no modification.

Let's compare record selection. 4a shows the sort specs required to process records for item 34341. The OPNQRYF equivalent (4b) uses the QRYSLT parameter to accomplish the same thing. Since ITMNBR is a numeric field, no quotes are needed to delimit the item number. If ITMNBR were a character field, we would surround it with quotes (QRYSLT('ITMNBR *EQ "34341"')) or double apostrophes (QRYSLT('ITMNBR *EQ ''34341''')).

Let's compare record selection. Figure 4a shows the sort specs required to process records for item 34341. The OPNQRYF equivalent (Figure 4b) uses the QRYSLT parameter to accomplish the same thing. Since ITMNBR is a numeric field, no quotes are needed to delimit the item number. If ITMNBR were a character field, we would surround it with quotes (QRYSLT('ITMNBR *EQ "34341"')) or double apostrophes (QRYSLT('ITMNBR *EQ ''34341''')).

You've probably dazzled your users by letting them specify record selection and maybe even sort sequence from a prompt screen. 5a contains such an OCL procedure. Parameter 1 tells which field is to be the sort field, and parameter 2 tells which item to select. If parameter 2 is left blank or contains the value 0, all items will be included. Parameter 51 is the sort field's starting position, parameter 52 the ending position, and parameter 53 is the field's length.

You've probably dazzled your users by letting them specify record selection and maybe even sort sequence from a prompt screen. Figure 5a contains such an OCL procedure. Parameter 1 tells which field is to be the sort field, and parameter 2 tells which item to select. If parameter 2 is left blank or contains the value 0, all items will be included. Parameter 51 is the sort field's starting position, parameter 52 the ending position, and parameter 53 is the field's length.

The OPNQRYF version (5b) is far superior. It is easier to read, and will require no modifications should the file layout change. There is no need to calculate beginning and ending positions and the sort field length. In addition, you do not have to worry about getting the parameters to line up in the correct columns.

The OPNQRYF version (Figure 5b) is far superior. It is easier to read, and will require no modifications should the file layout change. There is no need to calculate beginning and ending positions and the sort field length. In addition, you do not have to worry about getting the parameters to line up in the correct columns.

Now let's look at a couple of things that OPNQRYF will do that #GSORT won't do: 1) It will sort on a derived field and, 2) it will sort on fields from different files.

An example of sorting on a derived field is illustrated in 7. It requires another file format, shown in 6. The WORK1 file would have to be compiled, even though it would not contain any data. (Since it won't contain data, we compile it with the MBR(*NONE) option). The dummy (or shell) file, WORK1, is specified in three places: (1) the high-level language program (as an input file); (2) the FILE parameter of the OVRDBF command; and (3) the FORMAT parameter of the OPNQRYF command. The file containing the actual data, SLSHIST, is specified in the TOFILE parameter of the OVRDBF command and the FILE parameter of the OPNQRYF command.

An example of sorting on a derived field is illustrated in Figure 7. It requires another file format, shown in Figure 6. The WORK1 file would have to be compiled, even though it would not contain any data. (Since it won't contain data, we compile it with the MBR(*NONE) option). The dummy (or shell) file, WORK1, is specified in three places: (1) the high-level language program (as an input file); (2) the FILE parameter of the OVRDBF command; and (3) the FORMAT parameter of the OPNQRYF command. The file containing the actual data, SLSHIST, is specified in the TOFILE parameter of the OVRDBF command and the FILE parameter of the OPNQRYF command.

The MAPFLD parameter tells OPNQRYF to calculate the extended price (a virtual, or nonexistent, field) by multiplying the quantity ordered by the unit price. This virtual field becomes the basis for the sort.

An example of sorting on fields from two different files is illustrated in 9. A file, WORK2 (8), must be created in order to contain information from both files (a customer master file and the sales history file -- SLSHIST). The primary sort key, customer name, comes from the customer master file, and the secondary sort key, order number, comes from the SLSHIST file. The JFLD parameter tells which fields to use in joining the file. JDFTVAL(*YES) tells OPNQRYF to build a record with a blank customer name if the join fails (i.e., no customer number is found in the customer master file to match a customer number in the SLSHIST file). The MAPFLD parameter is needed to tell OPNQRYF from which file to retrieve the customer number.

An example of sorting on fields from two different files is illustrated in Figure 9. A file, WORK2 (Figure 8), must be created in order to contain information from both files (a customer master file and the sales history file -- SLSHIST). The primary sort key, customer name, comes from the customer master file, and the secondary sort key, order number, comes from the SLSHIST file. The JFLD parameter tells which fields to use in joining the file. JDFTVAL(*YES) tells OPNQRYF to build a record with a blank customer name if the join fails (i.e., no customer number is found in the customer master file to match a customer number in the SLSHIST file). The MAPFLD parameter is needed to tell OPNQRYF from which file to retrieve the customer number.

Limitations of OPNQRYF

Because OPNQRYF creates an open data path, not a physical file, it is restricted in ways that #GSORT is not. For example, the output of #GSORT could be used as input to a S/36 procedure such as TRANSFER, UPDATE, LISTDATA, etc. This would not work using OPNQRYF because, (1) OPNQRYF requires that a HLL program retrieve the data and, (2) certain system functions, such as CPYF and DSPPFM, will not share an existing open data path.

You can also use #GSORT to build a file which can be processed by other batch jobs or interactive jobs running at other terminals. Again, you will not be able to use OPNQRYF in the same way.

In each case, an HLL program would have to read the results of the OPNQRYF command into a physical file, which could then be copied to diskette or used by other jobs. Since the vast majority of your FMTDTA jobs are probably of the "sort-and-report" variety, you probably won't find these limitations to be a problem. OPNQRYF is not always the fastest access method. FMTDTA, the AS/400's reincarnation of #GSORT, may offer faster processing especially when processing large files.

Your Challenge

I hope these few simple examples have convinced you that OPNQRYF really is superior to #GSORT. And without a doubt, anyone who can make #GSORT do tricks has the ability to make OPNQRYF get up and walk! Well, #GSORT wizard. You now have a new challenge: become an OPNQRYF wizard. Oh, and by the way, tell your users that they "ain't seen nothin' yet."


A #GSORT User's Primer to Open Query File

Figure 1 Simple sales history file

 Figure 1: Simple Sales History File Field Name Type Start End Dec Comment Order Number ORDNBR zoned 1 6 0 Customer number CUSNBR char 7 10 Date of sale SLSDAT zoned 11 16 0 (YYMMDD) Item number ITMNBR zoned 17 21 0 Quantity QTY packed 22 25 0 Unit price UPRICE packed 26 30 2 
A #GSORT User's Primer to Open Query File

Figure 2 DDS for Sales History File

 Figure 2: DDS for Sales History File A R SLSHISTR A ORDNBR 6S 0 TEXT('Order number') A CUSNBR 4 TEXT('Customer number') A SLSDAT 6S 0 TEXT('Sales date') A ITMNBR 5S 0 TEXT('Item number') A QTY 7 0 TEXT('Quantity ordered') A UPRICE 9 2 TEXT('Unit price') 
A #GSORT User's Primer to Open Query File

Figure 3A Sorting Sales Data by customer number with #GSORT

 Figure 3a: Sorting Sales Data by Customer Number With #GSORT // LOAD #GSORT // FILE NAME-INPUT,LABEL-SLSHIST // FILE NAME-OUTPUT,LABEL-SORTFILE,etc. // RUN HSORTR 4A 3X 30 N FNC 7 10 CUSNBR FDC 1 30 // END // LOAD HLLPGM // FILE NAME-SLSHIST,LABEL-SORTFILE // RUN 
A #GSORT User's Primer to Open Query File

Figure 3B Sorting Sales Data by customer number with OPNQRYF

 Figure 3b: Sorting Sales Data by Customer Number With OPNQRYF PGM OVRDBF FILE(SLSHIST) SHARE(*YES) OPNQRYF FILE((SLSHIST)) KEYFLD((CUSNBR)) CALL HLLPGM CLOF OPNID(SLSHIST) DLTOVR FILE(SLSHIST) ENDPGM 
A #GSORT User's Primer to Open Query File

Figure 4A Record selection with #GSORT

 Figure 4a: Record Selection With #GSORT HSORTR 4A 3X 30 N I C 17 21EQC34341 FNC 7 10 CUSNBR FDC 1 30 
A #GSORT User's Primer to Open Query File

Figure 4B Record selection with OPNQRYF

 Figure 4b: Record Selection With OPNQRYF PGM OVRDBF FILE(SLSHIST) SHARE(*YES) OPNQRYF FILE((SLSHIST)) + QRYSLT('ITMNBR *EQ 34341') + KEYFLD((CUSNBR)) CALL HLLPGM CLOF OPNID(SLSHIST) DLTOVR FILE(SLSHIST) ENDPGM 
A #GSORT User's Primer to Open Query File

Figure 5A S/36 style prompt for #GSORT record selection

 Figure 5a: S/36-Style Prompt for #GSORT Record Selection and Sort Sequence * P1 = SORT FIELD (ITEM, CUST, ORDER) DEFAULT IS ITEM * P2 = ITEM TO SELECT (0 OR NULL = ALL) * P51 = BEGINNING POSITION OF SORT FIELD * P52 = ENDING POSITION OF SORT FIELD * P53 = LENGTH OF SORT FIELD * // IF ?1?=CUST EVALUATE P51,4=7 P52,4=10 // ELSE IF ?1?=ORDER EVALUATE P51,4=1 P52,4=6 // ELSE EVALUATE P51,4=17 P52,4=21 (ITEM) * // EVALUATE P53,4=?52?+1-?51? calculate field length * // LOAD #GSORT // FILE NAME-INPUT,LABEL-SLSHIST // FILE NAME-OUTPUT,LABEL-SORTFILE,etc. // RUN HSORTR ?53?A 3X 30 N // IF ?2'0'?=0 GOTO SKIP I C 17 21EQC?2? // TAG SKIP FNC?51??52? FDC 1 30 // END // LOAD HLLPGM // FILE NAME-SLSHIST,LABEL-SORTFILE // RUN 
A #GSORT User's Primer to Open Query File

Figure 5B Record selection prompting with OPNQRYF

 Figure 5b: Record Selection and Sort Sequence Prompting with OPNQRYF PGM PARM(&SORTSEQ &SLT_ITEM) DCL &SORTSEQ *CHAR 10 DCL &SORTFIELD *CHAR 10 DCL &SLT_ITEM *DEC ( 5 0 ) DCL &C_ITEM *CHAR 5 DCL &QRYSLT *CHAR 256 IF (&SORTED *EQ 'CUST') + (CHGVAR &SORTFIELD 'CUSNBR') ELSE IF (&SORTSEQ *EQ 'ORDER') (CHGVAR &SORTFIELD 'ORDER') ELSE + (CHGVAR &SORTFIELD 'ITMNBR') IF (&SLT_ITEM *EQ 0) + CHGVAR &QRYSLT '*ALL' ELSE DO CHGVAR &C_ITEM &SLT_ITEM CHGVAR &QRYSLT ('ITMNBR=' *CAT &C_ITEM) OVRDBF FILE(SLSHIST) SHARE(*YES) OPNQRYF FILE((SLSHIST)) QRYSLT(&QRYSLT) + KEYFLD((&SORTFIELD)) CALL HLLPGM CLOF OPNID(SLSHIST) DLTOVR FILE(SLSHIST) ENDPGM 
A #GSORT User's Primer to Open Query File

Figure 6 Work file format for WORK1

 Figure 6: Work File Format for WORK1 A* WORK FILE A* ORDER FILE WITH EXTENDED PRICE A* MAY BE COMPILED WITH MBR(*NONE) A REF(SLSHIST) A R WORK1R A ORDNBR R A CUSNBR R A SLSDAT R A ITMNBR R A QTY R A UPRICE R A XPRICE 11 2 TEXT('Extended price') 
A #GSORT User's Primer to Open Query File

Figure 7 OPNQRYF sorting on a derived field

 Figure 7: OPNQRYF Sorting on a Derived Field PGM OVRDBF FILE(WORK1) TOFILE(SLSHIST) SHARE(*YES) OPNQRYF FILE((SLSHIST)) + FORMAT(WORK1) + KEYFLD((XPRICE *DESCEND)) + MAPFLD((XPRICE 'QTY * UPRICE')) CALL HLL2 CLOF OPNID(SLSHIST) DLTOVR FILE(WORK1) ENDPGM 
A #GSORT User's Primer to Open Query File

Figure 8 Work file format for WORK2

 Figure 8: Work File Format for WORK2 A* WORK FILE A* ORDER FILE WITH CUSTOMER NAME A* MAY BE COMPILED WITH MBR(*NONE) A REF(SLSHIST) A R WORK2R A ORDNBR R A CUSNBR R A SLSDAT R A ITMNBR R A QTY R A UPRICE R A CUSNAM R REFFLD(CMFMT/CUSNAM CUSMAST) 
A #GSORT User's Primer to Open Query File

Figure 9 Using OPNQRYF to sort on fields from two files

 Figure 9: Using OPNQRYF to Sort on Fields From Two Files PGM OVRDBF FILE(WORK2) TOFILE(SLSHIST) SHARE(*YES) OPNQRYF FILE((SLSHIST) (CUSMAST)) + FORMAT(WORK2) + KEYFLD((CUSNAM) (ORDNBR)) + JFLD(SLSHIST/CUSNBR CUSMAST/CUSNBR) + JDFTVAL(*YES) + MAPFLD((CUSNBR 'SLSHIST/CUSNBR')) CALL HLL3 CLOF OPNID(SLSHIST) DLTOVR FILE(WORK2) ENDPGM 
BLOG COMMENTS POWERED BY DISQUS