CDS254

Print PCL Text, Line, Box, Overlay

 Last Revised: 01/06/25

This called routine can be used with PCL 5 compatible devices, typically laser or ink-jet printers, to print text, lines, and boxes.  Note that CDS254 does not work with PCL 6, nor with host-based printers, where the PC host is required for processing.

See example program CDX080 for sample code.

Printing Text

CALL "CDS254", Y6$, "T COL, ROW, WEIGHT, STYLE, POINT, PITCH, TYPEFACE, FILL, PATTERN", TEXT$

See Also:
CDS354 - Print 2 Column PCL Box
CDS454 - Print PCL Grid
CDS554 - Advanced PCL Grid

The string parameters following the T for text is optional, and only the fields necessary must be specified.

CDS254
Printing Text
COL The dot column where the text should be positioned. Dot columns are specified in 300 dot per inch, so @(10) would be the same as a COL of 300.  In addition to specifying an absolute column such as 300, a column relative to the current cursor position can be specified by inserting a + or - before the number as in +300.

If the COL is not specified, i.e., null, not zero, then the current cursor column will be used. A COL value of zero indicates the left most position.

You can also optionally specify a justification parameter L, R, or C following the COL value for Left, Right, or Centered justification of the text.  If not specified, then the text is left justified, i.e., it will print to the right of the COL specified as when using @().  For quantities and prices however, the R suffix may be used.

Note that this option currently only works for fixed spacing typefaces such as Courier, Line Printer, and Letter Gothic and Univers (a proportional typeface).  Note that additional proportional typefaces are supported if their font metrics record is in file CDSM80.  This file currently contains font metrics for typeface 4148 Univers at point sizes 8 through 14.  Other point sizes may be used, but the spacing may not be exact due to estimated character widths.  Please contact us to add font metrics for other typefaces or point sizes to the CDSM80 file.  This file is replaced during an Dynamo Tools upgrade, so don't add records yourself otherwise they will be lost after an upgrade.

Normally CDS254 will print text at the current font size or the size passed. However, CDS254 can also reduce the font size to insure the text fits within the space provided on the form.  You request this option by specifying the maximum dots the text may take following the L, R, or C character.

Note that the COL specified using the centering option varies depending on whether the maximum width parameter is provided.  When centering data without a width parameter as in CALL "CDS254",Y6$,"T1200C","Company Name", the 1200 refers to the center point, i.e., half of the text will be to the left, and the other half to the right.  When centering data within a fixed column width as in CALL "CDS254",Y6$,"T700C150","Center This" the 700 represents the left edge of the cell of 150 dots, not the center point.
ROW The dot row where printing will occur.  This typically refers to the line at the bottom of the characters, as opposed to the top. Like COL the ROW parameter may be preceded by a + or - for relative positioning.

If the ROW is not specified, i.e., null not zero, then the current cursor position will be used.  A ROW value of zero indicates the top most print position.
WEIGHT The weight of text using a range from -7 of Ultra Thin, to 0 for normal, to 3 for Bold, and 7 for Ultra Black.  Refer to Stroke Weight in a PCL reference for additional information.  Note that if the WEIGHT is not specified, then the current weight will be used.  Note this is a change from a previous version of CDS254 where the weight was always reset to 0 if not passed.
STYLE The style of type to use.  Principally used for italics, but can also be used for other styles supported by the particular printer or device.  The possible style values include: 
0Upright, solid (normal)
1Italic
4Condensed
5Condensed Italic
8Compressed or extra condensed
24Expanded
32Outline
64Inline
128Shadowed
160Outline Shadowed

If the STYLE is not specified, then 0 is assumed.
POINT This parameter is used only in proportionally spaced fonts such as Univers, Arial, Helvetica, etc. and typically may be any value from .10 to 576.  Normal type is usually within the range of 9 to 18 point. If not passed, the current point size will be used.

