XCALL HP

Please note: Since you too are a software developer, you will appreciate the significant effort that has gone into this product and our proprietary interest in it. Writing software is how we make a living.

It is not our intention to limit your distribution to others of ".DBR" programs that encorporate XCALL HP.

We did not have a Philadelphia lawyer draw up these terms, so please bear the spirit of the following in mind.

You are granted licence to utilize XCALL HP's source code in manners you see fit including the provision of compiled and linked programs to your company's customers.

In order to protect our interests, you are not granted licence to allow the source code or object code based on it to be made available to others outside your company.

Introduction

XCALL HP is a flexible method of controlling the HP LaserJet Series II and Series III in DBL programs. It gives you the ability to:

• Download fonts

• Manipulate font characteristics

• Address the page

• Draw lines and rectangles

• Shade areas in different densities

• Display Raster Graphics

• Display Text

And what's best of all?- It does all this in a simple to use, intuitive manner consistent with good programming practice. It uses the DBL Synergy style approach of functions and qualifiers (although it does not use Synergy).

Although DISPLAY statements and Synergy Xcall's typically output to the screen while XCALL HP typically outputs to the Laser, note the similarities in the following:

DISPLAY (ch, $scr_pos(5,1), 'This is normal',

& $scr_att(bold),

& $scr_pos(20,1),'This is bold')

XCALL W_DISP (id, wd_pos,5,1, 'This is normal',

& wd_attr,attr_set+attr_bold,

& wd_pos,20,1, 'This is bold')

XCALL HP (ch, hpPOS,5,1, 0,'This is normal',

& hpFONT,hpBOLD,

& hpPOS,20,1, 0,'This is bold')

The parameters you specify in xcall hp consist of functions, most of which are followed by one or more qualifiers.

The hpPOS function, for example, positions the cursor. (Did you know the LaserJet had a cursor?) It takes two qualifiers which are row and column.

For XCALL HP support, call (416) 783-9826

Thank you for your interest in XCALL HP
We hope it proves to be of good value to you.
-Alan Cohen, Computer Advocacy Inc

A Black Box

Before we knew the term object oriented programming, we described our design as an independent subroutine. The idea was to create a black box (with inputs and outputs) that could be "plugged in" to other code to do a job. The Black Box has grown with the proviso "Thou shalt not break other code."

You have the source. Instances where you're invited to make changes are indicated in the documentation. The program structure is explained in the documentation and the code itself. We suggest that you well document any changes you make. It might also be a good idea for you to advise us of the nature of your changes.

Feedback

Please comment on how you find working with XCALL HP's code and its documentation. Regarding the documentation in particular, we've done our best to explain things. (Still, when you've spent so much time at the nitty-gritty level, there's the danger of losing sight of the forest for the trees.) Working with a Page Printer is new for many people. Perhaps there are some concepts we haven't sufficiently described.

A Note on Graphics

The design considerations for graphics issues faced the fact that there many graphics packages, paint packages and scanning packages on the market. More specifically, there are many different file formats for graphics files.

For XCALL HP to operate efficiently, stand-alone programs had to be written to convert these files into a single file format that can be sent to the Laser with a minimum amount of processing overhead at execution time.

We've written two such programs. We'd like to know if you need more. BIT2HP.DBL and TIFF2HP.DBL are described in the Distribution contents section of this document. There are further notes in those files themselves.

If you have a hard copy graphic (a logo for example) for which you need a raster graphics file to be created, Computer Advocacy Inc can offer that service to you.

Table of Contents

Distribution contents

The following files are included on the XCALL HP distribution diskette

XCALL HP and XCALL HPSTRING

Addressing the Cursor

Both the screen and laser have an addressable cursor.

On the screen a row is a row. The number of rows on the screen doesn't change nor does the vertical size of a row.

On the laser, rows change. For example, with a standard font which prints 6 lines to the vertical inch, the 12th row would be at the 2 inch point. If you then switched to a very large font that only printed at 4 lines to the inch, and then did the very same cursor position to the 12th row, you would be placed at the 3 inch point!

XCALL HP has absolute cursor addressing using hpPOS and relative cursor addressing using hpMOVE.

As we've just discussed, however, even the "absolute" cursor positioning isn't very absolute insomuch as it depends on the current horizontal spacing (CPI) and vertical spacing (LPI) in effect.

To handle this, XCALL HP has two units of measures. (You change from one unit of measure to the other using the function hpDOTS.)

The default unit of measure is rows & columns (or lines & spaces). With this measurement, reference points change as CPI and LPI changes.

An alternative unit of measure is "dots". The HP Laser prints at 300 dots to the inch. Using "dots" as the unit of measure allows you to address the cursor to a specific point regardless of any CPI or LPI settings.

OUTPUT destination

In general, HP and HPSTRING differ only by their output destination.

XCALL HP sends its output to a channel. (It does not open a channel.) The channel number is the first parameter in the xcall.

XCALL HPSTRING appends its output onto the end of a string. The string is the first parameter in the xcall. Thus, you can use it to build strings.

All examples of the form:XCALL HP (ch, ...) could be written as:XCALL HPSTRING (variable, ...)

The exception is the situation where XCALL HPSTRING is instructed to output an entire file (a raster graphics for example). In such a case, it only appends the file name not the file's contents to the string.

How XCALL HP works

XCALL HP accepts, as parameters, a channel and up to 98 more parameters.

If a parameter is zero, the next parameter is expected to be an alpha string and is output as is.

If a parameter is greater than zero and less than 32, the corresponding ASCII value is output. For example, specifying 13,10 as two parameters would cause a carriage return and linefeed to be output.

If a parameter is greater than or equal to 32, the parameter is assumed to be a function as defined in HPSUB.DEF

Some of these functions require qualifiers. For example, hpPOS expects that the next two parameters will be a row and column.

XCALL APPEND

When XCALL HPSTRING is appending its output to a string rather than outputting to a channel (see Output destination above), it uses XCALL APPEND to do the appending.

DBL VERSIONS

Minimum DBL Version 4.30 is required.

VMS users should be aware of RMS's record oriented nature. We are not VMS users ourselves but we've been told that you must be careful here. It is your code, not XCALL HP itself, that actually opens the output channel that XCALL HP uses. If the output file is not opened as a "print file" or as a "stream file", you'll get gratuitous <cr><lf>'s all over the place.

COMPILE AND LINK CONSIDERATIONS

