FILE-CONTROL Paragraph

The FILE-CONTROL paragraph allows specification of file-related information.

General format

[ FILE-CONTROL. ]     [ { Indexed File    } ] ...     { Relative File   }     { Sequential File }     { Sort File       }

Indexed File

A file with indexed organization is a mass storage file from which any record may be accessed by giving the value of a specified key in that record. For each key data item defined for the records of a file, an index is maintained. Each such index represents the set of values from the corresponding key data item in each record. Each index, therefore, is a mechanism which can provide access to any record in the file.

Each indexed file has a primary index which represents the prime record key of each record in the file. Each record is inserted in the file, changed, or deleted from the file based solely upon the value of its prime record key. The prime record key of each record in the file must be unique, and it must not be changed when updating a record. The prime record key is declared in the RECORD KEY clause of the file control entry for the file.

Alternate record keys provide alternate means of retrieval for the records of a file. Such keys are named in the ALTERNATE RECORD KEY clause of the FILE-CONTROL Paragraph. The value of a particular alternate record key in each record need not be unique. When these values may not be unique, the DUPLICATES phrase is specified in the ALTERNATE RECORD KEY clause.

SELECT [ {OPTIONAL    } ] File-Name        [ {NOT OPTIONAL} ]     ASSIGN TO [Device-1] [File] ORGANIZATION IS INDEXED     [ WITH {COMPRESSION} ... ]          {ENCRYPTION }    [ COMPRESSION CONTROL VALUE IS Compression-Factor ]     [ ACCESS MODE IS {SEQUENTIAL} ]                    {RANDOM    }                    {DYNAMIC   }     [ COLLATING SEQUENCE IS Alphabet-Name ]     [ FILE STATUS IS File-Status ]     [ LOCK MODE IS { EXCLUSIVE WITH [MASS-UPDATE]                                         } ]                  { {AUTOMATIC} [ WITH LOCK ON [MULTIPLE] {RECORD } ] [ [WITH] ROLLBACK ] }                    {MANUAL   }                           {RECORDS}     RECORD KEY IS { Data-Item-1                        } [ WITH [NO] DUPLICATES ]                 { Key-Name-1 [ = {Data-Item-2} ... ] }     [ ALTERNATE RECORD KEY IS { Data-Item-3                        } [ WITH [NO] DUPLICATES ] ] ...                             { Key-Name-2 [ = {Data-Item-4} ... ] }     [ RESERVE {Integer} [{AREA }] ]                        {AREAS}     [ { RECORD  } DELIMITER IS STANDARD-1 ]     { RECORDS }     [ CLASS IS Class-Name ] .

Relative File

A file with relative organization is a mass storage file from which any record may be stored or retrieved by providing the value of its relative record number.

Conceptually, a file with relative organization comprises a serial string of areas, each capable of holding a logical record. Each of these areas is denominated by a relative record number. Each logical record in a relative file is identified by the relative record number of its storage area. For example, the tenth record is the one addressed by relative record number 10 and is in the tenth record area, whether or not records have been written in any of the first through the ninth record areas.

SELECT [ {OPTIONAL    } ] File-Name        [ {NOT OPTIONAL} ]     ASSIGN TO [Device-1] [File] ORGANIZATION IS RELATIVE

[ ACCESS MODE IS { SEQUENTIAL [ RELATIVE KEY IS Relative-Key ] } ]                    { RANDOM RELATIVE KEY IS Relative-Key         }                    { DYNAMIC RELATIVE KEY IS Relative-Key        }     [ FILE STATUS IS File-Status ]   [ LOCK MODE IS { EXCLUSIVE                                         } ]                  { {AUTOMATIC} [ WITH LOCK ON [MULTIPLE] {RECORD } ] }                    {MANUAL   }                           {RECORDS}     [ RESERVE {Integer} [AREA ] ]                        [AREAS]   [ WITH { COMPRESSION } ... ]          { ENCRYPTION  }  [ COMPRESSION CONTROL VALUE IS Compression-Factor ]     [ CLASS IS Class-Name ] .

Sequential File

Sequential files are organized so that each record, except the last, has a unique successor record; each record, except the first, has a unique predecessor record. The successor relationships are established by the order of execution of WRITE Statements when the file is created. Once established, successor relationships do not change except in the case where records are added to the end of a file.

A sequentially organized mass storage file has the same logical structure as a file on any sequential medium; however, a sequential mass storage file may be updated in place. When this technique is used, new records cannot be added to the file and each replaced record must be the same size as the original record.

In sequential files whose organization is LINE SEQUENTIAL, each record is terminated by one or more characters. They are not part of the data record, they are automatically appended to the record after writing and removed after reading.

Sequential files can be created either on disk or in memory.

