home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / mbug / mbug078.arc / PARSEFCB.DOC < prev    next >
Text File  |  1979-12-31  |  6KB  |  153 lines
  1.  
  2.  
  3.                  Documentation for PARSEFCB.REL
  4.  
  5.                         October 31, 1983
  6.  
  7.                          Jim Lopushinsky
  8.  
  9.  
  10. Entry Parameters:
  11.      Register       DE:  Address of input ASCII string
  12.                     HL:  Address of target FCB
  13.  
  14. Returned Value:
  15.      Register       HL:  Return code
  16.  
  17.  
  18. PARSEFCB.REL   is  a  subroutine  that  parses  an   ASCII   file
  19. specification  and  prepares  a File  Control  Block,  FCB.   The
  20. calling  program  places  the  address of  the  ASCII  string  in
  21. register  DE,  and  the address of the FCB in  HL.   The  maximum
  22. length of the input ASCII string to be parsed is 128 bytes.   The
  23. target FCB must be 36 bytes in length.
  24.  
  25. PARSEFCB has two entry points:
  26.  
  27.      PARSE     Standard parse with no user specification allowed.
  28.                This  subroutine performs an identical function to
  29.                BDOS function 152, Parse Filename.
  30.  
  31.      PARSEU    Standard   parse   with   optional   user   number
  32.                specified.  This entry point actually requires the
  33.                FCB to be 37 bytes in length, with the user number
  34.                at FCB-1.  PARSEU returns 0FFH at FCB-1 if no user
  35.                number  was  specified,   or  the  specified  user
  36.                number.
  37.  
  38. PARSE  assumes the input string contains file  specifications  in
  39. the following form:
  40.  
  41.      {d:}filename{.typ}{;password}
  42.  
  43. PARSEU  assumes the input string contains file specifications  in
  44. one of the following forms in addition to the form for PARSE:
  45.  
  46.      {du:}filename{.typ}{;password}
  47.      {u:}filename{.typ}{;password}
  48.      {ud:}filename{.typ}{;password}
  49.  
  50. where items enclosed in curly brackets are optional.   PARSE  and
  51. PARSEU  also accept isolated drive/user specifications  d:,  du:,
  52. u:,  ud: (PARSE only accepts the first form) in the input string.
  53. When  it  encounters one,  it sets the  filename,  filetype,  and
  54. password fields in the FCB to blank.
  55.  
  56. The PARSE and PARSEU functions parse the first file specification
  57. they  find in the input string.   The function  first  eliminates
  58. leading blanks and tabs.  The function then assumes that the file
  59. specification  ends on the first delimiter it encounters that  is
  60. out  of  context  with the specific field  it  is  parsing.   For
  61. instance,  if  it  finds  a period,  and it is  not  parsing  the
  62. filename   field,   the   period   delimits   the   entire   file
  63. specification.
  64.  
  65. The   parse  routines  recognize  the  following  characters   as
  66. delimiters:
  67.  
  68.      space
  69.      tab
  70.      return
  71.      null
  72.      ; (semicolon) - except before password field
  73.      = (equal)
  74.      < (less than)
  75.      > (greater than)
  76.      . (period) - except after filename and before filetype
  77.      : (colon) - except before filename and after drive/user
  78.      , (comma)
  79.      | (vertical bar)
  80.      [ (left square bracket)
  81.      ] (right square bracket)
  82.  
  83. If  a non-graphic character is encountered in the range 1 through
  84. 31 not listed above,  it treats the character as an  error.   The
  85. FCB is initialized as shown below:
  86.  
  87. Location       Contents
  88.  
  89. byte -1        (PARSEU  only)  The  user  field  is  set  to  the
  90.                specified user number.   If the user number is not
  91.                specified, the user field is set to 0FFH.
  92.  
  93. byte 0         The drive field is set to the specified drive.  If
  94.                the drive is not specified, the default drive code
  95.                is used.  0=default, 1=A, 2=B, etc.
  96.  
  97. byte 1-8       The  name is set to the specified  filename.   All
  98.                letters are converted to upper-case.   If the name
  99.                is not eight characters long,  the remaining bytes
  100.                in the filename field are padded with blanks.   If
  101.                the  filename has an asterisk,  *,  all  remaining
  102.                bytes  in  the filename field are filled  in  with
  103.                question  marks,   ?.   An  error  occurs  if  the
  104.                filename is more than eight bytes long.
  105. .pa
  106. byte 9-11      The  type field is set to the specified  filetype.
  107.                If  no  filetype is specified,  the type field  is
  108.                initialized to blanks.   All letters are converted
  109.                to   upper-case.    If  the  type  is  not   three
  110.                characters  long,   the  remaining  bytes  in  the
  111.                filetype  field  are padded with  blanks.   If  an
  112.                asterisk,  *,  occurs,  all  remaining  bytes  are
  113.                filled in with question marks, ?.  An error occurs
  114.                if the type field is more than three bytes long.
  115.  
  116. byte 12-15     Filled in with zeros.
  117.  
  118. byte 16-23     The   password  field  is  set  to  the  specified
  119.                password.   If  no password is  specified,  it  is
  120.                initialized  to blanks.   If the password is  less
  121.                than  eight characters long,  remaining bytes  are
  122.                padded with blanks.   All letters are converted to
  123.                upper-case.   If  the password field is more  than
  124.                eight  bytes long,  an error occurs.   Note that a
  125.                blank in the first position of the password  field
  126.                implies no password was specified.
  127.  
  128. byte 24-25     Filled in with zeros.
  129.  
  130. byte 26        Length of the password.
  131.  
  132. byte 27-35     Filled in with zeros.
  133.  
  134.  
  135. If an error occurs, 0FFFFH is returned in register pair HL.
  136.  
  137. On  a successful parse,  the function checks the next item in the
  138. input string.   It skips over trailing blanks and tabs and  looks
  139. at  the next character.   If the character is a null or  carriage
  140. return,  it  returns a 0 indicating the end of the input  string.
  141. If  the character is a delimiter,  it returns the address of  the
  142. delimiter.   If the character is not a delimiter,  it returns the
  143. address of the first trailing blank or tab.
  144.  
  145. If  the first non-blank or non-tab character in the input  string
  146. is  a null,  0,  or carriage return,  the function returns a zero
  147. indicating the end of the string.
  148.  
  149. If  the  function  is  to be used  to  parse  a  subsequent  file
  150. specification  in the input string,  the returned address must be
  151. advanced over the delimiter before placing it in register DE.
  152.  
  153.