@L}5 _$% l0$)$$Hȱ$ UhL" `e$$%`$%`  R@P!( L(1   Y I`  d  Ld M * @  $ % CC$$)%1 Udߥ$9%: !0 S$% DD˙`  }J)Lr d M * @  $ % CC$$)%1 Udߥ$9%: !0 S$%} DD˙`  }J)Lr J  ((  p L ()   J}L= ( L 0q A    IB JC;? D W } LL  ` W )LA!  ߰")-݆ p" } $G@LL 08`Q")<2Q0 -G$Ș݆ UL# ; p8(()(0ʥ)NQ` }$GȘ݆LU )L ݆ L GȘ ݆LL )W>Z   HH)H }p h  hyhy D L> L JJ    ! LA*` BF }7'8  M HN H` 8 Z  \LdJJ!"! GFE@F (!L }EE !E^ ^ E E7EȩEdE/EȩE  D } .L }  ;F d  ;?F7F? ( .   Z D LL d } . D  L    p  E` , d)  D L) 0BM݊L݉} ML  N݆ L NLML [ TEqEHȱEqEh 0Gȹ G} HLL GɛL  LFREE SECTORS G) *Gȩ GȽG GȌ*jj >G} C8jJ3j2CD( C202C ԠBX` N 1? l LlD:RAMDISK}.COMLu L1 L ;LHL  T`  `1  ɐ     `TU  } L ? .  t`GBJ ~DEHI B V0dV!}QDEHI VF9 ,0 ,0 s0hhL  L` H hDHEh"}DEL8HI4 0 HI,0 0  9 .G VLO#},0 L4*IJ`llD1:AUTORUN.SYSNEED MEM.SAV TO LOAD THIS FILE.D1:MEM.SAV J y08 B|DEHI$} V0 0`B;DEL`?<0LV`@ʆ v s? F0Ξ05: [ BDEHI%} VY8 B V  @  /DE `E:D1:DUP.SYSERROR-SAVING USER MEMORY ON DISKTYPE Y TO &}STILL RUN DOS B;DE J  (` 9 V⪍ ઍ  -'}LLu ÝDEHILV 9 .l 9 .l  `` s$B BH(}I|DE V BLV nB,DE JLV B V BLVDEIʩ BꭝLu } 3E:}DISK OPERATING SYSTEM II VERSION 2.5 COPYRIGHT 1984 ATARI CORP.A. DISK DIRECTORY I. FORMAT DISKB. RUN CARTRIDG*}E J. DUPLICATE DISKC. COPY FILE K. BINARY SAVED. DELETE FILE(S) L. BINARY LOADE. RENAME FILE M. RUN AT ADDRES+}SF. LOCK FILE N. CREATE MEM.SAVG. UNLOCK FILE O. DUPLICATE FILEH. WRITE DOS FILES P. FORMAT SINGLEL !N',}#"&))9(&*)/h)''-&؆莟R'S  vL/ˢ L }Insert DOS 2.5s, type Y Λx -}DEfHI 1莏#q! @ y0ɛ8A0,' ȅ 1 1ild! 1L!NO SUCH ITEMSELECT.} ITEM OR FOR MENU! 0 .z:*{}.|{ 1 0 0JB 18L%|DL/}%DIRECTORY--SEARCH SPEC,LIST FILE?[# 0 0 &|D3" 1L!NOT A DISK FILEN !B 1L!E# 1 !BD0}ED:}:1BJ|DE 1DEBHI 1 h0ߢ 0.1}  0?詛 1 y0YЛ 1 ;#L" ;#L! BL1TYPE "Y" TO DELETE...DELETE FILE SPEC2}COPY--FROM, TO?OPTION NOT ALLOWED377 FREE SECTORS COPYING---D2:JT.PICCOMl# 0|D .L/%#3}##JB|DE 1BHID#E 1#0: B 1L!#͑### B 1#c$0SY4}S1}:## # # .#Ƚ# # 𩛙## 1,#PD#ELJ- <.BJD#E 5}1 1HH 0hh|DL%1}:̳# L% #D#EL% 1 0 . .0O% 1L!WILD CARDS NOT A6}LLOWED IN DESTINATION 0 <.|K}N 2 FORMAT. t* 5) 1L!`) 0NΞ 0 L1) 1 L!BAD LOAD FILELOAD FROM WHAT FILE?) 0 ?}0#B 1L!WHAT FILE TO LOCK?) 0 0$B 1L!WHAT FILE TO UNLOCK?DUP DISK-SOURCE,DEST DRIVES?TYPE "Y" IF OK TO US@}E PROGRAM AREACAUTION: A "Y" INVALIDATES MEM.SAV.FE! +L1   `*  70 2 2A} 0.* 1 y0 0)INSERT BOTH DISKS, TYPE RETURN^, 1 y038逍 N, 1L! ,B}C, t*  Lx+, 0 ^, 1 y0 , ,0,0 ,L+ ,I0 ,Vǭ0C}Ξ, 0 }, 1 y0C,ШC, 0K'!" H H 'h h Lx+!EF 5L1L!D,I,HhD}` NOT ENOUGH ROOMINSERT SOURCE DISK,TYPE RETURNINSERT DESTINATION DISK,TYPE RETURNE}`  `8 rL1`-* 1P* 1 y0Y`hhL!NAME OF FILE TO MOVE?- 0 0|DL% <.F},^ 1 70 0 .@L# .BJ 1  DEHIB V L1 ,} 1 70,L.  G}JB|,#P#DE 1 HI BDEHHII 1 B 1 ,^ 1 70,0La- B V,#PH},^ 1 70 0L#L!-* 1P* 1 y0Yj383}mm ݭI}}`8}``|* ? ɛ,`|:-)| / 1L!`DESTINATION CANT BE DOJ}S.SYS0 0H{ 24Δ 28/L!/) 2 Π 2 0 ξK}hAΞB,0 J 1 BDEHI,HÝDE 1HIHIDELSAVE-GIVE L}FILE,START,END(,INIT,RUN)O S0 1`BDEPHI V` S0H 1 L!M}0 0 1L~0`PLEASE TYPE 1 LETTER,0`hhL! 70 1L0L<1 ,;ɛ7,"ɛ:ݦ1ݥN}A"D|ݤD|ȩ:|ȩ|ɛ,,(/+.ީ1 1,ɛ`轤{NAMEO} TOO LONG B VL!` L1I H1EΝDL1|mDiE` V0`8d/8 i:222 1 LP}!ERROR- 144ɛ+,' 20*.. өr2 1``2TOO MANY DIGITSINVALID HEXAQ}DECIMAL PARAMETER800 0 8 00`,0'D800 H,ɛh`2L1NEED D1 THRU D8uR} ECIMAL PARAMETER800 0 8 00`,0'D800 H,ɛh`2L1NEED D1 THRU D8uX X!XAXBXEXp~FXIX0@JXMXBXDXNXNXOXOXPXPXQXQXZSXXT} !#%(*,.02468:<>@BDFHIKMOQRTVWYZ\^_abcefhijkmnopqrstuvwwxyzz{||}}~~~Y"Y TYPE A KEY TYPE A KEYU} $Y+YpVY0-Y3Y0VYA$Y6Y6Y 7YY^ŗ4Ŗ,*Oȥȥ eem6YV}eƒЫe揦`YYe`YY`YYȩ-ȩY`YY*Y+Y`YY"/W}`ZZZZZ.ZHZЭYL+ZYЭYЭZh@1Z1Z2Z2Z3ZZMNX)NXi iNX1Z"&YZZԩX}/Y2Z2Z61Z/Z&YZԬZ/YZ/Y1Zl/Z`ZZPXIZPX JXKXZ JXKX`Z[OX Y}POXTOXQXSXZZ8QXZSXZ8ZZJZ*ZPX FXGXZ Y YZ 7Y YZ FXGXZ 7YZ}ZmZ Y Y YQXJJJJZZJJJJZH)8ZZh) ZYH)8ZZh) ZY`[[Z8RXQX ZQX8RX[} QX`ZPX ZZQX Z`[\ZPX ZRXQX ZQXZ mRXQX`"\B\$/Z%0Z@ԩ \!\ \䦆`C\e\3 \Z!\\} "\Z`m\\!/ 6Y Z Z0f\1g\$0Y1`\\ m\\\!X\iRXX\ [L]}\ [L\\i2`\]h\#Y8 Y C\`]P]/Z \0Z!\ "\ Yf\0g\1^}Ԡh\`Q]\] \ \ ]`@O_}`}a}b}c}??B?BB?B?B?B?BBBBBB~~~~~~Bd}BBBBB??B?BB?B?B?B?e}f}g}B?B?B?B?B??B?BBBBBBBB~~~~~~h}~BBBBBBBB?B?B?B?B??B?Bi}j}k}??B?BBB?B?B?BBBBBB~~~l}~~~BBBBBB??B?BBB?B?B?m}n}o}B?B?B?B?B??B?BBBBBBBB~p}~~~~~~BBBBBBBB?B?B?B?B??B?Bq}r}s}???BB?B?B?B?BBBBt}B~~~~~BBBBB???BB?B?B?B?u}v}w}B?B?B?B?B?B?B?BBBBx}BBBBB~~~~~~~~BBBBBBBBB?B?B?B?B?B?B?By}z}{}?B?B?B?B?B?B?B?|}BBBBBBB~~~~~~~BBBBBBB?B?B?B?B?B?B?B?}}~}}0?}<<333g111c1}11c111c111g11 1}X1_1g111c111c111c}331c1c}?01c1g3c1c1c1c1c1?c@1c1?}cb1cw1Ǐcv0@9` @9` @9` @}@8p03a@8|p?^@@}@@@@}@@@@}@@@`0 0@}`0 !0@?n0 !;px0@1p 31s0" fc0@9pha0" l3 0@}9la0R 3 0@9ga0T 3 0@9ca0T 3 0@9`6a0T 3 0@}9ha 0 3 0@g1pF #aa c0@?p<?p|@}@@@@}@@@}@gOǀ@B $$$!H@@B $$!H@C$O}@B '!H@@B@ $!H@@B $D$!@@B$#'}ǀ@P]Q]}EiͩkΩ͙kCopj`j {j`Hi͝Νh`L"SAB.}ORTNI:D"NUR  U +@@1AR@C@@dUB7t@dQ(N(C } SCREENS by Joseph J. WrobelQ(..(& Screens is an excellent utility that#..(&will al }low you to define areas of the(..(&screen as independent 'windows' and-..(&then input and output to these windows2 }..(&without effecting the rest of the7..(&display. Mix text with graphics with<..(&ease and without a PhD in p }rogramming.A1(1(& This side of the disk contains a fullF..(&manual which is formatted in 40 columnK..(&and will pr }int from DOS using option CP""(and P: as the destination.QOO(GTo print the manual in 80 column goto BASIC from DOS an }d RUN D:SMANPRTU1(1(& The other side of this disk containsV..(&the program and demo files. Boot withW..(&BASIC a }nd after the utility has loadedX**("run DEMO to see SCREENS in action.ZZ(*( Ӡ٠٠ϠϠϠJ@}} SCREENS by Joseph J. Wrobel Copyright 1986 Reference ManualForewordUtiliti}es are to programmers as toolsare to craftsmen. They are not anend, but a means to an end. They donot create, but aid in t}he process ofcreation. "SCREENS" is a utility.When it loads into your computer, itdoesn't "do" anything but increaseyour }potential. Novice programmerswill find it eases the implementationof some tasks which would be ratherdifficult to accompli}sh otherwise(like freely mixing text withgraphics or restricting user inputfields). Advanced programmers willfind it prov}ides an easy route toprofessional looking software via thedefinition of multiple independentvirtual screens. [For an examp}le ofsome of "SCREENS" capabilities, bootup your system using the "SCREENS"diskette (refer to the "Loading theprogram" se}ction below), then loadand run the BASIC program entitled"DEMO".]It is the purpose of this manual toacquaint the novice }and the advancedprogrammer alike with thecapabilities and uses of "SCREENS".The approach taken in Section 1 is tointroduc}e the features in a logicalorder, with simple programmingexamples accompanying theintroduction of each new feature.Sectio}n 2 is a concise review of"SCREENS" commands to be used as areference section once the user hasbecome familiar with the va}riousfunctions. Section 3 gets more intothe fundamental operation of"SCREENS" and is primarily intendedfor the inquisitiv}e advancedprogrammer.Before we get started, the authorwishes to emphasize his strong desireto make "SCREENS" not only a }usefulutility but also a "used" utility.Any suggestions for improvement inthe program or this manual are mostwelcome. Fur}ther, the author iswilling to discuss any modificationor software development which may berequired for a specific commerci}alapplication of "SCREENS"."SCREENS" requires an ATARI 400, 800,XL or XE computer with a minimum of32 kilobytes of memor}y and acompatible disk drive.The source code for "SCREENS" wasedited and assembled using theSynAssembler (copyright Syna}pseSoftware) on a 48kB ATARI 800computer system. This manual wascomposed on an ATARI 520ST usingSTWriter Elite (copyright} Atari,Inc.). ATARI is a trademark of Atari,Inc. Table of contents Tutorial Overview Loading the pro}gram Initial conditions Opening a window Window parameters Printing to a window Inputting from a window } Changing the parameters Acceptable parameter values Additional NOTE/POINT functions Other XIO commands Han}dler errors Reference Details Introduction Program installation Memory usage OS variables used Appen}dix A - Window image format Appendix B - Expanded font format Appendix C - Useful tables TutorialOver}viewEach of the multiplicity of standarddisplay modes on ATARI computersconsist of columns and rows ofpixels; pixels are} the smallestdiscretely addressable pictureelements in the display. The numberof columns and rows and the size andnature }of the pixels vary from modeto mode. For example, in GRAPHICS 24the display consists of 320 columnsand 192 rows of fine pi}xels which caneither be on or off. In GRAPHICS 0,the display consists of 40 columnsand 24 rows of pixels which actuallyco}mprise characters for this displaymode.One consistency across all the ATARIdisplay modes is the co-ordinatesystem used t}o locate a pixel on thedisplay. The ATARI system designatesthe leftmost pixel column of thedisplay as column 0 and the top}mostpixel row as row 0. Pixel positionsare then referenced to this origin.Thus, a pixel which is in the tenthcolumn from }the left and the fifthrow from the top is in column 9, row4.What "SCREENS" allows you to do is todesignate an arbitrary }rectangulararea in a display as an independentscreen, or window, and to output toor input from that window withouteffecti}ng the rest of the display.The way you designate the area of thedisplay the window is to occupy is tospecify (1) the colum}n and row pixelposition in standard co-ordinates ofthe window's upper left corner and(2) the number of columns and rowsth}e window is to contain.Position and size are just two of thecharacteristics you are able tospecify for each window. We'll}discuss the others later. But itbrings up the question of how youcommunicate such information to thesystem. The ATARI ope}rating systemsupports such communication throughits Central Input Output (CIO)protocol. To take advantage of thisprotocol}, "SCREENS" installs a devicecalled "W:". This device handles allthe functions supported by "SCREENS"including defining a }window, writingto it, reading from it and all thespecial functions to be describedlater.ATARI BASIC provides a number of}commands which allow the programmerto interface with CIO. These includeOPEN, CLOSE, GET, PUT, INPUT, PRINT,ENTER, LIST, N}OTE, POINT, STATUS andXIO. Each of these functions can beused with device "W:". In thediscussion which follows, these BASI}Ccommands will be used in exampleswhich demonstrate "SCREENS" features,as it is assumed that the reader hasfamiliarity wi}th ATARI BASIC. Ofcourse, any language which uses theCIO protocol can communicate with"W:" in an analogous fashion. Thede}tails of this communication arediscussed in Section 3.Loading the programTurn on your disk drive. When thebusy light ex}tinguishes, insert the"SCREENS" program diskette in thedrive (label up and towards you) andclose the door. Turn the comput}erpower switch on (non-XL models shouldhave the BASIC cartridge installed).The ATARI disk operating system (DOS)and "SCRE}ENS" will both autoload.When the autoload is complete, theprogram name will be displayed alongwith the version number; bel}ow it thecopyright notice and the READY promptwill appear."SCREENS" supports the use of theATARI 850 Interface; if you w}ish the"R:" handler to be installed atpower-up, turn on the 850 Interfacebefore you power up your computer. Itwill auto-l}oad along with DOS and"SCREENS"."SCREENS" exists on your programdiskette as a file named AUTORUN.SYS.Neither the diskett}e nor the file arecopy-protected. To transfer theAUTORUN.SYS file to another diskette,follow the DOS instructions for file}copying. On any ATARI DOS diskette towhich the "SCREENS" AUTORUN.SYS fileis copied, it is a wise precaution toalso create} a MEM.SAV file. Withoutit, a DOS call from BASIC willcorrupt the "W:" device handler.Some DOSs do not support theimmedi}ate loading and execution ofAUTORUN.SYS files on power-up. Forthese DOSs, follow the instructionsfor loading machine langu}age files.Initial conditionsOnce "SCREENS" has auto-loaded, the"W:" device handler is installed. Itwill neither interfe}re with normalsystem operation nor be lost onSYSTEM RESET. The only noticeablesystem difference (other than theexistence }of "W:") is a 3311 bytedecrease in free RAM. It is in this"stolen" RAM that the "W:" devicehandler resides.Opening a win}dowBefore you can use a window, it mustfirst be opened. This is done,logically enough, using the OPENstatement. The form}at of the OPENstatement for device "W:" is OPEN #iocb_no,io_type,reset_flag, device_idwhere iocb_no is an integer fro}m 1 to8 which specifies the input-outputcontrol block used to communicatewith the device being opened, io_typeis an integ}er which specifies thedirection of data flow (4=input,8=output and 12=both), reset_flag isan integer which, if non-zero, c}ausesthe parameters of the opened deviceto be reset and device_id is a stringconstant or variable of the form"W#:" where }# specifies a unit numberfrom 1 through 9 ("W:" defaults to"W1:").That's a lot of words, which maybecome easier to under}stand if we usean example. Let's interpret the OPENstatement: OPEN #3,8,0,"W6:"What it says is 'assign unit 6 ofdevice }"W:" to IOCB 3 for output anddon't reset that unit's currentparameters'.If we wanted the parameters reset, wecould chang}e the statement to read OPEN #3,8,1,"W6:"If we further wanted to OPEN thedevice for both input and output, wewould use } OPEN #3,12,1,"W6:"We could also use variables in thestatement. For example, IOCB=3:IOTYPE=12:RESET=1:A$="W6:" OPEN #IO}CB,IOTYPE,RESET,A$is equivalent to the OPEN statementin the previous paragraph which usedonly constants.To close a windo}w, one issues theCLOSE command. The format for thiscommand is simply CLOSE #iocb_nowhere iocb_no is the same number used}for opening the window. The result ofthe CLOSE command is to close off thepreviously opened CIO channel forcommunication }to the window and freeup that channel for other use.Neither the display nor the windowstate is altered by the CLOSEcomman}d.As noted above, device "W:" supportsunits one through nine. This meansthat up to nine independent windowscan be define}d at any one time. Eachwill have its own set of parameters.The windows can be defined to overlapon the display. If they do} so, thenwhat happens in one may effect what'sdisplayed in the other. If you wishto overlay windows in your program,you h}ave to be mindful of possibleinteraction. "SCREENS" provides a wayfor you to save individual windowsand recall them back t}o the display.We'll describe that process later.Window parametersRight now let's discuss theparameters which the user g}ets to setfor each window. There are fifteenaltogether. Four have to do withwindow placement. Two determinewindow positio}n; the user sets thepixel position (column and row) ofthe upper left corner of the window.Two determine window size; the u}sersets width and height of the windowin pixels.Seven parameters deal with thedisplay of text in the window. Two ofthes}e determine character placement;the user sets the row and columnoffset in pixels from the upper leftcorner of the window t}o the upperleft corner of the character cell ofthe next character to be displayed.These two parameters allow you topositi}on text randomly inside thewindow. Two parameters determinecharacter size; the user sets theheight and width of the charac}tercell in pixels. The character cell isthe size of the box on the displayset aside for each character.The three other p}arameters having todo with text display are as follows.One parameter is the base address ofthe character set to be used. T}hisparameter can be changed to takeadvantage of user-defined charactersets. One parameter is a flag whichtells the device} whether the selectedcharacter set is defined as an 8 by 8matrix (like the standard ROMcharacter set) or whether it is as}pecially designed 16 by 16 higherresolution set ("SOFT.SET", anexample of a 16 by 16 font, is onyour "SCREENS" diskette). }Oneparameter sets the color to be usedto display the character; it isanalogous to the BASIC COLORparameter but applies on}ly to textprinted in the window.The four remaining parameters do avariety of useful things. Oneparameter is the ASCII va}lue of thecharacter to be used as the cursorwhen receiving input from a window;the cursor can also be turned off.One para}meter sets the logic to beused when displaying a character; youhave the choice of AND, EOR, OR oroverwrite. This effects t}he way acharacter is printed atop informationwhich may already exist on thedisplay. One parameter locks thewindow to prev}ent it from clearing orscrolling. Finally, one parameter isthe value of np_index; the use ofthis parameter will be discuss}edlater.When the user specifies that thewindow parameters be reset when awindow is opened, the parameters takeon the fo}llowing values. The upperleft corner of the window is set tothe upper left corner of the display.The window size is set to } the maximumwindow size (320 by 192). Thecharacter cell is placed in the upperleft corner of the window and sizedto 8 by  }8. The base address of thecharacter set is set to that of theROM set, and the character size flagis zeroed indicating an 8 } by 8matrix. The character color is set to255, which is interpreted as COLOR 1in a two-color mode, COLOR 3 in afour color } mode, and so on. The inputcursor is an inverse space, thedisplay logic is overwrite, thewindow is unlocked and np_index i }szero.Printing to a windowLet's write a little program to seewhat all of this means. We'll usegraphics mode 8 as our d}isplay modeand write "HELLO" to the graphicsdisplay. 10 GRAPHICS 8 20 OPEN #1,8,1,"W:" 80 PRINT #1;"HELLO" 150 C}LOSE #1 160 ENDIf you run this program with"SCREENS" installed, you will findthat, as advertised, the word "HELLO"show}s up in the upper left handcorner of the display. Note that thetext looks just like standard ATARItext because we are usin}g the ROMcharacter set and printing into an 8by 8 character cell, the same as isused in the GRAPHICS 0 text mode.You sho}uld have expected the "H" toshow up where it did on the display.As was stated, when the parametersare reset, the window an}d thecharacter cell are placed in theupper left corner of the display. Butwhat about the rest of "HELLO"? Notethat each }character is positioned onecharacter cell width to the right ofthe preceding characterautomatically. That is, theparamete}rs which specify characterplacement are automatically adjustedafter each character is displayed topoint to the next charac}ter cell tobe filled.Add two lines to our sample programby typing 60 FOR X=1 TO 2 90 NEXT Xpressing RETURN after e}ach line. Nowrun the program again. Note that thesecond "HELLO" prints right below thefirst. "W:" treats the end-of-linec}haracter generated at the end of thefirst PRINT statement just like thetext editor does in GRAPHICS 0; itpositions the nex}t character at thebeginning of the next line on thedisplay. The only other characterwhich has a special effect on thewind}ow is the clear displaycharacter, ASCII 125. If the windowis not locked, sending this characterto a window will cause the }window toclear and the character position tobe set to the upper left corner ofthe window.Add another line to our sample}program by typing 70 PUT #1,125and pressing RETURN. Now run theprogram again. Note that the windowcleared between print}ing the firstand second "HELLO" and that thesecond "HELLO" printed at the topleft corner of the display.Now type LIST "W}:" and press RETURN.Note that the program is listed onthe display right below the "HELLO".Why does this happen? Well, whe}nBASIC lists a program to a device, itfirst opens it. This process does notreset "W:". Hence the "W:" devicehandler remem }bers where the nextcharacter was to be placed andcontinues on from there.List the program to "W:" a few moretimes. What !}happens when the textreaches the bottom of the graphicsdisplay? Scrolling! Logic is builtin to "W:" which scrolls the te"}xt inthe window whenever you attempt toprint beyond the bottom of thewindow. As noted above, this can beoverridden by loc#}king the window incase scrolling is not desired.Now let's modify our program a bit.Type 10 GRAPHICS 7and press RETURN$}. Now run the programagain. Note that the character cellsize is still 8 by 8 and thecharacters themselves are still fromt%}he standard ATARI set, but now theyare bigger and in color. Thedifference is due to the differencein pixel size and type b&}etweengraphic modes 7 and 8.List the program to "W:" twice andwatch the window scroll. Note thatagain it does so when th'}e textreaches the bottom of the graphicsdisplay. Because of the coarserresolution of graphics mode 7,however, less lines (}are printedbefore scrolling must occur. But "W:"knew that and scrolled when it hadto! That's because "W:" checks itssize)} and position relative to thecurrent graphics mode every time acharacter is printed. If the graphicsmode is changed betwee*}n characterssuch that the boundaries of thewindow now exceed the boundaries ofthe display, the window is re-sizedautomati+}cally. Thus, although westarted out by resetting the windowsize to 320 columns by 192 rows, justbefore the first character,} wasdisplayed (the "H" from "HELLO) thewindow was re-sized to fit ingraphics mode 7, i.e. to 160 columnsby 80 rows.What -}happens now if we switch back toGRAPHICS 8? Let's find out. Type GRAPHICS 8and press RETURN. Now list theprogram to "W:.}" a few times. Notethat "W:" retains the smaller windowsize that it was forced into whileprinting to the graphics 7 displa/}y.One further feature of the textoutput function of "W:" is that itresponds to the control-1 protocol,i.e. text display 0}is interrupted ifthe "1" key is pressed while theCONTROL key is depressed and thencontinues when this process isrepeated.1} List the program to "W:"again and try it out.Inputting from a windowThe input function supported by the"W:" device han2}dler employs thekeyboard handler to actually getcharacters from the keyboard and thendisplays them using the window'scurr3}ent character color, size, fontand display logic. When input is donethrough a window, all charactersentered at the keyboar4}d (with a fewexceptions) are accepted as input,printed to the window and returned tothe calling program. The followingpro5}gram is a simple example ofinputting through a window. Clear theprevious program, then type thisprogram in and run it. 6} 10 GRAPHICS 7 30 OPEN #1,12,1,"W:" 80 GET #1,X:? CHR$(27);CHR$(X);: IF X<>155 THEN 80 90 CLOSE #1 140 END7}In this example, the GET command isused to input one character at atime. The returned character is thenprinted in the te8}xt window as a checkthat the input function is workingproperly. Type a number of differentcharacters from the keyboard to 9}seehow the program functions. Pressingthe RETURN key, the BREAK key orcontrol-3 ends the program.There are two keys whic:}h act asediting keys during input. The"delete back space" key backs up thedisplayed cursor one character celland, if the ;}window is using overwritedisplay logic, erases the previouscharacter. The returned ASCII valuefor this key is 126. The "cl<}ear" key,when pressed while SHIFT or CONTROLis depressed, moves the cursor to thebeginning of the line and, if thewindow =}is using overwrite displaylogic, clears the current input line.The returned ASCII value for thesekey combinations is 125. >}Try runningthe sample program again and note thebehavior of these editing keys.Now let's add some lines to oursample pro?}gram to demonstrate someadditional input features. Thefollowing two lines will limit thesize of our input window to 128pi@}xels across by 8 pixels high. Sincewe are using the default 8 by 8character cell size, this will limitour window to one liA}ne of 16characters. Type the following 40 XIO 100,#1,1,0,"W:" 50 X=128:Y=8:POINT #1,X,Ypressing RETURN after each linB}e.The next two lines will change ourinput cursor to the underlinecharacter. Type the following 60 XIO 100,#1,6,0,"W:"C} 70 X=ASC("_"):Y=0:POINT #1,X,Ypressing RETURN after each line.Now let's set up to enter a stringfrom BASIC. Type the fD}ollowing 20 DIM A$(15) 80 INPUT #1,A$pressing RETURN after each line.Finally, let's print out the returnedstring inE} the text window afterinputting it from "W:". Type thefollowing 100 FOR I=1 TO LEN(A$) 110 PRINT CHR$(27);A$(I,I); 12F}0 NEXT I 130 PRINTpressing RETURN after each line.Now run the program and experimentwith entering data and using theedG}iting keys. Note that if fifteen orfewer characters are entered and thenthe RETURN key is pressed, thereceiving string varH}iable (A$)correctly holds the entered data. Ifmore than fifteen characters areentered before RETURN is pressed, thewindowI} scrolls and the additionalcharacters are displayed in the inputwindow. They are not returned intoA$, however, because theJ}y don't fitin the fifteen character dimensionedlength of A$. Note also the effect ofthe editing keys. Their major effectiK}s on the display; no characters areremoved from the string returned toA$, although some are removed fromthe display. The AL}SCII characters ofthe editing keys are returned,however, and they may be used in a"smart" input routine to re-constructthM}e correct input value.The following is a such a "smart"input routine. It is set up to inputa device and filename, such aN}s"D2:FILENAME.EXT". The maximum numberof characters to be input is fifteen.The routine uses the GET function toaccept chaO}racters from the window andproperly responds to the use of thetwo editing functions. Type in thefollowing lines 10 GRAPP}HICS 8:MAX=15: DIM IN$(MAX+1) 20 OPEN #1,12,1,"W:" 30 XIO 100,#1,0,0,"W:": X=96:Y=72:POINT #1,X,Y 40Q} PRINT #1;" Device & name:" 50 X=96:Y=80:POINT #1,X,Y 60 XIO 100,#1,1,0,"W:": X=8*(MAX+1):Y=8:POINT #1,X,Y 7R}0 XIO 100,#1,6,0,"W:": X=ASC("_"):Y=0:POINT #1,X,Y 80 TRAP 170 90 I=1:IN$="" 100 GET #1,X 110 IF X=125 THENS} 90 120 IF X=126 AND I=1 THEN 100 130 IF X=126 AND I>1 THEN I=I-1: IN$(I)="":GOTO 100 140 IF X=155 THEN 170 1T}50 IN$(I)=CHR$(X):I=I+1: IF I=MAX+2 THEN 90 160 GOTO 100 170 TRAP 40000 180 CLOSE #1 190 PRINT IN$ 200 ENDU}pressing RETURN after each line. Nowrun the program and check it out.This piece of code can easily bemodified to act as aV}n inputsubroutine in any BASIC program. Seealso the "GETDEMO" program on your"SCREENS" diskette.Changing the parametersW}The user can change any and all ofthe individual window parameters atany time, providing the window isopen. And likewise,X} the user cancheck on the current value of any ofthe parameters of any open window.The protocol for doing eitheroperationY} starts by issuing an XIOcommand to the window of interest.The form of the XIO command for thispurpose is XIO 100,#iocb_Z}no,np_index,0, device_idBoth iocb_no and device_id have beendescribed previously. The variablenp_index is an integer n[}umber from 0to 10. It tells the window whichparameters you wish to read or set.The table below is a partial list ofallowe\}d np_index values and theassociated window parameters.np_index parameters 0......window position (colu]}mn & row) 1......window size (width & height) 2......character position (column & row) 3....^}..character cell size (width & height) 4......character set address & size 5......character col_}or & display logic 6......cursor character 7......lock flagThe way the individual parameters areread and`} written is through the useof NOTE and POINT, respectively. Forexample, if you wished to set thecharacter cell size for a a}givenwindow to 13 pixels wide by 19 pixelshigh, you would first execute the XIO100 command with np_index set to 3.Assuminb}g the window was openedthrough IOCB 2, you would thenexecute the following statement X=13:Y=19:POINT #2,X,Y(Recall that c}ATARI BASIC does notallow the use of numeric constants inthe arguments of the POINT statement,i.e. the statement POINT #2,d}13,19would generate a syntax error.) Thenext character printed would fill a13 by 19 pixel cell.Clear the previous progre}am, thenenter a new program by typing 10 GRAPHICS 7 20 OPEN #1,8,1,"W:" 30 XIO 100,#1,3,0,"W:" 40 X=13:Y=19:POINf}T #1,X,Y 50 XIO 100,#1,5,0,"W:" 60 FOR X=1 TO 3 70 Y=0:POINT #1,X,Y 80 PRINT #1;"HELLO" 90 NEXT X 150 CLOSE g}#1 160 ENDpressing RETURN after each line. Nowrun the program. Note that thecharacters in the word "HELLO" areprinted iq}RB%DOS SYSB*)DUP SYSBOSAUTORUN SYSB INTRO BASBSMANUAL TXTBwSMANPRT n cells that are thirteenpixels wide and nineteen pixels high.Also, the three "HELLO"'s are alldifferent colors due to ther} POINTstatement in line 70.When you want to check on a windowparameter, use the NOTE command. Forexample, in the case ofs} window size,the value of np_index would first beset to 1 by executing the XIO 100command. Then, assuming the windowwas ot}pened through IOCB 1, executingthe following command NOTE #1,X,Ywould place the column position ofthe upper left corner u}of the windowin X and the row position in Y.Add another three lines to the sampleprogram by typing 100 XIO 100,#1,1,0,"v}W:" 130 NOTE #1,X,Y 140 PRINT X,Ypressing RETURN after each line. Nowrun the program again. Note that thewindow width w}and height are correctlyprinted out as 160 and 80respectively.Not all the parameters are passed inpairs. For example, inx} the case ofthe cursor character only a singlevalue is passed. In such cases, onlythe first parameter in the POINTcommandy} has meaning, the secondparameter is arbitrary, and the NOTEcommand will always return zero asthe value of the second paraz}meter.The value of np_index is readable viathe STATUS statement. Assuming awindow was opened through IOCB 4, youcould re{}ad the current value ofnp_index for that window by executingthe statement STATUS #4,Xwhich would place the current value|}of np_index into the variable X.Modify the sample program by typing 110 STATUS #1,N 120 PRINT N,pressing RETURN after}} each line. Runthe program again. The value ofnp_index is displayed along with thewindow width and height.Acceptable par~}ameter valuesATARI BASIC restricts the firstparameter passed in the POINTstatement to be an integer from 0 to32767 inclu}sive; the first valuereturned by NOTE can be an integerfrom 0 to 65535 inclusive. The secondargument of both statements mu}st bean integer from 0 to 255 inclusive.Any value within these limits can bepassed to the device "W:" withoutgenerating a}n error. However, if thevalues passed are out of range for agiven parameter they may be modifiedor ignored.The maximum v}alues for windowposition and size depend on thedisplay mode resolution. In turn, themaximum values for character position}and size depend on window size (note:maximum character width is 255regardless of window size). Before acharacter is printe}d to the display,these values are checked. If thecolumn/row position equals or exceedsthe number of columns/rows supported},then that parameter is set to zero.If either size parameter exceeds themaximum allowable value, then it isset to that ma}ximum. If any sizeparameter is set to zero by the user,it will be set to one by thehandler.The character base pointer ca}n be anyaddress from 0 to 65535; it does nothave to be on any particular memoryboundary. Because of the above-notedlimita}tion in the POINT statement,there is a problem in passing valuesgreater than 32767. To get aroundthis problem, the second }argument ofthe POINT statement is employed. Themost significant bit in the secondargument is ORed with the mostsignifican}t bit of the high orderbyte of the passed address. Thus, inorder to pass a character baseaddress greater than 32767, use t}hefollowing bit of BASIC code X=ADDRESS:Y=SIZE IF X>32767 THEN X=X-32768:Y=Y+128 POINT #1,X,YSince only the least sig}nificant bitof the second argument is used toindicate the character set size, theaddition of 128 will not alter itseffect}.Character color can be set to anynumber from 0 to 255 inclusive. If alarger number is passed, only theleast significant} byte is kept. Alleight bits of this byte are stored,but when a character is displayedonly those bits needed to specifyco}lor in the active graphics mode areused. For example, in graphics modeeight, only the least significant bitcontrols the co}lor; in graphics modeseven, the two least significant bitsare used; and so on.The valid values for characterdisplay logi}c range from 0 to 3inclusive; a larger value may bepassed, but only the two leastsignificant bits are kept. The tablebelo}w shows the logic type associatedwith each legal value value logic 0......overwrite 1......and 2......or } 3......exclusive-orOverwrite means that the bit map ofthe character cell to be displayedreplaces the data previously p}resenton that segment of the display. ANDmeans that the bit map of thecharacter cell to be displayed islogically ANDed wi}th the currentdisplay data on a a bit by bit basis,and the result displayed. Thus, a bitwill be set only if it is on in bo}ththe character cell and the previousdisplay. The OR and EXCLUSIVE-ORoptions behave like the AND optionexcept the logic u}sed to create theactual display is different. With OR,a bit is set if it is on in eitherthe character cell or the previous}display. With EXCLUSIVE-OR, a bit inthe display is unchanged if thecorresponding bit in the charactercell is zero and inv}erted if thecorresponding bit is one. Theexclusive-or operation is reversible;writing the same character twice tothe same} location using exclusive-orlogic results in a return to theoriginal display.Attractive text displays can becreated by m}ixing and overlaying textusing different display logic. Toview some, load and run the BASICprogram named "LOGIC" from your}"SCREENS" diskette. This BASICprogram demonstrates just a fewpossibilities; you can explore othersby modifying the DATA s}tatements.The cursor character can take on anyvalue from 0 to 255 inclusive. If alarger value is passed, only theleast s}ignificant byte is kept. Avalue of 155 for the cursor characterindicates that no cursor is to bedisplayed.The window loc}k flag is either 0 or1; passing any value other than zerocauses the parameter to be set toone, i.e. the window is locked.}Locking the window has three distincteffects: (1) the window will notclear; printing an ASCII 125 to thewindow will cause }the ATASCII symbolfor this character to be displayed,(2) the window will not scroll;attempting to print past the bottomof} the window will cause the text towrap around on the bottom line and(3) the frame drawn with the XIO 102command (see below}) will invert thedata under the frame instead ofwriting over it.Additional NOTE/POINT functionsThere are three addition}al NOTE/POINTfunctions beyond those described inthe previous two sections. These aretreated separately because they donot} deal with window characteristics.Rather, they are used to store andretrieve window images to and frommemory. The table be}low gives thethree additional values of np_indexand the parameters associated withthe NOTE and POINT commands whenthese v}alues are in effect. np_index NOTE/POINT parameters 8......byte count/store address 9......as above with compres}sion 10......start address/retrieve addressWhen np_index is set to 8, the NOTEfunction will return as its} firstargument the amount of memory spacerequired in bytes to store the imageof the window in memory; zero isalways retur}ned for the secondargument. If the user wishes to storeaway the window, sufficient memorymust be allocated somewhere in RA}M.This can be done by dimensioning astring variable of sufficient size tohold the image or by employing unusedRAM. To sto}re away the window, theuser now executes a POINT command(with np_index still equal to 8)having its first argument equal to}the starting address of the allocatedRAM. For memory addresses greaterthan 32767, the user must employ thesecond argument} as described in theparagraph above which discussed thecharacter base pointer.The use of NOTE and POINT whennp_index is }set to nine is identicalto that described in the previousparagraph. The difference in behavioris that when np_index equals} nine,the window image is stored in acompressed format. Most often thiswill result in a significantlysmaller RAM requirem}ent to store thewindow. Sometimes, however, when awindow image is sufficiently complex,the attempt at compression willact}ually require more space. The usershould routinely check both methodsof storage, and select the one whichrequires the less}er RAM space.When a window is stored in RAM, it isnot automatically erased from thedisplay. In fact, there is nomodifica}tion of the display. Bystoring a window away, however, theuser can now modify the display atwill knowing that the image ha}s beenstored away and can be recalledintact later. Once the window imageis transferred to RAM, it can even bestored on ca}ssette or disk. Otherprograms can recall that window imageinto RAM and then transfer the imageto the display.The window }image is retrieved fromRAM using the POINT command withnp_index set to 10. All the user mustdo is set the first argument e}qual tothe RAM address at which the windowresides. Once again, if the addressis greater than 32767, the secondargument is} used to indicate thatcondition. The same command is usedwhether the image was stored with orwithout compression. The "W:"} handleris able to distinguish the two typesof storage and reconstruct the windowimage from either.Note that when a wind}ow is retrieved,it does not have to be retrieved tothe same IOCB or to the same deviceunit, i.e. a window stored from "W3:}"does not have to be retrieved to"W3:". Further, the window to whichthe image is retrieved need not bethe same size or us}e the samegraphics mode as the window fromwhich the image was stored. When awindow image is stored, informationabout its }size is stored along withit. When the image is retrieved itwill be automatically sized to fitthe current window and the im}agepixels will be modified, ifnecessary, to be compatible with thecurrent graphics mode. This is a verypowerful feature o}f "SCREENS" whichcan be used to reduce or expandimages and combine images frommultiple sources.The logic used when retri}eving awindow image to the display isdetermined by the same parameterwhich determines the characterdisplay logic. It is s}et, asdescribed previously, by using theXIO 100 command with np_index set to5. The display logic values areinterpreted th}e same for windowretrieval as for character display.Thus, a retrieved window image canoverwrite or logically AND, OR orEX}CLUSIVE-OR with the current displaydata.The last function to be discussed isthe use of the NOTE command withnp_index set} to 10. In this case, thevalue returned for the firstparameter is the starting address ofthe "W:" handler in RAM; zero is}always returned for the secondparameter. Since the handler does notneed to reside at a set address, thisfunction is a conv}enience for thoseusers who need to know the handler'sexact RAM location.Other XIO commandsThere are two additional XIO }commandsrecognized by the "W:" handlerbesides the XIO 100 command used toset np_index. These are XIO 101 andXIO 102. Both} can be used to framethe current window, but they act insomewhat different fashions.When the XIO 101 command is issuedwi}th both parameters set to zero, asolid frame is drawn, one pixel wide,at the inside boundary of the window.The frame is ac}tually part of thewindow and will be cleared, scrolledand stored along with the rest of thewindow. If the first parameter }isnon-zero then the boundaries of thewindow are first moved out thatnumber of pixels before the frame isdrawn. If the sec}ond parameter isnon-zero then the boundaries of thewindow are moved in that number ofpixels after the frame is drawn.Thus}, assuming the window is not atthe outer boundaries of the display,one could draw a frame one pixel widejust outside the c}urrent windowboundaries by using the command XIO 101,#1,1,1,"W:"The window will grow by one pixel inall directions, the }frame will bedrawn inside that new boundary, thenthe window will be reduced to itsoriginal size.When the XIO 102 command} is issuedwith both parameters set to zero, allthe data inside the window isinverted, i.e. all the bits which are0 are se}t to 1 and all the bits thatare 1 are set to 0. If the firstparameter is non-zero then theboundaries of the window are fir}stmoved out that number of pixelsbefore the window is inverted. If thesecond parameter is non-zero then theboundaries of }the window are moved inthat number of pixels after the frameis inverted, and then the window isinverted again inside its n}ewboundaries. Thus, assuming the windowis not at the outer boundaries of thedisplay, one could draw a frame onepixel wide} just outside the currentwindow boundaries by using thecommand XIO 102,#1,1,1,"W:"The window will grow by one pixel ina}ll directions, the image will beinverted inside that boundary, thenthe window will be reduced to itsoriginal size and inve}rted again.Note that there is a distinctdifference between drawing the framethis way using XIO 102 as opposed toemployin}g the XIO 101 command. UsingXIO 102, you have not destroyed theimage which previously resided in thearea which is now "fra}me" since ithas just been inverted and notoverwritten. (Note: this is also truefor the XIO 101 command if the windowis lo}cked.) The process can bereversed by repeating the same XIO102 command used to draw the frame,and the display is now retu}rned toits original condition. Furthermore,the size of the frame drawn by theXIO 102 command is a function of thesize of }the arguments. To draw aframe four pixels wide, use thecommand XIO 102,#1,4,4,"W:"The command XIO 101,#1,4,4,"W:"on t}he other hand, will draw a singlepixel frame spaced four pixels awayfrom the edges of the originalwindow.As with all XIO} commands, the valuesof the two parameters are limited tointegers from 0 through 255inclusive.Handler errorsThe only e}rror generated by the "W:"device handler is ERROR 146. Thiserror will occur in two situations:(1) an attempt to use an uns}upportedXIO command, e.g. XIO122,#1,0,0,"W:", or (2) an attempt toset np_index to a value greater thanten, e.g. XIO 100,#}1,43,0,"W:". Thehandler will "pass along" the ERROR136 which is generated if a control-3is entered while inputting text fr}om"W:". Also, if the BREAK key ispressed during input or output, theprogram will be STOPPED. Referencech}aracter colorthe color used to display eachcharacter. Set/read as the firstargument of the POINT/NOTE commandexecuted wi}th np_index set to five.character display logicdetermines how a character orretrieved window merges with data ona displ}ay. Set/read as the secondargument of the POINT/NOTE commandexecuted with np_index set to five. value logic 0......o}verwrite 1......and 2......or 3......exclusive-orcharacter fontbit map of the character set to bedisplayed. The} starting address ofthe character font is set/read as thefirst argument of the POINT/NOTEcommand executed with np_index se}t tofour. If the address is greater than32767, it can be passed with thePOINT command by using the followingBASIC code }IF X>32767 THEN X=X-32768:Y=Y+128 POINT #1,X,Ycharacter positionthe offset in pixels from the upperleft corner of the }window to theupper left corner of the nextcharacter cell to be filled. Thehorizontal and vertical offsets areset/read as }the first and secondarguments of the POINT/NOTE commandexecuted with np_index set to two.character sizethe size in pixe}ls of the charactercell. The height and width areset/read as the first and secondarguments of the POINT/NOTE commandexecu}ted with np_index set to three.clearing a windowis performed by outputting an ASCII125 in a PRINT or PUT command, e.g.P}UT #1,125. When a window is cleared,the window area is blanked (alldisplay data set to zero) and thecharacter position is }automaticallyset to zero horizontal and verticaloffset. If a window is locked, thewindow will not be cleared and the"SHIF}T CLEAR" symbol will bedisplayed.closing a windowis performed with the CLOSE command,e.g. CLOSE #1. Neither the window}parameters nor the display iseffected.cursor characteris the character displayed as acursor when inputting from a windo}w.The ASCII value of this character isset/read as the first argument of thePOINT/NOTE command executed withnp_index set t}o six. If its value is155, then no cursor is displayed.font sizeis set/read as the second argument ofthe POINT/NOTE com}mand executed withnp_index set to four. A value of 0indicates an 8 by 8 character set,any other value indicates a 16 by 16}character set.framing a windowis performed using either the XIO 101or XIO 102 command, e.g. XIO101,#1,0,0,"W:" could b}e used to drawa frame just inside the currentwindow boundary. See the section on"Other XIO commands" for variations.hand}ler locationis read as the first argument of theNOTE command executed with np_indexset to 10. Its value is the startinga}ddress of the RAM memory occupied bythe "W:" handler.inputting text from a windowis performed using the GET or INPUTsta}tement, e.g. GET #1,X. The datareturned are the ASCII values of thekeyboard input. As the data is input,it is displayed us}ing the currentlydefined character set, size, colorand logic.inverting a windowis performed using the XIO 102command, }e.g. XIO 102,#1,0,0,"W:".All the bits in the window areinverted, i.e. all zeroes becomeones, all ones become zeroes.load}ing a window image from diskis performed in a three step process.First, the initial two bytes of theimage file must be re}ad to determinethe window image size. Then a spacein memory must be located ofsufficient size to hold the data.Finally, t}he remainder of the data isread from the file into memory. Thefollowing BASIC code demonstratesthis process. OPEN #1,4,0},"D:FILENAME.WDW" GET #1,L:GET #1,H:SIZE=256*H+L DIM IMAGE$(SIZE) IMAGE$(1)=CHR$(L) IMAGE$(2)=CHR$(H) FOR I=3 TO SI}ZE:GET #1,X IMAGE$(I)=CHR$(X):NEXT I CLOSE #1loading window parameters from diskassumes the data has been stored in a}file as described under "savingwindow parameters to disk". Thefollowing BASIC code demonstrates theprocess. OPEN #1,12,}1,"W:" OPEN #2,4,0,"D:FILENAME.PRM" FOR I=0 TO 7 XIO 100,#1,I,0,"W:" INPUT #2,X:INPUT #2,Y IF X>32767 THEN X=X-3276}8:Y=Y+128 POINT #1,X,Y:NEXT I CLOSE #1:CLOSE #2locked & unlocked window statusis determined by the state of thewindo}w lock flag. This flag isset/read as the first argument of thePOINT/NOTE command executed withnp_index set to seven. A val}ue of 0indicates an unlocked window; anyother value indicates a lockedwindow.np_indexis set as the first argument of t}heXIO 100 command, e.g. XIO100,#1,7,0,"W:". Its value can beread using the STATUS command, e.g.STATUS #1,X. Valid values }fornp_index are zero through teninclusive.opening a windowis accomplished using the OPENcommand, e.g. OPEN #1,8,1,"W:" }. Thewindow parameters are reset if thethird argument is non-zero, as it isin the example, otherwise they areunchanged. }overlaying windowscan be accomplished by (1) openingthe window to overlay the currentdisplay and defining its parameters, }(2) storing the current windowcontents to RAM, then (3) clearingthe window. The window can now beprinted to, input from,  }etc. When theuse of the overlay window iscomplete, the previously storedwindow image is retrieved from RAMwith overwrite  }display logic and theoverlay window closed.printing text to a windowis performed using the PUT or PRINTstatement, e.g. }PUT #1,X. The dataoutput to "W:" are the ASCII valuesof the characters to be displayed.They are displayed using thecurren}tly defined character set,size, color and logic. Two specialcharacters are recognized: ASCII 125which clears the window an}d ASCII 155which causes a display "carriagereturn/line feed", moving thecharacter position to the beginningof the followi}ng line.retrieving a window from RAMis accomplished using the POINTcommand with np_index set to ten. Thefirst argument }is the address in RAMof the window image data. Thefollowing BASIC code is an example ofthis process. X=ADR(IMAGE$):Y=0 } IF X>32767 THEN X=X-32768:Y=Y+128 POINT #1,X,Ysaving a window image to diskis accomplished by saving to diskthat part} of RAM into which thewindow image has been stored. OPEN #1,8,0,"D:FILENAME.WDW" PRINT #1;IMAGE$; CLOSE #1See "storin}g a window image to RAM".saving window parameters to diskis accomplished by reading theparameters using the NOTE functio}nand writing them to a file. Thefollowing BASIC code demonstrates theprocess. OPEN #1,12,0,"W:" OPEN #2,8,0,"D:FILENAM}E.PRM" FOR I=0 TO 7 XIO 100,#1,I,0,"W:" NOTE #1,X,Y PRINT #2;X:PRINT #2;Y NEXT I CLOSE #1:CLOSE #2storing a win}dow image to RAMis performed in a three step process.First, the window image size isdetermined by using the NOTE command}with np_index set to eight (normal)or nine (compressed). Then a space inmemory is reserved of sufficient sizeto hold the d}ata. Finally, the windowimage is transferred to RAM using thePOINT command with np_index set toeight or nine. The followin}g BASICcode demonstrates this process. XIO 100,#1,8,0,"W:" NOTE #1,NSIZE,DUMMY XIO 100,#1,9,0,"W:" NOTE #1,CSIZE,DUM}MY SIZE=CSIZE:TYPE=9 IF NSIZE32767 THEN X=X-32768:Y=Y+128 POINT #1,X,Ywindow positionthe offset in pixels from the upperleft corner of} the display to theupper left corner of the window. Thehorizontal and vertical offsets areset/read as the first and second}arguments of the POINT/NOTE commandexecuted with np_index set to zero.window sizethe size in pixels of the window. The }height and width are set/read as thefirst and second arguments of thePOINT/NOTE command executed withnp_index set to one.!} DetailsIntroductionThe purpose of this section is toprovide some additional details onthe structure an"}d workings of the"W:" device handler. No additionalfeatures will be described. Theinformation will be most useful tothose#} interested in non-BASICapplications or applications whichrequire the handler to be co-residentwith other software. This s$}ection isnot meant to be tutorial in nature;many sections assume an intimateknowledge of the ATARI operatingsystem.Prog%}ram installationThe "W:" device handler resides in a33 sector AUTORUN.SYS file. This fileloads into RAM at starting addre&}ss$6C00 (the 27kB boundary). Itinitially occupies just under 4kB ofRAM space. The starting address waschosen so that, in '}a multiple fileboot, "SCREENS" would load beyond anynon-relocatable application withwhich it was merged, yet becompatible(} with a 32kB system.The application is installed by anINIT routine which is laterjettisoned. This routine's primaryfunct)}ions are to (1) load the 850interface module handler if the 850is connected and powered up, (2)relocate the "W:" device ha*}ndler sothat it begins at the current MEMLOaddress, (3) adjust all the absolutememory addresses in the handler codeto ada+}pt to its new location and (4)point the DOSINI vector to thehandler initialization routine. Thehandler initialization rout,}ine, whichafter installation is vectored to onSYSTEM RESET, first does a JSR to thevector which had been in DOSINI justpr-}ior to installation of the "W:"handler. It then re-installs thedevice in the handler table,repositions MEMLO to just beyon.}d thedevice handler code and resets theparameters for all nine deviceunits.The application also has a RUN vectorwhich p/}oints to a routine which putsthe program title, the version numberand the copyright notice on thedisplay. This RUN routine0} is notcritical to handler operation. Thus,the "W:" handler AUTORUN.SYS fileneed not be the final file in acompound AUTOR1}UN.SYS file, i.e. itsRUN routine does not need precedence.Although some thought has been givento compatibility with other 2}AUTORUNprograms, certainly there are caseswhich will not yield to a simplemerging of the files. In particular,any file wh3}ich does not relocate yethas a RUN routine which must beexecuted cannot be easily merged.Memory usageOnce it is install4}ed, the "W:" devicehandler uses only two blocks of RAM.The largest block, of course, is the3311 bytes occupied by the hand5}leritself. Because the handler isrelocatable, the position of theblock is not fixed. For this reason,the NOTE function wi6}th np_index setto ten was designed to provide thestarting address of the handlerroutine.The other block of employed memo7}ry ison page zero. Thirty-two bytes from$E0 to $FF inclusive are used asworking space whenever the "W:"device is accessed8}. Other routinescan use this zero-page memory withimpunity, however, because the "W:"handler puts the values found therei9}n temporary storage while it'sworking, then restores them when ithas completed its job. The onlynecessary precaution is wi:}thinterrupt routines; if an interruptroutine employs any of the handler'szero page locations, it must do so ina fashion w;}hich restores them totheir original value when theinterrupt is complete.OS variables usedThe "W:" handler relies on the<}following operating system variablesto be used as described in the OSTechnical Users' Notes: BOTSCR,BRKKEY, DINDEX, DOSIN=}I, HATABS,ICAX1Z, ICAX2Z, ICAX3, ICAX4, ICAX5,ICCOMT, ICCOMZ, ICDNO, ICDNOZ, MEMLO,SAVMSC, SIOCB, SIOV, SSFLAG. Some ofth>}ese variables rate individualattention.SAVMSC is assumed to point to thefirst byte of the memory mappeddisplay. BOTSCR an?}d DINDEX togetherare used to describe the currentgraphics display mode; they determinethe display and pixel size used byt@}he "W:" handler. Note that thehandler does not recognize mixed modedisplays other than the standardgraphics modes with texA}t windows.Using "W:" in a custom mixed modedisplay is possible, but tricky,since only a single resolution anddisplay sizeB} is assumed. Manipulationof SAVMSC and DINDEX will give yousome degree of control.ICCOMZ contains the function numberof C}"special" commands. This appliesto the XIO function number. This alsoapplies to the "special" commandsNOTE and POINT. The D}NOTE command usesthe function number $26; the POINTcommand uses the function number$25.ICAX1Z and ICAX2Z are where CIO pE}utsthe values passed in the first andsecond arguments respectively of theOPEN and XIO commands. The valuespassed with theF} NOTE and POINTcommands are placed in locationsICAX3, ICAX4 and ICAX5. Inparticular, ICAX3 and ICAX4 containthe low and hG}igh byte respectively ofthe first argument; ICAX5 containsthe value of the second argument.One point already mentioned nuH}meroustimes is the limitation ATARI BASICputs on the value which may be passedas the first argument of an XIOcommand. ThiI}s necessitated someadditional code when the valueexceeded 32767. The way the handlerdetermines the value of the high byteJ}of the first argument passed by anXIO command is using the followingcode LDA ICAX5,X AND #$80 ORA ICAX4,XThe most siK}gnificant bit of the firstargument (ICAX5) may effect the highbyte of the first argument (ICAX4). Appendix AL}Window image formatThe window image is comprised of twoparts - an eight byte header and theactual image data. The firstM} twobytes of the header are the low andhigh bytes respectively of the countof the total number of bytes in thewindow imagN}e, including header. Thenext two bytes of the header are thelow and high bytes respectively ofthe number of pixel columns O}in thewindow. The next two bytes of theheader are the low and high bytesrespectively of the number of pixelrows in the wiP}ndow. The next byte ofthe header is the number bits perpixel in the window; sixteen is addedto this number if the window dQ}ata isin compressed format. The final byteof the header is a mask byte showingwhere the valid window data begins inthe fiR}rst image data byte. This maskis necessary because the window imageis not "left-justified" inside theimage data, i.e. it dS}oes notnecessarily begin at a byte boundary.Thus, it is necessary to indicatewhere the valid image data begins.This is doT}ne by the bits which areset in the mask byte.In the uncompressed storage format,all bytes in a line which hold anypart oU}f the window image are storedin order from left to right. Imagedata is stored in a line by lineformat, top to bottom, justV} as itappears in the display RAM. This isakin to the "standard" method ofstoring an ATARI graphics image. Infact, appendiW}ng the appropriateheader to a "standard" graphics imagefile will convert it into a windowimage file.Let's take an examplX}e of storing awindow image which is in fact a wholeGRAPHICS 24 display. What would theheader for this image look like if iY}twere stored uncompressed? The headerbytes would have the followingvalues: 8 30 64 1 192 0 1 255There are 8+30*256Z}=7688 total bytesin the image. The image is64+1*256=320 pixels wide by192+0*256=192 pixels high. There is 1bit per pixel.[} All the data in thefirst byte is valid (all bits of themask are 1).In the compressed storage format, thesame data bytes \}are stored and in thesame order as described above.However, the data is stored insequences. Each sequence is comprisedof ]}a count byte followed by one ormore data bytes. There are two typesof sequences. If the count byte has avalue of 0 to 127 ^}inclusive, then itis a repetitive sequence representingthe repeat of the following data bytecount+1 times. If the count by_}te is128 to 255 inclusive, then it is anon-repetitive sequence of count-127distinct data bytes.Using this technique to s`}tore thedata pattern <1 2 3 4 4 4 4 4 4 4 4 66 6 6 6 6 6 6 6 6 7 8 9> would resultin the data pattern <130 1 2 3 7 4 96 1a}30 7 8 9>. The example shows acompression of 50%, from 24 to 12bytes. Obviously, the degree ofcompression depends stronglyb} on therepetitiveness of the data and, infact, the compressed mode cansometimes require more storage spacethan the uncompc}ressed mode. For thatreason, it is always prudent to checkboth means of compression todetermine the more efficient one.d} Appendix BExpanded font formatThe "W:" handler will accept both 8by 8 and 16 by 16 character fonts.The fore}mat of the former has beenestablished by the format of thestandard ATARI character font in ROM.Each character is representf}ed byeight bytes; each byte represents oneline in the character in sequencefrom top to bottom. Each bit in abyte represeng}ts a pixel in the 8 by 8character cell; if it's set then thatbit is "on" when the character isdisplayed. The 16 by 16 charh}acter setis laid out in an analogous fashion.Each character of the set isrepresented by 32 bytes of data. Eachpair of byti}es represents a line ofthe character in sequence from top tobottom. The first byte of each pairrepresents the eight leftmoj}st bits ofthe character cell; the second byte,the rightmost bits. The order ofdisplay of the bits is the same as inthe 8 k}by 8 set, namely, the mostsignificant bit in the byte is theleftmost pixel. The order of thecharacters in the 16 by 16 chal}racterset is identical to that in the 8 by8 set. Appendix CUseful tablesXIO number function 100m}.........set np_index 101............frame 102............invertnp_index parameters 0......window position n} (column & row) 1......window size (width & height) 2......character position (columno} & row) 3......character cell size (width & height) 4......character set address & size 5...p}...character color & display logic 6......cursor character 7......lock flag 8......byte count/store addrq}ess 9......as above with compression 10......start address/retrieve addresslogic parameter value logicr} type 0..............overwrite 1..............and 2..............or 3..............excluss}ive-ordefault window characteristicswindow position: column=0, row=0window size: width=320, height=192character positiot}n: column=0, row=0character cell size: width=8, height=8character set: address=57344 (ROM), u} matrix=8x8, color=255 logic=overwritecursor character=160 (inverse space)lock flag=0 (unlocked)np_indexv}=012jAOFFSEROOFSEPAGEROWTEXTROW(@@@f@` ;@@,36x}-@6-@'6-@f36-@` A(..@@ D:SMANUAL.TXT2##@@y}P:<.-@(@*6-%@. F@(@P4AZ7@,0z} Ad&(@6-%@& Apn(@ x@4AP7@,0 A{}`(@6-%@(@6-%@B &!%-@&%%@0(@4 B6-@|}% @p#@@# B D:SMANPRTB\@K:W)@Z. D:INTRO.BASEENS in action.ZZ(*( Ӡ٠٠ϠϠϠJ@ :