1 02/06/84  parse_file_
  2 
  3 The parse_file_ subroutine provides a facility for parsing ASCII text
  4 into symbols and break characters.  It is recommended for occasionally
  5 used text-scanning applications.  In applications where speed or
  6 frequent use are important, in-line PL/I code is recommended (to do
  7 parsing) instead.
  8 
  9 
 10 A restriction of the subroutine is that the text to be parsed must be
 11 an aligned character string.
 12 
 13 The initialization entry points, parse_file_$parse_file_init_name and
 14 parse_file_$parse_file_init_ptr, save a pointer to the text to be
 15 scanned and a character count in internal static storage.  Thus, only
 16 one text can be parsed at one time.
 17 
 18 
 19 Entry points in parse_file_:
 20    (List is generated by the help command)
 21 
 22 
 23 :Entry:  parse_file_: 02/06/84 parse_file_
 24 
 25 Function: scans the text file and returns the next break character or
 26 symbol.  Blanks, newline characters, and comments enclosed by /* and
 27 */, however, are skipped.
 28 
 29 
 30 Syntax:
 31 declare parse_file_ entry (fixed bin, fixed bin, fixed bin(1),
 32      fixed bin(1));
 33 call parse_file_ (ci, cc, break, eof);
 34 
 35 
 36 Arguments:
 37 ci
 38    is an index to the first character of the symbol or break character.
 39    (Output).  (The first character of the text is considered to be
 40    character 1.)
 41 cc
 42    is the number of characters in the symbol.  (Output)
 43 break
 44    is set to 1 if the returned item is a break character; otherwise, it
 45    is 0.  (Output)
 46 eof
 47    is set to 1 if the end of text has been reached; otherwise, it is 0.
 48    (Output)
 49 
 50 
 51 :Entry:  parse_file_cur_line:  02/06/84 parse_file_$parse_file_cur_line
 52 
 53 
 54 Function: returns to the caller the current line of text being
 55 scanned.  This entry is useful in printing diagnostic error messages.
 56 
 57 
 58 Syntax:
 59 declare parse_file_$parse_file_cur_line entry (fixed bin, fixed bin);
 60 call parse_file_$parse_file_cur_line (ci, cc);
 61 
 62 
 63 Arguments:
 64 ci
 65    is an index to the first character of the line.  (Output).  (The
 66    first character of the text is considered to be character 1.)
 67 cc
 68    is the number of characters in the line.  (Output)
 69 
 70 
 71 :Entry:  parse_file_init_name:
 72 02/06/84 parse_file_$parse_file_init_name
 73 
 74 
 75 Function: initializes the subroutine given a directory and an entry
 76 point name.  It gets a pointer to the desired segment and saves it for
 77 subsequent calls in internal static.
 78 
 79 
 80 Syntax:
 81 declare parse_file_$parse_file_init_name entry (char(*), char(*), ptr,
 82      fixed bin(35));
 83 call parse_file_$parse_file_init_name (dir_name, entryname, ptr, code);
 84 
 85 
 86 Arguments:
 87 dir_name
 88    is the directory name portion of the pathname of the segment to be
 89    parsed.  (Input)
 90 entryname
 91    is the entryname of the segment to be parsed.  (Input)
 92 ptr
 93    is a pointer to the segment.  (Output)
 94 code
 95    is a standard status code.  (Output).  It is zero if the segment is
 96    initiated.  If nonzero, the segment cannot be initiated.  It can
 97    return any code from hcs_$initiate except error_table_$segknown.
 98 
 99 
100 :Entry:  parse_file_init_ptr:  02/06/84 parse_file_$parse_file_init_ptr
101 
102 
103 Function: initializes the parse_file_ subroutine with a supplied
104 pointer and character count.  It is used in cases where a pointer to
105 the segment to be parsed is already available.
106 
107 
108 Syntax:
109 declare parse_file_$parse_file_init_ptr entry (ptr, fixed bin);
110 call parse_file_$parse_file_init_ptr (ptr, cc);
111 
112 
113 Arguments:
114 ptr
115    is a pointer to a segment or an aligned character string.  (Input)
116 cc
117    is the character count of the ASCII text to be scanned.  (Input)
118 
119 
120 :Entry:  parse_file_ptr:  02/06/84 parse_file_$parse_file_ptr
121 
122 
123 Function: This entry point is identical to the parse_file_ entry point
124 except that a pointer (with bit offset) to the break character or the
125 symbol is returned instead of a character index.
126 
127 
128 Syntax:
129 declare parse_file_$parse_file_ptr entry (ptr, fixed bin, fixed bin(1),
130      fixed bin(1));
131 call parse_file_$parse_file_ptr (ptr, cc, break, eof);
132 
133 
134 Arguments:
135 ptr
136    is a pointer to the symbol or the break character.  (Output)
137 cc
138    is the number of characters in the symbol.  (Output)
139 break
140    is set to 1 if the returned item is a break character; otherwise, it
141    is 0.  (Output)
142 eof
143    is set to 1 if the end of text has been reached; otherwise, it is 0.
144    (Output)
145 
146 
147 :Entry:  parse_file_line_no:  02/06/84 parse_file_$parse_file_line_no
148 
149 
150 Function: returns to the caller the current line number of text being
151 scanned.  This entry is useful in printing diagnostic error messages.
152 
153 
154 Syntax:
155 declare parse_file_$parse_file_line_no entry (fixed bin);
156 call parse_file_$parse_file_line_no (cl);
157 
158 
159 Arguments:
160 cl
161    is the number of the current line.  (Output)
162 
163 
164 :Entry:  parse_file_set_break:
165 02/06/84 parse_file_$parse_file_set_break
166 
167 
168 Function: is used to define break characters.  Normally, all
169 nonalphanumeric characters are break characters (including blank and
170 newline).
171 
172 
173 Syntax:
174 declare parse_file_$parse_file_set_break entry (char(*));
175 call parse_file_$parse_file_set_break (cs)
176 
177 
178 Arguments:
179 cs
180    is a control string.  (Input).  Each character found in cs is made a
181    break character.
182 
183 
184 :Entry:  parse_file_unset_break:
185 02/06/84 parse_file_$parse_file_unset_break
186 
187 
188 Function: renders break characters as normal alphanumeric characters.
189 It is not possible to unset blank, newline, or comment delimiters,
190 however.  These are always treated as break characters.
191 
192 
193 Syntax:
194 declare parse_file_$parse_file_unset_break entry (char(*));
195 call parse_file_$parse_file_unset_break (cs);
196 
197 
198 Arguments:
199 cs
200    is a control string, each character of which is made a nonbreaking
201    character.  (Input)