HP.SUB is compiled in a quite normal fashion. Since it contains:
.include def:hpsub.def
you must have the logical def set to the directory where hpsub.def is found.

The same is true for HPSTRING.SUB. The file HPSTRING.SUB is very tiny, consisting of only a couple of lines. An additional consideration is that one of those lines is:
.include hp.sub
Since no logical is supplied for this include, you must either edit this file to supply one of your own, or insure that the compilation takes place at a time when hp.sub is in the current directory.

The bulk of the file def:hpsub.def consists of .define statements. All of the .defines begin with the letters hp. This file also contains the small common area.

If you are linking XCALL HP into a bound program, be aware of the issues regarding bound programs and common areas as discussed in your DBL System Reference Guide.

COMMON AREA

Your programs must
.include hpsub.def
for its definitions and common area. HPSUB.DEF includes a small COMMON area which it uses to remember various settings. Common area variables all begin with the letters "cmhp".

In general, the common area is only of any use to XCALL HP itself. It is used so the routine can retain certain settings between xcall's. There are two notable exceptions that relate to error handling:

ERROR HANDLING

In most cases, when XCALL HP detects some sort of error, there is little sense in continuing to process: the error is described in a fashion analogous to a standard DBL error and the routine STOPs.

If the common area cmhpTRAP is set to $true, there are a small number of error conditions that the routine will detect without completely stopping. If such an error is detected:

1. The value of cmhpERNUM is set to one of the following:

• 1 Raster graphics file not found

• 2 Soft font file not found

• 3 Invalid resolution value given for a raster graphic

• 4 Attempt made to download a soft font with an invalid switch indicating that the soft font is to be made "permanent" or "temporary"

2. There is no further processing of any subsequent parameters in the xcall. In other words, as soon as the error is detected, the routine returns (having set the value in cmhpERNUM). cmhpERNUM is cleared at the start of each xcall. cmhpTRAP is not.

Example:

cmhpTRAP=$true

ASK, display (1, 'What font do you want: ')

reads (1,FILE)

xcall hp (ch, hpLOAD,FILE,1,hpMAKEperm)

if (cmhpERNUM.eq.2)

begin

writes (1,'Font file not found!')

goto ASK

end

cmhpTRAP=

REFERENCE

The bulk of this document, the Reference section, describes each of the available functions. The structure of each section is:

Function

Description

Notes

See also

Example

The functions are listed in alphabetical order. Generally, each function description begins on a new page.

There is a section entitled "MACROS" which is not a function but is a discussion of the nature of LaserJet macros and the various hpMACRO functions which follow.

List of functions

0 displays alpha variable or literal

hpAREA defines row & col (vertical & horizontal) area

hpBOX draws a rectangle using hpAREA's dimensions

hpDEBUG tells laser to display codes (not execute them)

hpDOTS defines unit of measurement (row/col vs dots)

hpFILL shades an area defined by hpAREA

hpFLUSH sends <esc>E to flush page and do a soft reset

hpFONT sets font characteristics

hpFONT_DELETE deletes soft fonts from Laser memory

hpGRAPHIC prints a raster graphics file

hpHLINE draws a horizontal line

hpHTAB positions cursor horizontally

hpLM sets the left margin

hpLOAD downloads a soft font

hpLPI sets number of lines per inch

(MACROS) a discussion of the 8 macro functions which follow

hpMACROauto enable a macro for automatic overlay

hpMACROcall call a macro

hpMACROdel delete a macro

hpMACROdisable disable a macro from automatic overlay

hpMACROexecute execute a macro

hpMACROperm end a macro definition and make it permanent

hpMACROstart start a macro definition

hpMACROtemp end a macro definition and make it temporary

hpMANUAL sets paper location to be manual feed

hpMOVE positions cursor (relative)

hpPOS positions cursor (absolute)

hpPOP pops cursor position off the stack

hpPUSH pushes cursor position on the stack

hpSTATIONERY defines paper size

hpTHICK set horizontal and/or vertical line draw thickness

hpVLINE draws a vertical line

hpVTAB positions cursor vertically

hpUNDER turns on underlining

hpUNDER_OFF turns off underlining

0, alpha

Description: Displays alpha (variable or literal) at the current position. The statements:

xcall hp (ch,0,alpha)

display (ch,alpha)

are equivalent. Notes: We really didn't want to force the need for the '0', but, unfortunately, DBL subroutines have no way of properly telling the type of variable (A,D,F) being passed in. When XCALL HP sees function "0", it knows that the next parameter is an alpha string.

hpAREA, height, width

Description: Defines vertical and horizontal dimensions for subsequent use by hpBOX or hpFILL functions. Height and width are interpreted according to the current unit of measure. (Unit of measure is set with hpDOTS.) See also: hpBOX, hpFILL, hpDOTS

Example: Assuming unit of measure is dots, this code position the cursor at row 1" col 2". An area 1.5" high and 1" wide is declared and the outline of a box is drawn there.

xcall hp (ch,hpPOS,300,600, ;position cursor.

& hpAREA,450,300, ;define area.

& hpBOX) ;draw a box around it.

Assuming unit of measure is row & column, and that we are at 6 lines to the inch and 10 characters per inch, this next piece of code does the same thing.

xcall hp (ch,hpPOS,6,20, ;position cursor.

& hpAREA,9,10, ;define area.

& hpBOX) ;draw a box around it.

hpBOX

Description: Draws a box starting at the current cursor position using height and width provided by last hpAREA. The thickness of the horizontal and vertical portions of the box are one dot by default. This thickness can be changed. (see hpTHICK) Notes: Drawing a box does not change the cursor position. See also: hpAREA, hpFILL, hpTHICK

Example:

xcall hp (ch,hpPOS,12,50, ;position cursor.

& hpAREA,9,10, ;define area.

& hpBOX, ;draw a box around it.

& hpPOS,13,51, ;position just inside box

& 0,'Hello') ;and display 'hello' there

Assuming 10CPI and 6LPI, the cursor is positioned 2 inches down (because 2" is 12lines divided by 6LPI) and 5 inches across (because 5" is 50columns divided by 10CPI) on the page. There, a box is drawn which is 1.5 inches high (9/6) and 1 inch wide (10/10).

hpDEBUG, $true | $false

Description: The function hpDEBUG,$true sends an escape sequence which instructs the laser to turn on end-of-line wrap and to display subsequent escape sequences rather than executing them. The function hpDEBUG,$false sends an escape sequence to resume normal execution of escape sequences and to disable line wrap.

