The following article was printed in October 1988 of the magazine „8000 PLUS".
GSX routines in BASIC programs
GSXPLORATION
DIY graphics in BASIC for free! Charles Pulteney unravels some of the mysteries of GSX in the first of two features
It seems GSX has earned a reputation for being complicated to use. Well don't believe a word of it. This article provides you with a gentle introduction to GSX, a nuts and bolts utility which will enable you to use most of the PCW's graphical facilities (concentrating on printed output), and some example programs. The only technical skill required is the ability to plot points in relation to X and Y axes, a bit like the grid references on an Ordnance Survey map. You'll have to be reasonably familiar with BASIC too.
GSX stands for Graphical Systems Extension and is a piece of software supplied free with all PCWs. The only problem is knowing how to use it, as documentation is almost non-existent.
Yet Mallard BASIC can be used to call the facilities available in the PCW version of GSX. Although the screen output of the PCW version of GSX isn't so good, the printer output (for dot-matrix printers only) is really impressive and is capable of producing high quality graphs, bar charts, pie charts, sketches and letter headings.
First of all you need to set up a GSX start of day disc for Drive A. Using PIP.COM, copy the following files from the relevant system discs on to one side of a blank formatted disc. See the margin note overleaf if you want help. J14CPM3.EMS (the number may be slightly different, eg on a 9512 it is J21CPM3.EMS - check by taking a directory with DIR); BASIC.COM; DDHP7470.PRL; DDFXLR8.PRL; GENGRAF.COM; DDSCREEN.PRL; ASSIGN.SYS; DDFXHR8.PRL; and GSX.SYS are needed.
You now need to alter BASIC so that the GSX system is installed in memory when BASIC is run. This is done by typing GENGRAF BASIC. The GENGRAF copyright sign will appear and after a while the A> prompt will return. To avoid confusion with ordinary BASIC, rename this GSX version by typing REM GBASIC.COM=BASIC.COM.
You can erase GENGRAF.COM, as the file is no longer required. Your startup disc now has all the files you need to run GSX. In future, if you place the disc into Drive A after switching on your PCW, CP/M will load automatically. If you now type GBASIC you should see the GSX-80 copyright sign followed by the one for Mallard-80. Note that there are only 17k free bytes, ie. less than normal.
First you need a framework letting you use GSX facilities from your own programs. Type the utility program listed overleaf in and save it with SAVE "UTILITY.GSX".
The utility does not draw anything. To produce output you need to write another program starting at line 10000, and merge it with UTILITY.GSX. The utility simply sets GSX up to draw your picture on the screen or printer. You can put GOSUBS into your program which use the functions provided by the utility - they're summarised overleaf.
For example, if your main program has a line like GOSUB 2000 and has just set variables x1 to 5, y1 to 55, x2 to 80 and y2 to 80, you'll get a rectangle whose lower left corner is at 5 on the x-axis and 55 on the y-axis, and whose top right comer is at 80 on the x- and y-axes.
On this page is an example of a listing using some of the functions. Type the listing below, save it with SAVE LISTING2.GSX and when finished MERGE UTILITY.GSX. The utility you typed earlier will be tacked on and you can use the functions of the utility. If you now RUN you should be presented by a three choice menu. If you made errors while typing the first utility, they will be picked up by the ON ERROR GOTO sub-routine (if this should happen make the relevant amendments and type: SAVE "UTILITY.GSX" and run the program again). Select 1 (Screen Output). You should see the box, the text, the polygon and the markers being drawn on the screen.
Line 10010 draws a hollow rectangular box whose lower left co-ordinate is 5, 55 and whose upper right co-ordinate is 80,80.
Line 10020 draws a line ff text with the base of the first character at 40, 45.
Lines 10030-10080 draw an eight sided polygon with a vertical hatch fill (which you will not be able to see on the screen). There are two points to notice here. Use of the RESTOR/READ/DATA commands is the simplest way to enter a large number of co-ordinate values.
In line 10080, the first two items are the co-ordinates for x1, y1 , the next pair x2, y2, and so on. The polygon GOSUB is Ihe only one in which the data is ascribed directly to the pts.in% array. Note also that when using the polygon GOSUB, the final co-ordinate must he the same as the first one. In other words, you must finish where you started! It is for this reason that in this case the number of points (np%) is 9 and not 8. The RESTORE/READ/DATA commands can also be used to simplify data entry for the other GOSUBS.

Lines 10090-10110 draw 8 markers on the screen at the co-ordinates specified in line 10110.
[BASIC listing]

BASIC

