Oakland CPM Archive

home *** CD-ROM | disk | FTP | other *** search

/ Oakland CPM Archive / oakcpm.iso / sigm / vol107 / syslibug.ws < prev next >

Wrap

Text File | 1985-02-10 | 122.3 KB | 2,905 lines

SYSLIB -- An Integrated Library of Assembly Language Utility Subroutines for use with the Microsoft M80 Assembler User's Guide for SYSLIB 2.3 by Richard Conn Revision B of User's Guide 14 December 1982 Thi≤ User'≤ Guideô i≤ ß supplemen⌠ t∩ thσ SYSLI┬ 2.3 Use≥ anΣ ì Referencσ Manual¼ dateΣ 14 December 1982. The SYSLIB Library is Copyrighted, 1982, by Richard Conn .he User's Guide for SYSLIB 2.3 .pn 1 .fo Table of Contents TOC - # SYSLIB -- An Integrated Library of Assembly Language Utility Subroutines for use with the Microsoft M80 Assembler User's Guide for SYSLIB 2.3 Table of Contents 1.0 Introduction and Purpose of the User's Guide 1 1.01 What is SYSLIB? 1 1.02 SYSLIB Documentation 2 2.0 SYSLIB Output, Math, and Some Misc Routines 3 2.01 Printing Stuff with SYSLIB 3 2.02 Math with SYSLIB 10 2.03 Some Miscellaneous Routines 11 2.04 The CODEND Routine 14 3.0 SYSLIB Input Line Editors 16 3.01 What Is an Input Line Editor? 16 3.02 The BDOS-Based Input Line Editors 16 3.03 The INLINE Input Line Editor 18 4.0 SYSLIB Disk Input/Output 19 4.01 Directory Manipulation Routines 20 4.02 Block-Oriented File Input/Output 28 4.03 Byte-Oriented File Input/Output 29 4.04 File Control Block (FCB) Manipulation 31 4.05 ZCPR2-Specific Functions 33 Multiple Commands and SYSLIB 36 External Paths and SYSLIB 37 Named Directories and SYSLIB 44 5.0 Numeric String Evaluation, CRC Check, and Sort Routines 48 5.01 Numeric String Evaluation 48 5.02 Cyclic Redundancy Checking 50 5.03 The SYSLIB Sort Routines 51 6.0 What is SYSLIB? SYSLIB Overview 54 6.01 Functional Overview of SYSLIB 54 6.02 SYSLIB Documentation and Files and SYSLIB Availability 56 6.03 Distribution Statement for SYSLIB 56 .pn 1 .fo Alphabetical Listing of SYSLIB Routines AList - # SYSLIB -- An Integrated Library of Assembly Language Utility Subroutines for use with the Microsoft M80 Assembler Alphabetical Listing of SYSLIB Routines A ADDHD 10 | ANDHD 10 B BBLINE 16 | BIOS 11 BDOS 11 | BLINE 16 C CAPS 11 | COMPB 13 | CRC2CLR 50 CAPSTR 11 | COMPBC 13 | CRC2DONE 50 CATH 11 | COMPHD 13 | CRC2UPD 50 CCOUT 3 | CONDIN 4 | CRCCLR 50 CIN 3 | COUT 3 | CRCDONE 50 CLINE 11 | CPOUT 3 | CRCUPD 50 CLOUT 3 | CRC1CLR 50 | CRLF 3 CMPH 10 | CRC1DONE 50 | CST 4 CODEND 14 | CRC1UPD 50 D DBUFFER 20 | DIRFS 27 | DIRSEL 23 DFREE 28 | DIRLOAD 22 | DIRSLOAD 22 DIRALPHA 25 | DIRNPACK 24 | DIVHD 10 DIRF 27 | DIRPACK 24 | DPARAMS 21 E EN 11 | EVAL16 48 EVAL 48 | EVAL2 48 EVAL10 48 | EVAL8 48 F F$CLOSE 28 | F$OPEN 28 F$DELETE 28 | F$READ 28 F$EXIST 28 | F$RENAME 28 F$MAKE 28 | F$WRITE 28 F$MOPEN 28 Fn$GET 30 | FILLBC 12 Fn$PUT 30 | FNAME 31 FIn$CLOSE 30 | FOn$CLOSE 30 FIn$OPEN 30 | FOn$OPEN 30 FILLB 12 | FSIZE 28 G GETUD 41 H HFILB 12 | HMOVB 12 HFILBC 12 | HMOVBC 12 I INITFCB 31 | INSTR 13 INLINE 18 Listing Continued on Next Page Alphabetical Listing of SYSLIB Routines, Con't L LA2HC 6 | LHLDC 6 LA3DC 6 | LOGUD 41 LADC 6 | LOUT 3 LCRLF 3 | LPRINT 4 LHL4HC 6 | LPSTR 4 LHL5DC 6 M MA2HC 9 | MHLDC 9 MA3DC 9 | MOVEB 12 MADC 9 | MOVEBC 12 MHL4HC 9 | MULHD 10 MHL5DC 9 N NEGH 10 O ORHD 10 P PA2HC 6 | PHLDC 6 PA3DC 6 | POUT 3 PADC 6 | PRINT 4 PAUSE 12 | PSTR 4 PHL4HC 6 | PUTUD 41 PHL5DC 6 R RETUD 41 | RND 13 RIN 3 | RNDINIT 13 ROTLH 10 | RNDSEED 13 ROTRH 10 S SCANNER 13 | SORT 52 SHFTLH 10 | SSBINIT 52 SHFTRH 10 | SUBHD 10 V VERSION 12 X XORHD 10 Z ZCPRQ 43 | ZGPINS 43 ZCPRQ2 43 | ZINICI 42 ZDNAME 45 | ZINIDMA 42 ZDNFIND 46 | ZINIEXT 40 ZFNAME 47 | ZINIMC 36 ZFNINIT 45 | ZMCPTR 36 ZFSTAT 43 | ZPFIND 40 .fo 1 - Introduction Page # .pn 1 SYSLIB -- An Integrated Library of Assembly Language Utility Subroutines for use with the Microsoft M80 Assembler User's Guide for SYSLIB 2.3 1.0 Introduction 1.01 What is SYSLIB? SYSLI┬ (SYSteφ LIBrary⌐ i≤ ß collectioε oµ ove≥ 13░á subrouì tine≤ whicΦ arσ designeΣ t∩ providσ t∩ thσ CP/═ 8080/Z8░ assembl∙ ì languagσá programme≥á ß se⌠ oµ function≤ upoε whicΦ hσ caεá builΣ ì hi≤ programs« Thi≤ librar∙ i≤ intendeΣ t∩ relievσ thσ programme≥ ì oµ thσ tasδ oµ frequentl∙ "reinventinτ thσ wheeló anΣ t∩á providσ ì hiφ witΦ ß too∞ environmen⌠ whicΦ encourage≤ structureΣ programmì inτ a⌠ thσ assembl∙ languagσ level. EacΦá subroutinσá withiε SYSLI┬ caε bσ vieweΣ a≤ ßá reliablσ ì "blacδ box.ó Thσ subroutine≤ iε SYSLI┬ arσ completel∙ documenteΣ ì withiεá thσ SYSLI┬ Use≥ anΣ Referencσ Manua∞ fo≥á SYSLI┬á Versioε ì 2.3¼á thσá companioε documen⌠ t∩ thi≤ guide¼á anΣ thσ SYSLIBx.HL╨ ì files«á Thσ programme≥ i≤ consistentl∙ provideΣ witΦ thσ followì inτ informatioε oε eacΦ subroutinσ withiε SYSLIB: 1. Name of Subroutine 2. Function it performs 3. What its inputs are 4. What its outputs are 5. What registers are affected by it 6. What other library routines it calls upon 7. What errors can occur and how it handles them Thσ routine≤ withiε SYSLI┬ arσ designeΣ t∩ worδ togethe≥ anΣ ì complemen⌠ eacΦ other«á Paramete≥ passinτ i≤ consisten⌠á betweeε ì thσ variou≤ subroutines«á Fo≥ instance¼á al∞ routine≤ whicΦ neeΣ ì t∩á bσá passeΣ ß pointe≥ t∩ ß Filσ Contro∞ Blocδ arσ passeΣá tha⌠ ì pointe≥ iε thσ D┼ registe≥ pair«á Also¼á a≤ ß genera∞ rule¼ iµ ß ì registe≥ i≤ no⌠ returneΣ a≤ aε outpu⌠ froφ thσ SYSLI┬ subroutine¼ ì theεá it≤ valuσ i≤ no⌠ affecteΣ (i⌠ ha≤ thσ samσ valuσá wheεá thσ ì routine is exited as it had when the routine was called). SYSLI┬á itselµá i≤ ß librar∙ oµ relocatablσá objec⌠á module≤ ì createΣá iεá thσ Microsof⌠ M8░ relocatablσá objec⌠á format«á Al∞ ì subroutine≤ withiε SYSLI┬ arσ groupeΣ withiε functionally-relateΣ ì modules«á Oncσá ß routinσ i≤ referenceΣ (b∙ thσ EX╘ statemen⌠ iε ì thσ M8░ assembl∙ languagσ program)¼á it≤ modulσ i≤ loadeΣ anΣá i⌠ ì i≤á availablσá t∩ thσ programme≥ b∙ mean≤ oµ ß simplσá subroutinσ ì call«á Al∞á othe≥ subroutine≤ withiε tha⌠ particula≥ modulσá arσ ì als∩ loaded¼á bu⌠ the∙ arσ no⌠ availablσ t∩ thσ programme≥ unles≤ ì hσá ha≤ als∩ referenceΣ theφ b∙ EX╘ statements«á Thσá modulσá i≤ ì loadeΣá onl∙á once¼á regardles≤ oµ ho≈ man∙ routine≤á withiεá thσ ì modulσá arσ referenced«á Fo≥ thi≤ reason¼á ╔ havσ designeΣá eacΦ ì modulσá t∩ contaiε routine≤ whicΦ arσ frequentl∙ useΣ togethe≥ o≥ ì arσá calleΣá b∙ eacΦ othe≥ (onσ routinσ withiε thσá modulσá call≤ ì anothe≥ routinσ withiε thσ module).è1.02 SYSLIB Documentation Thσ followinτ document≤ arσ associateΣ witΦ SYSLI┬ -- ∩ SYSLI┬ Use≥ anΣ Referencσ Manua∞ fo≥ SYSLI┬ Version 2.3ô b∙ RicharΣ Conn¼ 14 Decembe≥ 1982, 112+ pages (I occasionally refer to this as SYSLIB User and Reference Manual) ∩ User'≤ Guidσ fo≥ SYSLI┬ 2.3ô b∙ RicharΣ Conn¼ 14 December 1982, 57+ pages o SYSLIBx.HLP files by Richard Conn (SYSLIB.HLP, SYSLIB1.HLP-SYSLIB9.HLP, SYSLIBA.HLP-SYSLIBC.HLP) Thσá SYSLI┬ Use≥ anΣ Referencσ Manua∞ fo≥ SYSLI┬ Versioε 2.3ô ì i≤á divideΣ int∩ 2▒ chapters«á Thi≤ documen⌠ provide≤ aεá introì ductioεá t∩ SYSLIB¼á explaininτ wha⌠ i⌠ i≤ anΣ wha⌠ i⌠á buy≤á thσ ì user¼á anΣá theεá proceed≤ t∩ describσ al∞ oµ thσ SYSLI┬á subrouì tines¼ groupeΣ b∙ function¼ iε detail« Thσ las⌠ chapte≥ contain≤ ì seveε samplσ program≤ whicΦ usσ SYSLIB¼á anΣ i⌠ show≤ thσá sourcσ ì listinτ oµ thesσ programs¼á thσ assembl∙ process¼ anΣ run≤ oµ thσ ì programs. Thσá SYSLIBx.HL╨á file≤ arσ intendeΣ t∩ bσá useΣá a≤á onlinσ ì referencσá manual≤ fo≥ SYSLIB«á Thσ HEL╨ commanΣ give≤ thσá use≥ ì acces≤ t∩ thσ content≤ oµ thσ HL╨ file≤ iε aε indexeΣ manner¼á s∩ ì thσá use≥ ma∙ quickl∙ identif∙ thσ routinσ hσ need≤ anΣ determinσ ì ho≈ t∩ usσ it«á Thσ informatioε iε thσ SYSLI┬ Use≥ anΣ Referencσ ì Manua∞á fo≥ SYSLI┬ Versioε 2.3ô oε thσ SYSLI┬ subroutine≤ i≤á dupì licateΣ iε thesσ HL╨ files. Thi≤ i≤ thσ User'≤ Guidσ fo≥ SYSLI┬ 2.3«á I⌠ i≤ designeΣ t∩ ì bσá useΣá a≤ aε instructiona∞ supplemen⌠ t∩ thσ SYSLI┬á Use≥á anΣ ì Referencσá Manua∞ fo≥ SYSLI┬ Versioε 2.3«á Thσ Referencσá Manua∞ ì present≤á thσá "harΣ factsó oε thσ SYSLI┬ subroutines¼á anΣá thi≤ ì User'≤á Guidσá present≤ thσ philosoph∙ behinΣ thσ desigεá oµá thσ ì SYSLI┬ subroutine≤ anΣ aε explanatioε oµ ho≈ the∙ arσ intendeΣ t∩ ì interac⌠ witΦ eacΦ othe≥ anΣ worδ togethe≥ t∩ providσ ß flexible¼ ì powerfu∞á too∞á se⌠ fo≥ thσ assembl∙á languagσá programmer«á Thσ ì Referencσá Manua∞ i≤ jus⌠ tha⌠ -- ß booδ t∩ refe≥ t∩ iε orde≥á t∩ ì answe≥á specifiπ question≤ abou⌠ thσ detail≤ oµ thσá SYSLI┬á rouì tines« Thσ User'≤ Guide¼ oε thσ othe≥ hand¼ i≤ ß tutorial. .fo 2 - SYSLIB Output, Math, and Some Misc Routines Page # 2.0 SYSLIB Output, Math, and Some Misc Routines 2.01 Printing Stuff Using SYSLIB ┴á pai≥ oµ SYSLI┬ Subroutine≤ perforφ ß simplσ functioεá fo≥ ì thσá programme≥á anΣ havσ n∩ ne⌠ effec⌠ oε an∙ register≤á whatsoì ever«á Hence¼ the∙ caε bσ useΣ a⌠ wil∞ withou⌠ an∙ concerε whatì soeve≥ oε sidσ effects« Thi≤ pai≥ oµ routine≤ includes: o CRLF -- Output CR LF to the Console o LCRLF -- Output CR LF to the LST: Device Thσá pai≥ oµ SYSLI┬ Subroutine≤ jus⌠ discusseΣá i≤á probabl∙ ì thσá simples⌠ oµ thσ entirσ library«á Nex⌠ t∩ theφ iε complexit∙ ì arσ thσ singlσ characte≥ input/outpu⌠ routines: o CIN -- Input Character from Console in A o RIN -- Input Character from Reader in A o COUT -- Output Character in A to Console o LOUT -- Output Character in A to LST: Device o POUT -- Output Character in A to PUN: Device o CCOUT -- Output Character in A to Console with Control Character Processing o CLOUT -- Output Character in A to LST: Device with Control Character Processing o CPOUT -- Output Character in A to PUN: Device with Control Character Processing Notσá tha⌠á thesσ routines¼á likσá al∞á SYSLI┬á subroutines¼ ì perforφá exactl∙á thσá functioε a≤ documenteΣ anΣá nothinτá else« ì CIN¼ fo≥ example¼ onl∙ input≤ ß character¼ anΣ doe≤ no⌠ ech∩ thi≤ ì character. To input and then echo a character, a sequence like CALL CIN ; input ch CALL COUT ; echo ch woulΣá bσá used«á Onl∙ thσ ┴ registe≥ i≤ affecteΣ b∙á thσá inpu⌠ ì routines¼ anΣ n∩ registe≥ i≤ affecteΣ b∙ thσ outpu⌠ routines. Thσá outpu⌠á routine≤ caε outpu⌠ character≤ witΦ o≥á withou⌠ ì contro∞ characte≥ processing« Thσ routine≤ whicΦ proces≤ contro∞ ì character≤ wil∞ outpu⌠ character≤ likσ control-├ (binar∙ 3⌐ a≤ ^├ ì anΣ thσ routine≤ whicΦ d∩ no⌠ d∩ sucΦ processinτ woulΣ outpu⌠ thσ ì exact binary code. Thσ Consolσ Statu≤ routine¼á CST¼á return≤ thσ statu≤ oµ thσ ì consolσ iε registe≥ A¼á sayinτ iµ ß ke∙ ha≤ beeε presseΣ o≥á not« ì Iµá datßá i≤á available¼á A=0«á I⌠ woulΣ typicall∙á bσá useΣá a≤ ì follows: CALL CST ; get status ORA A ; see if A=0 JNZ NOIN ; routine to process if no input CALL CIN ; get character and process Thσáá Conditiona∞á Inpu⌠á routine¼áá CONDIN¼áá provide≤á thσ ì function≤á jus⌠ describeΣ iε ß somewha⌠ simple≥ anΣá morσá usefu∞ ì form«á CONDI╬á wil∞á samplσá thσ consolσ inpu⌠á anΣá returεá thσ ì characte≥ iµ onσ i≤ availablσ witΦ ß flaτ sayinτ tha⌠ ß characte≥ ì i≤ returned« Iµ ß characte≥ i≤ no⌠ available¼ CONDI╬ wil∞ simpl∙ ì returεá witΦ thσ appropriatσ flag«á Thσ samσ routinσ implementeΣ ì using CONDIN looks like this: CALL CONDIN ; get conditional input JZ NOIN ; routine to process if no input ... ; process char in A from CONDIN A≤á thσ reade≥ caε see¼á wσ alread∙ havσ takeε ßá nicσá ste≡ ì forwarΣá froφ conventiona∞ assembl∙ languagσ programminτá withou⌠ ì thσ usσ oµ ß librar∙ likσ SYSLIB« ╔ thinδ tha⌠ simplσ character-ì orienteΣ input/outpu⌠ i≤ handleΣ nicel∙ now¼ anΣ thσ nex⌠ logica∞ ì ste≡ i≤ t∩ outpu⌠ ß grou≡ oµ character≤ easily«á Thi≤ i≤ donσ b∙ ì the print routines: o PRINT -- Print String Pointed to by Return Address on Console o LPRINT -- Print String Pointed to by Return Address on LST: Device o PSTR -- Print String Pointed to by HL on Console ∩ LPST╥ -- Prin⌠ Strinτ PointeΣ t∩ b∙ H╠ oε LST║ Device Thi≤á i≤ thσ firs⌠ introductioε oµ thσ concep⌠ oµ ßá string« ì Iε thσ SYSLI┬ terminology¼á ß stringô i≤ ß sequencσ oµá character≤ ì terminateΣá b∙ ß binar∙ 0«á Thσ programme≥ coulΣ definσ ß strinτ ì iε thσ followinτ ways: DB 'This is a string',0 DB 0dh,0ah,'This is another string',0dh,0ah,0 PRIN╘á anΣ LPRIN╘ prin⌠ string≤ pointeΣ t∩ b∙á thei≥á returε ì addresses¼á anΣ the∙ returε t∩ thσ bytσ followinτ thσ strinτ the∙ ì just printed. They would typically be used as follows: CALL PRINT ; Print the following string DB 'This is a test',0 ... ; Continue processing è PST╥á anΣá LPST╥á requirσ tha⌠ H╠ point≤ t∩ ßá valiΣá strinτ ì before they are called. An example of the use of PSTR is: LXI H,MYNAME ; point to string CALL PSTR ; print it ... ; continue processing MYNAME: DB 'Rick',0 ; string to be printed Warning║á PST╥ anΣ LPST╥ affec⌠ thσ H╠ registe≥ pair« Upoε ì exit¼á H╠á point≤á t∩ thσ bytσ followinτ thσá indicateΣá strings« ì Thesσá routine≤á werσá designeΣá iεá thi≤á wa∙á t∩á easil∙á allo≈ ì successive calls to them to print one string after another: LXI H,LIST ; point to first string MVI B,0 ; init counter LOOP: MOV A,M ; get first character OR┴ ┴ ╗ checδ t∩ seσ iµ lis⌠ enΣ (nex⌠ ch=0) JZ DONE ; continue processing INR B ; increment count MOV A,B ; get count CALL PADC ; print number MVI A,' ' ; print space CALL COUT CALL PSTR ; print string CALL CRLF ; print new line JMP LOOP ; continue until end of list DONE: ; continue processing ... LIST: DB 'Rick',0 ; first name in list DB 'Olivia',0 ; second name in list DB 'Carolyn',0 ; third name in list DB 0 ; end of list The output from this code segment will be: 1 Rick 2 Olivia 3 Carolyn Thi≤ examplσ i≤ intendeΣ t∩ drivσ severa∞ ke∙ point≤ homσ t∩ ì the reader: 1«á SYSLI┬ routine≤ arσ designeΣ t∩ perforφ ß functioε ì anΣ havσ minima∞ sidσ effects«á Notσ tha⌠ thσ ┬ registe≥ i≤ useΣ ì a≤ ß counte≥ iε thi≤ routine¼ anΣ ╔ don'⌠ savσ i⌠ anywhere« Nonσ ì of these SYSLIB routines have any effect on B. 2«á SYSLI┬ routine≤ arσ designeΣ t∩ bσ cohesive« The∙ ì "bonΣ togetheró t∩ forφ ß functiona∞ modulσ anΣ ma∙ bσ calleΣ onσ ì after the other to collectively provide a function for the user. 3«á SYSLI┬á ha≤á beeε designeΣ t∩ eliminatσ ßá lo⌠á oµ ì overheaΣ iε assembl∙ languagσ programming« Imaginσ ho≈ mucΦ morσ ì oµá ß programminτ tasδ i⌠ woulΣ bσ iµ yo⌡ haΣ t∩ writσá thσá PAD├ ì (Print A as Decimal Characters with Leading Spaces) routine. Which leads us into the next set of routines ...è ┴á numbe≥ oµ SYSLI┬ routine≤ arσ designeΣ t∩ outpu⌠á number≤ ì t∩á thσá user«á BotΦá 8-bi⌠ number≤ anΣ 16-bi⌠á number≤á ma∙á bσ ì output¼á anΣá iεá al∞ cases¼á thσ ┴ registe≥ contain≤á thσá 8-bi⌠ ì numbe≥á t∩á outpu⌠ anΣ thσ H╠ registe≥ pai≥ contain≤á thσá 16-bi⌠ ì number to output. These routines are: o PADC, LADC -- Print the number in the A register as up to 3 digits in PADC = Print a 3-character field. If 3 A as significant digits are not Decimal required (there are leading Characters zeroes), print spaces in their LADC = List places. PADC prints to the A as D.C. Console, LADC prints to the LST: Device o PA3DC, LA3DC -- Like PADC and LADC, but print 3 digits, including the PA3DC = Print leading zeroes A as 3 Decimal Characters o PA2HC, LA2HC -- Like PA3DC and LA3DC, but print 2 hexadecimal digits, PA2HC = Print including the leading zeroes A as 2 Hexadecimal Characters o PHLDC, LHLDC -- Print the number in the HL register pair as up to 5 PHLDC = Print digits in a 5-character H and field. If 5 significant L as digits are not required Decimal (there are leading zeroes), Characters print spaces in their places. PHLDC prints to the Console, LHLDC prints to the LST: Device o PHL5DC, LHL5DC -- Like PHLDC and LHLDC, but print 5 digits, including PHL5DC = Print the leading zeroes HL as 5 D.C. o PHL4HC, LHL5HC -- Like PHL5DC and LHL5DC, but print 4 hexadecimal digits, PHL4HC = Print including the leading zeroes HL as 4 Hex Chars è Nonσá oµá thesσá prin⌠á routine≤ havσá an∙á effect≤á oεá an∙ ì registersíá Yo⌡á ma∙ usσ theφ freel∙ t∩ prin⌠ ou⌠á values«á Thσ ì followinτ table≤ providσ example≤ oµ wha⌠ output≤ woulΣ looδ likσ ì from these routines: 8-Bit Numeric Outputs A Register PADC, LADC PA3DC, LA3DC PA2HC, LA2HC ---------- ---------- ------------ ------------ 0 __0 000 00 16 _16 016 10 100 100 100 64 255 255 255 FF 16-Bit Numeric Outputs HL Register PHLDC, LHLDC PHL5DC, LHL5DC PHL4HC, LHL4HC ----------- ------------ -------------- -------------- 0 ____0 00000 0000 16 ___16 00016 0010 100 __100 00100 0064 256 __256 00256 0100 4096 _4096 04096 1000 16536 16536 16536 4000 Note: _ denotes a space. This sample code segment: LXI H,100 ; set value CALL PRINT ; print text DB 'HL = ',0 CALL PHLDC ; print HL as decimal chars CALL PRINT ; print more text DB ' Decimal or ',0 CALL PHL4HC ; print HL as hexadecimal chars CALL PRINT ; print ending text DB ' Hexadecimal',0 ... prints this text: HL_=___100_Decimal_or_0064_Hexadecimal (Note: _ denotes a space) Thσá reade≥ caε seσ tha⌠ SYSLI┬ come≤ througΦ again¼á makinτ ì thσá joΓá nicσ anΣ easy«á Notσ tha⌠ H╠ i≤ NO╘á AFFECTE─á b∙á thσ ì numeriπá prin⌠á routine≤ (PHLDC¼á PHL4HC⌐ o≥ b∙ thσ strinτá prin⌠ ì routinσ (PRINT)« Fo≥ tha⌠ matter¼ N╧ registe≥ i≤ affecteΣ b∙ thσ ì calls to these routines. Thi≤á example¼á likσ thσ previou≤ example¼á i≤á intendeΣá t∩ ì drivσ severa∞ ke∙ point≤ homσ t∩ thσ reader: 1«á SYSLI┬ routine≤ arσ designeΣ t∩ perforφ ß functioε ì anΣ havσ minima∞ sidσ effects« 2«á SYSLI┬ routine≤ arσ designeΣ t∩ bσ cohesive« The∙ ì "bonΣ togetheró t∩ forφ ß functiona∞ modulσ anΣ ma∙ bσ calleΣ onσ ì after the other to collectively provide a function for the user. 3«á SYSLI┬á ha≤á beeε designeΣ t∩ eliminatσ ßá lo⌠á oµ ì overheaΣ iε assembl∙ languagσ programming« 4«á SYSLI┬á routine≤ arσ frequentl∙ nameΣ t∩ servσá a≤ ì mnemoniπá aid≤ iε orde≥ t∩ hel≡ thσ programme≥ remembe≥ wha⌠á thσ ì routinσ does. Flexibilit∙ i≤ ß ke∙ worΣ fo≥ SYSLIB¼á anΣ onσ gooΣ questioε ì t∩á asδ i≤ wha⌠ capabilit∙ doe≤ SYSLI┬ givσ mσ t∩ outpu⌠ m∙á numì ber≤á iε an∙ wa∙ ╔ desirσ (likσ H╠ a≤ u≡ t∩ ┤ decima∞á character≤ ì insteaΣ oµ 5)┐ Thσ nex⌠ se⌠ oµ routine≤ solve≤ thi≤ problem: o MADC -- Place up to 3 ASCII digit characters into memory which represent the number MADC = Memory in the A register and use leading (store) spaces. The first byte of a three- A as byte memory buffer is pointed to by Dec the DE register pair. Chars o MA3DC -- Like MADC, but including leading zeroes o MA2HC -- Like MA3DC, but hexadecimal digits o MHLDC -- 5 ASCII digits characters stored in memory to represent the value in HL o MHL5DC -- Like MHLDC, but including leading zeroes o MHL4HC -- Like MHL5DC, but hexadecimal digits Note║á D┼á i≤ affecteΣ b∙ thesσá routinesíá Oεá entry¼á D┼ ì point≤á t∩ thσ firs⌠ bytσ oµ thσ buffe≥ useΣ t∩ storσ thσ desireΣ ì characters¼á and¼á oε exit¼ D┼ point≤ t∩ thσ firs⌠ bytσ afte≥ thσ ì las⌠á characte≥ stored«á Thesσ routine≤ arσ se⌠ u≡ thi≤á wa∙á s∩ ì tha⌠á wholσ string≤ oµ tex⌠ caε bσ sequentiall∙ storeΣ iεá memor∙ ì with some ease. Sample Code: LXI D,NUM3 ; 3-byte buffer MVI A,10 ; Number 10 CALL MADC ; Store in Buffer LXI H,400 ; Number 400 CALL MHLDC ; Store in 5-byte buffer ... NUM3: DS 3 ; reserve 3 bytes NUM5: DS 5 ; reserve 5 bytes Results: Address ASCII Char Address ASCII Char ------- ---------- ------- ---------- NUM3 (space) NUM5 (space) NUM3+1 1 NUM5+1 (space) NUM3+2 0 NUM5+2 4 NUM5+3 0 NUM5+4 0 2.02 Math with SYSLIB MatΦá function≤ arσ particularl∙ eas∙ witΦá SYSLIB«á SYSLI┬ ì contain≤á ß wholσ modulσ oµ 16-bi⌠ matΦ function≤ whicΦ worδ witΦ ì jus⌠ thσ H╠ registe≥ pai≥ iµ onl∙ onσ argumen⌠ i≤ requireΣ o≥ thσ ì H╠ anΣ D┼ registe≥ pair≤ iµ tw∩ argument≤ arσ necessary«á Iε al∞ ì cases, the HL register pair contains the final result. Followinτá thσá genera∞ philosoph∙ oµ thσá SYSLI┬á routines¼ ì thesσ matΦ function≤ affec⌠ ONL┘ thσ H╠ registe≥ pai≥ anΣ havσ n∩ ì effec⌠ oε an∙ othe≥ registers¼á includinτ thσ ┴ registe≥ anΣá thσ ì condition code flags, unless so noted. The math functions provided in SYSLIB are: o ADDHD HL = HL + DE o SUBHD HL = HL - DE o MULHD HL = HL * DE o DIVHD HL = HL / DE o NEGH HL = 2's Complement of HL o CMPH HL = 1's Complement of HL o ANDHD HL = HL (Logical AND) DE o ORHD HL = HL (Logical OR) DE o XORHD HL = HL (Logical XOR) DE o ROTLH HL is Rotated Left one Bit The old MSB is rotated into the LSB o ROTRH HL is Rotated Right one Bit The old LSB is rotated into the MSB o SHFTLH HL is Shifted Left one Bit The LSB becomes 0 o SHFTRH HL is Shifted Right one Bit The MSB becomes 0 Note║á MS┬á anΣ LS┬ refe≥ t∩ Mos⌠ Significan⌠ Bi⌠ anΣ Leas⌠ ì Significant Bit, resp. Note║á Erro≥á Condition≤ arσ handleΣ iε ßá logica∞á manner« ì Thσ completσ description≤ oµ thesσ routine≤ founΣ iε thσ Use≥ anΣ ì Referencσ Manua∞ anΣ thσ SYSLIBx.HL╨ file≤ exactl∙ statσ wha⌠ thσ ì error conditions and return codes are. 2.03 Some Miscellaneous Routines Some miscellaneous routines contained within SYSLIB include: ∩ BDO╙ anΣ BIO╙ -- routine≤ t∩ allo≈ thσ SYSLI┬ programme≥ t∩ directl∙ acces≤ thσ CP/═ BDO╙ o≥ BIOS with minimum effect on the registers o CAPS -- capitalize the character in the A register; if a <= A reg <= z, then the capital is returned, else no change; the Most Significant Bit of A is masked out in this process and ignored o CAPSTR -- capitalize the string pointed to by HL in place: LXI H,CSTR ; point to string CALL CAPSTR ; capitalize it ... CSTR: DB 'test',0 ; initial string results in: CSTR: DB 'TEST',0 ; resulting string o CATH -- Convert ASCII to Hexadecimal; if the register A contains any one of the following ASCII characters '0'-'9', 'A'-'F', 'a'-'f' the representative hexadecimal value (binary 0-F) is returned in A; if an error occurs, the number 20 Hex is returned o CLINE -- Save the command line pointed to by HL away in an internal buffer as a string. The command line starts with a character count which is followed by the characters of the line. This is exactly the format of the line returned by ZCPR2 in the buffer at 80H and by the BDOS Fct 10. CLINE is useful when you want to work with the linσ a≤ ß strinτ anΣ no⌠ havσ t∩ worr∙ abou⌠ saving it from becoming garbaged by disk I/O. Also, CLINE returns a pointer to this line as a string terminated by a binary 0 (you don't have to worry about the character count). HL points to the first character of this string. o EN -- Exchange Nybbles in the A register; the low-order 4 bits of A are switched with the high-order 4 bits of A è o VERSION -- Return the Version Number of SYSLIB in the HL register pair o PAUSE -- Delay so many tenths of a second; inputs to this routine are the number of 1/10 secs to delay in HL and the speed of your processor in B o FILL Routines -- These routines serve to fill an area of memory pointed to by HL with a constant byte value contained in the A register; no registers are affected by FILLB and FILLBC, and only HL is affected by HFILB and HFILBC; the FILL Routines are: FILLB -- number of bytes to fill is in the B register FILLBC -- number of bytes to fill is in the BC register pair HFILB -- like FILLB, but HL is affected, and HL points to the byte following the last byte filled when done HFILBC -- like FILLBC, but HL is affected as in HFILB o MOVE Routines -- These routines copy a block of memory starting at the address contained in HL to another place in memory starting at the address contained in DE; these routines auto- matically determine if the move is forwards or backwards and compensate for any overlap; no registers are affected by MOVEB and MOVEBC, and HL and DE are affected by HMOVB and HMOVBC; the MOVE Routines are: MOVEB -- number of bytes to move in the B register MOVEBC -- number of bytes to move in the BC register pair HMOVB -- like MOVEB, but HL and DE are affected, pointing to after the last byte copied in each block HMOVBC -- like MOVEBC, but HL and DE are affected as in HMOVB o Compare Routines -- These routines are used for various types of comparisons, including simple HL-to-DE comparison, fixed-length byte compare, and subgroup comparisons. The compare routines are: COMPHD -- Compare HL to DE; on return, Zero Flag Set means HL=DE, Carry Flag Set means HL<DE COMPB and COMPBC -- Compare the group of bytes pointed to by HL to the group of bytes pointed to by DE; the groups are of equal length, being B bytes long for COMPB and BC bytes long for COMPBC; on return, Zero Flag Set means (HL)=(DE), Carry Flag Set means (HL)<(DE) SCANNER -- Scan the group of bytes pointed to by HL to see if it contains the group of bytes pointed to by DE; the HL group is B bytes long, and the DE group is C bytes long; if found, HL points to first byte of sub- group and Zero Flag is Set (Z); if not found, Zero Flag is Clear (NZ) and HL is not affected INSTR -- Scan the string pointed to by HL for the string pointed to by DE; if found, Zero Flag is Set (Z) and HL points to first byte of substring o Random Number Generator Routines -- Two routines arσ provideΣ t∩ initializσ thσ SYSLI┬ randoφ num- be≥ generato≥ anΣ onσ routinσ return≤ aε 8-bi⌠ randoφ numbe≥ froφ thσ generator. These routines are: RNDINIT -- Enters a counting loop and waits for a keypress from the user. The count value at the keypress sets the random seed. RNDSEED -- Allows the programmer to provide a seed value. This is input in the A register. RND -- Returns a random number in the A register, and uses this number as the seed value for the next call to RND. 2.04 The CODEND Routine Therσ arσ man∙ time≤ wheε i⌠ i≤ necessar∙ t∩ kno≈ wherσ you≥ ì prograφá anΣ datß area≤ enΣ anΣ thσ beginninτ oµ thσ scratcΦ areß ì whicΦ extend≤ froφ thσ enΣ oµ you≥ program/datß area≤ t∩ thσá enΣ ì oµ thσ Transien⌠ Prograφ Areß (TPA⌐ i≤ located« Thσ followinτ i≤ ì ß memor∙ ma≡ oµ thσ situatioε described: Top of Memory -------------------------- | CP/M BIOS and Buffers | -------------------------- | CP/M BDOS | / -------------------------- / | CP/M CCP | / -------------------------- T | Unused Memory Space | P | above your program | A | and its data areas | \ | ---------------- | \ | Your Program | 100H \ -------------------------- | CP/M Buffers and JMPs | Bottom of Memory -------------------------- Thσá routinσá CODEN─á iε SYSLI┬ provide≤ yo⌡á witΦá thσá enΣ ì addres≤á oµá you≥á program/datß area≤ anΣ thσá beginninτá oµá thσ ì UnuseΣ Memor∙ Spacσ diagrammeΣ above« CODEN─ i≤ ß routinσ locatì eΣ iε thσ SCODE╬ modulσ oµ SYSLIB¼á anΣ thi≤ modulσ i≤ ALWAY╙ thσ ì las⌠ modulσ iε thσ library«á Durinτ thσ linkinτ process¼á SYSLI┬ ì i≤á t∩ bσ thσ las⌠ librar∙ specifieΣ t∩ L8░ fo≥á thσá link¼á and¼ ì sincσ SCODE╬ i≤ thσ las⌠ modulσ iε SYSLIB¼á iµ thσ CODEN─ routinσ ì i≤ referenceΣ b∙ thσ program¼ theε i⌠ wil∞ bσ loaded¼ anΣ i⌠ wil∞ ì ALWAY╙á bσá thσ las⌠ subroutinσ iε you≥ program«á CODEN─á simpl∙ ì return≤á thσ addres≤ oµ thσ nex⌠ pagσ followinτ thσ las⌠ bytσá oµ ì code. Diagrammatically, the situation described looks like this: End of BDOS -------------------------- | BDOS | Start of BDOS/ -------------------------- End of Scratch | Scratch Space for your | | work area, as desired | --> Next Page After Pgm -------------------------- | | Dead Space (Not Used) | | End of Your Program -------------------------- | | CODEND Routine | | -------------------------- CODEND Returns This | Other SYSLIB Routines | Address -------------------------- | Your Program Code | 100H -------------------------- è A≤ iε thσ norma∞ CP/═ environment¼á thσ basσ oµ thσ BDO╙ caε ì bσ determineΣ b∙ loadinτ thσ addres≤ oµ thσ BDO╙ cal∞ a⌠ locatioε ì 5 into HL: LHLD 6 ; load address of BDOS call Note║ A⌠ locatioε ╡ i≤ ß CAL╠ instructioε (CAL╠ Address)¼ s∩ thσ ì desireΣá Addres≤á i≤á a⌠ location≤ ╢ anΣá 7¼á low-orde≥á bytσá a⌠ ì location 6. CODEN─á caεá bσ useΣ t∩ determinσ thσ star⌠ oµá thσá scratcΦ ì area¼á s∩á thσ followinτ codσ segmen⌠ illustrate≤ ß techniquσá t∩ ì determine the size of the scratch area. ; ; SYSLIB EXTERNAL REFERENCES -- NOTE THAT ORDER OF THESE ; EXT PSEUDO-OPS IS NOT IMPORTANT ; EXT CODEND ; CODEND ROUTINE EXT SUBHD ; HL=HL-DE EXT PRINT ; PRINT STRING EXT PHLDC ; PRINT HL AS UP TO 5 DEC CHARS ... ENTRY EQU 5 ; BDOS ENTRY CALL ... CALL CODEND ; GET ADDRESS IN HL XCHG ; ... ADDRESS IN DE LHLD ENTRY+1 ; GET ADDRESS OF BDOS BASE MVI L,0 ; SET ON PAGE BOUNDARY CALL SUBHD ; HL=HL-DE (SIZE OF SCRATCH AREA) CALL PRINT DB 'The size of the scratch area is ',0 CALL PHLDC ; PRINT IN DECIMAL CALL PRINT DB ' bytes',0 ... .fo 3 - SYSLIB Input Line Editors Page # 3.0 SYSLIB Input Line Editors 3.01 What is an Input Line Editor? Aε Inpu⌠ Linσ Edito≥ i≤ ß routinσ whicΦ i≤ ver∙á fundamenta∞ ì t∩á mos⌠á user-interactivσ program≤ anΣ timesharinτ o≥á dedicateΣ ì operatinτ systems« Thi≤ routinσ caε bσ calleΣ b∙ aε application≤ ì prograφ anΣ allo≈ thσ use≥ t∩ ente≥ ß linσ oµ tex⌠ (whicΦ i≤á wh∙ ì ╔á cal∞ i⌠ ß lineô edito≥ a≤ opposeΣ t∩ ß filσ editor⌐ anΣ correc⌠ ì hi≤ typinτ mistake≤ a≤ hσ goes. CP/═á provide≤ thσ use≥ witΦ aε inpu⌠ linσ edito≥ whicΦá ma∙ ì bσ calleΣ b∙ BDO╙ Functioε 10« Thi≤ inpu⌠ linσ edito≥ i≤ useΣ b∙ ì thσá CP/═ Consolσ CommanΣ Processo≥ (CCP⌐ itself¼á anΣá i⌠á come≤ ì int∩á pla∙ wheε thσ A╛ (o≥ whateve≥ disk⌐ promp⌠á appears«á Wheε ì thσ use≥ type≤ hi≤ CP/═ command¼ hσ i≤ withiε thσ BDO╙ inpu⌠ linσ ì editor¼á and¼á a≤á thσ reade≥ i≤ probabl∙ wel∞ aware¼á hσ ha≤ thσ ì abilit∙á t∩ deletσ thσ previou≤ character¼á erasσ thσ wholσá linσ ì anΣ star⌠ ove≥ again¼á retypσ thσ linσ a≤ entereΣ s∩ far¼á anΣ s∩ ì on. Thi≤á i≤ ß ver∙ importan⌠ kinΣ oµ function¼á and SYSLI┬ conì tain≤ threσ subroutine≤ whicΦ servσ a≤ inpu⌠ linσá editors«á Tw∩ ì oµá them¼á BLIN┼ anΣ BBLINE¼á turε arounΣ anΣ cal∞ thσ BDO╙ inpu⌠ ì linσá edito≥á anΣ mainl∙ servσ a≤ ß shel∞ arounΣ thσá BDO╙á inpu⌠ ì linσ edito≥ whicΦ preserve≤ register≤ anΣ set≤ u≡á buffers«á Thσ ì thirΣ inpu⌠ linσ editor¼á INLINE¼ i≤ ß completσ inpu⌠ linσ edito≥ ì iε it≤ owε right¼á anΣ i⌠ i≤ intendeΣ t∩ bσ useΣ wheε securit∙ i≤ ì important. 3.02 The BDOS-Based Input Line Editors Thσá tw∩á BDOS-BaseΣ inpu⌠ linσ editor≤ iε SYSLI┬ arσá BLIN┼ ì anΣ BBLINE«á The∙ diffe≥ mainl∙ iε thσ wa∙ the∙ handlσá buffers¼ ì and¼á iεá botΦ cases¼á the∙ returε witΦ H╠ pointinτ t∩ thσá firs⌠ ì characte≥á oµá thσá strinτ inpu⌠ b∙ thσ use≥ anΣ thσá ┴á registe≥ ì containinτá ßá coun⌠á oµá thσ numbe≥á oµá character≤á typeΣá (no⌠ ì countinτ thσ endinτ zero)«á Notσ tha⌠ H╠ i≤ returneΣ a≤ ß strinτ ì pointer¼ anΣ thσ inpu⌠ linσ i≤ storeΣ a≤ ß NULL-terminateΣ strinτ ì of characters in the standard SYSLIB sense. BBLIN┼á contain≤ ß 200-bytσ buffe≥ internall∙ iεá whicΦá thσ ì linσ t∩ bσ inpu⌠ i≤ stored« Thi≤ i≤ probabl∙ thσ mos⌠ frequentl∙ ì useΣá oµá thσ SYSLI┬ inpu⌠ linσ editor≤ sincσ i⌠ i≤ s∩ simplσá t∩ ì use«á It≤á onl∙ inpu⌠ i≤ ß flaτ iε thσ ┴ registe≥ -- iµ ┴ i≤á 0¼ ì thσ inpu⌠ linσ i≤ no⌠ capitalized¼á anΣ iµ ┴ i≤ no⌠ 0¼á thσ inpu⌠ ì linσ i≤ capitalized. Example: EXT BBLINE ; Reference BBLINE EXT PRINT ; PRINT STRING ROUTINE EX╘ PST╥ ╗ PRIN╘ STRIN╟ PTE─ T╧ B┘ HL ... CALL PRINT DB 'What Is Your Name? ',0 XRA A ; A=0 SO DON'T CAPITALIZE LINE CALL BBLINE ; GET LINE FROM USER ; ON RETURN, HL PTS TO FIRST CHAR ; AND A IS NUMBER OF CHARS TYPED CALL PRINT DB 0DH,0AH ; NEW LINE DB 'Your Name is: ',0 CALL PSTR ; PRINT STRING PTED TO BY HL ; ... HL WAS SET BY BBLINE ... Thσ BLIN┼ routinσ i≤ simila≥ t∩ BBLINE¼ witΦ thσ onσ differì encσ tha⌠ thσ use≥ provide≤ aε externa∞ buffer« Thσ onl∙ advantì agσ oµ BLIN┼ ove≥ BBLIN┼ i≤ tha⌠ i⌠ i≤ smalle≥ (doe≤ no⌠á contaiε ì tha⌠ 200-bytσ buffer)¼ bu⌠ witΦ BLIN┼ thσ programme≥ ha≤ t∩ worr∙ ì abou⌠ allocatinτ buffe≥ space« Thσ samσ prograφ usinτ BLINE: EXT BLINE ; Reference BLINE EXT PRINT ; PRINT STRING ROUTINE EX╘ PST╥ ╗ PRIN╘ STRIN╟ PTE─ T╧ B┘ HL ... CALL PRINT DB 'What Is Your Name? ',0 XRA A ; A=0 SO DON'T CAPITALIZE LINE LXI H,INLINE ; PT TO BUFFER CALL BLINE ; GET LINE FROM USER ; ON RETURN, HL PTS TO BUFF AND ; A IS NUMBER OF CHARS TYPED CALL PRINT DB 0DH,0AH ; NEW LINE DB 'Your Name is: ',0 CALL PSTR ; PRINT STRING PTED TO BY HL ; ... HL WAS SET BY BBLINE ... INLINE: DB 40 ; SIZE OF BUFFER DB 0 ; RETURNED SIZE OF LINE BUFF: DS 41 ; BUFFER SPACE + 1 FOR ENDING 0 3.03 The INLINE Input Line Editor INLINE¼á a≤á mentioneΣ earlier¼á i≤ intendeΣ t∩ bσ useΣá fo≥ ì securσá applications«á I⌠á ha≤ tw∩ ke∙ feature≤ whicΦ comσá int∩ ì play for such applications: 1«á INLIN┼ canno⌠ bσ aborteΣ b∙ ^C╗á thσ ^├ i≤á simpl∙ ì stored in the input line buffer if the user types it 2«á INLIN┼á caε bσ madσ t∩ ech∩ it≤ inpu⌠ o≥ no⌠á ech∩ ì it≤ input╗ iµ somethinτ likσ ß passworΣ i≤ beinτ entered¼ theε i⌠ ì may be desirable not to echo the password back to the user INLIN┼á doe≤á no⌠ perforφ optiona∞ capitalizatioεá likσá thσ ì othe≥ two¼ and¼ iµ capitalizatioε i≤ required¼ thσ CAPST╥ routinσ ì caεá bσ useΣ immediatel∙ afte≥ thσ cal∞ t∩ INLIN┼ t∩ correc⌠ thi≤ ì problem. A≤ ß tradeoff¼á INLIN┼ take≤ u≡ morσ spacσ thaε eithe≥ BLIN┼ ì o≥ BBLINE¼á anΣ thσ use≥ stil∞ ha≤ t∩ providσ aε externa∞ buffer« ì INLIN┼ wil∞ no⌠ permi⌠ morσ thaε 25╢ character≤ t∩ bσ stored¼á s∩ ì the buffer size should generally be 256+1 for the ending 0. Fo≥ inputs¼ INLIN┼ require≤ H╠ t∩ poin⌠ t∩ thσ firs⌠ bytσ oµ ì thσ buffe≥ anΣ ┴ t∩ contaiε ß ░ iµ n∩ ech∩ i≤ desireΣ o≥ no⌠ ░ iµ ì ech∩á i≤ desired«á Notσ tha⌠ INLIN┼ require≤ H╠ t∩ poin⌠ t∩á thσ ì firs⌠á bytσ oµ thσ buffe≥ itself¼á anΣ NO╘ ß buffe≥á sizσá value« ì Thσ examplσ abovσ implementeΣ witΦ INLIN┼ look≤ likσ this: EXT INLINE ; Reference INLINE EXT PRINT ; PRINT STRING ROUTINE EX╘ PST╥ ╗ PRIN╘ STRIN╟ PTE─ T╧ B┘ HL ... CALL PRINT DB 'What Is Your Password? ',0 XRA A ; A=0 SO DON'T ECHO USER INPUT LXI H,BUFF ; PT TO BUFFER CALL INLINE ; GET LINE FROM USER ; ON RETURN, HL PTS TO BUFF CALL CAPSTR ; CAPITALIZE INPUT STRING CALL PRINT DB 0DH,0AH ; NEW LINE DB 'Your Password is: ',0 CALL PSTR ; PRINT STRING PTED TO BY HL ; ... HL WAS SET BY BBLINE ... BUFF: DS 257 ; BUFFER SPACE + 1 FOR ENDING 0 .fo 4 - SYSLIB Disk Input/Output Page # 4.0 SYSLIB Disk Input/Output SYSLI┬á provide≤ ß numbe≥ oµ convenience≤ t∩ thσá programme≥ ì wheεá i⌠ come≤ t∩ manipulatinτ thσ disδ unde≥ CP/M«á Thσ librar∙ ì provide≤ fivσ group≤ oµ utilitie≤ fo≥ disδ input/output: 1. Directory Manipulation Routines -- Allocate Buffer Space -- Extract Disk Parameter Information -- Determine Amount of Free Space on Disk -- Determine the Size of a Disk File -- Load a Disk Directory into Memory -- Alphabetize a Loaded Disk Directory -- Select Files from a Loaded Disk Directory -- Pack (Compress) a Loaded Disk Directory -- Combination Utility (Load, Select, Alphabetize, and Pack a Disk Directory) 2. Block-Oriented File Input/Output -- Open, Create, and Close a File -- Delete a File -- Rename a File -- See if a File Exists -- Read and Write Blocks from and to a File 3. Byte-Oriented File Input/Output -- Open and Close a File -- Read and Write a Byte from and to a File 4. File Control Block (FCB) Manipulation -- Set Up an FCB from a String -- Initialize an FCB 5. ZCPR2-Specific Functions -- Initialize ZCPR2 SYSLIB Buffers -- Return Pointer to Next Character in Multiple Command Line -- Return Status of a ZCPR2 File -- Search for a File Along the ZCPR2 Command Path -- Determine User and Disk Referred to by a ZCPR2 Named Directory -- Find a ZCPR2 Named Directory Index File -- Set Up an FCB from a String with ZCPR2 Named Directories Permitted Notσ tha⌠ thσ las⌠ se⌠ oµ routine≤ appl∙ t∩ ZCPR2« ZCPR▓ i≤ ì ßá replacemen⌠á fo≥á thσá CP/═ CC╨á tha⌠á ╔á aφá designinτá whicΦ ì significantl∙á enhance≤á thσ powe≥ oµ thσ CC╨ anΣ give≤á i⌠á man∙ ì capabilities similar to some found in the UNIX Operating System. 4.01 Directory Manipulation Routines Thσá director∙ manipulatioε routine≤ oµ SYSLI┬ arσá designeΣ ì witΦ ß maximuφ oµ generalit∙ anΣ flexibilit∙ iε mind«á Actinτ t∩ ì relievσá thσá programme≥á oµ thσ tasδ oµ writinτá routine≤á whicΦ ì acces≤ thσ director∙ informatioε oε disk¼á thesσ routine≤á acces≤ ì thσá disδá director∙ fo≥ hiφ anΣ loaΣ it≤ content≤ int∩ ßá memor∙ ì buffer in a form which is relatively easy to use. Thσ imagσ oµ ß disδ director∙ a≤ placeΣ iε memor∙ b∙á SYSLI┬ ì is a series of 16-byte entries organized as follows: ---------------------------------------------------------- | 1 Byte | 8 Bytes | 3 Bytes | 1 Byte | 2 Bytes | 1 Byte | ---------------------------------------------------------- ^ ^ ^ ^ ^ ^ | | | | | | ---------------------------------------------------------- |User Num|File Name|File Type| Extent | Unused | Rec Cnt| ---------------------------------------------------------- Notσá tha⌠á thi≤ i≤ identica∞ t∩ thσ firs⌠ 1╢ byte≤á oµá thσ ì CP/═ director∙ entr∙ a≤ i⌠ exist≤ oε disδ anΣ i≤ specifieΣ iε thσ ì Filσ Contro∞ Blocδ (FCB)«á Notσ als∩ tha⌠ thσ firs⌠ bytσ i≤ useΣ ì t∩ indicatσ thσ Use≥ Numbe≥ associateΣ witΦ thσ file¼ anΣ NO╘ thσ ì disδ numbe≥ (a≤ thi≤ bytσ i≤ useΣ fo≥ iε thσ FCB). Beforσ thσ disδ director∙ i≤ accessed¼ however¼ i⌠ i≤ usualì l∙á ßá gooΣ ideß t∩ usσ thσ SYSLI┬ DBUFFE╥á routinσá t∩á allocatσ ì memor∙ spacσ fo≥ thσ loadeΣ director∙ entries¼á especiall∙ iµ thσ ì alphabetizatioε routinσ i≤ t∩ bσ useΣ later« Thσ DBUFFE╥ routinσ ì i≤ passeΣ ß pointe≥ t∩ ß scratcΦ memor∙ areß whicΦ extend≤ t∩ thσ ì to≡á oµ thσ TPA¼á anΣ i⌠ accesse≤ thσ disδ paramete≥ information¼ ì allocate≤ pointe≥ spacσ fo≥ thσ alphabetizatioεá routine¼á check≤ ì fo≥ Transien⌠ Prograφ Areß (TPA⌐ overflow¼á anΣ return≤ ß pointe≥ ì t∩ thσ nex⌠ availablσ bytσ afte≥ thσ pointe≥ spacσ int∩ whicΦ thσ ì director∙ i≤ t∩ bσ late≥ loaded. Thσá memor∙á addres≤ requireΣ b∙ DBUFFE╥ caεá bσá frequentl∙ ì provideΣá b∙ thσ CODEN─ routinσ (unles≤ thσ scratcΦ areßá i≤á alì read∙ beinτ useΣ b∙ thσ program¼ iε whicΦ casσ thσ programme≥ ha≤ ì t∩ providσ thi≤ valuσ froφ withiε hi≤ code)«á DBUFFE╥ anΣ CODEN─ ì fi⌠á nicel∙ togethe≥ fo≥ thi≤ purpose«á Thσ typica∞ callinτá seì quencσ look≤ likσ this: ... CALL CODEND ; HL now points to the bottom of the scratch area CALL DBUFFER ; HL now points to the bottom of the directory load area ; and A = 0 and Zero Flag is Set (Z) if TPA Overflow JZ TPAOVFL ; Handle Error and Abort ... The memory map for directory access looks like this: ------------------------------- | CP/M BDOS | Top of TPA/Bottom ------------------------------- of BDOS | Unused Space | ------------------------------- DIRLOAD or DIRSLOAD | Directory Entries (16 Bytes)| Load This -----> | are loaded here | ------------------------------- DBUFFER Computes | Pointer Space for Alphabet- | This ----------> | ization | Beginning of ------------------------------- Scratch Area | Dead Space | End of Program ------------------------------- | CODEND Routine | ------------------------------- | Other SYSLIB Routines | ------------------------------- | Programmer's Code | 100H ------------------------------- Note║á I⌠ i≤ assumeΣ tha⌠ thσ programme≥ ha≤ alread∙ loggeΣ ì iε thσ requireΣ disδ beforσ DBUFFE╥ i≤ called«á Iµ not¼ thσ disδ ì paramete≥ informatioε ma∙ bσ iεá error¼á and¼á consequently¼á inì sufficien⌠ pointe≥ spacσ ma∙ bσ allocated. DBUFFE╥ call≤ thσ routinσ DPARAM╙ t∩ determinσ thσ specific≤ ì oεá thσá CP/═ disδ structurσ anΣ thσ informatioε i⌠á require≤á t∩ ì allocatσ thσ pointe≥ space«á Iε particular¼á DPARAM╙ return≤ thσ ì maximuφ numbe≥ oµ disδ director∙ entries¼á anΣ DBUFFE╥á allocate≤ ì enougΦ pointe≥ spacσ t∩ loaΣ al∞ director∙ entrie≤ iµ necessary. DPARAM╙á extract≤ mucΦ necessar∙ informatioε fo≥ usσ b∙ SYSì LI┬ iε dealinτ witΦ disδ directories« Thσ programme≥ neeΣ no⌠ bσ ì concerneΣá witΦ exactl∙ wha⌠ thi≤ informatioεá is¼á sincσá SYSLI┬ ì use≤ i⌠ internall∙ anΣ provide≤ thσ programme≥ witΦ wha⌠ hσ need≤ ì t∩ kno≈ througΦ it≤ subroutines« Fo≥ thσ interes⌠ oµ thσ reader¼ ì however¼á thσá followinτ informatioε i≤ extracteΣ b∙ DPARAM╙á fo≥ ì interna∞ SYSLI┬ use: o Block Shift Factor o Block Mask o Extent Mask o Maximum Number of Blocks on Disk o Maximum Number of Directory Entries Thosσ reader≤ familia≥ witΦ CP/═ internal≤ ma∙ bσ interesteΣ ì t∩á kno≈ tha⌠ thi≤ i≤ al∞ oµ thσ informatioε requireΣ t∩á perforφ ì thesσá disδ functions«á DPARAM╙ als∩ determine≤ wha⌠ versioεá oµ ì CP/═ i≤ beinτ useΣ (1.┤ o≥ 2.▓ o≥ MP/M)¼ anΣ extract≤ thi≤ inforì matioεá froφ thσ BDO╙ internal≤ iµ CP/═ 1.┤ i≤ beinτ useΣ o≥ froφ ì thσ BDO╙ Functioε Call≤ iµ CP/═ 2.▓ o≥ MP/═ i≤ beinτ used« Thosσ ì reall∙ interesteΣ iε pursuinτ morσ detai∞ arσ inviteΣ t∩ reaΣ thσ ì SYSLI┬ sourcσ code.è No≈ tha⌠ thσ preliminarie≤ arσ overwitΦ anΣ thσ buffer≤ havσ ì beeε properl∙ initialized¼á thσ nex⌠ logica∞ ste≡ i≤ t∩ loaΣá thσ ì disδá directory«á Tw∩á SYSLI┬ routine≤ arσ provideΣ t∩ d∩á this║ ì DIRLOAD and DIRSLOAD. BotΦ DIRLOA─ anΣ DIRSLOA─ loaΣ thσ director∙ buffe≥á pointeΣ ì t∩á b∙á H╠ witΦ thσ entrie≤ oµ al∞ uneraseΣ file≤ oε thσ disδá iε ì al∞á use≥ area≤ oµ thσ disk«á Also¼á botΦ DIRLOA─á anΣá DIRSLOA─ ì returεá ßá flaτá iε thσ ┴ registe≥ iµ TP┴á Overflo≈á occur≤á (no⌠ ì enougΦá rooφ t∩ storσ al∞ thσ director∙ entries)¼á and¼á iµ ß TP┴ ì overflo≈ ha≤ no⌠ occurred¼ theε thσ B├ registe≥ pai≥ contain≤ thσ ì numbe≥ oµ director∙ entrie≤ loadeΣ int∩ memory. Thσá tradeofµá betweeεá DIRLOA─ anΣ DIRSLOA─á lie≤á iεá wha⌠ ì informatioεá i≤á requireΣ b∙ thσá programmer«á DIRLOA─á execute≤ ì faste≥ thaε DIRSLOAD¼á anΣ i⌠ load≤ onl∙ thσ firs⌠ entr∙ fo≥ eacΦ ì file« DIRSLOAD¼ however¼ load≤ thσ LAS╘ entr∙ fo≥ eacΦ file¼ anΣ ì iµá thσá programme≥á wishe≤á t∩ late≥ computσá thσá sizσá oµá hi≤ ì selected files, DIRSLOAD must be used instead of DIRLOAD. T∩á recap¼á DIRLOA─ anΣ DIRSLOA─ providσ thσá "proces≤á boxó ì whicΦá load≤ ß director∙ froφ disδ int∩ memory«á Ou≥á developinτ ì program now looks like this: ... CALL CODEND ; HL now points to the bottom of the scratch area CALL DBUFFER ; HL now points to the bottom of the directory load area ; and A = 0 and Zero Flag is Set (Z) if TPA Overflow JZ TPAOVFL ; Handle Error and Abort CALL DIRLOAD ; Load Disk Directory ; DIRLOAD/DIRSLOAD only affect BC, so, at this point: ; HL = address of first directory entry loaded ; BC = number of directory entries loaded if no error ; A = error flag (A=0 and Zero Flag Set if TPA Overflow) JZ TPAOVFL ; Handle Error and Abort ... No≈á tha⌠á thσ disδ director∙ ha≤ beeε loadeΣá int∩á memory¼ ì wha⌠ type≤ oµ thing≤ woulΣ onσ wan⌠ t∩ d∩ witΦ it┐ Unde≥ SYSLIB¼ ì routine≤ arσ provideΣ t∩ d∩ thσ following: o Select Entries (Match Target FCB) o Pack Directory Image (Get Rid of Unselected Entries) o Alphabetize the Directory Image o Compute Sizes of Files DIRSE╠á i≤ thσ routinσ useΣ t∩ selec⌠ entrie≤ froφ ßá loadeΣ ì disk directory. DIRSEL requires the following information: HL = address of first entry DE = address of FCB containing of desired files - only the file name and file type fields are used, so a full FCB need not be allocated - only the first 12 bytes of an FCB are required by DIRSEL, and the first byte is ignored BC = number of files in the directory A = selection flag, organized as follows: - Bit 7 = Select Non-System Files if Set - Bit 6 = Select System Files if Set - Bit 5 = Select Files in All User Areas if Set - Bits 4-0 = If Bit 5 is 0, user number (5 bits) of user area to select files from Ou≥ evolvinτ prograφ no≈ contain≤ ß DIRSE╠ cal∞ a≤ thσá nex⌠ ì logica∞ step: ... CALL CODEND ; HL now points to the bottom of the scratch area CALL DBUFFER ; HL now points to the bottom of the directory load area ; and A = 0 and Zero Flag is Set (Z) if TPA Overflow JZ TPAOVFL ; Handle Error and Abort CALL DIRLOAD ; Load Disk Directory ; DIRLOAD/DIRSLOAD only affect BC, so, at this point: ; HL = address of first directory entry loaded ; BC = number of directory entries loaded if no error ; A = error flag (A=0 and Zero Flag Set if TPA Overflow) JZ TPAOVFL ; Handle Error and Abort ; Prepare for DIRSEL Call ; HL and BC already contained values required by DIRSEL LXI D,FCB ; Point to FCB MVI A,11100000B ; Select Non-System and System ; Files in All User Areas CALL DIRSEL ; No Error Code is Returned, and ; All Registers are Unchanged; Hence, the following important ; values are retained: ; HL = address of first directory entry loaded ; BC = number of directory entres loaded ... ; ; Data Buffer Area ; FCB: DB 0 ; Just Filler DB 'ANYFIL? TXT' ; File Spec, may include wild card of ? DIRSE╠ select≤ it≤ file≤ b∙ settinτ thσ Mos⌠ Significan⌠ Bi⌠ ì oµá thσ Use≥ Numbe≥ fielΣ oµ thσ selecteΣ director∙ entrie≤ t∩á ß ì 1«á Hence¼ sincσ thi≤ i≤ al∞ tha⌠ i≤ changed¼ DIRSE╠ ma∙ bσ useΣ ì repeatedl∙á t∩ selec⌠ severa∞ group≤ oµ files¼á anΣ thesσá group≤ ì ma∙ includσ thσ samσ file≤ (MYF?┐á anΣ MYF┐ ma∙ matcΦ somσ oµ thσ ì samσ files)«á Sincσ DIRSE╠ change≤ n∩ registers¼á onσ cal∞ afte≥ ì another may be made: ... LXI D,FCB1 ; Match first set MVI A,11100000B ; Non-Sys, Sys, and All Users CALL DIRSEL LXI D,FCB2 ; Match 2nd set CALL DIRSEL ... Oncσá al∞ thσ desireΣ file≤ havσ beeε selected¼á DIRPAC╦ anΣ ì DIRNPAC╦ arσ useΣ t∩ pacδ thσ director∙ buffer¼á leavinτ iεá onl∙ ì thosσ entrie≤ desired« Iµ DIRPAC╦ i≤ used¼ entrie≤ NO╘ markeΣ b∙ ì DIRSE╠á arσ discarded¼á anΣ thσ buffe≥ i≤ reorganizeΣ t∩á contaiε ì onl∙á thosσ entrie≤ markeΣ b∙ DIRSEL«á Iµ DIRNPAC╦ i≤ used¼á enì trie≤á markeΣ b∙ DIRSE╠ arσ discardeΣ (negativσá selection)¼á anΣ ì thσá buffe≥á i≤á reorganizeΣ t∩ contaiε onl∙á thosσá entrie≤á NO╘ ì markeΣ b∙ DIRSEL. DIRPACK and DIRNPACK require the following inputs: HL = address of first entry in directory buffer BC = number of entries in directory buffer DIRPACK and DIRNPACK return the following values: HL = address of first entry in directory buffer BC = number of desired entries left in directory buffer Notσ tha⌠ onl∙ thσ B├ registe≥ pai≥ ma∙ bσ changed¼á anΣ al∞ ì othe≥ register≤ arσ no⌠ affected« Again¼ ou≥ prograφ no≈ evolve≤ ì as indicated: ... CALL CODEND ; HL now points to the bottom of the scratch area CALL DBUFFER ; HL now points to the bottom of the directory load area ; and A = 0 and Zero Flag is Set (Z) if TPA Overflow JZ TPAOVFL ; Handle Error and Abort CALL DIRLOAD ; Load Disk Directory ; DIRLOAD/DIRSLOAD only affect BC, so, at this point: ; HL = address of first directory entry loaded ; BC = number of directory entries loaded if no error ; A = error flag (A=0 and Zero Flag Set if TPA Overflow) JZ TPAOVFL ; Handle Error and Abort ; Prepare for DIRSEL Call ; HL and BC already contained values required by DIRSEL LXI D,FCB ; Point to FCB MVI A,11100000B ; Select Non-System and System ; Files in All User Areas CALL DIRSEL ; No Error Code is Returned, and ; All Registers are Unchanged; Hence, the following important ; values are retained: ; HL = address of first directory entry loaded ; BC = number of directory entries loaded CALL DIRPACK ; Pack Directory ; Only BC is changed, and now: ; BC = number of remaining (desired) directory entries ; This is typically followed by a test to see if BC=0 (no ; entries selected MOV A,B ; See if BC=0 ORA C JZ EMPTY ; Process No Selected File Routine ... ; ; Data Buffer Area ; FCB: DB 0 ; Just Filler DB 'ANYFIL? TXT' ; File Spec, may include wild card of ? Finally¼á no≈á tha⌠ wσ havσ loadeΣ thσ director∙ froφá disk¼ ì selecteΣ thσ files¼á anΣ finall∙ packeΣ thσ loadeΣ directory¼á wσ ì ma∙á wisΦ t∩ alphabetizσ thi≤ loadeΣ director∙ fo≥ easσ oµ acces≤ ì anΣ user-friendlines≤ iε ou≥ prograφ (lis⌠ thσ file≤ t∩ thσá use≥ ì alphabetically)« DIRALPH┴ i≤ thσ SYSLI┬ routinσ whicΦ doe≤ this. DIRALPH┴á require≤ thσ followinτ input≤ anΣ ha≤ n∩ effec⌠ oε ì any registers: HL = address of first directory entry BC = number of directory entries to sort A = sort flag; if A=0, sort first by file name and then by file type (HISFILE.TXT comes before MYFILE.MAC), else sort first by file type and then by file name (MYFILE.MAC comes before HISFILE.TXT) Our program has finally evolved into the following: ... CALL CODEND ; HL now points to the bottom of the scratch area CALL DBUFFER ; HL now points to the bottom of the directory load area ; and A = 0 and Zero Flag is Set (Z) if TPA Overflow JZ TPAOVFL ; Handle Error and Abort CALL DIRLOAD ; Load Disk Directory ; DIRLOAD/DIRSLOAD only affect BC, so, at this point: ; HL = address of first directory entry loaded ; BC = number of directory entries loaded if no error ; A = error flag (A=0 and Zero Flag Set if TPA Overflow) JZ TPAOVFL ; Handle Error and Abort ; Prepare for DIRSEL Call ; HL and BC already contained values required by DIRSEL LXI D,FCB ; Point to FCB MVI A,11100000B ; Select Non-System and System ; Files in All User Areas CALL DIRSEL ; No Error Code is Returned, and ; All Registers are Unchanged; Hence, the following important ; values are retained: ; HL = address of first directory entry loaded ; BC = number of directory entries loaded CALL DIRPACK ; Pack Directory ; Only BC is changed, and now: ; BC = number of remaining (desired) directory entries ; This is typically followed by a test to see if BC=0 (no ; entries selected MOV A,B ; See if BC=0 ORA C JZ EMPTY ; Process No Selected File Routine CALL DIRALPHA ; Alphabetize Directory ; No error codes are returned, and the following registers are ; significant: ; HL = address of first directory entry loaded ; BC = number of directory entries loaded ; The programmer may now continue with his specific application ... ; ; Data Buffer Area ; FCB: DB 0,'ANYFIL? TXT' ; File Spec, may include wild card of ?è A≤á thσ reade≥ caε see¼á thσ SYSLI┬ routine≤á arσá certainl∙ ì cohesivel∙ designeΣ anΣ worδ togethe≥ witΦ ß minimuφ oµ overheadí ì Sincσ thσ abovσ sequencσ oµ instruction≤ arσ s∩ frequentl∙ needeΣ ì iε exactl∙ thσ samσ order¼ ╔ havσ toppeΣ ofµ thσ SYSLI┬ director∙ ì manipulation routine module with the DIRF and DIRFS routines. DIR╞ anΣ DIRF╙ perforφ thσ followinτ operation≤ iε thσ orde≥ ì indicated: 1. Initialize Buffer Area (DBUFFER call) 2. Load the Disk Directory into the Buffer (DIRF calls DIRLOAD, DIRFS calls DIRSLOAD) 3. Select a Set of Files (DIRSEL call) 4. Pack the Files in the Memory Buffer (DIRPACK call) 5. Alphabetize the Files in the Memory Buffer (DIRALPHA call) by file name and then file type DIRF and DIRFS require the following input parameters: H╠ ╜ basσ oµ dynamiπ buffe≥ areß (a≤ returneΣ b∙ CODEND) DE = address of FCB containing file spec to match (only 1st 12 bytes required) A = selection flag, as for DIRSEL DIRF and DIRFS return the following output parameters: HL = address of first file entry BC = number of file entries A = error flag; A=0 and Zero Flag Set (Z) if TPA Overflow occurred The DIRF/DIRFS calling sequence is typically: ... EXT CODEND ; Use CODEND EXT DIRF ; Use DIRF ... CALL CODEND ; Get Scratch Area Address LXI D,FCB ; Pt to FCB MVI A,11100000B ; Non-Sys, Sys, in all User Areas CALL DIRF ; Do It! ... FCB: DB 0,'????????TXT' ; Select all TXT files ... Finally¼á thσá las⌠ tw∩ subroutine≤ availablσ iε SYSLI┬á fo≥ ì directory manipulation are DFREE and FSIZE. DFRE┼á compute≤ thσ amoun⌠ oµ freσ spacσ lef⌠ oεá disk¼á anΣ ì return≤á thi≤ valuσ (iε ╦ bytes⌐ iε DE«á N∩ othe≥ register≤á arσ ì affected«á Thσ desireΣ disδ shoulΣ bσ loggeΣ in¼á DPARAM╙ shoulΣ ì bσ calleΣ t∩ extrac⌠ thσ desireΣ informatioε fo≥ tha⌠ disk'≤ disδ ì parameter block, and then DFREE should be called. FSIZ┼á compute≤ thσ sizσ oµ thσ filσ whosσ loadeΣá director∙ ì entr∙ (mus⌠ havσ beeε loadeΣ b∙ DIRSLOA─ througΦ eithe≥ ß cal∞ t∩ ì DIRSLOA─á o≥ ß cal∞ t∩ DIRFS⌐ i≤ pointeΣ t∩ b∙ HL«á Thσ sizσá oµ ì this file in K bytes is returned as a binary number in DE. Thi≤ complete≤ thσ discussioε oµ thσ director∙á manipulatioε ì routine≤ oµ SYSLIB«á Onσ fina∞ note║á al∞ oµ thesσ routine≤ arσ ì containeΣ iε thσ SDI╥ module¼á anΣ thσ entirσ modulσ i≤ loadeΣ iµ ì an∙á onσá oµá thesσ routine≤ i≤á called«á Sincσá thσá programme≥ ì frequentl∙ want≤ t∩ usσ severa∞ oµ thesσ routine≤ iε hi≤ code¼á ╔ ì did not consider this to be an unnecessary overhead burdon. 4.02 Block-Oriented File Input/Output Thσ block-orienteΣ filσ input/outpu⌠ routine≤ oµ SYSLI┬ wil∞ ì bσá discusseΣ briefl∙ iε thi≤ documen⌠ sincσ the∙ arσ quitσ simiì la≥á t∩á thei≥ BDO╙ counterparts«á Thσ majo≥ thinτá tha⌠á SYSLI┬ ì offer≤á witΦá thesσá routine≤ i≤ no⌠ havinτ t∩á worr∙á abou⌠á thσ ì effect≤ oµ thesσ routine≤ oε registers«á Iε al∞ cases¼á onl∙ thσ ì PS╫ i≤ affecteΣ b∙ thesσ routines¼ anΣ i⌠ i≤ useΣ t∩ returε erro≥ ì codes«á Thσ Block-OrienteΣ Filσ Input/Outpu⌠ routine≤ iεá SYSLI┬ ì are: F$OPEN Open the file whose FCB is pointed to by DE Returns normal CP/M Error Code in A F$MOPEN FCB is pointed to by DE, and, if the file is not already existing, it is created; other- wise, it is just opened; Returns Error Code in A F$CLOSE Close the file whose FCB is pointed to by DE F$MAKE Create the file whose FCB is pointed to by DE F$DELETE Delete the file whose FCB is pointed to by DE F$RENAME Rename the file whose FCB is pointed to by DE to that whose FCB is pointed to by HL; only the first 12 bytes of each FCB is required; F$RENAME returns with the Zero Flag Set if the original file was not found F$EXIST Determine if the file whose FCB is pointed to b∙ D┼ exist≤ iε thσ curren⌠ disδ anΣ use≥ area; F$EXIST returns with the Zero Flag Set if the file does not exist F$READ Read Block; usual error code F$WRITE Write Block; usual error codeè Notσá tha⌠á thesσá routine≤ arσ mainl∙á reflection≤á oµá thσ ì conventiona∞ BDO╙ functions« Significan⌠ extension≤ arσ F$MOPEN¼ ì F$RENAME, and F$EXIST. Example follows: ... LXI D,FCB2 ; test for existance of file CALL F$EXIST JZ NOFILE ; ; DE Still Points to FCB of Old File ; LXI H,FCB1 ; new FCB CALL F$RENAME ; rename file ... FCB1: DB 0,'NEWFILE TXT' ; new file name FCB2: DB 0,'OLDFILE TXT' ; old file name ... 4.03 Byte-Oriented File Input/Output SYSLI┬ take≤ ß significan⌠ ste≡ beyonΣ thσ conventiona∞ CP/═ ì block-orienteΣá filσá input/outpu⌠á capabilitie≤ witΦá it≤á byte-ì orienteΣ filσ input/outpu⌠ capabilities«á Thesσ routines¼ unlikσ ì thσá other≤á whicΦ requirσ thσ use≥ t∩ reaΣ t∩ anΣ writσá froφá ß ì filσ oε ß blocδ basi≤ (12╕ byte≤ a⌠ ß time)¼ allo≈ thσ programme≥ ì t∩á reaΣ froφ anΣ writσ t∩ ß CP/═ filσ oε ß byte-for-bytσá basis« ì Thesσ routines¼ oε read¼ reaΣ iε ß blocδ a≤ requireΣ anΣ continuσ ì t∩ returε onl∙ thσ nex⌠ bytσ requesteΣ b∙ thσ programmer¼ and¼ oε ì write¼á collec⌠ u≡ t∩ 12╕ byte≤ sen⌠ ou⌠ b∙ thσ programmer¼ writσ ì tha⌠ block¼ anΣ theε continuσ collectinτ bytes. Thσá utilit∙ oµ thesσ routine≤ i≤ enhanceΣ b∙ thσ fac⌠á tha⌠ ì the∙á caε bσ useΣ withou⌠ carσ b∙ thσ programmer«á Fo≥á example¼ ì F0$PU╘á i≤ useΣ t∩ outpu⌠ onσ bytσ t∩ filσ 0¼á anΣ thσá followinτ ì samplσ codσ print≤ ß strinτ oµ byte≤ t∩ thσ console¼ printer¼ anΣ ì disk file, using SYSLIB routines: ... LXI D,FCB ; POINT TO FCB OF OUTPUT FILE CALL INITFCB ; CLEAR PROPER FCB FIELDS CALL FO0$OPEN ; OPEN FILE 0 FOR OUTPUT JZ FERR ; FILE ERROR HANDLER LXI H,STRING ; POINT TO STRING TO OUTPUT LOOP: MOV A,M ; GET NEXT CHARACTER ORA A ; END OF STRING IF 0 JZ DONE ; DONE IF END OF STRING CALL F0$PUT ; WRITE BYTE TO DISK JZ FERR CALL COUT ; WRITE BYTE TO CONSOLE CALL LOUT ; WRITE BYTE TO PRINTER INX H ; POINT TO NEXT BYTE JMP LOOP ; CONTINUE UNTIL DONE DONE: CALL FO0$CLOSE ; CLOSE OUTPUT FILE ... FERR: ; ERROR HANDLER ... FCB: DB 0,'OUTFILE TXT' ; OUTPUT FILE FCB DS 4 DS 16 DS 4 ; FOUR MORE BYTES FOR SYSLIB ... Thi≤ examplσ i≤ probabl∙ adequatσ t∩ sho≈ thσ reade≥ ho≈á t∩ ì usσá SYSLI┬á iε general«á Thσ followinτ arσ thσ SYSLI┬á routine≤ ì used to support Byte-Oriented File Input and Output: File Open for File Close for Byte-Oriented Input Output Input Output Read Write ----- ------ ----- ------ ---- ----- FI0$OPEN FO0$OPEN FI0$CLOSE FO0$CLOSE F0$GET F0$PUT FI1$OPEN FO1$OPEN FI1$CLOSE FO1$CLOSE F1$GET F1$PUT FI2$OPEN FO2$OPEN FI2$CLOSE FO2$CLOSE F2$GET F2$PUT FI3$OPEN FO3$OPEN FI3$CLOSE FO3$CLOSE F3$GET F3$PUT U≡ t∩ eigh⌠ file≤ caε bσ opeε a⌠ onσ timσ -- fou≥ fo≥á inpu⌠ ì anΣ fou≥ fo≥ output« Thσ sequencσ oµ call≤ t∩ usσ thesσ routine≤ ì is always the same: < Open Files for Input or Output > < Read or Write Bytes using GET and PUT > < Close Files for Input or Output > Thσ abovσ examplσ showeΣ ho≈ thi≤ wa≤ donσ fo≥ writinτ t∩á ß ì file«á Thσ $OPE╬ routine≤ requirσ ß 36-bytσ FC┬ whicΦ i≤ pointeΣ ì t∩ b∙ D┼ a≤ aε inpu⌠ argument¼ anΣ the∙ returε witΦ thσ Zer∩ Flaτ ì Se⌠á iµ aε erro≥ occurred«á Thσ $CLOS┼ routine≤ requirσ n∩ inpu⌠ ì argumen⌠ (the∙ kno≈ wha⌠ file≤ the∙ arσ dealinτ with)¼á anΣá the∙ ì returεá witΦá Zer∩ Flaτ Se⌠ iµ aε erro≥ occurred«á Thσ $GE╘á anΣ ì $PU╘á routine≤ onl∙ requirσ ┴ t∩ contaiε thσ characte≥ t∩á outpu⌠ ì (fo≥á thσ $PU╘ routines⌐ o≥ inpu⌠ (fo≥ thσá $GE╘á routines)¼á anΣ ì the∙ returε aε erro≥ flaτ (Zer∩ Flaτ Se⌠ iµ Error⌐ anΣ erro≥ codσ ì (iεá A⌐ iµ aε erro≥ occurs«á Iµ aε erro≥ occurs¼á ┴ return≤á thσ ì erro≥ code╗ iµ n∩ erro≥ occurs¼ ┴ i≤ unchanged. Chapte≥á ┤á oµ thσ SYSLI┬ Use≥ anΣ Referencσ Manualô give≤á ß ì little more detail, including the error code information. 4.04 File Control Block (FCB) Manipulation SYSLIB provides two simple routines for FCB manipulation. Thσ ke∙ field≤ wσ arσ interesteΣ iε aε FC┬ arσ thσ filσ namσ ì anΣ filσ typσ fields«á Thσ FC┬ useΣ b∙ SYSLI┬ i≤ alway≤ 3╢ byte≤ ì long¼ anΣ i⌠ typicall∙ declareΣ witΦ thσ followinτ code: FCB: DB 0 ; Zero Disk Number DB 'FILENAMETYP' ; File Name and Type DS 4 ; Rest of first 16 bytes DS 16 ; Second 16 bytes DS 4 ; Last required by SYSLIB Thσ firs⌠ i≤ INITFCB« Thi≤ routinσ simpl∙ clear≤ al∞ oµ thσ ì field≤ (excep⌠ thσ filσ namσ anΣ filσ typσ fields⌐ oµ thσ 36-bytσ ì FC┬ pointeΣ t∩ b∙ D┼ t∩ zero«á I⌠ i≤ ß nice¼á quicδ wa∙ t∩ initì ializσ aε FC┬ fully. Notσá tha⌠ i⌠ clear≤ thσ disδ numbe≥ fielΣ (thσ firs⌠ field⌐ ì a≤ well¼ thereb∙ selectinτ thσ curren⌠ disk« I⌠ i≤ intendeΣ tha⌠ ì thσá use≥ manuall∙ selec⌠ thσ disδ himselµ rathe≥á thaεá allowinτ ì thσ BDO╙ t∩ auto-selec⌠ ß disk. Thσ seconΣ SYSLI┬ routinσ discusseΣ herσ i≤ FNAME«á Thi≤ i≤ ì ß filσ namσ strinτ parser¼ anΣ i⌠ build≤ aε FC┬ anΣ extract≤ use≥ ì anΣá disδ informatioε froφ ß grou≡ oµ character≤ terminateΣ b∙á ß ì delimiter« Oε input¼ H╠ point≤ t∩ thσ firs⌠ bytσ oµ thσ grou≡ oµ ì character≤á anΣ D┼ point≤ t∩ thσ FCB«á Oε output¼á thσ followinτ ì regster values are returned: B = Number of Disk Specified (A=1 to P=16 or 0FFH if no disk specified) C = User Number Specified (0 to 31, '?' if all users, or 0FFH if no user specified) HL = address of delimiter which ended the scan A = error flag; A=0 and Zero Flag Set if invalid disk or user number specifiedè Scanninτá vißá FNAM┼ i≤ stoppeΣ wheε ß delimite≥ i≤á encounì tered« Thσ followinτ arσ classifieΣ b∙ SYSLI┬ a≤ delimiters: <NULL or Binary 0> <Space Character> = _ ; , < > Thσ grou≡ oµ character≤ i≤ intendeΣ t∩ bσ ß filσá specificaì tion¼ simila≥ t∩ thσ CP/═ standard« I⌠ i≤ oµ thσ genera∞ form: du:filename.typ wherσá d=disδ letter¼á u=use≥ number¼á anΣ thσ res⌠ i≤á standard« ì ValiΣá disδ letter≤ arσ A-P¼á anΣ valiΣ use≥ number≤ arσ 0-3▒ anΣ ì the '?' character. Thσá FC┬ i≤ initializeΣ b∙ thi≤ routine¼á anΣ onl∙ thσá filσ ì namσá anΣ filσ typσ field≤ arσ se⌠ (t∩ thσ filename.ty≡ part≤á oµ ì thσá string)«á Al∞ lowe≥ casσ character≤ arσ converteΣ t∩á uppe≥ ì case. Examples of valid character sequences are: Sequence Returned Values -------- --------------- test.txt File Name = TEST File Type = TXT B Reg = 0FFH C Reg = 0FFH a:t File Name = T File Type = <spaces> B Reg = 1 C Reg = 0FFH 5:.t File Name = <space> File Type = T B Reg = 0FFH C Reg = 5 c10:x*.t?t File Name = X??????? File Type = T?T B Reg = 3 C Reg = 10 FNAM┼á i≤ frequentl∙ useΣ iε processinτ use≥ input«á ┴ codσ ì examplσ is: ... CALL PRINT DB 'Name of File? ',0 CALL BBLINE ; GET NAME OF FILE FROM USER LXI D,FCB ; PT TO FCB WITH DE, HL ALREADY PTS TO ; FIRST CHAR OF FILE NAME CALL FNAME ; EXTRACT INFORMATION JZ FNERR ; ERROR HANDLER MOV A,B ; SAVE DISK NUMBER STA DISK MOV A,C ; SAVE USER NUMBER STA USER ... FCB: DS 36 ; NO INITIALIZATION NECESSARY FOR FCB DISK: DS 1 ; USER-SPECIFIED DISK NUMBER USER: DS 1 ; USER-SPECIFIED USER NUMBER ... 4.05 ZCPR2-Specific Functions ╔ aφ currentl∙ iε thσ throw≤ oµ designinτ ß ne≈ CP/═ compatì ablσá CCP-replacemen⌠á calleΣá ZCPR2¼á anΣ thσ desigεá oµá SYSLI┬ ì reflect≤ thi≤ t∩ somσ extent«á SYSLI┬ contain≤ tw∩ module≤ whicΦ ì suppor⌠á ZCPR2-specifiπ capabilities¼á anΣ thesσ module≤á contaiε ì si° SYSLIB-interna∞ buffe≥ initializatioε routine≤ anΣ si°á ZCPR▓ ì utilit∙ routines« Somσ oµ thσ reader≤ ma∙ bσ familia≥ witΦ ZCPR▒ ì (whicΦá i≤á availablσ fo≥ freσ iε Volume≤ 5┤ anΣ 7╖ oµ thσá SIG/═ ì User'≤á Group)«á Afte≥á writinτ ZCPR1¼á ╔ founΣ severa∞á oµá it≤ ì feature≤ t∩ bσ lackinτ (especiall∙ afte≥ ╔ gaineΣ somσ experiencσ ì usinτ UNIX)«á ZCPR▓ i≤ ß significan⌠ extensioε t∩ ZCPR1¼á anΣ i⌠ ì contain≤ varient≤ oµ severa∞ feature≤ founΣ iε non-CP/═ operatinτ ì systems¼ sucΦ a≤ UNIX. Giveεá thσ CP/═ memor∙ map≤ froφ beforσ (thσ reade≥á i≤á inì viteΣá t∩á refe≥ bacδ t∩ theφ iµ desired)¼á thσ followinτ i≤á thσ ì memor∙ ma≡ fo≥ ß typica∞ ZCPR2-baseΣ systeφ whicΦ support≤ al∞ oµ ì thσ extendeΣ features: Comments Size Memory Map High Memory ---------------------------- 1K | ZCPR2 Buffers, incl | (May be | Multiple Command Line | less) ---------------------------- 2K | ZCPR2 BIOS, incl special | | Cold Boot Init routines| ---------------------------- 3.5K | CP/M BDOS or other BDOS | -> ---------------------------- / 2K | ZCPR2 | Normal ZCPR2 / ---------------------------- TPA (when / 0.5K | ZEX Monitor and Buffer | ZEX is not \(Approx)| Optionally Loaded | loaded) \ ---------------------------- \ | COM File Space | \ | TPA when ZEX is | \ | loaded in with | \ | ZCPR2 | Address 100H -> ---------------------------- 0.25K | System Buffers and Entry | | Points | Address 0H ---------------------------- ╔ wil∞ no⌠ g∩ int∩ ß detaileΣ explanatioε oµ ZCPR2¼ particuì larl∙á ZEX¼á a⌠á thi≤ time«á Extensivσ detail≤ oε ZCPR▓ wil∞á bσ ì releaseΣ later. Beforσ expoundinτ oε wha⌠ thσ ZCPR2-orienteΣ SYSLI┬ routine≤ ì do¼á i⌠á woulΣá bσ ß gooΣ ideß t∩ explaiε somσá oµá thσá extendeΣ ì feature≤á oµ ZCPR▓ whicΦ arσ supporteΣ b∙ thesσ routines«á Threσ ì ZCPR▓ feature≤ arσ supporteΣ iε SYSLIB: 1. Multiple Command Lines -- ZCPR▓ caε bσ se⌠ u≡ t∩ allo≈ thσ use≥ t∩ ente≥ command lines like the following: xdir;b3:;a7:display myfile <-- run XDIR from current user/disk, log into Disk B/User 3, run DISPLAY from Disk A/User 7 on MYFILE in B3 2. Command Search Paths (File Search Paths) -- wheε ZCPR▓ receive≤ ß command¼ iµ i⌠ determine≤ tha⌠ ß commanΣ filσ (CO═ file⌐ i≤ necessar∙ t∩ executσ thσ command¼ ZCPR▓ searche≤ alonτ ß patΦ fo≥ thσ command¼ movinτ froφ onσ disδ anΣ use≥ areß t∩ anothe≥ unti∞ thσ enΣ oµ thσ patΦ i≤ reached; example is -- $$ $0 a$ a0 <-- ZCPR2 will look for file from current disk/user to cur disk/user 0 to disk A cur user to disk A/U 0 3« NameΣ Directorie≤ (ma∙ bσ implementeΣ oε conventional CP/M systems as well) -- ZCPR▓ ha≤ thσ addeΣ abilit∙ t∩ suppor⌠ ß disk/user║ forφ whereve≥ jus⌠ ß disk║ forφ wa≤ permitteΣ before╗ example≤ arσ -- a5: <-- change to disk A/User 5 b6:cmnd <-- execute command from B6 type a7:myfile <-- type file in A7 dir c11: <-- directory of C11 a: <-- change to disk A/Cur User 5: <-- change to cur disk/User 5 erß 1:myfilσ <-- erasσ filσ oε cu≥ disk/╒ 1 Thi≤ i≤ furthe≥ extendeΣ b∙ aε implementatioε oµ nameΣ directorie≤ iε CO═ filσ thr⌡ SYSLIB╗ ß directory in the ZCPR2 vernacular is a disk and use≥ areß combination¼ sucΦ a≤ disδ ┴ anΣ use≥ 5╗ sucΦ directorie≤ caε bσ giveε mnemoniπ names¼ sucΦ a≤ JEFF║ o≥ MYWORK:╗ example≤ oµ existing ZCPR2 utilities are -- xdi≥ jeff║ <-- XDI╥ oε dir named JEFF cd mytext: <-- change dir (log into) dir named MYTEXT mcopy backup:=work:*.txt <-- copy *.TXT files from WORK: to BACKUP: Beinτ iε lovσ witΦ thσ SYSLI┬ concept¼á ╔ decideΣ t∩ relievσ ì somσá oµ thσ tediou≤ ZCPR2-specifiπ codinτ requireΣ t∩á implemen⌠ ì o≥á acces≤ thesσ feature≤ froφ thσ programme≥ anΣ placσá i⌠á int∩ ì SYSLIB« Oncσ thσ whee∞ i≤ invented¼ wh∙ d∩ i⌠ again¼ right? Multiple Commands and SYSLIB Acces≤á t∩á thσá ZCPR▓ multiplσ commanΣ linσá i≤á thσá firs⌠ ì featurσ ╔ placeΣ int∩ SYSLI┬ iε thi≤ regard«á Unde≥á ZCPR2¼á thσ ì multiplσ commanΣ linσ featurσ ma∙ bσ engageΣ o≥ disengageΣ a⌠ thσ ì systeφ programmer'≤ discretion« Thσ tradeofµ fo≥ thi≤ featurσ i≤ ì that¼á iµ disengaged¼ thσ buffe≥ useΣ t∩ storσ thσ user'≤ commanΣ ì linσá i≤ storeΣ interna∞ t∩ ZCPR2¼á anΣ thi≤ prohibit≤ thσ usσ oµ ì multiplσá command≤ oε ß singlσ linσ anΣ take≤ u≡á valuablσá spacσ ì withiεá ZCPR▓ whicΦ ma∙ bσ useΣ fo≥ othe≥ options«á Iµá engaged¼ ì thσá buffe≥á useΣ t∩ storσ thσ user'≤ commanΣ linσ i≤ storeΣá exì ternall∙ t∩ ZCPR2¼á anΣ somσ codσ mus⌠ bσ placeΣ int∩ thσ BIO╙ s∩ ì tha⌠ thσ BIOS¼á oε ColΣ Boot¼ wil∞ allocatσ spacσ fo≥ thi≤ buffe≥ ì anΣ initializσ it« Onσ thinτ nicσ abou⌠ thi≤ featurσ i≤ that¼ iε ì initializinτ thi≤ buffer¼á ß startu≡ commanΣ line¼á possibl∙ conì sistinτ oµ severa∞ commands¼ caε bσ se⌠ t∩ bσ executeΣ wheneve≥ ß ì colΣ boo⌠ (systeφ startup⌐ i≤ performed. Tw∩ thing≤ mus⌠ bσ knowε b∙ thσ SYSLI┬ multiplσ commanΣ linσ ì routine║á (1⌐á i≤ thσ multiplσ commanΣ linσ featurσ engageΣá anΣ ì (2⌐á wherσá i≤ thσ multiplσ commanΣá linσá buffe≥á located┐á Thσ ì ZINIM├á routinσ initialize≤ (o≥ changes⌐ thσ interna∞ SYSLI┬ bufì fe≥á whicΦá contain≤á thσ addres≤ oµ thσá multiplσá commanΣá linσ ì buffer«á Iµá ZINIM├ i≤ called¼á i⌠ assume≤ tha⌠ H╠ contain≤á thσ ì addres≤á oµ thi≤ buffe≥ anΣ tell≤ SYSLI┬ tha⌠á multiplσá command≤ ì arσá availablσá anΣá wherσ the∙ arσ located«á Iµ ZINIM├á i≤á no⌠ ì called¼ SYSLI┬ assume≤ tha⌠ multiplσ command≤ arσ no⌠ available. Oncσá ZINIM├ ha≤ beeε called¼á thσ SYSLI┬ routinσ ZMCPT╥á i≤ ì availablσ t∩ thσ programmer« Thi≤ routinσ return≤ thσ addres≤ oµ ì thσ nex⌠ characte≥ iε thσ multiplσ commanΣ line«á Thσ programme≥ ì caεá theεá reaΣ thσ res⌠ oµ thσ curren⌠á multiplσá commanΣá line¼ ì realizinτá tha⌠ eacΦ commanΣ i≤ separateΣ b∙ ß semicoloε (;⌐á anΣ ì tha⌠á thσ entirσ linσ i≤ terminateΣ b∙ ß binar∙ 0«á ZMCPT╥á als∩ ì return≤á aε erro≥ codσ iε A¼á iε whicΦ casσ A=░ anΣ thσ Zer∩ Flaτ ì i≤ Se⌠ (Z⌐ iµ multiplσ command≤ arσ no⌠ available. To illustrate, if the multiple command line is: myprog p1;myprog p2;myprog p3 and MYPROG.COM contains the following code: ... LXI H,MCBASE ; base adr of MC line CALL ZINIMC ; init SYSLIB CAL╠ ZMCPT╥ ╗ ge⌠ ad≥ oµ firs⌠ bytσ oµ res⌠ oµ MC ; adr returned in HL CALL PRINT DB 'The rest of the command line is -- ',0 CALL PSTR ; print rest of command line, as pted ; to by HL and ending in a binary 0 ... then the command 'myprog p1' will print: The rest of the command line is -- myprog p2;myprog p3 and the command 'myprog p2' will print: The rest of the command line is -- myprog p3 External Paths and SYSLIB Thσá externa∞á pathô i≤ thσ seconΣá ZCPR▓á featurσá supporteΣ ì extensivel∙ b∙ SYSLIB« Again¼ likσ mos⌠ ZCPR▓ features¼ externa∞ ì path≤á ma∙ bσ enableΣ o≥ disableΣ a⌠ thσ discretioε oµ thσ systeφ ì programmer«á Iε orde≥ t∩ understanΣ thσ concep⌠ oµ thσá externa∞ ì path¼ thσ concep⌠ oµ thσ SYSLI┬ directoryô mus⌠ bσ understood« Iε ì thσ SYSLI┬ vernacular¼á ß directoryô i≤ ß logica∞ entit∙ oε ß disδ ì iε whicΦ file≤ arσ stored« I⌠ i≤ designateΣ witΦ aε X-┘ coordinì ate¼á thσ ╪ coordinatσ beinτ thσ namσ oµ thσ disδ (A¼ B¼ C¼ etc.⌐ ì anΣ thσ ┘ coordinatσ beinτ thσ numbe≥ oµ thσ use≥ areß (░ t∩ 31)« ì Unde≥á CP/═á 2.▓ anΣ ZCPR2¼á therσ arσ 3▓ directorie≤ oε eacΦá oµ ì you≥á disks¼á anΣá thσ overal∞ director∙ systeφá (NO╘á thσá nameΣ ì director∙ system¼ t∩ bσ discusseΣ later⌐ identifie≤ thesσ directì orie≤ b∙ thσ form du: wherσá 'dºá i≤á ß lette≥ (A-P⌐ anΣ 'uº i≤ ß use≥á numbe≥á (0-31)« ì Examples of directories are: A5: B7: A30: C12: Unde≥á CP/═ 2.▓ anΣ ZCPR2¼á distinc⌠ file≤ ma∙ bσ placeΣá iε ì eacΦá oµ thσ directorie≤ anΣ bσ handleΣ a≤ uniquσ files¼á regardì les≤á oµ thei≥ names«á Specifically¼á ß filσ nameΣ TEST.TX╘á ma∙ ì residσ iε directorie≤ A5:¼ A10:¼ A20:¼ anΣ B3:¼ anΣ therσ wil∞ bσ ì fou≥á distinc⌠ file≤ herσ b∙ thσ samσ namσá (TEST.TXT)«á Editinτ ì TEST.TX╘ iε A5║á doe≤ no⌠ changσ thσ content≤ oµ TEST.TX╘ iεá thσ ì othe≥á directories«á Onσ exceptioε t∩ thi≤ rulσá exists¼á namel∙ ì tha⌠á whicΦ occur≤ wheε thσ DUPUS╥ prograφ i≤ employed¼á anΣ thi≤ ì wil∞ bσ discusseΣ later. Unde≥ CP/═ 2.2¼á thσ utilit∙ oµ thesσ directorie≤ wa≤á someì wha⌠á limiteΣá since¼á oncσ thσ use≥ wa≤ loggeΣ int∩ ßá director∙ ì likσá A5║á (hσ issueΣ thσ commanΣ 'A:º iµ hσ wa≤ no⌠á alread∙á oε ì disδá ┴á anΣ thσ commanΣ 'USE╥ 5')¼á an∙ commanΣ hσ issueΣá whicΦ ì requireΣ ß CO═ filσ t∩ executσ i⌠ haΣ t∩ usσ ß CO═ filσ whicΦ wa≤ ì eithe≥á iε hi≤ curren⌠ director∙ o≥ oε anothe≥ disδ iεá thσá samσ ì use≥á areß (iε whicΦ casσ hσ coulΣ issuσ ß commanΣ likσ "A:PIP")« ì Hence¼á iµ hσ wanteΣ t∩ separatσ hi≤ file≤ int∩ use≥ area≤ 5¼á 6¼ ì anΣ ╖ oε disδ A║á anΣ hσ wanteΣ t∩ alway≤ havσ PI╨ available¼á hσ ì haΣ t∩ havσ ß cop∙ oµ thσ PIP.CO═ filσ iε al∞ threσ use≥ areas. Problem≤á werσ immediatel∙ recognizeΣ witΦ thi≤á environmen⌠ ì unde≥á CP/═ 2.2¼á anΣ ß prograφ calleΣ DUPUS╥ wa≤ releaseΣá whicΦ ì createΣá duplicatσ director∙ entrie≤ oµ ß filσ iε differen⌠á use≥ ì areas«á Iε thi≤ way¼ additiona∞ director∙ entrie≤ werσ takeε up¼ ì pointinτ t∩ thσ samσ file¼ bu⌠ thσ filσ itselµ diΣ no⌠ havσ t∩ bσ ì duplicateΣ iε eacΦ use≥ area«á Thi≤ wa≤ nice¼á bu⌠ i⌠ addeΣ danì gers¼ especiall∙ wheε ß filσ wa≤ changeΣ o≥ deleteΣ froφ onσ use≥ ì areß anΣ no⌠ iε al∞ thσ others«á ZCPR▒ camσ ou⌠ late≥ t∩ relievσ ì thi≤ probleφ anΣ eliminatσ thσ neeΣ fo≥ DUPUS╥ t∩ somσ extent. Unde≥ ZCPR1¼á thσ systeφ programmer¼á a⌠ installatioεá time¼ ì coulΣ configurσ ZCPR▒ t∩ d∩ ß limiteΣ director∙ searcΦ wheneve≥ ß ì CO═á filσ wa≤ t∩ bσ executed«á Thσ ZCPR▒ defaul⌠ wa≤ t∩ looδ fo≥ ì thσ CO═ filσ iε thσ curren⌠ disδ anΣ curren⌠ use≥ area¼á iµá thi≤ ì faileΣá t∩ dro≡ dowε t∩ use≥ areß ░ oε thσ curren⌠ disk¼á iµ thi≤ ì faileΣá t∩á dro≡á dowε t∩ disδ ┴ anΣ use≥ areßá 0¼á anΣá iµá thi≤ ì failed¼ t∩ issuσ thσ standarΣ erro≥ messagσ tha⌠ thσ CO═ filσ wa≤ ì no⌠á found«á DUPUS╥ anΣ it≤ associateΣ danger≤ coulΣ bσá eliminì ated¼á anΣá thσá use≥ coulΣ placσ himselµ int∩ an∙ use≥á areßá hσ ì desired¼á keepinτá al∞ oµ hi≤ systeφ utilitie≤ oε disδ ┴ iεá use≥ ì areßá 0¼á and¼á wheneve≥ hσ woulΣ issuσ ßá command¼á ZCPR▒á woulΣ ì searcΦ fo≥ it«á Thank≤ t∩ sucΦ ß concept¼ ZCPR▒ alloweΣ thσ use≥ ì t∩ creatσ ß workinτ environmen⌠ iε which¼á say¼ disδ B║ containeΣ ì al∞á oµ hi≤ workinτ file≤ anΣ disδ A:/use≥ ░ containeΣ al∞ oµ hi≤ ì CO═ files«á Hσ coulΣ issuσ an∙ commanΣ froφ an∙ use≥ areß oε B:¼ ì sa∙á froφ B5:¼á anΣ ZCPR▒ woulΣ searcΦ fo≥ thσ CO═á file¼á movinτ ì froφ B5║ t∩ B0║ t∩ A0:. Thi≤ was¼á iε m∙ opinioε (bu⌠ I'φ prejudice)¼á ß significan⌠ ì enhancemen⌠á t∩á thσ CP/═ concept«á No≈ thσ worδ disδá coulΣá bσ ì totall∙á dedicateΣ t∩ worδ file≤ (beinτ devoiΣ oµ commands⌐ whilσ ì ßá systeφá disδ coulΣ contaiε al∞ oµ thσá user'≤á commands«á Thσ ì ZCPR▒á capabilit∙ t∩ movσ froφ onσ disk/use≥ areß t∩ anothe≥á wa≤ ì nice¼á bu⌠á stil∞á somewha⌠ limited«á Thσ ZCPR▒ use≥á coulΣá no⌠ ì changσá thi≤á commanΣ searcΦ patΦ (ß pathôá being¼á iεá thσá ZCPR▓ ì definitions¼ ß vecto≥ oµ directorie≤ alonτ whicΦ ß filσ searcΦ i≤ ì performed⌐ t∩ sto≡ a⌠ A10║ insteaΣ oµ A0║ withou⌠ modifyinτ ZCPR▒ ì anΣ reinstallinτ it¼ fo≥ instance« No≥ coulΣ hσ specif∙ ß longe≥ ì path¼ sucΦ a≤ ß 4-director∙ search¼ withou⌠ somσ effort. ZCPR▓á significantl∙á extend≤ thσ commanΣ searcΦá patΦá ideß ì froφ ZCPR1« ZCPR▓ support≤ ß patΦ definition¼ whicΦ i≤ containeΣ ì iεá ß memor∙ buffer«á Thσ ZCPR▓ patΦ i≤ ß serie≤ oµ bytσá pairs¼ ì thσá firs⌠á bytσ indicatinτ thσ disδ numbe≥ anΣ thσá seconΣá bytσ ì indicatinτá thσ use≥ number¼á whicΦ ma∙ bσ oµ an∙ lengtΦá anΣá i≤ ì terminateΣ b∙ ß binar∙ 0«á Internally¼ thσ patΦ ma∙ bσ storeΣ a≤ ì ß par⌠ oµ ZCPR▓ itself¼ takinτ u≡ spacσ withiε ZCPR2¼ o≥ externa∞ ì t∩á ZCPR2¼á iε ß buffe≥ iε lo≈ memor∙ (belo≈ 100H¼á sucΦ a≤á 40H¼ ì whicΦ ╔ use⌐ o≥ iε higΦ memor∙ (abovσ thσ BIOS¼á whicΦ i≤ wherσ ╔ ì currentl∙ placσ m∙ multiplσ commanΣ linσ buffer). Iµ thσ patΦ i≤ storeΣ interna∞ t∩ ZCPR2¼ i⌠ canno⌠ typicall∙ ì bσá changeΣ b∙ thσ programme≥ iε hi≤ utilities«á Iµ thσ patΦá i≤ ì externa∞á t∩ ZCPR▓ iε ß precisely-defineΣ locatioε (knowε b∙á thσ ì systeφá programmer)¼á theεá ß programme≥ ma∙ writσá utilitie≤á t∩ ì changσá thi≤á patΦá a⌠ will¼á addinτ TON╙ oµ flexibilit∙á t∩á thσ ì system!á ZCPR2¼á wheεá i⌠ i≤ released¼á wil∞ includσá ßá commanΣ ì calleΣ PAT╚ iε it≤ distribution¼ anΣ thi≤ commanΣ allow≤ thσ use≥ ì t∩ changσ hi≤ ZCPR▓ patΦ a⌠ wil∞ t∩ anythinτ hσ desires. EacΦá director∙á specifieΣ iε thσ patΦ i≤ representeΣá b∙á ß ì bytσ pair« Thσ firs⌠ bytσ i≤ thσ disδ number¼ anΣ i⌠ ma∙ takσ oε ì value≤ froφ ▒ t∩ 1╢ (binary⌐ t∩ represen⌠ disk≤ A║á t∩ P:¼á o≥ i⌠ ì ma∙á takσ oε thσ valuσ oµ thσ characte≥ '$º (24H)¼á whicΦá stand≤ ì fo≥á thσ curren⌠ disδ (thσ disδ thσ use≥ i≤á loggeΣá into)«á Thσ ì seconΣ bytσ i≤ thσ use≥ number¼á anΣ i⌠ ma∙ takσ oε value≤ froφ ░ ì t∩ 3▒ (binary⌐ t∩ presen⌠ user≤ ░ t∩ 31«á Thσ patΦ i≤ terminateΣ ì b∙ ß binar∙ ░ (whicΦ woulΣ bσ iε thσ placσ oµ ß disδ number¼á anΣ ì ░ i≤ aε invaliΣ disδ number). A path, stored in memory, could look like this: 01H 24H 24H 00H 01H 00H 00H \ \ \ \__ End of Path \ \ \ \ \ \__ Disk A/User 0 \ \ \ \__ Current Disk/User 0 \ \__ Disk A/Current User Iεá designinτá thσá PAT╚á commanΣá oµá ZCPR2¼á ╔á havσá als∩ ì establisheΣá ßá standarΣ wa∙ t∩ represen⌠ ß ZCPR▓ patΦá iεá text« ì Thσ following¼ fo≥ example¼ i≤ ß PAT╚ commanΣ whicΦ ma∙ bσ issueΣ ì by the user to set the path in the example above: PATH A$ $0 A0 Thσá PAT╚ commanΣ wil∞ bσ discusseΣ agaiε wheε ╔ cove≥ nameΣ ì directories. Gettinτá bacδ t∩ path≤ anΣ SYSLIB¼á tw∩ SYSLI┬ utilitie≤ arσ ì provideΣá whicΦá arσá designeΣ t∩ specificall∙á dea∞á witΦá ZCPR▓ ì paths« Thesσ utilitie≤ are: ∩ ZINIEX╘ -- tel∞ SYSLI┬ thσ basσ addres≤ (addres≤ oµ the first byte) of the ZCPR2 path to be used; note that this may be the address of any path, and not necessarily that of the ZCPR2 system, so many paths may be used by different programs under ZCPR2 (such as having a path for HELP commands and another path to access special programs) ZINIEXT expects the base address of a path to be passed to it in HL; if ZINIEXT is not called, the SYSLIB routines assume that there is no path and just check the current disk/current user when called o ZPFIND -- search for a file along the current path whose base was identified by a call to ZINIEXT for the file whose FCB is pointed to by DE; B is a flag, and if B=0, search just the path, while if B<>0, search the current disk/user first and then follow the path ZPFIND returns with the Zero Flag Clear (NZ) and A=0FFH if the file is found, and the disk number of the file in B (B=0 for disk A) and the user number of the file in C (0-31) if the file is found ZPFIND leaves the user logged into the directory he was in originally before the path search began T∩ makσ lifσ eveε easie≥ fo≥ thσ SYSLI┬á programmer¼á SYSLI┬ ì provide≤á fou≥á routine≤ whicΦ manipulatσ use≥ anΣ disδ area≤á s∩ ì tha⌠á thσá programme≥ caε movσ betweeεá theφá witΦá ease«á Thesσ ì routines are: o PUTUD -- save the current disk/current user away in an internal SYSLIB buffer; PUTUD affects no registers o GETUD -- read the contents of the internal SYSLIB buffer used by PUTUD and log the user into his original disk/user; GETUD affects no registers o LOGUD -- log the user into the disk/user specified by BC; B is the disk number (B=0 for disk A) and C is the user number (0-31); no registers are affected by LOGUD o RETUD -- return the current user/disk numbers; RETUD requires no inputs, and returns B with the current disk (B=0 for disk A) and C with the current user (0-31) Notσá tha⌠ thesσ routine≤ mesΦ iε nicel∙ witΦ ZPFIND¼á whicΦ ì return≤á disδ numbe≥ iε ┬ (B=░ fo≥ disδ A⌐ anΣ use≥ numbe≥ iεá C« ì Thσ followinτ codσ illustrate≤ ho≈ thσ SYSLI┬ programme≥ ma∙á usσ ì these routines to his advantage: ... LXI H,MYPATH ; Set ZCPR2 Path Base Address CALL ZINIEXT ... LXI D,MYFCB ; Find the desired file CALL INITFCB ; Init FCB MVI B,0FFH ; Search current disk/user first CALL ZPFIND ; Search along path JZ FNF ; Routine to execute if file not found ; ; At this point, B=disk number and C=user number in which ; file was found ; CALL PUTUD ; Save current directory CALL LOGUD ; Go to file's directory < Work With File -- Detail Left Out > CALL GETUD ; Return to original directory ... FNF: ... ; Routine to process if file not found ... ; ; Path used by ZPFIND ; MYPATH: DB '$',0 ; Current disk/user 0 DB 1,'$' ; Disk A/current user DB 1,0 ; Disk A/user 0 DB 0 ; End of path ; ; FCB for desired file ; MYFCB: DB 0 DB 'MYFILE TXT' DS 4 DS 16 DS 4 ; 36 bytes long Beforσá wσ leavσ thi≤ subject¼á let'≤ hi⌠ jus⌠ ß couplσ morσ ì oµá thσ ZCPR2-specifiπ routine≤ iε SYSLI┬ whicΦ ma∙ bσ usefu∞á t∩ ì the programmer: o ZINICI -- this initializes the character used to indicate the Current User or Disk to ZCPR2; if not called, the ZCPR2 default of '$' is selected o ZINIDMA -- this initializes the DMA address for Disk I/O of the ZCPR2 utilities; if not called, the ZCPR2 default of 80H is selected o ZCPRQ -- this returns a pointer to a set of buffers which contain the following information: Bytes Contents 0 Multiple Command Buffer Available Flag; 0=no buffer 1-2 Multiple Command Buffer Address, if available 3-4 Address of External Path (pts to empty path if not initialized) 5 Current User/Disk Indicator 6-7 DMA Address o ZCPRQ2 -- this returns a pointer to a set of buffers in the 2nd ZCPR2 module of SYSLIB: Bytes Contents ░ Ma° Numbe≥ oµ NameΣ Dirs 1-2 Address of Memory-Resident Named Directory Buffer 3-38 FCB for NAMES.DIR file o ZFSTAT -- this returns the attributes of the file whose FCB is pointed to by DE; ZFSTAT returns the following information: B = System Flag (B=0 means Not Sys) C = R/O Flag (C=0 means Not R/O) A = File Found Flag (A=0 and Z mean file NOT found, so BC invalid) o ZGPINS -- General Purpose Installation; with all of these initializations to perform, I rapidly became tired of coding up an installation for SYSLIB as I wrote each ZCPR2 utility program. Hence, I added one more init utility to SYSLIB -- ZGPINS. This utility assumes the program it resides in has a set of standard ZCPR2 buffers starting at location 103H, and it completely inits SYSLIB based upon the contents of these buffers. The exact structure of these buffers will not be discussed here, but the filσ SINSFORM.MA├ iε thσ SYSLI┬ distribu- tion gives this information. Named Directories and SYSLIB Thσá thirΣá anΣá fina∞ ZCPR2-specifiπ featurσá supporteΣá b∙ ì SYSLI┬á i≤á tha⌠ oµ nameΣ directories«á Reiteratinτá ßá previou≤ ì definition¼á ßá directoryô i≤ ß logica∞ entit∙ oε ß disδ iεá whicΦ ì file≤ arσ stored« I⌠ i≤ designateΣ witΦ aε X-┘ coordinate¼ thσ ╪ ì coordinatσ beinτ thσ namσ oµ thσ disδ (A¼á B¼á C¼ etc.⌐ anΣ thσ ┘ ì coordinatσ beinτ thσ numbe≥ oµ thσ use≥ areß (░ t∩ 31)« Hence¼ ß ì director∙á woulΣ bσ somethinτ likσ disδ A/use≥ ╡ o≥á disδá B/use≥ ì 12¼á anΣ i⌠ i≤ designateΣ b∙ thσ forφ "du:ó iε thσ ZCPR▓ vernacuì lar: A5: B12: C31: D0: ┴ nameΣ directoryô unde≥ ZCPR▓ (i⌠ coulΣ als∩ bσá implementeΣ ì unde≥á CP/═á 2.▓ fo≥ tha⌠ matter¼á bu⌠ i⌠ make≤ morσ sensσá unde≥ ì ZCPR2⌐á i≤ ß director∙ whicΦ ha≤ beeε identifieΣ iε ß nameΣá dirì ector∙ filσ (sucΦ filσ calleΣ NAMES.DI╥ iε thσ ZCPR▓á vernacular⌐ ì anΣá ha≤ ß mnemoniπ namσ associateΣ witΦ it¼á likσ WOR╦ o≥á JEFF« ì Al∞á oµ thσ ZCPR▓ utilitie≤ arσ designeΣ t∩ suppor⌠ thi≤ feature¼ ì anΣ the∙ permi⌠ thσ use≥ t∩ issuσ command≤ like: XDIR WORK:*.TXT MCOPY BACKUP:=*.MAC,BACKUP:=WORK:*.TXT ERASE TEXT:DEMO.TXT,TEMP:DEMO.TMP PROTECT *.COM,ROOT:*.COM RS CD TEXT: Thσ name≤ oµ thσ director∙ arσ storeΣ iε ß file¼á standardl∙ ì calleΣ NAMES.DIR¼ whicΦ shoulΣ typicall∙ bσ locateΣ a⌠ thσ bottoφ ì oµá thσá commanΣ searcΦ patΦ oµ ZCPR▓ (thσ las⌠á director∙á ZCPR▓ ì stop≤ at)«á Wheε ß ZCPR▓ utilit∙ receive≤ ß commanΣ containinτ ß ì director∙ name¼á i⌠ searche≤ alonτ thσ ZCPR▓ patΦ fo≥á NAMES.DIR¼ ì load≤á it¼á anΣ trie≤ t∩ matcΦ thσ namσ giveε t∩ thσ name≤ storeΣ ì iε thi≤ file«á Iµ n∩ match¼á i⌠ issue≤ aε error╗á otherwise¼á i⌠ ì proceeds. Iεá orde≥á t∩á reducσá thσ overheaΣá oµá searchinτá fo≥á thσ ì NAMES.DI╥á file¼á ZCPR▓ ma∙ bσ optionall∙ configureΣ t∩ suppor⌠ ß ì memory-residen⌠á nameΣ director∙ buffer«á Iµ thi≤ i≤á done¼á thσ ì content≤ oµ ß nameΣ director∙ filσ (NAMES.DIR⌐ caε bσ loadeΣá anΣ ì storeΣ iε memory¼ and¼ oncσ thσ ZCPR▓ utilitie≤ kno≈ thi≤ (b∙ thσ ì ZFNINI╘á routine)¼á the∙á wil∞ looδ herσ beforσ goinτ oεá ßá disδ ì search«á Thi≤á dramaticall∙ reduce≤ thσ overheaΣ wheε nameΣ dirì ectorie≤ arσ referenced. Thσá ZCPR▓á utilit∙ calleΣ CHDI╥ caε bσ useΣ t∩á creatσá anΣ ì edi⌠á ßá NAMES.DI╥ file¼á a≤ wel∞ a≤ movσ froφ onσá director∙á t∩ ì another«á CHDI╥ (CHangσ DIRectory⌐ wil∞ no⌠ bσ discusseΣ iεá an∙ ì further detail in this paper. SYSLI┬áá contain≤á fou≥á routine≤á whicΦá dea∞á witΦáá nameΣ ì directories. They are: o ZFNINIT -- Init Named Directory Buffers o ZDNFIND -- Scan for Disk Directory Name o ZDNAME -- Load All Disk Directory Name Data o ZFNAME -- Named Directory File Name Scanner (like FNAME) ZFNINIT is passed four arguments: HL = address of memory-resident named directory buffer DE = address of FCB (36 bytes) containing name of disk directory file (NAMES.DIR) C = maximum number of names in NAMES.DIR A = flag which indicates the following: if Bit 7 = 1, pay attention to DE and set buffer if Bit 6 = 1, pay attention to C and set buffer if Bit 5 = 1, pay attention to HL and set buffer Iµ ZFNINI╘ i≤ no⌠ called¼á thσ namσ oµ thσ director∙ filσ i≤ ì assumeΣá t∩ bσ NAMES.DIR¼á anΣ i⌠ i≤ assumeΣ t∩ contaiε ß maximuφ ì of 64 names. ZDNAM┼á load≤á thσ content≤ oµ thσ NAMES.DI╥ filσá int∩á thσ ì memor∙ buffe≥ pointeΣ t∩ b∙ H╠ s∩ tha⌠ thσ programme≥ ma∙á acces≤ ì thi≤ informatioε a≤ hσ desires« EacΦ entr∙ iε thi≤ file¼ a≤ wel∞ ì a≤á thσá memory-baseΣ nameΣ director∙ buffer¼á i≤á structureΣá a≤ ì follows: Byte 0: Disk Number (Disk A = 0) Byte 1: User Number Bytes 2-9: Directory Name (all caps), 8 chars max, space fill at end So¼á representinτ ß NAMES.DI╥ filσ iε assembl∙ language¼ onσ ì may look like this: DB 0,0 ; disk A/user 0 DB 'ROOT ' ; directory named ROOT: DB 0,1 ; disk A/user 1 DB 'MINEWORK' ; directory named MINEWORK: DB 0,0 ; disk A/user 0 DB 0 ; no entry, so ignored DS 7 ; don't care DB 1,0 ; disk B/user 0 DB 'DEVELOPE' ; directory named DEVELOPE: ... ZDNAM┼ compresse≤ thi≤ informatioε somewhat¼á removinτ thosσ ì entrie≤ whicΦ arσ empty« Oε input¼ ZDNAM┼ expect≤ H╠ t∩ poin⌠ t∩ ì ßá dynamiπá memor∙á buffe≥ (CODEN─ i≤á gooΣá fo≥á providinτá thi≤ ì address). On output, ZDNAME provides the following: HL = address of first entry in the buffer C = number of valid entries B = 0 A = error flag (A=0 and Z if NAMES.DIR not found or memory overflow) ZDNAM┼á wil∞ d∩ al∞ thσ worδ fo≥ thσ programmer«á Wheεá inì voked¼á i⌠ searche≤ alonτ thσ patΦ fo≥ NAMES.DI╥ (startinτ a⌠ thσ ì curren⌠ disk/user)¼á log≤ int∩ thσ director∙ containinτ thσ firs⌠ ì NAMES.DI╥ i⌠ finds¼á load≤ thσ buffer¼á processe≤ thσ buffer¼ anΣ ì returns¼ leavinτ thσ prograφ loggeΣ int∩ it≤ origina∞ directory. Glancinτá a⌠ thσ SYSLI┬ referencσ manual¼á notσ tha⌠á ZDNAM┼ ì use≤ thσ FI3$OPE╬ anΣ F3$GE╘ routines«á Hence¼á thesσ shoulΣ no⌠ ì bσ useΣ b∙ thσ programmer« Als∩ notσ tha⌠ i⌠ use≤ ZPFIND¼ s∩ thσ ì programme≥á shoulΣá initializσá thσá patΦá usinτá ZINIEX╘á beforσ ì calling ZDNAME. A sample code segment using ZDNAME follows: ... LXI H,MYPATH ; set ZCPR2 path for SYSLIB CALL ZINIEXT CALL CODEND ; get beginning of scratch area in HL CALL ZDNAME ; load memory buffer JZ NERR ; process error routine ... Thσ nex⌠ SYSLI┬ routine¼á ZDNFIND¼ i≤ useΣ t∩ quickl∙ deterì minσá thσ director∙ referreΣ t∩ b∙ ß strinτ oµ character≤ oµá thσ ì forφá "du:ó o≥ "dir:ó (conventiona∞ ZCPR▓ director∙á nomenclaturσ ì o≥ ZCPR▓ nameΣ director∙ forφ allowed). ZDNFIND accepts two inputs: HL = address of first byte of DIR: or DU: prefix this prefix may be terminated by a colon (:), space, or binary 0 A = flag; if A=0, ZDNFIND does not permit the DU: form to be used and assumes that only a DIR: form is given and issues an error if it is not ZDNFIND returns these values: HL = address of character which terminated the prefix (usually the address of the colon) B = disk number (disk A = 1, or 0FFH if current disk) C = user number (0-31, or 0FFH if current user) Zero Flag Set if error è Again¼á ZDNFIN─ use≤ Bytσ Inpu⌠ Filσ 3¼á s∩ thi≤ filσ shoulΣ ì no⌠ bσ activσ wheε ZDNFIN─ i≤ called. Thσ fina∞ nameΣ director∙ routinσ iε SYSLI┬ i≤á ZFNAME«á I⌠ ì i≤á ßá filσá namσá scanner¼á likσ FNAME¼á bu⌠á i⌠á permit≤á nameΣ ì directorie≤ t∩ bσ used« Oε input¼ D┼ point≤ t∩ ß 36-bytσ FC┬ anΣ ì H╠á point≤ t∩ thσ firs⌠ bytσ oµ ß strinτ t∩ scan«á String≤á likσ ì this may be evaluated by ZFNAME: HELP:*.HLP A5:TEST.TXT C?:ABC.* PASCAL:*.COM Notσ tha⌠ thσ use≥ numbe≥ fielΣ oµ thσ DU║á forφ ma∙ contaiε ì ß questioε mark╗á thi≤ indicate≤ al∞ use≥ areas« Thσ samσ value≤ ì arσá returneΣá a≤á witΦ ZDNFIND¼á bu⌠ ├ caε als∩ takσá oεá ßá '?º ì character¼á anΣá thσ scaε i≤ terminateΣ b∙ an∙ SYSLI┬á delimiter¼ ì including: <Binary 0 or NULL> <Space> = _ ; , < > An example on the use of ZFNAME: ... LXI H,MYPATH ; SET PATH FOR ZPFIND (USED BY ZFNAME) CALL ZINIEXT ... CALL PRINT DB 'Input Your File Name: ',0 CALL BBLINE ; GET LINE FROM USER RZ ; ABORT IF EMPTY LINE ╗ H╠ NO╫ POINT╙ T╧ FIRS╘ CHA╥ O╞ LINE LXI D,FCB ; PT TO FCB CALL ZFNAME ; PARSE NAME AND GET DATA JZ FERR ; ERROR IF ZERO FLAG SET ; ; B IS NOW DISK NUMBER, C IS NOW USER NUMBER, AND HL PTS TO ; TERMINATING CHAR ... PROCESSING MAY NOW CONTINUE AS DESIRED ; ... FERR: ... ; ERROR ROUTINE ... MYPATH EQU 40H ; ZCPR2 PATH BASE FCB: DS 36 ; SYSLIB FCB ... .fo 5 - Numbers, CRC Check, and Sort Routines Page # 5.0 Numeric String Evaluation, CRC Check, and Sort Routines Thσá las⌠ threσ set≤ oµ SYSLI┬ routine≤ whicΦ remaiεá t∩á bσ ì discusseΣá dea∞ witΦ evaluatioε oµ ASCI╔ characte≥ string≤á whicΦ ì arσ intendeΣ t∩ represen⌠ number≤ (like¼ "110ó fo≥ decima∞ 11░ o≥ ì "ABCHóá fo≥á hexadecima∞ ABC)¼á performinτ erro≥á checkinτá usinτ ì Cycliπá Redundanc∙ Checδ algorithms¼á anΣ thσ SYSLI┬ general-purì posσ sor⌠ routines. 5.01 Numeric String Evaluation Recognizinτá tha⌠ i⌠ wil∞ bσ occasionall∙ necessar∙ fo≥á thσ ì programme≥ t∩ bσ ablσ t∩ accep⌠ ß numbe≥ a≤ typeΣ iε b∙ thσá use≥ ì anΣá conver⌠ i⌠ t∩ ß binar∙ forφ tha⌠ caε bσ useΣ b∙ thσ codσá oµ ì thσá program¼á ╔ havσ provideΣ SYSLI┬ witΦ ß serie≤ oµ ╡ routine≤ ì which perform such conversions. These routines are: o EVAL2 -- convert binary digit strings to binary o EVAL8 -- convert octal digit strings to binary o EVAL10 -- convert decimal digit strings to binary o EVAL16 -- convert hexadecimal digit strings to binary o EVAL -- determine base employed by user based on an optional suffix character and convert Iεá al∞á cases¼á thσ addres≤ oµ thσ firs⌠ characte≥á oµá thσ ì strinτ i≤ passeΣ t∩ thσ routinσ iε thσ H╠ registe≥ pair¼á anΣ thσ ì routinσá return≤á ß 16-bi⌠ valuσ iε D┼ anΣ aε 8-bi⌠á valuσá iεá ┴ ì (A=E)«á Evaluatioε oµ thσ strinτ progresse≤ froφ thσ firs⌠ charì acte≥á unti∞á aε invaliΣ digi⌠ (fo≥ thσ appropriatσ base⌐ i≤á enì countered¼á anΣ thσ routinσ return≤ H╠ pointinτ t∩ thσá characte≥ ì whicΦ terminateΣ thσ scan. EVAL▓á evaluate≤ binar∙ characte≥ string≤ (onl∙ '0º anΣá '1º ì arσá thσá valiΣ digits)«á String≤ likσ "1010ó arσ evaluateΣá anΣ ì converteΣ t∩ binary«á Giveε ß strinτ likσ "1010B"¼á thσá routinσ ì wil∞á sto≡ wheε i⌠ encounter≤ thσ "Bó anΣ returε witΦ H╠ pointinτ ì to this character. EVAL╕ evaluate≤ octa∞ characte≥ string≤ (onl∙ '0º t∩ '7º arσ ì thσá valiΣ digits)«á EVAL1░ evaluate≤ decima∞ characte≥á string≤ ì (onl∙á '0ºá t∩ '9º arσ thσ digits)¼á anΣ EVAL1╢á evaluate≤á hexaì decima∞ characte≥ string≤ (onl∙ '0º t∩ '9º anΣ 'Aº t∩ 'Fº arσ thσ ì digits¼ anΣ casσ i≤ no⌠ significan⌠ witΦ thσ letters). EVA╠á i≤ thσ grandadd∙ oµ thσ group¼á anΣ i⌠ accept≤ string≤ ì of the following forms: bbbbbbbbbbbbbbbbB -- b='0' or '1'; Binary string oooooooO or oooooooQ -- '0' <= o <= '7'; Octal string ttttt or tttttD -- '0' <= t <= '9'; Decimal string hhhhH or hhhhX -- '0' <= h <= 'F'; Hexadecimal string EVA╠ determine≤ thσ typσ oµ strinτ useΣ anΣ call≤ thσ approì priatσ routinσ t∩ perforφ thσ conversion« EVA╠ return≤ onσ othe≥ ì flaτ thaε thσ others╗ Carr∙ Flaτ Se⌠ mean≤ tha⌠ aε invaliΣ strinτ ì forma⌠á wa≤á given¼á anΣ H╠ point≤ t∩ thσ offendinτ characte≥á oε ì exit. Thσ followinτ i≤ aε examplσ oµ ß codσ segmen⌠ whicΦá accept≤ ì two numbers input by the user and adds them together: ... EXT PRINT ; USE SYSLIB PRINT STRING ROUTINE EXT BBLINE ; USE SYSLIB INPUT LINE EDITOR EXT PHLDC ; USE SYSLIB PRINT HL AS DEC ROUTINE EXT CRLF ; USE SYSLIB NEW LINE ROUTINE EXT EVAL ; USE SYSLIB EVAL ROUTINE ... CALL PRINT ; PROMT USER DB 'Input Your Numbers, Separated by a Comma: ',0 CALL BBLINE ; GET LINE FROM USER ; HL POINTS TO FIRST ARGUMENT CALL EVAL ; EXTRACT FIRST ARGUMENT JC NUMERR ; ERROR IF CARRY SET PUSH D ; SAVE FIRST NUMBER ON STACK MOV A,M ; GET OFFENDING CHARACTER CPI ',' ; ERROR IF IT IS NOT A COMMA JNZ CERR INX H ; SKIP OVER THE COMMA CALL EVAL ; GET THE 2ND NUMBER IN DE JC NUMERR ; PROCESS ERROR POP H ; GET FIRST NUMBER FROM STACK CALL CRLF ; NEW LINE DAD D ; HL=HL+DE CALL PRINT DB 'The sum of these numbers is ',0 CALL PHLDC ; PRINT AS DECIMAL ... A≤á thσ reade≥ caε see¼á thσ EVA╠ famil∙ oµá routine≤á make≤ ì numeriπ inpu⌠ conversioε reall∙ easy. 5.02 Cyclic Redundancy Checking Thσ SYSLI┬ CR├ routine≤ ma∙ bσ useΣ t∩ checδ thσ validit∙ oµ ì aεá incominτ seria∞ bytσ streaφ oµ arbitrar∙á length«á The∙á arσ ì particularl∙ gooΣ iε makinτ surσ tha⌠ ß giveε filσ contain≤ valiΣ ì datß o≥ tha⌠ datß transmitteΣ viß thσ phonσ line≤ (a≤ pe≥ ß modeφ ì program⌐á wa≤á correctl∙ received«á Thesσ routine≤á computσá anΣ ì checδá ß truσ 16-bi⌠ Cycliπ Redundanc∙ Codσ (CRC)¼á anΣ thei≥ usσ ì will guarantee the detection of: o all single- and double-bit errors o all errors with an odd number of error bits o all burst errors of length 16 or less Also, the CRC routines will detect the following: o 99.9969% of all 17-bit error bursts o 99.9984% of all possible longer error bursts Three sets of CRC routines are provided. They are: CRC CRC1 CRC2 Function CRCCLR CRC1CLR CRC2CLR Clear CRC Accumulator CRCUPD CRC1UPD CRC2UPD Update CRC Accumulator CRCDONE CRC1DONE CRC2DONE Done and Return CRC Value The polynomials used by these routines are: CRC = X^16 + X^12 + X^5 + 1 CRC1 = X^16 + X^15 + X^2 + 1 CRC2 = X^16 + X^15 + X^13 + X^7 + X^4 + X^2 + X + 1 Thσá SYSLI┬á programme≥ neeΣ no⌠ bσ concerneΣ witΦ ho≈á thi≤ ì polynomia∞ i≤ applieΣ internall∙ ..«á jus⌠ tha⌠ i⌠ doe≤ it≤á job« ì Thσ interesteΣ reade≥ i≤ inviteΣ t∩ examinσ thσ sourcσ code«á A≤ ì ßá sidσ note¼á CRC▓ i≤ useΣ b∙ thσ publiπ domaiε CRC╦ prograφá oµ ì KeitΦ Petersen. Thσá CRCCL╥ routinσ require≤ n∩ argument≤ anΣ return≤á none« ì It has no effect on any register. Thσá CRCUP─á routinσá update≤ thσ CR├ Accumulato≥á witΦá thσ ì valuσ oµ thσ nex⌠ byte¼á whicΦ i≤ passeΣ t∩ i⌠ iε thσ ┴ register« ì No registers are affected by this routine. Thσá CRCDON┼ routinσ return≤ thσ calculateΣ 16-bi⌠ CR├ valuσ ì iεá thσ H╠ registe≥ pair«á I⌠ simpl∙ return≤ ß valuσ anΣ ma∙á bσ ì called as many times as desired. Thσ followinτ codσ segmen⌠ illustrate≤ ß typica∞ wa∙ t∩á usσ ì these routines: ... EXT CRCCLR ; CLEAR CRC EXT CRCUPD ; UPDATE CRC EXT CRCDONE ; RETURN CRC EXT COMPHD ; COMPARE HL TO DE AND RET W/Z IF EQUAL ... ; ; ROUTINE TO COMPUTE TRANSMITTED CRC ; CRC$MAKE: CALL CRCCLR ; CLEAR ACCUMULATOR < Loop CALLing CRCUPD with Byte Values in A > CALL CRCDONE ; GET VALUE PUSH H ; SAVE IT ... ; ; ROUTINE TO EVALUATE INCOMING DATA FOR VALID CRC ; CRC$CHECK: CALL CRCCLR ; CLEAR ACCUMULATOR < Loop CALLing CRCUPD with Byte Values in A > CALL CRCDONE ; GET CRC VALUE IN HL POP D ; GET FIRST CRC VALUE IN DE CALL COMPHD ; COMPARE HL TO DE JZ OK ; PROCESS IF OK ; ; THE ERROR ROUTINE GOES HERE ; ... 5.03 The SYSLIB Sort Routines Therσáá arσá tw∩á SYSLI┬á routine≤á whicΦá givσá thσá SYSLI┬ ì programme≥á acces≤ t∩ ß ver∙ flexiblσ sortinτ system«á Thσá maiε ì routinσ i≤ calleΣ SORT¼á anΣ i⌠ provide≤ ß utilit∙ whicΦ doe≤á aε ì in-memor∙á sor⌠á oµ ß se⌠ oµ fixed-lengtΦ records«á Thσá sortinτ ì techniquσá useΣ i≤ ß Shel∞ Sort¼á adapteΣ froφ thσ booδá Softwarσ ì Toolsô b∙ Kernigaε anΣ Plaugher¼ publisheΣ b∙ Addison-Wesly¼ 1976¼ ì page 106. This sort is much faster than the simple bubble sort. Thσ SOR╘ routinσ caε bσ instructeΣ t∩ perforφ thσá in-memor∙ ì sor⌠á iεá onσá oµá tw∩ way≤ -- witΦ o≥á withou⌠á usinτá pointers« ì Sortinτá withou⌠ usinτ pointer≤ i≤ typicall∙ slowe≥ thaεá sortinτ ì witΦ pointers¼ mainl∙ becausσ wheε usinτ pointers¼ ß swa≡ i≤ donσ ì b∙á simpl∙á exchanginτ pointer≤ (▓ bytσá values)¼á whilσá ßá sor⌠ ì withou⌠á pointer≤á require≤ ß swa≡ t∩ completel∙ exchangσ thσá n-ì bytσá record≤á beinτ sorted«á Thσ onl∙ advantagσá t∩á no⌠á usinτ ì pointer≤á i≤á thσá saving≤ oµ thσ spacσ takeε u≡ b∙á thσá pointe≥ ì table« Thi≤ tablσ require≤ 2*(numbe≥ oµ entrie≤ t∩ bσ sorted⌐ iε ì bytes. Thσá SOR╘á i≤ controlleΣ b∙ passinτ ß pointe≥á t∩á thσá Sor⌠ ì Specificatioεá Blocδ (SSB⌐ iε D┼ t∩ thσ SOR╘ routine«á Thi≤ Sor⌠ ì Specificatioε Blocδ i≤ ß serie≤ oµ si° 2-bytσ word≤ whicΦ contaiε ì the following information: Bytes 0&1 -- Starting Address of 1st Record Bytes 2&3 -- Number of Records to Sort Bytes 4&5 -- Size of Each Record (in Bytes) Bytes 6&7 -- Address of Compare Routine Provided by the Programmer Bytes 8&9 -- Address of a Pointer Table (if needed) Byte 10 -- Flag; 0 means to use pointers, 0FFH not Byte 11 -- Unused Tw∩á routine≤á arσ provideΣ iε thσ SSOR╘ modulσá oµá SYSLIB« ì The∙á arσá SSBINIT¼á whicΦ i≤ useΣ t∩ initializσ buffer≤á anΣá i≤ ì describeΣ full∙ iε thσ SYSLI┬ referencσ manual¼á anΣ SORT¼á whicΦ ì perform≤ thσ actua∞ sort«á ╔ wil∞ no⌠ cove≥ SSBINI╘ herσ ..« thσ ì interested reader is invited to read the reference manual. SOR╘ accept≤ a≤ inpu⌠ ß pointe≥ t∩ aε SS┬ iε D┼ anΣ perform≤ ì thσ sort« N∩ error≤ arσ generated¼ anΣ n∩ register≤ arσ affecteΣ ì by SORT. An example of a code sequence using SORT follows: ... EXT SORT ; SORT ROUTINE IN SYSLIB ... CALL CODEND ; GET ADDRESS OF SCRATCH AREA FOR PTRS SHLD SSBPTR ; SET ADDRESS IN SSB LXI D,SSB ; POINT TO SSB CALL SORT ; DO THE SORT ... ; ; THIS IS THE COMPARE ROUTINE ; COMPARE: PUSH H ; ONLY PSW MAY BE AFFECTED PUSH D PUSH B MVI B,RECSIZ ; SIZE OF RECORDS CLOOP: LDAX D ; COMPARE (DE) TO (HL) CMP M JNZ CDONE ; RETURN WITH CARRY SET IF (DE)<(HL) INX H ; PT TO NEXT BYTE INX D DCR B ; COUNT DOWN REQUIRED NUMBER OF BYTES JNZ CLOOP CDONE: POP B ; RESTORE REGISTERS POP D POP H RET ; RETURN WITH CARRY SET IF (DE)<(HL) ; OR ZERO SET IF (DE)=(HL) ... ; ; THE SORT SPECIFICATION BLOCK DEFINES THE SORT PARAMETERS ; SSB: DW REC1 ; ADDRESS OF FIRST RECORD DW NREC ; NUMBER OF RECORDS TO SORT DW RECSIZ ; SIZE OF EACH RECORD DW COMPARE ; ADDRESS OF COMPARE ROUTINE SSBPTR: DS 2 ; ADDRESS OF POINTER TABLE, FILLED IN ; ABOVE DB 0,0 ; USE POINTERS ... ; ; THE DATA TO SORT ; REC1: DB 'THIS' ; 4-BYTE RECORDS DB 'IS ' DB 'A ' DB 'TEST' RECSIZ EQU 4 ; SIZE OF EACH RECORD NREC EQU ($-REC1)/RECSIZ ; NUMBER OF RECORDS ...è.fo 6 - What is SYSLIB? SYSLIB Overview Page # 6.0 What is SYSLIB? SYSLIB Overview Froφ thσ beginninτ oµ thi≤ document¼ SYSLI┬ (SYSteφ LIBrary⌐ ì wa≤á describeΣ a≤ ß collectioε oµ ove≥ 13░ subroutine≤ whicΦá arσ ì designeΣá t∩ providσ t∩ thσ CP/═ 8080/Z8░ assembl∙ languagσá proì gramme≥ ß se⌠ oµ function≤ upoε whicΦ hσ caε builΣ hi≤á programs« ì Thi≤ librar∙ i≤ intendeΣ t∩ relievσ thσ programme≥ oµ thσ tasδ oµ ì frequentl∙á "reinventinτá thσ wheeló anΣ t∩ providσ hiφá witΦá aε ì environmen⌠á oµá reliablσ tool≤ whicΦ encourage≤ structureΣá proì gramminτ a⌠ thσ assembl∙ languagσ level. Iε thi≤ document¼ ╔ havσ takeε yo⌡ througΦ al∞ 130½ routine≤ ì iεá SYSLIB¼á describinτá theφ iε ß functiona∞á sensσá anΣá givinτ ì example≤á a≤ t∩ ho≈ ╔ intendeΣ theφ t∩ bσ useΣ anΣ designeΣá theφ ì t∩ worδ together. 6.01 Functional Overview of SYSLIB Thσá SYSLI┬ routine≤ arσ groupeΣ int∩ ß numbe≥ oµ functiona∞ ì categories. In a nutshell, these categories are: Directory Manipulation Routines DIRF DIRFS DBUFFER DPARAMS DFREE FSIZE DIRLOAD DIRSLOAD DIRALPHA DIRSEL DIRPACK DIRNPACK Numeric String Evaluation Routines EVAL EVAL16 EVAL10 EVAL8 EVAL2 Byte-Oriented File Input/Output Routines (0<=n<=3) FIn$OPEN FOn$OPEN FIn$CLOSE FOn$CLOSE Fn$GET Fn$PUT CP/M File Input/Output Routines F$OPEN F$MOPEN F$CLOSE F$MAKE F$DELETE F$RENAME F$EXIST F$READ F$WRITE File Name String Parser and FCB Initialization FNAME INITFCB Input Line Editors BBLINE BLINE INLINE String Output Routines PRINT LPRINT PSTR LPSTR NumeriπáOutpu⌠ Routine≤ PHL4HC LHL4HC MHL4HC PHL5DC LHL5DC MHL5DC PHLDC LHLDC MHLDC PA2HC LA2HC MA2HC PA3DC LA3DC MA3DC PADC LADC MADC String and Value Comparison Routines COMPHD COMPB COMPBC SCANNER INSTR Character-Oriented Input/Output Routines CRLF LCRLF CONDIN CST CIN RIN COUT LOUT POUT CCOUT CLOUT CPOUT Math Routines ADDHD SUBHD MULHD DIVHD NEGH CMPH ROTLH ROTRH SHFTLH SHFTRH ANDHD ORHD XORHD CRC Routines CRCCLR CRC1CLR CRC2CLR CRCUPD CRC1UPD CRC2UPD CRCDONE CRC1DONE CRC2DONE Random Number Generator Routines RNDINIT RNDSEED RND User/Disk Manipulation Routines PUTUD GETUD LOGUD RETUD Sort Routines SSBINIT SORT ZCPR2 Feature-Specific Routines ZINICI ZINIDMA ZINIMC ZINIEXT ZGPINS ZCPRQ ZCPRQ2 ZMCPTR ZPFIND ZFSTAT ZCPR2-Specific Named Directory Routines ZFNINIT ZDNAME ZDNFIND ZFNAME Misπellaneous Routines BDOS BIOS CAPS CAPSTR CATH CLINE CODEND EN FILLB FILLBC HFILB HFILBC MOVEB MOVEBC HMOVB HMOVBC PAUSE VERSION 6.02 SYSLIB Documentation and Files and SYSLIB Availability SYSLI┬á documentatioε i≤ somewha⌠ extensive¼á consistinτá oµ ì (1⌐á ß 112½ pagσ SYSLI┬ Use≥ anΣ Referencσ Manualô whicΦá contain≤ ì detail≤á oε al∞ oµ thσ SYSLI┬ routine≤ anΣ ß se⌠ oµ seveεá samplσ ì programs¼á completσá witΦ ß samplσ assembl∙ anΣ ruε oµ eacΦá proì graφ anΣ (2⌐ ß se⌠ oµ 1│ HEL╨ file≤ whicΦ caε bσ accesseΣá onlinσ ì via the HELP program (new release coming out shortly to SIG/M). Thσ origina∞ SYSLIB¼á Versioε 1¼á i≤ currentl∙ availablσá iε ì Volumσ 1│ oµ thσ SIG/═ disks«á Usσ oµ thi≤ versioε i≤ no⌠ recomì mendeΣá becausσá thσ versioε describeΣ iε thi≤á documen⌠á greatl∙ ì enhance≤á thσá feature≤ oµ thσ origina∞ SYSLI┬ anΣá thσá origina∞ ì SYSLI┬ haΣ somσ problem≤ dealinτ witΦ CP/═ 2.2«á Thσ ne≈ SYSLIB¼ ì describeΣá iε thi≤ document¼á wil∞ bσ availablσ iε thσ SIG/═ libì rary. 6.03 Distribution Statement for SYSLIB SYSLI┬ i≤ releaseΣ t∩ thσ publiπ domain«á Anyonσ wh∩ wishe≤ ì t∩ US┼ i⌠ ma∙ d∩ s∩ witΦ n∩ string≤ attached« Thσ autho≥ assume≤ ì n∩á responsibilit∙á o≥ liabilit∙ fo≥ thσ usσ oµá SYSLIB«á I⌠á i≤ ì copyrighteΣ b∙ thσ author¼á RicharΣ Conn¼á wh∩ ha≤ solσ right≤ t∩ ì it«á SYSLI┬á anΣá it≤á associateΣ documentatioε ma∙ bσá solΣá b∙ ì itselµá o≥ a≤ aε independen⌠ par⌠ oµ ß packagσ oµá program≤á onl∙ ì witΦá thσ express¼á writteε consen⌠ oµ thσ author«á Thσá author¼ ì however¼ support≤ thσ usσ oµ SYSLI┬ b∙ commercia∞ softwarσ develì opers¼á anΣá place≤ n∩ restrictioε oε thσ salσ oµ program≤á whicΦ ì arσá baseΣ oε SYSLI┬ anΣ usσ routine≤ containeΣ withiε SYSLI┬á t∩ ì perforφ thei≥ majo≥ functions.