Skip to content

Keyword Table and Report Files

The following table lists the major keywords relevant to COBOL-IT Report Writer that may appear in the ENVIRONMENT DIVISION, FILE SECTION, and the RD entry, with a summary of their purposes. The third and fourth columns tell you whether or not the item is provided by IBM's OS/VS and DOS/VS COBOL and, if so, whether COBOL-IT Report Writer extends the facilities.

If you wish to remain compatible with OS/VS or DOS/VS COBOL, you should avoid the new keywords and the extensions to the old ones. You will find additional information on this subject in the compatibility paragraph at the end of each section.

Keyword Table

Keyword Purpose OS/VS DOS/VS Cobol? Extensions to OS/VS and DOS/VS COBOL
Select (in ENVIRONMENT Division) Associates file with external medium Yes
  • MODE clause to direct output to Independent Report File Handler
  • DUPLICATED clause for multiple report files
  • WITH PAGE BUFFER for holding page contents before printing
  • WITH RANDOM PAGE for writing to a cursor-controlled device
  • FIRST PAGE NO ADVANCING to suppress initial page advance
  • TYPE clause to select type of output device
Report Is / Reports Are (in FD) Associates report with file Yes ALL phrase
Style (in FD) Invokes a special printer facility for the file or report No
Line Limit Gives maximum report line width No
Global Makes report available to contained programs No
Page Limit Allocates regions of page for different groups TYPEs Yes
  • DE = Detail
  • First Body Group = First Detail
  • Last DE or CH = Last Detail
  • Last CF=Last Body Group=Footing
  • Phrases are not positionally independent sub-clauses
  • Limit, Lines(s) not required
  • First Detail/Last Detail not required even when Page Heading/Footing coded
Control Specifies field(s) whose change of contents triggers an control break Yes
  • Report=Final
  • Controls may overlap
Code Attaches non-print data to report records Yes
  • Value may be of any length
  • Code Is identifier format
  • Code Is literal format
Overflow Specifies action to be taken when expression or SUM overflows No
Allow Source Sum Cor Selects ANS-85 or ANS-68 rules for SUMming No

Report Files

COBOL-IT Report Writer produces output records and writes them automatically to COBOL report files when your program executes a GENERATE statement or TERMINATE statement. The report files are described very much like any other output sequential files. Each must have a SELECT...ASSIGN clause in the ENVIRONMENT DIVISION, and an FD in the FILE SECTION. They are accessed in the PROCEDURE DIVISION through the OPEN and CLOSE statements.

If the output is to be written to a special medium, or the program is to run in any special environment, or special treatment is to be given to the report data, the MODE clause is used. This directs report writer to use a specific file handler instead of writing output records in the standard way.

Your program may contain any number of report files and, if required, any number of other files. As usual, you may code your SELECT...ASSIGN clauses and your FD entries in any order.

select-assign

format

report

