ENGINEERING update FOR 2.0 PRINTGEN. A C Page 1 of 120 PRINTGEN. Engineering Update (DAA -170)

Transcription

1 o ENGINEERING update FOR 2.0 A C Page 1 of 120

2 Speifiations Subjet to Change. Convergent Tehnologies and NGEN are registered trademarks of Convergent Tehnologies, In. Convergent, CT-DBMS, CT-MAIL, CT-Net, CTIX, CTOS, DISTRIX, Doument Designer, Generi Print System, The Operator, AWS, CWS, IWS, MegaFrame, MiniFrame, MightyFrame, and X-Bus are trademarks of Convergent Tehnologies, In. CP/M-86 is a registered trademark of Digital Researh. MS and GW are trademarks of Mirosoft Corp. UNIX is a trademark of Bell Laboratories. Copyright 1985, 1986, 1987 by Conver~ent Tehnologies, In., San Jose, CA. Printed In USA. All ri~hts reserved. Title to and ownership of the doumentation ontamed herein shall at all times remain in Convergent Tehnologies, In., and/or its suppliers. The full opyright notie may not be modified exept with the express written onsent of Convergent Tehnologies, In. A C Page 2 of 120 Engineering Update (DAA-170)

3 TABLE OF CONTENTS C 1.0 PURPOSE and DEFINITION OF STRUCTURE and CONTENTS OF CONTENTS OF DISTRIBUTION DISKETIES INSTALLATION ADDITIONS and CHANGES STRUCTURE OF A GPS DEVICE DRIVER DEVICE-DRIVER FONT PROCESSING PAGE ORIENTATIONS and DIMENSIONS Page Dimensions Page Orientations DEVICE-DEPENDENT FUNCTIONS Required Devie-Dependent Proedures Graphis-Proessing Devie-Dependent Proedures... ~ DEVICE-DRIVER STATUS MESSAGES PAUSE Message FONT-REQUIRED Message FORM-REQUIRED Message DEVICE-DEPENDENT OUTPUT ROUTINES AVAILABLE GPS UTILITIES Font-Related Utilities Devie-Setup-Field Utility Misellaneous Utility Funtions FONT ESCAPE SEQUENCES GPS DATA STRUCTURES OF INTEREST A C Page 3 of 120

4 15.0 GPS CHARACTER-RECORD GPS DEVICE-SPECIFICATION PARAMETERS GPS 1.0 TO GPS 2.0 CONVERSION Pathing Existing GPS 1.1 Drivers... o/~" 17.2 Changes Required for GPS 2.0 Link... ~-.:~_~/ 17.3 Adding GPS 2.0 Features IMPLEMENTATION LANGUAGES LINKING A NEW GPS DRIVER DEBUGGING AIDS EXAMPLES GPS DEVICE-DRIVER STATUS CODES GPS Status Codes Font Servie Status Codes More GPS Status Codes A C Page 4 of 120 Engineering Update (DAA-170)

5 -~~ ~~ PURPOSE and DEFINITION OF () PrintGen is a tool kit whih assists the programmer in reating a new Generi Print System (GPS) devie driver. GPS is an abbreviation for the Generi Print System. PrintGen 2.0 addresses the issues of reating a GPS 2.0 devie driver. PrintGen is PrintGen is NOT - Doumentation relevant to the desription, definition and reation of devie-dependent GPS devie drivers. Objet modules for the devie-independent portion of a GPS devie driver. Various examples of devie-dependent ode for GPS devie drivers. A olletion of tools to simplify the reation of a new devie driver for GPS. An appliation or utility program whih will reate GPS devie drivers. A tool for the "Printing Administrator". A menu-driven program to modify existing drivers or to reate new GPS drivers. PrintGen's goal is to enable an experiened CTOS system programmer to reate a new GPS devie driver within four weeks. Many GPS devie drivers an be implemented in less time. More tehnially stated, the objet of PrintGen is to 1) assist the programmer in reating new devie-dependent ode, 2) l?rovide all of the GPS-Core modules to the programmer, and 3) assist the programmer in ombining the provided GPS-Core modules with the newly reated devie-dependent modules. Engineering Update (DAA-170) A C Page 5 of 120

6 COMPATIBILITY NOTE This version of PrintGen is an "engineering-update" version to be used with the Currently-released GPS 2.0. It entirely replaes the 1.1 version of PrintGen as well as the s1.01 "engineeringjpeial" version. This "engineering-update" version provides the faility to build devie drivers that are ompatible with GPS 2.0 and that inlude improvements made in GPS 2.0 devie drivers. Any drivers built by PrintGen for use with GPS 2.0 must be built with this version of PrintGen. Page 6 of 120 Engineering Update (DAA-170)