SELECT [ {OPTIONAL    } ] File-Name        [ {NOT OPTIONAL} ]     ASSIGN TO [Device-2] [File] [ ORGANIZATION IS [ {BINARY} ] SEQUENTIAL ]                                                   {LINE  }                                                   {RECORD}     [ ACCESS MODE IS SEQUENTIAL ]     [ FILE STATUS IS File-Status ]     [ LOCK MODE IS {EXCLUSIVE} WITH LOCK ON [MULTIPLE] {RECORD}                                                      {RECORDS} ]                  {AUTOMATIC}                  {MANUAL   }     [ PADDING CHARACTER IS Padding-Character ]    [ WITH { COMPRESSION } ... ]          { ENCRYPTION  }  [ COMPRESSION CONTROL VALUE IS Compression-Factor ]     [ CLASS IS Class-Name ].

Sort File

A sort file is a collection of records to be sorted by a SORT Statement. The sort file has no label procedures which the programmer can control and the rules for blocking and for allocation of internal storage are peculiar to the SORT Statement. The RELEASE and RETURN Statements imply nothing with respect to buffer areas, blocks, or reels. A sort file, then, may be considered as an internal file which is created (RELEASE Statement) from the input file or procedure, processed (SORT Statement), and then made available (RETURN Statement) to the output file or procedure.

SELECT [ {OPTIONAL    } ] File-Name        [ {NOT OPTIONAL} ]     ASSIGN TO [Device-1] [File]     [ ACCESS MODE IS SEQUENTIAL ]     [ FILE STATUS IS File-Status ]     [ LOCK MODE IS {EXCLUSIVE} WITH LOCK ON [MULTIPLE] {RECORD}                                                      {RECORDS} ]                  {AUTOMATIC}                  {MANUAL   }     [ PADDING CHARACTER IS Padding-Character ]    [ CLASS IS Class-Name ]   [ COLLATING SEQUENCE IS Alphabet-Name ]

Syntax rules

1.	Alphabet-Name, Device-1, Device-2, Device-3, File-Name, Key-Name-1 and Key-Name-2 are User-defined words, as defined in the Definitions section in the Preface of this document.

2.	File and Class-Name can be either Data Items or Nonnumeric Literals, as defined in the Definitions section in the Preface of this document.

3.	File may contain quotes.

4.	Compression-Factor and Integer are Integers, as defined in the Definitions section in the Preface of this document. The value must range from 1 and 100.

5.	Data-Item-1, Data-Item-2, Data-Item-3 and Data-Item-4 are Data Items that must appear in the file description entry of the file that they belong to.

6.	Data-Item-5, File-Status and Relative-Key are Data Items, as defined in the Definitions section in the Preface of this document.

7.	Padding-Character is a one-character Nonnumeric Literal.

General Rules

1.

When the OPTIONAL Phrase is specified, the file can be accessed even if it has not been created before. File operations (OPEN, DELETE, READ, REWRITE, START, WRITE) will be successful and the File-Status will be properly set to allow the program to notice that the file does not exist. If an OPTIONAL file is opened in I-O or in EXTEND mode, it is created.

2.	Device-1 can be one of the following reserved words: INPUT, OUTPUT, INPUT-OUTPUT, RANDOM, DISC, DISK, DYNAMIC, EXTERNAL.

3.	Device-2 can be one of the following reserved words: INPUT, OUTPUT, INPUT-OUTPUT, RANDOM, DISC, DISK, DYNAMIC, EXTERNAL, LINE ADVANCING, PRINT, PRINTER, PRINTER-1, ADDRESS.

LINE ADVANCING, PRINT, PRINTER and PRINTER-1 are synonymous and must be specified for print files.

4.	Device-3 can be one of the following reserved words: SORT, MERGE, SORT-MERGE, SORT-WORK.

5.	INPUT, OUTPUT, INPUT-OUTPUT, RANDOM, DISC, DISK, SORT, MERGE, SORT-MERGE, SORT-WORK are treated as commentaries.

6.	If Device-2 is not specified, then DISC is assumed, unless -flsu compiler flag is used.

7.	File is the name of the file to be opened, changing its value when the file has already been opened has no effect. The runtime Framework follows the rules described in Conceptual Characteristics of a File to resolve the name of the file.

8.	When DYNAMIC is specified, if File refers to a variable that is not otherwise defined, the Compiler creates a Working-Storage variable by that name that is PIC X(256). It is the program's responsibility to move a valid file name to this data item prior to opening the file.

9.

When EXTERNAL is specified, File is searched between environment variables and configuration properties. If a variable whose name is File is found, then its value is used for the physical file name otherwise File is used as is. There is a small difference between the EXTERNAL clause and the iscobol.file.env_naming (boolean) configuration property. When using EXTERNAL, the search of File in the configuration is performed by the file handler, while when using iscobol.file.env_naming (boolean), the search of File in the configuration is performed by the Framework before passing the file name to the file handler.