Note that for the internal bit-map line printer font of most HP printers, the POINT size should be set to 8.5 even though this is not a proportionally spaced font.
PITCH This parameter is used for fixed space fonts such as Courier and Letter Gothic.  It indicates the characters per inch. It should also be set to 16.67 when using the internal line printer font.  If not passed, the current pitch will be used.  The PITCH should not be specified for proportional spaced fonts.
TYPEFACE This parameter indicates the typeface family to use.  You can determine this parameters value by printing a PCL test font page on HP Laser printers, or referring to the HP technical documentation manuals.  Some of the popular values are listed below.
0Line printer
4099Courier
4101CG Times
4102Letter Gothic
4113CG Omega
4116Coronet
4140Clarendon Condensed
4148Univers
4168Antique Olive
4197Garamond
4297Marigold
4362Albertus
16602Arial
16901Times New Roman

If the TYPEFACE value is not passed, the current typeface is used.
FILL Text is typically printed in solid black. The FILL option can be used to lighten the text color as might be desired when printing text that overlays other text in the same area. FILL can range from 1 to 99. A FILL value of 20 produces lightly shaded text suitable for use as a watermark. The FILL option is available on versions of CDS254 dated on or after 01/06/25. Example.
PATTERN The PATTERN describes how the FILL is rendered. The default value of 2 is often sufficient. PATTERN can have a value from 0 to 4. See the PATTERN options in the boxes section below for more details.
TEXT$ The text parameter is the text to be printed.  You may optionally include a leading and/or trailing +$0D0A$ to cause the cursor to be positioned automatically down to the next line.  This is typically done on the last text field of each line so that the ROW value need not be passed to CDS254.  This trailing $0D0A$ will be taken into consideration for right and center justification.
Printing Vertical Lines

CALL "CDS254",Y6$,"V COL,ROW,ROW2,WIDTH"

Printing Vertical Lines
COL Dot column for upper left corner of line as described above

Note that the COL and ROW values are not optional for lines or boxes
ROW Dot row for upper left corner of line as described above

Note that the COL and ROW values are not optional for lines or boxes
ROW2 Dot row for lower left corner of line. If specified with a + prefix, then this indicates the relative length of the line in dots, as opposed to an absolute row number when the line should end.
WIDTH The width of the line in dots.  If not specified, one dot row will be used. Note that the width of the line extends to the right of the COL and ROW parameters specified.
Printing Horizontal Lines

CALL "CDS254",Y6$,"H COL,ROW,COL2,WIDTH"

Same as for vertical lines except that COL2 indicates either the column where the line ends, or the length of the line when using the + prefix.  The line extends below the COL and ROW specified for the dots specified in the optional WIDTH value.

Printing Boxes

CALL "CDS254","B COL,ROW,COL2,ROW2,WIDTH,FILL,PATTERN"

Printing Boxes
COL Indicates the dot column for the upper left corner of the box.  This value is required and the + or - prefix may not be used.
ROW Indicates the dot row for the upper left corner of the box.  This value is required and the + or - prefix may not be used.
COL2 Indicates the dot column for the lower right corner of the box.  An absolute number for a specific dot column may be used, or if preceded by + then the COL2 value represents the width of the box in dots.
ROW2 Indicates the dot row for the lower right corner of the box.  An absolute number for a specific dot row may be used, or if preceded by + then the ROW2 value represents the height of the box in dots.
WIDTH The width of the lines that make up the box.  Note that the lines of the box always extend in toward the center of the box from all four sides.  If not specified, a single dot width is assumed.
FILL An optional parameter used to fill the box with some pattern.  The value of the fill parameter depends upon the PATTERN value.  If the PATTERN value is 2 then the FILL value represents the percentage of shading from 1 to 100%.

Note that there are actually only 8 shading patterns supported for most laser printers.  Usually only the lightest shading is appropriate when printing text in the same box.

  • 1-2
  • 3-10
  • 11-20
  • 21-35
  • 36-55
  • 56-80
  • 81-99
  • 100

When the PATTERN value is 3 then cross hatch filling is done based on the value of FILL.

There are 6 patterns typically available.

