|
Report Files and RD Entries
Contents: This part contains full information about the COBOL Report Writer elements that can appear in the ENVIRONMENT DIVISION and FILE SECTION of your program, and then, in alphabetic order, the clauses that may be used in an RD entry.
Although most of the examples that follow use UPPER-CASE text, you may also use lower-case characters in any of the keywords and operands.
Report Files COBOL Report Writer produces output records and writes them automatically to COBOL report files when your program executes a GENERATE (see 4.2) or TERMINATE statement (see 4.6). 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. Format
b. FD entry: Format
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-YEAR-TOTALS. 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 (see 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 5.3). If you do code a record description after the FD entry, and you wish to obtain fixed-length 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. 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 5.3) 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 EXTERNAL and GLOBAL attributes have no effect. (Note that a report may still be GLOBAL, even though its corresponding file is not. Use of the MODL file handler also allows a report file to be treated as global (see 5.3.10). 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 re-compilation. 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. If both a type-name and DEFERRED are present, all styles will still be interpreted at run time, but the target device-name will be not need to be passed to the program at run time. The precompiler does not check that the given device-name exists. This enables you (on a Personal Computer) to use a symbolic device-name of your own choosing (for example TYPE IS PRINTER1) and create its Printer Description File later before execution, based on the one for an existing device. 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. The STYLE clause in the FD causes one or more styles to take effect for the file as a whole, currently on a Personal Computer only. Usually this means that a certain sequence of control characters will be sent to the printer just after the OPEN is executed and another sequence just before the CLOSE is executed. If no STYLE clause is coded, an implicit style for the file may take effect, if this has been defined in the Printer Description File. STYLE NORMAL ensures that no style takes effect at the file level. Full details are given in the next part (see STYLE Clause).
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 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 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. 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. 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 variable-length, 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 5.3).) FIRST PAGE WITH ADVANCING (the normal default)
is provided for symmetry.
Just as the FILE SECTION consists of a series of FD entries, each with record descriptions headed by an 01-level entry to follow, so the REPORT SECTION consists of RD entries, each followed by Report Group Descriptions headed by an 01-level entry. Your program may produce any number of reports, each with its own Report Description. Each Report Description consists of an RD entry followed by any number of Report Group Descriptions (although there are restrictions according to TYPE; see TYPE Clause). The order in which they are coded is immaterial. If several of the reports have strong similarities, you should define the report only once and make use of the DUPLICATED clause.
where report-description-entry is defined as follows: Format
REPORT SECTION and RD: Coding Rules All other DATA DIVISION sections, if present, should precede REPORT SECTION. Each report-name must be unique and must be the same as one of the report-names specified in the REPORT clause of one or more FD entries. (If a report-name appears in more than one FD, the UPON phrase of INITIATE is required, see INITIATE statement.) This correspondence is used to determine where the output is to be written. Each report-name introduced in the FD must match a report-name of an RD. The clauses of the RD may be written in any order; the order is not significant. Each RD entry is followed by at least one Report Group Description. These define all the report groups (sets of one or more report lines) that may be produced in the report. They are fully described in the next part (see TYPE Clause). If GLOBAL is specified, the report is available to any program contained in the current program, in the following senses: An INITIATE, GENERATE, or TERMINATE for the GLOBAL report-name may be issued from within a contained program, provided that the contained program itself does not have a locally-defined report of the same name. The contained program need not contain a REPORT SECTION. A GENERATE for any of the DETAIL report groups of the GLOBAL report may be issued from within a contained program, provided that the contained program itself does not have a locally-defined report and DETAIL group with the same names. If a GLOBAL report and a locally-defined report have different names but share DETAIL groups with the same name, these may be distinguished as usual by means of the IN/OF report-name qualifier. The special registers PAGE-COUNTER, LINE-COUNTER, LINE-LIMIT, and CODE-VALUE of the GLOBAL report, together with any sum-counters, may be accessed as GLOBAL items. Other report fields are not globally accessible. The CONTROL and SOURCE fields, or any other data items used during the processing of the GLOBAL report, are those that are accessible to the containing - not the contained - program. Thus, SOURCE items must normally also be GLOBAL if you wish to set up values in them and print them from within a contained program. If a contained program contains a GLOBAL report with an identical report-name, this will override the scope of original GLOBAL report until the end of the contained program. Similarly, a DETAIL group in a GLOBAL report of a contained program may override an identically-named one in the containing program. The program in which the GLOBAL report is defined must receive control at least once before the report can be accessed, even though it need not itself contain any procedural statements referring to the GLOBAL report. The STYLE clause causes one or more styles to take effect for the report as a whole. Usually this means that a certain control sequence will be sent to the printer just after the INITIATE is executed and another control sequence just before the TERMINATE is executed. If no STYLE clause is coded, an implicit style for the report may take effect, if this has been defined for the output device. STYLE NORMAL ensures that no style takes effect at the report level. Full details are given in the next part (see STYLE Clause).
The Formats and Rules for the other clauses in the RD are given in the sections that follow.
ALLOW SOURCE NO SUM CORR because it is based on the ANS 85 standard. You will need to code this clause only if you need to override the normal default, or if your program is to be portable and it is important to document which standard you are assuming.
¶ more than one DETAIL group, and ¶ a SUM clause referring to a data item that is defined in a section of your DATA DIVISION (other than the REPORT SECTION). For full details, see SUM Clause.
If you code the word NO the effect is reversed.
CODE Clause: Coding Rules The forms CODE IS and WITH CODE are synonymous. The CODE clause is not permitted if the associated FD entry is followed by a record description entry. This is because it would be illogical to WRITE independently to the file if there is also a CODE. See 2.2.2 and the rest of this section for further details. The literal, if coded, must be a non-numeric literal. If an identifier operand is used, it must represent a group field or a non-edited alphanumeric elementary field. The associated FD entry for the file must then have either a BLOCK CONTAINS clause with the CHARACTERS option or a RECORD CONTAINS clause, or both. If a mnemonic-name operand is coded, there must be an entry in SPECIAL-NAMES of the form: literal IS mnemonic-name where literal is non-numeric. The value of literal is then used as the CODE value. If you require compatibility with ANS-68 report writer, one character is the norm. For ANS-85 compatibility, you should code a two-character literal. If your report file description has a RECORD or BLOCK CONTAINS integer CHARACTERS clause and there is no MODE clause after SELECT, the size of the CODE, plus the maximum line width, must not be greater than the number of CHARACTERS specified. Not all RD entries associated with the same report file need have a CODE clause and all the CODE clauses need not specify an operand of the same length. However, if the report file does not use a user-written file-handler that might ascribe some meaning to different lengths of CODE, it may be impossible to recognize the CODE at the front of each records and decide how long it is.
If you do not specify a MODE clause after the SELECT for the corresponding report file, the value of the CODE is prefixed to every
record written by report writer to the report file. The CODE is placed after any line feed, carriage return, or other control characters:
If the length of the CODE is not the same for every report being written to the file, or if some of the reports have no CODE, then a MODE PRNT clause is assumed in default, causing the built-in PRNT file handler to be invoked. If you do specify a MODE clause after the SELECT, CODE-VALUE will be passed to the Independent Report File Handler in the Report Control Area. Built-in file-handlers (PRNT, MODL, NOPF) treat the CODE in the authodox way just described, but a user-written file handler may interpret CODE-VALUE in any desired way. Hence, your own user-written file handler may use the CODE clause for the passing of any additional information that is required by the file handler but does not necessarily appear in the report line itself. See Independent Report File Handlers for more information. If a literal or mnemonic-name is used, the size of CODE-VALUE is the length of literal, and CODE-VALUE is preset to the value of literal. If an identifier is used, the length of CODE-VALUE is the (maximum) record length given in the RECORD CONTAINS clause, minus the LINE LIMIT. The current value of identifier is stored in CODE-VALUE at the start of the processing for each DETAIL or CONTROL HEADING for the report. This does not occur if the current group is a CONTROL FOOTING, so as to ensure that only pre-control-break values will be used. In the following example (assuming ADV is in effect) the size of CODE-VALUE is 140 minus 132 = 8 bytes, and the field WC-ACCOUNT-REF is moved to CODE-VALUE at the start of each non-CF body group:
CONTROL Clause This clause should be coded in your RD if your report has additional lines, such as total lines and subheadings, that are to be produced upon a change of value in one or more "key" fields (known as control fields or simply controls).
CONTROL Clause: Coding Rules As the format shows, you may code either the special keyword REPORT (or its equivalent, FINAL), or a list of identifiers (control-ids), or both. Commas are optional but helpful separators here, but you should code at least one space or new line between the operands. At least one operand must be coded. REPORT, if present, must appear first in the list of control-ids. You may omit REPORT even if you refer to it in the Report Description. FINAL is an alternative name for REPORT. Each control-id must be REPORT/FINAL or the name of an unedited data item in the DATA DIVISION of your program. It must not be a special register in the REPORT SECTION, such as PAGE-COUNTER. You may include qualifiers and subscripts if necessary. A PICTURE of a control-id should not have a "V" (implied decimal point) symbol. You cannot use the same control-id more than once in the same CONTROL clause (unless a redefinition is used), but you can use the same control-id in different RDs. Control-ids are required to be either group items or unedited alphanumeric or numeric DISPLAY items with a maximum size. Thus edited items and items with a USAGE of COMPUTATIONAL or INDEX are prohibited. If you would like to use such an item as a control without restrictions on its format, you can simply REDEFINE it or use a group level item containing only the item in question:
It is acceptable for your control fields to overlap. The following usage is therefore allowed:
Coding the CONTROL clause enables you to include some additional elements in your report description, namely: ¶ You can specify a CONTROL HEADING and/or a CONTROL FOOTING group for each control-id, if needed. (See TYPE Clause.) ¶ You can code PRESENT/ABSENT AFTER clauses (formerly known as GROUP INDICATE) with any of the control-ids as operand to cause report fields, lines etc. to appear or disappear after a change in its value. (See PRESENT AFTER Clause.) ¶ You can defer the RESETting (zeroing) of a total field until after a change in a higher control. (See SUM Clause.)
In the following diagram, there are two levels of control. Two CONTROL HEADING groups and one CONTROL FOOTING have been coded. (There is no CONTROL FOOTING FOR YEAR.) The "boxes" around each of these groups shows their extent.
We have used some abbreviations in the following code - for example omitting the SOURCE and TYPE keywords - to save space. To shorten it further, you could abbreviate
CONTROL HEADING FOR YEAR and CONTROL FOOTING FOR YEAR as CH YEAR and CF YEAR.
The preceding diagram illustrates the following important points: Your CONTROL HEADING and CONTROL FOOTING groups are coded as separate 01-level report groups. You can lay out CH and CF groups exactly as you like, just as you would for a DETAIL; report writer imposes no pre-defined format on any groups. If you need a different CONTROL HEADING at more than one level (YEAR and MONTH in our example), you must code a new group for each level. This means that all groups may have different layouts. In this example, this applies also to the CONTROL FOOTING groups. (However, you can if you wish use the same group description for both levels by coding TYPE CF FOR YEAR, MONTH.) Report writer produces your CONTROL HEADING group at the start of each new value of the control. Similarly, it produces your CONTROL FOOTING group at the end of each new value of the control. CONTROL FOOTING groups are produced using the control values that existed before the control break. (See next item below for a fuller description of this.) Both the CONTROL HEADING and the CONTROL FOOTING groups are optional for each control-id. You may code just a CONTROL HEADING group, or just a CONTROL FOOTING group, or neither. The reserved word REPORT (or FINAL) is a special case representing the highest possible control. It is not a data-name. Include this as the first of your set of controls if you need special action to be taken once only at the beginning and end of the report; for example, if you require grand totals to be produced for the entire report.
Report writer keeps an internal copy of the pre-break contents of each control so that it may detect changes in the controls, known as control breaks. Ignoring the
special case REPORT or FINAL for the moment, whenever your program issues a GENERATE statement, the CONTROL clause causes report writer to compare the contents of each control with its
contents when the previous GENERATE was executed. The first control is examined first, then the second and so on. If no changes are found in any of the controls, no
special action is taken. As soon as a change is found in a control, no further controls are examined. A break in a higher control always implies a break in all the lower controls
, whether their contents have actually changed or not. (Obviously, 1991's JANUARY is a different month from 1992's JANUARY.) If you have more than one control, they must therefore
have a hierarchy. Here are some examples:
MONTH within YEAR CONTROLS ARE YEAR, MONTH
When a control break is detected, if your report has CONTROL FOOTING groups, each control field is first saved in a temporary holding area and is then overwritten with the contents it had before the break for the duration of the production of the CONTROL FOOTINGs. This means that your program will use the before-the-break contents of any CONTROL field (for example in a SOURCE, or a PRESENT WHEN) in the following TYPEs of group: a CONTROL FOOTING; a PAGE HEADING or PAGE FOOTING, when the page advance was caused by a CONTROL FOOTING; and in the following situations: when it is used as a SOURCE or SUM operand, either as it is or as a subscript or qualifier, or as part of an expression; when it is used as part of a condition; when it appears in a parameter to a FUNCTION; when it is referenced implicitly, that is, via a redefinition, or via a group field or subordinate field or an intersecting field. Only control fields exhibit their before-the-break values when referenced at CONTROL FOOTING time. To obtain the before-the-break value of a field other than a control field, you should use a Declarative procedure to save its current value (see USE BEFORE REPORTING Directive, Operation). After the lowest-level CONTROL FOOTING has been produced, and before any CONTROL HEADING or DETAIL groups are output, the current contents of all controls are restored . For a full description of the steps, see GENERATE Statement. Report writer will not detect a control break until your program issues a GENERATE. If a control field in your input data changes several times but no GENERATE is issued during that time, no control breaks will be detected. Your CONTROL identifiers need not be chosen just from ready-made locations in your input files or database. You may also "manufacture" them in WORKING-STORAGE. As a simple example, you may wish to print subtotals by quarter, although your main input gives just the months:
You cannot define more than one CONTROL HEADING or CONTROL FOOTING for a given control-id in your report. However, cases sometimes occur when you would like two CONTROL FOOTING report groups for the same level of control. You may achieve this referring to the same control field under a different name, as in the following case, where we must have two groups because the second part begins on a new page:
Here, the two controls W-ACCT-NO-1 and W-ACCT-NO-2 are physically the same field. Consequently, there will be a break in the higher control whenever there is a break in the lower control, and the two CONTROL FOOTING groups, GRP-A and GRP-B, will always appear together in that order. Report writer will consider a control break to have taken place if there is any change in the bit-pattern of the control field. For example, if the field is packed decimal (COMPUTATIONAL-3), a value of (hex) 123C and (hex) 123F will be considered different, even though they both represent the same numeric value. If this property is undesirable, your program should MOVE such a field to a DISPLAY field and use the DISPLAY field as the control field.
If your program has several Report Descriptions, each report is processed independently of the others. You can decide separately for each report whether it will have a CONTROL clause
and which controls to specify. When you issue a GENERATE for a report that has controls, report writer examines the controls for that report only, ignoring all the others.
Department A:
There may be other purposes for specifying an item as a control. You might include it for the following reasons: To trigger a PRESENT AFTER clause (or a GROUP INDICATE clause), or the RESET phrase of the SUM clause. To force a control break even though a lower control has not changed. You might want to output just monthly totals over several years' data. If you then declare MONTH as a control you must include YEAR too as a higher control, because it is quite possible for JANUARY 1991 to be followed immediately by JANUARY 1992 if you happen to have no data for FEBRUARY to DECEMBER 1991. (Note: in this example, you could also solve the problem by having just one control, YEAR-MONTH, if they are contiguous.) Because you may want to use the field as a SOURCE at CONTROL FOOTING time and you want to obtain the previous value of the field. (See item 2 above.) For example, you might have both CUSTOMER-NUMBER and CUSTOMER-NAME. By making CUSTOMER-NAME a control field following CUSTOMER-NUMBER (the "true" control field), you can be sure that you will see only the pre-break values of CUSTOMER-NAME at Control Footing time. For documentary purposes. The lowest-level controls need not be used at all in the program.
LINE LIMIT Clause: Coding Rules The value coded gives the maximum line width, in other words the greatest number of print columns required for your report. You may simply enter the column width of your printer, for example: LINE LIMIT IS 132 or, if your report is clearly designed to take up less than this number of columns, use that value instead. The identifier form of the clause is used if you wish the width of your report line to assume different values at different times. This form of the clause takes effect only when you use either the REPEATED Clause (see 3.19), or the WRAP Clause (see 3.28). The identifier must be an unedited numeric field. If the FD entry for the corresponding report file contains a BLOCK or RECORD CONTAINS integer CHARACTERS clause (other than BLOCK CONTAINS 0 CHARACTERS), the value of integer, and the size of any CODE field, must not be less the LINE LIMIT, or its default value (see item 3 in the section below).
If you use the identifier form of the clause, report writer evaluates its contents dynamically at INITIATE time and uses that as the value for the clause. For the purpose of checking the validity of COLUMN numbers, it will use the default maximum value described below. The value set up by the identifier is used at run time for the following purposes: to vary the number of REPEATED groups that may be placed side-by-side (see REPEATED Clause), as one means of adjusting the right margin when the WRAP clause is used to produce line wrap round (see WRAP Clause), to check for (illegal) line overflow in variable-position report fields when the WRAP clause is not used. If you omit the LINE LIMIT clause, report writer will assume a default value of the maximum line width. This is set to 256 in the report writer software as supplied but this default may be changed by customization to any other value (see Installation and Operation). The LINE LIMIT need not be the same as logical record length of the report file. The latter is established from the computed maximum length of the lines of the report, or from the RECORD or BLOCK CONTAINS clauses if present (see 2.2.3). An internal special register with the reserved name LINE-LIMIT is established in the Report Control Area, containing the value specified in the LINE LIMIT clause, or its default value.
Format b
OVERFLOW Clause: Coding Rules The OVERFLOW (format a) and SUM OVERFLOW clauses (format b) are distinct clauses and you may choose a different option for each. If your program contains no SUM clauses, the SUM OVERFLOW clause is not required. Similarly, if your program has no clauses of the form SOURCE arithmetic-expression , the OVERFLOW clause is not required. In either case, the clause may nevertheless be coded and it then has no effect. Use the OMITTED option if your report uses arithmetic expressions or has a SUM clause respectively but there is no likelihood of a size error. Use the REPLACE BY option if your report may be sensitive to improbable values in the user's data and you would like to show on the report exactly where errors have occurred. REPLACE BY can be followed by either a numeric or a non-numeric literal-1, whatever the PICTURE of your report field. Use the STOP option only if SUM or arithmetic overflow is extremely unlikely but potentially damaging and you are content for your program to execute an "emergency" COBOL STOP in such a case.
The SUM OVERFLOW clause takes effect if your program contains SUM clauses. On each addition, a check may be performed for size error. This clause does not affect any of the other functions of the SUM clause, such as the resetting (zeroing) of the totals. The default in each case is STANDARD (see below). If you choose the OMITTED option the effect is as follows: OVERFLOW: Report writer will not perform any checks for arithmetic overflow. This will save a small overhead on the evaluation of expressions. If a size error occurs, then at best your report field will have some high-order digits truncated. If a zero divide error occurs, your program will fail at run time . SUM OVERFLOW: Report writer will not perform any checks for SUM overflow. This will save a small overhead on totalling. If a size error occurs, at least one top digit will be truncated and lost from the total field. If you choose the STANDARD option, the effect is as follows: OVERFLOW: Report writer will always check for size error, or zero divide, when it evaluates each SOURCE expression. If this happens, your report field will be blank and a run time error 10 will be indicated. SUM OVERFLOW: Report writer will check for size error on each addition into a total field. If this happens, a run time error 11 will be indicated. No adding will take place into your total field and you will obtain the total up to the point just after the last valid addition. If you code the REPLACE BY option, the effect is as follows: OVERFLOW: Report writer will check for a size error or zero divide and, if this occurs, it will place your specified literal-1 in the SOURCE report field instead of the erroneous value. SUM OVERFLOW: Report writer will check for a size error and, if this occurs, it will place your specified literal-1 in the SUM report field instead of the erroneous value. In either case, if you choose a numeric literal-1, this value will be stored according to the rules of the MOVE statement. If you choose a non-numeric literal-1, the literal will be stored, as for a MOVE, in your report field, treated as though it were redefined as an unedited alphanumeric field (PIC X...). For example, if overflow occurs and your report field is defined as:
and your RD contains the clause: OVERFLOW PROCEDURE IS REPLACE BY ZERO, the following will appear:
If you code the STOP option, report writer will execute a COBOL STOP literal-2 as soon as an error is detected.
PAGE LIMIT Clause: Coding Rules The format above gives you choices of keywords, and in each case the different keywords have the same meaning. Traditionally, the sub-clauses were referred to as the HEADING , FIRST DETAIL, LAST DETAIL, and FOOTING phrases. We also usually refer to the whole clause as the PAGE LIMIT clause, even though the word LIMIT is optional. Each of the sub-clauses is optional, but none of the first four sub-clauses may be present without the PAGE LIMIT sub-clause. You may code the sub-clauses in any order , and they may appear anywhere in the RD statement. The order shown follows a natural progression from the top to the bottom of the page and is therefore recommended for maximum lucidity. The values of integer-1, integer-2, integer-3, and integer-4 (if you code their sub-clauses), and integer-6 represent the start and finish points of various regions of your page, working down from the top to the bottom. Ensure that the regions start and finish in the order shown in the diagram below (see 2.9.3). Any two integers may be equal. All integers must lie between 1 and 9999 inclusive. If you use the identifier form of the LAST DETAIL sub-clause, the identifier used must be an unedited numeric field and its value at every generation of your report must lie between the FIRST DETAIL and LAST CONTROL FOOTING positions, inclusive. By using the + integer-5 form of the LAST CONTROL FOOTING sub-clause, you specify the extra lines to be made available to CONTROL FOOTING groups. Ensure that you cannot exceed the PAGE LIMIT: that is, the LAST DETAIL value (identifier-1 or integer-3) + the LAST CF offset (integer-5) must be not greater than the PAGE LIMIT (integer-6 ). The FIRST four PAGE LIMIT sub-clauses may all be omitted. Here are some guidelines on their use: HEADING is never required. However, if your report has a PAGE HEADING that begins with a relative LINE, you may use HEADING as an anchor point for the start of that group. FIRST DETAIL should be coded if you have a PAGE HEADING group, especially one that might vary in depth, and you want the body of the page to follow at a fixed position underneath it. LAST DETAIL should be coded if you have a PAGE FOOTING group and want the body of the page to end short of the line preceding it or if you want to use LAST DETAIL in conjunction with LAST CF as described in the next paragraph. Use the LAST DETAIL identifier form if you want to vary the logical page depth dynamically. LAST CF (or LAST CONTROL FOOTING, or FOOTING) should be coded if you have CONTROL FOOTING groups and want to leave some space before the PAGE FOOTING begins. (If the option is not in effect, this may be provided automatically - see item 7 in the next section.) If you omit the PAGE LIMIT clause, your report will consist of one continuous stream of output without page breaks. Your Report Group Descriptions will then not be able to contain absolute LINE (see LINE Clause), or NEXT GROUP (see NEXT GROUP Clause), PAGE HEADING and FOOTING groups, or any form of any clause that makes use of the keyword PAGE.
Each of your groups will be checked to fit into its appropriate region. (The REPORT HEADING and REPORT FOOTING groups are special cases.) The fitting of groups on the page is described in detail in the next part (see LINE Clause). If you code a HEADING sub-clause, its value will be used in the case where you have a PAGE HEADING or a REPORT HEADING group whose first LINE clause is relative . Those groups will then be positioned relative to the value of HEADING minus 1. (Compare the different rule for the positioning of a relative first LINE clause in a body group at FIRST DETAIL, see LINE Clause.) The region between FIRST DETAIL and LAST CONTROL FOOTING inclusive is the body of the page. Apart from the optional REPORT HEADING and REPORT FOOTING groups, which may appear anywhere on the page, only body groups (CONTROL HEADING, DETAIL, and CONTROL FOOTING) will appear in this region. However, if a PAGE HEADING group encroaches into the FIRST DETAIL position, a diagnostic message (096) will be issued and the first body group will appear immediately after the PAGE HEADING group (as though the FIRST DETAIL were absent - see below). CONTROL HEADING and DETAIL groups are not allowed to appear below the LAST DETAIL position. If LAST DETAIL is above LAST CONTROL FOOTING, your CONTROL FOOTING groups will thereby have extra space available to them. This extra space reduces the likelihood of the displeasing effect that results when they are forced to the top of a page. (See LINE Clause for more details.) You can imply this spacing by making LAST DETAIL fall short of PAGE LIMIT (or short of the line before the PAGE FOOTING if you have one). An alternative way to indicate this extra space is to code: LAST CONTROL FOOTING IS +integer-5. If you code the identifier form of the LAST DETAIL sub-clause, report writer will take the contents of the identifier at the start of each GENERATE and use that as the value for the sub-clause. If you use the relative form of the LAST CONTROL FOOTING sub-clause (with +), the number of lines you specify will be added to the LAST DETAIL value to give the LAST CONTROL FOOTING value. For example: LAST CONTROL FOOTING + 3 specifies that 3 extra lines are to be available during the page fit for CONTROL FOOTING groups, regardless of any variations in an identifier operand of LAST DETAIL.
If you omit any of the first four optional sub-clauses, and report writer needs their values, it will infer default values according to the following rules:
The following examples show some possible forms of this clause:
This form is valid for all situations because of the defaults. All your body groups will fit between your PAGE HEADING (or line 1 in its absence) and your PAGE FOOTING (or line 60 in its absence).
This reserves lines 1-4 for the PAGE HEADING and, if your report has no PAGE HEADING, they will be left blank. Your CONTROL FOOTING groups may come down to the line before any PAGE FOOTING, or line 60 if there is no PAGE FOOTING, but CONTROL HEADING and DETAIL groups must end 3 lines before that point.
Here the value of WS-PAGE-SIZE will be used as the lower limit for all body groups (since the identifier form of LAST DETAIL causes LAST CONTROL FOOTING to default to LAST DETAIL instead of to PAGE LIMIT). |