7 2.0 STRUCTURE and CONTENTS OF PrintGen onsists of three basi omponents: ( """. / 1) The PrintGen manual. 2) PrintGen files. 3) PrintGen examples. PrintGen Manual - This manual: a. b.. d. PrintGen Files Defines what funtions must be performed by the devie-dependent portion of any G PS devie driver. Defines what proedural interfaes must be present in any G PS devie driver. Defines the GPS data-output proedures that must be used by the devie-speifi portion of any GPS devie driver. Desribes and defines the various GPS data strutures that are of onern to the deviedependent ode in any G PS driver. e. Comments upon the example devie-driver soure files that are inluded in PrintGen. The PrintGen files provide the devie-driver programmer with: a. The devie-independent portion of any G PS devie driver. b. Data-struture definitions whih may be inluded in the programmer's deviedependent ode.. Commands and file-lists that ontrol and simplify the linkage of a new G PS devie driver. PRIl'I'-GEN Engineering Update (DAA-170) A C Page 7 of 120

8 PrintGen Examples - Devie-dependent soure ode for different types of GPS devie drivers is inluded with the PrintGen produt. These examples are taken from the set of Convergent Tehnologies supported GPS devie drivers. They omplement the defmitions in the PrintGen Manual by showing the implementation of working GPS devie drivers. Comments upon the driver examples are found in the PrintGen Manual. ;/ Related Doumentation - Printin~ Guide. Desribes installation and use of GPS devies. Generi Print System Pro~ammer's Guide. Desribes the omponents and arhiteture of G PS. The etos 012eratin~ System Manual Volume I. Desribes yte Streams, and Byte-Stream Image Modes. 3.0 CONTENTS OF DISTRIBUTION DISKETTES This release of PrintGen is ontained on two diskettes. Most files are ontained in an arhive file on the two diskettes. PrintGen-related files on the PrintGen-Installation diskettes [diskette #1] <Sys> HdInstall.sub <CT> 2.0PrintGen.do PrintGen-installation file. This doument (Doument Designer 2.0 format). (-" '~... j' A C Page 8 of 120 Engineering Update (DAA-170)

9 [diskette #1]<CT>.Ol and [diskette #2]<CT>.02 (Arhive File) o CtosTypes.h String.h String.mdf CtosLib.edf CtosTypes.edf CommStatus_prelO.obj CommNub_prelO.obj lnitco~prelo.obj lnitcomm.obj 2.0DevDr.lib 2.0Gpam.lib GpsDb.ldf DD.lit strutgps.h DdParams.asm DdParams.idf DdParams.h DdSam.idf DdSam.h GpsEr.idf GpsEr.h Ctos struture and subroutine definitions. Byte-Stream routines inluded in GPS devie drivers. Library of G PS-Core routines. Library ontaining G P AM routines. (Version 2.0) Defines data strutures used by a GPS devie driver. Template for the devie-desription parameter file that must be provlded with eah GPS devie driver. Proedural definitions of the GPS-Core routines alled by devie-dependent ode for data output. Definitions of er odes generated by GPS devie drivers.. Engineering Update (DAA-170) A C Page 9 of 120

10 MinMax.idf Convert.idf CompileOptions.idf DdChan~ePWheel.idf DdUtilitIes.idf FontUtil.h FontUtil.idf DdVp.idf DRLTypes.h DDLits.h types.h ulos.idf Util.idf XUtilDD.idf DdFntLit.h DdVpData.h LinkGpsDriver. sub AltVer.run linkgpsfirst.f1s linkgpsgr.fls linkgpsgrstub.fls linkgpsreqres. fis linkdaisy.fls Definitions of Utility routines used by the devie-speifi soure ode of the example devie drivers. Definitions of Submit file whih implements the Link GPS Driyer ommand. Utility used when reating a GPS devie driver that an be loaded with the PMOS server. Run file for ~ ommand. List of GPS-Core routines that must be the first objet modules in the list of objet modules speified to the Linker when linking a GPS devie driver. List of GPS-Core graphis modules. List of GPS-Core modules that must be inluded when graphisproessing is not supported by a driver. List of GPS-Core modules that are required in all G PS devie drivers. List of devie-speifi objet modules for the Daisy GPS devie driver. Page 10 of 120 PRINTGE~

11 linkdaisy.libr.fls linkdaisy.sub DaisyParams.asm Daisy. DaisyJ)ata. DdConfig. DdFontChangeG. plm DdSheet. Conat2. Conat3. Daisy.h DdFDeLh Ulmp. U. linkhplaserjelfls linkhplaserjet.libr.fls linkhplaser J elfls HpParams.asm HpLaserJet.plm linklmagen8300.fls linklmagen8300.libr.f1s linklmagen8300. sub Ddlmagen8300. asm DdlmagenDriver. plm DdlmagenFont. List of devie speifi Library files, if any, for the Daisy GPS devie driver. Daisy submit file that links the Daisy driver. Daisy-driver soure ode. List of devie-speifi objet modules for the HPLaserJet G PS devie driver. List of devie speifi Library files, if any, for the HPLaserJet GPS devie driver. HPLaserJ et submit file that links the HPLaserJet devie driver. HPLaserJet-driver soure files. List of devie-speifi objet modules for the Imagen8300 G PS devie driver. List of devie speifi Library files, if any, for the Imagen8300 G PS devie driver. Imagen8300 submit file that links the Imagen8300 devie driver. Imagen-driver soure files. A-09-01IS9-01-C Page II of 120

12 linklptsimple.fls linklptsimple.libr.fls linklptsimple. sub LptSimple. LptParams.asm Compile.-Examples.sub CompileJ)ev.sub PrtGen.fls List of devie-speifi objet modules for the LptSimple GPS devie driver. List of devie speifi Library files, if any, for the LptSimple GPS devie driver. Submit file that links the LptSimple Devie Driver by means of the Link GPS Driver ommand. Simple-ASCII -printer driver soure files. Submit file that ompiles the soure files of the example devie drivers. The Submit file that is alled for eah of the four example devie drivers. List of all the files in the Arhive file in the CT diretories of the PrintGen installation diskettes. A-09-0llS9-01-C Page 12 of 120 PRI1'"TGEN Engineering Update (DAA-170)

13 4.0 INSTALLATION PrintGen may be installed onto a workstation whih has been booted from a hard-disk -- it annot be installed upon a system that boots from a floppy disk. CTOS Standard Software 10.3, or later is required for PnntGen installation and use. The installation proedure: a) Restores the PrintGen files from the distribution diskettes arhive file to various diretories on the urrently pathed devie. The diretories will be reated if they do not already exist. Note that the user must assure that existing diretories are of the size indiated below or the ompilation and link of example drivers may fail. These diretories are: <2.0Daisy> <2.0DaisyBld> <2.0HP> <2.0HPBld> <2.0Imagen> <2.0ImagenBld> <2.0Lpt> <2.0LptBld> <2.0DevDrBld> <2.0Gpam> <2.0GpamBld> <2.0GpsDef> <2.0PrtGenBld> 200 Files 75 Files (default) 200 Files 75 Files (default) 200 Files 75 Files (default) 200 Files 75 Files (default) 75 Files ldefaultl 75 Files default 75 Files default 200 Files 75 Files (default) b) Copies ommand files to the "system" diretory. This is usually the [Sys]<Sys> diretory. Another "system" diretory may be speified -- see Installation Proedure step 3 for the desription of that installation parameter. ) Adds PrintGen ommands to a ommand file. The ommand file to whih ommands are added is usually [Sys] <Sys>Sys.mds. Another ommand file may be speified -- see Installation-Proedure step 3 for the desription of that installation parameter. PRIl'-'7GEN Page 13 of 120

14 PrintGen is installed onto a hard-disk workstation by performing the following proedure: 1. Plae the PrintGen-distribution diskette into floppy drive fro]. 2. Use the PATH ommand to set the path to the volume where ;/ -", PrintGen diretories will reside. Set default rassword to the volume password for the PrintGen volume. I any installation "'-.. j parameters other than the defaults are used, other volume passwords may need to be set, or perhaps none at all. 3. Use the SUBMIT ommand to submit [fo]<sys>hdlnstall. sub. The INSTALL ommand will work here; however, there is no way to set installation parameters if the install is done via the INSTALL ommand. No parameters need be set, but there are two installation parameters that may be speified by the installer. Installation parameters - - # 1) Installation Floppy Drive - This is the devie from whih the PrintGen files are restored. It defaults to [ro]. A different drive an be speified with this SUBMIT parameter. #2) Command File This is the ommand file to whih the PrintGen ommands are added. It defaults to [Sys] <Sys>Sys.mds. A different ommand file (e.g., [Sys]<Sys>Speial.mds) an be speified with the third SUBMIT parameter. Any of these parameters must be on the SUBMIT ommand's "Parameters" line. Position is important. If a value is to be entered on the seond parameter, but not for the first, a null parameter (i.e., ") must preede the seondparameter string on the "Parameters" line. 4. The Restore ommand will prompt the user to mount/insert [ro]<t>.ol. This is the first of the two distribution diskettes, and is already inserted in the drive -- the user need only press <GO> at this point. When the Restore ommand prompts the user for [fo]<t>.02, he should remove the first diskette, insert the seond diskette and press <GO>. 5. After the "installation-ompleted" message is displayed, the PrintGen-distribution diskette is removed from [ro]. A C Page 14 of 120

15 6. On previous releases, the user ould elet to opy the Example files from a separate diskette. In this release, all files are restored, inluding the example drivers and their soure. C ~\, y 7. All of the example GPS devie drivers an be ompiled by submitting the following submit file: CompUe-Examples.sub. This file invokes another submit file, CompUeJ)ev.sub, to ompile eah of the example drivers. Examination of CompUeJ)ev.sub will reveal the parameters required to ompile and link the desired driver. 5.0 ADDITIONS and CHANGES Fonts and harater-translation: Among the major new features introdued in GPS 2.0 are: 1) the support of various fonts within a doument; and 2) harater translation. These new devie-driver features are desribed in the following setions and subsetions of this doument: DEVICE-DRIVER FONT PROCESSING (page 18) Font-Related Utilities (page 53) Page orientations and sizes: GPS 2.0 has added a number of additional features to GPS in the area of page orientations and page dimensions. Landsape and portrait pages an now be printed in the same doument. Devie page sizes an be speified at devie-driver installation. See the PAGE ORIENTATIONS and DIMENSIONS setion (page 21) for more information about page orientations and sizes. Devie-driver initialization: Failities have been added for devie-dependent ode that must perform initilizations and resoure alloations during installation, before the devie driver is onverted to a CTOS system servie. See the desrietion of the DdBeroreConvertG routine (page 34) in the Required evie-dependent Proedures subsetion. Engineering Update (DAA-170) A C Page 15 of 120

16 Debugging aids: A number of features have been added to the GPS 2.0 devie drivers that aid the debugging of devie-dependent ode. These are new features whih have either been added expliitly for debugging, or whih also aid debugging in addition to their pnmary purpose. Debugging the devie-dependent ode of a G PS devie driver is aided by the following features: Debugger entry at devie-driver installation. DdBeforeConvertG and DdFirstChaneG DDP routines. File output of output-devie ommands. See the DEBUGGING AIDS setion (page 104) of this doument for detailed information about these debugging aids. GPS GPS 2.0 ompatibility and onversion: GPS GPS 2.0 ompatibility issues are disussed in detail at the appropriate plaes throughout this doument. In addition, the GPS 1 0 TO {IPS 2.0 CQNVERSION setion (page 94) is devoted to GPS GPS 2.0 onversion. That setion disusses several different onversion approahes. The different approahes require different amounts of onversion effort and Ylel,d different levels of GPS 2.0 funtionality. 6.0 STRUCTURE OF A GPS DEVICE DRIVER / This setion of the PrintGen Manual provides insight into the arhiteture of a GPS devie driver. This overview will aid the programmer in understanding how the devie-dependent portion of a GPS devie driver fits into the rest of the driver. It will also aid the programmer in understanding whih funtions the deviedependent ode must perform and whih funtions are already implemented in the devie-independent portion of a GPS devie dnver. Two basi omponents omprise a GPS devie driver. Those omponents are: GPS devie-driver~. GPS devie-dependent portion (DDP). The Core onsists of all ode that is used by all GPS devie drivers, independent of the atual output devie being driven. All ode in any driver that is devie-dependent omprises the DDP ode. Page 16 of 120

17 The objet of PrintGen is to: 1) assist the programmer in reating new DDP ode, 2) provide all of the GPS-Core modules to the programmer, and 3) assist the programmer in ombining the provided GPS-Core modules with the newly reated deviedependent modules. One of the design goals of G PS, was to greatly simplify the task of implementing new drivers. Consequently, the majority of a GPS devie driver's ode is in the GPS Core -- relatively little DDP ode need be reated to implement a new G PS devie driver. The DDP of a GPS devie driver translates GPS data into deviespeifi data. It onverts loations in GPS units of measure to the appropriate devie-speifi loations, in the devie's units of measure. It onverts GPS harater-attribute flags into deviespeifi ommand sequenes. It onverts GPS olor values into the appropriate, devie-dependent ommand sequenes, et. From the perspetive of the DDP, the GPS Core may be thought of as perfonmng two funtions. First, it provides harater and graphis information to the DDP for translation into a deviespeifi format; and, seondly, it takes the devie-speifi data from the DDP and outputs it to that physial devie. Therefore, a GPS devie driver is arhiteturally omposed of two parts: the GPS Core; and the DDP. But, using a data-flow model, the DDP is sandwihed in the middle of the GPS Core - it reeives GPS data from the Core, translates it into deviespeifi data, and sends that new data to other half of the GPS Core for output. You an view the omplete GPS devie driver in terms of the "J am Sandwih" model. The bread is the GPS Core, and the jam is the DDP. The "jam" is surrounded by the "bread" -- one slie of the GPS Core sends (GPS) data to the DDP while the other slie of the GP1S Core reeives (devie-speifi) data from the DDP of the GPS devie driver. The text data reeived by the DDP from the GPS Core onsists of GPS Charater Reords. One of these reords is reeived for eah harater to be printed. A GPS Charater Reord speifies whih harater is to be printed, and where it is to be printed on the page. This reord is fully defined in the Q S CHARACTER-RECORD setion (page 83). The graphis data reeived by the DDP from the GPS Core define various graphis objets, in terms of GPS units. The graphisdata struture is defined for eah ~aphis-proessing routine in the DEVICE-DEPENDENT FUNCTIONS setion (page 33). Output data emitted by the DDP of the GPS devie driver is a stream of bytes, in whatever format is proper for the partiular devie supported by the driver. A C Page 17 of 120

18 The DDP does not always translate the output data. If TRANSPARENT, IMAGE or BINARY ima~e modes are in effet, all of the data is sent diretly from the mput slie of the GPS Core to the output slie, ompletely bypassmg the DDP of the driver. (These "image modes" are defined in the GPAM and CTOS-bytestreams doumentation.) Some of the GPS Core ode is used only in the proessing of graphis data. A GPS devie driver whih supports only textual \,,-"/ data need not be burdened with graphis-proessing ode whih it will never use. Exlusion of the Core's $faphis ode may be requested when the devie-driver runfile IS being linked. The details of this are desribed in the LINKING A NEW GPS DRIVER setion (page 1(0). 7.0 DEVICE-DRIVER FONT PROCESSING Amon, the major new features introdued in GPS 2.0 are: 1 The support of various fonts within a doument. 2 Charater translation. This setion disusses what a GPS 2.0 devie driver must aomplish to support font translation, what information a devie driver obtains from the Convergent Font Database, and what fonttranslation ations are the responsibility of the devie-dependent ode in any GPS 2.0 devie driver. This setion desnbes the "font philosophy" of a GPS 2.0 devie driver. Subsequent setions detail the proedures providing font-translation servies to devie-dependent ode. This supplements the Font Database and Font ServIe information provided in the Printini Guide. Charater translation is required for the use of various fonts within a doument, but is also a useful feature even with devies that an output only one font. For example, the output harater ode used to print a 8, varies from devie to devie. The harater translation feature in the GPS 2.0 devie driver an be used to translate the doument's harater ode for 8 into the harater ode required by the partiular devie to print the Ii harater. This setion disusses the harater translation feature in the more general ase of multiple-font translations, but is relevant for those GPS 2.0 devie drivers that support only one font and require some harater-ode translations. / Page 18 of 120

19 ( The following definitions are used in the rest of this setion and in some subsequent setions. A glyph is mark made by an output devie. Often a printed harater and a glyph are the same thing, but not always. A is an output harater. Depending upon the output devie's \ apabilities, this harater ould be omposed of either one or two. glyphs. Some printers have a ommand that results in an ii glyph,/ being printed, but on some other printers the ii is printed by ommanding the 'printer to output an a glyph and an umlaut glyph at the same 10atlOn. Let Q: Let,8 Let X represent the harater ode for a harater in a doument. represent the ode for a glyph that an be printed by a devie. represent the ommand string whih must be sent to a devie to ause a partiular glyph to be printed. The goal of a GPS 2.0 devie driver, with respet to font translation, is to perform the following translations: a--+,8-+x For a given a, find its orresponding,8, and then find the X whih orresponds to that,8. Or to put it another way, for a given harater ode in a doument (a), find the value ({3) used to represent that glyph on the partiular output devie, and then find the devie ommand (X) that must be sent to the devie to ause the desired glyph to be printed. For example, assume the following: 1. The harater ode for in a doument is A partiular printer is apable of printing the glyph. 3. The ode assigned to the glyph for this printer is The ommand that must be sent to this printer to print the glyph is SHIFf-IN/123/SHIFT-OUT. So ds 3. f3 is 250. X is SHIFf - INI123/SHIFf -OUT. And the desired translation to print a upon this partiular printer is: SHIFf-IN/123/SHIFf-OUT. The translation sequene: a-+,8-+x is more manageable when separated into its two omponents: 1. 0:-+,8 2.,8 -+ X Engineering Update (DAA-170) A C Page 19 of 120

20 The first translation (0' -+ (3) is referred to as the First-Level Translation. The seond «(3 -+ x) is referred to as the Seond Level Translation. In general, the First-Level Translation is atually not a I-to-l translation, but rather a I-to-many translation. Consider the above ase of a printer that prints an i by outputting two glyphs (an a and an umlaut) at the same position. In this ase the Flrst Level Translation must translate from the doument ode to the printer's glyph odes. (And then the printer ommands to print eah of these two glyphs are obtained by performing the Seond Level Translation u~on eah of these two resultant glyph odes.) So the First-Level Translation is really: ' 0' -+ «(3,/3,/3...,(3). The Font Se~i~e 3 supports this I-to-many mapping in the First Level Translation. A GPS 2.0 devie driver is organized suh that the driver Core ontrols the First-Level Translation, and the devie-dependent ode ontrols the Seond-Level Translation. (Utility routmes are provided for use by the devie-dependent ode to extrat the Seond-Level Translation information from the Font Database.) This division between the Core and devie-dependent ode means that the devie-dependent ode need not ompose a harater from individual glyphs, and need not translate from the doument harater ode to the devie's glyph odes. The Core passes to the devie-dependent ode a series of devie-glyph odes and the loation at whih eah glyph is to be plaed upon the page. The devie-dependent ode is then responsible for orretly positioning the "printhead" and for obtamin~ and outputting the orresponding print-glyph ommand. ConSIder again the above ase of a printer that prints an a by outputting two glyphs (an a and an umlaut) at the same position. The Core will translate the doument ode for a into the devie's glyph ode for an a and the devie's glyph ode for an umlaut. These two glyph odes will be passed to the devie-dependent ode, whih is responsible for obtaining and outputting the two orresponding printer ommands. Design of a partiular GPS 2.0 devie driver and the information for that devie in the Font Database are, therefore, interrelated. Generally, the devie-driver designer should also "design" the data to be added to the Font Database for that devie. Subsequent setions in this doument detail: 1. Routines alled from devie-dependent ode to obtain Seond-Level Translation data. 2. Font-related information passed from the Core to the devie-dependent ode for eah printer glyph to be printed. 3. Examples of how some of the Convergent-supplied devie drivers use these routines. Page 20 of 120

21 8.0 PAGE ORIENTATIONS and DIMENSIONS GPS 2.0 has added a number of additional features to GPS in the area of page orientations and page dimensions. Landsape and portrait pages an now be printed in the same doument. Devie page sizes an be speified at devie-driver installation. To take full advantage of these new features, devie-dependent ode and data must added for eah hardware devie that an support them. Page orientation and page dimensions are presented together in this setion beause page orientation is determined by page dimensions. 8.1 Page Dimensions Several page-dimension sets exist in a GPS 2.0 devie driver. They are: 1~ PrintGen page-dimensions. 2 Installation page-dimensions. 3 GPAM page-dimensions. 4 Current page-dimensions. These four page-dimensions are desribed in detail below. PrintGen page-dimensions: Eah GPS 2.0 devie driver inludes a speifiation of the maximum-sized page that an be supported by the devie driver. This page-dimension pair is speified in DDwPgLength and DDwPgWidth. These two PrintGen variables are defined in the GPS DEVICE-SPECIFICATION PARAMETERS setion (page 87).. These two variables had a different usage in GPS 1.0 devie drivers. In GPS 1.0 devie drivers, they speified the driver's page size for eah page of eah doument. In GPS 2.0 devie drivers, these variables speify the driver's maximum page size. The three other page-dimensions annot exeed this drivermaximum page size. PRI~7GEN Page 21 of 120

22 Installation page-dimensions: Devie page size is speified at devie-driver installation. This installation page-dimension beomes: a. The default page size for all douments printed by this driver. b. The maximum page size for all douments printed by this driver. This installation-time, page-size speifiation allows a single devie driver to support different-sized paper in different installation instanes. Installation page-size is limited by the PrintGen page-dimensions. An installation page-size that is larger than the PrintGen-speified page-size is not aepted. During installation, eah installation page-dimension that exeeds the orresponding PrlntGen pagedimension is replaed by the orresponding PrintGen pagedimension. For example, if the PrintGen page-size is 81f2 X 11 and a page-size of 14 X 10 is speified at devie-driver installation, then the resultant installation, default page-size will be 8 1 /2 X 10. Installation page-dimensions are speified b~ entering values into the l&.ni1h and ~ fields of the Paie ]2imensiQru; for GPS Output setion of Print Manager's devie-driver installation form, ~~fp~o entering a value into the Chars Per Line (nqn-gpam field of the same Print Manager form. The "Chars Per Line" value is a speial-ase, page-width speifiation, and is / '" disussed later in this subsetion. ' GPAM page-dimensions: GPAM's GPAMBeginPage all may inlude page-dimension speifiations. This page-dimension information speifies the page-dimensions to be used while printing the page data that follows the GP AMBeginPage all. Any GP AM page-dimensions replae the Installation page-dimensions for the page that follows. GP AM page-dimensions are limited by the Installation pagedimensions. A GP AM page-size that is larger than the installation-speified pa~e-size is not aepted. During GPAMBeginPage-proessmg, eah GPAM page-dimension that. exeeds the orresponding Installation page-dimension is replaed by the orresponding Installation page-dimension. Page 22 of 120 Engineering Update (DAA-170)

23 Current page-dimensions: ( '~, / ("~ " '\ The page-dimensions urrently in effet are the Current pagedimensions. These are the page-dimensions atually used by the G PS Core in proessing print data. Current page-dimension values are a funtion of the preeding three types of GPS deviedriver page-dimensions. Usually, the Current page-dimensions are equal to either the Installation page-dimensions or to the GPAM page-dimensions. When printing a GPAM doument, the Current page-dimensions are usually equal to the GP AM page-dimensions. When printing a non-gpam doument, the Current page-dimensions are usually equal to the Installation page-dimensions. But they are sometimes not equal to either the GP AM or Installation page-dimensions. As desnbed above, Installation page-dimensions an be altered by PrintGen page-dimension limitations, and GP AM page-dimensions an be altered by Installation page-dimension limitations. Also, the atual Current page-dimensions are affeted by the I>:~: orientation requested. This is desribed in the following Orientations subsetion (page 27). When devie-driver installation begins, the PrintGen pagedimensions are used as the Current page-dimensions. After the Installation page-dimensions have been obtained (and perhaps altered by PrintGen pa~e-dimension limitations), they beome the new Current page-dimensions. When any GPAM pagedimensions are enountered, their (perhaps altered) values beome the new Current page-dimension values. If a page-orientation request neessitates a hange in page-dimensions, then the new, hanged values beome the new Current page-dimension values. Page-dimension usage: Page-dimension values have two primary uses in a GPS devie driver: 1. Page-orientation determination. 2. Devie-dependent information. C~ Pa~e-orientation determination is disussed in the ~ Onentations subsetion (page 27), whih follows. Page-dimension information is passed to the devie-dependent ode at the beginning of eah pa~e. (See the desription of DdNewPageG in the DEVICE-DEPENDENT FUNCTIQ~S setion, page 40.) Generally, the page-dimensions do not ause the Core to restrit where haraters or graphis may be plaed on a page. A GP AMReposition may be speified to any loation within the 45" X 45" GPS page spae, regardless of the page-dimensions. And haraters and graphi objets may be plaed at any loation within the GPS page spae. There are some speial ases in Page 23 of 120

24 whih the GPS Core does fore plaement of haraters to be within the Current page-dimensions. These involve the printing of non-gp AM and unformatted douments, and are disussed below. Chars-Per-Line and non-gpam douments: When a non-gp AM doument is being printed, the page width is based upon number of olumns instead of the speified J'age width. This number-of-olumns value is obtained from the Uars Per Line (non-gpam output) field of. the Print Manager's devie-installation form. When a non-gp AM doument is being printed, the page width is based upon how many olumns are available. When a GPAM doument is being printed, the page width is based upon the speified size in inhes. A GPS 2.0 implementation detail is signifiant here. The GPS Core's Current page-dimensions are always inhes, never olumns, even when printing a non-gp AM doument. When the printin~ of a non-gp AM doument is begun, the speified Ch.ars Per Lme value is multiplied by the devie driver's default harater width (DDwWidth) to ~enerate a page width in inhes that the Core an use for part of Its page-dimensions. If a devie driver has a partiularly large default harater width and a large enough "olumns" value is speified, then the Core will attempt to / generate a page width that exeeds the 16-bit limit of GPS units. If suh overflow ours, the resultant output is undefined. For 7 examrle, if a devie driver's default harater width is one-tenth inh (144 GPS units), then the maximum valid value of Chars Per ~ is about 445. Line wrapping and automati FonnFeeds: In a limited number of ases, the GPS Core will prevent an attempt to plae a harater past the right edge of a page or beyond the bottom of a page. These ases our only in unformatted douments. An unformatted doument is a doument that does not ontain harater-positioning ommands. An ASCII text file is therefore an unformatted doument (LineFeed, CarriageReturn, Tab and FormFeed are not harater-positioning onimands for this lassifiation). A GP AM file mayor may not be a formatted doument. If it ontains no harater-positioning ommands, then it is an unformatted doument. Wh"en any attempt is made to plae a harater of an unformatted doument past the bottom of the page, a new page is begun, and Page 24 of 120 Engineering Update (DAA-170)

25 that harater is positioned at the beginning of this new page. The offpage detetion and new-page generation is performed by the GPS Core. The page-length omponent of the Current pagedimensions determines the loation of the bottom edge of the page. Attempts to plae an unformatted-doument harater past the right edge of the page mayor may not be allowed. The default is to allow suh harater plaement. However, if Wrap: was entered on the Deyie Setup field of Print Manager's deviedriver installation form, then suh past-the-right-edge plaement is not allowed by the Core. Rather the offending harater is plaed at the beginning of the next line. The pa~e-width omponent of the Current page-dimensions determmes the loation of the right edge of the page. So for an ASCII text file that ontains no FormFeeds, a new page will be automatially reated by the Core eah time the urrent page is filled. If Wrap: is not speified at installation and any lines of the text are wider than the printer, the appearane of the output depends only upon what the partiular printer does when an output line exeeds its apaity. If Wrap: is speified, then these too-long text lines will be automatially nwrapped n onto the next printer line by the GPS Core. GPS 1.0 devie drivers perform quite differently in this respet. They fore line wrappmg and automati page ejet for all douments -- even formatted douments. By entering Wrap: on the Deyie Setup field of Print Manager's devie-driver installation form, a GPS 2.0 devie driver an be made to behave like a GPS 1.0 devie driver, when proessing unformatted douments. Page borders: The Paie Dimensions for GPS Output setion of Print Manager's devie-driver installation form inludes Border fields. Border values are for speial ases of printing hardware. Border values are often requlred for laser-printer drivers. Even for laser printers, these fields an usually be left blank. Many of the laser printers are unable to print on all of their page's harater positions. Although these printers allow the ommands to print on these positions, they are unable to atually make any marks on their page's at those loations. These dead z.ones are alon9 one or more of the page's four ed,8es. The size of eah edge s dead zone usually differs from the SlZes of that page's other dead zones. Their values vary among the different brands of laser printers, and even vary among a given brand. It is not unusual, for example, for the first one to three olumns of a laser printer to be unusable. Engineering Update (DAA-170) A C Page 25 of 120

26 Default border values must be supplied as part of eah GPS devie driver. If no border values are entered at devie-driver installation, then all of the driver's default border values are used. For printers that do not have this dead-zone problem (non-laser printers), the default border values should be O. For laser printers, nominal border values for the supported printers should be inluded in the GPS devie driver. If the proper default border values are built into the devie driver, the user will rarely need to enter any border values when installing the driver. Some ',,-./ experimentation with several opies of the given printer is usually required to obtain these values. A GPS devie driver's default border values are stored in the following devie-driver variables: DDwLeftBorder Width of the page's left-edge dead zone (GPS units). DDwRightBorder Width of the page's right-edge dead zone (GPS units). DDwTopBorder Height of the page's top-edge DDwBottomBorder dead zone (GPS units). Height of the page's bottomedge dead zone (GPS units). These devie-driver variables are listed in the GPS DEYICE SPECIFICATION PARAMETERS setion (page 87). The border values affet the Core's Current-page-dimensions alulations. They affet the page's default first-harater position, where auto-line~wrap ours,. where auto-page-ejet ours, auto-sizing of graphis, auto-entering of graphis, et. These printer border values should not be onfused with formatted-douments' margins. Values should nnu be entered into the border fields at devie-driver installation time in an attempt to reate doument margins! Page 26 of 120

27 8.2 Page Orientations Two pa~e orientations are supported by the GPS 2.0 Core. Pageorientation information is passed from the G PS Core to the devie-dependent ode at the beginning of eah page. A given printer mayor may not produe output in the two orientations. Whether or not it does is determined by: 1) Whether or not the printer hardware an print in two orientations. 2) Whether or not page-orientation support has been inluded in the GPS devie driver's devie-dependent ode. Page-orientation definitions: The two page ori~ntations are named: PortraIt Landsape o When a ~age's hei~ht (or len~h) is Keater than its width, then tbat page s orientation is Portrait. ( e painting of a portrait is usually taller than it is wide.) When a page's width is iteater than the paie's heiiht (or length), tben that page's orientation is Landsape. (The painting of a landsape IS usually wider than it is tall.) Desired page orientation may be speified by two means in a GPS 2.0 devie driver. First, a Portrait or Landsape orientation may be requested in the GP AMBeginPage all. The baspet field of the parameters struture may be set to Landsape or Portrait. Seondly, the Current page dimensions may be used to speify the page orientation. If GPAMBeginPage's baspet field is set to default, then the Current page dimensions are evaluated by the GPS Core. If the Current page dimensions have a height greater than their width, Portrait orientation will be requested. If the width is greater, Landsape orientation will be requested. The Current page dimensions are also used to determine page orientation when a doument ontains no GP AMBeginPage speifiations. A baspet value of Landsape or Portrait takes preedene over Current page dimensions and GPAMBeginPage page dimensions. GP AM appliations may use either means of speifying page orientation. The Convergent Doument Designer, for example, does not utilize the baspet field at all. Rather every page of a Page 27 of 120

28 Doument Designer doument has speifi dimensions assoiated with it, and these dimensions are inluded in the GP AMBeginPage alls. So at the beginning of eah page, the GP AMBeginPage page dimensions are used to speify the desired orientation for that page. A GPAM doument may ontain pages of both orientations. This is true beause at the beginning of eah GP AM page, a new page orientation may be requested. This is aomplished through use of either the GP AMBeginPage baspet value or the GP AMBeginPage page dimensions. Only one page orientation will exist in a non-gp AM doument. Sine a non-gp AM doument does not inlude GPAMBeginPage alls, it annot speify page orientation or page-dimensions. Therefore the Installation page-dimensions will be used to selet page orientation, and the page orientation will not hange within the doument. For the same reasons, only one page orientation will exist in GPAM douments that do not inlude GPAMBeginPage alls. Suh default page orientations ma differ for non-g P AM and GPAM douments, however. This IS beause the Chars Per Line value speifies the installation pa~e width for non-gp. AM douments, while ~ (in inhes) speifies it for GPAM douments. The two are generally not the same, and may result in different page orientations being requested. For example, assume that a dnver is installed with the following page dimensions: 1) Width = 8 1 h", Length = 11" and Chars-Per-Line = 132. Assume also that the devie driver's default harater width is 0.1 inh. Then the default Current page-dimensions will differ for the two types of douments. For a GP AM doument the dimensions are 81f2 X 11, whih speifies portrait orientation. For a non-gp AM doument the dimensions are 13.2 X 11, whih speifies landsape orientation ( " = 13.2"). /' DDP's page-orientation responsibilities: A GPS devie driver's devie-dependent ode must: Speify to the G PS Core whether or not this devie driver supports more than one page orientation. Aess the page-orientation information provided by the Core. Issue to the printer the neessary hange-pageorientation ommands. DdDevOrient values speify the devie driver's page-orientation apabilities. Page 28 of 120 Engineering Update (DAA-170)

29 Page-orientation information is passed to the DDP at the beginning of eah page. The following PaieL and PaieP subsetion desribes the one ase in whih the devie-dependent ode is not responsible for generating the printer's hange-page-orientation ommands. DdDevOrient values: A data struture in eah GPS devie driver speifies the pageorientation apabilities of that devie driver. The data struture is DdDevOrient. See the GPS DEVICE-SPECIFICATION PARAMETERS setion (page 92) for the DdDevOrient-struture definition and field values. Multip'le page-orientation proessing will be done by the Core only if the borients field speifies that the devie is apable of outputting in two orientations. If this field is set to one, the Core will never notify the DDP of requests for page-orientation hanges. The devie's default page orientation is speified by the value set in the bderault field. If the driver supports only one page orientation (borients = LI0RIENTATION), the value plaed into the bderault field is irrelevant. Laser printers' page borders (desribed in the previous subsetion) neessitate the bptol field. The Core must alulate the first and last "olumns" that will atually show up on a page. It must also alulate the first and last usable lines. These values are determined by page-border values. When page orientation hanges, these values are realulated. If page orientation hanges from its default orientation, is the new Left Border now the old Top Border or the old Bottom Border? It varies from printer to printer. The value that is set into this bptol field speifies whether it is the old Top Border or the old Bottom Border. The other, needed border-rotation rules are also speified by this field's value. Page 29 or 120

30 A $feat variety of orientation-hange possibilities exist among the vanous devies that support multiple page orientations. Therefore the following should be done to determine the orret value for the bptol field: 1. Set bptol to one of its two valid values. Valid bptol values are 1 and 2. Symbol values defined in DdParams.asm are LMINUS90 and LPLUS Print a non-gp AM doument in the non-default page orientation. (This doument should not begin with spaes.) 3. If any of the first haraters of eah line do not show up on the output page, then set bptol to its other valid value. If the driver supports only one page orientation (borients = LIORIENTATION), the value plaed into the bptol field is irrelevant. If the driver supports a multi-orientation printer that does not have dead-zones on its page's edges, set bptol to either of the two valid values. The flfntdev must always be set to FALSE in a GPS 2.0 devie driver. Page-orientation information passed to DDP: Eah time that a J?age is begun, the GPS Core alls the DDP's DdNewPageG routme. This all inludes a pointer to the new page's Page Desriptor. The Page Desriptor is a struture ontaining information about the new page's dimensions and orientation. It is defined in the GPS DATA STRUCTURES OF INTEREST setion (page 78). The borient field of the struture speifies the page's orientation. I t is the responsibility of the devie-dependent ode to interpret the borient field, and issue the needed orientation-hange ommands to the output devie. Any font-seletion operations that are a funtion of page orientation must be handled by the devie-dependent ode. Printing douments using both portrait and landsape orientations is supported only to the extent that the same printer fonts are available 10 both orientations. Page 30 of 120 Engineering Update (DAA-170)

31 PageL and PageP: The GPS Core does provide an orientation-hange-ommand output faility. It is alled PageLlPageP. Its intended use is for temporary, page-orientation support of new printers. The PageLlPageP feature should be no longer needed after the driver has been updated to support that new printer. PageLlPageP is a GPS-Core feature that outputs hange-pageorientation ommands to the devie. The ommands that is sends to the printer are speified by the user at devie-driver installation. PageLlPageP is relevant only if the DDP speifies that it supports both page orientations. Two different page-orientation ommand strings may be entered into Print Manager's devie-driver installation form. One is the ommand whih auses the devie to swith to landsape orientation -- this string is alled the PageL string. The other is the ommand whih auses the devie to swith to portrait orientation -- it is alled the PageP string. A PageL string is speified by typing PageL:<hex-string> into the DEVICE SETUP field of Print Manager's devie-installation form. A PageP string is speified by typing PageP:<hex-string> into that field. <hex-string> is the ommand string that is to be sent to the output devie. The PageL string is output to the devie, DY the GPS Core, after alling DdNewPageG if all of the following are true: 1. A PageL string was speified at devie-driver installation. 2. The new page's orientation is landsape. 3. Both page orientations are supported by the devie driver. The PageP string is output to the devie, by the GPS Core, after alling DdNewPageG if all of the following are true: 1. A PageP string was speified at devie-driver installation. 2. The new page's orientation is portrait. 3. Both page orientations are supported by the devie driver. Page 31 of 120

32 It is not reommended that the PageLlPageP faility be onsidered as a permanent solution to any devie-support requirement.. A better approah is to have a list of devie names that are reognized by the devie-dependent ode. The user enters one of these names into the DEVICE SETUP field of Print Manager's devie-installation form when installing the devie driver. The DDP uses this information to selet the devie ommands that it should, itself, output when DdNewPageG is alled. This approah is less error prone, is easier for the user, and enables the deviedependent ode to selet the appropriate set of devie-dependent ommands. Another example of the use of PageL and PageP strings is in the Convergent-supplied Daisy devie driver. The goal was to make it likely that many of the laser "daisy emulators" would work with Convergent's driver, and that the page-orientation apabilities of these daisy emulators ould be used. This was aomplished by speifying that the Daisy driver supports both page orientations (DdDevOrient.bOrients = L20RIENTATIONS), and by utilizing the PageL/PageP faility. If a user speifies PageL and PageP strings when installing the Convergent-supplied Daisy devie driver, the appropriate ommand string will be output (by the Core) to the attahed printer eah time that page onentation hanges. If suh a laser printer was to be used regularly with the Daisy driver, PrintGen should be used to reate a new version of the devie driver. This new version would reognize a new devie name that represents this laser daisy emulator Uust as it urrently reognizes names that represent the Diabl0630, Qume, et.) Ourrene of this new devie name would signal the deviedependent ode to output the required hange-orientation ommands when its DdNewPageG is alled by the Core. Page 32 of 120 Engineering Update (DAA-170)

33 9.0 DEVICE-DEPENDENT FUNCTIONS ' This setion lists the funtions that must be provided by the DDP's devie-dependent ode. These proedures are alled by the GPS devie-dnver Core to pass haraters to the DDP, pass graphis objets to the DDP, begin and end douments, begin and end pages, et. Not all of these funtions must always be implemented. The proedure speifiations in this setion are divided into two groups: ALWAYS REQUIRED, REQUIRED ONLY FOR GRAPHICS PROCESSING. Eah proedure's speifiation onsists of: 1) A proedure delaration. 2) 3) This delaration inludes the name of the proedure; the proedure's parameters; and type of value (if any) returned by the proedure. PLM syntax is used for the proedure delarations. If a proedure expets parameters, they are enlosed in parentheses. If a data-type is assigned to the proedure, then the proedure is alled as a funtion and returns a value of the speified data-type. Most of the required devie-dependent proedures are alled as funtions, and most of these funtions return an error ode. This is a one-word value. It is equal to zero for no error, or equal to a CTOS, GPS or user-define d error ode. Error odes to may be used by GPS devie-driver writers. Desription of the funtion to be performed by the proedure. Desription of eah input parameter. For eah input parameter, its use and data-type. are desribed. Please note that some input parameters are used to speify where the proedure's output data is to be plaed. Engineering Update (DAA-170) A C Page 33 of 120