CDS554

Automated PCL Grid

 Last Revised: 09/27/23

This called routine can be used to print to a PCL compatible printer, the detail section of a sales order, invoice, statement, purchase order, transfer order, or any other document.  Using this routine will significantly reduce the code required to produce very clear and readable documents.

CDS554 will:

  1. automatically suppress columns that are all blank in each non-heading row,
  2. automatically determine the width of each column, expanding or reducing width based on document contents,
  3. shrink the point size of the text to fit within the column,
  4. automatically determine the height of each row, based on the number of lines of text printed in the row,
  5. automatically split the document over multiple pages if required.

CDS554 can:

  1. optionally print document name, document reference heading, document reference number, and overlay for logo, etc.
  2. have text span multiple columns,
  3. print using proportional or fixed-width characters,
  4. print using regular or bold weight font,
  5. align text to be left justified, centered, or right justified,
  6. keep rows together to prevent the total section from being split over multiple pages,
  7. print notepad text.

See also CDS254, CDS354, CDS454.

CDS554 is called 4 different ways.

Call Type Call Frequency Calling Arguments
Initialization one time CALL "CDS554::SETUP", S554$, COLS$
Cell Line once for each line of text in cell CALL "CDS554", S554$, COL {, TXT$, CELLOPTS$ }
Row once at the end of each row CALL "CDS554::ENDROW", S554$ {, ROWOPTS$ }
Print once at the end of all rows CALL "CDS554::PRINT", S554$, Y6$

Call CDS554 for each non-spanned cell, even if there is no text to be printed in order to print the cell grid lines.

If you are using CDS554 to print multiple sections within the same document, then after calling CDS554::PRINT, you must call CDS554::SETUP again to start the next section, even if the columns are the same as the previous section.

CDS554 Arguments
Call Type Argument Passed To/From Description
Initialization S554$ From Used to store parameters and data until printed.  Note: Do not CALL "CDS041" to obtain the template for CDS554 before calling CDS554 the first time.  The template is built by CDS554 dynamically during the initialization CALL.
COLS$ To Used to indicate the number of columns and horizontal alignment of each column. i.e., if COL$="LLCR" the grid will contain 4 columns, columns 1 and 2 left justified, column 3 centered, and column 4 right justified.
LLeft justify text in column
CCenter text in column
RRight justify text in column
Cell Line S554$ To Used to store parameters and data until printed
COL To Column number where text will be printed, first column is 1.
TXT$ To Line of text to be printed.  TXT$ can contain line feed characters ($0A$) to include multiple lines of text in the same cell.  You can also CALL CDS554 with the same COL multiple times in order to print each TXT$ on separate lines within the same cell.  See example below.  Trailing $0A$ are removed from TXT$.  TXT$ can contain any character except $01$.
CELLOPTS$ To Optional parameter that can contain in any order:
SnSpan n columns indicator.  "n" can be a 1, 2, or 3 digit number.  If COL=2 and CELLOPTS$ contains S3 then the text will span 3 columns (Columns 2, 3 and 4).  Note: you should not call CDS554 to print text in the spanned columns (COL=3 and COL=4).
LLeft justify text in cell (overriding column alignment in COLS$)
CCenter text in cell (overriding column alignment in COLS$)
RRight justify text in cell (overriding column alignment in COLS$)
HTreat cell like a heading row with 9 point bold text on a shaded background.  Only necessary when entire row is not a heading row.
VnPrint text n dots lower on the page than normal.  Useful when overriding the row height and text prints too high in cell.  A row that is 120 dots high that has two lines of text in the cell looks centered vertically with V43 included in CELLOPTS$.
FCDS554 prints all text using the Univers proportional font.  In some cases it is desirable to print with a fixed width font.  Include F in CELLOPTS$ to cause this cell to print using a fixed width font.
{NotepadFile,TextID}Indicates that the Notepad Text from NotepadFile with TextID should print in the cell below TXT$ if present.  Note: Include the {} characters in CELLOPTS$.  No error will be reported if the Notepad File or Text does not exist.  Only one notepad per cell is supported.
(color)Indicates that the entire cell contents should print in the color specified.  Include the parentheses and specify the color using a color name, such as "red", RGB values such as FFA500, or decimal values such as 255,64,32.  Refer to CDS254 for additional information about printing in color.
Row S554$ To Used to store parameters and data until printed
ROWOPTS$ To Optional row options parameter that can contain in any order:
HRow is a heading row.  Text will be printed 9 point bold on a shaded background.  The last heading row encountered, is automatically re-printed at the top of the grid on the next page.
BPrint text in 10 point bold font on a shaded background.
TPrint the current rows and all rows that follow together on the same page.  Typically set on the first total line so that all total rows appear on the same page.  Note that printing of a blank row, i.e., ROWOPTS$ contains "b", or discontinuing printing of heading row "D", will also signal the end of the Totals group.
Tn

