07/30/86 check_star_name_ The check_star_name_ subroutine analyzes a character string to be sure that it has been formed according to the rules of the star convention, and optionally checks that it also conforms to the rules for forming entrynames. It returns a starname type code that indicates whether the string is a starname, and whether the starname matches every possible name. Entry points in check_star_name_: (List is generated by the help command) :Entry: check_star_name_: 07/30/86 check_star_name_ Function: this entrypoint accepts a character string and a bit mask as its inputs, and analyzes the character string according to the tests selected by the bit mask. Syntax: declare check_star_name_ entry (char(*), bit(36) aligned, fixed bin(2), fixed bin(35)); call check_star_name_ (starname, control_mask, type, code); Arguments: starname (Input) the character string to be analyzed. Trailing spaces in the character string are ignored. control_mask (Input) a bit string constructed from constants listed below. type (Output) one of the starname type codes listed below. code (Output) one of the standard status codes listed below. List of control_mask constants: these constants are defined in check_star_name.incl.pl1, and can be combined in most cases using boolean or. CHECK_STAR_IGNORE_ARCHIVE permit the archive component pathname delimiter, double colon ("::") in the starname, and treat it as a pair of nonspecial characters. By default, this would be rejected. CHECK_STAR_IGNORE_ENTRYPOINT permit the entrypoint convention delimiters, dollar sign ("$") and vertical bar ("|") in the starname, and treat them as nonspecial characters. By default, they would be rejected. CHECK_STAR_IGNORE_EQUAL permit the equal convention characters, equal sign ("=") and percent sign ("%") in the starname, and treat them as nonspecial characters. By default, they would be rejected. CHECK_STAR_IGNORE_LENGTH permit an entryname starname or a component name starname to be more than 32 characters long. By default, this is not permitted. The containing dir and entrypoints of path are not checked for length. CHECK_STAR_IGNORE_NONASCII permit nonASCII characters in an entryname starname or a component name starname, and treat them as nonspecial characters. By default, they would be rejected. CHECK_STAR_IGNORE_NULL permit null components in the starname. By default, they would be rejected. CHECK_STAR_IGNORE_PATH permit the pathname delimiters, less than ("<") and greater than (">") in the starname, and treat them as nonspecial characters. By default, they would be rejected. CHECK_STAR_PROCESS_ARCHIVE if the archive component pathname delimiter is present, analyze the substring preceding it and the substring following it separately. If either name is a starname, indicate that the match procedure must be used. A second archive delimiter will be rejected. If this is combined with CHECK_STAR_PROCESS_ENTRYPOINT, an archive delimiter following the entrypoint delimiter will be rejected. CHECK_STAR_PROCESS_ENTRYPOINT if one of the entrypoint convention delimiters is present, check the substring preceding it and the substring following it separately. If either name is a starname, indicate that the match procedure must be used. A second entrypoint delimiter will be rejected. If it is combined with CHECK_STAR_PROCESS_ARCHIVE, an entrypoint delimiter preceding the archive delimiter will be rejected. CHECK_STAR_PROCESS_PATH if pathname delimiters are present, analyze only the substring following the rightmost pathname delimiter. If this string is of zero length, report that PL/I comparison can be used, because the expanded pathname will end in the name of a directory, and valid directory names can't contain star convention characters. (This is intended for names like "<". Names like ">udd>" may be rejected by expand_pathname_, but are acceptable to check_star_name_.) CHECK_STAR_REJECT_WILD return error_table_$nostars if any star convention characters are present. CHECK_STAR_IGNORE_ALL combines all the CHECK_STAR_IGNORE flags. This can be used to analyze a starname to determine its type without applying any of the tests intended for validating entrynames. CHECK_STAR_ENTRY_DEFAULT combines exactly the same tests used by the obsolete check_star_name_$entry entrypoint, which is equivalent to combining CHECK_STAR_IGNORE_ENTRYPOINT and CHECK_STAR_IGNORE_EQUAL. CHECK_STAR_PATH_DEFAULT combines exactly the same tests used by the obsolete check_star_name_$path entrypoint, which is equivalent to combining CHECK_STAR_PROCESS_ARCHIVE, CHECK_STAR_IGNORE_ENTRYPOINT, CHECK_STAR_IGNORE_EQUAL, and CHECK_STAR_PROCESS_PATH. List of starname type codes: these type constants are defined in check_star_name.incl.pl1. STAR_TYPE_MATCHES_EVERYTHING (2) no comparison is necessary, since the starname matches all possible strings. STAR_TYPE_USE_MATCH_PROCEDURE (1) the procedure match_star_name_ must be used to compare the string to possible matching strings, because it is a starname containing stars (asterisks) and question marks. STAR_TYPE_USE_PL1_COMPARE (0) the string is not a starname and can be compared using PL/I comparison rules. List of status codes: 0 the string passes all of the selected tests, and the starname type output indicates whether the string is a starname. error_table_$archive_pathname the archive component pathname delimiter was found, and the control_mask did not permit it. error_table_$bad_arg the control mask specified an unimplented test. error_table_$bad_file_name the string violates the rules for forming entrynames and the control_mask did not permit it. error_table_$badequal equal convention characters were found and the control_mask did not permit them. error_table_$badpath the directory name contains a nonASCII character and CHECK_STAR_PROCESS_PATH was specified but CHECK_STAR_IGNORE_NONASCII was not. error_table_$badstar the string violates the rules for forming starnames. error_table_$entlong The string was more than 32 characters long and the control_mask did not permit it. If CHECK_STAR_PROCESS_PATH was specified, the entryname part of the string was more than 32 characters long. If CHECK_STAR_PROCESS_ARCHIVE was specified, either the entryname or the component name was more than 32 characters long. error_table_$inconsistent the control_mask was in error, specifying both CHECK_STAR_PROCESS and CHECK_STAR_IGNORE the same test. error_table_$invalid_ascii the entryname contains a nonASCII character and CHECK_STAR_IGNORE_NONASCII was not specified. error_table_$nostars stars or question marks were found and CHECK_STAR_REJECT_WILD was specified in the control_mask. Note that star_type will correctly reflect the starname type for this case. error_table_$null_name_component the string contains null components and the control_mask did not permit them. Notes: see the description of the hcs_$star_ entrypoint in hcs_.info to find how to list the directory entries that match a given starname. See match_star_name_.info to find how to match a starname with an entryname. See starname.gi.info for the rules governing the formation and interpretation of starnames. See entryname.gi.info for the rules governing the formation of entrynames. :Entry: entry: 07/30/86 check_star_name_$entry Function: this entrypoint accepts the entryname to be analyzed as input. Syntax: declare check_star_name_$entry entry (char(*), fixed bin(35)); call check_star_name_$entry (entryname, code); Arguments: entryname (Input) is the entryname to be validated. Trailing spaces in the entryname character string are ignored. code (Output) is one of the nonstandard status codes listed below. List of status codes: 0 the entryname is valid and is not a starname (does not contain asterisks or question marks). 1 the entryname is valid and is a starname (does contain asterisks or question marks). 2 the entryname is valid and is a starname that matches every entryname. error_table_$badstar the entryname is invalid. It violates the rules for forming starnames, or it violates the rules for constructing entrynames. Notes: This entrypoint is obsolete. Use the check_star_name_ entrypoint for new applications. The new entrypoint returns a variety of different standard error codes explaining a rejection whereas this entrypoint can only return a single standard error code value for compatability. See the description of the hcs_$star_ entrypoint in hcs_.info to find how to list the directory entries that match a given starname. See match_star_name_.info to find how to match a starname with an entryname. See starname.gi.info for the rules governing the formation and interpretation of starnames. See entryname.gi.info for the rules governing the formation of entrynames. :Entry: path: 07/30/86 check_star_name_$path Function: this entrypoint accepts a pathname as its input and analyzes the final entryname in that pathname. Syntax: declare check_star_name_$path entry (char(*), fixed bin(35)); call check_star_name_$path (path, code); Arguments: path (Input) is the pathname whose final entryname is to be validated. Trailing spaces in the pathname character string are ignored. code (Output) is one of the nonstandard status codes listed below. List of status codes: 0 the entryname is valid and is not a starname (does not contain asterisks or question marks). 1 the entryname is valid and is a starname (does contain asterisks or question marks). 2 the entryname is valid and is a starname that matches every entryname. error_table_$badstar the entryname is invalid. It violates the rules for forming starnames, or it violates the rules for forming pathnames. Notes: This entrypoint is obsolete. Use the check_star_name_ entrypoint for new applications. The new entrypoint returns a variety of different standard error codes explaining a rejection whereas this entrypoint can only return a single standard error code value for compatibility. See the description of the hcs_$star_ entrypoint in hcs_.info to find how to list the directory entries that match a given starname. See match_star_name_.info to find how to match a starname with an entryname. See starname.gi.info for the rules governing the formation and interpretation of starnames. See pathname.gi.info for the rules governing the formation of pathnames. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved