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 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: = _ ; , < > 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 = B Reg = 1 C Reg = 0FFH 5:.t File Name = 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: