home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / sigm / sigmv089.ark / SYSLIB3.HLP < prev    next >
Encoding:
Text File  |  1985-02-10  |  8.0 KB  |  174 lines
  1. Introduction fo Byte-Oriented File Input/Output Routines
  2. Byte-Oriented Input and Output File Open
  3. Byte-Oriented Input and Output File Close
  4. Byte-Oriented Input and Output
  5. Error Return Codes
  6. :Byte-Oriented File Input/Output Routines
  7.      Thσá followinτá documentatioεá cover≤ thσá serie≤á oµá byte-ì
  8. orienteΣá filσ input/outpu⌠ routine≤ iε SYSLIB«á  Thesσá routine≤ ì
  9. allo≈ thσ use≥ t∩ sequentiall∙ reaΣ froφ (GET⌐ anΣ writσ t∩ (PUT⌐ ì
  10. ß filσ oε ß byte-for-bytσ basis«á  Hence¼á thesσ routine≤ providσ ì
  11. aε exceptionall∙ simplσ methoΣ fo≥ handlinτ inpu⌠ froφ anΣ outpu⌠ ì
  12. t∩ ß file.
  13.      ┴ typica∞ prograφ whicΦ employ≤ thesσ routine≤ mus⌠ opeε thσ ì
  14. requireΣ file≤ beforσ doinτ an∙ processing¼ mus⌠ theε perforφ thσ ì
  15. processinτá oε thσ openeΣ files¼á anΣ mus⌠ theε closσá thσá file≤ ì
  16. wheεá thσá processinτ i≤ completσ (closinτ thσ file≤ i≤á optiona∞ ì
  17. fo≥ inpu⌠ file≤ anΣ mandator∙ fo≥ outpu⌠ files).
  18.      SYSLI┬ provide≤ fou≥ set≤ oµ routine≤ fo≥ byte-orienteΣ filσ ì
  19. inpu⌠ anΣ output«  Thesσ routine≤ arσ --
  20.  
  21. Input Open     Output Open     GET    PUT   Input Close  Output Close
  22. ----------     -----------     ---    --¡   -----------  ------------
  23.  FI0$OPEN       FO0$OPEN      F0$GET F0$PUT  FI0$CLOSE    FO0$CLOSE
  24.  FI1$OPEN       FO1$OPEN      F1$GET F1$PUT  FI1$CLOSE    FO1$CLOSE
  25.  FI2$OPEN       FO2$OPEN      F2$GET F2$PUT  FI2$CLOSE    FO2$CLOSE
  26.  FI3$OPEN       FO3$OPEN      F3$GET F3$PUT  FI3$CLOSE    FO3$CLOSE
  27.  
  28.      Thi≤á systeφá allow≤á thσ use≥ t∩ havσ u≡ t∩á ╕á file≤á opeε ì
  29. simultaneousl∙ -- fou≥ arσ opeε fo≥ inpu⌠ usinτ GE╘ anΣ fou≥á arσ ì
  30. opeεá fo≥á outpu⌠ usinτ PUT«á  Fo≥ example¼á thσ followinτá i≤á ß ì
  31. samplσ codσ sectioε usinτ thesσ routine≤ fo≥ tw∩ files:
  32.  
  33.  
  34.           EXT  FI0$OPEN   ; DECLARE LIBRARY REFERENCES
  35.           EXT  FO0$OPEN
  36.           EXT  FI0$CLOSE
  37.           EXT  FO0$CLOSE
  38.           EXT  F0$GET
  39.           EXT  F0$PUT
  40.           ...
  41.           LXI  D,FCBI    ; PT TO FCB OF INPUT FILE
  42.           CALL FI0$OPEN
  43.           LXI  D,FCBO    ; PT TO FCB OF OUTPUT FILE
  44.           CALL FO0$OPEN
  45.           ...
  46.           [body containing CALL F0$GET and CALL F0$PUT where required]
  47.           ...
  48.           CALL FI0$CLOSE  ; CLOSE FILE
  49.           CALL FO0$CLOSE
  50.           ...
  51.           END
  52.      Notσ tha⌠ onl∙ thσ routine≤ t∩ bσ useΣ arσ referenceΣ iε thσ ì
  53. EX╘ statements«á  Iµ yo⌡ d∩ no⌠ neeΣ ß particula≥ routine¼ d∩ no⌠ ì
  54. referencσá it«á  No⌠á referencinτ aε unneedeΣá routinσá generall∙ ì
  55. save≤ thσ overheaΣ memor∙ spacσ oµ loadinτ i⌠ froφ thσ library.
  56.      EacΦ se⌠ oµ INPU╘ OPEN¼á INPU╘ CLOSE¼á OUTPU╘á OPEN¼á OUTPU╘ ì
  57. CLOSE¼á GET¼ anΣ PU╘ routine≤ i≤ containeΣ iε onσ librar∙ module¼ ì
  58. s∩á referencinτ an∙ oµ thesσ routine≤ cause≤ thσ entirσ modulσ t∩ ì
  59. bσá loaded¼á anΣá al∞á thσ routine≤ arσ accessablσá t∩á thσá use≥ ì
  60. (provideΣ the∙ arσ mentioneΣ iε thσ externa∞ definitions⌐ withou⌠ ì
  61. an∙áá additiona∞á memor∙áá overhead«áá  Specifically¼áá FI0$OPEN¼ ì
  62. FI0$CLOSE¼á FO0$OPEN¼ FO0$CLOSE¼ F0$GET¼ anΣ F0$PU╘ arσ containeΣ ì
  63. iε onσ module¼á anΣ referencσ t∩ an∙ oµ thesσ routine≤ load≤á thσ ì
  64. entirσ module╗ thσ samσ i≤ truσ fo≥ thσ othe≥ set≤ oµ routines.
  65.      Thσ CLOS┼ routinσ fo≥ outpu⌠ (FOn$CLOSE⌐ i≤ ALWAY╙ required╗ ì
  66. i⌠á fill≤á thσ res⌠ oµ thσ curren⌠ blocδ witΦ Ctrl-┌ followeΣá b∙ ì
  67. <NULL╛á byte≤ anΣ properl∙ close≤ file«á  Thσ CLOS┼á routinσá fo≥ ì
  68. inpu⌠ (FIn$CLOSE⌐ i≤ requireΣ ONL┘ I╞ yo⌡ arσ goinτ t∩ late≥ opeε ì
  69. anothe≥á filσá fo≥á inpu⌠ usinτ thσá correspondinτá OPE╬á routinσ ì
  70. (FIn$OPEN)«á  FIn$CLOS┼á onl∙ serve≤ t∩ rese⌠ thσ OPE╬ flaτ (useΣ ì
  71. t∩ GE╘ t∩ ascertaiε tha⌠ thσ filσ ha≤ beeε properl∙ opened).
  72. :FI$OPEN and FO$OPEN, et al -- Byte-Oriented Input and Output File Open
  73.      Routine Names:  FI0$OPEN, FI1$OPEN, FI2$OPEN, FI3$OPEN
  74.      Function║
  75.           Opeεá thσ filσ whosσ FC┬ i≤ pointeΣ t∩ b∙ D┼ fo≥á inpu⌠ ì
  76. (usσá witΦá F$GET)«á  FIn$OPE╬á initialize≤ thσá FC┬á fields¼á s∩ ì
  77. further initialization is not necessary.
  78.      Inputs:  DE = ptr to FCB of file to open
  79.      Outputs:  Z Flag is Error Indicator, A is Error Code
  80.      Registers Affected:  PSW
  81.      SYSLIB Routines Called:  Internal
  82.      Special Error Conditions:  See Section on Error Codes
  83.  
  84.      Routine Names:  FO0$OPEN, FO1$OPEN, FO2$OPEN, FO3$OPEN
  85.      Function║
  86.           Opeε thσ filσ whosσ FC┬ i≤ pointeΣ t∩ b∙ D┼ fo≥á outpu⌠ ì
  87. (usσá witΦá F$PUT)«á  FOn$OPE╬ initialize≤á thσá FC┬á fields¼á s∩ ì
  88. furthe≥á initializatioεá i≤ no⌠ necessary«á  I⌠ als∩ create≤á thσ ì
  89. indicated file if it does not already exist.
  90.      Inputs:  DE = ptr to FCB of file to open
  91.      Outputs:  Z Flag is Error Indicator, A is Error Code
  92.      Registers Affected:  PSW
  93.      SYSLIB Routines Called:  Internal
  94.      Special Error Conditions:  See Section on Error Codes
  95. :FI$CLOSE and FO$CLOSE, et al -- Byte-Oriented Input and Output File Close
  96.      Routine Names:  FI0$CLOSE, FI1$CLOSE, FI2$CLOSE, FI3$CLOSE
  97.      Function║
  98.           Closσá thσ filσ previousl∙ openeΣ b∙ thσá correspondinτ ì
  99. FI$OPE╬á routine«á  Usσá oµá thesσ routine≤ i≤á optiona∞á iµá thσ ì
  100. anothe≥á filσá wil∞á no⌠ bσ openeΣ late≥ iε thσá prograφá b∙á thσ ì
  101. correspondinτ FI$OPE╬ routine.
  102.      Inputs:  -None-
  103.      Outputs:  Z Flag is Error Indicator, A is Error Code
  104.      Registers Affected:  PSW
  105.      SYSLIB Routines Called:  Internal
  106.      Specia∞ Erro≥ Conditions:  See Section on Error Codes
  107.  
  108.      Routine Names:  FO0$CLOSE, FO1$CLOSE, FO2$CLOSE, FO3$CLOSE
  109.      Function║
  110.           Closσá thσ filσ previousl∙ openeΣ b∙ thσá correspondinτ ì
  111. FO$OPE╬ routine«  Usσ oµ thesσ routine≤ i≤ MANDATOR┘ afte≥ outpu⌠ ì
  112. t∩ thσ filσ (usinτ thσ correspondinτ F$PU╘ routine⌐ i≤ complete.
  113.      Inputs:  -None-
  114.      Outputs:  Z Flag is Error Indicator, A is Error Code
  115.      Registers Affected:  -None-
  116.      SYSLIB Routines Called:  Internal
  117.      Specia∞ Erro≥ Conditions:  See Section on Error Codes
  118. :F$GET and F$PUT, et al -- Byte-Oriented Input and Output
  119.      Routine Names:  F0$GET, F1$GET, F2$GET, F3$GET
  120.      Function║
  121.           Ge⌠ thσ nex⌠ bytσ iε sequencσ froφ thσ filσá previousl∙ ì
  122. openeΣ b∙ thσ correspondinτ FI$OPE╬ routine«  Bytσ i≤ returneΣ iε ì
  123. Registe≥ A.
  124.      Inputs:  -None-
  125.      Outputs:  A = Next byte from file if no error
  126.                If Error, NZ and A = Error Code
  127.      Registers Affected:  PSW
  128.      SYSLIB Routines Called:  Internal
  129.      Specia∞ Erro≥ Conditions:  See Section on Error Codes
  130.  
  131.      Routine Names:  F0$PUT, F1$PUT, F2$PUT, F3$PUT
  132.      Function║
  133.           Pu⌠á thσá bytσ iε Registe≥ ┴ ont∩ thσ enΣ oµá thσá filσ ì
  134. previousl∙ openeΣ b∙ thσ correspondinτ FO$OPE╬ routine.
  135.      Inputs:  A = Byte to PUT
  136.      Outputs:  Z Flag is Error Indicator, A is Error Code
  137.      Registers Affected:  PSW
  138.      SYSLIB Routines Called:  Internal
  139.      Specia∞á Erro≥ Conditions║  See Section on Error Codes
  140. :Error Return Codes
  141.  
  142.      Fo≥á eacΦ oµ thσ routine≤ iε thi≤ se⌠ oµ byte-orienteΣá filσ ì
  143. I/╧ routines¼ thσ Zer∩ Flaτ anΣ thσ ┴ Registe≥ pla∙ ß ke∙ rolσ iε ì
  144. indicating the error conditions of the routines.
  145.  
  146.      Iµá thσá Zer∩á Flaτá i≤ Se⌠ (Z⌐ afte≥á ßá routinσá ha≤á beeε ì
  147. executed¼á theε thi≤ indicate≤ tha⌠ n∩ erro≥ ha≤ occurred«  Thσ ┴ ì
  148. Registe≥á i≤á eithe≥á unaffecteΣ (iε mos⌠ cases⌐á o≥á contain≤á ß ì
  149. returned value (if so indicated, as in Fn$GET routines).
  150.  
  151.      Iµá thσá Zer∩ Flaτ i≤ Clea≥ (NZ⌐ afte≥ ßá routinσá ha≤á beeε ì
  152. executed¼á theε thi≤ indicate≤ tha⌠ aε erro≥ ha≤ occurred«  Thσ ┴ ì
  153. Registe≥á no≈á contain≤á thσ Erro≥á Code«á  Thσá followinτá tablσ ì
  154. summarize≤á thσá Erro≥á Code≤á whicΦ ma∙ bσá returneΣá iεá thσá ┴ ì
  155. Register.
  156.  
  157.      The following screen display summarizes the Error Codes.
  158.  
  159.  
  160.                      Summary of Error Codes
  161.            Returned by Byte-Oriented File I/O Routines
  162.  
  163.           Code Meaning
  164.           ---- -------
  165.  
  166.             1  GET or PUT attempted on an unopened file
  167.             2  Disk Full (Ran out of space)
  168.             3  Input File Not Found
  169.             4  Attempt to Read Past EOF
  170.             5  Directory Full
  171.             6  Error in Closing a File
  172.             7  Attempt to Open a File which is already Open
  173.  
  174.