1 /* START OF: help_args_.incl.pl1 * * * * * * * * * * * * * * * * * * * */ 2 3 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 4 /* */ 5 /* Name: help_args_.incl.pl1 */ 6 /* */ 7 /* This include file declares the structure used by the help command and other subsystems to pass */ 8 /* info segment selection and printing control information to the help_ subroutine. */ 9 /* */ 10 /* This based structure is NEVER allocated. help_$init returns a pointer to this structure, */ 11 /* which it stores in a temporary segment and partially initializes. */ 12 /* */ 13 /* The structure contains 5 arrays with refer extents, allowing complete freedom in the numbers */ 14 /* of selection values given. The caller must fill in the adjustable arrays at the top of the */ 15 /* structure first, growing the arrays as each new element is added. After each array is filled, */ 16 /* the caller begins filling in the next array. */ 17 /* */ 18 /* On return from help_$init, all of the arrays have 0 extents, except: */ 19 /* */ 20 /* - help_args.search_dirs array is initialized with directories from the user's search paths */ 21 /* named: */ 22 /* info_segments, info_segs, info */ 23 /* */ 24 /* These search paths are defined by the (add delete print set)_search_paths commands. */ 25 /* The caller of help_$init may may change help_args.search_dirs to some other directories; */ 26 /* or set help_args.Nsearch_dirs = 0 to eliminate searching for info segments. */ 27 /* */ 28 /* A legend describing the variable naming convention follows. */ 29 /* */ 30 /* STARTING LETTER STANDS FOR */ 31 /* P pointer to */ 32 /* L length of */ 33 /* D descriptor of */ 34 /* S switch */ 35 /* V version */ 36 /* */ 37 /* Status */ 38 /* */ 39 /* 0) Created: October, 1978 by Gary Dixon */ 40 /* 1) Modified: June 4, 1983 by Gary Dixon - add Sctl.inhibit_errors flag. */ 41 /* 2) Modified: April, 1985 by L.Adams - use Vhelp_args_2. */ 42 /* */ 43 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 44 45 /****^ HISTORY COMMENTS: 46 1) change(1986-03-07,LJAdams), approve(1986-03-07,MCR7327), 47 audit(1986-03-10,Lippard), install(1986-04-24,MR12.0-1048): 48 Declares structure used by the help command and other subsystems to pass 49 info segment selection and printing control information the help_ 50 subroutine. 51 2) change(1987-01-26,LJAdams), approve(1987-09-03,MCR7766), 52 audit(1988-05-03,GDixon), install(1988-09-13,MR12.2-1109): 53 Added lep to Sctl. 54 Added Sctl.cs to indicate if search or section requests are to be case 55 sensitive or not. 56 Changed version to Vhelp_args_3. 57 3) change(1988-02-12,LJAdams), approve(1988-03-07,MCR7857), 58 audit(1988-05-03,GDixon), install(1988-09-13,MR12.2-1109): 59 Added help_data_ptr to point to a second help_args structure that will be 60 used for list_requests. 61 4) change(2020-08-27,GDixon), approve(2021-02-23,MCR10089), 62 audit(2021-03-31,Swenson), install(2021-03-31,MR12.6g-0053): 63 A) PL/I content of the declare statements below were NOT changed. 64 All comments for help_args elements were updated to clarify how a new help_ 65 implementation uses each element. The new help_ always creates its own ssu_ 66 subsystem which implements the user's responses to "More help?" prompts as 67 ssu_ requests. 68 B) Improve comments for help_args.Sctl elements, and .min_Lpgh and .max_Lpgh 69 elements. 70 END HISTORY COMMENTS */ 71 72 73 dcl 1 help_args aligned based (Phelp_args), /* help's input arguments. */ 74 2 version fixed bin, /* = 3, currently. Use Vhelp_args_3. */ 75 /* (set by help_$init, CHECKED BY CALLER OF help_) */ 76 77 2 Sctl, /* control argument switches: (SET BY CALLER OF help_) */ 78 79 /* help.pl1 control arg for each switch */ 80 /* -------- */ 81 (3 he_only, /* -header print only a header, nothing else. */ 82 3 he_pn, /* -brief_header */ 83 /* if header printed, includes info pathname. */ 84 85 /* (help always sets next two switches to "1"b) */ 86 3 he_info_name, /* if header printed, includes any info_name. */ 87 3 he_counts, /* if header printed, includes line counts. */ 88 /* If none of the 3 switches above are set, */ 89 /* then only info header is shown in heading. */ 90 91 3 title, /* -titles print section titles, then prompt user */ 92 3 scn, /* -section select 1st section with title match STRs */ 93 3 srh, /* -search select 1st paragraph matching STRs */ 94 3 bf, /* -brief print only syntax, arg/control_arg names */ 95 3 ca, /* -control_arg */ 96 /* print arg/control_arg desc. matching STRs */ 97 3 ep, /* -entry_point */ 98 /* for subr_, select subr_$subr_ entrypoint */ 99 /* to display first, rather than introduction */ 100 3 all, /* -all display info blocks with no prompts. */ 101 3 lep, /* -lep for subr_, list entrypoints rather than */ 102 /* displaying subroutine introduction block. */ 103 3 cs, /* -case_sensitive */ 104 /* -section/-search/-control_arg STRs honor */ 105 /* letter case when searching. By default, */ 106 /* such searches are case-insensitive. */ 107 3 inhibit_errors, /* (help cmd does not set this switch) */ 108 /* inhibits error diagnostics when desired */ 109 /* info seg/block is not found. Useful for */ 110 /* subsystems like ted that want to diagnose */ 111 /* their own errors. */ 112 3 no_video) /* -no_video */ 113 /* user prompt/response sequences are not */ 114 /* overwritten when user_i/o via window_io_. */ 115 bit(1) unal, 116 3 mbz1 bit(21) unal, 117 118 2 Nsearch_dirs fixed bin, /* number of info_segment (or other) search directories. */ 119 /* (set by help_$init for info_seg search paths; */ 120 /* CALLER OF help_ can set to 0 to display use */ 121 /* of search paths, or replace with different */ 122 /* set of search paths) */ 123 2 Npaths fixed bin, /* number of info segment names. (SET BY CALLER OF help_) */ 124 2 Ncas fixed bin, /* number of -control_arg STRs (SET BY CALLER OF help_) */ 125 2 Nscns fixed bin, /* number of -section STRs (SET BY CALLER OF help_) */ 126 2 Nsrhs fixed bin, /* number of -search STRs (SET BY CALLER OF help_) */ 127 2 min_Lpgh fixed bin, /* used in earlier versions, help_ now ignores min_Lpgh */ 128 /* (set by help_$init, CALLER CAN CHANGE) */ 129 2 max_Lpgh fixed bin, /* maximum lines in group of paragraphs displayed as a */ 130 /* unit. Defaults to terminal page length. */ 131 /* (set by help_$init, CALLER CAN CHANGE) */ 132 2 Lspace_between_infos fixed bin, /* spaces inserted between infos when several are printed */ 133 /* by one invocation. */ 134 /* (set by help_$init, CALLER CAN CHANGE) */ 135 2 min_date_time fixed bin(71), /* do not process infos modified before this date. */ 136 /* (SET BY CALLER OF help_; help cmd never uses) */ 137 138 2 sci_ptr ptr, /* (set by help_$init to null; ignored by help_) */ 139 2 help_data_ptr ptr, /* (set by help_$init to null; ignored by help_) */ 140 2 pad2 (6) fixed bin, /* reserved for future expansion. */ 141 142 /* End of fixed-length part of the structure. */ 143 144 2 search_dirs (0 refer (help_args.Nsearch_dirs)) 145 char (168) unal, /* directories help_ will look in to find info */ 146 /* segments when relative paths (without < or >)*/ 147 /* are given. When help_$init is called, the */ 148 /* current search rules (from a search list of */ 149 /* caller's choice) will be given here. Caller */ 150 /* may modify this list if desired before */ 151 /* calling help_. */ 152 2 path (0 refer (help_args.Npaths)), /* names of sought info segments. */ 153 3 value char(425) varying, /* These are the args themselves, without */ 154 /* processing by expand_pathname_, etc. */ 155 /* Their length is length(path) + length("$") */ 156 /* + length(entry_point_name). */ 157 /* Note that entry_point_names can be 256 chars.*/ 158 /* (SET BY CALLER OF help_) */ 159 3 info_name char(32) unal, /* name of logical info to be printed. */ 160 /* (SET BY CALLER OF help_) */ 161 /* "" = help_ should set this to entry part */ 162 /* of path.value, minus the suffix. */ 163 /* other = logical info name not a name on the */ 164 /* physical info segment. */ 165 3 dir (1) char(168) unal, /* dir part of a pathname (set by help_). */ 166 3 ent char(32) unal, /* ent part of name (set by help_). */ 167 3 ep char(32) varying, /* entry point part of name. (set by help_) */ 168 3 code fixed bin(35), /* error code while processing this path. */ 169 /* (set by help_) */ 170 3 S, /* switches indicating path type. */ 171 (4 pn_ctl_arg, /* -pn ctl given before this path. */ 172 /* (SET BY CALLER OF help_) */ 173 4 info_name_not_starname, /* caller-supplied path.info_name is not a */ 174 /* star name, even if it has * or ? chars. */ 175 /* (SET BY CALLER OF help_) */ 176 4 less_greater, /* A < or > appears in path.value. */ 177 /* (set by help_) */ 178 4 starname_ent, /* on if ent is a starname. */ 179 /* (set by help_) */ 180 4 starname_info_name, /* on if info_name is a starname. */ 181 /* (set by help_) */ 182 4 separate_info_name) bit(1) unal, /* on if info_name given by caller. */ 183 /* (set by help_) */ 184 4 pad3 bit(30) unal, 185 2 ca (0 refer (help_args.Ncas)) /* the ctl_arg names, without leading - just as */ 186 char(32) varying, /* req'd by the -ca ctl_arg of help. */ 187 /* (SET BY CALLER OF help_) */ 188 2 scn (0 refer (help_args.Nscns)) /* substrings sought in section titles. */ 189 char(80) varying, /* (SET BY CALLER OF help_) */ 190 2 srh (0 refer (help_args.Nsrhs)) /* search strings. */ 191 char(80) varying, /* (SET BY CALLER OF help_) */ 192 Phelp_args ptr, 193 Vhelp_args_3 fixed bin int static options(constant) init(3); 194 195 dcl help_ entry (char(*), ptr, char(*), fixed bin, fixed bin(35)), 196 help_$init entry (char(*), char(*), char(*), fixed bin, ptr, fixed bin(35)), 197 help_$term entry (char(*), ptr, fixed bin(35)); 198 199 200 /* END OF: help_args_.incl.pl1 * * * * * * * * * * * * * * * * * * * */