Keep the current row and the n rows that follow, on the same page.  "n" can be a 1, 2, or 3 digit number.

Based on the total row height and the space left at the bottom of the page, CDS554 may split a multi-line row over multiple pages. To disable that feature, include "T1" in ROWOPTS$ which will start the row on the next page.

bPrint blank row, 30 dots high, with no text or cell borders.  It can be used to separate sections such as a notepad from the detail section of the document.  If the current row has any cell text to be printed, then the blank row will follow the text row.  If the current row has no text to print, then only the blank row will be printed.
PPrint blank row, similar to the lower case b option, with no text or cell borders.  The height of the blank row will be such that the next row will print at the bottom of the page.  This is typically done to cause a row containing notepad text to print at the bottom of the page.
DAfter the current row has been printed, discontinue printing of last heading row as first row on each page.  This option could be used when the main portion of the grid has been completed, but there are additional rows that only contain notepad text.  If the column headings used at the start of the grid do not apply to the notepad rows, and there are no additional non-notepad rows to follow, include D in ROWOPTS$ to disable printing the heading row on new pages that might be required for multi-page notepad text.
NStart a new page before printing this row.  Cannot be used on the same row with the T or Tn option.
hnThis option can be used to set the minimum row height.  "n" represents dots (300/inch) and can be a 1, 2, or 3 digit number.  By design, CDS554 will not print rows that do not include any text.  In order to print such a row use this hn row option.  A typical row contains 48 dots per line of text in the cell plus 10 dots of margin.  To create a row that is the same height as a row containing 1 line of text, include h58 in ROWOPTS$.  To create a row that is the same height as a row containing 2 lines of text, include h106 in ROWOPTS$.  This option can be used to set the row height larger to provide room for hand-written text on the document.  The row height option cannot be used with the b or P row options.
Print S554$ To
MINCOL[COL] Use to override the minimum column width in dots (300/inch) of any column or to disable column resizing.  Typically only needed when a column that is all blank should print as might be needed when the column is used for a hand-written value.  Set to -1 to disable column resizing as might be desired a price or amount column.
WIDTH Use to override the overall width of the grid.  Defaults to 2400 for portrait orientation, and 3150 for landscape.
BOTTOM Use to override the last row that can be printed on the page.  Defaults to 3150 for portrait orientation, and 2400 for landscape.
PAGE1ROW Set to the dot row of top line of the grid on page 1.  There are 300 dots per inch, with a 1/4" page margin, so a value of 450 will print 1 3/4 inches from the top of the page.
PAGE2ROW Use to override the dot row of the top line of the page number grid that prints at the top right of all pages except page 1.  Default value is 100.  When printing an overlay such as a logo on the top of each page, you may need to set PAGE2ROW to a higher value to insure the main grid does not overprint the overlay.
CONAME$ If non-blank CONAME$ will print centered using bold 14 point type at the top of each page.
DOCNAME$ If non-blank, DOCNAME$ will print right justified using bold 14 point at the top right of each page.  Use to print the document name such as SALES ORDER, INVOICE, PURCHASE ORDER, etc.
OVERLAY$ Optional overlay file name containing overlay file to be printed on each page.  The overlay file typically contains a company logo, name, address, etc. that typically prints at the top left of each page, although can print anywhere on the page, including as a watermark.
PAGENO$ Pass as "N" to disable printing page number on subsequent pages.
PAGE2REFHEAD$ Use to print a document reference number heading such as Sales Order#, Invoice#, Purchase Order#, etc. in a row above the page#.
PAGE2REFNO$ Use to print a document reference number to the right of the heading described above.
SIZE Pass as 1 for portrait, or 2 for landscape orientation when it is necessary to mix portrait and landscape pages on the same printer channel.  Leave as 0 when the entire document should print in the same orientation as when the printer was opened using CDS084.
NEWPAGE$ Pass as "Y" to cause CDS554 to perform a new page routine before printing page 1.  This includes the call to CDS094 and printing of the PAGE2REFHEAD$, PAGE2REFNO$, and Page number fields on page 1, that otherwise would only print on pages 2 and following.
S554$ From
LASTROW Set by CDS554 as the last dot row of the grid.  Useful when additional printing needs to be done below the grid.
S554$ N/A The following fields are reserved for use by CDS554 and should not be altered by the application.
ACTROW$[COLS]
CELLOPT$[COLS]
COLS
ROWS
LCR$[COLS]
ROWDATA$
Y6$ To Printer Control data from printer selection routine CDS084.
Example - Copy and paste to console mode to execute example
2700 TEST:
2710 BEGIN

