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
Rafael Victória-Pereira has more than 20 years of IBM i experience as a programmer, analyst, and manager. Over that period, he has been an active voice in the IBM i community, encouraging and helping programmers transition to ILE and free-format RPG. Rafael has written more than 100 technical articles about topics ranging from interfaces (the topic for his first book, Flexible Input, Dazzling Output with IBM i) to modern RPG and SQL in his popular RPG Academy and SQL 101 series on mcpressonline.com and in his books Evolve Your RPG Coding and SQL for IBM i: A Database Modernization Guide. Rafael writes in an easy-to-read, practical style that is highly popular with his audience of IBM technology professionals.
Rafael is the Deputy IT Director - Infrastructures and Services at the Luis Simões Group in Portugal. His areas of expertise include programming in the IBM i native languages (RPG, CL, and DB2 SQL) and in "modern" programming languages, such as Java, C#, and Python, as well as project management and consultancy.
MC Press books written by Rafael Victória-Pereira available now on the MC Press Bookstore.
 |
||
 |
|
Evolve Your RPG Coding: Move from OPM to ILE...and Beyond Transition to modern RPG programming with this step-by-step guide through ILE and free-format RPG, SQL, and modernization techniques. List Price $79.95 Now On Sale
|
|
||
 |
|
Flexible Input, Dazzling Output with IBM i Uncover easier, more flexible ways to get data into your system, plus some methods for exporting and presenting the vital business data it contains. List Price $79.95
Now On Sale
|
|
||
 |
|
SQL for IBM i: A Database Modernization Guide Learn how to use SQL’s capabilities to modernize and enhance your IBM i database. List Price $79.95
Now On Sale
|
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