1 :Info: info_seg_:  2020-11-04  info_seg_
  2 
  3 
  4 The info_seg_ subroutine...
  5  - parses info segments into their components (lines, paragraphs,
  6    sections, blocks); and
  7  - verifies formatting and section titles of each info seg component.
  8    Any errors are diagnosed by error switches in the parse output
  9    structures.
 10 
 11 
 12 Notes on usage sequences:
 13 A) The verify_info command uses info_seg_ to parse info segments to be
 14    validated, making the following sequence of calls:
 15      - call info_seg_$initialize(...);
 16           Called one per verify_info command.
 17      - call info_seg_$append_iFiles(...);
 18           Called once for each INFO_PATH starname argument.
 19      - call info_seg_$parse_iFile(...);
 20           Called for each info seg (iFile structure) found by
 21           $append_iFiles.
 22      - call info_seg_$terminate(...);
 23           Called once after all files have been verified.
 24 
 25 
 26 Entry points in info_seg_:
 27    (List is generated by the help command)
 28 
 29 
 30 :Entry: initialize:  2020-11-04  info_seg_$initialize
 31 
 32 Function: creates an ssu_ standalone invocation to simplify argument
 33 processing and storage management for any command using info_seg_.
 34 
 35 Completes initialization of the info_seg_data structure provided by the
 36 caller.
 37 
 38 
 39 Syntax:
 40    declare info_seg_$initialize entry (ptr, char(*), char(*), ptr,
 41      entry variable, fixed bin(35);
 42    call info_seg_$initialize (info_seg_dataP, caller_name,
 43      caller_version, arg_list_ptr, ssu_abort_routine, code);
 44 
 45 
 46 Arguments:
 47 info_seg_dataP
 48    points to the info_seg_data structure (see info_seg_dcls_.incl.pl1)
 49    which caller provides as input.
 50      A) Caller sets info_seg_data.version to indicate which structure
 51         version is being passed.
 52      B) Caller sets info_seg_data.ptrs, info_seg_data.files = null()
 53         to prepare for a later call to info_seg_$terminate.
 54      C) Caller optionally sets info_seg_data.sciP to point to an
 55         existing ssu_ invocation.  If this pointer is null(), then
 56         initialization also creates its own ssu_ standalone
 57         invocation, using the other parameters.
 58    See the "Notes on cleanup" section for more information.
 59 
 60 
 61    If info_seg_data.sciP is null, the following arguments are passed
 62    directly to ssu_$standalone_invocation.  See the MPM Subroutines
 63    description of that entry point for more details.
 64 
 65 
 66 caller_name
 67    gives name of calling command.  Can be accessed by
 68    ssu_$get_subsystem_name.
 69 caller_version
 70    gives caller's version number.  Can be accessed by
 71    ssu_$get_subsystem_version.
 72 arg_list_ptr
 73    points to calling command's input argument list.  Use ssu_$arg_ptr
 74    to access arguments.  The caller may used ssu_ calls to process its
 75    input arguments.  The info_seg_ subroutine does not access this
 76    arg_list_ptr.    To simply argument handling, see:
 77       ssu_standalone_command_.incl.pl1
 78 
 79 
 80 ssu_abort_routine
 81    subroutine to be called if an info_seg_$XXX routine encounters a
 82    fatal error and needs to abort execution of the calling command.
 83    This subroutine should go to a label that exits the command (call's
 84    its cleanup routine, then returns).
 85 code
 86    is an ssu_ status code.  It is non-zero when a fatal error occurs.
 87    Cases include:
 88     - info_seg_data.version has a value not supported by info_seg_; or
 89     - ssu_$standalone_invocation creation failed.
 90    ssu_$print_message (and other ssu_ routines) may not be called to
 91    report such errors.
 92 
 93 
 94 Notes on cleanup:
 95 
 96 When initialization completes, info_seg_data.ptrs and
 97 info_seg_data.relatives.files point to data items used in subsequent
 98 calls to info_seg_ subroutines.  The caller must create a cleanup
 99 on-unit that calls info_seg_$terminate to terminate info segments, and