10.

When ADDRESS is specified, File is searched between Data Division items. The content of the sequential file is sotored in the data item and resides in memory. The data item pointed by File should be alphanumeric. If you wish to share the memory file between two programs in the same run unit, then File should be defined as EXTERNAL or passed as parameter through the Linkage Section.

11.	Each File-Name in the Data Division must be specified only once in the FILE-CONTROL paragraph. Each File-Name specified in the SELECT clause must have a file description or a sort description entry in the Data Division of the same program.

12.	When the ORGANIZATION Phrase is not specified, the compiler assumes that the file is sequential.

13.	COMPRESSION is treated as commentary. Refer to your file system documentation to see if this feature is supported and how to activate it.

14.	ENCRYPTION activates file encryption. Refer to your file system documentation to see if this feature requires additional configuration.

15.	When the ACCESS Phrase is not specified, the compiler assumes that access mode is sequential.

16.	When the SEQUENTIAL Phrase is specified, the file is accessed in a sequential order. The START Statement may be used to establish a starting point for a series of subsequent sequential retrievals.

17.	When the RANDOM Phrase is specified, the file is accessed in a programmer-specified order. The I-O Statements may be used to retrieve or store a specific record in the file. Sequential access is not permitted.

18.	When the DYNAMIC Phrase is specified, the file is accessed either in a sequential or in a programmer-specified order, depending on the I-O statement being executed.

19.	When the COLLATING Phrase is specified, the file will use the collating sequence specified by Alphabet-Name. The behavior depends on the file system being used.

20.

File-Status is a two-character conceptual entity whose value is set to indicate the status of an input-output operation during the execution of an I-O statement and prior to the execution of any imperative statement associated with that I-O statement or prior to the execution of any applicable USE AFTER STANDARD EXCEPTION procedure.

21.	When the LOCK Phrase is not specified, the lock mode is automatic.

22.	When the EXCLUSIVE Phrase is specified, the lock mode is exclusive. The entire file is locked and no other processes can have access to it

23.	When the MASS-UPDATE Phrase is specified, the file access is optimized for heavy updates. The actual behavior depends on the file system being used.

24.	When the AUTOMATIC Phrase is specified, the lock mode is automatic. Records are locked when any READ Statement is executed.

25.	When the MANUAL Phrase is specified, the lock mode is manual. Records locks are obtained only when the LOCK phrase is explicitly specified on an I-O statement.

26.	When the MULTIPLE Phrase is specified in the LOCK ON Phrase, simultaneous locks on multiple records of the same logical file are allowed.

27.	The setting of a record lock is part of the atomic operation of an I-O statement.

28.	When the ROLLBACK Phrase is specified, multiple record locking is implied unless the -fl compiler flag was used. A transaction is automatically started before opening the file and it is committed right after.

29.	Data-Item-1 and Key-Name-1 identify the prime record key of the file.

30.	Data-Item-3 and Key-Name-2 identify one of the alternate keys of the file.

31.	When the WITH DUPLICATES Phrase is specified, duplicate values are allowed for the key.

32.	When the WITH NO DUPLICATES Phrase is specified, only unique values are allowed for the key.

33.	When the WITH DUPLICATES Phrase is specified in the RECORD KEY Phrase, the actual behavior depends on the file system being used.

34.	The RESERVE clause is treated as a commentary.

35.	Class-Name identifies the class that handles the files. It is the file system handler.

36.	The PADDING clause is treated as a commentary.

37.	LOCK MODE is ignored for Sequential and Sort files.

38.

Class-Name specifies the internal Framework class that will handle the file. There is a class for each known file.index. Setting the CLASS clause to a specific value forces the file to be handled by a specific internal class, overriding existing settings like Framework properties and Compiler options. The CLASS clause must point to a valid class, otherwise an error will be returned. The following table lists the possible values for the CLASS clause:

Indexed files