Example:

myfont = so_and_so

xcall hp (ch,0,'Sequence sent with "myfont" is',13,10,10,

& hpDEBUG,1,

& hpFONT,myfont,

& hpDEBUG,0)

hpDOTS, $true | $false

Description: The function hpDOTS,$true informs the system that all subsequent measurements are to done in dots. The HP LaserJet prints 300 dots to the inch. hpDOTS,$false informs the system that all subsequent measurements are done according to the horizontal spacing (CPI) and the vertical spacing (LPI) in effect.

Notes: The value ($true or $false) is stored in HP's common area as variable cmhpDOTS. This function does not cause any output to the printer. It only changes the value in the common area. The initial setting for this value is $false. IE: cursor positioning, line drawing and areas are done relative to the current CPI and LPI. You should establish, for your applications, a "norm" for common variables such as hpDOTS. When code specifically deviates from the norm, you should remember to put it back! This is analogous to remembering to turn off reverse video on your screen display.

Example:

xcall hp (ch,hpDOTS,$false, ;measure by row/col

& hpPOS,6,10, ;position cursor.

& 0,'* Line6 Column10', ;

& hpDOTS,$true, ;measure by dots

& hpPOS,300,600, ;position cursor.

& 0,'* Line 1" Column 2" ');

hpFILL, percentage

Description: Shades an area starting at the current cursor position using height and width provided by last hpAREA. The darkness of the shading is given by percentage where percentage may range up to 100. A percentage of 100 would be totally black.

Notes: Upon completion, the cursor position is unchanged.

See also: hpAREA, hpBOX

Example:

xcall hp (ch,hpPOS,12,50, ;position cursor.

& hpAREA,9,10, ;define area.

& hpFILL,20, ;shade inside of box.

& hpPOS,13,51, ;position just inside box

& 0,'Shaded') ;and display text there

Assuming 10CPI and 6LPI, the cursor is positioned 2 inches down and 5 inches across the page. There, an area defined as 1.5 inches high and 1 inch wide is shaded. The word "Shaded" appears in the shaded area. (With only 20% shading, the word "Shaded" is quite readable.)

hpFLUSH

Description: Sends the escape sequence <esc>E which causes any existing pages to be printed, resets the printer to default conditions and deletes any temporary fonts and macros. Notes: This is not the same as a formfeed which always ejects a page. If there is nothing in the laser to print, there will be no forms eject. Permanent soft fonts and permanent macros are untouched. Temporary soft fonts and temporary macros are deleted. "Hewlett-Packard strongly recommends the use of the <esc>E command at the beginning and end of each job."

Example:

xcall hp (ch,0,'The end',

& hpFLUSH)

close ch

hpFONT, description

Description: Selects one or more attributes which describe a font. Attributes selected represent a change from the existing LaserJet's internally maintained attributes list.

Notes: The description parameter is a single D18 number. It may be specified by adding together pieces in the xcall itself as in:

xcall hp (ch, hpFONT, hp10CPI+hpBOLD)

You may find it more convenient to pre-define your own variables to contain these summations as in the example below. The variables you so define should be declared in your data division as D18. See also the Tips & Techniques section. The following is a re-print from the HP LaserJet II technical manual: The printer maintains a table which contains the values of all of the currently specified characteristics. Whenever the printer receives an escape sequence specifying a font characteristic, the printer records that characteristic in the table. The printer selects a font based on a prioritization of the characteristics in the table. The priority of the characteristics is shown in the following list:

Priority of Characteristics
(highest) Orientation
Symbol Set
Spacing
Pitch
Height
Style
Stroke
Weight
Typeface (lowest)

The allowable values are shown in the following table. You may make additions or changes in HPSUB.DEF to those characteristics marked [*]

---------------------------------------------------------

CHARACTERISTIC CHOOSE 0 or 1 of

---------------------------------------------------------

Orientation hpPORT, hpLAND portrait or landscape

[*]Symbol Set hpMATH7 0A The names here are arbitrary

hpTAX 0B (such as "hpMATH7") but their

hpDANISH 0D associated codes are the ones

hpUK 1E supplied by the font supplier.

hpFRENCH 0F

hpGERMAN 0G You may make additions or changes

hpITALIAN 0I to these symbol sets by editing

hpECMA94 0N HPSUB.DEF Instructions for doing

hpMATH8A 0Q so are given in HPSUB.DEF

hpMATH8B 1Q

hpPCLINE 4Q

hpECMA7 10Q

hpECMA8 11Q

hpSWEDISH 0S

hpSPANISH 1S

hpASCII 0U

hpLEGAL 1U

hpROMAN8 8U

hpPC8 10U

hpPC8DN 11U

hpPC850 12U

hpPIA 15U

Spacing hpPRO, hpFIX proportional or fixed pitch

[*]Pitch characters to the inch. CPI is used

hp5CPI hp9CPI to display fixed spaced characters

hp6CPI hp10CPI (but not proportional characters).

hp7CPI hp12CPI Regardless, it affects all subsequent

hp8CPI (horizontal) cursor positioning.

hp81CPI NOTE: hp81CPI is 8.1

hp167CPI NOTE: hp167CPI is 16.7which is

internally converted to 16.67

[*]Height hp4PT, hp10PT refers to the height of the font as