1horizontal lines
2vertical lines
3positive slope lines like a slash /
4negative slope lines like a backslash \
5both horizontal and vertical lines
6both positive and negative slope lines
PATTERN The fill pattern to use. 
0solid black fill
1erase (white) fill
2shaded fill (requires FILL value above) Default value if not passed or passed as null.
3cross-hatch fill (requires FILL value above)
4last fill pattern specified

Note that when printing lines and boxes, the cursor position does not change.

Saving the Cursor Position

CALL "CDS254",Y6$,"S"

This call may be required before printing text in one particular location on the page, when after printing you desire the cursor back in the same position that it was previously.

Restoring the Cursor Position

CALL "CDS254",Y6$,"R"

This restores the cursor position saved previously.

Printing an Overlay

CALL "CDS254",Y6$,"O",OVERLAYFILENAME$

An overlay is a document that prints on each page.  This command is used to define an overlay.  The overlay will be automatically cancelled the next time the printer is reset, typically at the start and end of each print job.  You may also call CDS254 with no overlay file name to cancel the overlay.  Note that the overlay begins printing on the current page and since CDS084 will print an overlay named XX/faxcover.prn on the fax coverpage, you should not call CDS254 to print an overlay until after the first call to CDS094 in the NEWPAGE routine of the application.  Otherwise both overlays will print on the fax coverpage.

The easiest way to create an overlay file is to design your overlay using any word processor or design software, print it to paper to insure it looks the way you want, then choose the option to print the document to a file.  Then you need to do some manual file manipulation.  There is a program still under development named CV200 that will edit the output file and strip out the PCL commands that reset the printer, change orientation, and other paper source related commands.  If you do not do this step, then the overlay will print on its own page and not 'overlay' the other printing.

CALL "CDS254",Y6$,"Ox",FILENAME$

The x is passed to CDS095 as the parameter indicating whether or not a message should be displayed if the file cannot be opened.  Defaults to "N" if not passed.  FILENAME$ is the name of the overlay file.  Pass FILENAME$ as null to cancel the overlay prior to the end of the print job.  You may change the overlay file by calling CDS254 again without the need to call it to cancel the initial overlay.

Example:

IF Y6.P=1 THEN CALL "CDS254",Y6$,"O","invoice.prn"

Printing in Color

CALL "CDS254",Y6$,"Ccolorcode"

CDS254 is compatible with most PCL 5c compatible color printers.  Call CDS254 with the C command to change the color of subsequent operations.

Mode Calling Format Color code Example
Simple Color Mode CALL "CDS254", Y6$, "C[color]"
Valid [color] options
Pass either the number or name
0 black
1 red
2 green
3 yellow
4 blue
5 magenta
6 cyan
7 white (not supported on all printers)
CALL "CDS254", Y6$, "Cblack"

 

CALL "CDS254", Y6$, "Cred"

 

CALL "CDS254", Y6$, "C0"

 

CALL "CDS254", Y6$, "C1"

 

 
RGB colors in hexadecimal CALL "CDS254", Y6$, "C[RRGGBB]" Replace [RRGGBB] with hexadecimal RGB value CALL "CDS254", Y6$, "CFFA500"
RGB colors in decimal CALL "CDS254", Y6$, "C[rrr,ggg,bbb]" Replace [rrr,ggg,bbb] with decimal RGB values CALL "CDS254", Y6$, "C255,64,32"
Color Example
7000 TEST:
7010 BEGIN
7020 CALL "CDS084",ERR=9996,Y$,Y5$,U0,S084$,Y6,Y6$
7025 CALL "CDS254",Y6$,"T0,0,0,0,0,12,4099"
7030 LET ABC$="ABCDEFGHIJKLMNOPQRSTUVWXYZ"
7040 CALL "CDS254",Y6$,"Cblack"
7050 PRINT (Y6.CH)ABC$
7060 CALL "CDS254",Y6$,"Cred"
7070 PRINT (Y6.CH)ABC$
7080 CALL "CDS254",Y6$,"Cgreen"
7090 PRINT (Y6.CH)ABC$
7100 CALL "CDS254",Y6$,"Cyellow"
7105 PRINT (Y6.CH)ABC$
7110 CALL "CDS254",Y6$,"Cblue"
7120 PRINT (Y6.CH)ABC$
7130 CALL "CDS254",Y6$,"Cmagenta"
7140 PRINT (Y6.CH)ABC$
7150 CALL "CDS254",Y6$,"Ccyan"
7160 PRINT (Y6.CH)ABC$
7170 LET COL=0,ROW=400,CLR$="FFA500"; GOSUB TESTBOX
7180 LET COL=300,ROW=400,CLR$="FFFF99"; GOSUB TESTBOX

