1 :Info: help_:  2020-10-23  help_
  2 
  3 The help_ subroutine performs the basic work of the help command in
  4 printing selected information from one or more info segments.  The
  5 caller may select what information is to be printed, what search list
  6 is to be used to find the info segments, and what suffix the info
  7 segments must have.  Thus, the help_ provides an interface for
  8 implementing a subsystem help command.
  9 
 10 Several entry points in the help_ subroutine are described below.
 11 help_$init must be called before calling the help_ or
 12 help_$check_info_segs entry points.  The help_ or help_$check_info_segs
 13 entry points may then be called one or more times.  When the caller no
 14 longer needs the help_args structure, help_$term must be called to
 15 release the temporary segment containing the help_args structure.
 16 
 17 
 18 Entry points in help_:
 19    (List is generated by the help command)
 20 
 21 
 22 :Entry: init:  2020-10-23  help_$init
 23 
 24 
 25 Function: obtains a pointer to the help_args structure which is used
 26 to pass information from the caller to the help_ and
 27 help_$check_info_segs entry points.  The structure is a based
 28 structure containing several arrays with adjustable extents.  The
 29 help_$init entry point creates the structure in a temporary segment so
 30 that these arrays can be grown incrementally by the caller as
 31 information is added to the structure.
 32 
 33 
 34 Syntax:
 35 declare help_$init entry (char(*), char(*), char(*), fixed bin, ptr,
 36      fixed bin(35));
 37 call help_$init (caller, search_list_name, search_list_ref_dir,
 38      required_version, Phelp_args, code);
 39 
 40 
 41 Arguments:
 42 caller
 43    is the name of the calling program, on whose behalf the temporary
 44    segment containing the help_args structure is obtained.  (Input)
 45 search_list_name
 46    is the name of the search list to be used in searching for info
 47    segments.  A null string may be given if no search list is to be
 48    used.  (Input)
 49 search_list_ref_dir
 50    is the pathname of the directory to be used when expanding the
 51    referencing_dir search rule in the search list.  If a null string is
 52    given, the referencing_dir search rule is omitted from the search
 53    list.  (Input)
 54 
 55 
 56 required_version
 57    is the version number of the help_args structure which the caller is
 58    prepared to accept.  The recommended version is Vhelp_args_3.
 59    However, earlier values are supported: 1 and 2.  (Input)
 60 Phelp_args
 61    is a pointer to the help_args structure, declared in
 62    help_args_.incl.pl1.  (Output)
 63 code
 64    is a standard status code reporting any failure in expanding the
 65    search list.  (Output)
 66 
 67 
 68 :Entry: help_:  1984-02-08  help_
 69 
 70 Function: searches for info segments, selects information blocks
 71 (infos), and prints the information.  The caller provides information
 72 in the help_args structure (obtained in the call to help_$init) to
 73 select the infos to be printed and the type of information to be
 74 printed.
 75 
 76 The help_ subroutine may ask the user questions about how much
 77 information should be printed.  These questions and the responses the
 78 user may give are in the description of the help command.  Questions
 79 are asked using the command_query_ subroutine.
 80 
 81 
 82 Syntax:
 83 declare help_ entry (char(*), ptr, char(*), fixed bin, fixed bin(35));
 84 call help_ (caller, Phelp_args, suffix, progress, code);
 85 
 86 
 87 Arguments:
 88 caller
 89    is the name of the calling program, on whose behalf the temporary
 90    segment containing the help_args structure is obtained.  (Input)
 91 Phelp_args
 92    is a pointer to the help_args structure, declared in
 93    help_args_.incl.pl1.  (Output)
 94 suffix
 95    is the suffix which must appear in the entrynames of info segments
 96    to be processed by this invocation of help_.  This suffix is also
 97    assumed when omitted from the (final or only) entryname of values
 98    given for help_args.path.value in the help_args structure.  If a
 99    null string is given, then no suffix is required in info segment