Class-Name	Effect
com.iscobol.extfh.ExtfhIndex	The file is handled by the 32bit EXTFH interface.
com.iscobol.extfh3.ExtfhIndex	The file is handled by the 64bit EXTFH interface.
com.iscobol.io.DynamicBtrieve	The file is handled by the Btrieve interface.
com.iscobol.io.DynamicConnector	The file is handled by c-tree through FileConnector.
com.iscobol.io.DynamicCtree	The file is handled by c-tree of version 9.5.51961 or previous.
com.iscobol.io.DynamicCtree2	The file is handled by c-tree of version 9.5.53702 or later.
com.iscobol.io.DynamicDCI	The file is handled by the DBMaker DCI interface.
com.iscobol.io.DynamicEasyDB	The file is handled by isCOBOL Database Bridge.
com.iscobol.io.DynamicJIsam	The file is a JIsam archivie (default).
com.iscobol.io.DynamicMConnector	The file is handled by the Micro Focus File Connector.
com.iscobol.io.DynamicRemote	The file is handled remotely by the file server feature provided by isCOBOL Server.
com.iscobol.io.DynamicVConnector	The file is handled by the Vision File Connector.
com.iscobol.io.DynamicVision	The file is handled by the Acucobol-GT Vision interface. The runcbl library, provided separately, is required.
com.iscobol.io.ScanMF	The file is handled by an internal Micro Focus files interface. You can only sequentially read next in input mode, other i-o is not supported. Micro Focus formats 1, 2, 3, 4 and 8 as well as C-ISAM are supported. Compressed files are not supported.
com.iscobol.io.ScanRMKF	The file is handled by an internal RM/COBOL files interface. You can only sequentially read next in input mode, other i-o is not supported.
com.iscobol.io.ScanVision	The file is handled by an internal Vision interface. You can only sequentially read next, other i-o is not supported. Vision formats 3 to 6 are supported.   The following file types are currently not supported: - encrypted files - Vision files version 1 and 2 A 9D error is returned on open of unsupported files.
faircom.rtg.DynamicCtreeJ	The file is handled by c-tree of version 10.4.0.39701 or later through a Java interface. Note that the native client library is always required.

If the CLASS clause is omitted, indexed files are handled based on the iscobol.file.index configuration property.

 

Relative and Binary Sequential files

Class-Name	Effect
com.iscobol.extfh.ExtfhRelative	The relative file is handled by the 32bit EXTFH interface.
com.iscobol.extfh.ExtfhSequential	The sequential file is handled by the 32bit EXTFH interface.
com.iscobol.extfh3.ExtfhRelative	The relative file is handled by the 64bit EXTFH interface.
com.iscobol.extfh3.ExtfhSequential	The sequential file is handled by the 64bit EXTFH interface.
com.iscobol.io.DynamicMFSequential	The file is handled in compatibility with Micro Focus.
com.iscobol.io.DynamicRelative	The file is a binary file on the local machine (default).
com.iscobol.io.DynamicRemote	The file is handled remotely by the file server feature provided by isCOBOL Server.
com.iscobol.io.DynamicSeqACU	The fixed length sequential file is handled in compatibility with Acucobol.
com.iscobol.io.DynamicVarSeqACU	The variable length sequential file is handled in compatibility with Acucobol.
com.iscobol.io.RemoteRelative	The file is a binary file on the client machine (Application Server).

If the CLASS clause is omitted, binary and relative files are handled based on the iscobol.file.relative and iscobol.file.sequential configuration properties.

 

Line Sequential files

Class-Name	Effect
com.iscobol.extfh.ExtfhLineSequential	The file is handled by the 32bit EXTFH interface.
com.iscobol.extfh3.ExtfhLineSequential	The file is handled by the 64bit EXTFH interface.
com.iscobol.io.DynamicLSeq8bit	The file is handled by the standard isCOBOL interface (default).
com.iscobol.io.DynamicLSeqACU	The file is handled by an Acucobol compatible interface that discards form feed, carriage return and line feed before returning the record.
com.iscobol.io.DynamicLSeqMF_N	The file is handled by a Micro Focus compatible interface that doesn’t treat 0x0A in COMP fields as line feed.
com.iscobol.io.DynamicRemote	The file is handled remotely by the file server feature provided by isCOBOL Server. It doesn’t work for stream files and print files. It doesn’t work if program is compiled with the -flsu option.

If the CLASS clause is omitted, line sequential files are handled based on the iscobol.file.linesequential configuration property.

39.

isCOBOL sorting logic for SORT files is totally written in Java and is configurable. The maximum size of data to sort is equal to the maximum size of a Java file (up to 2^64 bytes depending on O.S.). It uses a predefined block of RAM memory that is 1 MB in size by default, but can be configured by setting the iscobol.sort.memsize configuration property.

If this size is enough, the data is entirely sorted using the Collections Java object.

If the size of the memory block is not enough, the block is saved on disk in a temporary directory (the system temporary directory by default, but it can be configured by setting the iscobol.sort.dir configuration property), then the memory block is cleared and used for remaining data.

There is a maximum number of temporary files (16 by default, but it can be configured by setting the iscobol.sort.maxfiles configuration property). If this number is not enough, then all the sorted files are merged into a single sorted temporary so the Framework can create more temporary files.

The process continues until no more data to sort is available. At the end, if the data size is less than the allocated RAM memory, the results are returned directly from memory, otherwise data is read from temporary files.

With the default configuration, optimal performances are obtained when the data to sort is less than 1 MB.