Help note
To copy those files: run CP/M and at the A> prompt type PIP [RETURN]. At line asterisk type M:=A:BASIC.COM [RETURN] ana so on for each lite in the list. Insert your blank formatted disc and type A:=M:*.* [RETURN]. 8256 owners must copy the files in two stages as there is not enough room in Drive M to hold them all. For 8256 or 8512 users insert the appropriate side of the systems discs before copying. J14CPM3.EMS and BASIC.COM are on side 2, DDHP7470.PRL on side 3 and the rest on 4.
It is easy to build up a picture in this way. However, before experimenting further you need to know how to place your output exactly where you want it. GSX uses a co-ordinate system for its X and Y axes which is based on a range of 0 to 32767. This wide range makes it difficult to know exactly where output will appear when a drawing is sent to the printer or screen. The utility takes this problem into account, by scaling the X and Y axes to more sensible dimensions. Listing 3 produces a sheet of graph paper based on these dimensions which will simplify the planning of your drawings.
Notes 1
The order in which you place your statements in relation to their final position on the paper is not important. GSX will process your instructions in the correct order.
Also, the screen does not display fill characteristics, while only one text size, text direction and polymarker size are shown. The first 5 polyline styles will be drawn. Locomotive Software sell an improved screen driver which displays fills.
Notes 2
Most of the output in draft and high quality modes is similar. The two exceptions are character height and marker size (for draft, double the sze% and hgt% values in the opposite table). Draft quality is most useful tor checking that the right fill patterns have been selected.

BASIC

Notes 3
It is best to keep text and drawings away from the edges of the available space.
Also, the variables controlling text height, text direction, fill etc. are always returned to the default settings whenever they are used. You therefore need to reset these values whenever you want to reuse a function.
[BASIC listing]
[The machine code in lines 9010-9030 is: LD D,B ! LD E,C ! LD C,73 ! JP 0005]

Type NEW then type in the following listing followed by the commands SAVE "GRAPHPAP.GSX" and MERGE "UTILITY.GSX".
Type RUN then select 1 (Screen Output). You should see the graph paper being drawn a little unevenly on the screen (it will look better on printout than on screen, remember). The X and Y axes will be labelled. Again, any errors in your typing will interrupt the program. It everything is correct, exit by pressing any key. Type RUN again, and select 3 (High Quality Output). After a short delay you will be prompted to load the printer with paper (make sure that the paper lies between the points marked and 80 on the bail bar)
What you can do
GOSUB  FUNCTION              OPTIONS               VARIABLES
1000   Draw polygon          Number of points      np%=number of points (and fill)
       Fill polygon                                fill%=1 for Fill or 0 for Hollow
                             Fill styles(4)        sty%=0 (hollow),sty%=1 (black)
                                                   sty%=2 (grey scale),sty%=3 (hatch)
                             Style index           only relevant when sty%=2 or 3
                             6 gradations          idx%=1,or 2,or 3,or 4,or 5,or 6
2000   Draw rectangular box                        x1,y1=lower left co-ordinate
       (and fill)                                  x2,y2=upper right co-ordinate
                             Fill rectangular box  as above for fill%,sty%,and idx%
3000   Place text at x1,y1                         x1,y1=co-ordinate at which base of
                                                   first character is printed mes$="Text"
                             Character sizes(12)   hgt%=1,400,600,800,1000,1200,
                                                   1400,1600,1800,2000,2200,or 2400
                             Text directions(4)    dir%=0,or 90,or 180,or 270
4000   Drawline between                            x1,y1=first co-ordinate
       two points                                  x2, y2=second co-ordinate
                             line styles(6)        psty%=1,2,3,4,5,or 6
5000   Plot marker for line                        x1,y1=co-ordinate
                             marker types(5)       tpe%=1,2,3,4,or 5 
                             marker sizes(12)      sze%(as for text character sizes)
Notes 4
GSX expects to find the drivers (the .PRL files) on every disc. This waste of space can be avoided by changing the ASSIGN.SYS file. Using RPED, replace each @ with M. GSX will then expect to find these files on Drive M, so be sure to copy them there from your startup disc first. If you have no plotter remove the reference to DDHP7470.PRL in ASSIGN.SYS and delete this PRL file from your disc.
Unless you reset the PCW, it is impossible to stop the printer once output has been sent to it!
[BASIC listing]
 The GRAPHPAP.GSX listing. When tacked on to UTILITY.GSX this will produce graph paper which you can use to plan out your graphics.

HTML customization by Werner Cirsovius
February 2015
© 8000 PLUS