100    entrynames, and none is assumed in values of help_args.path.value.
101    (Input)
102 
103 
104 progress
105    is a special status code that indicates which stage of processing
106    help_ was performing when an error occurs.  (Output) See "Notes on
107    status codes" below.
108 code
109    is a standard status code.  (Output) See "Notes on status codes"
110    below.
111 
112 
113 Notes on status codes:  Errors can occur during different stages of
114 processing.  The following is a list of progress codes:
115 
116 1  the Phelp_args argument points to an unimplemented version of the
117    help_args structure.  code = error_table_$unimplemented_version.
118 
119 2  help_args.Npaths is not positive, indicating that no info_names
120    were given.  help_ is unable to select info segments for printing.
121    code = error_table_$noarg.
122 
123 3  an error is encountered while evaluating one or more of the
124    help_args.path.value values.  help_args.path.code indicates the
125    particular error encountered in each value.  Code can have any value
126    returned by expand_pathname_$add_suffix or check_star_name_$entry,
127    or it may be returned as error_table_$inconsistent.
128 
129 
130 4  no fatal errors are encountered.  Some infos matching
131    help_args.path were found.  Any nonfatal errors encountered while
132    finding the infos are diagnosed to the user, unless
133    help_args_.Sctl.inhibit_errors is on.  A list of infos to be
134    compared with the -section and -search criteria is created.
135    Code is returned as error_table_$nomatch if no matching info
136    segments are found.
137 
138 5  infos matching the -section and -search criteria are printed.
139    Code is returned as error_table_$nomatch only when no infos match
140    the -section and -search criteria.  help_ does not report such an
141    error to the user.  The caller is responsible for doing this.
142 
143 
144 :Entry: check_info_segs:  1984-02-08  help_$check_info_segs
145 
146 
147 Function: searches for info segments modified since a given date.
148 It returns a sorted list of info segments matching the selection
149 criteria.  The list is sorted by directory name, and within a
150 directory by entryname.  In addition, the help_$check_info_segs entry
151 point flags entrynames found in more than one directory.  All but the
152 first such duplicate segment are marked with a cross reference flag
153 and are sorted after all unique info segments.  The caller provides
154 the selection criteria in the help_args structure, obtained by calling
155 help_$init.  In particular, help_args.min_date_time specifies the info
156 segment modification threshold.
157 
158 
159 Syntax:
160 declare help_$check_info_segs entry (char(*), ptr, char(*), fixed bin,
161      fixed bin(35), ptr);
162 call help_$check_info_segs (caller, Phelp_args, suffix, progress, code,
163      PPDinfo_seg);
164 
165 
166 Arguments:
167 caller
168    is the name of the calling program, on whose behalf the temporary
169    segment containing the help_args structure is obtained.  (Input)
170 Phelps_args
171    is a pointer to the help_args structure, declared in
172    help_args_.incl.pl1.  (Output)
173 suffix
174    is the suffix which must appear in the entrynames of info segments
175    to be processed by this invocation of help_.  This suffix is also
176    assumed when omitted from the (final or only) entryname of values
177    given for help_args.path.value in the help_args structure.  If a
178    null string is given, then no suffix is required in info segment
179    entrynames, and none is assumed in values of help_args.path.value.
180    (Input)
181 
182 
183 progress
184    is a special status code that indicates which stage of processing
185    help_ was performing when an error occurs.  (Output) See the help_
186    entry point.
187 code
188    is a standard status code.  (Output) See the help_ entry point.
189 PPDinfo_seg
190    points to the PDinfo_seg structure which contains a sorted list of
191    pointers to descriptors for the selected info segments.  It is
192    declared in help_cis_args_.incl.pl1.  (Output)
193 
194 
195 :Entry:  term:  1984-02-08  help_$term
196 
197 
198 Function: releases the temporary segment in which the help_args
199 structure (and the PDinfo_seg and Dinfo_seg structures of
200 help_$check_info_segs) are created.  This entry point should be called
201 before calling help_$init again.
202 
203 
204 Syntax:
205 declare help_$term entry (char(*), ptr, fixed bin(35));
206 call help_$term (caller, Phelp_args, code);
207 
208 
209 Arguments:
210 caller
211    is the name of the calling program, on whose behalf the temporary
212    segment containing the help_args structure is obtained.  (Input)
213 Phelp_args
214    is a pointer to the help_args structure, declared in
215    help_args_.incl.pl1.  (Output)
216 code
217    is a standard status code.  (Output)
218 
219 
220 :hcom:
221 
222 
223 
224 
225 /****^  HISTORY COMMENTS:
226   1) change(2020-10-23,GDixon), approve(2021-02-23,MCR10089),
227      audit(2021-03-31,Swenson), install(2021-03-31,MR12.6g-0053):
228       A) Change format of header dates, but not their value or other header line
229          content.
230       B) Change order of appearance of help_ entry points to reflect their correct
231          order of use.
232       C) Change description of the help_$init required_version
233          argument to list the latest version recommends, as well as
234          earlier supported versions.
235                                                    END HISTORY COMMENTS */
236 
237 
238