2720 CALL "CDS041","CDS084",S084$,"YY"
2730 LET S084.MODE$="E",S084.NAME$="APDF"
2740 CALL "CDS084",ERR=9996,Y$,Y5$,U0,S084$,Y6,Y6$
2750 CALL "CDS094",Y6$; REM "New page
2760 CALL "CDS554::SETUP",S554$,"LLRRCR"; REM "Initialize 6 columns
2770 LET COL=COL+1; CALL "CDS554",S554$,COL,"Item#"
2780 LET COL=COL+1; CALL "CDS554",S554$,COL,"Description"
2790 LET COL=COL+1; CALL "CDS554",S554$,COL,"Quantity"
2800 LET COL=COL+1; CALL "CDS554",S554$,COL,"Price"
2810 LET COL=COL+1; CALL "CDS554",S554$,COL,"U"; REM "Example of a column with no data
2820 LET COL=COL+1; CALL "CDS554",S554$,COL,"Total"
2830 CALL "CDS554::ENDROW",S554$,"H"; REM "Heading row
 2840 FOR I=1 TO 8; REM "Print detail several times to demonstrate page 2 info
 2850 LET COL=0
2860 LET COL=COL+1; CALL "CDS554",S554$,COL,"12345"
2870 LET COL=COL+1; CALL "CDS554",S554$,COL,"Black USB Mouse"
2880 CALL "CDS554",S554$,COL,"Optical"; REM "Example of multi-line text using multiple CDS554 calls
 2890 LET COL=COL+1; CALL "CDS554",S554$,COL,"12"
2900 LET COL=COL+1; CALL "CDS554",S554$,COL,"10.00"
2910 LET COL=COL+1; CALL "CDS554",S554$,COL,""
2920 LET COL=COL+1; CALL "CDS554",S554$,COL,"120.00"
2930 CALL "CDS554::ENDROW",S554$
2940 LET COL=0
2950 LET COL=COL+1; CALL "CDS554",S554$,COL,"4744-ABX"
2960 LET COL=COL+1; CALL "CDS554",S554$,COL,"IBM Personal Computer"
2970 CALL "CDS554",S554$,COL,"Intel Core 2 Duo 3.5GHz Processor"
2980 LET COL=COL+1; CALL "CDS554",S554$,COL,"1"
2990 LET COL=COL+1; CALL "CDS554",S554$,COL,"500.00"
3000 LET COL=COL+1; CALL "CDS554",S554$,COL,""
3010 LET COL=COL+1; CALL "CDS554",S554$,COL,"500.00"
3020 CALL "CDS554::ENDROW",S554$
3030 CALL "CDS554",S554$,1,""
3040 CALL "CDS554",S554$,2,"Includes:"+$0A$+"2Gb memory"+$0A$+"300 Gb Disc Drive"+$0A$+"Wireless b/g/n","S4"; REM "Example of multi-line text using a single CALL to CDS554
3050 CALL "CDS554",S554$,6,""
3060 CALL "CDS554::ENDROW",S554$
3070 NEXT I
3080 CALL "CDS554",S554$,1,"Subtotal","S5R"; REM "Span 5 columns, right align text
3090 CALL "CDS554",S554$,6,"620.00"
3100 CALL "CDS554::ENDROW",S554$,"T"; REM "Keep the following lines together on the same page
3110 CALL "CDS554",S554$,1,"Shipping","S5R"
3120 CALL "CDS554",S554$,6,"30.00"
3130 CALL "CDS554::ENDROW",S554$
3140 CALL "CDS554",S554$,1,"7.75% Sales Tax","S5R"
3150 CALL "CDS554",S554$,6,"50.38"
3160 CALL "CDS554::ENDROW",S554$
3170 CALL "CDS554",S554$,1,"Total","S5R"
3180 CALL "CDS554",S554$,6,"700.38"
3190 CALL "CDS554::ENDROW",S554$,"B"; REM "Print total row bold
3200 LET S554.PAGE1ROW=600,S554.DOCNAME$="INVOICE"
3205 LET S554.PAGE2REFHEAD$="Invoice#",S554.PAGE2REFNO$="987654321"
3210 CALL "CDS554::PRINT",S554$,Y6$
3220 CALL "CDS094",Y6$,"E"; REM "Close printer
3230 PRINT S554.LASTROW

Click here to view output