hp6PT, hp12PT measured in points.(a point = 1/72")

hp7PT, hp144PT NOTE that the point sizes:

hp8PT, hp18PT 85, 95, 144

hp85PT, hp24PT are 8.5, 9.5, 14.4

hp95PT, hp30PT

hp36PT

Style hpUPRIGHT

hpITALIC

[*] Stroke Weight hpLIGHT, lighter print

hpMEDIUM, medium print (normal)

hpBOLD darker print (bold)

[*] Typeface hpLINEPRINT

hpCOURIER

hpHELV

hpTIMES

hpGOTHIC

hpPRESTIGE

hpPRESENT

hpOPTIMA

hpGARAMOND

hpCOOPER

hpCORONET

hpBROADWAY

hpBAUER

hpCENTURY

hpUNIVERSITY

hpCGTIMES (HP III scalable)

hpUNIVERS (HP III scalable)

Example: The following example depicts a situation where the need is for 2 fonts:a big one for a heading (customer name) a standard one for most of the lines In addition, whenever FLG is set, we'll switch the current font to bold. In the data division, BIG, STD are declared as D18 variables.

Both fonts are of the same orientation, symbol set, spacing, style, weight and type.

set BIG,STD= hpPORT ;orientation
& + hpROMAN8 ;symbol set
& + hpFIX ;spacing
& + hpUPRIGHT ;style
& + hpMEDIUM ;weight
& + hpCOURIER ;type

BIG =BIG + hp6CPI ;pitch ;for BIG FONT
& + hp24PT ;points

STD =STD + hp12CPI ;pitch ;for STD FONT
& + hp12PT ;points

open (ch,o,'hplaser:')

;-- Switch to big print, display name, then switch back to std --

xcall hp (ch,hpFONT,BIG,0,CUSNAME,
& hpFONT,STD,13,10)

;-- If FLG set, switch to bold before displaying, then medium after
;-- otherwise, just dump the line

for I = 1 step 1 until N do
if (flg)
then xcall hp (ch,hpFONT,hpBOLD,rec(I),13,10,hpFONT,hpMEDIUM)
else writes (ch,rec(I))

hpFONT_DELETE, fontID

Description: Deletes a temporary font. fontID is the ID number assigned when the font was downloaded.

See also: hpLOAD

Example: xcall hp (ch,hpFONT_DELETE,1)

hpGRAPHIC, filename, resolution

Description: Sends a Raster Graphics File. filename is a full file specification. resolution is one of the 4 allowable resolutions which are 75, 100, 150 or 300. Prints a raster graphics file filename starting at the current cursor position using a resolution of resolution.

Notes:
XCALL HPSTRING appends only the file's name rather than its contents.

Raster graphics files are not the files used by scanner or paint programs!

Raster graphics files, in LaserJet terminology are files that typically contain groups of bytes that represent a bit pattern (most significant bit first) for a single raster line. Each such group of bytes is preceded by an escape sequence indicating the number of bytes which will follow.

That sequence, together with its data is called Transfer Raster Data.
Its syntax is:<esc> * b # W [raster row]
where # identifies the number of bytes in raster row.

The sequence <esc>* r 1 A placed at the top of the file (before the first Transfer Raster Data) signals that data is about to be transferred.

The sequence <esc>* r B placed at the bottom of the file (after the last Transfer Raster Data) signals that the raster graphic is over.

There are two stand alone programs provided as part of the distribution of XCALL HP which create raster graphics files. They are described in the Distribution contents section of this document. There are further notes in the source listings themselves.

Example: xcall hp (ch,hpGRAPHIC, 'pic:flower.hp', 100)

Prints the graphic file pic:flower.hp at a resolution of 100 dots/inch.

hpHLINE, length

Description: Draws a horizontal line starting at the current cursor position of length length which is measured according to hpDOTS, the current unit of measurement. The thickness of the line will be hpHTHICK, the current horizontal thickness.

Notes: Upon completion, the cursor position is unchanged. See also: hpTHICK, hpVLINE, hpDOTS

Example: xcall hp (ch,
& hpPOS,12,50, ;position cursor.
& hpHTHICK,10, ;set a vertical thickness
& hpHLINE,30, ;draw 3 inch horizontal line
& hpMOVE,1,0, ;drop down 1 line
& 0,'Authorized Signature')

hpHTAB, col

Description: Positions the cursor horizontally to the position col. See also: hpMOVE, hpVTAB, hpDOTS

Example: xcall hp (ch,
& hpDOTS,$true, ;set unit of measure to dots
& hpTHICK,25, ;set line thickness index.
& hpPOS,100,100, ;position cursor at 1" x 1"
& hpHLINE,1200, ;draw a 4" horizontal line
& hpHTAB,700, ;move to middle of line
& hpVLINE,1500) ;draw a 5" vertical line

This code draws a big "T". The hpHTAB,700 could have been replaced with hpPOS,100,700

hpLM,col

Description: Sets the left margin to column col.

Notes: When the laser is reset, (by hpFLUSH for example,) the margin is reset to 0.

Example:
The following code prints a phone book with 3 columns, of 50 lines each. The traditional print technique is to count your lines as you print them. When that counter hits some number (say 50), you clear the counter, eject the page and start again. Here, it's similar except we increment the margin by 30 and reposition the cursor back to the top of the same page. (We've also drawn some vertical lines to separate the columns.)

clear line, margin

do forever
begin
reads (1,rec,eof)
if (line.gt.50)
begin
line =
margin = margin+30
if (margin.gt.60)
begin
margin = xcall hp (ch,
& hpPOS,0,29,hpVLINE,50,
& hpPOS,0,59,hpVLINE,50,
& hpFLUSH)
end
xcall hp (ch,
& hpLM,margin,
& hpPOS,0,margin)
end
writes (ch,rec)
incr line
end
end

hpLOAD, filename, id,

hpMAKEtemp|hpMAKEperm

Description: Downloads a soft font. filename is a full file specification. id is the HP's internal identification number for the font.

The last qualifier indicates whether or not this font is be considered temporary or permanent.

Example:
xcall hp (ch,
& hpLOAD,'font:tr140bpn.r8l', 1,
& hpMAKEperm)

hpLPI,

number of lines to the inch

Description: Defines Lines per inch measurement.

Notes: LPI determines vertical spacing. It is analagous to CPI (pitch) which determines horizontal spacing although CPI is a font attribute while LPI is not. LPI affects row and column cursor positioning (but not cursor positioning using "dots"). It also determines what linefeed does. hpLPI,3 would give you double spacing relative to hpLPI,6 (which is "normal" line spacing). Similarly, hpLPI,12 would give you half- line spacing

Example:
xcall hp (ch,
& hpFONT,mytinyfont,
& hpLPI,12,
& 0, 'These 2 tiny lines fit in',13,10,
& 0, 'the space of 1 normal line',13,10,10,
& hpFONT,mynormalfont,
& hpLPI,6,
& 0, 'such as this line')

MACROS

The following is a discussion of LaserJet macros and an introduction to the eight hpMACROxxx functions which follow.

Applications may perform the same task numerous times. For tasks performed repeatedly, use of macros can significantly reduce the number of commands that would otherwise have to be sent repeatedly to the printer.

A macro is a collection of escape sequences, control codes and data that are downloaded to the printer which can subsequently be invoked using a single command.

Macros occupy a portion of the LaserJet's user memory. Depending on the amount of available user memory, up to 32 macros can be stored in memory simultaneously.

All macros have an ID number (0-32767). Each of the 8 hpMACROxxxx functions take a single qualifier which is the ID number.

CREATING A MACRO

1 hpMACROstart,ID signals "start definition for macro# ID".

2 the macro will consist of the commands and data that are subsequently received by the printer.

3 hpMACROtemp,ID signals "macro completed and is temporary".
hpMACROperm,ID signals "macro completed and is permanent".

TEMPORARY vs PERMANENT

The reset function hpFLUSH or pressing the control panel's Reset will cause a temporary macro to be deleted. Permanent macros are not deleted by a reset.

INVOKING A MACRO

There are three ways to invoke a macro: execute, call and automatic-overlay.

Execute

The function hpMACROexecute,ID executes a macro. Any changes made to the print environment (a change in font, for example) will remain in effect after the macro has completed.

Call

The function hpMACROcall,ID calls a macro. Any changes made to the print environment (a change in font, for example) will not remain in effect after the macro has completed. IE the print environment is saved before the macro's invocation and restored after it. NOTE The current cursor position is not considered part of the print environment; therefore, the cursor position is not restored even after a "call". To have the cursor's position restored, use hpPUSH at the start of the macro and hpPOP at its end.

Automatic Overlays

You do not invoke automatic overlays. They are, instead, automatically invoked as the final operation each time a page is printed. To enable a macro as an automatic overlay, use function hpMACROauto,ID. The invocation of an automatic overlay follows the rules of a "call" rather than an "execute"

DELETING A MACRO

To delete a macro with ID# of ID, use hpMACROdel,ID

DISABLING AN AUTOMATIC OVERLAY

To disable an automatic overlay, use hpMACROdisable,ID Note that this does not delete the macro. It only disables its automatic invocation every time a page is completed.

Example: The following excerpt

• defines a macro whose ID is LETTERHEAD.

• positions the cursor to the top of the page

• draws the raster graphic stored in file name LOGO.HP

• switches to a font called FANCYFONT

• positions the cursor again

• prints some text, draws a horizontal line

• signals that this macro is to be permanent

xcall hp (ch,
& hpMACROstart,Letterhead, ;start defining new macro.
& hpDOTS,1, ;insure we're in dots.
& hpPOS,0,0, ;position cursor to top
& hpGRAPHIC,'LOGO.HP',150, ;load graphic @ 150dots/inch
& hpFONT,FancyFont, ;switch to this font
& hpPOS,150,300,0,'ABC Corporation' ;@ 1.5" ,3" print this text
& hpPOS,225,300,0,'Anytown, USA', ;@ 1.75",3" print this text
& hpHTHICK,10, ;set horizontal thickness
& hpPOS,300,0, ;position to 3",0"
& hpHLINE,2400, ;draw a line 8" wide
& hpDOTS,0, ;put cmhpDOTS back to norm
& hpHTHICK,1, ;put cmhpHTHICK back to norm
& hpMACROperm,Letterhead) ;end permanent macro;--

Notes:
Presumably, LETTERHEAD is a value globally known to other programs. We use addressing by dots (hpDOTS,1) rather than by row and column because we're switching fonts (which would switch the measurements of rows and columns) Recall that neither hpDOTS nor hpHTHICK cause any output to the printer by itself. Therefore, their use does not occupy printer memory space in the macro. Since these values are stored in the common, we make sure to put them back to what we consider "normal".

Subsequent code could invoke this macro in one of the three possible ways: hpMACROexecute
hpMACROcall
hpMACROauto.

If a program invokes a macro as an automatic overlay, (hpMACROauto) it probably ought to disable it eventually (hpMACROdisable)!

If this macro is executed, the font in effect after macro completion will be FancyFont.

If this macro is called or overlaid, the font in effect after macro completion will be whatever font was in effect before the macro began.

The appeal of a macro should be clear. Once loaded, it need not be loaded again. The loading process may be time consuming. The raster graphics file LOGO.HP might be many thousands of bytes in size.

The cost should also be clear. LaserJet user memory is consumed. The trade-off is processing speed versus consumption of Laser memory.

hpMACROauto, ID

Description:
Enables a previously defined macro whose id is ID for automatic overlay. Immediately before each page is completed, the macro is automatically invoked as though it had been "called".

hpMACROcall, ID

Description:
Invokes a previously defined macro whose id is ID. Upon completion, the print environment is restored to the state it was in before the invocation. Note that cursor position is not considered part of this environment.

hpMACROdel, ID

Description:
Deletes the macro whose id is ID.

hpMACROdisable, ID

Description:
Disables a macro that has been previously declared to be an automatic overlay. Note that this does not delete the macro.

hpMACROexecute, ID

Description:
Invokes a previously defined macro whose id is ID. Upon completion, the print environment remains in whatever state the macro has set up.

hpMACROperm, ID

Description:
Signals that a macro definition has now ended and that the macro is to be considered permanent. Reset functions (such as hpFLUSH) will not disturb this macro.

hpMACROstart, ID

Description: Begins definition of a new macro. If an old macro with the same ID exists, it is replaced with the new macro.

hpMACROtemp, ID

Description: Signals that a macro definition has now ended and that the macro is to be considered temporary. Reset functions (such as hpFLUSH) will cause this macro to be deleted.

hpMANUAL

Description:
Causes the current page (if any) to be flushed and prompts the operator (on the laser itself) to feed paper manually.

To turn off hpMANUAL use hpFLUSH.

See also: hpFLUSH hpSTATIONERY

Notes: Since hpFLUSH is used to turn hpMANUAL off, recall that hpFLUSH ejects the current page if there is anything on the current page.

Example:
In this example, the user is prompted, on the laser itself, to insert a manually fed piece of paper. The reason, perhaps, is that we wish to print a cover letter on company letterhead (paper which is not in the tray) followed by a statement (on standard paper which is in the tray).

xcall hp (ch,hpMANUAL, hpPOS,15,0)

for I = 1 step 1 until 30 do writes (ch, cover(I))

xcall hp (ch,hpFLUSH,hpPOS,5,0)

for I = 1 step 1 until 50 do writes (ch, line(I))

xcall hp (ch,hpFLUSH)

hpMOVE,row,col

Description:
Positions the cursor relative to its current location by row,col. The actual physical position resulting from this will depend on the current unit of measurement as defined by hpDOTS.

See also: hpPOS, hpHTAB, hpVTAB, hpDOTS

Notes: The top of page is hpPOS,0,0 not hpPOS,1,1

Example:
xcall hp (ch,
& hpDOTS,$false,
& hpPOS,4,10, 0,'-----+',
& hpMOVE,1,3, 0,'-----+',
& hpMOVE,1,3, 0,'-----+',
& hpMOVE,1,3, 0,'-----+')

This example draws a staircase. Each of the hpMOVEs move the cursor 1 row down and 3 columns to the right. Note that row & col can be positive (down/right) or negative (up/left).

hpPOS,row,col

Description:
Positions the cursor to row,col. The actual physical position resulting from this will depend on the current unit of measurement as defined by hpDOTS.

See also: hpMOVE, hpHTAB, hpVTAB, hpDOTS

Notes: The top of page is hpPOS,0,0 not hpPOS,1,1

Example:
xcall hp (ch,
& hpDOTS,$false,
& hpPOS,4,10, 0,'Name',
& hpPOS,5,10, 0,'Rank',
& hpPOS,6,10, 0,'Serial#',
& hpFONT,hpBOLD,
& hpPOS,4,20, 0,'Alan',
& hpPOS,5,20, 0,'slave',
& hpPOS,6,20, 0,'1234',
& hpFONT,hpMEDIUM)

hpPUSH & hpPOP

Description:
The HP LaserJet has a 20 position cursor stack which can be pushed and popped on a last-in first-out basis.

Example:
xcall hp (ch,
& 13,10, 0,'some data [see footnote]',
& hpPUSH,
& hpPOS,55,10, 0,'This is a footnote',
& hpPOP,
& 13,10, 0,'more data')

Having printed "some data", we realize that we need a footnote at the bottom of the page. We save the cursor position (hpPUSH), position the cursor to the bottom of the page, print the footnote, restore the cursor position (hpPOP) and then resume.

hpSTATIONERY, type

Description:
Designates the physical page size which, in turn, defines the size of the logical page. The type qualifier is a numeric code representing the type of stationery.

When this command is received, any existing pages are flushed. If the stationery (paper size) is different from that of the installed paper, a message is displayed on the control panel requesting its installation.

Notes: The following types are included in hpsub.def although you may use any other valid type code that your laser's documentation indicates.

Type hpsub.def Label Description
paper 1 hpPAPERexec executive (7.25" x 10.5")
2 hpPAPERletter letter (8.5" x 11")
3 hpPAPERlegal legal (8.5" x 14")
26 hpPAPERa4 A4 (210mm x 297mm)
envelopes 80 hpENVletter letter (7.875" x 7.5")
81 hpENVbusiness business (4.125" x 9.5")
90 hpENVdl international DL (110mm x 220mm)
91 hpENVc5 international C5 (162mm x 229mm)

Example:
The following example changes orientation to landscape, calls for an envelope, prints the envelope, changes back to portrait and calls for standard paper.

xcall hp (ch,
& hpFONT,hpLAND,
& hpSTATIONERY,hpENVbusiness,
& hpPOS,12,30, 0,NAME,
& hpPOS,13,30, 0,ADDR,
& hpPOS,14,30, 0,CITY,
& hpFONT,hpPORT,
& hpSTATIONERY,hpPAPERletter)

hpTHICK,thick & hpVTHICK & hpHTHICK

Description:
This function declares that all subsequent lines drawn will be of thickness thick which can vary from 1 to 99.

hpTHICK sets both horizontal and vertical line thicknesses.
hpVTHICK sets the thickness for vertical lines only.
hpHTHICK sets the thickness for horizontal lines only.

Notes:
By default, these values are set to 1. No output to the printer occurs. The values set are the common area variables cmhpVTHICK & cmhpHTHICK.

Example:
xcall hp (ch,
& hpHTHICK,1, ;set for thin thickness
& hpHLINE,50,13,10, ;draw line, drop down.
& 0,'Subtotal',13,10, ;text, drop down.
& hpTHICK,10, ;set for thicker now
& hpHLINE,50,13,10, ;draw line, drop down.
& 0,'TOTAL') ;text

hpUNDER & hpUNDER_OFF

Description:
hpUNDER and hpUNDER_OFF turn underlining on and off respectively.

Example: xcall hp (ch,
& hpUNDER, 0,'This is underlined but',
& hpUNDER_OFF, 0,' this is not')

hpVLINE, length

Description:
Draws a vertical line starting at the current cursor position of length length, which is measured according to hpDOTS (the current unit of measurement). The thickness of the line will be hpVTHICK, (the current vertical thickness).

Notes: Upon completion, the cursor position is unchanged.

See also: hpTHICK, hpHLINE, hpDOTS

Example:
xcall hp (ch,
& hpPOS,300,300, ;position cursor.
& hpVLINE,900, ;draw 3 inch vertical line
& hpHLINE,900) ;draw 3 inch horizontal line

Assuming that the current unit of measurement (hpDOTS) is in dots, this code draws only the left side and top side of a 3" x 3" box.

hpVTAB,row

Description:
Positions the cursor vertically to the position row.

See also: hpHTAB, hpDOTS

Example:
xcall hp (ch,
& hpTHICK,25, ;set line thickness index.
& hpPOS,300,300, ;position cursor at 1" x 1"
& hpVLINE,1200, ;draw a 4" vertical line
& hpVTAB,1500, ;move to bottom of line
& hpHLINE,900) ;draw a 3" horizontal line

This code draws a big "L". The hpVTAB,1500 could have been replaced with hpPOS,1500,300 or with hpMOVE,1200,0 (Recall that after drawing a line, the cursor remains at its original position.)

FISH & CHIPS

To clarify a potential confusion about fonts, consider the analogy of ordering something at a restaurant.

xcall hp (ch,hpFONT,fish_and_chips) reflects your "order" of a font described in the variable "fish_and_chips". Although you are free to order whatever you want, you'll probably be disappointed if your restaurant is a hamburger stand! The anxious-to-please owner will give you whatever comes closest, hoping you'll be happy!

The same is true here. If the font you "order" isn't in the laser jet at the time you order it, don't expect to get it.

WHAT'S IN THE KITCHEN?

LaserJet printers come with some built-in fonts. You power it on and they're there. Your Laser printer should have a print-test function that lists what's in its "kitchen".

The HP Series II, for example comes with 3 fixed spaced fonts: courier 10cpi, courier bold 10cpi and lineprinter 16.66cpi. Each of these is available in two versions: portrait and landscape. Thus, the Series II comes with 6 built-in fonts. Each one is independent of the others.

