Start RGR software reference manual at next page R G R ======= Software Reference Manual Version V2.0 November 1983 This document describes how to use the Report Generator Routines (RGR). It provides the information required to design reports for printing on a video terminal and/or lineprinter or printing-terminal and to develop programs that use RGR-reports for output. Contents CHAPTER 1 Introduction to RGR 1.1 Overview . . . . . . . . . . . . . . . . . . . . . 1-1 1.2 Report source file . . . . . . . . . . . . . . . . 1-2 1.3 Report compiler . . . . . . . . . . . . . . . . . 1-2 1.4 Report driver subroutines . . . . . . . . . . . . 1-2 CHAPTER 2 Report source file 2.1 Overview . . . . . . . . . . . . . . . . . . . . . 2-1 2.2 Terminology . . . . . . . . . . . . . . . . . . . 2-2 2.2.1 Report lay-out . . . . . . . . . . . . . . . . . 2-2 2.2.2 Report page . . . . . . . . . . . . . . . . . . 2-2 2.2.3 Report description . . . . . . . . . . . . . . . 2-2 2.2.4 Field . . . . . . . . . . . . . . . . . . . . . 2-2 2.2.5 Report source file . . . . . . . . . . . . . . . 2-2 2.2.6 Reports library file . . . . . . . . . . . . . . 2-2 2.2.7 Reports document list file . . . . . . . . . . . 2-3 2.3 Numeric picture . . . . . . . . . . . . . . . . . 2-3 2.4 Location . . . . . . . . . . . . . . . . . . . . . 2-4 2.5 Report description language . . . . . . . . . . . 2-4 2.5.1 REP-record . . . . . . . . . . . . . . . . . . . 2-5 2.5.2 HDR-record . . . . . . . . . . . . . . . . . . . 2-6 2.5.3 FIX-record . . . . . . . . . . . . . . . . . . . 2-6 2.5.4 TEX-record . . . . . . . . . . . . . . . . . . . 2-7 2.5.5 DAT-record . . . . . . . . . . . . . . . . . . . 2-7 CHAPTER 3 Report compiler 3.1 Running the compiler . . . . . . . . . . . . . . . 3-1 3.2 Output from the compiler . . . . . . . . . . . . . 3-2 3.2.1 Reports library file . . . . . . . . . . . . . . 3-2 3.2.2 Reports document list file . . . . . . . . . . . 3-2 3.2.3 Error messages . . . . . . . . . . . . . . . . . 3-3 CHAPTER 4 Introduction to the report driver subroutines 4.1 Program access to reports . . . . . . . . . . . . 4-1 4.2 Defining reports and fields by name . . . . . . . 4-2 4.3 Printing the report . . . . . . . . . . . . . . . 4-2 CHAPTER 5 Form driver subroutine calls 5.1 RGRCLS - close output stream . . . . . . . . . . . 5-1 5.2 RGRDAT - output relative data . . . . . . . . . . 5-2 5.3 RGREND - close all units used by RGR currently open . . . . . . . . . . . . . . . . . . . . . . . 5-2 5.4 RGRLOC - return location . . . . . . . . . . . . . 5-2 5.5 RGROPN - open reports library file . . . . . . . . 5-3 5.6 RGROUT - open or re-open output stream . . . . . . 5-4 5.7 RGRPOS - choose a report from the reports library 5-4 5.8 RGRPRT - print the current page . . . . . . . . . 5-5 5.9 RGRPUT - output text at absolute location . . . . 5-5 5.10 RGRTEX - output relative text . . . . . . . . . . 5-6 5.11 RGRTPG - test page . . . . . . . . . . . . . . . . 5-6 CHAPTER 6 Software example 6.1 Create report source file . . . . . . . . . . . . 6-1 6.2 Create reports library file . . . . . . . . . . . 6-2 6.3 Write FORTRAN IV application program . . . . . . . 6-3 CHAPTER 7 System internals 7.1 System subroutines . . . . . . . . . . . . . . . . 7-1 7.2 System size . . . . . . . . . . . . . . . . . . . 7-1 7.3 Overlay requirements . . . . . . . . . . . . . . . 7-2 CHAPTER 1 Introduction to RGR 1.1 Overview RGR is a set of Report Generator Routines. RGR software contains the tools for developing report applications with direct addressing facilities per output page and running them on a normal printing device. Printed reports have been the most common tool for showing data in a sequential manner. RGR software now brings the speed, and low cost of computerized processing and the convenience of page addressing which, until now, did not exist for the conventional hardcopy devices. RGR is written in FORTRAN IV for RT11/RSTS and FORTRAN IV+ for RSX-11M. Reports are designed by the use of a report description language described furtheron in this manual. RGR associates constant data with the report, not with the application program, resulting in simplified application program maintenance and increased application program flexibility. Reports can later be modified without the need to recompile the application program. RGR software has three main components for developing and executing report application programs: - report source file - report compiler - report driver subroutines Introduction to RGR page 1-2 1.2 Report source file The report source file contains records which describe the reports as a whole by defining the fields (name, length, page position etc.). These records are legible ASCII-character strings (report description language), and can be created and/or modified by any available text editor. When designing reports, you assign report names, field names, and refer to data that will be used by the report driver subroutines, when the report is used by an application. The desired information to be displayed on reports is controlled by the actual design of the report and the specific application requirements. 1.3 Report compiler The report compiler RGR allows you to create and modify reports libraries and versions of report descriptions that are suitable for hard-copy listings (reports document list file). 1.4 Report driver subroutines The report driver subroutines are a set of routines that permits your application program to access reports from a reports library created by the report compiler. Application programs access reports by issuing report driver subroutine calls that are embedded in the program and are written in the source language of the program. All report driver subroutine calls refer to specific reports and/or fields within the reports by the names you assigned to them in the report source file. CHAPTER 2 Report source file 2.1 Overview Using any text editor available on your system and the report description language, you can create, modify and store customized reports. Your application programs can then use these reports to output data in the defined lay-out. Creating or editing a report is an interactive and iterative process. You can test the various possibilities by observing the reports document list file or by testing your design using a small test program (see software example elsewhere). The product of your editor work is one or more report descriptions in the report source file, that can be translated by the report compiler into the reports library file. The report descriptions can be retrieved from the report source file for additions or modifications. You can change individual fields or text portions of the report without affecting other fields or text. For example, you might want to translate the text of a report, being fix text and therefore beyond control of the application program, into another language, reposition items on the lay-out to make the report more attractive to the eye, add or remove fields, or supply additional fix text. You can make these and other changes by editing the report source file and recompile it into the reports library file. The purpose of the report description is to provide information to another software component: the report driver subroutines. These routines handle the interaction of the application program with the report lay-out displayed on the screen and/or printed on a hardcopy device. Report source file page 2-2 2.2 Terminology 2.2.1 Report lay-out The report lay-out is the definition and positionning of texts and fields on a report page. The computer positions output data on the lay-out by using a report description that specifies to the computer which characters where to be put on the page. 2.2.2 Report page The report page is the physical medium (number of lines and columns) that collects a (hard-)copy of the report. 2.2.3 Report description The report description is the computer's specifications of a report. It specifies which characters and/or fields to put on the report lay-out as well as the location which can be defined absolute or relative. The name of the report and how the report and its fields are processed are also part of the specification. 2.2.4 Field A field is a set of contiguous report page positions with defined starting position (absolute/relative) and field length. A field can be a fix text string or a formatted blank for some of the information that a report has been designed to work with. 2.2.5 Report source file The report source file is a computer file that contains one or more report descriptions in legible ASCII format (report description language). It can be modified by the use of any text editor and must be compiled by the report compiler in order to make the report description(s) processable by the report driver subroutines. 2.2.6 Reports library file The reports library file is a computer file containing at least one report description. It is a binary file is arranged so individual report descriptions can be accessed by name for use by report driver subroutines. Report source file page 2-3 2.2.7 Reports document list file The reports document list file is a legible ASCII file showing full documentation on the contents of a reports library file (report names, report lay-outs, field-name and -length). 2.3 Numeric picture A picture or numeric picture-string is a character string defining the print lay-out for a value. Pictures for (numeric) fields must be coded according to the report description language as follows: 9 indicates a normal (no zero suppress) numeric position. Z indicates a numeric position with zero supression. For the integer part of a picture: "9"-characters may not appear to the left of "Z"-characters. For the decimal part of a picture: "9"-characters may not appear to the right of "Z"-characters. S indicates that the sign must be printed (+ or -). When the "S"-character is the rightmost character of the picture-string or elsewhere positioned to the left of a "9"-character then the sign is fixed to that postion. In other cases the sign is floating to the left of the leftmost significant character. E as the rightmost character of the picture-string indicates exponential notation. The printed picture-string will be enlarged by three characters: sign and exponent (+nn). The rightmost character in the picture-string different from the above mentioned characters (9,Z,S and E) will be treated as the decimal point. The presence of more than one "strange" character in the picture is allowed and provides the possibility of displaying numeric data with special (non-numeric) characters between the characters representing the number. Report source file page 2-4 2.4 Location Location parameters (data items) define the type (absolute or relative) of positionning of the leftmost character of a text or field in the report lay-out. A location is a string with two integer numbers separated by any non-numeric character (not a comma!). The first integer defines the row (absolute) or number of rows (relative) and the second integer indicates the column (absolute) or number of positions (relative). - Absolute coordinates have no sign character and must have values greater than zero and within the defined ranges (report lay-out logical page size). - Relative coordinates must have a sign character (+ or -) and may be equal or less than zero. 2.5 Report description language The report description language is the language used to describe reports in the report source file. It is legible ASCII format and can be created and/or modified by any text editor available on the system. Every report description record contains a record type code and one or more data items which hold the describing information. Record type code and data items within one record are mutually separated by comma's. Text-strings (always the last data item in a description record) may contain comma's without being considered as data item separators. Description records may have a maximum length of 127 characters. Record type code, report name and field-name may appear in upper-case, lower-case or mixed-case, and are transferred to upper-case by the report compiler. Text-strings are not modified in any way. Report source file page 2-5 2.5.1 REP-record The REP-record defines the start of a new report description in the report source file and has following format: REP , name , phys.page , log.page , window , row where: REP is the record type code. name is the name of the report (max. 6 characters). This is the name by which the report is referred to by the application program. phys.page is the number of lines per physical page of the output device. If zero, RGR assumes that the output device can handle hardware formfeeds. If -1, RGR uses the compiler default (66 lines). log.page are two integer numbers: number of rows and columns of the logical page (i.e. report lay-out). The two integers must be separated by any non-numeric character (not a comma!). window are two integer numbers: number of first and last row in the logical page addressable by relative coordinates. The two integers must be separated by any non-numeric character (not a comma!). row is an integer number indicating how many rows from the previous report must be copied into the current report (in the workfile). If not given the whole previous report will be cleared. In this way it is possible to combine two reports. Report source file page 2-6 2.5.2 HDR-record The HDR-record defines some heading facilities provided by RGR and has following format: HDR , date , time , page , start where: HDR is the record type code. date location of the date string (dd-mmm-yy). Must be absolute or blank (no date). time location of the time string (hh:mm:ss). Must be absolute or blank (no time). page location of the page number (nnn). Must be absolute or blank (no page number). start location of the imaginary printhead after the fix text and/or heading info is printed. 2.5.3 FIX-record The FIX-record defines a text-string at a fixed position (fix text) which will appear on all pages of the report (e.g. header lines) and has following format: FIX , location , text-string where: FIX is the record type code. location is the location parameter for this text. Must be absolute coordinates. text-string string to be printed, leading and trailing spaces are discarded. Report source file page 2-7 2.5.4 TEX-record The TEX-record defines a text-string which will appear on a report page under application program control only (relative text). It has following format: TEX , name , location , text-string where: TEX is the record type code. name is the name of the field (max. 6 characters). This is the name by which the field is referred to by the application program. location is the location parameter for the text, and may be absolute or relative coordinates. text-string string to be printed, leading and trailing spaces are discarded. 2.5.5 DAT-record The DAT-record defines a field (=blank area), where data can be printed under control of the application program (relative data). It has following format: DAT , name , location , data-type , length/picture where: DAT is the record type code. name is the name of the field (max. 6 characters). This is the name by which the field is referred to by the application program. location is the location parameter for the text, and may be absolute or relative coordinates. data-type is a character that indicates the type of data: S = character string I = numeric integer R = numeric real length length of the string in case of data-type "S". or picture picture-string defining the print lay-out of the value in case of data-type "I" and "R". For the definition of a numeric picture see elsewhere in this manual. CHAPTER 3 Report compiler The report compiler is the only program that creates and modifies reports library files. The compiler should be used when you want to examine the contents of a reports library file. The compiler provides following sevices: - Translates a (legible ASCII) report source file into a (binary) reports library file. - Creates a reports document list file, showing the contents of the reports library file. 3.1 Running the compiler To run the compiler type: RUN RGR The compiler returns with an identification and asks for a source file name and whether a reports library file and/or document list file should be made. The programs for RSX and RT11 ask their questions differently. RSX asks wether the output files must be created or not, while RT11 asks for the device where the output files must be written to. Both create the output files with fixed filenames depending on the source filename. For RT11 : Source file : If a name is entered without extension, the compiler will search for the existence of a file with extension ".REP". Report compiler page 3-2 Device Library file : Enter the divice where the compiler must write its library file with extension ".REX". Default is no library file. Device Document file : Enter the divice where the compiler must write its document list file with extension ".RLS". Default is no document file. For RSX : Source file : If a name is entered without extension, the compiler will search for the existence of a file with extension ".REP". Library file : If Yes is entered the compiler will create a library file with extension ".REX". Default entry is "Y". Document file: If Yes is entered the compiler will create a reports document list file with extension ".RLS". Default entry is "Y". Now the compiler prints all the names of the reports encountered in the report source file and the eventual error messages. 3.2 Output from the compiler 3.2.1 Reports library file The reports library file is the only file used by the report driver subroutines, and must have the extension ".REX" in order to be accessable. 3.2.2 Reports document list file The reports document list file is a legible ASCII printfile showing the contents of the reports library file. For every report in the library file it shows three types of information: - report page parameters showing the physical and logical sizes of the report. - report lay-out containing all text and relative data fields with absolute location (represented by the text itself or the defined picture resp. a number of Report compiler page 3-3 "X"-characters for strings). - relative text and relative data description data. 3.2.3 Error messages If the compiler discovers soft or hard errors during compilation of the report source file, it can issue three kinds of messages to the terminal screen and to the reports document list file (if active): W (warning) if applicable invalid data will be replaced by compiler defaults. E (error) invalid data send to the library (if active) which will result in erroneous execution of the report driver subroutines. F (fatal error) non-recoverable error, resulting in compiler execution halt. Error messages have following lay-out: ?RGR-t-[record type code/[field name/]] message-text where: t is the error type code: W, E or F. record type code is the identification of the report description record where the error was found. field name is the name of the field where the error was detected. CHAPTER 4 Introduction to the report driver subroutines The report driver subroutines are a set of routines that is a subcomponent of your program. In an application that uses printing as output mechanism, using the report driver subroutines can reduce your programming effort by manipulating the output device (lineprinter or printing/video-terminal). This chapter discusses how the report driver subroutines interact with the report description as created in the report source file. The term "report" refers to the image printed on the output device and to the computerized report description that the report driver subroutines handle internally. Throughout the chapter, programming requirements are mentioned and specific subroutine calls are mentioned occasionally but not fully described. In the next chapter the calls are arranged in alphabetical order and full description is presented for each one. 4.1 Program access to reports Your program uses report descriptions by reading them from the reports library file that has been stored on a mass storage volume, such as a disc. Report descriptions created in the report source file must be translated by the report compiler into the reports library file, in order to be accessable by the report driver subroutines. Introduction to the report driver subroutines page 4-2 4.2 Defining reports and fields by name The name that you assign to a report in the report source file is the only information that the report driver subroutines need to read the report from the reports library file. The name that you assign to a field in the report source file is all the form driver subroutines require, regardless of where you locate the field within the report. As long as changes to report and field characteristics have no effect on the logic of your programs, you can change the characteristics without having to modify your programs. 4.3 Printing the report A typical procedure for issuing a report in an RGR application is as follows: 1. For all applications, open the reports library file. This is done with the RGROPN call. 2. Define one or more output streams by issuing the the call RGROUT. Up to four streams may simultaneously be open, providing a maximum of four similar output streams on different devices. Issue a RGROUT call for every output stream requested. 3. Position the library file at the desired report. This is done with the RGRPOS call. 4. Fill the report lines by using the call for RGRDAT (output relative data field), RGRLOC (return actual page location), RGRPUT (print text at absolute location) and/or RGRTEX (print relative text). 5. Output the actual report page to the defined output streams by the use of the RGRPRT call. The report driver subroutines RGROUT and RGRCLS provide a mechanism to close a particular output stream temporarely (output stream suspended but logical channel number remains open) or final (logical channel number closed). CHAPTER 5 Form driver subroutine calls A flexible set of report driver subroutines provide functions that print reports. The descriptions below show what each call does, what input arguments it requires, and what output it returns to your program. For each call, syntax is indicated. 5.1 RGRCLS - close output stream The report driver subroutine closes an output stream temporarely or final. CALL RGRCLS (unit, keyword) where: unit is the INTEGER logical unit number for the file. keyword is a STRING containing one of the following keyword parameters: FIN - close the output stream (i.e. close the logical unit number physically). TMP - close the output stream temporarely (i.e. output to that logical unit number is suspended but the stream can be activated again by RGROUT). Form driver subroutine calls page 5-2 5.2 RGRDAT - output relative data The report driver subroutine puts the data on the report page at the specified location. If necessary (relative coordinates and page is full) the current report page buffer is printed automatically (auto-page by RGRPRT) and actual text is directed to a new page buffer. CALL RGRDAT (field, data) where: field is a STRING containing the name of the field. data is a STRING, INTEGER or REAL variable according to the type of the specified field and, in case of numeric data, will be printed according to the picture specification in the report library file. 5.3 RGREND - close all units used by RGR currently open This routine should be the last RGR-call in the program before the program exits and must be used under RT11 before chaining to another program. CALL RGREND 5.4 RGRLOC - return location The report driver subroutine returns the row and column number defining the actual position of the imaginary printhead in the page. CALL RGRLOC (row, column) where: row is the INTEGER row number. column is the INTEGER column number. Form driver subroutine calls page 5-3 5.5 RGROPN - open reports library file The report driver subroutine opens the specified reports library file on a given logical unit number. CALL RGROPN (file, lunit, wunit, device) where: file is a STRING containing the name (max. 6 characters), eventual with device but without the extension of the reports library file. The extension ".REX" will be assigned by the subroutine. lunit is the INTEGER logical unit number for the library file. wunit is the INTEGER logical unit number for the work file (report page buffer), buffering the report page as long as the page is not printed (by RGRPRT). device is a STRING containing the device name on which the workfile will be stored. If device is a null-string the default device will be used. Form driver subroutine calls page 5-4 5.6 RGROUT - open or re-open output stream The report driver subroutine activates an output stream by opening a new logical unit number (=open) or by re-activating a previous defined output stream that is temporarely closed by a RGRCLS call (=re-open). CALL RGROUT (unit, copy, lpage, file) where: unit is the INTEGER logical unit number for the output stream device. copy is the INTEGER number of copies per page to be printed. In case of "open", a value equal or less than zero is modified to one. In case of "re-open", a value equal or less than zero does not modify the originally defined number of copies. lpage is the INTEGER number of lines per physical page of the output device. If zero, RGR assumes that the output device can handle hardware formfeeds. If -1, RGR uses the value as defined by the report description in the reports library file. file is a STRING containing the file name and/or device of the output stream. In case of re-open, the unit number is sufficient identification and file name can be a null-string. 5.7 RGRPOS - choose a report from the reports library The report driver subroutine searches the reports library file for the specified report. CALL RGRPOS (report, npage) where: report is a STRING containing the report name (max. 6 characters). npage is the INTEGER number to reset the page numbering at the specified value for the next output page. If equal or less than zero, no reset is done. Form driver subroutine calls page 5-5 5.8 RGRPRT - print the current page The report driver subroutine outputs the current report page buffer to all the active output streams, as many times as defined by the number of copies specified per output stream. CALL RGRPRT This routine has no argument list, and will be executed automatically when the report page buffer overflows while processing RGRDAT or RGRTEX calls for fields with relative row-coordinates. Any application always should issue one RGRPRT call in order to direct the last report page buffer to the active output streams. If an output stream is specified with name: "KB:", "TT:" or "TI:", then RGR assumes a video terminal as output device which means that the RGRPRT automatically switches the terminal to 132 characters per line (if your terminal features that function) at the beginning of every report page and operator response (hit RETURN key) is requested at the end of every page. 5.9 RGRPUT - output text at absolute location The report driver subroutine outputs a text-string at absolute location to the report page buffer. This routine can also be used to restore a previously determined location (with RGRLOC), in which case the text-string may be a null-string. Row and/or column zero will be accepted but no text will be printed in that case. CALL RGRPUT (row, column, text) where: row is the INTEGER absolute row number of the report page or zero. column is the INTEGER absolute column number of the report page or zero. text is the STRING containing the text. May be a null-string. Form driver subroutine calls page 5-6 5.10 RGRTEX - output relative text The report driver subroutine puts the relative text-string as defined by the report description in the reports library on the report page at the specified location. If necessary (relative coordinates and page is full) the current report page buffer is printed automatically (auto-page by RGRPRT) and actual text is directed to a new page buffer. CALL RGRTEX (field) where: field is a STRING containing the name of the field. 5.11 RGRTPG - test page This routine can be used in two modes. In the first mode the driver is asked how many lines are available from the virtual cursor to the end of the window. In the latter mode the driver is asked to perform an auto-page, that means that the current report page buffer is printed, if less than a given number of rows has been left between the virtual pointer and the end of the window. CALL RGRTPG (mode, rows) where: mode is an INTEGER number indicating: 0 - ask for number of rows left. 1 - do auto-page if number of rows left not sufficient. rows is an INTEGER that is filled if mode=0 or that gives the number of rows for the testpage if mode=1. CHAPTER 6 Software example RGR programs must be written according to the rules of the specific language used. Programmers should consult their language reference manual for this information. The next step to running an RGR application is linking the program to the report driver subroutines library so that the calls to the report driver subroutines will be processed. 6.1 Create report source file Create a report source file (DEMO.REP), using any available text editor, with following contents: REP , DEMREP , 0 , 60/120 , 5/55 HDR , 1/55 , 1/75 , 1/95 , 4/0 FIX , 1/1 , This is the first header-line of the DEMO FIX , 1/50 , date FIX , 1/70 , time FIX , 1/90 , page FIX , 2/5 , Second header line starts at column 5 FIX , 60/1 , Last line of logical page TEX , RTEXT1 , +1/1 , Relative text 1 TEX , RTEXT2 , 25/+8 , Relt-2 DAT , RDAT1 , -1/40 , I , Z9 DAT , RDAT2 , +0/+3 , R , 99.999E DAT , RDAT3 , 40/10 , S , 5 Software example page 6-2 6.2 Create reports library file Compile this report source file using the RGR compiler, creating a library file (DEMO.REX) with one report, and the reports document list file (DEMO.RLS). RUN RGR RGR-report compiler - V1.0 dd-mmm-yy time hh:mm:ss RT11 RSX Source file : DEMO Source file : DEMO Device Library file : DK: Library file : Device Document file : DK: Document file: DEMREP DEMREP Software example page 6-3 6.3 Write FORTRAN IV application program Now create a FORTRAN IV test program: PROGRAM RGRDEM C CALL RGROPN ('DEMO',20,21,'') ! open library CALL RGROUT (22,1,0,'LP:') ! open output stream CALL RGRPOS ('DEMREP',1) ! position at report C DO 10 I=1,3 ! RTEXT1 at column 1 CALL RGRTEX('RTEXT1') ! on row 5,6 and 7 10 CONTINUE C CALL RGRPUT(21,0,'') ! position row 21 I=20 20 CALL RGRDAT('RDAT1',I) ! RDAT1 and RDAT2 CALL RGRDAT('RDAT2',1.234*10.**I) ! on rows 20 - 10 I=I-1 IF (I.GE.10) GOTO 20 C CALL RGRPUT(0,0,'') ! position column 0 DO 30 I=1,5 CALL RGRTEX('RTEXT2') ! RTEXT2 5x at row 25 30 CONTINUE C CALL RGRPUT(30,0,'') ! position row 30, column 0 DO 40 I=1,5 VAL=1.11111*I*10.**(I-1) CALL RGRDAT('RDAT2',VAL) ! RDAT2 5x at row 30 40 CONTINUE C CALL RGRDAT('RDAT3','AbCdEfGhIjK') ! string truncated C CALL RGRPUT(50,0,'') ! position row 50, output 20 DO 50 I=1,20 ! lines with RTEXT1. After CALL RGRTEX('RTEXT1') ! 5 lines, data window over- 50 CONTINUE ! flow will cause auto-page C CALL RGRPRT ! output last report page buffer C CALL RGREND END Compile this program and link it with the report driver subroutines library. CHAPTER 7 System internals Information on the RGR package, as described in the previous chapters, might in most cases do for understanding and using the report driver subroutines properly. For maintenance on the package and in special cases where linking in overlay is required, more information of the system internals might be useful. 7.1 System subroutines Besides the report driver subroutines previously described, there are five more subroutines in the package used by the report driver subroutines: RGRCS - copies text-strings into the report page buffer. RGRIP - initializes the report page buffer. RGRPS - determines the absolute position in the report page buffer and puts the text starting at that position. RGRWR - writes the actual row into the report page buffer and reads a new actual row from the report page buffer into the common area (RGRCOM). RGRWS - combines RGRWR and RGRCS for absolute locations. 7.2 System size The RGR subroutines use alltogether about 5.5 K words of memory plus .25 K words per I/O buffer used (=open logical unit number). Because not all report driver subroutines are necessarely used, this size can be reduced according to the specific application requirements. RGR uses a common area with the name RGRCOM and a size of 561 bytes (281 words) for the communication between the various report driver subroutines. System internals page 7-2 7.3 Overlay requirements Not all of the report driver subroutines may overlay one another. Because RGRDAT and RGRTEX can issue calls to RGRPS with relative location this subroutine may, under certain circumstances (data window overflow), want to call RGRPRT for auto-page. All the other report driver subroutines may overlay each other. The five system subroutines can also call each other so, when overlay structures are required, carefully study the contents of Table 1. If the linkage editor does not automatically places the common area RGRCOM in the root of the overlay structure, a common area as described in the previous section must be declared in the root-segment of the program. Table 1 shows which report driver subroutines issue calls for other RGR-, USERLIB- and/or SYSLIB-subroutines. Table 1: Subroutine calls of the system subroutines: cal \ by| RGR RGR RGR RGR RGR RGR RGR RGR RGR RGR RGR RGR RGR RGR -led \ | CLS DAT END LOC OPN OUT POS PRT PUT TEX TPG PS WR WS --------+----------------------------------------------------------- RGRPRT | X X | RGRCS | X X X RGRIP | X X RGRPS | X X X RGRWR | X X X X X RGRWS | X | FATAL | X X X X X X X X X X SBUILD | X SCVTI | X X SCVTLU | X X X X X SCVTR | X SWRITE | X | DATE | X INDEX | X ISCOMP | X X X X X LEN | X SCOPY | X X X X TIME | X TRIM | X INDEX Auto-page, 5-2, 5-6 lay-out, 2-2, 3-2 page, 2-2 Close output stream, 5-1 page buffer, 5-3, 5-5 Common area, 7-1 to 7-2 page parameters, 3-2 source file, 1-1 to 1-2, Data item, 2-4 2-1 to 2-2, 6-1 separator, 2-4 Report description, 1-2, 2-1 to 2-2, 4-1 Error, 3-3 language, 1-1 to 1-2, fatal, 3-3 2-1 to 2-2, 2-4 message, 3-3 record, 2-4 warning, 3-3 Report driver subroutines, 1-1 to 1-2, 2-1, 4-1, 7-2 Field, 1-2, 2-1 to 2-2, 4-2 library, 6-1, 6-3 length, 2-2 to 2-3 Reports name, 1-2, 2-3 to 2-4 document list file, 1-2, 2-1, Field description data, 3-3 2-3, 3-2, 6-2 File name, 5-3 library, 1-2, 2-2, 3-2, extension, 3-1 to 3-2, 5-3 5-3 to 5-4, 6-2 Fix text, 2-2, 2-6 Size of the system, 7-1 Location, 2-4, 5-2 System subroutine, 7-1 absolute, 2-4, 3-2 parameter, 2-4 Text editor, 1-2, 2-1 to 2-2, relative, 2-4 2-4, 6-1 Open reports library, 5-3 Output stream, 4-2 open, 5-4 Overlay requirements, 7-1 to 7-2 Physical page, 2-5, 5-4 Picture, 2-3, 2-7 string, 2-7 Positionning absolute, 2-2 relative, 2-2 Print report, 4-2, 5-1 Record type code, 2-4 Relative data, 2-7, 3-2, 5-2 text, 2-7, 5-6 Report, 1-2, 2-2, 4-1 compiler, 1-1 to 1-2, 2-1, 3-1, 6-2