Independent Report File Handlers

An Independent Report File Handler (or file handler) is a separately-compiled program routine that takes over all the functions of the normal COBOL OPEN-WRITE-CLOSE protocol for a particular report. The source program, as written, is identical in all respects to a regular batch print program, except that the SELECT...ASSIGN clause for the file to which the report is directed carries the additional sub-clause MODE IS... (see Report Files), and that there may also be a CODE clause in the RD. (The MODE sub-clause can also be "forced" by default onto any report file does not have a MODE by an external option setting - see Installation and Operation.)

File handlers monitor the results of any i/o operations they perform and pass any error codes back in the FILE STATUS field in the usual way, or, if no FILE STATUS is specified, they display a suitable message and, if the error is irrecoverable, abort the run.

New Report Writer comes with some built-in file handlers and these are listed below. Any number of others may be written by users to similar standards. File handlers can be written in COBOL or another language.

Supplied File Handlers

The following list explains the function of each of the built-in file handlers and gives the MODE mnemonic you require to invoke each.

Mode	Purpose	Effect of Code
MODE PRINT	Basic printing This file handler performs the same basic print functions as when no file handler is used at all. Unless you already specify a MODE clause, it will be used automatically when any of the following features is used: PAGE BUFFER clause in SELECT DUPLICATED clause in SELECT STYLE clause UPON option of INITIATE CODEs of unequal length for RDs of same file.	Placed at start of print line, as in ANS standards. It is output after any carriage control characters.
MODE NOPF	Basic printing without using page feeds. This file handler fills each page entirely using line feeds.	Placed in print line after the carriage control.
MODE MODL	For use in a modular system. This file handler may be used by more than one separately compiled program in a run unit. Each program may thus write to the same report file. See listing below.	Placed in print line after the carriage control.
MODE CHAN	Make optimal use of any printer channels. The channel positions are fed into the file handler at run time, as described in Installation and Operation. The file handler automatically uses channel skips to get as near as possible to each target line. The RD does not change.	Placed in print line after the carriage control.
MODE DUPL (not VSE)	Emulate OS/VS and DOS/VS COBOL's ability to write to two files simultaneously. The file handler performs the OPEN, WRITE, CLOSE as appropriate for each file in turn.	Placed in print line after the carriage control.

User-Written File Handlers

An Independent Report File Handler is not usually developed as part of one program, but separately so that it can be used by all the report programs in a project. Only a brief specification is normally required, similar to those in the table of built-in file handlers below. Any application will then be able to use the file handler.

The file handler has a fixed LINKAGE SECTION, and the areas and their various locations are given in COBOL format below. For use in a language other than COBOL, translate the data-names and PICTUREs as appropriate.

The program-name of the file handler is related to the name of the MODE mnemonic. Full details are given in Operation and Installation.

Possible Uses of a File Handler

In this section we list some possible uses to which you might put a file handler.

Using COBOL-IT Report Writer for Non-Report Output

Provided your program's "report lines" contain no COMPUTATIONAL entries, you might adapt your file handler to produce output which is not intended for printing but instead for passing on to another program. Then, if you decide to ignore all LINE numbers, so that each "line" is another record irrespective of the "line advance", your file handler would simple do a WRITE without ADVANCING.

Output to database

Your program may be required to send its printed output to a database rather than in a sequential file.

Private STYLEs

If the printer has advanced features that require special programming, you can designate certain STYLEs as PRIVATE. The processing of such STYLEs is then left to your file handler. Full details are in Installation and Operation.

Output to multiple files

Your file handler may write to several files simultaneously, as outlined above (see Several Outputs From the Same RD) and under MODE DUPL above.

Using Code

In a "batch" report, the CODE is a "literal" prefixed to every print line. However, with a file handler you can designate the CODE clause for the passing of any additional information from the program to the file handler. Normally this is to control the output, rather than for output as part of the data. For example, given the necessary hardware and software prerequisites, you might decide to develop a file handler, and use the CODE clause, as follows:

Your possible file handler	Likely use of CODE
Microfiche output	Key for fiche indexing
Remote transmission	Identifier for remote printer
Spooled restart system	Key, page number, etc., for restart

The contents of the program's CODE operand appears in the file handler as the LINKAGE SECTION item L-RCA-CODE-VAL, as described later in this section.

Actions of an Independent Report File Handler

A file handler must perform certain mandatory housekeeping functions in order to execute correctly in combination with the report writer code. However, the method by which the report data is physically output is left entirely to the file handler.

If the file handler may be required to service more than one report file or INITIATEd report simultaneously, or be required to be usable by more than one program simultaneously, it should store its intermediate results in the File Control Area or Report Control Area, where certain locations have been reserved for discretionary use by the file handler.

The following are the mandatory housekeeping actions that must be performed by every file handler. The standard locations referred to are described later in this section.

• If the location L-FCA-ACT-IND is anything other than "0" or "9", "OPEN" the report "file". The file handler may interpret the OPEN function and the nature of the "file" in any way it wishes. The value of L-FCA-ACT-IND indicates the type of OPEN required (OUTPUT, EXTEND, or other).

• If the location L-RCA-ACT-IND is "6", "INITIATE" the report. The file handler may perform the INITIATE action in any way it wishes.

• If there is data to output, indicated by the field L-PRC-BYTE-CNT being non-zero, "print" the data. The exact nature of the "printing" activity is left entirely to the file handler and may differ widely from a "batch" WRITE statement. The following locations will be needed to accomplish this:

  • L-RCA-VERT-POSN contains the current vertical position or zero. If it iszero the file handler should execute a "form feed". This action should be omitted if L-RCA-PAGE-LIM is zero, indicating that the report is not divided into pages.

  • L-FCA-SUPP-PFD, if set to 1, indicates that the program has a FIRST PAGE NO ADVANCING clause in the SELECT...ASSIGN. If so, the "form feed" is not done and instead the current position is assumed to be "line 1". It is cleared automatically by the control routine.

  • L-RCA-LINE-CNTR contains the target vertical position. By subtracting L-RCA-VERT-POSN from this, you obtain the distance to be advanced.

• If the location L-RCA-ACT-IND is "8", "TERMINATE" the report. The file handler may perform the TERMINATE action in any way it wishes.

• If the location L-FCA-ACT-IND is "9", "CLOSE" the report "file". The file handler may interpret the CLOSE function in any way it wishes.

• By convention, there will never be more than one action from the possibilities OPEN, INITIATE, "print", TERMINATE, and CLOSE on any entry.

File Handler LINKAGE Areas

All the information required by the file handler is passed to it via optional user parameters and three standard LINKAGE areas, of which source copies are provided with this product.

Optional leading parameters: user-defined parameters

There may be any number of parameters at the start of the LINKAGE SECTION pre-determined by the user and specified through the USING phrase of the MODE clause. See Report Files for a description of this phrase.

• Parameter 1: File Control Area - he File Control Area contains information relating to the current report file. A File Control Area is set up for each report file that has a MODE clause.

  

  

  

• Parameter 2: Report Control Area - The Report Control Area is set up by the Precompiler for each report that is directed to a file that has a MODE clause. In the user program, the Report Control Area is identified by the report-name.

  

  

  

• Parameter 3: Report Data - This parameter contains the data to be written. For OPEN, INITIATE, TERMINATE and CLOSE operations, this parameter is a dummy with a value of zero in the counter L-PRC-BYTE-CNT. The number of bytes to be written may be reduced to the value in L-RCA-LINE-SIZE when it is non-negative.

  

Sample Independent Report File Handler

The following is the complete code of the standard MODL file handler (used for writing to a single report file from a modular system). This file handler is one of the simplest, and so it may be used as a model for your own user-written file handlers, which will require almost all the code that follows, except perhaps for the incrementing and decrementing of the "nest depth" (W-OPEN-NEST) which is peculiar to this file handler.

At least one file handler is supplied in source form with this product, giving you a machine-readable copy of most of this coding.