home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / turbopas / extfn.ark / EXTFN.DOC next >
Encoding:
Text File  |  1989-09-27  |  11.4 KB  |  262 lines
  1. .PL
  2.  
  3.      Description of the unit EXTFN
  4.  
  5.  
  6.  
  7.  
  8.      1.  Introduction.
  9.  
  10.         In utilities like NSWEEP and in ZCPR, one can address files in any  user 
  11.      area  by including the user area number in the file name.  Such file  names 
  12.      are called extended file names, as they (may) contain the user area  number 
  13.      between the drive name and the colon.  For CP/M diehards using Turbo Pascal 
  14.      3.0, a package of procedures in EXTFN.UNT are made available, which provide 
  15.      the possibility to specify extended file names, like 'A9:FILE.BOO', in a TP 
  16.      program.
  17.  
  18.         All the necessary definitions are gathered into one file.  The structure 
  19.      of  this file resembles a UNIT as introduced in TP 4.0, with  an  interface 
  20.      section  and an implementation section, but despite this comment it  is  an 
  21.      ordinary include file.
  22.  
  23.  
  24.      2.  Functional description.
  25.  
  26.         The function of the package is to enable the pascal programmer to access 
  27.      files in any user area, in the understanding that each of the (open)  files 
  28.      can  be located in different user areas.  Moreover, this function  must  be 
  29.      independent  of  the file type, thus it should work for text  files,  typed 
  30.      files as well as untyped files.
  31.  
  32.         An  implementation  requirement  was that all the  standard  pascal  i/o 
  33.      procedures  and functions would still be working when using this  function.  
  34.      This requirement is met.
  35.  
  36.        If  a  file with an extended name is to be used, two actions  are  needed 
  37.      prior  to actual using the file: the file name must be put into  a  special 
  38.      data  structure  (FILEDESCRIPTORS) and the file must be  registered.   Only 
  39.      when  a  file is registered, the required user area will be  selected  when 
  40.      accessing  the  file.  Once registered, the normal Pascal  i/o  procedures, 
  41.      like  assign, reset, rewrite, (block)read, (block)write and close,  can  be 
  42.      invoked.
  43.  
  44.         The  (pseudo) unit EXTFN.UNT consists 4 type definitions,  5  procedures 
  45.      and 2 functions.
  46.  
  47.      2.1.  Type definitions.
  48.  
  49.         The  type FILETYPES enumerates the two possible file types supported  by 
  50.      TP: DISKFILE for a disk file and DEVICE for a logical device.
  51.  
  52.         The  type FILENAMETYPES enumerates the possible formats of a  disk  file 
  53.      name: DUNE_FORMAT for a name including disk and user area, DNE_FORMAT for a 
  54.      name  without  the  user area and NE_FORMAT for a  name  without  disk  and 
  55.      without  user  area.  The DNE_FORMAT is equivalent with the  standard  full 
  56.      name of CP/M.
  57.  
  58.         The  type  FULLFILENAMES specifies the string to save  a  maximum  sized 
  59.      extended file name.
  60.  
  61.         The type FILEDESCRIPTORS specifies a record in which the separate fields 
  62.      of a file name are stored.
  63.  
  64.  
  65.  
  66.                                        - 1 -
  67.  
  68.      Description of the unit EXTFN
  69.  
  70.  
  71.      2.2.  Procedures and functions
  72.  
  73.         The  syntax  of  the  procedures  and  functions  within  EXTFN.UNT  are 
  74.      summarised in the table below.  They are given in alphabetical order.
  75.  
  76.       function  ExpandFileName( var FileDesc : FileDescriptors ;
  77.                                     NameType : FileNameTypes ) : FullFileNames ;
  78.       procedure InitFileNameUnit ;
  79.       procedure RegisterFile  ( var FileDesc : FileDescriptors ;
  80.                                 var SomeFile ) ;
  81.       function  SameName      ( var FileDesc1: FileDescriptors ;
  82.                                 var FileDesc2: FileDescriptors ,
  83.                                     NameType : FileNameTypes ) : Boolean ;
  84.       procedure SplitFileName ( var FileDesc : FileDescriptors ;
  85.                                     FileName : FullFileNames ) ;
  86.       procedure UnInitFileNameUnit ;
  87.       procedure UnRegisterFile( var SomeFile ) ;
  88.  
  89.      2.2.1.  ExpandFileName
  90.  
  91.         Function ExpandFileName builds from the filedescriptor a string with the 
  92.      file name.  The name is formatted according to the specified  FileNameType.  
  93.      A  'current'  value of the drive will be replaced by its actual  value  and 
  94.      also  a  'current' value of the user area will be replaced by  its  current 
  95.      actual value.  The result may contain the '?' wildcard character.
  96.  
  97.         This function is needed to assign a TP file to a CP/M file (or  device). 
  98.      Typically a program will contain the following fragment:
  99.  
  100.            RegisterFile( MyFileName, MyFile ) ;
  101.            Assign( MyFile, ExpandFileName(MyFileName,DNE_Format) ) ;
  102.  
  103.      2.2.2.  InitFileNameUnit
  104.  
  105.         Procedure  InitFileNameUnit  should be invoked once, before any  of  the 
  106.      other  procedures  and functions in EXTFN.UNT is invoked.   It  initialises 
  107.      some  of  the internal variables and it installs an extension  to  BDos  by 
  108.      modifying the BDos vector.
  109.  
  110.      2.2.3.  RegisterFile
  111.  
  112.         Procedure  RegisterFile  registers  which files  are  assigned  extended 
  113.      names.  It builds an internal table, specifying the files and the user area 
  114.      in which they are located.  Note that the user area to use is fixed at  the 
  115.      time  procedure RegisterFile is invoked: any change in the file name  after 
  116.      the invokation does not affect the user area to be used.  If the user  area 
  117.      in  the  extended file name specifies the 'current' user area,  the  actual 
  118.      user area is substituted.
  119.  
  120.         Procedure RegisterFile effectivly invokes UnRegisterFile to ensure  that 
  121.      one file occurs at most once in the internal table.  This behaviour can  be 
  122.      used to modify the registered user area in case it might have been changed.  
  123.      However, it is not allowed to invoke RegisterFile while the file is open!
  124.  
  125.      2.2.4.  SameName
  126.  
  127.         Boolean function SameName compares two extended file names and returns a 
  128.      TRUE  value if they match and a FALSE value if they don't  match.   Through 
  129.  
  130.  
  131.                                        - 2 -
  132.  
  133.      Description of the unit EXTFN
  134.  
  135.  
  136.      the  specification  of the NameType one can select whether the  drive  name 
  137.      and/or  the  user area number should be included in  the  comparison.   Two 
  138.      names  match if for every position in each of the fields the characters  of 
  139.      the two names are either equal or at least one of them is the '?'  wildcard 
  140.      character.  In the comparison the '?' wildcard matches also a  non-existing 
  141.      character.
  142.  
  143.      2.2.5.  SplitFileName
  144.  
  145.         Procedure  SplitFileName takes an extended file name in a string  as  an 
  146.      argument  and it builds a variable of type FILEDESCRIPTORS.  The  procedure 
  147.      recognises both extended disk file names and the logical device names.  The 
  148.      procedure  is liberal with regard to erroneous specifications: it does  not 
  149.      report errors and it tries to make the best of it. 
  150.  
  151.         If  the drive designator is not specified in the file name  string,  the 
  152.      drive  is set to 'current'.  At the invokation of either ExpandFileName  or 
  153.      SameName,  the  'current' indication is substituted by the  actual  current 
  154.      drive designator.
  155.  
  156.         The user area number is handled in the same way: if it is not  specified 
  157.      it is set to 'current' and replaced by the actual value whenever necessary.
  158.  
  159.         The  '*'  wildcard  character is replaced by a number  of  '?'  wildcard 
  160.      characters, enough to fill up the entire field.  Any characters between the 
  161.      '*' wildcard and the next field terminator, like '.', are lost.
  162.  
  163.      2.2.6.  UnInitFileNameUnit
  164.  
  165.         Procedure  UnInitFileNameUnit restores the original BDos  vector,  which 
  166.      was modified by InitFileNameUnit.  See section 'Usage' for more comments on 
  167.      this procedure.
  168.  
  169.      2.2.7.  UnRegisterFile
  170.  
  171.         Procedure  UnRegisterFile  removes a file from the  list  of  registered 
  172.      files,  thereby disabling the feature to select a user area for that  file.  
  173.      This procedure must not be called while the file is open!
  174.  
  175.  
  176.      3.  Usage.
  177.  
  178.        Typically, a program using extended file names will contain the following 
  179.      program fragments:
  180.  
  181.         Program UseExtendedFileNames ;
  182.         {$IEXTFN.UNT}  { Include unit }
  183.         ...
  184.         var
  185.            ExtFileName :   FileDescriptors ;  { Extended name of ExtFile }
  186.            ExtFile     : File of Something ;  { Some file }
  187.            NameString  :     FullFileNames ;  { String with extended file name }
  188.         ...
  189.         begin  { of main program }
  190.            InitFileNameUnit ;
  191.            ...
  192.            ReadLn( NameString ) ;                     { Retrieve file name }
  193.            SplitFileName( ExtFileName, NameString ) ; { Crack file name }
  194.  
  195.  
  196.                                        - 3 -
  197.  
  198.      Description of the unit EXTFN
  199.  
  200.  
  201.            RegisterFile ( ExtFileName, ExtFile ) ;    { Register file }
  202.            Assign( ExtFile, ExpandFileName(ExtFileName,DNE_Format) ) ;
  203.            ...
  204.            ...  { Do I/O on file ExtFile }
  205.            ...
  206.            Close( ExtFile ) ;
  207.            UnInitFileNameUnit ;
  208.         end.
  209.  
  210.         Note  the invokation of UnInitFileNameUnit at the end: it  restores  the 
  211.      original BDos vector in low memory.  If the program is compiled to disk and 
  212.      the  program  is started 'from the CP/M prompt', the BDos  vector  will  be 
  213.      restored  also at the warm boot, which occurs when the program  terminates.
  214.  
  215.         However,  if the program is run from within TP, the BDos vector MUST  be 
  216.      restored  prior to returning to TP.  Thus for normal  program  termination, 
  217.      UnInitFileNameUnit should be called at the end of the program.  In order to 
  218.      catch the premature terminations due to run-time errors, it is advisable to 
  219.      use your own error processor, which invokes UnInitFileNameUnit.
  220.  
  221.  
  222.      4.  Short technical description.
  223.  
  224.         To  implement extended file names, a small shell is put on top of  BDos.  
  225.      This  shell  is the procedure OwnBDos in EXTFN.UNT.  Each call  to  OwnBDos 
  226.      from TP which references a file with an extended name, is replaced by  four 
  227.      BDos calls.  The first call retrieves the currently selected user area, the 
  228.      second call selects the user area for that specific file, the third call is 
  229.      the  original,  intercepted  BDos call and the fourth and  last  BDos  call 
  230.      reselects  the  original  user area.  The return code received  by  the  TP 
  231.      runtime routines, is the return code of the file I/O BDos call.
  232.  
  233.         The procedure InitFileNameUnit modifies the vector in low memory to jump 
  234.      to  OwnBDos  in  stead of BDos.  At the time the  program  terminates,  the 
  235.      vector must be restored: if not, the first invokation of BDos after program 
  236.      termination will have unpredictable results and most probably the  computer 
  237.      will 'hang'.
  238.  
  239.  
  240.      5.  Remarks.
  241.  
  242.        Any  remarks, comments, bug reports, bug fixes and ideas for  improvement 
  243.      are welcome, in either Dutch or English.  E-mail is preferred.
  244.  
  245.         Wim Nelis
  246.         Rozenhof 4
  247.         8316 CX  Marknesse
  248.         The Netherlands
  249.  
  250.         (0) 5273 - 3172
  251.         NELIS@NLR.NL   (Internet)
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                        - 4 -
  262.