You might think that courier 10cpi and courier bold 10cpi are the same font! Afterall, fish & chips and fish & chips with ketchup are the same thing, aren't they? Characteristically, one is just a slight variation of the other, isn't it? The answer is NO! They are different! To follow through with the analogy, consider that the restaurant owner keeps all his servings in the freezer. He has some pre-packaged fish & chip meal containers there: some are marked "with ketchup"; some are marked "no ketchup".

If you order fish & chips with ketchup, and he hasn't got any, he'll probably deliver fish & chips no ketchup and hope you won't notice.

The same is true with the laser. Assume the currently selected font in the laser is courier 10cpi. If you then say:

xcall hp (ch,hpFONT,hpITALIC)

you may be disappointed when nothing changes. It's only going to work if your laser has another font identical to courier 10cpi except that its style is "italic".

Let's back up: All fonts have a unique set of eight characteristics.

Style is one of the 8 font characteristics. Typical values are encoded in hpsub.def as hpUPRIGHT and hpITALIC.

Stroke weight is another font characteristic. Typical values are encoded in hpsub.def as hpLIGHT, hpMEDIUM, and hpBOLD. (Now you see why "courier 10cpi" and "courier bold 10cpi" are two different fonts!)

Point size is another font characteristic. Typical values are encoded in hpsub.def such as hp12PT and hp14PT. There are others too. There are 72 points to the inch. A 12 point font is 1/6" tall. Just as is the case with style, stroke weight and any of the other font characteristics, if you alter even one of them, you are in fact requesting an entirely different font.

But point size is a little different. It represents the difference between bit- mapped and scalable fonts. We'll discuss that in a moment.

EXPANDING THE KITCHEN - Built-in

You can't change the built-in fonts. Some lasers come with more than others. The HP Series III has more than the HP Series II.

EXPANDING THE KITCHEN - Cartridges

Besides the "built-in" fonts, most laser printers have one or two "cartridge slots". Companies like Hewlett Packard and Pacific Data supply cartridges that contain non-volatile memory pre-loaded with many more fonts. Once inserted, these fonts become part of the printer. The Pacific Data 25-in-1 cartridge has "172 fonts and symbol sets." But don't be too impressed. Some of those fonts are so similiar to each other that you'd be hard pressed to see the difference.

EXPANDING THE KITCHEN - Soft Fonts

The laser has volatile memory for "soft fonts". Soft font files, supplied by various vendors, can be downloaded to the laser. Unlike the built-in and cartridge fonts, these ones disappear when the machine is powered down.

BIT-MAPPED vs SCALABLE

All the fonts available to Series II machines are called "bit-mapped".

Series III printers also support "scalable" fonts, some of which are built- in. Scalable fonts (and the internal PCL5 processor that manipulates them) are interesting.

As we've discussed, when you alter any of the characteristics of a font, you're basically calling for a totally different font.

This is true for scalable fonts as well, but there's one big exception. The exception is point size. Specifically, "scalable" means "the point size is scalable". The point size on a scalable font can be varied without calling for a totally different font.

In bit-mapped fonts, a 12point font, a 14point font and an 18point font are, in fact, three different fonts. In a scalable font, (all other characteristics being equal) they would all be the same single font. In fact, you could get dozens of point sizes out of it!

There are other reasons to suggest that Series III (PCL 5) printers are superior to Series II (PCL 4) printers, but "scale-ability" is the most obvious one.

Be advised that most scalable fonts are proportionally spaced rather than fixed spaced fonts.

For data-processing applications (columnar output), as opposed to word- processing applications (textual output), fixed spaced fonts are more desirable to work with because it's easier to line things up.

TIPS & TECHNIQUES

Because there are 8 parameters necessary to fully define a font, consider two techiques to reduce both typing and errors. Assume you often use a font you call "STD". Declare a D18 variable called that.

1. USE A .INCLUDE FILE

Create a file STD.HP to contain the following single line:

STD=hpPORT+hpROMAN8+hpFIX+hp10CPI+hp12PT+hpUPRIGHT+hpMEDIUM+hpCOURIER

With this .include, you'll just say XCALL HP (ch, hpFONT,STD).

2. MAKE A SUBROUTINE

   You can extend this technique, making it a runtime decision, by writing a subroutine that looks up a small table file consisting of pairs of font names and their D18 values.

   To understand how the D18 variable is constructed, here is a piece of XCALL HP's source:

   record
   font_parms ,d18
   record ,x
   orient ,d1 ; 1 - 1
   symval ,d2 ; 2 - 3 SYMVAL & SYMTERM together are SYMBOL
   symterm ,d2 ; 4 - 5 SET. SYMTERM (the termination char)
   ; is the term char's ASCII value
   spacing ,d1 ; 6 - 6
   pitch ,d3 ; 7 - 9
   point ,d3 ;10 -12
   style ,d1 ;13 -13
   weight ,d1 ;14 -14
   type ,d2 ;15 -18

If you look at HPSUB.DEF (after the common area and the function defines), you'll see the structure of the font qualifiers. You can make additions or changes to many of them: instructions on how to do so are in the file.

Some of the values are obvious:
the value of hp12LPI is 12.

Some of the values require knowledge of the available/allowable parameter values in Hewlett Packard's Page Control Language (PCL). For example, the PCL typeface value for courier is 3. (which is hpCOURIER)

To fully define a font, pick 1 from each group and add them up.

In practice, there aren't many fonts you'll use. In our shop,we use five fonts called
tinyfont,
smalfont
stndfont
lrgefont and
hugefont
(For stnd and lrge, we also get variants of them by turning on italics or bold.)

The technique we use is to put all five D18 values into the environment and then use xcall getlog to get them when necessary.

How you put those values into the environment is operating system dependent unless you can use xcall setlog. The following comment lines are from a command file that we internally use to do this.

!

! Set up environment variables for main fonts

!

! Suggested LPI:-- 12 8 6 6 4

!

! TINYFONT SMALFONT STNDFONT LRGEFONT HUGEFONT

!

! ---------------------- orient portrait portrait portrait portrait portrait

! | -------------------- symbol ASCII=0U PC8=10U ASCII=0U ASCII=0U ASCII=0U

! | | --------------- spacing fixed fixed fixed fixed fixed

! | | | ------------- pitch 27.2cpi 16.67cpi 12cpi 10cpi 6.5cpi

