File Access and Record Manipulation

Chapter 7

Presentation Copyright 2002, Bryan Meyers

Objectives
Define sequential and random file access Discuss file maintenance Define record locking

Programming in RPG IV Third Edition

READ (Read a Record)

Factor 2 specifies file name
For externally described files, Factor 2 can be a record format name

%EOF function signals end-of-file %ERROR function signals file I/O error
Requires (E) extender
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 /FREE READ(E) CustMast; SELECT; WHEN %ERROR; // Error processing goes here WHEN %EOF(CustMast); // End-of-file processing goes here OTHER; // Record processing goes here ENDSL; /END-FREE
Programming in RPG IV Third Edition 3

SETLL (Set Lower Limit)

SETLL positions a file at the first record with a key greater than or equal to the value specified in Factor 1
Allows you to begin sequential processing at a record other than the first on in the file To reposition the file to the beginning, use figurative constant *LOVAL as Factor 1

Does not actually retrieve a record

Simply positions the file Can be used to determine whether or not a record exists without actually reading it
Programming in RPG IV Third Edition 4

SETLL (Set Lower Limit)

%FOUND is turned on when a record in the file has a key equal to or greater than Factor 1 %EQUAL comes on if a record is in the file whose key exactly matches Factor 1 %ERROR function signals file I/O error
Requires (E) extender

Programming in RPG IV Third Edition

SETLL (Set Lower Limit)

*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 /FREE SETLL(E) CustIn CustMast; SELECT; WHEN %ERROR(CustMast); EXSR SystemErr; WHEN %EQUAL(CustMast); EXSR ExactMatch; WHEN %FOUND(CustMast); EXSR GTMatch; OTHER; EXSR ValueTooHi; ENDSL; /END-FREE

Programming in RPG IV Third Edition

SETGT (Set Greater Than)

SETLL positions a file at the first record with a key is greater than Factor 1
To reposition the file to the end, use figurative constant *HIVAL as Factor 1

Does not actually retrieve a record

Simply positions the file

Programming in RPG IV Third Edition

SETGT (Set Greater Than)

%FOUND is turned on if a record in the file has a key greater than Factor 1 %EQUAL does not apply %ERROR signals file I/O error
Requires (E) extender
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 /FREE SETGT(E) CustIn CustMast; SELECT; WHEN %ERROR; EXSR SystemErr; WHEN %FOUND(CustMast); EXSR GTMatch; OTHER; EXSR ValueTooHi; ENDSL; /END-FREE
Programming in RPG IV Third Edition 8

READE (Read Equal Key)

READE sequentially reads the next record if the key matches Factor 1
Applies only to full procedural files Used to process sets of records with duplicate keys

Programming in RPG IV Third Edition

READE (Read Equal Key)

%EOF is turned on if the record keys do not match
Or if file is at end-of-file

%EQUAL function is turned on if the record keys match %ERROR signals file I/O error
Requires (E) extender
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 /FREE SETLL InDate Orders; IF %EQUAL; READE InDate Orders; DOW NOT %EOF(Orders); EXCEPT OrderLine; READE InDate Orders; ENDDO; ELSE; EXCEPT NoOrders; ENDIF; /END-FREE
Programming in RPG IV Third Edition 10

READP and READPE

READP (Read previous)
Same as READ, but reads backwards, from end to beginning

READPE (Read previous equal)

Same as READE, but reads backwards, from end to beginning

%EOF function signals beginning of file You can also use READPE with Factor 1 blank
Position the file first with an input operation
Programming in RPG IV Third Edition 11

CHAIN (Random File Retrieval)

Literal or data item name in Factor 1 contains key value of record to be randomly read %FOUND function is turned on if the CHAIN is successful CHAIN positions the file in a manner similar to the SETLL
CHAIN reads the record
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 /FREE CHAIN CustNbr CustMaster; IF %FOUND(CustMaster); EXSR CustFound; ELSE; EXSR NoCust; ENDIF; /END-FREE
Programming in RPG IV Third Edition 12

KLIST and KFLD

KLIST (Key List) operation defines a field as a composite key
Factor 1 specifies the name of the KLIST

At least one KFLD (Define parts of a key) operation immediately follows KLIST
Declares a field that is part of the key
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq.... C StdSemCrs KLIST C KFLD Student C KFLD Smster C KFLD Course ... /FREE CHAIN StdSemCrs StudGrades; /END-FREE
Programming in RPG IV Third Edition 13

KLIST and KFLD

KFLD order determines the order of fields which are concatenated to form the KLIST KLIST can be used to access a file on a partial key list
Provided the portion you want is the major, or highorder key field(s)
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq.... C StdSem KLIST C KFLD Student C KFLD Smster ... /FREE CHAIN StdSem StudGrades; /END-FREE
Programming in RPG IV Third Edition 14

