CP/M/CPM_CDROM.iso/simtel/sigm/vols000/vol089/syslib3.hlp

Text File | 1985-02-09 | 8KB | 174 lines

Introduction fo Byte-Oriented File Input/Output Routines
Byte-Oriented Input and Output File Open
Byte-Oriented Input and Output File Close
Byte-Oriented Input and Output
Error Return Codes
:Byte-Oriented File Input/Output Routines
     Thσá followinτá documentatioεá cover≤ thσá serie≤á oµá byte-ì
orienteΣá filσ input/outpu⌠ routine≤ iε SYSLIB«á  Thesσá routine≤ ì
allo≈ thσ use≥ t∩ sequentiall∙ reaΣ froφ (GET⌐ anΣ writσ t∩ (PUT⌐ ì
ß filσ oε ß byte-for-bytσ basis«á  Hence¼á thesσ routine≤ providσ ì
aε exceptionall∙ simplσ methoΣ fo≥ handlinτ inpu⌠ froφ anΣ outpu⌠ ì
t∩ ß file.
     ┴ typica∞ prograφ whicΦ employ≤ thesσ routine≤ mus⌠ opeε thσ ì
requireΣ file≤ beforσ doinτ an∙ processing¼ mus⌠ theε perforφ thσ ì
processinτá oε thσ openeΣ files¼á anΣ mus⌠ theε closσá thσá file≤ ì
wheεá thσá processinτ i≤ completσ (closinτ thσ file≤ i≤á optiona∞ ì
fo≥ inpu⌠ file≤ anΣ mandator∙ fo≥ outpu⌠ files).
     SYSLI┬ provide≤ fou≥ set≤ oµ routine≤ fo≥ byte-orienteΣ filσ ì
inpu⌠ anΣ output«  Thesσ routine≤ arσ --

Input Open     Output Open     GET    PUT   Input Close  Output Close
----------     -----------     ---    --¡   -----------  ------------
 FI0$OPEN       FO0$OPEN      F0$GET F0$PUT  FI0$CLOSE    FO0$CLOSE
 FI1$OPEN       FO1$OPEN      F1$GET F1$PUT  FI1$CLOSE    FO1$CLOSE
 FI2$OPEN       FO2$OPEN      F2$GET F2$PUT  FI2$CLOSE    FO2$CLOSE
 FI3$OPEN       FO3$OPEN      F3$GET F3$PUT  FI3$CLOSE    FO3$CLOSE

     Thi≤á systeφá allow≤á thσ use≥ t∩ havσ u≡ t∩á ╕á file≤á opeε ì
simultaneousl∙ -- fou≥ arσ opeε fo≥ inpu⌠ usinτ GE╘ anΣ fou≥á arσ ì
opeεá fo≥á outpu⌠ usinτ PUT«á  Fo≥ example¼á thσ followinτá i≤á ß ì
samplσ codσ sectioε usinτ thesσ routine≤ fo≥ tw∩ files:


          EXT  FI0$OPEN   ; DECLARE LIBRARY REFERENCES
          EXT  FO0$OPEN
          EXT  FI0$CLOSE
          EXT  FO0$CLOSE
          EXT  F0$GET
          EXT  F0$PUT
          ...
          LXI  D,FCBI    ; PT TO FCB OF INPUT FILE
          CALL FI0$OPEN
          LXI  D,FCBO    ; PT TO FCB OF OUTPUT FILE
          CALL FO0$OPEN
          ...
          [body containing CALL F0$GET and CALL F0$PUT where required]
          ...
          CALL FI0$CLOSE  ; CLOSE FILE
          CALL FO0$CLOSE
          ...
          END
     Notσ tha⌠ onl∙ thσ routine≤ t∩ bσ useΣ arσ referenceΣ iε thσ ì
EX╘ statements«á  Iµ yo⌡ d∩ no⌠ neeΣ ß particula≥ routine¼ d∩ no⌠ ì
referencσá it«á  No⌠á referencinτ aε unneedeΣá routinσá generall∙ ì
save≤ thσ overheaΣ memor∙ spacσ oµ loadinτ i⌠ froφ thσ library.
     EacΦ se⌠ oµ INPU╘ OPEN¼á INPU╘ CLOSE¼á OUTPU╘á OPEN¼á OUTPU╘ ì
CLOSE¼á GET¼ anΣ PU╘ routine≤ i≤ containeΣ iε onσ librar∙ module¼ ì
s∩á referencinτ an∙ oµ thesσ routine≤ cause≤ thσ entirσ modulσ t∩ ì
bσá loaded¼á anΣá al∞á thσ routine≤ arσ accessablσá t∩á thσá use≥ ì
(provideΣ the∙ arσ mentioneΣ iε thσ externa∞ definitions⌐ withou⌠ ì
an∙áá additiona∞á memor∙áá overhead«áá  Specifically¼áá FI0$OPEN¼ ì
FI0$CLOSE¼á FO0$OPEN¼ FO0$CLOSE¼ F0$GET¼ anΣ F0$PU╘ arσ containeΣ ì
iε onσ module¼á anΣ referencσ t∩ an∙ oµ thesσ routine≤ load≤á thσ ì
entirσ module╗ thσ samσ i≤ truσ fo≥ thσ othe≥ set≤ oµ routines.
     Thσ CLOS┼ routinσ fo≥ outpu⌠ (FOn$CLOSE⌐ i≤ ALWAY╙ required╗ ì
i⌠á fill≤á thσ res⌠ oµ thσ curren⌠ blocδ witΦ Ctrl-┌ followeΣá b∙ ì
<NULL╛á byte≤ anΣ properl∙ close≤ file«á  Thσ CLOS┼á routinσá fo≥ ì
inpu⌠ (FIn$CLOSE⌐ i≤ requireΣ ONL┘ I╞ yo⌡ arσ goinτ t∩ late≥ opeε ì
anothe≥á filσá fo≥á inpu⌠ usinτ thσá correspondinτá OPE╬á routinσ ì
(FIn$OPEN)«á  FIn$CLOS┼á onl∙ serve≤ t∩ rese⌠ thσ OPE╬ flaτ (useΣ ì
t∩ GE╘ t∩ ascertaiε tha⌠ thσ filσ ha≤ beeε properl∙ opened).
:FI$OPEN and FO$OPEN, et al -- Byte-Oriented Input and Output File Open
     Routine Names:  FI0$OPEN, FI1$OPEN, FI2$OPEN, FI3$OPEN
     Function║
          Opeεá thσ filσ whosσ FC┬ i≤ pointeΣ t∩ b∙ D┼ fo≥á inpu⌠ ì
(usσá witΦá F$GET)«á  FIn$OPE╬á initialize≤ thσá FC┬á fields¼á s∩ ì
further initialization is not necessary.
     Inputs:  DE = ptr to FCB of file to open
     Outputs:  Z Flag is Error Indicator, A is Error Code
     Registers Affected:  PSW
     SYSLIB Routines Called:  Internal
     Special Error Conditions:  See Section on Error Codes

     Routine Names:  FO0$OPEN, FO1$OPEN, FO2$OPEN, FO3$OPEN
     Function║
          Opeε thσ filσ whosσ FC┬ i≤ pointeΣ t∩ b∙ D┼ fo≥á outpu⌠ ì
(usσá witΦá F$PUT)«á  FOn$OPE╬ initialize≤á thσá FC┬á fields¼á s∩ ì
furthe≥á initializatioεá i≤ no⌠ necessary«á  I⌠ als∩ create≤á thσ ì
indicated file if it does not already exist.
     Inputs:  DE = ptr to FCB of file to open
     Outputs:  Z Flag is Error Indicator, A is Error Code
     Registers Affected:  PSW
     SYSLIB Routines Called:  Internal
     Special Error Conditions:  See Section on Error Codes
:FI$CLOSE and FO$CLOSE, et al -- Byte-Oriented Input and Output File Close
     Routine Names:  FI0$CLOSE, FI1$CLOSE, FI2$CLOSE, FI3$CLOSE
     Function║
          Closσá thσ filσ previousl∙ openeΣ b∙ thσá correspondinτ ì
FI$OPE╬á routine«á  Usσá oµá thesσ routine≤ i≤á optiona∞á iµá thσ ì
anothe≥á filσá wil∞á no⌠ bσ openeΣ late≥ iε thσá prograφá b∙á thσ ì
correspondinτ FI$OPE╬ routine.
     Inputs:  -None-
     Outputs:  Z Flag is Error Indicator, A is Error Code
     Registers Affected:  PSW
     SYSLIB Routines Called:  Internal
     Specia∞ Erro≥ Conditions:  See Section on Error Codes

     Routine Names:  FO0$CLOSE, FO1$CLOSE, FO2$CLOSE, FO3$CLOSE
     Function║
          Closσá thσ filσ previousl∙ openeΣ b∙ thσá correspondinτ ì
FO$OPE╬ routine«  Usσ oµ thesσ routine≤ i≤ MANDATOR┘ afte≥ outpu⌠ ì
t∩ thσ filσ (usinτ thσ correspondinτ F$PU╘ routine⌐ i≤ complete.
     Inputs:  -None-
     Outputs:  Z Flag is Error Indicator, A is Error Code
     Registers Affected:  -None-
     SYSLIB Routines Called:  Internal
     Specia∞ Erro≥ Conditions:  See Section on Error Codes
:F$GET and F$PUT, et al -- Byte-Oriented Input and Output
     Routine Names:  F0$GET, F1$GET, F2$GET, F3$GET
     Function║
          Ge⌠ thσ nex⌠ bytσ iε sequencσ froφ thσ filσá previousl∙ ì
openeΣ b∙ thσ correspondinτ FI$OPE╬ routine«  Bytσ i≤ returneΣ iε ì
Registe≥ A.
     Inputs:  -None-
     Outputs:  A = Next byte from file if no error
               If Error, NZ and A = Error Code
     Registers Affected:  PSW
     SYSLIB Routines Called:  Internal
     Specia∞ Erro≥ Conditions:  See Section on Error Codes

     Routine Names:  F0$PUT, F1$PUT, F2$PUT, F3$PUT
     Function║
          Pu⌠á thσá bytσ iε Registe≥ ┴ ont∩ thσ enΣ oµá thσá filσ ì
previousl∙ openeΣ b∙ thσ correspondinτ FO$OPE╬ routine.
     Inputs:  A = Byte to PUT
     Outputs:  Z Flag is Error Indicator, A is Error Code
     Registers Affected:  PSW
     SYSLIB Routines Called:  Internal
     Specia∞á Erro≥ Conditions║  See Section on Error Codes
:Error Return Codes

     Fo≥á eacΦ oµ thσ routine≤ iε thi≤ se⌠ oµ byte-orienteΣá filσ ì
I/╧ routines¼ thσ Zer∩ Flaτ anΣ thσ ┴ Registe≥ pla∙ ß ke∙ rolσ iε ì
indicating the error conditions of the routines.

     Iµá thσá Zer∩á Flaτá i≤ Se⌠ (Z⌐ afte≥á ßá routinσá ha≤á beeε ì
executed¼á theε thi≤ indicate≤ tha⌠ n∩ erro≥ ha≤ occurred«  Thσ ┴ ì
Registe≥á i≤á eithe≥á unaffecteΣ (iε mos⌠ cases⌐á o≥á contain≤á ß ì
returned value (if so indicated, as in Fn$GET routines).

     Iµá thσá Zer∩ Flaτ i≤ Clea≥ (NZ⌐ afte≥ ßá routinσá ha≤á beeε ì
executed¼á theε thi≤ indicate≤ tha⌠ aε erro≥ ha≤ occurred«  Thσ ┴ ì
Registe≥á no≈á contain≤á thσ Erro≥á Code«á  Thσá followinτá tablσ ì
summarize≤á thσá Erro≥á Code≤á whicΦ ma∙ bσá returneΣá iεá thσá ┴ ì
Register.

     The following screen display summarizes the Error Codes.


                     Summary of Error Codes
           Returned by Byte-Oriented File I/O Routines

          Code Meaning
          ---- -------

            1  GET or PUT attempted on an unopened file
            2  Disk Full (Ran out of space)
            3  Input File Not Found
            4  Attempt to Read Past EOF
            5  Directory Full
            6  Error in Closing a File
            7  Attempt to Open a File which is already Open