FILE Declaration

FILE Declaration

A file should declare with all its characteristics for processing in the application program. The file is unknown to the program if it is not declared. Programs use these characteristics to know about the file, like the file type, length, recording mode, etc., and start processing the file.

The file declaration has two parts -

  • File Definition (FILE-CONTROL paragraph Entries).
  • File Structure Definition (File & Record description entries).

File Definition (FILE-CONTROL paragraph Entries) -

Logical file definition is the first mandatory step while introducing a file to the program for processing. The file becomes known to the program with this definition, which should contain complete information about the file and assign a logical name to the physical file.

These definitions are declared in FILE-CONTROL paragraph in INPUT-OUTPUT SECTION of ENVIRONMENT DIVISION. The file types allowed to be defined in the program are -

  • Sequential file (QSAM, ESDS).
  • Indexed file (KSDS).
  • Relative file (RRDS).
  • Line-sequential file (Limited to Z/oS UNIX).

Syntax -

[ENVIRONMENT DIVISION.]
[INPUT-OUTPUT SECTION.]
[FILE-CONTROL.]
    [SELECT logical-file-name ASSIGN TO DSNname]
    [ORGANIZATION IS file-organization]
    [ACCESS MODE IS access-mode]
	[RECORD KEY IS record-key]
	[ALTERNATE RECORD KEY IS alt-record-key WITH DUPLICATES]
	[RELATIVE KEY IS relative-key]
	[RECORD DELIMITER IS record-delimiter]
    [FILE STATUS IS file-status].
Note! All statements coded in [ ] are optional.

Parameters -

  • SELECT clause - Used to map the logical-file-name with the physical file external to the program.
  • logical-file-name - This is the name we use in the program to refer to the file. It's like an alias for the physical file. (e.g., FILE1, FILE2).
  • DSNname - This is the 8-character device name where the file is stored. i.e., DDname in JCL or DSName in CICS. (e.g., DISK, TAPE).
  • ORGANIZATION IS - Specifies the file organization to the program, and the file organizations are - SEQUENTIAL, INDEXED, and RELATIVE. If the ORGANIZATION is not coded, assumes the file is sequential.
  • ACCESS MODE IS - specifies how records will be accessed. access-modes are -
    • SEQUENTIAL - The records will be accessed sequentially and applicable to sequential, indexed, and relative files.
    • RANDOM - The records will be accessed randomly (in a programmer-specified manner) and applicable to indexed and relative files.
    • DYNAMIC - It is a combination of sequential, random, or both access modes and is applicable to indexed and relative files.
    If the ACCESS MODE is not coded, access mode is sequential assumed.
  • RECORD KEY IS - Specifies the key field to access the records and applicable only to indexed files.
  • ALTERNATE RECORD KEY - Specifies the alternate key field to access the records and applicable only to indexed files. WITH DUPLICATES specifies that a file can have duplicates in ALTERNATE KEY.
  • RELATIVE KEY - Specifies the RRN field to access the records and applicable only to relative files.
  • RECORD DELIMITER - Specifies the character that separates records in the file and applicable only to sequential files.
  • FILE STATUS - Used to get the success or failure status of the input-output operations performed on the file.
    • file-status (non-vsam files) - It is a two-character alphanumeric variable.
    • file-status (VSAM files) - It is an alphanumeric group variable of 6 bytes.
    Refer File Status Codes

Examples -

Scenario1 - Logical file definition for a fixed-length(80) sequential file(empps) to access sequentially.

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT empps ASSIGN TO emppsdd
    ORGANIZATION IS SEQUENTIAL
    ACCESS MODE IS SEQUENTIAL 
    FILE STATUS IS ws-fs1.

Scenario2 - Logical file definition for a variable-length indexed file(empksds) to access randomly. 

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT empksds ASSIGN TO empdd
    ORGANIZATION IS INDEXED
    ACCESS MODE IS RANDOM 
	RECORD-KEY IS emp-no
    FILE STATUS IS ws-fs2.

File Structure Definition (File & Record description entries) -