7190 LET COL=600,ROW=400,CLR$="FF3300"; GOSUB TESTBOX
7200 LET COL=900,ROW=400,CLR$="00CC33"; GOSUB TESTBOX
7210 LET COL=1200,ROW=400,CLR$="99FF99"; GOSUB TESTBOX
7215 LET COL=1500,ROW=400,CLR$="CCFF99"; GOSUB TESTBOX
7220 LET COL=1800,ROW=400,CLR$="6699FF"; GOSUB TESTBOX
7230 LET COL=2100,ROW=400,CLR$="00CCFF"; GOSUB TESTBOX
7290 CALL "CDS094",Y6$,"E"
7300 GOTO 9996


7900 TESTBOX:
7910 CALL "CDS254",Y6$,"C"+CLR$
7920 CALL "CDS254",Y6$,"B"+STR(COL)+","+STR(ROW)+","+STR(COL+300)+","+STR(ROW+300)+",2,100,0"
7930 CALL "CDS254",Y6$,"Cblack"
7940 CALL "CDS254",Y6$,"T"+STR(COL)+"C300,"+STR(ROW+175)+",3,0,14,,4148",CLR$
7950 RETURN

Click to view result
Printing Notepad Text

CDS254 can be used to print Notepad (Window) Text that includes attributes including bold text, underlined text, and reverse text.  Reverse text is printed in an italics font for printers that have the italic font setting specified in Printer Type Maintenance (PFM).

CALL "CDS254",Y6$,"N COL, ROW, COLSIZE, POINT, PITCH, TYPEFACE","NotepadFileChan,TextID{,FROMLINE,TOLINE}"

Y6$ Printer control data from CDS084
N "N" indicates Notepad Text command
COL Dot Column of first line of text
ROW Dot Row of first row of text
COLSIZE Optional dot columns that notepad text can be printed in
POINT Optional point size (used for proportional fonts only).  If not specified CDS254 will use 10 point.  If the text will not fit in the space available, then the point size will be reduced.
PITCH Optional pitch (characters per inch - used for fixed width fonts only).  If not specified CDS254 will use 10 cpi.  If the text will not fit in the space available, then the pitch will be increased.
TYPEFACE Optional typeface.  If not specified, notepad text that has no line drawing characters will be printed in typeface 4148 (Univers); notepad text that contains any line drawing characters will be printed in typeface 4099 (Courier).
NotepadFileChan Required file name or channel number of notepad text file already open.
TextID Required TextID of the notepad text
FROMLINE Optional starting line# within the notepad text to begin printing at.  If not provided, the entire notepad will be printed, and must fit on the page at the ROW indicated.  If provided, this is the starting line# of the notepad text
TOLINE Optional ending line# within the notepad text.  This would be the last line# printed.  Will print to end of notepad if not provided.

CDS254 will not report an error if unable to OPEN the NotepadFile nor if the TextID is not on file.

Notepad Text Example

Notepad Text with TextID of "PROMOT" from Notepad Text File DCCW15 will print at dot column 0, dot row 100.
4600 TEST:
4610 BEGIN
4620 CALL "CDS091",Y$
4630 CALL "CDS041","CDS084",S084$
4640 LET S084.RPTWIDTH$="N"
4650 CALL "CDS084",Y$,Y5$,U0,S084$,Y6,Y6$
4680 CALL "CDS254",Y6$,"N0,100","DCCW15,PROMOT"
4690 CALL "CDS094",Y6$,"E"