! | | | | --------- points 3.6 pts 8.5 pts 10 pts 12pts 18pts

! | | | | | ----- style upright upright upright upright upright

! | | | | | | --- weight medium medium medium medium bold

! | | | | | | | - typeface gothic courier gothic gothic present

! | | | | | | | |

! 1 1085 2 272 036 1 5 0006 TINYFONT

! 1 1085 2 167 085 1 5 0003 SMALFONT

! 1 0885 2 120 100 1 5 0006 STNDFONT

! 1 0885 2 100 120 1 5 0006 LRGEFONT

! 1 0085 2 065 180 1 9 0011 HUGEFONT

PRINTING COLUMNAR REPORTS WITH PROPORTIONAL FONTS

The best strategy for printing columnar reports using a proportionally spaced font is to avoid it.

Consider the following:

record line

name ,a20

address ,a30

city ,a15

The traditional approach in printing is to prepare an entire print line and dump it to the printer with something like:

writes (ch,line)

For columnar reports, this doesn't work well because the letters are of different sizes: the letter "m" is fat, the letter "i" is skinny. The only options are to use either hpPOS to position the row and column or to use hpHTAB to position just the column, as in:

xcall hp (ch,

& hpHTAB,0, 0,name,

& hpHTAB,20, 0,address,

& hpHTAB,50, 0,city,
& 13,10)

This insures that your columns are left justified aligned.

It is much more difficult to generate columnar reports of numbers using a proportionally spaced font. In these situation, you would not want left justification. You would want either right justification or decimal point justification and xcall hp provides neither. To get proper alignment of numbers, you must use a fixed spacing font.

PRINTING COLUMNAR REPORTS WITH MULTIPLE FIXED FONTS

Remember that, as you change fonts, horizontal spacing may also be changing. A stategy to consider is to use cursor positioning as discussed above in conjunction with hpDOTS,$true. By using dot positioning, the cursor is positioned at the same spot regardless of the current CPI or LPI settings.

CURSOR POSITIONING AND LINE DRAWING.

When you address the cursor, the cursor is positioned to a single point. The vertical component is the point where the baseline for the next character will be printed. The bottom of most characters will sit here. Lower case characters that have descenders (eg: "g") will extend below the baseline.

xcall hp(ch,
& hpPOS,12,20,
& hpHLINE,7,
& 0,'abcdefg' )

will draw a line at position row12, col20. It will also print the string 'abcdefg' at that same point. The bottom of the letters 'abcdef' will probably coincide exactly with the line. The letter 'g' will extend underneath the line.

If you draw a 12 line deep box, starting at row 3, you can position the cursor at row 4 and print 12 lines inside it. The 12th print line, however, will be sitting right on the bottom of the box and any lower case letters with descenders will in fact print underneath the bottom of the box.

Similar considerations are relevant to the horizontal components. If the width of your box is 20 characters, you can fit 20 characters inside it. The 1st character may be touching the left side of the box. The last character may be touching the right side of the box.

If you draw a horizontal line from column 1 until column 50, you are actually drawing a line from the left side of column1 until the right side of column 50 (which is the left side of column 51). Thus, to draw a vertical line down from the right side of the horizontal line (making a corner), you would position the cursor at column 51 (not 50).

THICKNESS BUG NOTE:

The design of hpBOX was supposed to be measuring the outside of the box. It doesn't quite work. Top to bottom is accurate but the horizontal position where the inside right edge starts is really where it should be ending. In other words, a 2" wide box is wider than 2" by the amount of thickness.

DEBUGGING:
If your Laser's output is not what you're expecting, try using hpDEBUG,1. This will cause the laser to display your escape codes rather than executing them.

HP ESCAPE SEQUENCES:
The HP's User's Guide lists all the escape codes the printer supports but doesn't go into much detail on most of them. For more detail, you'll the need the Technical Reference Manual.

NOTES on HP.SUB source:
hp.sub is well documented and readable, once you get the hang of it.

HOW PARAMETERS ARE HANDLED
Except for the 1st parameter, all the rest are called P1,P2,P3... These Px parameter names are never used once inside the routine! Instead, the following technique is used.

The variable ptr is a pointer that points to a parameter using the DBL construct %arg(ptr)

When you use the construct %arg(i) you are referring to the ith parameter but you must also tell DBL what type (A,D,F) it is by casting it. There are 3 casting functions: %a (for alpha), %d (for decimal numeric), and %f (for fixed numeric)

To refer to the ith parameter as decimal numeric, use %d(%arg(i))

For example, as the routine is looping though its parameters, it is checking for a parameter value of zero. This value indicates that the next parameter is to be considered an alpha string which is to be displayed. Here (on the next page) is part of that code:

if (.not.%d(%arg(ptr)))
begin
incr ptr
display(ch,%a(%arg(ptr)))
...

WHAT MOST OF THE CODE DOES
The bulk of the work happens at label PARSE and in an unlabelled CASE statement that uses the function numbers in HPSUB.DEF

PARSE, INCR ptr ;If parameter ptr is zero, the next parameter is an alpha. Increment
; ptr, display parameter ptr as an alpha. Loop back to PARSE.

;If parameter ptr is less than 32, the next parameter is a decimal
; number whose ASCII value is to be displayed. Increment ptr,
; display parameter ptr as a decimal number. Loop back to PARSE.

; At this point, parameter ptr is numeric 32 or greater.

SWITCH = %d(%arg(ptr)) - 31

CASE SWITCH OF BEGINCASE ;big unlabelled case statement

;----------

;--hpPOS=32

;----------

The code for hpPOS will increment ptr twice: the first time

to get the row, the second time to get the column. Based

on whether or not we're using DOTS to do the addressing,

one of two different escape sequences will be created. For

XCALL HP, the escape sequence will be output to the

channel. For XCALL HPSTRING, we use XCALL

APPEND to append the escape sequence onto the end of

STRING.

;----------

;

;----------

;----------

;

;-----------

ENDCASE

WHAT IS THAT FONT?
Included in the distribution is subroutine FONTRPT.SUB which returns to you a narrative description of a D18 font descriptor.
Syntax: xcall fontrpt (font, alpha)
ALPHA should be minimum A70

Also included is SHOWFONT.DBL (which uses FONTRPT). It reads an input file of font descriptors and outputs a file identical to the input file except that the narrative descriptions are appended onto the end of each record.