ANSI Standard PL/B Language and Visual PL/B
FILELIST
NOTE TO OUR READERS
This web resource is written for our own use. But we feel strongly that the PL/B language should be shared with the software community. So feel free to use this at will!
BUT PLEASE...
if you find errors or omissions or have a better way to do something. TELL US! Dialog helps us all. Send e-mail to:
support@mmcctech.com
Other links:
FILELIST:
-
This is a SUNBELT ONLY language feature.
CONCEPT OF USE
The FILELIST instruction is a method for updating multiple indexes to the same text file.
In traditional PL/B programming, you'd define TWO (or more) indexed files and process them separately. One file would be the primary and the other(s) would be secondary indexes. Records would be WRITTEN into the primary file then the secondary record keys would be INSERTED into the secondary index(s).
With a FILELIST you still define the multiple files, but you list them inside a FILELIST container:
WORK_ORDER_FILES FILELIST
WO_HEADER IFILE
WO_PART_ISI IFILE
FILELISTEND
Note the following things concerning the
IFILE statement within a FILELIST.
- The files are listed in a specific order. The PRIMARY index must be first. All other files in the FILELIST are considered secondary indexes.
OPENING FILES
Once the files are defined, they are opened in two ways. First, the files can be opened in one shot at the FILELIST level. That is, using the above example the open would be:
OPEN WORK_ORDER_FILES
Secondly, the files can be opened individually by name. Again using the example the opens would be:
OPEN WO_HEADER,{filename},{mode}
OPEN WO_PART_ISI,{filename},{mode}
Note the following things concerning the
IFILE statement within a FILELIST.
INDEX KEYS
For the FILELIST processing to work, the runtime must know the key structure of all of the files which are members of the FILELIST. These keys are obtained from the
.ISI file iteslf. You can get the keys into the file in two ways.
First, you can prep the file using a key. The key must be in the form "n-n". In a non-filelist prep you can give the key as just a length. That is:
- when file defined outside of a FILELIST:
PREP TESTFILE,"test-isi","test-isi","10","30"
- when file defined within a FILELIST
PREP TESTFILE,"test-isi","test-isi","1-10","30"
As a point of standards, it would be good practice to always PREP indexed files using the second format. This is true even if the file is not used in a FILELIST. It doesn't impose any limits and it does insure that when a FILELIST is added to the system later, the index will be ready. (The exception is where the programs must be compatible with non-Sunbelt compilers.)
Second, you can use the SUNINDEX or SUNIDXNT to externally create the ISI file.
NOTE:When you create the ISI file with the index utility, you can later re-index the file using the "R" parameter. You CANNOT use the "R" index parameter when the file was prepped internally, regardless of how you specify the keys.
An example of the "R" method would be:
- initially index the file via something like:
SUNINDEX test-isi;1-10,15-18,13,11-12
- anytime after that you can reindex via:
SUNINDEX test-isi;R
Again, when you create the ISI file with a PREP within the program, the FILELIST will work but you cannot SUNINDEX using the "R" parameter. SUNINDEX reports that there are no key specifications in this type of file.
OTHER NOTES
You can PREP any individual file by name, even when the file is defined within in a FILELIST.
You CANNOT directly write or update or delete records to a file which is defined within a FILELIST. If you want to write to an individual file that's part of a FILELIST, you'll have to define it again and separately outside of the FILELIST.
READ, READKS, READKP may all be done to the individual file names. They are NOT done at the FILELIST level since the reads address a specific record, not the collection of records identifed by the FILELIST group.
FILEIO may be used in place of the READ, READKS, READKP. If you try to do a FILEIO for WRITE or UPDATE operations you will get a runtime error.
This is a stub that was used for testing.... it's left here as a reminder only:
- Define primary and secondary files WITHIN a filelist.
the NAME= parameter is not required if you're not going to open using the filelist name.
- Prep secondary file with key
- Prep primary with key
- Write the FILELIST (you can't write the individual file)
- Close primary
- Close secondary
- Open either file by name (not by file list)
- read or readks against the file
FILELIST Examples
.......................................................
. TESTPREP 10/17/2001
. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
. ³ TEST ISI PREPS TO SEE HOW TO DEFINE THE KEY ³
. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
.
INCLUDE Z:COMMON
INCLUDE REVISION.DBS
.
.............................................
. The following EQU's are to allow the test program
. to be compiled with and without various sections
. of code just to see what happens.
.
PREP_ROUTINE EQU 0
WRITE_ROUTINE EQU 0
UPDATE_ROUTINE EQU 1
READ_ROUTINE EQU 1
.
NUL DIM 1
.
.....................................
. Define the files in the list.
. Note that the NAME= parameter is NOT used.
. Instead, the files will be PREPPED or OPENED individually
.
IFILE_LIST FILELIST
IFILE IFILE ;primary file
IFILE2 IFILE ;secondary index
FILELISTEND
.
I_RECORD LIST
I_KEY DIM 15 ;primary record key
I_DATA DIM 20 ;We'll just put a timestamp here.
I_SEQUENCE FORM 4 ;This will be the secondary index key
I_DOT INIT "." ;just to show end of record when listing.
LISTEND
.
WINSHOW ;we'll run this on the main screen
INCLUDE COLR-BAR ;mmcc's color information (not required)
.
DISPLAY "TESTPREP BEGINS"
.
.........................
.
%IF PREP_ROUTINE > 0
DISPLAY "PREP ZZ-ISI2 secondary index"
PREP IFILE2,"ZZ-ISI","ZZ-ISI2", "36-39", "40"
.
DISPLAY "PREP ZZ-ISI primary index"
PREP IFILE, "ZZ-ISI","ZZ-ISI", "1-15","40"
.
...............
. Create a group of test records counting up.
.
MOVE " 20",I_SEQUENCE ;starting 2ndary key.
MOVE "100",NWK03 ;starting unique part of prime key
LOOP
PACK I_KEY, NWK03," A B C ",SPACES ;build up the key
CALL WRITE_FILELIST ;write the LIST & increment NWK03
IF (NWK03 > 110) ;is this enough for the test?
BREAK ;yep... stop now
ENDIF
ADD "10",NWK03 ;increment PRIMARY KEY
REPEAT
.
...............
. Create a SECOND group of test records counting down.
. This should give a nice mix of records
.
MOVE "151",NWK03 ;second group of primary keys
LOOP
PACK I_KEY, NWK03," A B C ",SPACES ;build up key
CALL WRITE_FILELIST ;write the LIST & increment NWK03
IF (NWK03 < 110) ;is this enough for the test?
BREAK ;yep... stop now
BREAK
ENDIF
SUB "8",NWK03 ;decrement PRIMARY key
REPEAT
.
DISPLAY "CLOSE IFILE" ;first set of records are done
CLOSE IFILE
CLOSE IFILE2
.
KEYIN "Original PREP & WRITE done. Tap any key ",*+,REPLY,*-
%ENDIF
.
.........................
. Second test will re-open the files which were prepped above.
. We'll just write another group of records.
.
%IF WRITE_ROUTINE > 0
DISPLAY "Write routine... see how to open existing files ":
"for I/O."
.
DISPLAY "OPEN ZZ-ISI2 secondary index"
OPEN IFILE2,"ZZ-ISI2" ,"ZZ-ISI2", "36-39", "40"
.
DISPLAY "OPEN ZZ-ISI primary index"
OPEN IFILE, "ZZ-ISI" ,"ZZ-ISI", "15","40"
.
MOVE " 20",I_SEQUENCE ;start 2ndary key at same point
MOVE "500",NWK03 ;new group of prime keys
LOOP
PACK I_KEY, NWK03," A B C ",SPACES ;build up key
CALL WRITE_FILELIST ;write the LIST & increment NWK03
IF (NWK03 > 520) ;is this enough
BREAK ;yep... stop now
ENDIF
ADD "10",NWK03 ;increment prime key
REPEAT
.
DISPLAY "CLOSE IFILE"
CLOSE IFILE
CLOSE IFILE2
.
KEYIN "OPEN and WRITE routine done. Tap any key ",REPLY
%ENDIF
.
..............................................
. This routine reads back the primary key file.
. The data and the secondary key are displayed for each record.
. The user can enter a different secondary key.
. If they do, then the files are updated.
. That should take care of both ISIs.
.
%IF UPDATE_ROUTINE > 0
DISPLAY "Update routine... ":
"See how the indexes are updated."
.
DISPLAY "OPEN ZZ-ISI2 secondary index"
OPEN IFILE2,"ZZ-ISI2" ,"ZZ-ISI2", "36-39", "40"
.
DISPLAY "OPEN ZZ-ISI primary index"
OPEN IFILE, "ZZ-ISI" ,"ZZ-ISI", "15","40"
.
DISPLAY "You can change the secondary key on any record ":
"by keying a new value."
.
LOOP
READKS IFILE;I_RECORD
BREAK IF OVER
.
DISPLAY "KEY:",*HON,*LL,I_KEY, *PL,*HOFF:
" D:", *HON,*LL,I_DATA, *PL,*HOFF;
.
MOVE I_SEQUENCE,NWK04
KEYIN " Seq:",*HON,*DVRV=I_SEQUENCE,*HOFF," ";
IF (I_SEQUENCE != NWK04)
DISPLAY " UPDATE"
CALL UPDATE_FILELIST
ELSE
DISPLAY SPACE
ENDIF
REPEAT
.
DISPLAY "CLOSE IFILEs"
CLOSE IFILE
CLOSE IFILE2
.
KEYIN "OPEN and UPDATE routine done. Tap any key ",REPLY
%ENDIF
.
...................................
. This routine just opens the files one at a time and displays
. all of the records on screen for confirmation
.
%IF READ_ROUTINE > 0
MOVE "ZZ-ISI",FILENAME
DISPLAY "Read back PRIMARY index:",*HON,*LL,FILENAME,*PL,*HOFF
OPEN IFILE,FILENAME,READ
LOOP
READKS IFILE;TITLE_LINE
BREAK IF OVER
DISPLAY *HON,*LL,TITLE_LINE,*PL,*HOFF
REPEAT
KEYIN "Tap any to read back ISI2",*+,REPLY,*-
.
...................................
.
MOVE "ZZ-ISI2",FILENAME
DISPLAY "Read back SECONDARY index:",*HON,*LL,FILENAME,*PL,*HOFF
OPEN IFILE,FILENAME,READ
LOOP
READKS IFILE;TITLE_LINE
BREAK IF OVER
DISPLAY *HON,*LL,TITLE_LINE,*PL,*HOFF
REPEAT
DISPLAY "End of readback "
%ENDIF
.
KEYIN "End of TESTPREP ",*+,REPLY,*-
STOP
.
................
.
write_filelist
CLOCK TIMESTAMP,I_DATA
ADD "12",I_SEQUENCE
DISPLAY " Write key:",*HON,*LL,I_KEY,*PL,*HOFF:
" ",*HON,I_SEQUENCE,*HOFF
WRITE IFILE_LIST; I_RECORD
RETURN
.
................
.
update_filelist
CLOCK TIMESTAMP, I_DATA
UPDATE IFILE_LIST;I_RECORD
RETURN
v1.10