1 07/30/86  check_star_name_
  2 
  3 The check_star_name_ subroutine analyzes a character string to be sure
  4 that it has been formed according to the rules of the star convention,
  5 and optionally checks that it also conforms to the rules for forming
  6 entrynames.  It returns a starname type code that indicates whether the
  7 string is a starname, and whether the starname matches every possible
  8 name.
  9 
 10 
 11 Entry points in check_star_name_:
 12    (List is generated by the help command)
 13 
 14 
 15 :Entry: check_star_name_: 07/30/86  check_star_name_
 16 
 17 Function: this entrypoint accepts a character string and a bit mask as
 18 its inputs, and analyzes the character string according to the tests
 19 selected by the bit mask.
 20 
 21 
 22 Syntax:
 23 declare check_star_name_ entry (char(*), bit(36) aligned, fixed bin(2),
 24         fixed bin(35));
 25 call check_star_name_ (starname, control_mask, type, code);
 26 
 27 
 28 Arguments:
 29 starname
 30    (Input) the character string to be analyzed.  Trailing spaces in the
 31    character string are ignored.
 32 control_mask
 33    (Input) a bit string constructed from constants listed below.
 34 type
 35    (Output) one of the starname type codes listed below.
 36 code
 37    (Output) one of the standard status codes listed below.
 38 
 39 
 40 List of control_mask constants:  these constants are defined in
 41    check_star_name.incl.pl1, and can be combined in most cases using
 42    boolean or.
 43 CHECK_STAR_IGNORE_ARCHIVE
 44    permit the archive component pathname delimiter, double colon ("::")
 45    in the starname, and treat it as a pair of nonspecial characters.
 46    By default, this would be rejected.
 47 CHECK_STAR_IGNORE_ENTRYPOINT
 48    permit the entrypoint convention delimiters, dollar sign ("$") and
 49    vertical bar ("|") in the starname, and treat them as nonspecial
 50    characters.  By default, they would be rejected.
 51 CHECK_STAR_IGNORE_EQUAL
 52    permit the equal convention characters, equal sign ("=") and percent
 53    sign ("%") in the starname, and treat them as nonspecial characters.
 54    By default, they would be rejected.
 55 
 56 
 57 CHECK_STAR_IGNORE_LENGTH
 58    permit an entryname starname or a component name starname to be more
 59    than 32 characters long.  By default, this is not permitted.  The
 60    containing dir and entrypoints of path are not checked for length.
 61 CHECK_STAR_IGNORE_NONASCII
 62    permit nonASCII characters in an entryname starname or a component
 63    name starname, and treat them as nonspecial characters.  By default,
 64    they would be rejected.
 65 CHECK_STAR_IGNORE_NULL
 66    permit null components in the starname.  By default, they would be
 67    rejected.
 68 CHECK_STAR_IGNORE_PATH
 69    permit the pathname delimiters, less than ("<") and greater than
 70    (">") in the starname, and treat them as nonspecial characters.  By
 71    default, they would be rejected.
 72 
 73 
 74 CHECK_STAR_PROCESS_ARCHIVE
 75    if the archive component pathname delimiter is present, analyze the
 76    substring preceding it and the substring following it separately.
 77    If either name is a starname, indicate that the match procedure must
 78    be used.  A second archive delimiter will be rejected.  If this is
 79    combined with CHECK_STAR_PROCESS_ENTRYPOINT, an archive delimiter
 80    following the entrypoint delimiter will be rejected.
 81 CHECK_STAR_PROCESS_ENTRYPOINT
 82    if one of the entrypoint convention delimiters is present, check the
 83    substring preceding it and the substring following it separately.
 84    If either name is a starname, indicate that the match procedure must
 85    be used.  A second entrypoint delimiter will be rejected.  If it is
 86    combined with CHECK_STAR_PROCESS_ARCHIVE, an entrypoint delimiter
 87    preceding the archive delimiter will be rejected.
 88 
 89 
 90 CHECK_STAR_PROCESS_PATH
 91    if pathname delimiters are present, analyze only the substring
 92    following the rightmost pathname delimiter.  If this string is of
 93    zero length, report that PL/I comparison can be used, because the
 94    expanded pathname will end in the name of a directory, and valid
 95    directory names can't contain star convention characters.  (This is
 96    intended for names like "<".  Names like ">udd>" may be rejected by
 97    expand_pathname_, but are acceptable to check_star_name_.)
 98 CHECK_STAR_REJECT_WILD
 99    return error_table_$nostars if any star convention characters are
