All about READ in RPGLE & Why we use it with SETLL/SETGT?

READ

READ is one of the most used Opcodes in RPGLE. As the name suggests main purpose of this Opcode is to read a record from Database file.

What are the different READ Opcodes?

To list, Below are the five Opcodes. 

1. READ - Read a Record
2. READC - Read Next Changed Record
3. READE - Read Equal Key Record
4. READP - Read Prior Record
5. READPE - Read Prior Equal Record

We will see more about each of these later in this article. Before that, We will see a bit about SETLL/SETGT. 

SETLL (Set Lower Limit)

SETLL accepts Key Fields or Relative Record Number (RRN) as Search Arguments and positions the file at the Corresponding Record (or Next Record if exact match isn't found). 

SETGT (Set Greater Than)

SETGT accepts Key Fields or Relative Record Number (RRN) as Search Arguments and positions the file at the Next Record (Greater Than the Key value).

Syntax:

SETLL SEARCH-ARGUMENTS/KEYFIELDS FILENAME

SETGT SEARCH-ARGUMENTS/KEYFIELDS FILENAME

One of the below can be passed as Search Arguments.

• Key Fields
• Relative Record Number
• Key List (KLIST - defined with Key Fields) - Only in Fixed Format RPGLE
• %KDS (Key Fields defined in a Data Structure)

SETLL/SETGT are also used to identify if a record is present in the File or not. %FOUND() can be used to immediately after SETLL/SETGT. 

This would eliminate the need to execute READ operation if there is no record found in the File.

We will now see more about each of the READ* Operations before we go on to the dependency with SETLL/SETGT with READ.

READ (Read a Record)

READ Operation reads a record currently pointed to from a Database file. And, loads it into Data structure if Data Structure name is provided in the READ operation. 

We will see later in this article on how to point to a specific record using SETLL/SETGT.

Syntax:

READ(E N) FILE_NAME DATA_STRUCTURE_NAME

Data Structure Name and Extenders 'E', 'N' are Optional.

Extender 'E' is used to capture any errors. %ERROR can be used to identify if there are any errors during the READ.

Extender 'N' is used if the Record needs to be read with No lock (Read Only mode). This isn't allowed if the file is opened for Inout only.

READC (Read Next Changed Record):

READC Operation reads the next changed Record on a Subfile. This can only be used with WORKSTN files. 

Syntax:

READC(E) RECORD_FORMAT DATA_STRUCTURE_NAME

Unlike the READ operation, READC expects Record Format Name. Record Format specified with SFILE Keyword on the File Definition. 

Data Structure Name and Extender 'E' are Optional and are similar to READ. Please see the READ Section for more details. 

Extender 'N' isn't allowed with READC. 

READ doesn't require pointer to be setup by SETLL/SETGT. Click Here to see more about READC and how it is related to SFLNXTCHG.

READE (Read Equal Key Record):

READE operation Reads the Next record with Matching key record currently pointed to from a Database file. 

Syntax:

READE(N E) SEARCH_ARGUMENTS/KEYS FILE_NAME DATA_STRUCTURE_NAME

One of the below can be passed as Search Arguments.

• Key Fields
• Relative Record Number
• Key List (KLIST - defined with Key Fields) - Only in Fixed Format RPGLE
• %KDS (Key Fields defined in a Data Structure)

Data Structure Name and Extenders 'E', 'N' are Optional. See READ Section for more details on these.

READP (Read Prior Record)

READP operation Reads the Prior record to the currently pointed record from a Database file. 

Syntax: 

READP(E N) FILE_NAME DATA_STRUCTURE_NAME

Data Structure Name and Extenders 'E', 'N' are Optional. See READ Section for more details on these.

READPE (Read Prior Equal Key Record)

READPE operation Reads the Prior record with Matching Key record currently pointed to from a Database file. 

Syntax:

READPE(N E) SEARCH_ARGUMENTS/KEYS FILE_NAME DATA_STRUCTURE_NAME

One of the below can be passed as Search Arguments.

• Key Fields
• Relative Record Number
• Key List (KLIST - defined with Key Fields) - Only in Fixed Format RPGLE
• %KDS (Key Fields defined in a Data Structure)

Data Structure Name and Extenders 'E', 'N' are Optional. See READ Section for more details on these.

Why is it necessary to use SETLL/SETGT with READ?

As we have seen in the previous sections, READ would read the record from where it is pointed to. Now, How is it pointed? We should be using SETLL/SETGT to position at a specific record. 

READ & READP would read the Next & Prior records respectively from where it is pointed to. These doesn't accept any Search Arguments or Key fields. These can be used with files which aren't defined for Keyed Access as well. 

We could set the pointer at the start of the file, end of the file, before a specific key record or after a specific key record. We will see how to read (and what combination to use) for each of these scenarios.

• Read the first record in the file. 

Position to the file using SETLL and use READ to read the first Record. Search Arguments needs to be passed as '*START' in case of not opened with Keyed Access and '*LOVAL' could be used with file opened with Keyed Access. If there are no records available to read, End Of File can be captured using %EOF(), this would return '1' for End Of File.

E.g.: 

SETLL *START FILE_NAME ; // would position to the Starting of the file

(OR)

SETLL *LOVAL FILE_NAME ; // would position to the Lowest key value.    Would be starting of the file.

READ FILE_NAME ;

DOW NOT %EOF(FILE_NAME) ; 

// Required Program Logic

READ FILE_NAME ;

ENDDO ; // This would read the file Until End Of File

• Read the last record in the file.

Position to the file using SETGT and use READP to read the first Record. Search Arguments needs to be passed as '*END' in case of not opened with Keyed Access and '*HIVAL' could be used with file opened with Keyed Access. If there are no records available to read, End Of File can be captured using %EOF(), this would return '1' for End Of File.

E.g.: 

SETGT *END FILE_NAME ; // would position to the Starting of the file

(OR)

SETGT *HIVAL FILE_NAME ; // would position to the Lowest key value.    Would be starting of the file.

READP FILE_NAME ;

DOW NOT %EOF(FILE_NAME) ; 

// Required Program Logic

READP FILE_NAME ;

ENDDO ; // This would read the file Until End Of File. File would read from End to Start. So End of File in this case would be after the first Record.

READE & READPE would Read the Next Equal Key & Prior Equal Key records respectively from where it is pointed to. Key Fields are mandatory for these Operations and can only be used with the filed defined with Keyed Access. 

We could set the pointer at the start of the file, end of the file, before a specific key record or after a specific key record. We will see how to read (and what combination to use) for each of these scenarios.

• Read the record(s) with Specific Key values in the file from Start to End. 

Position to the file using SETLL with Key Fields and use READE to read the first Record with Matching Key. If there are no records available to read matching with the Key fields defined, End Of File can be captured using %EOF(), this would return '1' for End Of File.

E.g.: 

SETLL (KFLD1 : KFLD2) FILE_NAME ; // would position before the KFLD1, KFLD2

READE (KFLD1 : KFLD2) FILE_NAME ;

DOW NOT %EOF(FILE_NAME) ; 

// Required Program Logic

READE (KFLD1 : KFLD2) FILE_NAME ;

ENDDO ; // This would read the file Until End Of File

• Read the record(s) with Specific Key values from End to Start.

Position to the file using SETGT and use READP to read the first Record. Search Arguments needs to be passed as '*END' in case of not opened with Keyed Access and '*HIVAL' could be used with file opened with Keyed Access. If there are no records available to read, End Of File can be captured using %EOF(), this would return '1' for End Of File.

E.g.: 

SETGT (KFLD1 : KFLD2) FILE_NAME ; // would position to the Starting of 

READPE (KFLD1 : KFLD2) FILE_NAME ;

DOW NOT %EOF(FILE_NAME) ; 

// Required Program Logic

READPE (KFLD1 : KFLD2) FILE_NAME ;

ENDDO ; // This would read the file Until End Of File. File would read from End to Start. So End of File in this case would be after the first Record.

E.g.: If there are below records in FILE1 under FLD1

ABC

DEF

GHI

JKL

MNO

PQR

SETLL *START FILE1 ; // This would position the cursor at the First Record of the File (i.e. ABC). READ would read 'ABC' and READP would return End Of File.

SETLL ('DEF') FILE1 ; // This would position the cursor at the Second Record (i.e. before DEF). READ would read Record 'DEF' and READP would read record 'ABC'

SETGT ('MNO') FILE1 ; // This would position the cursor at the end of Record 'MNO'. READP would read 'MNO' and READ would read PQR.

SETGT ('PQR') FILE1 ; // This would position the cursor at the end of Last Record (i.e., PQR). READP would read 'PQR' and READ would return End Of File.

SETGT *END FILE1 ; // This would position the cursor at the end of Last Record (i.e. PQR). READP would read 'PQR' and READ would return End Of File.

I hope this post has been a bit of help in understanding more about READ and why/when we use READ along with SETLL/SETGT.

If you have any Suggestions or Feedback, Please leave a comment below or use Contact Form.