VLR

The VLR option affects the file status returned from READ statements for variable-length records when the length of record returned is inconsistent with the record descriptions. It eases your migration from earlier versions to Enterprise COBOL V6, if your programs have READ statements that result in a record length conflict.

Syntax

Default: VLR=STANDARD

After the execution of a READ statement:

If the number of character positions in the record that is read is less than the minimum size specified by the record description entries for the file, the portion of the record area that is to the right of the last valid character read is undefined.
If the number of character positions in the record that is read is greater than the maximum size specified by the record description entries for the file, the record is truncated on the right to the maximum size.

In either of these cases, the READ statement is successful, and the file status is set to either 00 (with VLR=COMPAT set, hiding the record length conflict condition) or 04 (with VLR=STANDARD set, indicating that a record length conflict has occurred).

COMPAT: VLR=COMPAT checks the size of the read record against the "VARYING IN SIZE FROM min TO max" declaration of the FD clause. If you specify VLR=COMPAT, you get the status value of 00 when READ statements encounter a record length conflict.; Note: This setting can hide I/O problems that can arise with the wrong length read situation. Use the VLR=COMPAT option with caution, and check for correct READ statements.
STANDARD: Important: You must add code to each READ statement to use VLR=STANDARD for testing file status.
VLR=STANDARD checks the size of the read record against the declaration of the FD level 01 clause. If you specify VLR=STANDARD, you get the status value of 04 when READ statements encounter a record length conflict.; VLR=STANDARD helps you avoid accessing undefined data in a record and also avoid getting protection exceptions for attempting to reference a part of the record that was truncated.
Tip: Alternatively, check if you get the compile-time information message IGYPG3178, which indicates that the sizes of the smallest and largest records do not match the range of the RECORD IS VARYING clause. If you do not get this message, you would get the status value of 00 rather than 04 with VLR=STANDARD. If you get the message, you have at least one record description with length outside the range of the RECORD IS VARYING clause. The compiler issues IGYPG3178 regardless of your VLR setting, and the message does not halt the compilation. For more information about IGYPG3178, see Information message IGYPG3178.

The following example shows how the VLR option checks the size of the read record against the declaration of the FD clause and FD level 01 clause, with Table 1 below illustrating the resulting file status (FS) of various lengths of records read. In this case a record read is a series of strings.

* The file contains two record definitions:
* REC-20: up to 20 characters
* REC-50: up to 50 characters
* The file must contain between 10 to 80 characters in total.
FD MYDD
   block contains 0 records
   record varying in size from 10 to 80
   recording mode V.
01 REC-20
   02 PIC X(20).
01 REC-50.
   02 PIC X(50).

Table 1. Length of record read and file status
Length of record read	5	15	40	70	85
>= min varying (10)	✘	✔	✔	✔	✔
<= max varying (80)	✔	✔	✔	✔	✘
>= min level 01 (20)	✘	✘	✔	✔	✔
<= max level 01 (50)	✔	✔	✔	✘	✘
Valid data?	✘	✘	✔	✘	✘
COBOL V4	FS=04 ✘	FS=00 ✔	FS=00 ✔	FS=00 ✔	FS=00 ✔
COBOL V6 `VLR(COMPAT)`	FS=04 ✘	FS=00 ✔	FS=00 ✔	FS=00 ✔	FS=00 ✔
COBOL V6 `VLR(STANDARD)`	FS=04 ✘	FS=04 ✘	FS=00 ✔	FS=04 ✘	FS=04 ✘
Notes: "FS=00" means that the record is accepted (✔). "FS=04" means that the record is flagged as invalid (✘). "Min varying" and "max varying" refer to the minimum and maximum size specified in the RECORD VARYING clause, which is 10 and 80 in this case. "Min level 01" and "max level 01" refer to the size of the smallest and largest level 01 record description, which is 20 for REC-20 and 50 for REC-50 in this case.

Visual demonstrations of the scenarios in the preceding table are provided as follows, where [?] represents undefined space, [X] represents truncated data, and other characters in boxes like [A] represent filled data.

A record length of 5 is represented as follows:
```
[A][B][C][D][E][?][?][?][?][?][?][?][?][?][?][?][?][?][?][?]
|<---- 5 ---->|<------------- Undefined (15) ------------->|
```
The record length of 5 is less than the min varying 10 and less than the min level 01 of 20, so the record is invalid (✘) in any COBOL compiler version.
A record length of 15 is represented as follows:
```
[A][B][C][D][E][F][G][H][I][J][K][L][M][N][O][?][?][?][?][?]
|<------------------ 15 ------------------->|<Undefined(5)>|
```
The record length of 15 is larger than the min varying 10 and less than the min level 01 of 20, so the record is invalid (✘) under COBOL 6 VLR=STANDARD.

A record length of 40 is represented as follows:

[A][B][C][D][E][F][G][H][I][J][K][L][M][N][O][P][Q][R][S][T]
[U][V][W][X][Y][Z][1][2][3][4][5][6][7][8][9][0][1][2][3][4]
|<------------------------ 40 ---------------------------->|

The record length of 40 is within the varying range 10-80 and meets the level 01 requirements, so the record is valid (✔).

A record length of 70 is represented as follows:

[A][B][C][D][E][F][G][H][I][J][K][L][M][N][O][P][Q][R][S][T]
[U][V][W][X][Y][Z][1][2][3][4][5][6][7][8][9][0][1][2][3][4]
[5][6][7][8][9][0][1][2][3][4][5][6][7][8][9][0][1][2][3][4]
[5][6][7][8][9][0]
|<-------------------------- 70 -------------------------->|

The record length of 70 is within the varying range 10-80, but larger than the max level 01 of 50, so the record is invalid under COBOL 6 VLR=STANDARD.

A record length of 85 is represented as follows:

[A][B][C][D][E][F][G][H][I][J][K][L][M][N][O][P][Q][R][S][T]
[U][V][W][X][Y][Z][1][2][3][4][5][6][7][8][9][0][1][2][3][4]
[5][6][7][8][9][0][1][2][3][4][5][6][7][8][9][0][1][2][3][4]
[5][6][7][8][9][0][1][2][3][4][5][6][7][8][9][0][1][2][3][4]
[5][6][7][8][9][0][1][2][3][4][5][6][7][8][9][0]
|<------------------------- 80 --------------------------->|[X][X][X][X][X]
                                                           |<--Truncated->|

The record length of 85 is larger than the max varying 80 and max level 01 of 50, so the record is truncated (✘).

Information message IGYPG3178

The information message IGYPG3178 can also help you avoid I/O problems by telling you if a program has a possibility of a wrong length READ. This message can be used to assist with migration from VLR=COMPAT to VLR=STANDARD by indicating the possible wrong length READ that you can solve by correcting the File Definition (FD). You can also raise the severity of the message so that the program must be corrected in order to run. To do this, use the MSGEXIT suboption of the EXIT compiler option to change the severity of message IGYPG3178 from I (RC=0) to S (RC=12), E (RC=8), or W (RC=4). If you are not interested in seeing this message, you can suppress the message completely.