Logical file structure definition has the definition of the file logical structure that is needed to process the data in the program. The logical structure is the copybook layout used to map the file record.

The logical file structure definition should be in the FILE SECTION of DATA DIVISION.

Syntax -

[DATA DIVISION.]
[FILE SECTION.]
[FD logical-file-name]
    [RECORD CONTAINS ...]
    [BLOCK CONTAINS ...]
    [LABEL RECORD IS OMITTED|STANDARD|variable1]
	[DATA RECORD IS file-record]
	[RECORDING MODE IS F|V|U|S].

01 file-record    PIC X(max-rec-length).

Parameters -

  • FD - Used to specify the file description entry for logical-file-name. FD and SELECT clauses should have the same logical-file-name.
  • RECORD CONTAINS - Specifies the size of the records.
  • BLOCK CONTAINS - Specify the block size in terms of characters or records per block.
  • LABEL RECORD IS - Specifies if label records exist in the file or not and their type. (e.g., STANDARD, OMITTED).
  • DATA RECORD IS - Assigns a local name to the file record. (e.g., EMPLOYEE-RECORD).
  • RECORDING MODE IS - Specifies how the records are stored in the file. (e.g., F(Fixed), V(Variable), U(Unformatted), S(Spanned)). It is only applicable for sequential files.
  • 01 file-record ..- Specifies the record structure declaration.

Different Record Lengths -

There are three types of declarations based on the record lengths -

  • Fixed length records - Specifies the file has fixed-length records and declaration is 
    RECORD CONTAINS record-length CHARACTERS
BLOCK CONTAINS block-length CHARACTERS
    Declaration for the fixed-length record of length 80 - 
    RECORD CONTAINS 80 CHARACTERS
BLOCK CONTAINS 800 CHARACTERS
  • Variable length records - Specifies the file has variable-length records and declaration is 
    RECORD CONTAINS min-rec-length TO max-rec-length CHARACTERS
BLOCK CONTAINS min-blk-length TO max-blk-length CHARACTERS
    Declaration for the variable-length record of length 80 to 100 - 
    RECORD CONTAINS 80 TO 100 CHARACTERS
BLOCK CONTAINS 800 TO 1000 CHARACTERS
  • Dynamic length records - Specifies the file has variable-length records but the record length will be passed at runtime. The declaration is 
    RECORD IS VARYING IN SIZE FROM min-length TO max-length CHARACTERS 
		DEPENDING ON variable1
BLOCK CONTAINS min-blk-length TO max-blk-length CHARACTERS
    Declaration for the Dynamic length record of length 80 t0 100 - 
    RECORD CONTAINS 80 TO 100 CHARACTERS
         DEPENDING ON ws-length
BLOCK CONTAINS 800 TO 1000 CHARACTERS

Examples -

Scenario1 - Logical file definition and structure definition for a fixed-length(80) sequential file(empps) to access sequentially. 

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT empps ASSIGN TO emppsdd
    ORGANIZATION IS SEQUENTIAL
    ACCESS MODE IS SEQUENTIAL 
    FILE STATUS IS ws-fs1. 
	
DATA DIVISION.
FILE SECTION.
FD empps
    RECORD CONTAINS 80 CHARACTERS
    BLOCK CONTAINS 800 CHARACTERS
    LABEL RECORD IS OMITTED
	DATA RECORD IS emp-rec
	RECORDING MODE IS F.

01 emp-rec    PIC X(80).

Scenario2 - Logical file definition and structure definition for a variable-length indexed file(empksds) to access randomly. 

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT empksds ASSIGN TO empdd
    ORGANIZATION IS INDEXED
    ACCESS MODE IS RANDOM 
	RECORD-KEY IS emp-no
    FILE STATUS IS ws-fs2.

DATA DIVISION.
FILE SECTION.
FD empdd
    RECORD CONTAINS 80 TO 100 CHARACTERS
    BLOCK CONTAINS 800 TO 1000 CHARACTERS
	DATA RECORD IS emp-rec.

01 emp-rec    PIC X(100).