Select and FD: Coding Rules

  • You may code any other clauses after SELECT and any other clauses except LINAGE in the FD entry that may be appropriate for an output sequential file. In particular, a FILE STATUS clause may be used to return the status of your report file. The order of clauses is not significant.

  • Each report-name is a name of up to 30 characters, formed according to the usual rules for COBOL names. You might choose names that describes the output produced by the report, such as REPORTS ARE MONTHLY-SALES, END-OF-YEARTOTALS.

  • Each report-name must be the same as the report-name following an RD in your REPORT SECTION. A report-name may be DBCS. A report-name may appear only once in an FD entry. However, it may appear in more than one FD provided that any INITIATE for the report-name has the UPON file-name phrase (INITIATE statement) and provided that all the corresponding SELECT statements for these files differ only in their file-name, ASSIGN clause and MODE clause (if present).

  • If every report is to be written to the same file, you may write REPORTS ARE ALL. ALL must be the only operand and REPORTS ARE ALL must be the only REPORT(S) clause in the program.

  • A RECORD CONTAINS clause, or a BLOCK CONTAINS clause with the CHARACTERS option, is required if the identifier form of the CODE clause is used in any RD associated with the file. In all other cases, it is optional.

  • You should not normally specify a record-description-entry after the FD entry, because report writer relieves you of the need to code any WRITE statements for the report files. Your program may WRITE records to a report file independently of report writer, provided that there is no MODE clause in the corresponding SELECT and no CODE clause in the RD, and in this case you will of course need to specify at least one 01-level record description following the FD entry. An explicit WRITE to the report file may be necessary in rare instances, such as when a downstream program will read your report file and it requires a header or trailer which must not have a carriage control character in its first byte. (Otherwise, a REPORT HEADING or REPORT FOOTING could be used for this purpose: even if there are non-DISPLAY fields to be written, they could be handled using a SOURCE referencing them as a large group field.) An Independent Report File Handler may also be used to manipulate the output for this purpose (see Independent Report File Handlers).

  • If you do code a record description after the FD entry, and you wish to obtain fixedlength records, you should code a RECORD CONTAINS clause, even if you have also specified RECORDING MODE IS F. The integer of the RECORD CONTAINS clause should agree with the size of your record and must allow for the carriage control character if the NOADV option is in effect.

  • The MODE clause is used to indicate that each line of the report is to be passed to an Independent Report File Handler, instead of being written directly to a print file. The mnemonic-name consists of up to four alphanumeric characters . No check is made on the availability of the file handler until execution time. The file handler may be either the basic file handler PRNT, a user-written, or a built-in file handler. File handlers extend the uses of report writer beyond output to "batch" files. They have two chief uses: (a) they allow the output to be sent to any kind of new physical device without changes to the program and (b) they allow a "back-end" software routine to perform any additional processing on the output. File handlers are described in a later section (see Independent Report File Handlers) where the supplied file handlers are also listed.

  • The DUPLICATED, WITH RANDOM PAGE, and WITH PAGE BUFFER features cannot be implemented at run time by direct output and require a file handler to be present (although their processing is handled entirely by the run time system and not by the file handler itself). So if any of these clauses is present, but no MODE clause has been coded, the precompiler will assume an implicit MODE PRNT clause to be present. The same assumption is made if any report associated with the file has a CODE clause (except when all such reports have a CODE clause and they are all of the same length), see CODE clause.

  • If the MODE clause is present, or is assumed implicitly for the reasons given in the preceding paragraph, the following restrictions apply:

    • No record descriptions may follow the FD entry for that file, as you cannot WRITE directly to a file that is processed by an Independent Report File Handler, see Independent Report File Handlers.

    • The clauses RESERVE integer-1 AREA(S), PADDING CHARACTER, RECORD DELIMITER, and PASSWORD of the SELECT...ASSIGN clause and the clauses BLOCK CONTAINS integer RECORDS, LABEL RECORD(S) IS/ARE data-name, RECORD IS VARYING..., CODE-SET, and VALUE OF... of the FD are not processed by the file handler and are treated as documentary only.

    • No USE AFTER STANDARD ERROR/EXCEPTION PROCEDURE Declarative section should be coded for the file.

    • The CANCEL and STOP RUN statements cannot be relied on to CLOSE files implicitly, as allowed under ANS 85 for regular files.

  • The device-name of the TYPE clause gives the make and model of the output device, or some other symbolic name. The TYPE clause enables the precompiler, or the run time system, to select the correct sequence of control characters to produce the desired special effect on the target device. (See STYLE clause.) Apart from the reserved name NONE (meaning that no particular device is to be assumed) and TEST (a specially reserved name), there is a set of special character values associated with each device-name and each of the special effects available from the device. The physical values of these characters and the method by which they are inserted into the output is highly machine- and device-dependent, but quite transparent to the program. Device-names are described in Installation and Operation.

    DEFERRED means that any styles used are to be interpreted at run time, rather than stored explicitly when the program is precompiled. This enables the same program to operate with a number of different output devices without recompilation.

    If DEFERRED alone is given, the program will determine the target device at run time from the operating environment. It is then assumed that there may be an implicit style at the FD and the RD levels at run time (unless STYLE NONE is specified) and provision is made for them.

    DEFERRED is also implied if PAGE BUFFER is coded, since the page buffer routine must know which characters are printable and which are control characters. DEFERRED may also be forced by any particular STYLE if the implementation decides that the routines required to effect it cannot be included at precompilation time.

    If TYPE is not coded, the precompiler will assume a default device-name, chosen by the user at customization time, which may be absent, i.e. NONE.

    If the device-name is NONE, any STYLE clause applying to this file, other than NORMAL, will be rejected, whether it is in the corresponding FD, any report assigned to the file, or in a report group description.