Output Files
File Specification
O (output) in position 17 If you are adding records to a file that already contains records, enter an A in position 20 If the file is externally described, code an E in position 22 If the file is keyed, code a K in position 34 Code DISK as the device (36-42)
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++ FCustMast O E K DISK
Programming in RPG IV Third Edition 15

EXCEPT (Exception Output)

Similar to printing a line except the data is written to a database file O Specifications contain the record name and the exception name
List specific fields you want to add
Or *ALL

To append records to an existing file, use the ADD keyword in positions 18-20
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 OFilename++DF..N01N02N03Excnam++++B++A++Sb+Sa+............................. O..............N01N02N03Field+++++++++YB.End++PConstant/editword/DTformat++ OCustRecordEADD Record O *ALL
Programming in RPG IV Third Edition 16

WRITE (Write a Record)

Use a WRITE operation to add records to a file The WRITE operation requires a recordformat name, rather than a file name %ERROR function signals a file I/O error
Requires (E) extender
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 /FREE WRITE CustRecord; /END-FREE
Programming in RPG IV Third Edition 17

DELETE (Delete Record)

The DELETE operation deletes a single record from the file specified in Factor 2
Logically deletes records, rather than physically removing them

If Factor 1 is blank, the most recently read record is deleted If duplicate records based on the Factor 1 value exist in the file, the system deletes only the first record
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 /FREE CustNbr = '100'; DELETE(E) CustNbr CustMaster; IF %ERROR(CustMaster); //Error processing goes here ENDIF; /END-FREE
Programming in RPG IV Third Edition 18

Update Files
Support both input and output operations File Specifications
U (update) in position 17 If you are adding records to a file that already contains records, enter A in position 20 Code E in position 22 for externally described file Code K in position 34 for keyed file
Otherwise arrival sequence is assumed

Code DISK as the device (36-42)

*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++ FCustMast UF E K DISK
Programming in RPG IV Third Edition 19

UPDATE (Modify Existing Record)

Modifies the record most recently read
Used only with update files Must have previously successfully retrieved a record

Does not use Factor 1 Factor 2 must contain a record format name
If file is externally described
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 /FREE CHAIN CustNbr CustMaster; IF %FOUND(CustMaster); BalanceDue = BalanceDue + InvoiceAmt; UPDATE CustRecord; ENDIF; /END-FREE
Programming in RPG IV Third Edition 20

UPDATE (Modify Existing Record)

UPDATE causes the current program values of all the records fields to be rewritten to the file
Use EXCEPT instead when you want to designate specific fields to be rewritten

Cannot issue multiple UPDATEs for a single read operation

Programming in RPG IV Third Edition

21

File and Record Locking

When two users access the same file and update the same record, one of the users changes might get lost
Phantom update

File locking limits file access to one user at a time

Not usually practical

Record locking limits access to a specific record

Programming in RPG IV Third Edition 22

Record Locking
If your program designates a file as an update file, RPG IV automatically places a lock on a record when it is read When a record is locked, other application programs can only access that record if they have defined the file as an input file Updating that record or reading another record releases the record from its locked state

Programming in RPG IV Third Edition

23

File and Record Locking

Use the (N) extender to specify that a retrieval operation should not lock a record in an update file
Use with care

UNLOCK, OPEN, and CLOSE also control locking

*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 /FREE CHAIN(N) CustNbr CustMaster; /END-FREE
Programming in RPG IV Third Edition 24

I/O Errors
Use the (E) extender to trap file I/O errors
Older RPG programs may use an indicator in positions 72-73 (Lo) for I/O operations to trap errors

Be sure to check the status of the %ERROR function after an I/O operation
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 /FREE UPDATE(E) CustRecord; IF %ERROR; EXSR IOError; ENDIF; /END-FREE
Programming in RPG IV Third Edition 25

Points to Remember
READ, READE, READP, and READPE are input operations used to access records sequentially
Used with full procedural files Used with input or update files

SETLL and SETGT position the file prior to a sequential read operation

Programming in RPG IV Third Edition

26

Points to Remember
CHAIN randomly retrieves a record
Also positions the file for subsequent sequential reading

The KLIST and KFLD operations define a composite key and the fields that comprise the key A partial KLIST initiates access to sets of records that share a common value on the first field(s) of a composite key
Programming in RPG IV Third Edition 27

Points to Remember
WRITE or EXCEPT put records into an output file or an update file UPDATE and DELETE are specific to update files You cannot UPDATE a record without having first read it

Programming in RPG IV Third Edition

28

Points to Remember
OS/400 includes built in record locking to prevent the problem of phantom updates Techniques exist to minimize record locking, but they should not be used if they might cause phantom updates
For example, UNLOCK

The (E) extender and the %ERROR function provide error checking capabilities for file operations
Programming in RPG IV Third Edition 29