02/08/84 help_ The help_ subroutine performs the basic work of the help command in printing selected information from one or more info segments. The caller may select what information is to be printed, what search list is to be used to find the info segments, and what suffix the info segments must have. Thus, the help_ provides an interface for implementing a subsystem help command. Several entry points in the help_ subroutine are described below. help_$init must be called before calling the help_ or help_$check_info_segs entry points. The help_ or help_$check_info_segs entry points may then be called one or more times. When the caller no longer needs the help_args structure, help_$term must be called to release the temporary segment containing the help_args structure. Entry points in help_: (List is generated by the help command) :Entry: help: 02/08/84 help_ Function: searches for info segments, selects information blocks (infos), and prints the information. The caller provides information in the help_args structure (obtained in the call to help_$init) to select the infos to be printed and the type of information to be printed. The help_ subroutine may ask the user questions about how much information should be printed. These questions and the responses the user may give are in the description of the help command. Questions are asked using the command_query_ subroutine. Syntax: declare help_ entry (char(*), ptr, char(*), fixed bin, fixed bin(35)); call help_ (caller, Phelp_args, suffix, progress, code); Arguments: caller is the name of the calling program, on whose behalf the temporary segment containing the help_args structure is obtained. (Input) Phelp_args is a pointer to the help_args structure, declared in help_args_.incl.pl1. (Output) suffix is the suffix which must appear in the entrynames of info segments to be processed by this invocation of help_. This suffix is also assumed when omitted from the (final or only) entryname of values given for help_args.path.value in the help_args structure. If a null string is given, then no suffix is required in info segment entrynames, and none is assumed in values of help_args.path.value. (Input) progress is a special status code that indicates which stage of processing help_ was performing when an error occurs. (Output) See "Notes on status codes" below. code is a standard status code. (Output) See "Notes on status codes" below. Notes on status codes: Errors can occur during different stages of processing. The following is a list of progress codes: 1 the Phelp_args argument points to an unimplemented version of the help_args structure. code = error_table_$unimplemented_version. 2 help_args.Npaths is not positive, indicating that no info_names were given. help_ is unable to select info segments for printing. code = error_table_$noarg. 3 an error is encountered while evaluating one or more of the help_args.path.value values. help_args.path.code indicates the particular error encountered in each value. Code can have any value returned by expand_pathname_$add_suffix or check_star_name_$entry, or it may be returned as error_table_$inconsistent. 4 no fatal errors are encountered. Some infos matching help_args.path were found. Any nonfatal errors encountered while finding the infos are diagnosed to the user, unless help_args_.Sctl.inhibit_errors is on. A list of infos to be compared with the -section and -search criteria is created. Code is returned as error_table_$nomatch if no matching info segments are found. 5 infos matching the -section and -search criteria are printed. Code is returned as error_table_$nomatch only when no infos match the -section and -search criteria. help_ does not report such an error to the user. The caller is responsible for doing this. :Entry: check_info_segs: 02/08/84 help_$check_info_segs Function: searches for info segments modified since a given date. It returns a sorted list of info segments matching the selection criteria. The list is sorted by directory name, and within a directory by entryname. In addition, the help_$check_info_segs entry point flags entrynames found in more than one directory. All but the first such duplicate segment are marked with a cross reference flag and are sorted after all unique info segments. The caller provides the selection criteria in the help_args structure, obtained by calling help_$init. In particular, help_args.min_date_time specifies the info segment modification threshold. Syntax: declare help_$check_info_segs entry (char(*), ptr, char(*), fixed bin, fixed bin(35), ptr); call help_$check_info_segs (caller, Phelp_args, suffix, progress, code, PPDinfo_seg); Arguments: caller is the name of the calling program, on whose behalf the temporary segment containing the help_args structure is obtained. (Input) Phelps_args is a pointer to the help_args structure, declared in help_args_.incl.pl1. (Output) suffix is the suffix which must appear in the entrynames of info segments to be processed by this invocation of help_. This suffix is also assumed when omitted from the (final or only) entryname of values given for help_args.path.value in the help_args structure. If a null string is given, then no suffix is required in info segment entrynames, and none is assumed in values of help_args.path.value. (Input) progress is a special status code that indicates which stage of processing help_ was performing when an error occurs. (Output) See the help_ entry point. code is a standard status code. (Output) See the help_ entry point. PPDinfo_seg points to the PDinfo_seg structure which contains a sorted list of pointers to descriptors for the selected info segments. It is declared in help_cis_args_.incl.pl1. (Output) :Entry: init: 02/08/84 help_$init Function: obtains a pointer to the help_args structure which is used to pass information from the caller to the help_ and help_$check_info_segs entry points. The structure is a based structure containing several arrays with adjustable extents. The help_$init entry point creates the structure in a temporary segment so that these arrays can be grown incrementally by the caller as information is added to the structure. Syntax: declare help_$init entry (char(*), char(*), char(*), fixed bin, ptr, fixed bin(35)); call help_$init (caller, search_list_name, search_list_ref_dir, required_version, Phelp_args, code); Arguments: caller is the name of the calling program, on whose behalf the temporary segment containing the help_args structure is obtained. (Input) search_list_name is the name of the search list to be used in searching for info segments. A null string may be given if no search list is to be used. (Input) search_list_ref_dir is the pathname of the directory to be used when expanding the referencing_dir search rule in the search list. If a null string is given, the referencing_dir search rule is omitted from the search list. (Input) required_version is the version number of the help_args structure which the caller is prepared to accept, currently Vhelp_args_1. (Input) Phelp_args is a pointer to the help_args structure, declared in help_args_.incl.pl1. (Output) code is a standard status code reporting any failure in expanding the search list. (Output) :Entry: term: 02/08/84 help_$term Function: releases the temporary segment in which the help_args structure (and the PDinfo_seg and Dinfo_seg structures of help_$check_info_segs) are created. This entry point should be called before calling help_$init again. Syntax: declare help_$term entry (char(*), ptr, fixed bin(35)); call help_$term (caller, Phelp_args, code); Arguments: caller is the name of the calling program, on whose behalf the temporary segment containing the help_args structure is obtained. (Input) Phelp_args is a pointer to the help_args structure, declared in help_args_.incl.pl1. (Output) code is a standard status code. (Output) ----------------------------------------------------------- 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