100    present.
101 
102 
103 CHECK_STAR_IGNORE_ALL
104    combines all the CHECK_STAR_IGNORE flags.  This can be used to
105    analyze a starname to determine its type without applying any of the
106    tests intended for validating entrynames.
107 CHECK_STAR_ENTRY_DEFAULT
108    combines exactly the same tests used by the obsolete
109    check_star_name_$entry entrypoint, which is equivalent to combining
110    CHECK_STAR_IGNORE_ENTRYPOINT and CHECK_STAR_IGNORE_EQUAL.
111 CHECK_STAR_PATH_DEFAULT
112    combines exactly the same tests used by the obsolete
113    check_star_name_$path entrypoint, which is equivalent to combining
114    CHECK_STAR_PROCESS_ARCHIVE, CHECK_STAR_IGNORE_ENTRYPOINT,
115    CHECK_STAR_IGNORE_EQUAL, and CHECK_STAR_PROCESS_PATH.
116 
117 
118 List of starname type codes: these type constants are defined in
119    check_star_name.incl.pl1.
120 STAR_TYPE_MATCHES_EVERYTHING (2)
121    no comparison is necessary, since the starname matches all possible
122    strings.
123 STAR_TYPE_USE_MATCH_PROCEDURE (1)
124    the procedure match_star_name_ must be used to compare the string
125    to possible matching strings, because it is a starname containing
126    stars (asterisks) and question marks.
127 STAR_TYPE_USE_PL1_COMPARE (0)
128    the string is not a starname and can be compared using PL/I
129    comparison rules.
130 
131 
132 List of status codes:
133 0
134    the string passes all of the selected tests, and the starname type
135    output indicates whether the string is a starname.
136 error_table_$archive_pathname
137    the archive component pathname delimiter was found, and the
138    control_mask did not permit it.
139 error_table_$bad_arg
140    the control mask specified an unimplented test.
141 error_table_$bad_file_name
142    the string violates the rules for forming entrynames and the
143    control_mask did not permit it.
144 error_table_$badequal
145    equal convention characters were found and the control_mask did not
146    permit them.
147 
148 
149 error_table_$badpath
150    the directory name contains a nonASCII character and
151    CHECK_STAR_PROCESS_PATH was specified but
152    CHECK_STAR_IGNORE_NONASCII was not.
153 error_table_$badstar
154    the string violates the rules for forming starnames.
155 error_table_$entlong
156    The string was more than 32 characters long and the control_mask did
157    not permit it.  If CHECK_STAR_PROCESS_PATH was specified, the
158    entryname part of the string was more than 32 characters long.  If
159    CHECK_STAR_PROCESS_ARCHIVE was specified, either the entryname or
160    the component name was more than 32 characters long.
161 
162 
163 error_table_$inconsistent
164    the control_mask was in error, specifying both CHECK_STAR_PROCESS
165    and CHECK_STAR_IGNORE the same test.
166 error_table_$invalid_ascii
167    the entryname contains a nonASCII character and
168    CHECK_STAR_IGNORE_NONASCII was not specified.
169 error_table_$nostars
170    stars or question marks were found and CHECK_STAR_REJECT_WILD was
171    specified in the control_mask.  Note that star_type will correctly
172    reflect the starname type for this case.
173 error_table_$null_name_component
174    the string contains null components and the control_mask did not
175    permit them.
176 
177 
178 Notes: see the description of the hcs_$star_ entrypoint in hcs_.info
179 to find how to list the directory entries that match a given starname.
180 See match_star_name_.info to find how to match a starname with an
181 entryname.  See starname.gi.info for the rules governing the formation
182 and interpretation of starnames.  See entryname.gi.info for the rules
183 governing the formation of entrynames.
184 
185 
186 :Entry: entry:  07/30/86  check_star_name_$entry
187 
188 Function: this entrypoint accepts the entryname to be analyzed as
189 input.
190 
191 
192 Syntax:
193 declare check_star_name_$entry entry (char(*), fixed bin(35));
194 call check_star_name_$entry (entryname, code);
195 
196 
197 Arguments:
198 entryname
199    (Input) is the entryname to be validated.  Trailing spaces in the
200    entryname character string are ignored.
201 code
202    (Output) is one of the nonstandard status codes listed below.
203 
204 
205 List of status codes:
206 0
207    the entryname is valid and is not a starname (does not contain
208    asterisks or question marks).
209 1
210    the entryname is valid and is a starname (does contain asterisks or
211    question marks).
212 2
213    the entryname is valid and is a starname that matches every
214    entryname.
215 error_table_$badstar
216    the entryname is invalid.  It violates the rules for forming
217    starnames, or it violates the rules for constructing entrynames.
218 
219 
220 Notes: This entrypoint is obsolete.  Use the check_star_name_
221 entrypoint for new applications.  The new entrypoint returns a variety
222 of different standard error codes explaining a rejection whereas this
223 entrypoint can only return a single standard error code value for
224 compatability.
225 
226 See the description of the hcs_$star_ entrypoint in hcs_.info to find
227 how to list the directory entries that match a given starname.  See
228 match_star_name_.info to find how to match a starname with an
229 entryname.  See starname.gi.info for the rules governing the formation
230 and interpretation of starnames.  See entryname.gi.info for the rules
231 governing the formation of entrynames.
232 
233 
234 :Entry: path:  07/30/86  check_star_name_$path
235 
236 Function: this entrypoint accepts a pathname as its input and analyzes
237 the final entryname in that pathname.
238 
239 
240 Syntax:
241 declare check_star_name_$path entry (char(*), fixed bin(35));
242 call check_star_name_$path (path, code);
243 
244 
245 Arguments:
246 path
247    (Input) is the pathname whose final entryname is to be validated.
248    Trailing spaces in the pathname character string are ignored.
249 code
250    (Output) is one of the nonstandard status codes listed below.
251 
252 
253 List of status codes:
254 0
255    the entryname is valid and is not a starname (does not contain
256    asterisks or question marks).
257 1
258    the entryname is valid and is a starname (does contain asterisks or
259    question marks).
260 2
261    the entryname is valid and is a starname that matches every
262    entryname.
263 error_table_$badstar
264    the entryname is invalid.  It violates the rules for forming
265    starnames, or it violates the rules for forming pathnames.
266 
267 
268 Notes: This entrypoint is obsolete.  Use the check_star_name_
269 entrypoint for new applications.  The new entrypoint returns a variety
270 of different standard error codes explaining a rejection whereas this
271 entrypoint can only return a single standard error code value for
272 compatibility.
273 
274 See the description of the hcs_$star_ entrypoint in hcs_.info to find
275 how to list the directory entries that match a given starname.  See
276 match_star_name_.info to find how to match a starname with an
277 entryname.  See starname.gi.info for the rules governing the formation
278 and interpretation of starnames.  See pathname.gi.info for the rules
279 governing the formation of pathnames.