ACE/4GL report control in AWK

Here is a collection of AWK functions that provide some of the report control features found in 4GL and ACE. They are based on C routines that were originally written for use in the old Informix 3.30. This isn't particularly amazing code, but it has come in handy on occasion. If you run into any problems or bugs, I'd appreciate hearing about them. Happy paginating, Walt. #!/bin/sh # # This is a shell archive. To extract its contents, # execute this file with /bin/sh to create the file(s): # # rptfuncs.awk rptfuncs.doc rptsample1.awk rptsample2.awk # # This shell archive created: Thu Feb 17 13:34:22 EST 1994 # echo "Extracting file rptfuncs.awk" sed -e 's/^X//' <<\\SHAR_EOF > rptfuncs.awk X# rptfuncs.awk X# X# X# SCCS ID: @(#) rptfuncs.awk 1.1 2/17/94 13:08:27 X# X# (c) Copyright 1994 by Walt Hultgren. All rights reserved. X# X# X# Functions: X# X# start_report initialize report control & start report X# need account for lines about to be printed X# skip_to_top_of_page finish current page & move to top of next page X# finish_page finish current page & stop at bottom X# finish_report finish report by finishing current page if needed X# X# X X Xfunction start_report( arg_prtppg, arg_linppg, arg_hdrflg ) { X X rp_prtppg = arg_prtppg # printed lines/page including header X rp_linppg = arg_linppg # total lines/page for NL's, 0 for FFD's X rp_lincnt = 0 # current line count (lines printed) X rp_pageno = 1 # current page number X rp_hdrflg = 1 # ==> need header before next report line X rp_status = 0 # status return X X "date +%D" | getline rp_date # current date MM/DD/YY X "date +%T" | getline rp_time # current time HH:MM:SS X X if ( arg_hdrflg != 0 ) skip_to_top_of_page() X X return rp_status X } X X Xfunction need( arg_lines ) { X X if ( arg_lines > 0 ) X { X if ( rp_hdrflg == 1 || rp_lincnt + arg_lines > rp_prtppg ) X { X if ( skip_to_top_of_page() ) return rp_status X } X X rp_lincnt = rp_lincnt + arg_lines X } X X rp_status = 0 X X return rp_lincnt X } X X Xfunction skip_to_top_of_page() { X X if ( finish_page() ) return rp_status X X rp_status = page_header( rp_pageno ) X X if ( rp_status < 0 ) return rp_status X X rp_lincnt = rp_status X rp_hdrflg = 0 X X rp_status = 0 X X return rp_status X X } X X Xfunction finish_page() { X X if ( rp_lincnt > 0 ) X { X while ( rp_lincnt < rp_prtppg ) X { X print "" X ++rp_lincnt X } X X rp_status = page_trailer( rp_pageno ) X X if ( rp_status < 0 ) return rp_status X X rp_lincnt = rp_lincnt + rp_status X X if ( rp_linppg > 0 ) X { X while ( rp_lincnt < rp_linppg ) X { X print "" X ++rp_lincnt X } X } X else X { X printf( "%c", 12 ) X } X X rp_pageno = rp_pageno + 1 X X rp_lincnt = 0 X rp_hdrflg = 1 X X } X X rp_status = 0 X X return rp_status X X } X X Xfunction finish_report() { X X return finish_page() X X } SHAR_EOF if [ `wc -c < rptfuncs.awk` -ne 2497 ] then echo "Lengths do not match -- Bad Copy of rptfuncs.awk" fi echo "Extracting file rptfuncs.doc" sed -e 's/^X//' <<\\SHAR_EOF > rptfuncs.doc Xrptfuncs.doc X X XThis file explains the use of the AWK functions found in "rptfuncs.awk", which Xsimulate some of the report control features of the Informix 4GL and ACE report Xfacilities. X XThese functions are based on C routines that were originally written to provide Xprograms containing Informix 3.30 ALL II calls with the same report control Xfunctionality found in ACE. They have since been ported to Informix-4GL as Xwell as to AWK. X XThis code is provided without any warranties, but I would like to hear of any Xbugs or problems you run into. Please send such reports to walt@rmy.emory.edu. X X XUSING THE FUNCTIONS X XThese functions perform only line counting and automatic pagination. They do Xnot attempt to inspect the data being printed and provide control breaks, Xgroup processing or other report generation features. X XEach function is named similar to its 4GL counterpart. The available functions Xare: X X start_report initialize report control & optionally print header X need account for lines about to be printed X skip_to_top_of_page finish current page & move to top of next page X finish_page finish current page & stop at bottom X finish_report finish report by finishing current page if needed X XTo use the report functions, you must supply the main body of the AWK report, Xplus two functions: page_header() and page_trailer(). X XTo initialize the report control parameters, call start_report() before any Xreport output is generated. This is often done in a BEGIN{} section of the XAWK program. X XAs you are about to print each group of one or more report lines, call the Xfunction need() with the number of lines about to be printed. This must be Xdone for all output lines, even if they are printed one at a time. If you want Xto keep a block of lines together on the same page, call need() with the total Xnumber of lines in the block before you print any of them as you would in 4GL Xor ACE. X XWhen all report output has been generated, call finish_report() to complete the Xlast page. This is usually done in an END{} section. X X XFUNCTIONS YOU SUPPLY X XYou must supply two report functions in addition to the other AWK code you Xwrite to generate the body of the report. X XThe page_header() function is called by the report functions to print a page Xheader whenever the report moves to the top of a new page. The page_trailer() Xfunction is called to print a page trailer at the bottom of each page. X XThese functions should not call need() prior to printing header or footer Xlines. Each function should return the number of lines it printed. X XNeither function has to generate any output, but both must be present. If Xeither of these functions does not print anything, it should return a value Xof (0) to indicate that no lines were printed. X XHeaders on different pages do not have to contain the same number of lines. XThis is also true for trailers. X XEach function is called with a single argument, which is the number of the Xcurrent page. That is, the functions are called by "page_header(pageno)" and X"page_trailer(pageno)".@@N