100 release storage for structures describing those info segments.
101 
102 
103 :Entry: append_iFiles:  2020-03-01  info_seg_$append_iFiles
104 
105 Function: creates an iFile structure for each info segment matching an
106 input pathname.  Each new iFile structure is attached to the
107 info_seg_data.files threaded list, in alphabetic order by first
108 entryname of the info segment.  For details, see the "Notes on iFile
109 structures" section of this info segment.
110 
111 
112 Syntax:
113    declare info_seg_$append_iFiles entry (ptr, char(*));
114    call info_seg_$append_iFiles (info_seg_dataP, path);
115 
116 
117 Arguments:
118 info_seg_dataP
119    points to the info_seg_data structure.  Refer to
120    info_seg_dcls_.incl.pl1.
121 path
122    a relative or absolute pathname identifying one or more info
123    segments.  A suffix of .info is assumed if not present.  The star
124    convention is supported.
125 
126 
127 Notes on the structure:
128 Each iFile structure created by info_seg_ is added to the
129 info_seg_data.files threaded list.  Use the following code to set
130 iFileP to point to structures on this list:
131 
132      do iFileP = info_seg_data.relatives.files.firstP
133           repeat iFile.sib.nextP   while (iFileP ^= null());
134              ... <code to operate on each iFile> ...
135           end;
136 
137 The code for each iFile would include a call to parse the info
138 segment, followed by code to process the structure hierarchy returned
139 by parsing.  The iFile and info_seg_data structures are declared in
140 info_seg_dcls_.incl.pl1.
141 
142 
143 :Entry: parse_iFile:  2020-03-01  info_seg_$parse_iFile
144 
145 Function: initiates the info segment described by iFile, and parses
146 that segment into one or more components:
147 
148    - info block   Portion of an info segment completely describing:
149                   a command or active function; a subroutine or one of
150                   its entry points; a subsystem request or active
151                   request; or some other topic of general information.
152    - section      A titled group of paragraphs in an info block.
153    - paragraph    A group of lines from an info block which are
154                   displayed as a unit.
155    - line         A set of characters short enough to display on a
156                   single row of most display terminals.
157 
158 
159 Syntax:
160    declare info_seg_$parse_iFile entry (ptr, ptr);
161    call info_seg_$parse_iFile (info_seg_dataP, iFileP);
162 
163 
164 Arguments:
165 info_seg_dataP
166    points to the info_seg_data structure (see info_seg_dcls_.incl.pl1).
167 iFileP
168    points to an iFile input structure for the file to be parsed.
169 
170 
171 Notes:
172 Before calling info_seg_$parse_iFile, the iFile structure contains
173 only the location of an info segment, and threads to other iFile
174 structures.
175 
176 
177 After parsing, the following information has been added to the iFile
178 structure...
179  - A pointer to, and length of, the characters in the info segment.
180  - An array of all names on the info segment.
181  - A list of iLine structures, each describing a line of the info
182    segment.
183  - A list of iBlok structures, each describing a block of the info
184    segment.
185  - Integers classifying the block organization within the info segment.
186 
187 
188 In addition, each iBlok structure describes...
189  - A pointer to, and length of, the characters in the block.
190  - An array of names in the block divider (if the block began with a
191    divider).
192  - Block heading line information (date and header string).
193  - A list of iSect structures, each item describing sections within
194    the block.
195  - A list of iPgh structures, each item describing paragraphs within
196    the block.
197  - A list of iLine structures, each item describing lines within the
198    block.
199 
200 
201 :Entry: reinitialize:  2020-03-09  info_seg_$reinitialize
202 
203 Function: terminates info segment files that were parsed, and empties
204 temporary storage used for info segment data structures.
205 
206 
207 Syntax:
208    declare info_seg_$reinitialize entry (ptr);
209    call info_seg_$reinitialize (info_seg_dataP);
210 
211 
212 Arguments:
213 info_seg_dataP
214    points to the info_seg_data structure (see info_seg_dcls_.incl.pl1).
215 
216 
217 Notes on cleanup:
218 When initialization completes, info_seg_data.ptrs point to data items
219 used in subsequent calls to info_seg_ subroutines.  The caller must
220 create a cleanup on-unit that calls a routine to release storage for
221 these data items:
222    - Calls info_seg_$reinitialize to reinitialize info segments, and
223      release storage for structures describing those info segments.
224    - Calls ssu_$destroy_invocation to release the ssu_ standalone
225      invocation identified by the info_seg_data.sciP pointer.
226 
227 In addition, the caller must call the cleanup routine described
228 above before returning to its caller.
229 
230 
231 :Entry: terminate:  2020-03-09  info_seg_$terminate
232 
233 Function: terminates info segment files that were parsed, and releases
234 temporary storage used for info segment data structures.  If
235 info_seg_$initiate created its own ssu_ standalone invocation, that
236 invocation is destroyed.
237 
238 
239 Syntax:
240    declare info_seg_$terminate entry (ptr);
241    call info_seg_$terminate (info_seg_dataP);
242 
243 
244 Arguments:
245 info_seg_dataP
246    points to the info_seg_data structure (see info_seg_dcls_.incl.pl1).
247 
248 
249 Notes on cleanup:
250 When initialization completes, info_seg_data.ptrs point to data items
251 used in subsequent calls to info_seg_ subroutines.  The caller must
252 create a cleanup on-unit that calls a routine to release storage for
253 these data items:
254    - Calls info_seg_$terminate to terminate info segments, and
255      release storage for structures describing those info segments.
256    - Calls ssu_$destroy_invocation to release the ssu_ standalone
257      invocation identified by the info_seg_data.sciP pointer if the
258      caller created that ssu_ standalone invocation.
259 
260 In addition, the caller must call the cleanup routine described
261 above before returning to its caller.
262 
263 
264 :hcom:
265 
266 /****^  HISTORY COMMENTS:
267   1) change(2020-03-01,GDixon), approve(2021-02-23,MCR10089),
268      audit(2021-03-31,Swenson), install(2021-03-31,MR12.6g-0053):
269      Information segment created as subroutine was developed.
270   2) change(2020-11-04,GDixon), approve(2021-02-23,MCR10089),
271      audit(2021-03-31,Swenson), install(2021-03-31,MR12.6g-0053):
272      In info_seg_$initialize, change description of info_seg_dataP
273      argument to correctly describing setup of this structure by callers.
274   3) change(2020-11-25,GDixon), approve(2021-02-23,MCR10089),
275      audit(2021-03-31,Swenson), install(2021-03-31,MR12.6g-0053):
276      Change spelling of "entrypoint" to "entry point".
277                                                    END HISTORY COMMENTS */