File-Control and FD: Operation

  • If you specify more than one report-name in the same REPORTS ARE clause, you will be able to generate report data either consecutively or concurrently for the same file. (REPORT IS and REPORTS ARE are interchangeable, however many reportnames follow.) Tips on creating more than one report concurrently will be found later (see Concurrent Reports).

  • The USING phrase indicates that the file handler is to be passed the parameters you specify in addition to the parameters normally passed automatically to the file handler on each call. The additional parameters will be first in the list of parameters passed. Only user-written file handlers may employ additional parameters, and their associated documentation should specify the exact number and size of the additional parameters required because, unless these are correct, unpredictable results may occur. Each parameter may be an identifier or literal or any other item that would normally be allowed in the USING phrase of a CALL statement, including their additional keywords such as LENGTH OF, ADDRESS OF, BY CONTENT, or BY REFERENCE.

  • The DUPLICATED clause indicates that integer-2 copies of the report writer Report Control Areas are to be created. For example, if you code DUPLICATED 4 TIMES, four copies of PAGE-COUNTER, LINE-COUNTER, control-break areas, total fields, and other internal registers or locations used by report writer will be set up under that report-name. Each copy controls a totally separate report, passed to a different physical file (although only one FD entry is needed). This enables you to produce several separate reports that share an identical or similar layout without having to re-code several similar Report Descriptions.

  • The WITH PAGE BUFFER clause indicates that the Page Buffer facility is to be available to the file handler. This enables you to use the SET PAGE TO HOLD / RELEASE, SET LINE, and SET COLUMN statements (see 4.4 Report Writer SET statements Report Writer SET Statements) to build up your page in random fashion. A full explanation of Independent Report File Handlers and all related clauses is given in a later part (see Independent Report File Handlers).

  • The WITH RANDOM PAGE clause indicates that the SET LINE and SET COLUMN statements may be used (see Report Writer SET statements) to build up your page in random fashion. This clause is used when the output device is one which outputs data page by page rather than line by line (such as a visual display, or laser or page printer) and can change its "current position" to anywhere on the page. It is similar to WITH PAGE BUFFER, except that the buffer is in the device itself rather than in the program.

  • If you require normal output to a standard file, you may write MODE IS BATCH. This prevents any use of a file handler. MODE IS BATCH cannot be used if a DUPLICATED or WITH PAGE BUFFER clause has been coded.

  • If you do not code a RECORD CONTAINS clause or a BLOCK CONTAINS clause with the CHARACTERS option, report writer will calculate the logical record length for the report file from the longest actual line found in all the Report Descriptions associated with the file (rounded up to a multiple of 4). The length of the CODE field, where appropriate, and carriage control character are also added.

  • If you do code a RECORD CONTAINS clause (or, in its absence, a BLOCK CONTAINS clause with the CHARACTERS option), the integer specified will be used as the logical record length for the report file. The same integer, after subtracting the length of the carriage control character (if the NOADV option is in effect) and the CODE field, if appropriate, is also used to calculate a provisional value for the maximum line width for any report associated with the file (up to the default maximum established on customization), in case you omit the LINE LIMIT clause in an RD entry.

  • If you write RECORDING MODE IS V for a standard batch file (one not produced by a file handler), Report Writer will write variable-length records to your report file, truncating them, where possible, immediately after the last field in the line. This means that in most reports records will be considerably shorter, even after allowing for the additional record descriptor bytes that precede each record. If you also coded an optional RECORD CONTAINS clause with the format RECORD CONTAINS lower-integer TO higher-integer CHARACTERS, the lower-integer is used as a minimum length for all report records written to the file. Since QSAM normally requires at least four bytes per record (plus the carriage control byte), you should write RECORD CONTAINS 4 TO maximum-integer CHARACTERS, or, if NOADV is in effect, then RECORD CONTAINS 5 TO maximum-integer CHARACTERS.

  • If you specify a RECORDING MODE clause for a file that uses an Independent Report File Handler, the recording mode you specify will be placed in report writer's File Control Area for the report file, and the file handler may choose whether to act on it or to ignore it. The records passed to a file handler are always variablelength, irrespective of the RECORDING MODE. The file handler may process them in this form or output them as fixed-length records. The built-in PRNT file handler ignores the RECORDING MODE and uses the record format specified, or implied, at run time.

  • You may specify EXTERNAL or GLOBAL for a file that has a REPORT(S) clause. It is not necessary for a report file to be GLOBAL in order for it to have a GLOBAL report associated with it.

  • If you write FIRST PAGE NO ADVANCING, the usual form feed is not issued at the start of the first page after execution of the OPEN for the file. Instead, the program assumes that the paper is already positioned on line 1 of the page. This feature is useful for printing on pre-numbered forms when you do not want the first page to be wasted. (You may also eliminate all form feeds using the MODE NOPF (see Supplied File Handlers).) FIRST PAGE WITH ADVANCING (the normal default) is provided for symmetry.

Compatibility

The MODE, DUPLICATED, WITH PAGE BUFFER, FIRST PAGE NO ADVANCING and STYLE clauses, and the concept of an Independent Report File Handler are unique to new Report Writer.

Back to top